chore: pre-CI cleanup + Task #8 Docker + CI

.gitattributes

@@ -0,0 +1,48 @@
+# Normalize line endings across all platforms.
+# Prevents CRLF/LF churn when the same repo is used from Windows + Linux/macOS + CI.
+* text=auto eol=lf
+
+# --- Source files: always LF ---
+*.py     text eol=lf
+*.pyi    text eol=lf
+*.ts     text eol=lf
+*.tsx    text eol=lf
+*.js     text eol=lf
+*.jsx    text eol=lf
+*.mjs    text eol=lf
+*.cjs    text eol=lf
+*.json   text eol=lf
+*.jsonc  text eol=lf
+*.yml    text eol=lf
+*.yaml   text eol=lf
+*.toml   text eol=lf
+*.md     text eol=lf
+*.html   text eol=lf
+*.css    text eol=lf
+*.svg    text eol=lf
+*.sh     text eol=lf
+Dockerfile text eol=lf
+.env.example text eol=lf
+.gitignore text eol=lf
+.gitattributes text eol=lf
+
+# --- Windows-only files stay CRLF ---
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# --- Binary: leave alone ---
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.webp binary
+*.pdf  binary
+*.ico  binary
+*.woff  binary
+*.woff2 binary
+*.ttf  binary
+*.otf  binary
+*.zip  binary
+*.tar  binary
+*.gz   binary

.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+# ============================================================================
+# CI pipeline
+#
+# On every push and every PR to main we:
+#   1. python-lint-and-test — ruff + pytest (95 tests, all no-network)
+#   2. ui-typecheck-and-build — tsc --noEmit + vite build
+#   3. docker-build — build both images so a broken Dockerfile fails the PR
+#
+# Jobs run in parallel except docker-build, which is gated on both lint jobs
+# passing (no point building images if the code doesn't lint).
+# ============================================================================
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  # Cancel in-flight runs when a new commit lands on the same branch/PR.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ---------- Python: ruff + pytest ------------------------------------------
+  python-lint-and-test:
+    name: Python — ruff + pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: requirements.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff pytest pytest-cov
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Test (pytest)
+        # Tests must not require network. The extractor is stubbed via
+        # dependency-injection in the eval + API test suites.
+        run: pytest -q --tb=short
+
+  # ---------- UI: typecheck + build ------------------------------------------
+  ui-typecheck-and-build:
+    name: UI — tsc + vite build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ui
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - name: Build
+        run: npm run build
+
+  # ---------- Docker: build both images (smoke) ------------------------------
+  docker-build:
+    name: Docker — build API + UI images
+    runs-on: ubuntu-latest
+    needs: [python-lint-and-test, ui-typecheck-and-build]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build API image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/api.Dockerfile
+          push: false
+          load: true
+          tags: sdx-api:ci
+          cache-from: type=gha,scope=api
+          cache-to: type=gha,mode=max,scope=api
+
+      - name: Build UI image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/ui.Dockerfile
+          push: false
+          load: true
+          tags: sdx-ui:ci
+          cache-from: type=gha,scope=ui
+          cache-to: type=gha,mode=max,scope=ui

.gitignore

@@ -70,6 +70,12 @@ evaluation/reports/*.json
 # --- Docker ---
 *.log
 
+# --- Frontend (ui/) ---
+ui/node_modules/
+ui/dist/
+ui/.vite/
+ui/*.local
+
 # --- Model cache ---
 .cache/
 models/

README.md

@@ -2,7 +2,7 @@
 
 > Multi-domain document extraction — turn invoices, receipts, and SEC filings into schema-validated JSON with confidence scoring, multi-model benchmarking, and quantified accuracy.
 
-[![CI](https://img.shields.io/badge/CI-pending-yellow)]()
+[![CI](https://github.com/adityapatel007-byte/structured-data-extractor/actions/workflows/ci.yml/badge.svg)](https://github.com/adityapatel007-byte/structured-data-extractor/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.11+-blue)]()
 [![OpenAI](https://img.shields.io/badge/LLM-GPT--5%20nano-green)]()
 [![License](https://img.shields.io/badge/license-MIT-lightgrey)]()

docker-compose.yml

@@ -0,0 +1,63 @@
+# ============================================================================
+# Structured Data Extraction — local Docker stack
+#
+#   docker compose up --build       # first run (or after Dockerfile changes)
+#   docker compose up               # subsequent runs
+#   docker compose logs -f api      # tail API logs
+#   docker compose down             # stop + remove containers
+#
+# The UI waits for the API healthcheck before it accepts traffic. Once both
+# are up, browse to http://localhost:5173 — the frontend's /api calls are
+# proxied by nginx into the api container over the compose network.
+# ============================================================================
+services:
+  api:
+    build:
+      context: .
+      dockerfile: docker/api.Dockerfile
+    image: sdx-api:latest
+    container_name: sdx-api
+    ports:
+      - "8000:8000"
+    env_file:
+      # Only OPENAI_API_KEY is strictly required. Everything else is
+      # optional and read via src/utils/config.py.
+      - .env
+    environment:
+      # Fallbacks in case .env is missing keys — the app still starts.
+      PYTHONPATH: /app
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+    volumes:
+      # Mount sample data read-only so the eval CLI can run in-container.
+      # Nothing else from the host filesystem leaks in.
+      - ./data/samples:/app/data/samples:ro
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8000/health"]
+      interval: 15s
+      timeout: 3s
+      start_period: 10s
+      retries: 3
+    restart: unless-stopped
+    networks:
+      - sdx-net
+
+  ui:
+    build:
+      context: .
+      dockerfile: docker/ui.Dockerfile
+    image: sdx-ui:latest
+    container_name: sdx-ui
+    ports:
+      - "5173:5173"
+    depends_on:
+      api:
+        # Only start once /health returns 200 — avoids the flash of proxy
+        # errors when the frontend loads before FastAPI is ready.
+        condition: service_healthy
+    restart: unless-stopped
+    networks:
+      - sdx-net
+
+networks:
+  sdx-net:
+    driver: bridge

docker/api.Dockerfile

@@ -0,0 +1,66 @@
+# ============================================================================
+# Structured Data Extraction — API image
+#
+# Multi-stage build: builder installs Python deps into a venv, runtime is a
+# slim image with only the venv + source code. Cuts final image size roughly
+# in half vs a single-stage build (no pip cache, no build toolchain).
+# ============================================================================
+
+# ---------- Stage 1: builder --------------------------------------------------
+FROM python:3.11-slim AS builder
+
+# System build tools — only present in the builder stage, not runtime.
+# Needed because pymupdf / Pillow may compile C extensions on some archs.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      build-essential \
+      gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create an isolated venv so the runtime stage can just copy /opt/venv.
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /build
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+# ---------- Stage 2: runtime --------------------------------------------------
+FROM python:3.11-slim AS runtime
+
+# poppler-utils supports pdf2image; libglib is a pymupdf runtime dep.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      poppler-utils \
+      libglib2.0-0 \
+      curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy the venv from the builder — no dev deps, no pip cache.
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+
+# Non-root user — hardens against container escapes. FastAPI needs no privs.
+RUN groupadd --system app && useradd --system --gid app --home /app app
+WORKDIR /app
+
+# Copy only what the API needs at runtime. src/ contains the entire python
+# package; pyproject.toml is present for tooling that reads project metadata.
+COPY --chown=app:app src/ ./src/
+COPY --chown=app:app pyproject.toml ./
+
+USER app
+
+EXPOSE 8000
+
+# Container healthcheck — Docker + docker-compose will use this to gate startup
+# of dependent services (the UI waits on `service_healthy`).
+HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -fsS http://localhost:8000/health || exit 1
+
+# uvicorn's --host 0.0.0.0 makes the port reachable from other compose services.
+# Single worker keeps the FastAPI dependency singleton (DocumentExtractor)
+# consistent; if we ever need horizontal scale we'll switch to gunicorn.
+CMD ["uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker/nginx.conf

@@ -0,0 +1,56 @@
+# ============================================================================
+# nginx config for the UI container.
+#
+# Two jobs:
+#   1. Serve the Vite-built static assets under /
+#   2. Proxy /api/* to the API container (service name "api" on the compose
+#      network). This mirrors the Vite dev-server proxy in ui/vite.config.ts
+#      so the frontend's fetch("/extract") calls work identically in dev and
+#      in the compose stack.
+# ============================================================================
+server {
+    listen       5173;
+    server_name  _;
+
+    # Compressed responses for text-y assets (JS, CSS, HTML, JSON).
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript
+               application/xml+rss text/javascript image/svg+xml;
+    gzip_min_length 1024;
+
+    # Static assets — long-cache with immutable hint. Vite fingerprints
+    # filenames, so a new build cache-busts automatically.
+    location /assets/ {
+        root /usr/share/nginx/html;
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # API proxy — strip the /api prefix so the FastAPI routes stay clean.
+    # `service_healthy` in compose guarantees this backend is up before we
+    # accept traffic here.
+    location /api/ {
+        proxy_pass         http://api:8000/;
+        proxy_http_version 1.1;
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+
+        # Extraction can take 20-60s for large PDFs, so bump the read timeout
+        # above the nginx default (60s).
+        proxy_connect_timeout 10s;
+        proxy_read_timeout    120s;
+
+        # Big uploads: 10-K filings can be 5+ MB.
+        client_max_body_size  20m;
+    }
+
+    # SPA fallback — any non-file route falls back to index.html so React
+    # Router (or hash routing) can take over.
+    location / {
+        root /usr/share/nginx/html;
+        index index.html;
+        try_files $uri $uri/ /index.html;
+    }
+}

docker/ui.Dockerfile

@@ -0,0 +1,42 @@
+# ============================================================================
+# Structured Data Extraction — UI image
+#
+# Multi-stage build: stage 1 (node) runs the Vite production build, stage 2
+# (nginx) serves the resulting static bundle and proxies /api to the api
+# container. Nothing from node_modules survives into the runtime image.
+# ============================================================================
+
+# ---------- Stage 1: build the Vite bundle -----------------------------------
+FROM node:20-alpine AS builder
+
+WORKDIR /ui
+
+# Copy package manifests first — this lets Docker cache the npm install
+# layer across code-only changes.
+COPY ui/package.json ui/package-lock.json ./
+RUN npm ci --no-audit --no-fund
+
+# Copy the rest of the ui source and build.
+COPY ui/ ./
+RUN npm run build
+
+# ---------- Stage 2: serve with nginx ----------------------------------------
+FROM nginx:1.27-alpine AS runtime
+
+# Custom nginx config — proxies /api to the api container.
+COPY docker/nginx.conf /etc/nginx/conf.d/default.conf
+# Remove the stock nginx config that listens on :80 — we listen on :5173 only.
+RUN rm -f /etc/nginx/conf.d/default.conf.bak && \
+    sed -i '/listen       80;/d' /etc/nginx/nginx.conf 2>/dev/null || true
+
+# Copy the built bundle.
+COPY --from=builder /ui/dist /usr/share/nginx/html
+
+EXPOSE 5173
+
+# nginx:alpine runs as root by default — nginx workers drop to `nginx` user
+# themselves once bound to the port, so we leave the entrypoint alone.
+HEALTHCHECK --interval=15s --timeout=3s --start-period=5s --retries=3 \
+    CMD wget -qO- http://localhost:5173/ >/dev/null || exit 1
+
+CMD ["nginx", "-g", "daemon off;"]

pyproject.toml

@@ -13,7 +13,21 @@ target-version = "py311"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP", "B", "SIM"]
-ignore = ["E501"]  # line-length handled by formatter
+ignore = ["E501", "UP017"]  # E501: line-length via formatter. UP017: datetime.UTC (3.11-only) — we still support timezone.utc for broader interpreter reach in tooling.
+
+[tool.ruff.lint.per-file-ignores]
+# HTTP-error taxonomy — these are our own class hierarchy, not surprises.
+# Renaming to `*Error` would leak "Error" everywhere at call sites without
+# adding meaning.
+"src/api/errors.py" = ["N818"]
+# FastAPI convention: File(...) / Depends() go in function default args.
+# The whole framework is built around this pattern.
+"src/api/routers/*.py" = ["B008"]
+# Parser branches carry different explanatory comments — a ternary would
+# drop them and hurt readability more than help.
+"src/data_prep/parsers.py" = ["SIM108"]
+# Test tuple-unpacking sometimes leaves parts unused for clarity.
+"tests/**/*.py" = ["B007"]
 
 [tool.black]
 line-length = 100

src/data_prep/cord.py

@@ -8,7 +8,8 @@ Reference: https://github.com/clovaai/cord
 """
 from __future__ import annotations
 
-from typing import Any, Iterator
+from collections.abc import Iterator
+from typing import Any
 
 from src.data_prep.parsers import clean_text, parse_money
 from src.schemas import Receipt, ReceiptLineItem

src/data_prep/sroie.py

@@ -12,7 +12,8 @@ Reference: https://rrc.cvc.uab.es/?ch=13
 """
 from __future__ import annotations
 
-from typing import Any, Iterator
+from collections.abc import Iterator
+from typing import Any
 
 from src.data_prep.parsers import clean_text, parse_date, parse_money
 from src.schemas import Address, Receipt

src/eval/__init__.py

@@ -11,7 +11,7 @@ Public entry points:
     run_eval(records, extractor, doc_type, ...) -> EvalReport
     write_reports(report, out_dir) -> (csv_path, md_path)
 """
-from src.eval.runner import EvalReport, run_eval
 from src.eval.report import write_reports
+from src.eval.runner import EvalReport, run_eval
 
 __all__ = ["run_eval", "EvalReport", "write_reports"]

src/eval/cli.py

@@ -21,7 +21,6 @@ import argparse
 import sys
 from datetime import datetime
 from pathlib import Path
-from typing import Callable
 
 from pydantic import BaseModel
 
@@ -33,7 +32,6 @@ from src.schemas.registry import get_schema
 from src.utils.cost_tracker import ExtractionMetrics
 from src.utils.logging import logger
 
-
 # ---------------------------------------------------------------------------
 # Extractor factories: pluggable strategies for how a JSONL record becomes an
 # (ExtractionResult, ExtractionMetrics) pair.

src/eval/report.py

@@ -8,7 +8,6 @@ from pathlib import Path
 
 from src.eval.runner import EvalReport
 
-
 # --- CSV -------------------------------------------------------------------
 
 def write_per_record_csv(report: EvalReport, out_path: str | Path) -> Path:

src/eval/runner.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import time as _time
 from collections.abc import Callable, Sequence
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from statistics import mean
 from typing import Any
 

src/schemas/invoice.py

@@ -106,7 +106,7 @@ class Invoice(StrictModel):
         return normalize_currency(v)
 
     @model_validator(mode="after")
-    def _sanity_check_totals(self) -> "Invoice":
+    def _sanity_check_totals(self) -> Invoice:
         """Sanity-check: if subtotal + tax + shipping ~= total, we're consistent.
 
         We don't reject on mismatch (the model may have transcribed one field

src/utils/cost_tracker.py

@@ -38,7 +38,7 @@ class ExtractionMetrics:
 class Timer:
     """Context manager for measuring wall-clock latency in ms."""
 
-    def __enter__(self) -> "Timer":
+    def __enter__(self) -> Timer:
         self._start = perf_counter()
         self.elapsed_ms = 0.0
         return self

tests/unit/test_api.py

@@ -11,12 +11,11 @@ import io
 import pytest
 from fastapi.testclient import TestClient
 
-from src.api.deps import MAX_UPLOAD_BYTES, get_extractor
+from src.api.deps import get_extractor
 from src.api.main import create_app
 from src.schemas import ExtractionResult, Receipt
 from src.utils.cost_tracker import ExtractionMetrics
 
-
 # --- Fake extractor --------------------------------------------------------
 
 class _FakeExtractor:

tests/unit/test_data_prep.py

@@ -5,7 +5,6 @@ of SROIE and CORD.
 """
 from __future__ import annotations
 
-import json
 from datetime import date
 from pathlib import Path
 
@@ -17,7 +16,6 @@ from src.data_prep.sroie import normalize_sroie_record
 from src.data_prep.writer import read_jsonl, write_jsonl
 from src.schemas import Receipt
 
-
 # --- Money parsing ---------------------------------------------------------
 
 

tests/unit/test_eval.py

@@ -12,8 +12,6 @@ from __future__ import annotations
 
 from datetime import date
 
-import pytest
-
 from src.data_prep.writer import read_jsonl
 from src.eval.comparators import (
     compare,
@@ -29,7 +27,6 @@ from src.eval.runner import run_eval
 from src.schemas import ExtractionResult, Receipt
 from src.utils.cost_tracker import ExtractionMetrics
 
-
 # --- Comparators -----------------------------------------------------------
 
 class TestComparators:

tests/unit/test_extractor.py

@@ -21,7 +21,6 @@ from src.schemas import (
     Receipt,
 )
 
-
 # --- Prompt registry -------------------------------------------------------
 
 

tests/unit/test_schemas.py

@@ -21,7 +21,6 @@ from src.schemas import (
     list_doc_types,
 )
 
-
 # --- Invoice ----------------------------------------------------------------
 
 

ui/package.json

@@ -19,6 +19,7 @@
     "three": "^0.169.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
     "@types/three": "^0.169.0",

ui/src/components/PaperScene.tsx

@@ -19,7 +19,7 @@
  */
 import { Canvas, useFrame } from "@react-three/fiber";
 import { Environment } from "@react-three/drei";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import type { Group, Mesh } from "three";
 import * as THREE from "three";
 
@@ -62,18 +62,19 @@ export function PaperScene({ state }: Props) {
 
 function Sheet({ state }: { state: PaperState }) {
   const group = useRef<Group>(null!);
-  const [mouse, setMouse] = useState({ x: 0, y: 0 });
+  // Mouse position lives in a ref, not state, so pointer movement doesn't
+  // force React re-renders at ~60Hz. `useFrame` reads it directly on the next
+  // GPU tick, so parallax stays live without touching the render loop.
+  const mouse = useRef({ x: 0, y: 0 });
 
   // Track the mouse across the whole window — the parallax reads better when
   // it's tied to page position, not just the canvas.
   useEffect(() => {
     const onMove = (e: MouseEvent) => {
-      setMouse({
-        x: (e.clientX / window.innerWidth) * 2 - 1,
-        y: -(e.clientY / window.innerHeight) * 2 + 1,
-      });
+      mouse.current.x = (e.clientX / window.innerWidth) * 2 - 1;
+      mouse.current.y = -(e.clientY / window.innerHeight) * 2 + 1;
     };
-    window.addEventListener("mousemove", onMove);
+    window.addEventListener("mousemove", onMove, { passive: true });
     return () => window.removeEventListener("mousemove", onMove);
   }, []);
 
@@ -88,9 +89,9 @@ function Sheet({ state }: { state: PaperState }) {
     const driftRotX = Math.sin(t * 0.4) * 0.05;
     const driftRotZ = Math.cos(t * 0.3) * 0.03;
 
-    // Parallax offset from mouse.
-    const paraX = mouse.x * 0.14;
-    const paraY = mouse.y * 0.08;
+    // Parallax offset from mouse (ref-based — no React re-renders).
+    const paraX = mouse.current.x * 0.14;
+    const paraY = mouse.current.y * 0.08;
 
     // Targets vary by state.
     const targetRotX = state === "extracted" ? -0.35 : driftRotX + paraY * 0.8;
@@ -117,14 +118,16 @@ function Sheet({ state }: { state: PaperState }) {
         <meshBasicMaterial color="#000000" transparent opacity={0.12} />
       </mesh>
 
-      {/* Main sheet — a slightly wider-than-tall rectangle. */}
+      {/* Main sheet — a slightly wider-than-tall rectangle.
+          Uses MeshBasicMaterial so the texture (which already contains its
+          own baked-in shading + gradient) reads at full brightness. Standard
+          PBR shading was dimming the printed text — user flagged this. */}
       <mesh castShadow receiveShadow>
         <boxGeometry args={[2.55, 3.4, 0.02]} />
-        <meshStandardMaterial
+        <meshBasicMaterial
           map={texture}
-          roughness={0.85}
-          metalness={0}
           side={THREE.DoubleSide}
+          toneMapped={false}
         />
       </mesh>
 
@@ -202,24 +205,35 @@ function Glow({ active }: { active: boolean }) {
  * that the sheet reads as a document rather than a blank plane.
  */
 function paperTexture(): THREE.CanvasTexture {
+  // Draw at 2× so the sheet stays sharp when the camera is close.
+  // `ctx.scale` lets us keep all layout coordinates in the original 512×680
+  // logical space — every font-size and offset below is unchanged.
+  const SCALE = 2;
+  const LOGICAL_W = 512;
+  const LOGICAL_H = 680;
   const c = document.createElement("canvas");
-  c.width = 512;
-  c.height = 680;
+  c.width = LOGICAL_W * SCALE;
+  c.height = LOGICAL_H * SCALE;
   const ctx = c.getContext("2d")!;
+  ctx.scale(SCALE, SCALE);
+  // From here on, treat the drawing surface as if it were LOGICAL_W × LOGICAL_H.
+  // Local aliases keep the layout math readable.
+  const cw = LOGICAL_W;
+  const ch = LOGICAL_H;
 
   // Base paper — warm cream with a subtle gradient
-  const grad = ctx.createLinearGradient(0, 0, 0, c.height);
+  const grad = ctx.createLinearGradient(0, 0, 0, ch);
   grad.addColorStop(0, "#f8f2e2");
   grad.addColorStop(1, "#efe8d0");
   ctx.fillStyle = grad;
-  ctx.fillRect(0, 0, c.width, c.height);
+  ctx.fillRect(0, 0, cw, ch);
 
   // Speckle grain
   for (let i = 0; i < 2200; i++) {
     ctx.fillStyle = `rgba(120,100,60,${Math.random() * 0.04})`;
     ctx.fillRect(
-      Math.random() * c.width,
-      Math.random() * c.height,
+      Math.random() * cw,
+      Math.random() * ch,
       Math.random() * 1.6,
       Math.random() * 1.6
     );
@@ -230,7 +244,7 @@ function paperTexture(): THREE.CanvasTexture {
   ctx.lineWidth = 1.2;
   ctx.beginPath();
   ctx.moveTo(40, 96);
-  ctx.lineTo(c.width - 40, 96);
+  ctx.lineTo(cw - 40, 96);
   ctx.stroke();
 
   // Vendor/merchant label
@@ -241,10 +255,10 @@ function paperTexture(): THREE.CanvasTexture {
   // Ruled body lines (light)
   ctx.strokeStyle = "rgba(16,32,59,0.09)";
   ctx.lineWidth = 1;
-  for (let y = 130; y < c.height - 120; y += 26) {
+  for (let y = 130; y < ch - 120; y += 26) {
     ctx.beginPath();
     ctx.moveTo(40, y);
-    ctx.lineTo(c.width - 40, y);
+    ctx.lineTo(cw - 40, y);
     ctx.stroke();
   }
 
@@ -258,25 +272,25 @@ function paperTexture(): THREE.CanvasTexture {
   ];
   rows.forEach(([desc, amt], i) => {
     ctx.fillText(desc, 40, 156 + i * 26);
-    ctx.fillText(amt, c.width - 130, 156 + i * 26);
+    ctx.fillText(amt, cw - 130, 156 + i * 26);
   });
 
   // Total
   ctx.strokeStyle = "rgba(16,32,59,0.55)";
   ctx.beginPath();
   ctx.moveTo(40, 260);
-  ctx.lineTo(c.width - 40, 260);
+  ctx.lineTo(cw - 40, 260);
   ctx.stroke();
 
   ctx.fillStyle = "#10203b";
   ctx.font = 'italic 22px "Instrument Serif", serif';
   ctx.fillText("Total", 40, 292);
   ctx.font = 'italic 22px "Instrument Serif", serif';
-  ctx.fillText("$1,800.00", c.width - 140, 292);
+  ctx.fillText("$1,800.00", cw - 140, 292);
 
   // Bottom stamp — a red circle with "PAID" (ish)
-  const cx = c.width - 110;
-  const cy = c.height - 110;
+  const cx = cw - 110;
+  const cy = ch - 110;
   ctx.save();
   ctx.translate(cx, cy);
   ctx.rotate(-0.18);
@@ -296,7 +310,14 @@ function paperTexture(): THREE.CanvasTexture {
   ctx.restore();
 
   const tex = new THREE.CanvasTexture(c);
-  tex.anisotropy = 8;
+  // Sharpness knobs — user flagged text as bitty on the hero.
+  // • LinearFilter (no mipmap blur) keeps small type crisp at close camera range.
+  // • anisotropy 16 keeps text readable at glancing angles as the sheet tilts.
+  // • generateMipmaps off — we don't need distance LODs for a hero prop.
+  tex.minFilter = THREE.LinearFilter;
+  tex.magFilter = THREE.LinearFilter;
+  tex.anisotropy = 16;
+  tex.generateMipmaps = false;
   tex.needsUpdate = true;
   return tex;
 }

ui/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

ui/tsconfig.json

@@ -15,6 +15,7 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noFallthroughCasesInSwitch": true,
+    "types": ["node", "vite/client"],
     "baseUrl": ".",
     "paths": {
       "@/*": ["src/*"]