From 9b8b7e0ed8c4aa961b418ec1614f35719ec35936 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 20:24:48 -0700
Subject: [PATCH 01/84] Fix CI step gating and group Dependabot action updates

---
 .github/dependabot.yml   |  4 +++
 .github/workflows/ci.yml | 58 +++++++++++++++++++++++++++++++++-------
 2 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index e71e765..5b31257 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -13,6 +13,10 @@ updates:
     labels:
       - dependencies
       - github-actions
+    groups:
+      github-actions-all:
+        patterns:
+          - "*"
 
   - package-ecosystem: pip
     directory: /
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e473676..5058db3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,15 +31,30 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Check for pyproject.toml
+        id: check
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "::notice::pyproject.toml not present, skipping Python checks"
+          fi
       - uses: actions/setup-python@v6
+        if: steps.check.outputs.exists == 'true'
         with:
           python-version: '3.12'
           cache: pip
-      - run: pip install -e .[dev]
-      - run: ruff check .
-      - run: ruff format --check .
-      - run: mypy backend
-      - run: pytest -q
+      - if: steps.check.outputs.exists == 'true'
+        run: pip install -e .[dev]
+      - if: steps.check.outputs.exists == 'true'
+        run: ruff check .
+      - if: steps.check.outputs.exists == 'true'
+        run: ruff format --check .
+      - if: steps.check.outputs.exists == 'true'
+        run: mypy backend
+      - if: steps.check.outputs.exists == 'true'
+        run: pytest -q
 
   frontend:
     needs: detect
@@ -50,15 +65,29 @@ jobs:
         working-directory: frontend
     steps:
       - uses: actions/checkout@v6
+      - name: Check for frontend/package.json
+        id: check
+        run: |
+          if [ -f package.json ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "::notice::frontend/package.json not present, skipping frontend checks"
+          fi
       - uses: actions/setup-node@v6
+        if: steps.check.outputs.exists == 'true'
         with:
           node-version: lts/*
           cache: npm
           cache-dependency-path: frontend/package-lock.json
-      - run: npm ci
-      - run: npm run lint --if-present
-      - run: npx tsc --noEmit
-      - run: npm run build
+      - if: steps.check.outputs.exists == 'true'
+        run: npm ci
+      - if: steps.check.outputs.exists == 'true'
+        run: npm run lint --if-present
+      - if: steps.check.outputs.exists == 'true'
+        run: npx tsc --noEmit
+      - if: steps.check.outputs.exists == 'true'
+        run: npm run build
 
   docker:
     needs: detect
@@ -66,8 +95,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - name: Check for Dockerfile
+        id: check
+        run: |
+          if [ -f Dockerfile ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "::notice::Dockerfile not present, skipping Docker build"
+          fi
       - uses: docker/setup-buildx-action@v4
+        if: steps.check.outputs.exists == 'true'
       - uses: docker/build-push-action@v6
+        if: steps.check.outputs.exists == 'true'
         with:
           context: .
           push: false

From b479d3ef9f0b6df0743e11bffc336533d6acddb1 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:17:40 -0700
Subject: [PATCH 02/84] Add slice 1 backend skeleton with quick-print path

---
 .env.example                           |  26 +++++
 Dockerfile                             |  35 +++++++
 backend/labelforge/__init__.py         |   1 +
 backend/labelforge/catalog/__init__.py |   0
 backend/labelforge/catalog/loader.py   |  90 ++++++++++++++++++
 backend/labelforge/config.py           |  19 ++++
 backend/labelforge/db.py               |  34 +++++++
 backend/labelforge/main.py             |  61 ++++++++++++
 backend/labelforge/models/__init__.py  |  46 +++++++++
 backend/labelforge/printer/__init__.py |   0
 backend/labelforge/printer/client.py   |  61 ++++++++++++
 backend/labelforge/render/__init__.py  |   0
 backend/labelforge/render/fonts.py     |  70 ++++++++++++++
 backend/labelforge/render/text.py      | 126 +++++++++++++++++++++++++
 backend/labelforge/routes/__init__.py  |   0
 backend/labelforge/routes/auth.py      |  15 +++
 backend/labelforge/routes/fonts.py     |  15 +++
 backend/labelforge/routes/health.py    |   8 ++
 backend/labelforge/routes/labels.py    |  20 ++++
 backend/labelforge/routes/print.py     |  63 +++++++++++++
 compose.dev.yml                        |  29 ++++++
 compose.yml                            |  31 ++++++
 labels.yml                             | 125 ++++++++++++++++++++++++
 23 files changed, 875 insertions(+)
 create mode 100644 .env.example
 create mode 100644 Dockerfile
 create mode 100644 backend/labelforge/__init__.py
 create mode 100644 backend/labelforge/catalog/__init__.py
 create mode 100644 backend/labelforge/catalog/loader.py
 create mode 100644 backend/labelforge/config.py
 create mode 100644 backend/labelforge/db.py
 create mode 100644 backend/labelforge/main.py
 create mode 100644 backend/labelforge/models/__init__.py
 create mode 100644 backend/labelforge/printer/__init__.py
 create mode 100644 backend/labelforge/printer/client.py
 create mode 100644 backend/labelforge/render/__init__.py
 create mode 100644 backend/labelforge/render/fonts.py
 create mode 100644 backend/labelforge/render/text.py
 create mode 100644 backend/labelforge/routes/__init__.py
 create mode 100644 backend/labelforge/routes/auth.py
 create mode 100644 backend/labelforge/routes/fonts.py
 create mode 100644 backend/labelforge/routes/health.py
 create mode 100644 backend/labelforge/routes/labels.py
 create mode 100644 backend/labelforge/routes/print.py
 create mode 100644 compose.dev.yml
 create mode 100644 compose.yml
 create mode 100644 labels.yml

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f2f73f7
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,26 @@
+# labelforge environment — copy to .env and fill in your values.
+# All variables are read by pydantic-settings; names are case-insensitive.
+
+# REQUIRED: shared secret for the HTTP API.  All /api/* routes (except /api/health)
+# require:  Authorization: Bearer <API_TOKEN>
+API_TOKEN=changeme
+
+# REQUIRED: IP or hostname of the Brother QL printer.
+# For network backend this becomes tcp://<PRINTER_HOST>:9100.
+PRINTER_HOST=192.168.1.x
+
+# Brother QL model identifier, must match brother_ql's model list.
+PRINTER_MODEL=QL-820NWB
+
+# Printer connection backend: network | linux_kernel | pyusb
+PRINTER_BACKEND=network
+
+# Label media loaded in the printer by default (used as UI pre-selection).
+DEFAULT_LABEL_MEDIA=62
+
+# Host path where SQLite, labels.yml, fonts, and previews are stored.
+# Must be bind-mounted into the container at the same path.
+DATA_DIR=/var/docker/labelforge
+
+# Python log level: DEBUG | INFO | WARNING | ERROR
+LOG_LEVEL=INFO
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..3acec2c
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,35 @@
+# TODO: Slice N — add a multi-stage frontend build stage (node:lts-alpine, npm ci + npm run build)
+#        before this runtime stage, then COPY --from=frontend /app/frontend/dist /app/frontend/dist
+#        and mount it via FastAPI StaticFiles.
+
+FROM python:3.12-slim
+
+# System fonts required by render/text.py; Pillow wheels include libjpeg/zlib.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        fonts-dejavu-core \
+        fonts-liberation2 \
+        fonts-noto-core \
+    && rm -rf /var/lib/apt/lists/*
+
+# Non-root runtime user (uid 1000).
+RUN useradd -u 1000 -m labelforge
+
+WORKDIR /app
+
+# Install Python dependencies + the labelforge package (editable so the source
+# at /app/backend/labelforge/ is authoritative — enables bind-mount hot-reload
+# in compose.dev.yml without rebuilding the image).
+COPY pyproject.toml README.md ./
+COPY backend/ backend/
+RUN pip install --no-cache-dir -e .
+
+# Default label catalog shipped in the image.  At startup, if
+# ${DATA_DIR}/labels.yml is absent, main.py copies this into the volume.
+COPY labels.yml /app/labels.yml
+
+RUN chown -R labelforge:labelforge /app
+USER labelforge
+
+EXPOSE 8000
+
+CMD ["uvicorn", "labelforge.main:app", "--host", "0.0.0.0", "--port", "8000"]
diff --git a/backend/labelforge/__init__.py b/backend/labelforge/__init__.py
new file mode 100644
index 0000000..f102a9c
--- /dev/null
+++ b/backend/labelforge/__init__.py
@@ -0,0 +1 @@
+__version__ = "0.0.1"
diff --git a/backend/labelforge/catalog/__init__.py b/backend/labelforge/catalog/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/labelforge/catalog/loader.py b/backend/labelforge/catalog/loader.py
new file mode 100644
index 0000000..d61facd
--- /dev/null
+++ b/backend/labelforge/catalog/loader.py
@@ -0,0 +1,90 @@
+import logging
+from pathlib import Path
+
+import yaml
+from brother_ql.labels import ALL_LABELS, FormFactor
+
+from labelforge.models import LabelEntry
+
+logger = logging.getLogger(__name__)
+
+_catalog: dict[str, LabelEntry] = {}
+
+# Map FormFactor enum values to the integer stored in LabelEntry.form_factor.
+# FormFactor.DIE_CUT=1, ENDLESS=2, ROUND_DIE_CUT=3, PTOUCH_ENDLESS=4
+_FORM_FACTOR_INT: dict[FormFactor, int] = {ff: ff.value for ff in FormFactor}
+
+
+def load_catalog(yml_path: Path) -> None:
+    global _catalog
+
+    lib_labels = {label.identifier: label for label in ALL_LABELS}
+
+    yml_entries: dict[str, dict] = {}
+    if yml_path.exists():
+        with yml_path.open() as fh:
+            data = yaml.safe_load(fh) or {}
+        for entry in data.get("labels", []):
+            try:
+                yml_entries[entry["id"]] = entry
+            except (KeyError, TypeError):
+                logger.warning("Skipping malformed catalog entry: %s", entry)
+    else:
+        logger.warning("labels.yml not found at %s — using library fallbacks only", yml_path)
+
+    new_catalog: dict[str, LabelEntry] = {}
+    lib_only = 0
+
+    for lib_id, lib_label in lib_labels.items():
+        form_factor_int = _FORM_FACTOR_INT.get(lib_label.form_factor, 0)
+        dots = (lib_label.dots_printable[0], lib_label.dots_printable[1])
+        tape = (lib_label.tape_size[0], lib_label.tape_size[1])
+
+        if lib_id in yml_entries:
+            y = yml_entries[lib_id]
+            entry = LabelEntry(
+                id=lib_id,
+                display_name=y.get("display_name", lib_id),
+                brother_part=y.get("brother_part"),
+                description=y.get("description"),
+                category=y.get("category"),
+                color_capable=bool(y.get("color_capable", False)),
+                printer_requirements=y.get("printer_requirements") or [],
+                common_use=y.get("common_use") or [],
+                preview_image=y.get("preview_image"),
+                dots_printable=dots,
+                tape_size=tape,
+                form_factor=form_factor_int,
+            )
+        else:
+            entry = LabelEntry(
+                id=lib_id,
+                display_name=lib_id,
+                dots_printable=dots,
+                tape_size=tape,
+                form_factor=form_factor_int,
+            )
+            lib_only += 1
+
+        new_catalog[lib_id] = entry
+
+    yml_only = sum(1 for k in yml_entries if k not in lib_labels)
+    for stale_id in yml_entries:
+        if stale_id not in lib_labels:
+            logger.warning("Catalog entry '%s' not in brother_ql library — hidden", stale_id)
+
+    _catalog = new_catalog
+    logger.info(
+        "Catalog loaded: %d entries (%d library-only fallbacks, %d yml-only hidden)",
+        len(new_catalog),
+        lib_only,
+        yml_only,
+    )
+
+
+def get_catalog() -> dict[str, LabelEntry]:
+    return _catalog
+
+
+def get_label(label_id: str) -> LabelEntry | None:
+    return _catalog.get(label_id)
diff --git a/backend/labelforge/config.py b/backend/labelforge/config.py
new file mode 100644
index 0000000..b31473f
--- /dev/null
+++ b/backend/labelforge/config.py
@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    api_token: str
+    printer_host: str
+    printer_model: str = "QL-820NWB"
+    # one of: network, linux_kernel, pyusb
+    printer_backend: str = "network"
+    data_dir: Path = Path("/var/docker/labelforge")
+    default_label_media: str = "62"
+    log_level: str = "INFO"
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+
+settings = Settings()
diff --git a/backend/labelforge/db.py b/backend/labelforge/db.py
new file mode 100644
index 0000000..a8ef5a4
--- /dev/null
+++ b/backend/labelforge/db.py
@@ -0,0 +1,34 @@
+import sqlite3
+from pathlib import Path
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS print_jobs (
+    id          INTEGER PRIMARY KEY,
+    template_id TEXT    NULL,
+    payload_json TEXT   NOT NULL,
+    label_media TEXT    NOT NULL,
+    preview_path TEXT   NULL,
+    pinned      INTEGER NOT NULL DEFAULT 0,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS settings (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+"""
+
+
+def get_connection(db_path: Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def init_db(db_path: Path) -> None:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = get_connection(db_path)
+    conn.executescript(_SCHEMA)
+    conn.commit()
+    conn.close()
diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
new file mode 100644
index 0000000..d72ceca
--- /dev/null
+++ b/backend/labelforge/main.py
@@ -0,0 +1,61 @@
+import logging
+import shutil
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from labelforge.catalog.loader import load_catalog
+from labelforge.config import settings
+from labelforge.db import init_db
+from labelforge.render.fonts import load_fonts
+from labelforge.routes import fonts, health, labels
+from labelforge.routes import print as print_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):  # noqa: ARG001
+    logging.basicConfig(
+        level=settings.log_level.upper(),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    logger = logging.getLogger(__name__)
+
+    data_dir: Path = settings.data_dir
+    (data_dir / "data").mkdir(parents=True, exist_ok=True)
+    (data_dir / "fonts").mkdir(parents=True, exist_ok=True)
+    logger.info("Data directory: %s", data_dir)
+
+    yml_path = data_dir / "labels.yml"
+    if not yml_path.exists():
+        default_yml = Path("/app/labels.yml")
+        if default_yml.exists():
+            shutil.copy(default_yml, yml_path)
+            logger.info("Copied default labels.yml to %s", yml_path)
+        else:
+            logger.warning(
+                "labels.yml missing at %s and no default at /app/labels.yml", yml_path
+            )
+
+    db_path = data_dir / "data" / "app.db"
+    init_db(db_path)
+    logger.info("Database ready: %s", db_path)
+
+    load_catalog(yml_path)
+    load_fonts(data_dir / "fonts")
+
+    yield
+    # Nothing to clean up on shutdown.
+
+
+app = FastAPI(
+    title="labelforge",
+    version="0.0.1",
+    description="Self-hosted Brother QL label printer API",
+    lifespan=lifespan,
+)
+
+app.include_router(health.router, prefix="/api")
+app.include_router(labels.router, prefix="/api")
+app.include_router(fonts.router, prefix="/api")
+app.include_router(print_router.router, prefix="/api")
diff --git a/backend/labelforge/models/__init__.py b/backend/labelforge/models/__init__.py
new file mode 100644
index 0000000..9373089
--- /dev/null
+++ b/backend/labelforge/models/__init__.py
@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class LabelEntry(BaseModel):
+    id: str
+    display_name: str
+    brother_part: str | None = None
+    description: str | None = None
+    category: str | None = None
+    color_capable: bool = False
+    printer_requirements: list[str] = []
+    common_use: list[str] = []
+    preview_image: str | None = None
+    # library-derived fields
+    dots_printable: tuple[int, int] = (0, 0)
+    tape_size: tuple[int, int] = (0, 0)
+    # form_factor integer: 1=die-cut, 2=continuous, 3=round, 4=ptouch-continuous
+    form_factor: int = 0
+
+
+class FontInfo(BaseModel):
+    name: str
+    path: str
+    family: str
+    style: str
+
+
+class QuickPrintRequest(BaseModel):
+    text: str = Field(..., min_length=1)
+    font: str
+    font_size: int = Field(48, ge=6, le=200)
+    alignment: Literal["left", "center", "right"] = "left"
+    orientation: Literal["standard", "rotated"] = "standard"
+    label_media: str
+    bold: bool = False
+    italic: bool = False
+
+
+class PrintJobResponse(BaseModel):
+    job_id: int
+    status: str
+    preview_url: str | None = None
diff --git a/backend/labelforge/printer/__init__.py b/backend/labelforge/printer/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
new file mode 100644
index 0000000..f3aa8b6
--- /dev/null
+++ b/backend/labelforge/printer/client.py
@@ -0,0 +1,61 @@
+# Import paths verified against brother-ql-inventree 1.3:
+#   brother_ql.raster.BrotherQLRaster       — builds the instruction buffer
+#   brother_ql.conversion.convert           — PIL Image → raster bytes (returns qlr.data)
+#   brother_ql.backends.helpers.send        — transmits bytes to the printer
+#
+# Network backend expects printer_identifier in the form "tcp://host[:port]"
+# (port defaults to 9100 when omitted).  The send() helper also accepts
+# backend_identifier values: "network", "linux_kernel", "pyusb".
+
+import logging
+
+from brother_ql.backends.helpers import send
+from brother_ql.conversion import convert
+from brother_ql.raster import BrotherQLRaster
+from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class PrintError(Exception):
+    pass
+
+
+def print_image(
+    image: Image.Image,
+    label_media: str,
+    model: str,
+    backend: str,
+    host: str,
+) -> str:
+    """Convert *image* to raster instructions and send to the printer.
+
+    Returns the send outcome string. NOTE: the network backend cannot read
+    back from the printer, so it returns 'sent' (transmitted, result unknown)
+    rather than 'printed' even on success. Only USB backends can confirm an
+    actual print. Callers must not treat 'sent' as a guaranteed print.
+
+    Raises PrintError on any failure so callers can surface a clean 500.
+    """
+    try:
+        qlr = BrotherQLRaster(model)
+        # rotate=0: keep the rendered image's width (696px for 62mm) as the
+        # print-head width. rotate='auto' (the library default) can flip a
+        # wide continuous image into a geometry the printer reads as the wrong
+        # roll type. The renderer already produces the correct orientation.
+        instructions = convert(qlr, [image], label_media, cut=True, rotate="0")
+        identifier = f"tcp://{host}" if backend == "network" else host
+        result = send(
+            instructions=instructions,
+            printer_identifier=identifier,
+            backend_identifier=backend,
+            blocking=True,
+        )
+        logger.debug("Print result: %s", result)
+        if result.get("outcome") == "error":
+            raise PrintError(f"Printer reported an error: {result}")
+        return result.get("outcome", "unknown")
+    except PrintError:
+        raise
+    except Exception as exc:
+        raise PrintError(f"Print failed: {exc}") from exc
diff --git a/backend/labelforge/render/__init__.py b/backend/labelforge/render/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/labelforge/render/fonts.py b/backend/labelforge/render/fonts.py
new file mode 100644
index 0000000..68dcc98
--- /dev/null
+++ b/backend/labelforge/render/fonts.py
@@ -0,0 +1,70 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_SYSTEM_FONT_DIR = Path("/usr/share/fonts/truetype")
+_EXTENSIONS = {".ttf", ".otf"}
+# Style keyword tokens used to split family from style in filename stems.
+_STYLE_TOKENS = {
+    "Bold", "Italic", "Light", "Thin", "Medium", "Regular",
+    "Black", "Condensed", "Oblique", "SemiBold", "ExtraBold",
+}
+
+_font_cache: list["FontInfo"] = []
+
+
+@dataclass
+class FontInfo:
+    name: str   # filename stem — used as font identifier in the API
+    path: str
+    family: str
+    style: str
+
+
+def _parse_stem(stem: str) -> tuple[str, str]:
+    """Split 'DejaVuSans-Bold' into family='DejaVu Sans', style='Bold'."""
+    tokens = stem.replace("-", " ").replace("_", " ").split()
+    style_parts = [t for t in tokens if t in _STYLE_TOKENS]
+    family_parts = [t for t in tokens if t not in _STYLE_TOKENS]
+    family = " ".join(family_parts) or stem
+    style = " ".join(style_parts) or "Regular"
+    return family, style
+
+
+def _scan_dir(directory: Path, fonts: dict[str, FontInfo]) -> None:
+    if not directory.exists():
+        logger.debug("Font directory not found, skipping: %s", directory)
+        return
+    for path in sorted(directory.rglob("*")):
+        if path.suffix.lower() in _EXTENSIONS and path.is_file():
+            name = path.stem
+            family, style = _parse_stem(name)
+            fonts[name] = FontInfo(name=name, path=str(path), family=family, style=style)
+
+
+def load_fonts(user_font_dir: Path) -> None:
+    global _font_cache
+    fonts: dict[str, FontInfo] = {}
+    _scan_dir(_SYSTEM_FONT_DIR, fonts)
+    # User fonts overlay system fonts on name collision.
+    _scan_dir(user_font_dir, fonts)
+    _font_cache = list(fonts.values())
+    logger.info("Fonts loaded: %d fonts discovered", len(_font_cache))
+
+
+def get_fonts() -> list[FontInfo]:
+    return _font_cache
+
+
+def get_font_path(name: str) -> str | None:
+    for f in _font_cache:
+        if f.name == name:
+            return f.path
+    return None
+
+
+def reload_fonts(user_font_dir: Path) -> None:
+    """Re-scan font directories. Not yet wired to an endpoint."""
+    load_fonts(user_font_dir)
diff --git a/backend/labelforge/render/text.py b/backend/labelforge/render/text.py
new file mode 100644
index 0000000..2e9d5cc
--- /dev/null
+++ b/backend/labelforge/render/text.py
@@ -0,0 +1,126 @@
+import logging
+
+from PIL import Image, ImageDraw, ImageFont
+
+from labelforge.catalog.loader import get_label
+from labelforge.render.fonts import get_font_path
+
+logger = logging.getLogger(__name__)
+
+# Horizontal and vertical padding in pixels applied inside the label bounds.
+_PADDING = 20
+
+# form_factor values that represent continuous (endless) media.
+_CONTINUOUS_FORM_FACTORS = {2, 4}  # ENDLESS=2, PTOUCH_ENDLESS=4
+
+
+class RenderError(Exception):
+    pass
+
+
+def render_text(
+    text: str,
+    font_name: str,
+    font_size: int,
+    alignment: str,
+    orientation: str,
+    bold: bool,  # noqa: ARG001 — reserved for future bold-variant font selection
+    italic: bool,  # noqa: ARG001 — reserved for future italic-variant font selection
+    label_media: str,
+) -> Image.Image:
+    """Render *text* onto a white PIL Image sized for *label_media*.
+
+    For continuous media the height expands to fit the text.
+    For die-cut media the height is fixed; raises RenderError if text overflows.
+    """
+    label = get_label(label_media)
+    if label is None:
+        raise RenderError(f"Unknown label media: {label_media}")
+
+    font_path = get_font_path(font_name)
+    if font_path is None:
+        raise RenderError(f"Font not available: {font_name}")
+
+    try:
+        pil_font = ImageFont.truetype(font_path, font_size)
+    except Exception as exc:
+        raise RenderError(f"Could not load font '{font_name}': {exc}") from exc
+
+    width_px = label.dots_printable[0]
+    usable_width = width_px - 2 * _PADDING
+
+    # Measure and wrap using a throw-away draw surface.
+    _probe = ImageDraw.Draw(Image.new("L", (1, 1)))
+    lines = _wrap_text(text, pil_font, usable_width, _probe)
+    line_height = _measure_line_height(pil_font, _probe)
+    total_text_height = len(lines) * line_height
+    total_height = total_text_height + 2 * _PADDING
+
+    is_continuous = label.form_factor in _CONTINUOUS_FORM_FACTORS
+
+    if is_continuous:
+        height_px = max(total_height, 1)
+    else:
+        height_px = label.dots_printable[1]
+        if total_height > height_px:
+            raise RenderError(
+                f"Text exceeds label dimensions at requested font size "
+                f"({total_height}px rendered, {height_px}px available). "
+                "Reduce font size or shorten the text."
+            )
+
+    img = Image.new("L", (width_px, height_px), 255)
+    draw = ImageDraw.Draw(img)
+
+    y = _PADDING
+    for line in lines:
+        bbox = draw.textbbox((0, 0), line, font=pil_font)
+        text_width = bbox[2] - bbox[0]
+
+        if alignment == "center":
+            x = (width_px - text_width) // 2
+        elif alignment == "right":
+            x = width_px - text_width - _PADDING
+        else:
+            x = _PADDING
+
+        draw.text((x, y), line, fill=0, font=pil_font)
+        y += line_height
+
+    if orientation == "rotated":
+        img = img.rotate(90, expand=True)
+
+    return img
+
+
+def _measure_line_height(font: ImageFont.FreeTypeFont, draw: ImageDraw.ImageDraw) -> int:
+    bbox = draw.textbbox((0, 0), "Ag|", font=font)
+    return (bbox[3] - bbox[1]) + 4  # +4px inter-line gap
+
+
+def _wrap_text(
+    text: str,
+    font: ImageFont.FreeTypeFont,
+    max_width: int,
+    draw: ImageDraw.ImageDraw,
+) -> list[str]:
+    """Word-wrap *text* to fit within *max_width* pixels."""
+    output: list[str] = []
+    for paragraph in text.splitlines():
+        if not paragraph.strip():
+            output.append("")
+            continue
+        words = paragraph.split()
+        current = ""
+        for word in words:
+            candidate = f"{current} {word}".strip() if current else word
+            bbox = draw.textbbox((0, 0), candidate, font=font)
+            if bbox[2] - bbox[0] <= max_width:
+                current = candidate
+            else:
+                if current:
+                    output.append(current)
+                current = word
+        if current:
+            output.append(current)
+    return output or [""]
diff --git a/backend/labelforge/routes/__init__.py b/backend/labelforge/routes/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/labelforge/routes/auth.py b/backend/labelforge/routes/auth.py
new file mode 100644
index 0000000..72170f3
--- /dev/null
+++ b/backend/labelforge/routes/auth.py
@@ -0,0 +1,15 @@
+
+from fastapi import Header, HTTPException
+
+from labelforge.config import settings
+
+
+async def require_auth(authorization: str | None = Header(None)) -> None:
+    """FastAPI dependency: enforce Bearer token on all protected routes."""
+    if authorization is None:
+        raise HTTPException(status_code=401, detail="Authorization header required")
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Authorization header must use Bearer scheme")
+    token = authorization[7:]
+    if token != settings.api_token:
+        raise HTTPException(status_code=403, detail="Invalid API token")
diff --git a/backend/labelforge/routes/fonts.py b/backend/labelforge/routes/fonts.py
new file mode 100644
index 0000000..7e2418b
--- /dev/null
+++ b/backend/labelforge/routes/fonts.py
@@ -0,0 +1,15 @@
+from fastapi import APIRouter, Depends
+
+from labelforge.models import FontInfo
+from labelforge.render.fonts import get_fonts
+from labelforge.routes.auth import require_auth
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+@router.get("/fonts", response_model=list[FontInfo])
+async def list_fonts() -> list[FontInfo]:
+    return [
+        FontInfo(name=f.name, path=f.path, family=f.family, style=f.style)
+        for f in get_fonts()
+    ]
diff --git a/backend/labelforge/routes/health.py b/backend/labelforge/routes/health.py
new file mode 100644
index 0000000..5fcfcde
--- /dev/null
+++ b/backend/labelforge/routes/health.py
@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/health")
+async def health() -> dict:
+    return {"status": "ok"}
diff --git a/backend/labelforge/routes/labels.py b/backend/labelforge/routes/labels.py
new file mode 100644
index 0000000..fd7bcf8
--- /dev/null
+++ b/backend/labelforge/routes/labels.py
@@ -0,0 +1,20 @@
+from fastapi import APIRouter, Depends, HTTPException
+
+from labelforge.catalog.loader import get_catalog, get_label
+from labelforge.models import LabelEntry
+from labelforge.routes.auth import require_auth
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+@router.get("/labels", response_model=list[LabelEntry])
+async def list_labels() -> list[LabelEntry]:
+    return list(get_catalog().values())
+
+
+@router.get("/labels/{label_id}", response_model=LabelEntry)
+async def get_label_by_id(label_id: str) -> LabelEntry:
+    entry = get_label(label_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Unknown label media: {label_id}")
+    return entry
diff --git a/backend/labelforge/routes/print.py b/backend/labelforge/routes/print.py
new file mode 100644
index 0000000..e8ca2e7
--- /dev/null
+++ b/backend/labelforge/routes/print.py
@@ -0,0 +1,63 @@
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from labelforge.catalog.loader import get_label
+from labelforge.config import settings
+from labelforge.db import get_connection
+from labelforge.models import PrintJobResponse, QuickPrintRequest
+from labelforge.printer.client import PrintError, print_image
+from labelforge.render.text import RenderError, render_text
+from labelforge.routes.auth import require_auth
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+@router.post("/print/quick", response_model=PrintJobResponse)
+async def quick_print(request: QuickPrintRequest) -> PrintJobResponse:
+    if not request.text.strip():
+        raise HTTPException(status_code=400, detail="Text is required")
+
+    if get_label(request.label_media) is None:
+        raise HTTPException(status_code=400, detail=f"Unknown label media: {request.label_media}")
+
+    try:
+        image = render_text(
+            text=request.text,
+            font_name=request.font,
+            font_size=request.font_size,
+            alignment=request.alignment,
+            orientation=request.orientation,
+            bold=request.bold,
+            italic=request.italic,
+            label_media=request.label_media,
+        )
+    except RenderError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    try:
+        outcome = print_image(
+            image=image,
+            label_media=request.label_media,
+            model=settings.printer_model,
+            backend=settings.printer_backend,
+            host=settings.printer_host,
+        )
+    except PrintError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    db_path = settings.data_dir / "data" / "app.db"
+    conn = get_connection(db_path)
+    try:
+        cursor = conn.execute(
+            "INSERT INTO print_jobs (payload_json, label_media) VALUES (?, ?)",
+            (request.model_dump_json(), request.label_media),
+        )
+        conn.commit()
+        job_id = cursor.lastrowid
+    finally:
+        conn.close()
+
+    return PrintJobResponse(job_id=job_id, status=outcome)
diff --git a/compose.dev.yml b/compose.dev.yml
new file mode 100644
index 0000000..508d22d
--- /dev/null
+++ b/compose.dev.yml
@@ -0,0 +1,29 @@
+name: labelforge-dev
+
+services:
+  labelforge:
+    build: .
+    image: labelforge:dev
+    restart: "no"
+    env_file: .env
+    environment:
+      LOG_LEVEL: DEBUG
+    volumes:
+      # Bind-mount source for hot-reload.  The editable pip install inside the
+      # image points to /app/backend/labelforge/, so this overlay takes effect
+      # immediately without rebuilding.
+      - ./backend:/app/backend
+      # Dev data directory — kept separate from any production volume.
+      - ./data:/data
+    ports:
+      - "8001:8000"
+    command:
+      - uvicorn
+      - labelforge.main:app
+      - --host
+      - "0.0.0.0"
+      - --port
+      - "8000"
+      - --reload
+      - --reload-dir
+      - /app/backend
diff --git a/compose.yml b/compose.yml
new file mode 100644
index 0000000..640d808
--- /dev/null
+++ b/compose.yml
@@ -0,0 +1,31 @@
+name: labelforge
+
+services:
+  labelforge:
+    build: .
+    image: labelforge:latest
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - /var/docker/labelforge:/var/docker/labelforge
+    networks:
+      - traefik
+      - dockflare
+    labels:
+      # ── Traefik (LAN — labels.home.arpa via internal Traefik instance) ────
+      traefik.enable: "true"
+      traefik.http.routers.labelforge-lan.rule: "Host(`labels.home.arpa`)"
+      traefik.http.routers.labelforge-lan.entrypoints: "web"
+      traefik.http.services.labelforge.loadbalancer.server.port: "8000"
+
+      # ── Dockflare (Cloudflare Tunnel — labels.crzynet.com) ───────────────
+      # Adjust label keys to match your Dockflare version / configuration.
+      dockflare.enable: "true"
+      dockflare.hostname: "labels.crzynet.com"
+      dockflare.service: "http://labelforge:8000"
+
+networks:
+  traefik:
+    external: true
+  dockflare:
+    external: true
diff --git a/labels.yml b/labels.yml
new file mode 100644
index 0000000..6f8ae30
--- /dev/null
+++ b/labels.yml
@@ -0,0 +1,125 @@
+# labelforge default label catalog
+# Maps brother_ql library identifiers to user-friendly metadata.
+# Required fields: id, display_name
+# All other fields are optional. Unknown fields are ignored.
+# Reload: restart the app or POST /api/admin/reload-catalog (future slice).
+
+labels:
+
+  # ── Continuous (mono) ─────────────────────────────────────────────────────
+
+  - id: "12"
+    display_name: "12mm Continuous"
+    description: "Narrow continuous tape, black on white."
+    category: continuous
+    color_capable: false
+
+  - id: "29"
+    display_name: "29mm Continuous"
+    description: "Medium-width continuous tape, black on white."
+    category: continuous
+    color_capable: false
+
+  - id: "38"
+    display_name: "38mm Continuous"
+    description: "Wide continuous tape, black on white."
+    category: continuous
+    color_capable: false
+
+  - id: "50"
+    display_name: "50mm Continuous"
+    description: "50mm continuous tape, black on white."
+    category: continuous
+    color_capable: false
+
+  - id: "54"
+    display_name: "54mm Continuous"
+    description: "54mm continuous tape, black on white."
+    category: continuous
+    color_capable: false
+
+  - id: "62"
+    display_name: "62mm Continuous (Black)"
+    brother_part: "DK-22205"
+    description: "General-purpose paper tape, black on white."
+    category: continuous
+    color_capable: false
+    common_use:
+      - "address labels"
+      - "file folders"
+      - "spool labels"
+
+  # ── Continuous (two-color) ────────────────────────────────────────────────
+
+  - id: "62red"
+    display_name: "62mm Continuous (Black + Red)"
+    brother_part: "DK-22251"
+    description: "Two-color paper tape. Requires QL-800 series printer."
+    category: continuous
+    color_capable: true
+    printer_requirements:
+      - "QL-800"
+      - "QL-810W"
+      - "QL-820NWB"
+
+  # ── Die-cut ───────────────────────────────────────────────────────────────
+
+  - id: "17x54"
+    display_name: "17mm × 54mm Die-cut"
+    description: "Small die-cut label."
+    category: die-cut
+    color_capable: false
+
+  - id: "17x87"
+    display_name: "17mm × 87mm Die-cut"
+    description: "Small elongated die-cut label."
+    category: die-cut
+    color_capable: false
+
+  - id: "29x90"
+    display_name: "29mm × 90mm Address Label"
+    brother_part: "DK-11201"
+    description: "Standard address label, die-cut."
+    category: die-cut
+    color_capable: false
+    common_use:
+      - "address"
+      - "file folder"
+      - "spool"
+
+  - id: "38x90"
+    display_name: "38mm × 90mm Die-cut"
+    description: "Medium die-cut label."
+    category: die-cut
+    color_capable: false
+
+  - id: "52x29"
+    display_name: "52mm × 29mm Die-cut"
+    description: "Wide short die-cut label."
+    category: die-cut
+    color_capable: false
+
+  - id: "62x29"
+    display_name: "62mm × 29mm Die-cut"
+    description: "Wide short die-cut label."
+    category: die-cut
+    color_capable: false
+
+  - id: "62x100"
+    display_name: "62mm × 100mm Shipping Label"
+    brother_part: "DK-11202"
+    description: "Larger die-cut, good for shipping or product labels."
+    category: die-cut
+    color_capable: false
+    common_use:
+      - "shipping"
+      - "product"
+
+  # ── Round ─────────────────────────────────────────────────────────────────
+
+  - id: "d24"
+    display_name: "24mm Round"
+    brother_part: "DK-11218"
+    description: "Round die-cut, 24mm diameter."
+    category: round
+    color_capable: false

From 40272353fc89021d374e4debaba8f2ac1f1c342c Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:17:50 -0700
Subject: [PATCH 03/84] Document printer setup and slice 1 decisions

---
 .gitignore        |  2 ++
 CHANGELOG.md      | 25 +++++++++++++++++++++++--
 README.md         | 35 +++++++++++++++++++++++++++++++++++
 docs/decisions.md | 24 ++++++++++++++++++++++++
 4 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 8fbf412..1588431 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,6 +41,7 @@ Thumbs.db
 
 # Runtime data (should never be committed)
 data/
+data-dev/
 *.db
 *.db-journal
 *.sqlite
@@ -66,3 +67,4 @@ logs/
 .coverage
 htmlcov/
 coverage.xml
+test-print.json
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 151c480..11dc144 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,14 +9,35 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 - PRD covering quick-print, templates, label catalog, history, HTTP API, printer status, and settings
 - Architecture doc locking stack: FastAPI + SQLite + brother-ql-inventree + Vite/TS + Fabric.js
 - Glossary defining vocabulary
-- ADR log with 6 decisions recorded (library choice, license, name, storage, frontend, label catalog model, auth)
+- ADR log (library choice, license, name, storage, frontend, label catalog model, auth, print-outcome reporting, convert rotation)
 - CLAUDE.md for AI session context
 - GPL-3.0 LICENSE
 - .gitattributes enforcing LF line endings
 - .gitignore for Python + Node + IDE artifacts
+- **Slice 1 backend skeleton** — FastAPI app with lifespan startup (DB init, catalog load, font scan)
+- `GET /api/health` — unauthenticated liveness probe
+- `GET /api/labels`, `GET /api/labels/{id}` — merged label catalog (library truth + labels.yml metadata)
+- `GET /api/fonts` — discovered font list (system fonts + user fonts at `${DATA_DIR}/fonts/`)
+- `POST /api/print/quick` — render text with Pillow, print via brother-ql-inventree, log to history
+- Bearer-token auth on all `/api/*` routes except `/api/health`; app refuses to start without `API_TOKEN`
+- SQLite schema (`print_jobs`, `settings`) created on startup via raw sqlite3
+- Default `labels.yml` catalog (15 DK media entries: continuous, die-cut, round)
+- Dockerfile (single-stage python:3.12-slim; bundled fonts: dejavu-core, liberation2, noto-core; multi-stage frontend build deferred)
+- `compose.yml` (production: Traefik + Dockflare networks) and `compose.dev.yml` (hot-reload via bind-mount + uvicorn --reload, published on host port 8001)
+- `.env.example` documenting all env vars
+- README: required printer setup (Command Mode → Raster, Template Mode → Off, Unit → mm) and `wrong roll type` troubleshooting
+
+### Changed
+- `convert()` called with explicit `rotate="0"` instead of the library default `auto` (see ADR 2026-05-20)
+
+### Fixed
+- Dockerfile: copy `README.md` before `pip install -e .` (hatchling validates the readme path; build failed without it)
+- `compose.dev.yml`: removed `DATA_DIR=/data/` override that did not match the bind-mount path, breaking startup catalog/DB load
+- `.gitignore`: ignore `data-dev/` and the `test-print.json` scratch file
+- Print API now reports the true send outcome (`sent` for the network backend) instead of always claiming `printed` (see ADR 2026-05-20)
 
 ### Status
-- No code yet. Design phase complete. Next: backend skeleton + first end-to-end print path (slice 1).
+- Slice 1 verified end-to-end: a real label printed on the QL-820NWB (DK-1209 die-cut, `62x29`). The render → convert → network-send path is confirmed working. Deferred to later slices: templates, canvas editor, history UI, printer-status query, settings UI, batch/increment, frontend.
 
 ---
 
diff --git a/README.md b/README.md
index 64affc5..fda8fbd 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,41 @@ Self-hosted web app for designing, saving, and printing labels to Brother QL ser
 - Print history with reprint and pinning
 - Freeform canvas editor (text, QR codes, barcodes, images, shapes)
 
+## Printer setup (required)
+
+The app talks to the printer in **raster** mode over TCP. A factory or
+previously-used Brother QL-820NWB often ships configured for standalone
+template printing, which will reject raster jobs with a misleading
+`wrong roll type` error. Set these on the printer's LCD before first use:
+
+- **Command Mode → Raster.** Menu → (Template/Command settings) → Command
+  Mode → Raster. If it is set to `P-touch Template` or `ESC/P`, raster jobs
+  fail. This is the single most common cause of prints not appearing.
+- **Template Mode → Off.** Menu → Template Settings → Template Mode → Off.
+  A saved template size overrides DK roll auto-detection and forces a fixed
+  label size, causing `wrong roll type` on a non-matching roll.
+- **Unit → mm.** Menu → Settings → Unit → mm. Cosmetic, but keeps the panel
+  readout consistent with the catalog.
+
+After changing Command Mode, reseat the DK roll (remove it, close the cover
+empty so the printer reports no media, then reload) so media auto-detection
+re-runs.
+
+### Troubleshooting `wrong roll type`
+
+If a job is rejected as `wrong roll type` even with the settings above:
+
+- **Worn or sample rolls.** Detection depends on the plastic tabs on the
+  roll's spool end-caps pressing micro-switches in the bay. Worn rolls (e.g.
+  the bundled SAMPLE roll) can fail to be sensed and get rejected. Test with
+  a standard DK roll that has intact end-caps.
+- **Media mismatch.** The `label_media` in the request must match the roll
+  physically loaded. The printer rejects a job whose declared media does not
+  match what it senses.
+- The network backend cannot read printer status back, so a failed print may
+  still return HTTP 200 with `status: "sent"` — `sent` means *transmitted*,
+  not *confirmed printed*. Watch the physical printer.
+
 ## Design docs
 
 See [`docs/PRD.md`](docs/PRD.md) for scope, then [`docs/features/`](docs/features/) for per-feature designs.
diff --git a/docs/decisions.md b/docs/decisions.md
index d658afe..ab741b7 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,30 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-20 — Print API reports `sent`, not `printed`, on the network backend
+
+**Decision**: `POST /api/print/*` returns the print outcome verbatim from the brother_ql backend. For the network (TCP) backend this is `sent`, meaning the raster was transmitted but the result is unconfirmed. Only backends that can read printer status back (USB) return `printed`. The API never claims `printed` for a network send.
+
+**Why**: The brother_ql network backend writes raster bytes and returns immediately — the QL-820NWB does not support status read-back over TCP, so the library cannot know whether a label actually printed. Reporting `printed` would be a lie that misleads API consumers (e.g. Home Assistant) into trusting a success that may not have happened. `sent` accurately means "transmitted, outcome unknown."
+
+**Considered**:
+- Always report `printed` on a successful send (rejected — false positive; hides real failures like a rejected roll)
+- Add a follow-up status query after sending (rejected for v1 — the network backend doesn't reliably answer status requests; revisit with printer-status feature)
+
+**Would revisit if**: the printer-status feature lands and we can poll for completion, or we add a USB backend path that confirms prints.
+
+---
+
+## 2026-05-20 — brother_ql `convert()` called with explicit `rotate="0"`
+
+**Decision**: `printer/client.py` passes `rotate="0"` to `brother_ql.conversion.convert()` rather than relying on the library default of `rotate="auto"`. The renderer (`render/text.py`) produces images already in the correct orientation for the print head.
+
+**Why**: `auto` rotation can flip a wide continuous image into a geometry that misrepresents the label width. Keeping `rotate="0"` makes the rendered image's pixel width (e.g. 696px for 62mm) the print-head width directly, matching what the renderer intends. Verified that for the current render path both produce identical rasters, but explicit-zero removes ambiguity if the renderer's output dimensions change.
+
+**Would revisit if**: a future render path produces images in the feed-direction orientation, at which point rotation handling moves into the renderer or this flag changes accordingly.
+
+---
+
 ## 2026-05-19 — Use `brother-ql-inventree` as the printer library
 
 **Decision**: Take `brother-ql-inventree` (PyPI) as the printer protocol library. Pin as a normal dependency, do not fork.

From 5da9aba466b307e87c254974d41aed73d28a8f14 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:20:50 -0700
Subject: [PATCH 04/84] updates

---
 .claude/CLAUDE.md           | 60 -------------------------------------
 .claude/hooks/vexp-guard.sh | 14 ---------
 .claude/settings.json       | 16 ----------
 .claude/settings.local.json |  7 -----
 4 files changed, 97 deletions(-)
 delete mode 100644 .claude/CLAUDE.md
 delete mode 100644 .claude/hooks/vexp-guard.sh
 delete mode 100644 .claude/settings.json
 delete mode 100644 .claude/settings.local.json

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
deleted file mode 100644
index 09b4011..0000000
--- a/.claude/CLAUDE.md
+++ /dev/null
@@ -1,60 +0,0 @@
-## vexp — Context-Aware AI Coding <!-- vexp v2.0.17 -->
-
-### MANDATORY: use vexp pipeline — do NOT grep or glob the codebase
-For every task — bug fixes, features, refactors, debugging:
-**call `run_pipeline` FIRST**. It executes context search + impact analysis +
-memory recall in a single call, returning compressed results.
-
-Do NOT use grep, glob, Bash, or cat to search/explore the codebase.
-vexp returns pre-indexed, graph-ranked context that is more relevant and
-uses fewer tokens than manual searching. Prefer `get_skeleton` over Read to
-inspect files (detail: minimal/standard/detailed, 70-90% token savings).
-Only use Read when you need exact raw content to edit a specific line.
-
-### Primary Tool
-- `run_pipeline` — **USE THIS FOR EVERYTHING**. Single call that runs
-  capsule + impact + memory server-side. Returns compressed results.
-  Auto-detects intent (debug/modify/refactor/explore) from your task.
-  Includes full file content for pivots.
-  Examples:
-  - `run_pipeline({ "task": "fix JWT validation bug" })` — auto-detect
-  - `run_pipeline({ "task": "refactor db layer", "preset": "refactor" })` — explicit
-  - `run_pipeline({ "task": "add auth", "observation": "using JWT" })` — save insight in same call
-
-### Other MCP tools (use only when run_pipeline is insufficient)
-- `get_skeleton` — **preferred over Read** for inspecting files (minimal/standard/detailed detail levels, 70-90% token savings)
-- `index_status` — indexing status and health check
-- `expand_vexp_ref` — expand V-REF hash placeholders in v2 compact output
-
-### Workflow
-1. `run_pipeline("your task")` — ALWAYS FIRST. Returns pivots + impact + memories in 1 call
-2. Need more detail on a file? Use `get_skeleton({ files: [...], detail: "detailed" })` — avoid Read unless editing
-3. Make targeted changes based on the context returned
-4. `run_pipeline` again ONLY if you need more context during implementation
-5. Do NOT chain multiple vexp calls — one `run_pipeline` replaces capsule + impact + memory + observation
-
-### Subagent / Explore / Plan mode
-- Subagents CAN and MUST call `run_pipeline` — always include the task description
-- The PreToolUse hook blocks Grep/Glob when vexp daemon is running
-- Do NOT spawn Agent(Explore) to freely search — call `run_pipeline` first,
-  then pass the returned context into the agent prompt if needed
-- Always: `run_pipeline` → get context → spawn agent with context
-
-### Smart Features (automatic — no action needed)
-- **Intent Detection**: auto-detects from your task keywords. "fix bug" → Debug, "refactor" → blast-radius, "add" → Modify
-- **Hybrid Search**: keyword + semantic + graph centrality ranking
-- **Session Memory**: auto-captures observations; memories auto-surfaced in results
-- **LSP Bridge**: VS Code captures type-resolved call edges
-- **Change Coupling**: co-changed files included as related context
-
-### Advanced Parameters
-- `preset: "debug"` — forces debug mode (capsule+tests+impact+memory)
-- `preset: "refactor"` — deep impact analysis (depth 5)
-- `max_tokens: 12000` — increase total budget for complex tasks
-- `include_tests: true` — include test files in results
-- `include_file_content: false` — omit full file content (lighter response)
-
-### Multi-Repo Workspaces
-`run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope.
-Use `index_status` to discover available repo aliases.
-<!-- /vexp -->
\ No newline at end of file
diff --git a/.claude/hooks/vexp-guard.sh b/.claude/hooks/vexp-guard.sh
deleted file mode 100644
index 9cefc1d..0000000
--- a/.claude/hooks/vexp-guard.sh
+++ /dev/null
@@ -1,14 +0,0 @@
-#!/bin/bash
-# vexp-guard: block Grep/Glob when vexp daemon is running AND index is healthy.
-# Fast path: if socket file or healthy marker doesn't exist, allow immediately.
-# PID check: verify daemon process is alive (handles stale files after kill -9).
-VEXP_DIR="${CLAUDE_PROJECT_DIR:-.}/.vexp"
-SOCK="$VEXP_DIR/daemon.sock"
-HEALTHY="$VEXP_DIR/healthy"
-PID_FILE="$VEXP_DIR/daemon.pid"
-if [ -S "$SOCK" ] && [ -f "$HEALTHY" ] && [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE" 2>/dev/null)" 2>/dev/null; then
-  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"vexp daemon is running. Use run_pipeline instead of Grep/Glob."}}'
-else
-  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"vexp index not ready, allowing direct search fallback."}}'
-fi
-exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
deleted file mode 100644
index 3883ca6..0000000
--- a/.claude/settings.json
+++ /dev/null
@@ -1,16 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Grep|Glob|Regex",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh",
-            "timeout": 3000
-          }
-        ]
-      }
-    ]
-  }
-}
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
deleted file mode 100644
index 7cb5ff9..0000000
--- a/.claude/settings.local.json
+++ /dev/null
@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git push *)"
-    ]
-  }
-}

From 28a277c8d80ab7fb2405400932925b9eca4f6e23 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:20:59 -0700
Subject: [PATCH 05/84] update

---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index 1588431..ac33dab 100644
--- a/.gitignore
+++ b/.gitignore
@@ -63,6 +63,9 @@ logs/
 .vexp/daemon.pipe
 .vexp/vexp.log
 
+# claude 
+.claude/
+
 # Test artifacts
 .coverage
 htmlcov/

From 81443d14a07a982c4b37f941b34fb26f93da8fd0 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:46:43 -0700
Subject: [PATCH 06/84] Add quick-print frontend scaffold (Vite + vanilla TS)

---
 CHANGELOG.md                      |   1 +
 frontend/index.html               |  12 ++
 frontend/package.json             |  14 ++
 frontend/src/api.ts               |  42 +++++
 frontend/src/main.ts              |   4 +
 frontend/src/pages/quick-print.ts | 249 ++++++++++++++++++++++++++++++
 frontend/src/style.css            | 130 ++++++++++++++++
 frontend/src/types.ts             |  39 +++++
 frontend/tsconfig.json            |  13 ++
 frontend/vite.config.ts           |   9 ++
 10 files changed, 513 insertions(+)
 create mode 100644 frontend/index.html
 create mode 100644 frontend/package.json
 create mode 100644 frontend/src/api.ts
 create mode 100644 frontend/src/main.ts
 create mode 100644 frontend/src/pages/quick-print.ts
 create mode 100644 frontend/src/style.css
 create mode 100644 frontend/src/types.ts
 create mode 100644 frontend/tsconfig.json
 create mode 100644 frontend/vite.config.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 11dc144..885dbf4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 - GPL-3.0 LICENSE
 - .gitattributes enforcing LF line endings
 - .gitignore for Python + Node + IDE artifacts
+- **Slice 2 frontend skeleton** — Vite + TypeScript quick-print SPA: token gate, label/font selectors (grouped by form factor), font size, bold/italic, alignment, orientation, print via `POST /api/print/quick`, localStorage pref persistence; Preview button present but disabled pending backend endpoint
 - **Slice 1 backend skeleton** — FastAPI app with lifespan startup (DB init, catalog load, font scan)
 - `GET /api/health` — unauthenticated liveness probe
 - `GET /api/labels`, `GET /api/labels/{id}` — merged label catalog (library truth + labels.yml metadata)
diff --git a/frontend/index.html b/frontend/index.html
new file mode 100644
index 0000000..7b26961
--- /dev/null
+++ b/frontend/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>LabelForge</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/frontend/package.json b/frontend/package.json
new file mode 100644
index 0000000..ce02cf0
--- /dev/null
+++ b/frontend/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "labelforge-frontend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vite": "^6.3.5"
+  }
+}
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
new file mode 100644
index 0000000..a37a70d
--- /dev/null
+++ b/frontend/src/api.ts
@@ -0,0 +1,42 @@
+import type { FontInfo, LabelEntry, PrintJobResponse, QuickPrintRequest } from './types'
+
+export const TOKEN_KEY = 'labelforge_token'
+
+function getToken(): string {
+  return localStorage.getItem(TOKEN_KEY) ?? ''
+}
+
+async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
+  const res = await fetch(path, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${getToken()}`,
+      ...(options.headers as Record<string, string>),
+    },
+  })
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`
+    try {
+      const body = await res.json() as { detail?: unknown }
+      if (body.detail) detail = String(body.detail)
+    } catch { /* use status fallback */ }
+    throw new Error(detail)
+  }
+  return res.json() as Promise<T>
+}
+
+export function getLabels(): Promise<LabelEntry[]> {
+  return apiFetch<LabelEntry[]>('/api/labels')
+}
+
+export function getFonts(): Promise<FontInfo[]> {
+  return apiFetch<FontInfo[]>('/api/fonts')
+}
+
+export function quickPrint(req: QuickPrintRequest): Promise<PrintJobResponse> {
+  return apiFetch<PrintJobResponse>('/api/print/quick', {
+    method: 'POST',
+    body: JSON.stringify(req),
+  })
+}
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
new file mode 100644
index 0000000..b3b3711
--- /dev/null
+++ b/frontend/src/main.ts
@@ -0,0 +1,4 @@
+import './style.css'
+import { mountQuickPrint } from './pages/quick-print'
+
+mountQuickPrint(document.getElementById('app')!)
diff --git a/frontend/src/pages/quick-print.ts b/frontend/src/pages/quick-print.ts
new file mode 100644
index 0000000..0e27d81
--- /dev/null
+++ b/frontend/src/pages/quick-print.ts
@@ -0,0 +1,249 @@
+import { getFonts, getLabels, quickPrint, TOKEN_KEY } from '../api'
+import type { LabelEntry, QuickPrintRequest } from '../types'
+
+// localStorage is the v1 stand-in for saved settings; replace when GET/PUT /api/settings exists
+const PREF = {
+  font: 'labelforge_font',
+  font_size: 'labelforge_font_size',
+  label_media: 'labelforge_label_media',
+  alignment: 'labelforge_alignment',
+  orientation: 'labelforge_orientation',
+}
+
+const FORM_FACTOR_LABEL: Record<number, string> = {
+  1: 'Die-cut',
+  2: 'Continuous',
+  3: 'Round',
+  4: 'P-touch Continuous',
+}
+
+// Render order for form-factor groups
+const FF_ORDER = [2, 1, 3, 4]
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+export function mountQuickPrint(root: HTMLElement): void {
+  if (!localStorage.getItem(TOKEN_KEY)) {
+    renderTokenGate(root)
+  } else {
+    renderForm(root)
+  }
+}
+
+function renderTokenGate(root: HTMLElement): void {
+  root.innerHTML = `
+    <div class="token-gate">
+      <h2>LabelForge</h2>
+      <p>Enter your API token to continue.</p>
+      <input id="token-input" type="password" placeholder="API token" autocomplete="current-password" />
+      <button id="token-save">Save token</button>
+    </div>
+  `
+  const input = root.querySelector<HTMLInputElement>('#token-input')!
+  const btn = root.querySelector<HTMLButtonElement>('#token-save')!
+
+  function save(): void {
+    const val = input.value.trim()
+    if (!val) return
+    localStorage.setItem(TOKEN_KEY, val)
+    renderForm(root)
+  }
+
+  btn.addEventListener('click', save)
+  input.addEventListener('keydown', (e) => { if (e.key === 'Enter') save() })
+}
+
+function renderForm(root: HTMLElement): void {
+  root.innerHTML = `
+    <div class="quick-print">
+      <h2>Quick Print</h2>
+      <div id="status-msg" class="status-msg" hidden></div>
+      <form id="print-form" autocomplete="off">
+        <div>
+          <label for="text">Text</label>
+          <textarea id="text" rows="4" required></textarea>
+        </div>
+
+        <div>
+          <label for="font">Font</label>
+          <select id="font"><option value="">Loading…</option></select>
+        </div>
+
+        <div>
+          <label for="font-size">Font size</label>
+          <input id="font-size" type="number" min="6" max="200" value="48" />
+        </div>
+
+        <div>
+          <label for="label-media">Label media</label>
+          <select id="label-media"><option value="">Loading…</option></select>
+        </div>
+
+        <div>
+          <label>Style</label>
+          <div class="checkboxes">
+            <label><input id="bold" type="checkbox" /> Bold</label>
+            <label><input id="italic" type="checkbox" /> Italic</label>
+          </div>
+        </div>
+
+        <div>
+          <label>Alignment</label>
+          <div class="radio-group">
+            <label><input type="radio" name="alignment" value="left" checked /> Left</label>
+            <label><input type="radio" name="alignment" value="center" /> Center</label>
+            <label><input type="radio" name="alignment" value="right" /> Right</label>
+          </div>
+        </div>
+
+        <div>
+          <label>Orientation</label>
+          <div class="radio-group">
+            <label><input type="radio" name="orientation" value="standard" checked /> Standard</label>
+            <label><input type="radio" name="orientation" value="rotated" /> Rotated</label>
+          </div>
+        </div>
+
+        <div class="actions">
+          <button type="button" id="btn-preview" disabled title="Preview endpoint not yet implemented">Preview</button>
+          <button type="submit" id="btn-print" disabled>Print</button>
+        </div>
+      </form>
+    </div>
+  `
+
+  const form = root.querySelector<HTMLFormElement>('#print-form')!
+  const textarea = root.querySelector<HTMLTextAreaElement>('#text')!
+  const fontSelect = root.querySelector<HTMLSelectElement>('#font')!
+  const fontSizeInput = root.querySelector<HTMLInputElement>('#font-size')!
+  const labelSelect = root.querySelector<HTMLSelectElement>('#label-media')!
+  const boldCheck = root.querySelector<HTMLInputElement>('#bold')!
+  const italicCheck = root.querySelector<HTMLInputElement>('#italic')!
+  const btnPrint = root.querySelector<HTMLButtonElement>('#btn-print')!
+  const statusMsg = root.querySelector<HTMLDivElement>('#status-msg')!
+
+  function showStatus(msg: string, kind: 'success' | 'error'): void {
+    statusMsg.textContent = msg
+    statusMsg.className = `status-msg ${kind}`
+    statusMsg.hidden = false
+  }
+
+  function hideStatus(): void {
+    statusMsg.hidden = true
+  }
+
+  function updatePrintButton(): void {
+    btnPrint.disabled = textarea.value.trim() === ''
+  }
+
+  textarea.addEventListener('input', updatePrintButton)
+
+  Promise.all([getFonts(), getLabels()]).then(([fonts, labels]) => {
+    // Populate fonts
+    fontSelect.innerHTML = fonts
+      .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
+      .join('')
+    const savedFont = localStorage.getItem(PREF.font)
+    if (savedFont) fontSelect.value = savedFont
+
+    // Group labels by form_factor, sort within groups by display_name
+    const groups = new Map<number, LabelEntry[]>()
+    for (const label of labels) {
+      const ff = label.form_factor
+      if (!groups.has(ff)) groups.set(ff, [])
+      groups.get(ff)!.push(label)
+    }
+    for (const entries of groups.values()) {
+      entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
+    }
+
+    // Render known order first, then any remaining form_factor values
+    const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
+    labelSelect.innerHTML = allKeys
+      .filter(k => groups.has(k))
+      .map(k => {
+        const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
+        const opts = groups
+          .get(k)!
+          .map(l => `<option value="${esc(l.id)}">${esc(l.display_name)}</option>`)
+          .join('')
+        return `<optgroup label="${esc(groupLabel)}">${opts}</optgroup>`
+      })
+      .join('')
+
+    const savedLabel = localStorage.getItem(PREF.label_media)
+    if (savedLabel) labelSelect.value = savedLabel
+
+    // Restore remaining prefs
+    const savedSize = localStorage.getItem(PREF.font_size)
+    if (savedSize) fontSizeInput.value = savedSize
+
+    const savedAlignment = localStorage.getItem(PREF.alignment)
+    if (savedAlignment) {
+      const radio = form.querySelector<HTMLInputElement>(
+        `input[name="alignment"][value="${savedAlignment}"]`
+      )
+      if (radio) radio.checked = true
+    }
+
+    const savedOrientation = localStorage.getItem(PREF.orientation)
+    if (savedOrientation) {
+      const radio = form.querySelector<HTMLInputElement>(
+        `input[name="orientation"][value="${savedOrientation}"]`
+      )
+      if (radio) radio.checked = true
+    }
+  }).catch((err: Error) => {
+    showStatus(`Failed to load form data: ${err.message}`, 'error')
+  })
+
+  form.addEventListener('submit', async (e) => {
+    e.preventDefault()
+    btnPrint.disabled = true
+    hideStatus()
+
+    const alignment = (
+      form.querySelector<HTMLInputElement>('input[name="alignment"]:checked')?.value ?? 'left'
+    ) as QuickPrintRequest['alignment']
+
+    const orientation = (
+      form.querySelector<HTMLInputElement>('input[name="orientation"]:checked')?.value ?? 'standard'
+    ) as QuickPrintRequest['orientation']
+
+    const req: QuickPrintRequest = {
+      text: textarea.value,
+      font: fontSelect.value,
+      font_size: parseInt(fontSizeInput.value, 10),
+      alignment,
+      orientation,
+      label_media: labelSelect.value,
+      bold: boldCheck.checked,
+      italic: italicCheck.checked,
+    }
+
+    localStorage.setItem(PREF.font, req.font)
+    localStorage.setItem(PREF.font_size, String(req.font_size))
+    localStorage.setItem(PREF.label_media, req.label_media)
+    localStorage.setItem(PREF.alignment, req.alignment)
+    localStorage.setItem(PREF.orientation, req.orientation)
+
+    try {
+      const result = await quickPrint(req)
+      // "sent" = transmitted to printer network backend, not confirmed printed
+      showStatus(
+        `Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`,
+        'success'
+      )
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+    } finally {
+      updatePrintButton()
+    }
+  })
+}
diff --git a/frontend/src/style.css b/frontend/src/style.css
new file mode 100644
index 0000000..1668a0c
--- /dev/null
+++ b/frontend/src/style.css
@@ -0,0 +1,130 @@
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+body {
+  font-family: system-ui, sans-serif;
+  background: #f5f5f5;
+  margin: 0;
+  padding: 1rem;
+  color: #1a1a1a;
+}
+
+#app {
+  max-width: 520px;
+  margin: 0 auto;
+}
+
+h2 {
+  margin: 0 0 1.25rem;
+}
+
+.token-gate,
+.quick-print {
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 1.5rem;
+}
+
+form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+label {
+  display: block;
+  font-weight: 600;
+  font-size: 0.875rem;
+  margin-bottom: 0.25rem;
+}
+
+textarea,
+input[type="number"],
+select {
+  width: 100%;
+  padding: 0.4rem 0.5rem;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  font: inherit;
+  font-size: 0.9rem;
+}
+
+textarea {
+  resize: vertical;
+}
+
+.checkboxes,
+.radio-group {
+  display: flex;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.checkboxes label,
+.radio-group label {
+  font-weight: normal;
+  display: flex;
+  align-items: center;
+  gap: 0.3rem;
+  cursor: pointer;
+}
+
+.actions {
+  display: flex;
+  gap: 0.75rem;
+  margin-top: 0.5rem;
+}
+
+button {
+  padding: 0.45rem 1.1rem;
+  border: 1px solid #999;
+  border-radius: 4px;
+  background: #fff;
+  font: inherit;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+
+button[type="submit"] {
+  background: #1a6fdb;
+  color: #fff;
+  border-color: #1a6fdb;
+  font-weight: 600;
+}
+
+button[type="submit"]:disabled,
+button:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.status-msg {
+  padding: 0.6rem 0.8rem;
+  border-radius: 4px;
+  font-size: 0.875rem;
+  margin-bottom: 0.75rem;
+}
+
+.status-msg.success {
+  background: #e6f4ea;
+  border: 1px solid #a8d5b5;
+  color: #1a5c2a;
+}
+
+.status-msg.error {
+  background: #fdecea;
+  border: 1px solid #f5b8b4;
+  color: #7a1a14;
+}
+
+/* token gate */
+.token-gate input[type="password"] {
+  width: 100%;
+  padding: 0.4rem 0.5rem;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  font: inherit;
+  margin-bottom: 0.5rem;
+}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
new file mode 100644
index 0000000..3c3ebac
--- /dev/null
+++ b/frontend/src/types.ts
@@ -0,0 +1,39 @@
+export interface LabelEntry {
+  id: string;
+  display_name: string;
+  brother_part: string | null;
+  description: string | null;
+  category: string | null;
+  color_capable: boolean;
+  printer_requirements: string[];
+  common_use: string[];
+  preview_image: string | null;
+  dots_printable: [number, number];
+  tape_size: [number, number];
+  // 1=die-cut, 2=continuous, 3=round, 4=ptouch-continuous
+  form_factor: number;
+}
+
+export interface FontInfo {
+  name: string;
+  path: string;
+  family: string;
+  style: string;
+}
+
+export interface QuickPrintRequest {
+  text: string;
+  font: string;
+  font_size: number;
+  alignment: 'left' | 'center' | 'right';
+  orientation: 'standard' | 'rotated';
+  label_media: string;
+  bold: boolean;
+  italic: boolean;
+}
+
+export interface PrintJobResponse {
+  job_id: number;
+  status: string;
+  preview_url: string | null;
+}
diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json
new file mode 100644
index 0000000..1ca183c
--- /dev/null
+++ b/frontend/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
new file mode 100644
index 0000000..30211ee
--- /dev/null
+++ b/frontend/vite.config.ts
@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': 'http://localhost:8001',
+    },
+  },
+})

From 889c712d3ba6b38dd692ba14def0c4548e907b10 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:54:06 -0700
Subject: [PATCH 07/84] Add quick-print preview endpoint

---
 backend/labelforge/main.py           |  2 ++
 backend/labelforge/routes/preview.py | 41 ++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+)
 create mode 100644 backend/labelforge/routes/preview.py

diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index d72ceca..bb377e7 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -11,6 +11,7 @@
 from labelforge.render.fonts import load_fonts
 from labelforge.routes import fonts, health, labels
 from labelforge.routes import print as print_router
+from labelforge.routes import preview as preview_router
 
 
 @asynccontextmanager
@@ -59,3 +60,4 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
 app.include_router(labels.router, prefix="/api")
 app.include_router(fonts.router, prefix="/api")
 app.include_router(print_router.router, prefix="/api")
+app.include_router(preview_router.router, prefix="/api")
diff --git a/backend/labelforge/routes/preview.py b/backend/labelforge/routes/preview.py
new file mode 100644
index 0000000..7286ad5
--- /dev/null
+++ b/backend/labelforge/routes/preview.py
@@ -0,0 +1,41 @@
+import io
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+
+from labelforge.catalog.loader import get_label
+from labelforge.models import QuickPrintRequest
+from labelforge.render.text import RenderError, render_text
+from labelforge.routes.auth import require_auth
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+@router.post("/preview/quick")
+async def preview_quick(request: QuickPrintRequest) -> Response:
+    if not request.text.strip():
+        raise HTTPException(status_code=400, detail="Text is required")
+
+    if get_label(request.label_media) is None:
+        raise HTTPException(status_code=400, detail=f"Unknown label media: {request.label_media}")
+
+    try:
+        image = render_text(
+            text=request.text,
+            font_name=request.font,
+            font_size=request.font_size,
+            alignment=request.alignment,
+            orientation=request.orientation,
+            bold=request.bold,
+            italic=request.italic,
+            label_media=request.label_media,
+        )
+    except RenderError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    buf = io.BytesIO()
+    image.save(buf, format="PNG")
+    return Response(content=buf.getvalue(), media_type="image/png")

From 12737ef7b393f254b828d167119dce69cacc7c2c Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:55:18 -0700
Subject: [PATCH 08/84] Add settings store and GET/PUT settings endpoints

---
 backend/labelforge/main.py            |  2 +
 backend/labelforge/routes/print.py    |  6 ++
 backend/labelforge/routes/settings.py | 27 ++++++++
 backend/labelforge/settings_store.py  | 97 +++++++++++++++++++++++++++
 4 files changed, 132 insertions(+)
 create mode 100644 backend/labelforge/routes/settings.py
 create mode 100644 backend/labelforge/settings_store.py

diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index bb377e7..8701467 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -12,6 +12,7 @@
 from labelforge.routes import fonts, health, labels
 from labelforge.routes import print as print_router
 from labelforge.routes import preview as preview_router
+from labelforge.routes import settings as settings_router
 
 
 @asynccontextmanager
@@ -61,3 +62,4 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
 app.include_router(fonts.router, prefix="/api")
 app.include_router(print_router.router, prefix="/api")
 app.include_router(preview_router.router, prefix="/api")
+app.include_router(settings_router.router, prefix="/api")
diff --git a/backend/labelforge/routes/print.py b/backend/labelforge/routes/print.py
index e8ca2e7..5430582 100644
--- a/backend/labelforge/routes/print.py
+++ b/backend/labelforge/routes/print.py
@@ -5,6 +5,7 @@
 from labelforge.catalog.loader import get_label
 from labelforge.config import settings
 from labelforge.db import get_connection
+from labelforge import settings_store
 from labelforge.models import PrintJobResponse, QuickPrintRequest
 from labelforge.printer.client import PrintError, print_image
 from labelforge.render.text import RenderError, render_text
@@ -60,4 +61,9 @@ async def quick_print(request: QuickPrintRequest) -> PrintJobResponse:
     finally:
         conn.close()
 
+    try:
+        settings_store.set("last_quick_print", request.model_dump())
+    except Exception:
+        logger.warning("Failed to record last_quick_print", exc_info=True)
+
     return PrintJobResponse(job_id=job_id, status=outcome)
diff --git a/backend/labelforge/routes/settings.py b/backend/labelforge/routes/settings.py
new file mode 100644
index 0000000..d78f1e3
--- /dev/null
+++ b/backend/labelforge/routes/settings.py
@@ -0,0 +1,27 @@
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from labelforge import settings_store
+from labelforge.routes.auth import require_auth
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+@router.get("/settings")
+async def get_settings() -> dict[str, Any]:
+    return settings_store.get_all()
+
+
+@router.put("/settings")
+async def update_settings(body: dict[str, Any]) -> dict[str, Any]:
+    # Validate all keys first (all-or-nothing)
+    for key, value in body.items():
+        try:
+            settings_store.validate(key, value)
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+    # Write all
+    for key, value in body.items():
+        settings_store.set(key, value)
+    return settings_store.get_all()
diff --git a/backend/labelforge/settings_store.py b/backend/labelforge/settings_store.py
new file mode 100644
index 0000000..0e82a6b
--- /dev/null
+++ b/backend/labelforge/settings_store.py
@@ -0,0 +1,97 @@
+import json
+import logging
+from typing import Any
+
+from labelforge.config import settings as app_settings
+from labelforge.db import get_connection
+
+logger = logging.getLogger(__name__)
+
+_REGISTRY: dict[str, dict] = {
+    "retention_mode": {
+        "default": "forever",
+        "vtype": str,
+        "enum": frozenset({"forever", "last_n", "last_days"}),
+    },
+    "retention_count": {"default": 500, "vtype": int},
+    "retention_days": {"default": 90, "vtype": int},
+    # default falls back to config.settings.default_label_media, not a hardcoded literal
+    "default_label_media": {"default": None, "vtype": str, "nullable": True},
+    "default_font": {"default": "DejaVuSans", "vtype": str},
+    "default_font_size": {"default": 48, "vtype": int},
+    "default_orientation": {
+        "default": "standard",
+        "vtype": str,
+        "enum": frozenset({"standard", "rotated"}),
+    },
+    "printer_status_check": {"default": True, "vtype": bool},
+    "printer_status_timeout_ms": {"default": 2000, "vtype": int},
+    "last_quick_print": {"default": None, "vtype": dict, "nullable": True},
+}
+
+
+def _db_path():
+    return app_settings.data_dir / "data" / "app.db"
+
+
+def _default(key: str) -> Any:
+    if key == "default_label_media":
+        return app_settings.default_label_media
+    return _REGISTRY[key]["default"]
+
+
+def validate(key: str, value: Any) -> None:
+    """Raise ValueError if key is unknown or value fails type/enum check."""
+    if key not in _REGISTRY:
+        raise ValueError(f"Unknown setting: {key}")
+    entry = _REGISTRY[key]
+    if value is None:
+        if not entry.get("nullable", False):
+            raise ValueError(f"Setting '{key}' cannot be null")
+        return
+    vtype = entry["vtype"]
+    if vtype is int:
+        # bool is a subclass of int — reject booleans for int fields
+        if not (isinstance(value, int) and not isinstance(value, bool)):
+            raise ValueError(f"Setting '{key}' expects int, got {type(value).__name__}")
+    elif not isinstance(value, vtype):
+        raise ValueError(f"Setting '{key}' expects {vtype.__name__}, got {type(value).__name__}")
+    if "enum" in entry and value not in entry["enum"]:
+        raise ValueError(
+            f"Setting '{key}' must be one of {sorted(entry['enum'])}, got {value!r}"
+        )
+
+
+def get_all() -> dict[str, Any]:
+    conn = get_connection(_db_path())
+    try:
+        rows = conn.execute("SELECT key, value FROM settings").fetchall()
+        db_vals = {row["key"]: json.loads(row["value"]) for row in rows}
+    finally:
+        conn.close()
+    return {key: db_vals.get(key, _default(key)) for key in _REGISTRY}
+
+
+def get(key: str) -> Any:
+    if key not in _REGISTRY:
+        raise ValueError(f"Unknown setting: {key}")
+    conn = get_connection(_db_path())
+    try:
+        row = conn.execute("SELECT value FROM settings WHERE key = ?", (key,)).fetchone()
+        return json.loads(row["value"]) if row else _default(key)
+    finally:
+        conn.close()
+
+
+def set(key: str, value: Any) -> None:  # noqa: A001
+    validate(key, value)
+    conn = get_connection(_db_path())
+    try:
+        conn.execute(
+            "INSERT INTO settings (key, value) VALUES (?, ?)"
+            " ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+            (key, json.dumps(value)),
+        )
+        conn.commit()
+    finally:
+        conn.close()

From 51a6b08040a4bd2808b355f270af3378683e3bf8 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 22:56:49 -0700
Subject: [PATCH 09/84] Wire quick-print frontend to preview and settings
 endpoints

---
 frontend/src/api.ts               |  31 ++++++
 frontend/src/pages/quick-print.ts | 156 +++++++++++++++++-------------
 frontend/src/style.css            |  11 +++
 3 files changed, 130 insertions(+), 68 deletions(-)

diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index a37a70d..e3da719 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -40,3 +40,34 @@ export function quickPrint(req: QuickPrintRequest): Promise<PrintJobResponse> {
     body: JSON.stringify(req),
   })
 }
+
+export async function previewQuick(req: QuickPrintRequest): Promise<Blob> {
+  const res = await fetch('/api/preview/quick', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${getToken()}`,
+    },
+    body: JSON.stringify(req),
+  })
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`
+    try {
+      const body = await res.json() as { detail?: unknown }
+      if (body.detail) detail = String(body.detail)
+    } catch { /* use status fallback */ }
+    throw new Error(detail)
+  }
+  return res.blob()
+}
+
+export function getSettings(): Promise<Record<string, unknown>> {
+  return apiFetch<Record<string, unknown>>('/api/settings')
+}
+
+export function putSettings(partial: Record<string, unknown>): Promise<Record<string, unknown>> {
+  return apiFetch<Record<string, unknown>>('/api/settings', {
+    method: 'PUT',
+    body: JSON.stringify(partial),
+  })
+}
diff --git a/frontend/src/pages/quick-print.ts b/frontend/src/pages/quick-print.ts
index 0e27d81..836e6a0 100644
--- a/frontend/src/pages/quick-print.ts
+++ b/frontend/src/pages/quick-print.ts
@@ -1,15 +1,6 @@
-import { getFonts, getLabels, quickPrint, TOKEN_KEY } from '../api'
+import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api'
 import type { LabelEntry, QuickPrintRequest } from '../types'
 
-// localStorage is the v1 stand-in for saved settings; replace when GET/PUT /api/settings exists
-const PREF = {
-  font: 'labelforge_font',
-  font_size: 'labelforge_font_size',
-  label_media: 'labelforge_label_media',
-  alignment: 'labelforge_alignment',
-  orientation: 'labelforge_orientation',
-}
-
 const FORM_FACTOR_LABEL: Record<number, string> = {
   1: 'Die-cut',
   2: 'Continuous',
@@ -17,7 +8,6 @@ const FORM_FACTOR_LABEL: Record<number, string> = {
   4: 'P-touch Continuous',
 }
 
-// Render order for form-factor groups
 const FF_ORDER = [2, 1, 3, 4]
 
 function esc(s: string): string {
@@ -111,10 +101,13 @@ function renderForm(root: HTMLElement): void {
         </div>
 
         <div class="actions">
-          <button type="button" id="btn-preview" disabled title="Preview endpoint not yet implemented">Preview</button>
+          <button type="button" id="btn-preview" disabled>Preview</button>
           <button type="submit" id="btn-print" disabled>Print</button>
         </div>
       </form>
+      <div id="preview-area" class="preview-area" hidden>
+        <img id="preview-img" alt="Label preview" />
+      </div>
     </div>
   `
 
@@ -125,8 +118,12 @@ function renderForm(root: HTMLElement): void {
   const labelSelect = root.querySelector<HTMLSelectElement>('#label-media')!
   const boldCheck = root.querySelector<HTMLInputElement>('#bold')!
   const italicCheck = root.querySelector<HTMLInputElement>('#italic')!
+  const btnPreview = root.querySelector<HTMLButtonElement>('#btn-preview')!
   const btnPrint = root.querySelector<HTMLButtonElement>('#btn-print')!
   const statusMsg = root.querySelector<HTMLDivElement>('#status-msg')!
+  const previewArea = root.querySelector<HTMLDivElement>('#preview-area')!
+  const previewImg = root.querySelector<HTMLImageElement>('#preview-img')!
+  let previewObjectUrl: string | null = null
 
   function showStatus(msg: string, kind: 'success' | 'error'): void {
     statusMsg.textContent = msg
@@ -138,21 +135,64 @@ function renderForm(root: HTMLElement): void {
     statusMsg.hidden = true
   }
 
-  function updatePrintButton(): void {
-    btnPrint.disabled = textarea.value.trim() === ''
+  function updateButtons(): void {
+    const empty = textarea.value.trim() === ''
+    btnPrint.disabled = empty
+    btnPreview.disabled = empty
+  }
+
+  function buildRequest(): QuickPrintRequest {
+    const alignment = (
+      form.querySelector<HTMLInputElement>('input[name="alignment"]:checked')?.value ?? 'left'
+    ) as QuickPrintRequest['alignment']
+    const orientation = (
+      form.querySelector<HTMLInputElement>('input[name="orientation"]:checked')?.value ?? 'standard'
+    ) as QuickPrintRequest['orientation']
+    return {
+      text: textarea.value,
+      font: fontSelect.value,
+      font_size: parseInt(fontSizeInput.value, 10),
+      alignment,
+      orientation,
+      label_media: labelSelect.value,
+      bold: boldCheck.checked,
+      italic: italicCheck.checked,
+    }
   }
 
-  textarea.addEventListener('input', updatePrintButton)
+  textarea.addEventListener('input', updateButtons)
+
+  btnPreview.addEventListener('click', async () => {
+    btnPreview.disabled = true
+    hideStatus()
+    try {
+      const blob = await previewQuick(buildRequest())
+      if (previewObjectUrl) URL.revokeObjectURL(previewObjectUrl)
+      previewObjectUrl = URL.createObjectURL(blob)
+      previewImg.src = previewObjectUrl
+      previewArea.hidden = false
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+    } finally {
+      updateButtons()
+    }
+  })
 
-  Promise.all([getFonts(), getLabels()]).then(([fonts, labels]) => {
-    // Populate fonts
+  // Load fonts, labels, and settings in parallel; settings failure is non-fatal
+  Promise.all([
+    getFonts(),
+    getLabels(),
+    getSettings().catch((err: Error) => {
+      console.warn('Failed to load settings:', err.message)
+      return null as Record<string, unknown> | null
+    }),
+  ]).then(([fonts, labels, sett]) => {
+    // Populate fonts dropdown
     fontSelect.innerHTML = fonts
       .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
       .join('')
-    const savedFont = localStorage.getItem(PREF.font)
-    if (savedFont) fontSelect.value = savedFont
 
-    // Group labels by form_factor, sort within groups by display_name
+    // Group labels by form_factor
     const groups = new Map<number, LabelEntry[]>()
     for (const label of labels) {
       const ff = label.form_factor
@@ -162,8 +202,6 @@ function renderForm(root: HTMLElement): void {
     for (const entries of groups.values()) {
       entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
     }
-
-    // Render known order first, then any remaining form_factor values
     const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
     labelSelect.innerHTML = allKeys
       .filter(k => groups.has(k))
@@ -177,27 +215,34 @@ function renderForm(root: HTMLElement): void {
       })
       .join('')
 
-    const savedLabel = localStorage.getItem(PREF.label_media)
-    if (savedLabel) labelSelect.value = savedLabel
-
-    // Restore remaining prefs
-    const savedSize = localStorage.getItem(PREF.font_size)
-    if (savedSize) fontSizeInput.value = savedSize
-
-    const savedAlignment = localStorage.getItem(PREF.alignment)
-    if (savedAlignment) {
-      const radio = form.querySelector<HTMLInputElement>(
-        `input[name="alignment"][value="${savedAlignment}"]`
+    // Restore form from settings; last_quick_print takes precedence over per-key defaults
+    const lqp = (sett?.last_quick_print ?? null) as QuickPrintRequest | null
+    if (lqp) {
+      fontSelect.value = lqp.font ?? String(sett?.default_font ?? 'DejaVuSans')
+      fontSizeInput.value = String(lqp.font_size ?? sett?.default_font_size ?? 48)
+      labelSelect.value = String(lqp.label_media ?? sett?.default_label_media ?? '62')
+      boldCheck.checked = lqp.bold ?? false
+      italicCheck.checked = lqp.italic ?? false
+      const aRadio = form.querySelector<HTMLInputElement>(
+        `input[name="alignment"][value="${lqp.alignment ?? 'left'}"]`
       )
-      if (radio) radio.checked = true
-    }
-
-    const savedOrientation = localStorage.getItem(PREF.orientation)
-    if (savedOrientation) {
-      const radio = form.querySelector<HTMLInputElement>(
-        `input[name="orientation"][value="${savedOrientation}"]`
+      if (aRadio) aRadio.checked = true
+      const oRadio = form.querySelector<HTMLInputElement>(
+        `input[name="orientation"][value="${lqp.orientation ?? 'standard'}"]`
+      )
+      if (oRadio) oRadio.checked = true
+    } else {
+      const defFont = String(sett?.default_font ?? 'DejaVuSans')
+      const defSize = String(sett?.default_font_size ?? 48)
+      const defMedia = String(sett?.default_label_media ?? '62')
+      const defOrientation = String(sett?.default_orientation ?? 'standard')
+      fontSelect.value = defFont
+      fontSizeInput.value = defSize
+      labelSelect.value = defMedia
+      const oRadio = form.querySelector<HTMLInputElement>(
+        `input[name="orientation"][value="${defOrientation}"]`
       )
-      if (radio) radio.checked = true
+      if (oRadio) oRadio.checked = true
     }
   }).catch((err: Error) => {
     showStatus(`Failed to load form data: ${err.message}`, 'error')
@@ -208,33 +253,8 @@ function renderForm(root: HTMLElement): void {
     btnPrint.disabled = true
     hideStatus()
 
-    const alignment = (
-      form.querySelector<HTMLInputElement>('input[name="alignment"]:checked')?.value ?? 'left'
-    ) as QuickPrintRequest['alignment']
-
-    const orientation = (
-      form.querySelector<HTMLInputElement>('input[name="orientation"]:checked')?.value ?? 'standard'
-    ) as QuickPrintRequest['orientation']
-
-    const req: QuickPrintRequest = {
-      text: textarea.value,
-      font: fontSelect.value,
-      font_size: parseInt(fontSizeInput.value, 10),
-      alignment,
-      orientation,
-      label_media: labelSelect.value,
-      bold: boldCheck.checked,
-      italic: italicCheck.checked,
-    }
-
-    localStorage.setItem(PREF.font, req.font)
-    localStorage.setItem(PREF.font_size, String(req.font_size))
-    localStorage.setItem(PREF.label_media, req.label_media)
-    localStorage.setItem(PREF.alignment, req.alignment)
-    localStorage.setItem(PREF.orientation, req.orientation)
-
     try {
-      const result = await quickPrint(req)
+      const result = await quickPrint(buildRequest())
       // "sent" = transmitted to printer network backend, not confirmed printed
       showStatus(
         `Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`,
@@ -243,7 +263,7 @@ function renderForm(root: HTMLElement): void {
     } catch (err) {
       showStatus((err as Error).message, 'error')
     } finally {
-      updatePrintButton()
+      updateButtons()
     }
   })
 }
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 1668a0c..9d8b79c 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -119,6 +119,17 @@ button:disabled {
   color: #7a1a14;
 }
 
+.preview-area {
+  margin-top: 1rem;
+  text-align: center;
+}
+
+.preview-area img {
+  max-width: 100%;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+}
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;

From 57d936fad28a1d2906b4cc4ab6e39cdb460daef7 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 23:37:21 -0700
Subject: [PATCH 10/84] Add templates table, models, and store
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deps: qrcode[pil]>=8.0 and python-barcode>=0.15 added to pyproject.toml —
first new runtime deps since initial skeleton; required by the template
renderer (Phase 3) for QR and barcode element generation.

Schema: CREATE TABLE IF NOT EXISTS templates (id, name unique, display_name,
label_media, canvas_json, field_schema, created_at, updated_at, deleted_at).
Idempotent migration adds field_values TEXT and batch_id TEXT to print_jobs
via PRAGMA table_info check + ALTER TABLE, since SQLite has no ADD COLUMN IF
NOT EXISTS.

Models: FieldSpec, Template, TemplateCreate, TemplateUpdate, PrintRequest,
BatchPrintRequest, BatchJobResult, BatchPrintResponse added to
labelforge.models.

Store: labelforge.templates.store — list_templates, get_template,
create_template, update_template, soft_delete, duplicate. Name validation
enforces ^[a-z0-9][a-z0-9-]*$ slug; duplicate names raise ValueError (→ 409
in routes); missing templates return None (→ 404).
---
 backend/labelforge/db.py                 |  38 ++++-
 backend/labelforge/models/__init__.py    |  58 +++++++
 backend/labelforge/templates/__init__.py |   0
 backend/labelforge/templates/store.py    | 187 +++++++++++++++++++++++
 pyproject.toml                           |   2 +
 5 files changed, 277 insertions(+), 8 deletions(-)
 create mode 100644 backend/labelforge/templates/__init__.py
 create mode 100644 backend/labelforge/templates/store.py

diff --git a/backend/labelforge/db.py b/backend/labelforge/db.py
index a8ef5a4..d80b377 100644
--- a/backend/labelforge/db.py
+++ b/backend/labelforge/db.py
@@ -3,19 +3,31 @@
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS print_jobs (
-    id          INTEGER PRIMARY KEY,
-    template_id TEXT    NULL,
-    payload_json TEXT   NOT NULL,
-    label_media TEXT    NOT NULL,
-    preview_path TEXT   NULL,
-    pinned      INTEGER NOT NULL DEFAULT 0,
-    created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+    id           INTEGER PRIMARY KEY,
+    template_id  TEXT    NULL,
+    payload_json TEXT    NOT NULL,
+    label_media  TEXT    NOT NULL,
+    preview_path TEXT    NULL,
+    pinned       INTEGER NOT NULL DEFAULT 0,
+    created_at   TEXT    NOT NULL DEFAULT (datetime('now'))
 );
 
 CREATE TABLE IF NOT EXISTS settings (
     key   TEXT PRIMARY KEY,
     value TEXT NOT NULL
 );
+
+CREATE TABLE IF NOT EXISTS templates (
+    id           INTEGER PRIMARY KEY,
+    name         TEXT UNIQUE NOT NULL,
+    display_name TEXT NOT NULL,
+    label_media  TEXT NOT NULL,
+    canvas_json  TEXT NOT NULL,
+    field_schema TEXT NOT NULL DEFAULT '[]',
+    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at   TEXT NOT NULL DEFAULT (datetime('now')),
+    deleted_at   TEXT NULL
+);
 """
 
 
@@ -26,9 +38,19 @@ def get_connection(db_path: Path) -> sqlite3.Connection:
     return conn
 
 
+def _migrate_print_jobs(conn: sqlite3.Connection) -> None:
+    """Idempotently add columns to print_jobs that post-date the initial schema."""
+    existing = {row["name"] for row in conn.execute("PRAGMA table_info(print_jobs)")}
+    if "field_values" not in existing:
+        conn.execute("ALTER TABLE print_jobs ADD COLUMN field_values TEXT NULL")
+    if "batch_id" not in existing:
+        conn.execute("ALTER TABLE print_jobs ADD COLUMN batch_id TEXT NULL")
+    conn.commit()
+
+
 def init_db(db_path: Path) -> None:
     db_path.parent.mkdir(parents=True, exist_ok=True)
     conn = get_connection(db_path)
     conn.executescript(_SCHEMA)
-    conn.commit()
+    _migrate_print_jobs(conn)
     conn.close()
diff --git a/backend/labelforge/models/__init__.py b/backend/labelforge/models/__init__.py
index 9373089..d197ce7 100644
--- a/backend/labelforge/models/__init__.py
+++ b/backend/labelforge/models/__init__.py
@@ -44,3 +44,61 @@ class PrintJobResponse(BaseModel):
     job_id: int
     status: str
     preview_url: str | None = None
+
+
+# ── Templates ────────────────────────────────────────────────────────────────
+
+class FieldSpec(BaseModel):
+    name: str
+    type: Literal["text", "number", "date", "enum"] = "text"
+    required: bool = True
+    default: str | None = None
+    increment: bool = False
+    enum_values: list[str] = []
+
+
+class Template(BaseModel):
+    name: str
+    display_name: str
+    label_media: str
+    canvas_json: dict
+    field_schema: list[FieldSpec]
+    created_at: str
+    updated_at: str
+
+
+class TemplateCreate(BaseModel):
+    name: str
+    display_name: str | None = None
+    label_media: str
+    canvas_json: dict
+    field_schema: list[FieldSpec] = []
+
+
+class TemplateUpdate(BaseModel):
+    display_name: str | None = None
+    label_media: str | None = None
+    canvas_json: dict | None = None
+    field_schema: list[FieldSpec] | None = None
+
+
+# ── Print / batch ─────────────────────────────────────────────────────────────
+
+class PrintRequest(BaseModel):
+    fields: dict[str, str] = {}
+
+
+class BatchPrintRequest(BaseModel):
+    labels: list[dict[str, str]]
+
+
+class BatchJobResult(BaseModel):
+    job_id: int
+    status: str
+
+
+class BatchPrintResponse(BaseModel):
+    batch_id: str
+    jobs: list[BatchJobResult]
+    succeeded: int
+    failed: int
diff --git a/backend/labelforge/templates/__init__.py b/backend/labelforge/templates/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/labelforge/templates/store.py b/backend/labelforge/templates/store.py
new file mode 100644
index 0000000..6d81b97
--- /dev/null
+++ b/backend/labelforge/templates/store.py
@@ -0,0 +1,187 @@
+import json
+import re
+import sqlite3
+from datetime import datetime, timezone
+
+from labelforge.config import settings
+from labelforge.db import get_connection
+from labelforge.models import FieldSpec, Template, TemplateCreate, TemplateUpdate
+
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+
+def _db_path():
+    return settings.data_dir / "data" / "app.db"
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _row_to_template(row: sqlite3.Row) -> Template:
+    return Template(
+        name=row["name"],
+        display_name=row["display_name"],
+        label_media=row["label_media"],
+        canvas_json=json.loads(row["canvas_json"]),
+        field_schema=[FieldSpec(**f) for f in json.loads(row["field_schema"])],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+def _validate_name(name: str) -> None:
+    if not _NAME_RE.match(name):
+        raise ValueError(
+            f"Template name '{name}' is invalid — use lowercase letters, digits, "
+            "and hyphens only; must start with a letter or digit."
+        )
+
+
+def list_templates() -> list[Template]:
+    conn = get_connection(_db_path())
+    try:
+        rows = conn.execute(
+            "SELECT * FROM templates WHERE deleted_at IS NULL ORDER BY name"
+        ).fetchall()
+        return [_row_to_template(r) for r in rows]
+    finally:
+        conn.close()
+
+
+def get_template(name: str, include_deleted: bool = False) -> Template | None:
+    conn = get_connection(_db_path())
+    try:
+        if include_deleted:
+            row = conn.execute(
+                "SELECT * FROM templates WHERE lower(name) = lower(?)", (name,)
+            ).fetchone()
+        else:
+            row = conn.execute(
+                "SELECT * FROM templates WHERE lower(name) = lower(?) AND deleted_at IS NULL",
+                (name,),
+            ).fetchone()
+        return _row_to_template(row) if row else None
+    finally:
+        conn.close()
+
+
+def create_template(data: TemplateCreate) -> Template:
+    _validate_name(data.name)
+    conn = get_connection(_db_path())
+    try:
+        if conn.execute(
+            "SELECT 1 FROM templates WHERE lower(name) = lower(?)", (data.name,)
+        ).fetchone():
+            raise ValueError(f"Template name '{data.name}' already exists.")
+
+        display_name = data.display_name or data.name
+        now = _now_utc()
+        conn.execute(
+            """INSERT INTO templates
+               (name, display_name, label_media, canvas_json, field_schema, created_at, updated_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (
+                data.name,
+                display_name,
+                data.label_media,
+                json.dumps(data.canvas_json),
+                json.dumps([f.model_dump() for f in data.field_schema]),
+                now,
+                now,
+            ),
+        )
+        conn.commit()
+        row = conn.execute(
+            "SELECT * FROM templates WHERE name = ?", (data.name,)
+        ).fetchone()
+        return _row_to_template(row)
+    finally:
+        conn.close()
+
+
+def update_template(name: str, data: TemplateUpdate) -> Template | None:
+    conn = get_connection(_db_path())
+    try:
+        if not conn.execute(
+            "SELECT 1 FROM templates WHERE lower(name) = lower(?) AND deleted_at IS NULL",
+            (name,),
+        ).fetchone():
+            return None
+
+        updates: dict[str, object] = {"updated_at": _now_utc()}
+        if data.display_name is not None:
+            updates["display_name"] = data.display_name
+        if data.label_media is not None:
+            updates["label_media"] = data.label_media
+        if data.canvas_json is not None:
+            updates["canvas_json"] = json.dumps(data.canvas_json)
+        if data.field_schema is not None:
+            updates["field_schema"] = json.dumps([f.model_dump() for f in data.field_schema])
+
+        set_clause = ", ".join(f"{k} = ?" for k in updates)
+        conn.execute(
+            f"UPDATE templates SET {set_clause} WHERE lower(name) = lower(?)",  # noqa: S608
+            (*updates.values(), name),
+        )
+        conn.commit()
+        row = conn.execute(
+            "SELECT * FROM templates WHERE lower(name) = lower(?)", (name,)
+        ).fetchone()
+        return _row_to_template(row) if row else None
+    finally:
+        conn.close()
+
+
+def soft_delete(name: str) -> bool:
+    conn = get_connection(_db_path())
+    try:
+        cursor = conn.execute(
+            "UPDATE templates SET deleted_at = ? "
+            "WHERE lower(name) = lower(?) AND deleted_at IS NULL",
+            (_now_utc(), name),
+        )
+        conn.commit()
+        return cursor.rowcount > 0
+    finally:
+        conn.close()
+
+
+def duplicate(name: str, new_name: str, new_label_media: str) -> Template:
+    _validate_name(new_name)
+    conn = get_connection(_db_path())
+    try:
+        orig = conn.execute(
+            "SELECT * FROM templates WHERE lower(name) = lower(?) AND deleted_at IS NULL",
+            (name,),
+        ).fetchone()
+        if not orig:
+            raise ValueError(f"Template '{name}' not found.")
+
+        if conn.execute(
+            "SELECT 1 FROM templates WHERE lower(name) = lower(?)", (new_name,)
+        ).fetchone():
+            raise ValueError(f"Template name '{new_name}' already exists.")
+
+        now = _now_utc()
+        conn.execute(
+            """INSERT INTO templates
+               (name, display_name, label_media, canvas_json, field_schema, created_at, updated_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (
+                new_name,
+                new_name,
+                new_label_media,
+                orig["canvas_json"],
+                orig["field_schema"],
+                now,
+                now,
+            ),
+        )
+        conn.commit()
+        row = conn.execute(
+            "SELECT * FROM templates WHERE name = ?", (new_name,)
+        ).fetchone()
+        return _row_to_template(row)
+    finally:
+        conn.close()
diff --git a/pyproject.toml b/pyproject.toml
index 017f07b..5ca22c9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -18,6 +18,8 @@ dependencies = [
     "pydantic-settings>=2.6",
     "pyyaml>=6.0",
     "pillow>=10.4",
+    "qrcode[pil]>=8.0",
+    "python-barcode>=0.15",
     "brother-ql-inventree>=1.3",
 ]
 

From 9d3b2ceedecf5dea72ef585ae1c3fc1fdff60a3d Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Tue, 19 May 2026 23:58:28 -0700
Subject: [PATCH 11/84] Add template field detection and schema merge

---
 backend/labelforge/templates/fields.py | 73 ++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 backend/labelforge/templates/fields.py

diff --git a/backend/labelforge/templates/fields.py b/backend/labelforge/templates/fields.py
new file mode 100644
index 0000000..ec73593
--- /dev/null
+++ b/backend/labelforge/templates/fields.py
@@ -0,0 +1,73 @@
+import re
+
+from labelforge.models import FieldSpec
+
+_PLACEHOLDER_RE = re.compile(r"\{([a-zA-Z0-9_]+)\}")
+
+# Trailing-digit pattern for advance(): splits "spool-047" into ("spool-", "047")
+_TRAILING_DIGITS_RE = re.compile(r"^(.*?)(\d+)$")
+
+
+def detect_fields(canvas_json: dict) -> list[str]:
+    """Return ordered unique field names found in canvas element content."""
+    seen: dict[str, None] = {}  # ordered set via dict
+    for obj in canvas_json.get("objects", []):
+        raw: str | None = None
+        t = obj.get("type", "")
+        if t in ("i-text", "text", "textbox"):
+            raw = obj.get("labelforge_raw_content") or obj.get("text", "")
+        elif obj.get("labelforge_qr_payload") is not None:
+            raw = obj["labelforge_qr_payload"]
+        elif obj.get("labelforge_barcode_payload") is not None:
+            raw = obj["labelforge_barcode_payload"]
+        if raw:
+            for name in _PLACEHOLDER_RE.findall(raw):
+                seen[name] = None
+    return list(seen)
+
+
+def merge_schema(detected: list[str], existing: list[FieldSpec]) -> list[FieldSpec]:
+    """Merge detected field names with the stored schema.
+
+    - Keeps existing specs for names still detected (preserves user edits).
+    - Adds newly-detected names with defaults (type=text, required=True).
+    - Drops specs whose name is no longer detected.
+    """
+    existing_by_name = {f.name: f for f in existing}
+    result: list[FieldSpec] = []
+    for name in detected:
+        if name in existing_by_name:
+            result.append(existing_by_name[name])
+        else:
+            result.append(FieldSpec(name=name))
+    return result
+
+
+def resolve_content(raw: str, values: dict[str, str]) -> str:
+    """Substitute {name} placeholders with values. Raises ValueError for missing keys."""
+
+    def replacer(m: re.Match) -> str:
+        name = m.group(1)
+        if name not in values:
+            raise ValueError(f"Missing required field: '{name}'")
+        return values[name]
+
+    return _PLACEHOLDER_RE.sub(replacer, raw)
+
+
+def advance(value: str) -> str:
+    """Increment the trailing numeric portion of *value* by 1.
+
+    Pure number:      "47"     → "48"
+    Zero-padded:      "047"    → "048"  (width preserved; grows on overflow: "099" → "100")
+    Suffix-numeric:   "spool-047" → "spool-048"
+    Non-numeric:      returned unchanged.
+    """
+    m = _TRAILING_DIGITS_RE.match(value)
+    if not m:
+        return value
+    prefix, digits = m.group(1), m.group(2)
+    next_num = int(digits) + 1
+    # Preserve zero-padding width; allow growth on overflow (e.g. 099 → 100)
+    next_str = str(next_num).zfill(len(digits)) if digits.startswith("0") else str(next_num)
+    return prefix + next_str

From 14d2f1ff37b60203e82d5684c71384e8247eeabd Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 17:31:38 -0700
Subject: [PATCH 12/84] Add server-side template renderer

---
 backend/labelforge/render/template.py | 232 ++++++++++++++++++++++++++
 1 file changed, 232 insertions(+)
 create mode 100644 backend/labelforge/render/template.py

diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
new file mode 100644
index 0000000..8965aa5
--- /dev/null
+++ b/backend/labelforge/render/template.py
@@ -0,0 +1,232 @@
+import io
+import logging
+
+import barcode as _barcode_lib
+import qrcode
+from barcode.writer import ImageWriter
+from PIL import Image, ImageDraw, ImageFont
+from qrcode.constants import ERROR_CORRECT_H, ERROR_CORRECT_L, ERROR_CORRECT_M, ERROR_CORRECT_Q
+
+from labelforge.catalog.loader import get_label
+from labelforge.models import Template
+from labelforge.render.fonts import get_font_path
+from labelforge.render.text import RenderError
+from labelforge.templates.fields import resolve_content
+
+logger = logging.getLogger(__name__)
+
+_PADDING = 20
+_CONTINUOUS_FORM_FACTORS = {2, 4}
+
+_QR_CORRECTION = {
+    "L": ERROR_CORRECT_L,
+    "M": ERROR_CORRECT_M,
+    "Q": ERROR_CORRECT_Q,
+    "H": ERROR_CORRECT_H,
+}
+
+
+def _canvas_color_to_l(color: str | None) -> int | None:
+    """Map a CSS color string to mode-L pixel value; None means no fill."""
+    if not color or color in ("transparent", "rgba(0,0,0,0)", "none"):
+        return None
+    lc = color.lower().strip()
+    if lc in ("#fff", "#ffffff", "white", "rgb(255,255,255)"):
+        return 255
+    return 0
+
+
+def _resolve_font_path(family: str, weight: str | None, style: str | None) -> str | None:
+    """Return the best matching font file path, falling back to base family on miss."""
+    bold = bool(weight and str(weight).lower() in ("bold", "700", "800", "900"))
+    italic = bool(style and str(style).lower() in ("italic", "oblique"))
+
+    # Normalise family name into candidate stems (CSS name, no-space, hyphen-joined).
+    bases: list[str] = list(
+        dict.fromkeys([family, family.replace(" ", ""), family.replace(" ", "-")])
+    )
+    candidates: list[str] = []
+    for base in bases:
+        if bold and italic:
+            candidates += [f"{base}-BoldItalic", f"{base}BoldItalic"]
+        if bold:
+            candidates += [f"{base}-Bold", f"{base}Bold"]
+        if italic:
+            candidates += [f"{base}-Italic", f"{base}Italic", f"{base}-Oblique"]
+        candidates.append(base)
+
+    seen: set[str] = set()
+    for name in candidates:
+        if name in seen:
+            continue
+        seen.add(name)
+        path = get_font_path(name)
+        if path:
+            return path
+    return None
+
+
+def _paste_onto(
+    canvas: Image.Image, sub: Image.Image, left: int, top: int, angle: float
+) -> None:
+    """Paste sub-image onto canvas; invert-mask whites out, rotate around element centre."""
+    if abs(angle) > 0.01:
+        # Preserve centre point across expand-rotation.
+        cx = left + sub.width // 2
+        cy = top + sub.height // 2
+        sub = sub.rotate(-angle, expand=True, resample=Image.BICUBIC, fillcolor=255)
+        left = cx - sub.width // 2
+        top = cy - sub.height // 2
+    # Dark pixels (value≈0) → mask 255 (opaque); white (255) → mask 0 (skip).
+    # Preserves antialiasing in intermediate greys.
+    mask = sub.point(lambda p: 255 - p)
+    canvas.paste(sub, (left, top), mask=mask)
+
+
+def _render_text_element(
+    obj: dict, values: dict[str, str], box_w: int, box_h: int
+) -> Image.Image:
+    raw = obj.get("labelforge_raw_content") or obj.get("text", "")
+    text = resolve_content(raw, values)
+
+    family = obj.get("fontFamily", "")
+    font_path = _resolve_font_path(family, obj.get("fontWeight"), obj.get("fontStyle"))
+    if not font_path:
+        raise RenderError(f"Font not available: {family!r}")
+
+    font_size = max(6, int(obj.get("fontSize", 20)))
+    try:
+        pil_font = ImageFont.truetype(font_path, font_size)
+    except Exception as exc:
+        raise RenderError(f"Could not load font '{family}': {exc}") from exc
+
+    align = obj.get("textAlign", "left")
+    if align not in ("left", "center", "right"):
+        align = "left"
+
+    sub = Image.new("L", (max(box_w, 1), max(box_h, 1)), 255)
+    draw = ImageDraw.Draw(sub)
+    draw.multiline_text((0, 0), text, font=pil_font, fill=0, align=align)
+    return sub
+
+
+def _render_qr_element(
+    payload: str, correction: str, box_w: int, box_h: int
+) -> Image.Image:
+    if not payload:
+        raise RenderError("QR payload is empty after field substitution")
+    ec = _QR_CORRECTION.get((correction or "M").upper(), ERROR_CORRECT_M)
+    qr = qrcode.QRCode(error_correction=ec, border=1)
+    qr.add_data(payload)
+    qr.make(fit=True)
+    buf = io.BytesIO()
+    qr.make_image(fill_color=0, back_color=255).save(buf, "PNG")
+    buf.seek(0)
+    img = Image.open(buf)
+    img.load()
+    return img.convert("L").resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
+
+
+def _render_barcode_element(
+    payload: str, symbology: str, box_w: int, box_h: int
+) -> Image.Image:
+    if not payload:
+        raise RenderError("Barcode payload is empty after field substitution")
+    symb = (symbology or "code128").lower().replace("-", "").replace("_", "")
+    try:
+        bc_class = _barcode_lib.get_barcode_class(symb)
+    except Exception:
+        bc_class = _barcode_lib.get_barcode_class("code128")
+    try:
+        bc = bc_class(payload, writer=ImageWriter())
+    except Exception as exc:
+        raise RenderError(f"Invalid barcode payload for {symbology!r}: {exc}") from exc
+    buf = io.BytesIO()
+    bc.write(buf, options={"write_text": False})
+    buf.seek(0)
+    img = Image.open(buf)
+    img.load()
+    return img.convert("L").resize((max(box_w, 1), max(box_h, 1)), Image.LANCZOS)
+
+
+def render_template(template: Template, values: dict[str, str]) -> Image.Image:
+    """Rasterize *template* with *values* substituted for placeholders.
+
+    Returns a mode='L' PIL Image (0=black, 255=white) sized for the print head.
+    Two-color (62red) rendering is a later slice; always renders mono.
+    """
+    label = get_label(template.label_media)
+    if label is None:
+        raise RenderError(f"Unknown label media: {template.label_media!r}")
+
+    canvas_w = label.dots_printable[0]
+    objects = template.canvas_json.get("objects", [])
+    is_continuous = label.form_factor in _CONTINUOUS_FORM_FACTORS
+
+    if is_continuous:
+        bottommost = 0
+        for obj in objects:
+            t = int(obj.get("top", 0))
+            h = int(obj.get("height", 0) * float(obj.get("scaleY", 1.0)))
+            bottommost = max(bottommost, t + h)
+        canvas_h = max(bottommost + _PADDING, 1)
+    else:
+        canvas_h = label.dots_printable[1]
+
+    canvas = Image.new("L", (canvas_w, canvas_h), 255)
+    draw = ImageDraw.Draw(canvas)
+
+    for obj in objects:
+        obj_type = obj.get("type", "")
+        left = int(obj.get("left", 0))
+        top = int(obj.get("top", 0))
+        angle = float(obj.get("angle", 0))
+        box_w = max(1, int(obj.get("width", 10) * float(obj.get("scaleX", 1.0))))
+        box_h = max(1, int(obj.get("height", 10) * float(obj.get("scaleY", 1.0))))
+
+        try:
+            if obj_type in ("i-text", "text", "textbox"):
+                sub = _render_text_element(obj, values, box_w, box_h)
+                _paste_onto(canvas, sub, left, top, angle)
+
+            elif obj_type == "image":
+                if obj.get("labelforge_qr_payload") is not None:
+                    payload = resolve_content(obj["labelforge_qr_payload"], values)
+                    sub = _render_qr_element(
+                        payload, obj.get("labelforge_qr_error_correction", "M"), box_w, box_h
+                    )
+                    _paste_onto(canvas, sub, left, top, angle)
+                elif obj.get("labelforge_barcode_payload") is not None:
+                    payload = resolve_content(obj["labelforge_barcode_payload"], values)
+                    sub = _render_barcode_element(
+                        payload, obj.get("labelforge_barcode_symbology", "code128"), box_w, box_h
+                    )
+                    _paste_onto(canvas, sub, left, top, angle)
+                else:
+                    raise RenderError("Image elements not yet supported")
+
+            elif obj_type == "line":
+                # x1,y1,x2,y2 are offsets from the element's left,top origin.
+                x1 = left + int(obj.get("x1", 0))
+                y1 = top + int(obj.get("y1", 0))
+                x2 = left + int(obj.get("x2", box_w))
+                y2 = top + int(obj.get("y2", box_h))
+                draw.line([(x1, y1), (x2, y2)], fill=0, width=max(1, int(obj.get("strokeWidth", 1))))
+
+            elif obj_type in ("rect", "Rect"):
+                fill_v = _canvas_color_to_l(obj.get("fill"))
+                sw = max(1, int(obj.get("strokeWidth", 1)))
+                sub = Image.new("L", (box_w, box_h), 255)
+                sub_draw = ImageDraw.Draw(sub)
+                sub_draw.rectangle([0, 0, box_w - 1, box_h - 1], fill=fill_v, outline=0, width=sw)
+                _paste_onto(canvas, sub, left, top, angle)
+
+            else:
+                logger.debug("Skipping unhandled element type %r", obj_type)
+
+        except RenderError:
+            raise
+        except Exception as exc:
+            raise RenderError(f"Failed to render element '{obj_type}': {exc}") from exc
+
+    return canvas

From ea30f0bdd6ff1c89043e308d219cdd8302a840f2 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 17:44:50 -0700
Subject: [PATCH 13/84] Add template CRUD endpoints

---
 backend/labelforge/main.py             |  2 +
 backend/labelforge/routes/templates.py | 94 ++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 backend/labelforge/routes/templates.py

diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 8701467..043cb85 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -13,6 +13,7 @@
 from labelforge.routes import print as print_router
 from labelforge.routes import preview as preview_router
 from labelforge.routes import settings as settings_router
+from labelforge.routes import templates as templates_router
 
 
 @asynccontextmanager
@@ -63,3 +64,4 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
 app.include_router(print_router.router, prefix="/api")
 app.include_router(preview_router.router, prefix="/api")
 app.include_router(settings_router.router, prefix="/api")
+app.include_router(templates_router.router, prefix="/api")
diff --git a/backend/labelforge/routes/templates.py b/backend/labelforge/routes/templates.py
new file mode 100644
index 0000000..acffa32
--- /dev/null
+++ b/backend/labelforge/routes/templates.py
@@ -0,0 +1,94 @@
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from labelforge.catalog.loader import get_label
+from labelforge.models import Template, TemplateCreate, TemplateUpdate
+from labelforge.routes.auth import require_auth
+from labelforge.templates import store
+from labelforge.templates.fields import detect_fields, merge_schema
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+def _load_or_404(name: str) -> Template:
+    tmpl = store.get_template(name)
+    if tmpl is None:
+        raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
+    return tmpl
+
+
+@router.get("/templates", response_model=list[Template])
+async def list_templates() -> list[Template]:
+    return store.list_templates()
+
+
+@router.get("/templates/{name}", response_model=Template)
+async def get_template(name: str) -> Template:
+    return _load_or_404(name)
+
+
+@router.post("/templates", response_model=Template, status_code=201)
+async def create_template(data: TemplateCreate) -> Template:
+    if get_label(data.label_media) is None:
+        raise HTTPException(status_code=400, detail=f"Unknown label media: {data.label_media!r}")
+
+    objects = data.canvas_json.get("objects", [])
+    if not objects:
+        raise HTTPException(status_code=400, detail="Template has no elements")
+
+    detected = detect_fields(data.canvas_json)
+    data.field_schema = merge_schema(detected, data.field_schema)
+
+    try:
+        return store.create_template(data)
+    except ValueError as exc:
+        msg = str(exc)
+        status = 409 if "already exists" in msg else 400
+        raise HTTPException(status_code=status, detail=msg) from exc
+
+
+@router.put("/templates/{name}", response_model=Template)
+async def update_template(name: str, data: TemplateUpdate) -> Template:
+    existing = _load_or_404(name)
+
+    if data.label_media is not None and get_label(data.label_media) is None:
+        raise HTTPException(status_code=400, detail=f"Unknown label media: {data.label_media!r}")
+
+    if data.canvas_json is not None:
+        detected = detect_fields(data.canvas_json)
+        data.field_schema = merge_schema(detected, existing.field_schema)
+
+    result = store.update_template(name, data)
+    if result is None:
+        raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
+    return result
+
+
+@router.delete("/templates/{name}", status_code=204)
+async def delete_template(name: str) -> None:
+    if not store.soft_delete(name):
+        raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
+
+
+class _DuplicateRequest(BaseModel):
+    name: str
+    label_media: str
+
+
+@router.post("/templates/{name}/duplicate", response_model=Template, status_code=201)
+async def duplicate_template(name: str, body: _DuplicateRequest) -> Template:
+    _load_or_404(name)  # 404 if source doesn't exist / is deleted
+
+    if get_label(body.label_media) is None:
+        raise HTTPException(status_code=400, detail=f"Unknown label media: {body.label_media!r}")
+
+    try:
+        return store.duplicate(name, body.name, body.label_media)
+    except ValueError as exc:
+        msg = str(exc)
+        status = 409 if "already exists" in msg else 400
+        raise HTTPException(status_code=status, detail=msg) from exc

From 75e680681e264be1cfd038a6359769fba8ebf46a Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 17:47:40 -0700
Subject: [PATCH 14/84] Add template print, preview, and batch endpoints

---
 backend/labelforge/main.py                  |   2 +
 backend/labelforge/routes/template_print.py | 183 ++++++++++++++++++++
 2 files changed, 185 insertions(+)
 create mode 100644 backend/labelforge/routes/template_print.py

diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 043cb85..3db3042 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -13,6 +13,7 @@
 from labelforge.routes import print as print_router
 from labelforge.routes import preview as preview_router
 from labelforge.routes import settings as settings_router
+from labelforge.routes import template_print as template_print_router
 from labelforge.routes import templates as templates_router
 
 
@@ -65,3 +66,4 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
 app.include_router(preview_router.router, prefix="/api")
 app.include_router(settings_router.router, prefix="/api")
 app.include_router(templates_router.router, prefix="/api")
+app.include_router(template_print_router.router, prefix="/api")
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
new file mode 100644
index 0000000..1619e36
--- /dev/null
+++ b/backend/labelforge/routes/template_print.py
@@ -0,0 +1,183 @@
+import io
+import json
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+
+from labelforge.config import settings
+from labelforge.db import get_connection
+from labelforge.models import (
+    BatchJobResult,
+    BatchPrintRequest,
+    BatchPrintResponse,
+    PrintRequest,
+)
+from labelforge.printer.client import PrintError, print_image
+from labelforge.render.template import render_template
+from labelforge.render.text import RenderError
+from labelforge.routes.auth import require_auth
+from labelforge.templates import store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+def _db_path():
+    return settings.data_dir / "data" / "app.db"
+
+
+def _apply_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
+    """Return values dict with defaults filled in; raise HTTPException for missing required."""
+    result = dict(values)
+    for field in template_fields:
+        if field.name not in result:
+            if field.default is not None:
+                result[field.name] = field.default
+            elif field.required:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Missing required field: '{field.name}'",
+                )
+    return result
+
+
+def _insert_job(
+    template_name: str,
+    label_media: str,
+    field_values: dict,
+    request_json: str,
+    batch_id: str | None = None,
+) -> int:
+    conn = get_connection(_db_path())
+    try:
+        cursor = conn.execute(
+            """INSERT INTO print_jobs
+               (template_id, payload_json, label_media, field_values, batch_id)
+               VALUES (?, ?, ?, ?, ?)""",
+            (
+                template_name,
+                request_json,
+                label_media,
+                json.dumps(field_values),
+                batch_id,
+            ),
+        )
+        conn.commit()
+        return cursor.lastrowid
+    finally:
+        conn.close()
+
+
+@router.post("/print/{name}")
+async def print_template(name: str, body: PrintRequest) -> dict:
+    tmpl = store.get_template(name)
+    if tmpl is None:
+        raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
+
+    values = _apply_defaults(tmpl.field_schema, body.fields)
+
+    try:
+        image = render_template(tmpl, values)
+    except RenderError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    try:
+        outcome = print_image(
+            image=image,
+            label_media=tmpl.label_media,
+            model=settings.printer_model,
+            backend=settings.printer_backend,
+            host=settings.printer_host,
+        )
+    except PrintError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    job_id = _insert_job(name, tmpl.label_media, values, body.model_dump_json())
+
+    # preview_url points at the history preview route, which lands in a later slice.
+    return {
+        "job_id": job_id,
+        "status": outcome,
+        "template": name,
+        "label_media": tmpl.label_media,
+        "preview_url": f"/api/history/{job_id}/preview.png",
+    }
+
+
+@router.post("/preview/{name}")
+async def preview_template(name: str, body: PrintRequest) -> Response:
+    tmpl = store.get_template(name)
+    if tmpl is None:
+        raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
+
+    values = _apply_defaults(tmpl.field_schema, body.fields)
+
+    try:
+        image = render_template(tmpl, values)
+    except RenderError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    buf = io.BytesIO()
+    image.save(buf, format="PNG")
+    return Response(content=buf.getvalue(), media_type="image/png")
+
+
+@router.post("/print/{name}/batch", response_model=BatchPrintResponse)
+async def batch_print(name: str, body: BatchPrintRequest) -> BatchPrintResponse:
+    count = len(body.labels)
+    if count < 1:
+        raise HTTPException(status_code=400, detail="Batch count must be >= 1")
+    if count > 1000:
+        raise HTTPException(status_code=400, detail="Batch count exceeds maximum (1000)")
+
+    tmpl = store.get_template(name)
+    if tmpl is None:
+        raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
+
+    batch_id = str(uuid.uuid4())
+    jobs: list[BatchJobResult] = []
+    succeeded = 0
+    failed = 0
+
+    for label_values in body.labels:
+        try:
+            values = _apply_defaults(tmpl.field_schema, label_values)
+            image = render_template(tmpl, values)
+            outcome = print_image(
+                image=image,
+                label_media=tmpl.label_media,
+                model=settings.printer_model,
+                backend=settings.printer_backend,
+                host=settings.printer_host,
+            )
+            job_id = _insert_job(
+                name, tmpl.label_media, values,
+                BatchPrintRequest(labels=[label_values]).model_dump_json(),
+                batch_id=batch_id,
+            )
+            jobs.append(BatchJobResult(job_id=job_id, status=outcome))
+            succeeded += 1
+        except (HTTPException, RenderError, PrintError, ValueError) as exc:
+            msg = exc.detail if isinstance(exc, HTTPException) else str(exc)
+            jobs.append(BatchJobResult(job_id=-1, status=f"error: {msg}"))
+            failed += 1
+        except Exception as exc:
+            jobs.append(BatchJobResult(job_id=-1, status=f"error: {exc}"))
+            failed += 1
+
+    # Return 200 if at least one succeeded; 500 if all failed.
+    # Mixed results return 200 — 207 deferred per api.md.
+    if failed == count:
+        raise HTTPException(
+            status_code=500,
+            detail=BatchPrintResponse(
+                batch_id=batch_id, jobs=jobs, succeeded=0, failed=failed
+            ).model_dump(),
+        )
+
+    return BatchPrintResponse(
+        batch_id=batch_id, jobs=jobs, succeeded=succeeded, failed=failed
+    )

From cd1f523d7b2f5407ad2ee6b059d168b9680630da Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 22:22:12 -0700
Subject: [PATCH 15/84] Record printer-status and settings ADRs; update
 changelog status

---
 CHANGELOG.md      |  8 +++++--
 docs/decisions.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 885dbf4..38910f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,7 +9,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 - PRD covering quick-print, templates, label catalog, history, HTTP API, printer status, and settings
 - Architecture doc locking stack: FastAPI + SQLite + brother-ql-inventree + Vite/TS + Fabric.js
 - Glossary defining vocabulary
-- ADR log (library choice, license, name, storage, frontend, label catalog model, auth, print-outcome reporting, convert rotation)
+- ADR log (library choice, license, name, storage, frontend, label catalog model, auth, print-outcome reporting, convert rotation, server-side template rendering, settings source-of-truth, printer status via EWS)
 - CLAUDE.md for AI session context
 - GPL-3.0 LICENSE
 - .gitattributes enforcing LF line endings
@@ -38,7 +38,11 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 - Print API now reports the true send outcome (`sent` for the network backend) instead of always claiming `printed` (see ADR 2026-05-20)
 
 ### Status
-- Slice 1 verified end-to-end: a real label printed on the QL-820NWB (DK-1209 die-cut, `62x29`). The render → convert → network-send path is confirmed working. Deferred to later slices: templates, canvas editor, history UI, printer-status query, settings UI, batch/increment, frontend.
+
+- Slice 1 verified end-to-end: a real label printed on the QL-820NWB (DK-1209 die-cut, `62x29`). The render → convert → network-send path is confirmed working. 62mm continuous print remains a media-coverage test pending a continuous roll (capability proven, that specific media not yet physically run).
+- Templates engine (slice) built and committed: storage, CRUD, server-side renderer, print/preview/batch. Not yet smoke-tested against a created template end-to-end.
+- Printer status: empirically confirmed the network print path (TCP 9100) does not answer status requests; the printer's EWS page (HTTP port 80) does report loaded media and is the chosen status source (opt-in). See ADR 2026-05-20 (c).
+- Deferred to later slices: Fabric.js canvas editor, history UI + retention, printer-status feature (EWS scrape), settings UI, two-color (62red) rendering, image elements / image upload.
 
 ---
 
diff --git a/docs/decisions.md b/docs/decisions.md
index ab741b7..279a404 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,64 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-20 (c) — Printer status comes from the EWS status page (opt-in), not the print path or vendor SDKs
+
+**Decision**: Live printer status (loaded media type, device-ready state) is read by fetching and parsing the printer's embedded web server (EWS) status page over HTTP — `http://<printer-host>/general/status.html` on the QL-820NWB — **as an opt-in feature, disabled by default**. The raster print path (TCP 9100) and the Brother b-PAC / Mobile SDKs are NOT used for status.
+
+**Why**: Three channels were evaluated against the locked stack (Python/FastAPI, Linux container, networked printer):
+
+- **TCP 9100 (raster/print path)** — send-only. A probe issuing the status-information request opcode (`ESC i S`) then reading returned empty against an idle, ready printer. No status here. (Confirmed empirically.)
+- **Brother b-PAC SDK / Mobile SDK** — these do expose status (e.g. `getLabelInfoStatus` returning a label-ID enum), but b-PAC is a Windows COM component and the Mobile SDK is iOS/Android. Neither runs in a Linux container. Off-stack — rejected. (The enum reports the same sensed-media fact the EWS page already gives us, so nothing is lost.)
+- **EWS over HTTP (port 80)** — the printer serves a status page reporting `Device Status` (e.g. READY), `Media Type` (e.g. "62mm x 29mm"), `Media Status`, and `Emulation`. The Status page is readable with an unauthenticated GET. Verified directly against the device. **Chosen.**
+
+**Scope of this decision**: read-only, unauthenticated status scrape, opt-in.
+
+- Default **off**. A setting (`printer_status_check`) enables it; when off, labelforge assumes nothing about loaded media and relies solely on the user-selected `label_media`.
+- Status is **advisory, never a gate**. A status read never blocks or fails a print. If the fetch fails, times out, or the page can't be parsed, status is reported as "unknown" and printing proceeds normally.
+
+**Consequence — the page is firmware-controlled, so version-track the parser**: The status page is HTML emitted by printer firmware and can change shape across firmware versions. Therefore the parser targets a known page layout and records which layout/firmware it was written against (a parser-version constant); parsing must fail soft (unrecognized layout → status "unknown" + logged warning, never an exception reaching the print flow); treat the scrape as best-effort telemetry, not a contract.
+
+**Deferred open decision — authenticated EWS access (NOT decided here)**: Logging into the EWS with the admin password exposes firmware version and the ability to change raster/printer settings via authenticated POSTs (which carry a CSRF token). This is materially different from read-only status — it means storing the printer admin credential and performing writes against device config. That needs its own decision (security posture, where the password lives, whether write access is in scope for a single-user homelab tool). Flagged as a future fork; deliberately out of scope here.
+
+**Would revisit if**: the EWS page format proves too unstable across firmware to parse reliably, or a feature need pulls the authenticated-EWS decision onto the table.
+
+---
+
+## 2026-05-20 (b) — Settings: DB rows are source of truth, env is bootstrap default
+
+**Decision**: User-adjustable preferences live in the SQLite `settings` table and are the source of truth at runtime. Code holds the default for each setting. Environment variables are NOT the runtime source for these preferences — with one bridge: the `default_label_media` setting falls back to the env value (`config.settings.default_label_media`) when no DB row exists. All other settings fall back to their code-defined defaults.
+
+**Why**: `config.py` already reads `default_label_media` from env, and `features/settings.md` lists the same key as a DB-backed setting — an overlap that needed resolving. The settings doc's model is "defaults in code, DB stores overrides," which fits a UI that lets the user change preferences at runtime (env changes require a container restart; DB changes don't). Making the DB authoritative means the Settings UI is the single place a preference is owned. The one env bridge (`default_label_media`) preserves the existing env-based bootstrap so a fresh install with no DB rows still honors a deployer's configured default.
+
+**Considered**:
+
+- **Env always wins** — rejected. A runtime Settings UI that can't actually change a setting without a container restart is a confusing UI; env is for deploy-time bootstrap, not live preferences.
+- **Ignore env entirely, code defaults only** — rejected. Throws away the existing `default_label_media` env bootstrap that deployers may already rely on.
+- **DB authoritative, env bridges `default_label_media` only** — chosen. DB owns runtime prefs; the existing env bootstrap is preserved for the one key that already had it.
+
+**Consequence**: The settings store reads DB-first, then default; for `default_label_media` the default is the env value rather than a hardcoded literal. `features/settings.md` should note this precedence so the env/DB relationship is documented where settings are specified.
+
+**Would revisit if**: more settings need a deploy-time env bootstrap (then generalize the bridge into a per-key "env default" mechanism rather than special-casing one key).
+
+---
+
+## 2026-05-20 — Templates render server-side from element data, not from a browser-exported image
+
+**Decision**: A template stores its design as structured element data (the canvas scene plus per-element `labelforge_*` content with `{placeholders}`). At print/preview time the **server** resolves placeholder values into element content and rasterizes the scene to a Pillow bitmap. The rendered bitmap is the source of truth for both preview and print. The browser is never in the print path.
+
+**Why**: The API contract is "a client passes *values* for a named template and the server prints that template with those values" (`POST /api/print/{name}` with `{fields: {...}}`). The client sends values, not an image. Any client — a script, a webhook, a phone shortcut, a home-automation call, or the app's own UI — must get the same result with no browser involved. Therefore the server must hold the design and render it itself. This is also what `architecture.md` already assumes (Pillow is the rendering source of truth) and what `features/templates.md` implies (QR/barcode regenerated server-side from the resolved payload).
+
+**Considered**:
+- **Browser exports a PNG, server prints that bitmap** — rejected. Breaks the core API contract: a headless client has no browser, so it could not render a template at all. Only the UI could ever print. This defeats the reason the API exists.
+- **Headless browser on the server (Playwright/Puppeteer renders Fabric)** — rejected for v1. Faithful to the editor, but drags a full browser + Node runtime into the `python:3.12-slim` runtime image, inflating image size and ops weight against the single-small-container design. Disproportionate for a single-user homelab tool.
+- **Server re-renders from element data with Pillow** — chosen. Browser-free, keeps the runtime image lean, and makes the API work for every client by construction. QR via `qrcode[pil]`, barcodes via `python-barcode`, text/line/rect/image via Pillow.
+
+**Consequence / known cost**: There are now two renderers of the same scene — the Fabric.js editor (authoring, in-browser) and the server-side Pillow renderer (preview + print). They must agree on geometry: coordinate origin, the 300dpi label scale, font metrics, and element transforms (`angle`, `scaleX`, `scaleY`). Divergence shows up as "preview/print doesn't match the editor." Mitigations: the editor operates in label-pixel coordinates at print DPI (per `features/templates.md`), and `POST /api/preview/{name}` returns the *server*-rendered bitmap so the user always previews the real output, not the editor's own canvas. The server renderer is the authority; the editor is an approximation of it.
+
+**Would revisit if**: editor/server geometry drift becomes a recurring source of bugs that coordinate-matching can't tame, at which point a headless-browser renderer (accepting the image-size cost) returns to the table.
+
+---
+
 ## 2026-05-20 — Print API reports `sent`, not `printed`, on the network backend
 
 **Decision**: `POST /api/print/*` returns the print outcome verbatim from the brother_ql backend. For the network (TCP) backend this is `sent`, meaning the raster was transmitted but the result is unconfirmed. Only backends that can read printer status back (USB) return `printed`. The API never claims `printed` for a network send.

From 3ef28136dd2d61caad3943d0130c29f5b6d2765c Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 22:38:51 -0700
Subject: [PATCH 16/84] Default DATA_DIR to /data and make compose
 deployment-generic

---
 .env.example                 |  7 ++++---
 backend/labelforge/config.py |  2 +-
 compose.yml                  | 29 ++++++++---------------------
 3 files changed, 13 insertions(+), 25 deletions(-)

diff --git a/.env.example b/.env.example
index f2f73f7..d8a2af3 100644
--- a/.env.example
+++ b/.env.example
@@ -18,9 +18,10 @@ PRINTER_BACKEND=network
 # Label media loaded in the printer by default (used as UI pre-selection).
 DEFAULT_LABEL_MEDIA=62
 
-# Host path where SQLite, labels.yml, fonts, and previews are stored.
-# Must be bind-mounted into the container at the same path.
-DATA_DIR=/var/docker/labelforge
+# Where SQLite, labels.yml, fonts, and previews are stored INSIDE the container.
+# Default works with the named volume in compose.yml. Only change this if you
+# also change the container-side mount path.
+DATA_DIR=/data
 
 # Python log level: DEBUG | INFO | WARNING | ERROR
 LOG_LEVEL=INFO
diff --git a/backend/labelforge/config.py b/backend/labelforge/config.py
index b31473f..57cf0a7 100644
--- a/backend/labelforge/config.py
+++ b/backend/labelforge/config.py
@@ -9,7 +9,7 @@ class Settings(BaseSettings):
     printer_model: str = "QL-820NWB"
     # one of: network, linux_kernel, pyusb
     printer_backend: str = "network"
-    data_dir: Path = Path("/var/docker/labelforge")
+    data_dir: Path = Path("/data")
     default_label_media: str = "62"
     log_level: str = "INFO"
 
diff --git a/compose.yml b/compose.yml
index 640d808..1dea3b4 100644
--- a/compose.yml
+++ b/compose.yml
@@ -6,26 +6,13 @@ services:
     image: labelforge:latest
     restart: unless-stopped
     env_file: .env
+    ports:
+      - "8000:8000"
+    # Reverse proxy / tunnel wiring is deployment-specific. labelforge serves plain HTTP on port 8000;
+    # put it behind whatever proxy you use (Traefik, Caddy, nginx, Cloudflare Tunnel, etc.).
+    # To use a host directory instead of a named volume, replace with:  - /your/host/path:/data
     volumes:
-      - /var/docker/labelforge:/var/docker/labelforge
-    networks:
-      - traefik
-      - dockflare
-    labels:
-      # ── Traefik (LAN — labels.home.arpa via internal Traefik instance) ────
-      traefik.enable: "true"
-      traefik.http.routers.labelforge-lan.rule: "Host(`labels.home.arpa`)"
-      traefik.http.routers.labelforge-lan.entrypoints: "web"
-      traefik.http.services.labelforge.loadbalancer.server.port: "8000"
+      - labelforge-data:/data
 
-      # ── Dockflare (Cloudflare Tunnel — labels.crzynet.com) ───────────────
-      # Adjust label keys to match your Dockflare version / configuration.
-      dockflare.enable: "true"
-      dockflare.hostname: "labels.crzynet.com"
-      dockflare.service: "http://labelforge:8000"
-
-networks:
-  traefik:
-    external: true
-  dockflare:
-    external: true
+volumes:
+  labelforge-data:

From 8e4501a32395d76aee7c8e219867c301bb072692 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 22:39:49 -0700
Subject: [PATCH 17/84] Remove homelab specifics from docs; correct branch
 model

---
 CLAUDE.md            |  7 +++----
 docs/architecture.md | 24 ++++++++++++------------
 2 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index adc1568..82350c3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ When working on a task, load the relevant feature doc(s) plus `architecture.md`
 - **Config**: PyYAML for the label catalog
 - **Frontend**: Vite + TypeScript, vanilla (no React/Vue/Svelte), Fabric.js for the canvas
 - **Deployment**: single Docker container, multi-stage build (frontend → static assets → served by FastAPI)
-- **Container image**: published to Gitea registry (`gitea.crzynet.com`) and Docker Hub
+- **Container image**: built from the included `Dockerfile`; publish to whatever registry you use.
 
 ## Non-negotiables
 
@@ -37,8 +37,7 @@ When working on a task, load the relevant feature doc(s) plus `architecture.md`
 - **No SaaS dependencies.** Self-hosted only. No cloud functions, no hosted databases, no third-party APIs that aren't user-controllable.
 - **No Next.js, no SSR frameworks.** Frontend is a static SPA served from the FastAPI container.
 - **No alternative printer libraries** without an ADR. We picked `brother-ql-inventree` after evaluation.
-- **Container data path**: `/var/docker/labelforge/` on the host. SQLite at `data/app.db`, label catalog at `labels.yml`, fonts at `fonts/`, optional label preview images at `label-previews/`.
-- **External hostname**: `labels.crzynet.com` (Cloudflare Tunnel via Dockflare). Internal: `labels.home.arpa` (Traefik on LAN).
+- **Data path**: the app reads/writes everything under `$DATA_DIR` (default `/data` in the container): SQLite at `$DATA_DIR/data/app.db`, label catalog at `$DATA_DIR/labels.yml`, fonts at `$DATA_DIR/fonts/`, optional preview images at `$DATA_DIR/label-previews/`. How that path is backed (named volume, bind mount) is the operator's choice.
 
 ## Working style
 
@@ -57,7 +56,7 @@ From the session prompt that owns this project:
 ## Repo conventions
 
 - Line endings: LF only. `.gitattributes` enforces this. If `git diff --stat` shows all files modified, run `git config core.autocrlf input && git checkout -- .`
-- Branches: `main` is deployable. Feature work in `feature/<name>` branches.
+- Branches: `main` is protected — the ONLY way in is a pull request, gated by CodeQL and other checks; never push to `main` directly. `dev` is the working branch (solo work commits straight to `dev`). Use `feature/<name>` branches when more than one person is working; merge those to `dev`, then PR `dev` → `main` for a release.
 - Commits: imperative present tense ("Add template recall endpoint" not "Added"). No conventional-commits prefixes.
 - Compose stack lives at the repo root as `compose.yml`. Dev compose at `compose.dev.yml`.
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 3ca0d4c..e5fc46a 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -22,10 +22,12 @@
 
 ### Storage
 
-- **SQLite** at `/var/docker/labelforge/data/app.db` — templates, history, settings, API tokens
-- **`labels.yml`** at `/var/docker/labelforge/labels.yml` — user-editable label catalog metadata
-- **Fonts** at `/var/docker/labelforge/fonts/` — `.ttf` / `.otf` files, drop-in
-- **Label preview images** (optional) at `/var/docker/labelforge/label-previews/` — referenced from `labels.yml`
+- **SQLite** at `$DATA_DIR/data/app.db` — templates, history, settings, API tokens
+- **`labels.yml`** at `$DATA_DIR/labels.yml` — user-editable label catalog metadata
+- **Fonts** at `$DATA_DIR/fonts/` — `.ttf` / `.otf` files, drop-in
+- **Label preview images** (optional) at `$DATA_DIR/label-previews/` — referenced from `labels.yml`
+
+$DATA_DIR defaults to `/data` inside the container; back it with a named volume or bind mount as you prefer.
 
 ### Why these choices
 
@@ -44,7 +46,7 @@ labelforge/
 ├── CLAUDE.md
 ├── .gitignore
 ├── .gitattributes
-├── compose.yml                   # production-shaped, used by Dockhand
+├── compose.yml                   # single-service stack; bring your own proxy
 ├── compose.dev.yml               # local dev: bind mounts, no Traefik labels
 ├── Dockerfile                    # multi-stage: frontend build → python runtime
 ├── pyproject.toml                # backend deps + tool config
@@ -123,16 +125,14 @@ merge: only identifiers in the intersection are user-facing.
 
 ## Deployment
 
-- Single Compose stack deployed via Dockhand on `docker10`
-- Networks: `traefik` (LAN routing) and `dockflare` (Cloudflare Tunnel to `labels.crzynet.com`)
-- Data volume: `/var/docker/labelforge/` host path bind-mounted
-- Image source: built locally on a CI host, pushed to Gitea registry, optionally mirrored to Docker Hub
-- Env-driven config: printer host/port, API token, default label media, retention defaults
-- No build step at deploy time — image is pre-built
+- Single Docker image built from the included `Dockerfile` (multi-stage: frontend build → python runtime). No build step at deploy time once the image is built.
+- Runs as one container serving plain HTTP on port `8000`. Put it behind whatever reverse proxy or tunnel you use; proxy wiring is deployment-specific and intentionally not baked into the app.
+- Persistent data lives under `$DATA_DIR` (default `/data`); back it with a named volume or a host bind mount. See `compose.yml` for a standalone example and `compose.dev.yml` for local hot-reload dev.
+- Env-driven config: printer host/port, API token, default label media, data dir, log level. See `.env.example`.
 
 ## Out of scope for v1
 
-- Reverse-proxy hardening beyond what Traefik defaults give
+- Reverse-proxy hardening (proxy choice is left to the operator)
 - Database migrations beyond initial schema creation (manually managed for v1)
 - Health-check endpoint beyond what Traefik needs
 - Prometheus metrics endpoint (can add later if useful)

From bac4ad7a5afdffa54153de9039ff167ac504b579 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 22:40:13 -0700
Subject: [PATCH 18/84] Record deployment-generic and branch-model ADR

---
 docs/decisions.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/decisions.md b/docs/decisions.md
index 279a404..09ce095 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,20 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-20 (d) — App stays deployment-generic; branch model is PR-gated main + dev working branch
+
+**Decision (deployment)**: labelforge's repo and docs describe the app generically — a single Docker container serving HTTP on 8000, with persistent data under `$DATA_DIR` (default `/data`). No specific host paths, hostnames, registries, orchestrators, or reverse-proxy wiring appear in the app or its public docs. `compose.yml` ships a standalone example using a named volume; operators substitute their own bind mount / proxy / tunnel.
+
+**Decision (branches)**: `main` is protected and reachable only via pull request, gated by CodeQL and other checks — never a direct push. `dev` is the working branch; solo work commits directly to `dev`. `feature/<name>` branches are used when more than one person is involved, merged to `dev`, and `dev` is PR'd to `main` for a release.
+
+**Why**: The project is public open source. Baking the owner's homelab (host paths like `/var/docker/labelforge`, hostnames like `labels.crzynet.com`, Dockflare/Traefik labels, Gitea registry, the orchestrator) into the app's defaults and docs made it non-portable and misled readers — a stranger cloning the repo got the author's filesystem as a default and a deploy story they can't use. The deployment specifics are the operator's concern, not the app's. Separately, the documented branch model (`main` deployable, feature branches as default) did not match reality (PR-gated `main`, `dev` as the normal working branch), which repeatedly caused confusion; the docs now match the actual workflow.
+
+**Consequence**: `config.py` defaults `DATA_DIR=/data`; `compose.yml` uses a named volume and carries no proxy/network specifics; CLAUDE.md and architecture.md describe paths as `$DATA_DIR`-relative and deployment as bring-your-own-proxy. The owner's actual homelab deployment (named orchestrator, host paths, tunnel) lives outside this repo. Any future doc or default that reintroduces a specific host/hostname/registry/orchestrator into the app should be rejected and pointed at this ADR.
+
+**Would revisit if**: the project ships an official first-party deployment (e.g. a published image + opinionated compose) — at which point an *example* registry/image name may belong in docs, still framed as one option, not a baked-in default.
+
+---
+
 ## 2026-05-20 (c) — Printer status comes from the EWS status page (opt-in), not the print path or vendor SDKs
 
 **Decision**: Live printer status (loaded media type, device-ready state) is read by fetching and parsing the printer's embedded web server (EWS) status page over HTTP — `http://<printer-host>/general/status.html` on the QL-820NWB — **as an opt-in feature, disabled by default**. The raster print path (TCP 9100) and the Brother b-PAC / Mobile SDKs are NOT used for status.

From 5d1ba221216f340581bfde900246d8aaf54a2b3e Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:18:00 -0700
Subject: [PATCH 19/84] Render QR and barcode crisp for 1-bit print; make
 preview match print output
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

QR: use box_size=1 to generate the smallest natural image (1px/module), then
scale by the largest integer multiple that fits the target box with NEAREST
resampling.  Every module is guaranteed N×N pure black/white pixels — no grey
edges that the print threshold can crush.

Barcode: binarize to pure 0/255 before scaling, then NEAREST instead of
LANCZOS.  LANCZOS was introducing anti-aliased grey at bar edges; those grey
values survived the 1-bit threshold and merged adjacent bars.

Preview: introduce PRINT_THRESHOLD (70, matching convert()'s default) and
to_print_bitmap() in printer/client.py.  Both preview endpoints now apply
the same invert+threshold step as convert(), returning a pure B/W PNG that
is the exact bitmap the printer rasterizes.  print_image() passes the
constant explicitly to convert() so the single definition governs both paths.
---
 backend/labelforge/printer/client.py        | 20 +++++++++++++++-
 backend/labelforge/render/template.py       | 26 +++++++++++++++++----
 backend/labelforge/routes/preview.py        |  3 ++-
 backend/labelforge/routes/template_print.py |  4 ++--
 4 files changed, 44 insertions(+), 9 deletions(-)

diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
index f3aa8b6..b295030 100644
--- a/backend/labelforge/printer/client.py
+++ b/backend/labelforge/printer/client.py
@@ -16,6 +16,24 @@
 
 logger = logging.getLogger(__name__)
 
+# Centralized threshold — must match the value passed to convert() so that
+# to_print_bitmap() and print_image() apply the exact same 1-bit decision.
+PRINT_THRESHOLD = 70  # percent, same semantics as convert()'s threshold= kwarg
+_THRESHOLD_PX: int = min(255, max(0, int((100.0 - PRINT_THRESHOLD) / 100.0 * 255)))
+# Original L pixels ≤ this value print as black; above it → white (no ink).
+_PRINT_CUTOFF: int = 255 - _THRESHOLD_PX
+
+
+def to_print_bitmap(image: Image.Image) -> Image.Image:
+    """Reproduce convert()'s 1-bit threshold on *image*.
+
+    Returns a mode-'L' image (0 = will print black, 255 = will not print)
+    that is the exact bitmap the printer rasterizes.  Use this for preview
+    responses so preview == print for every element type.
+    """
+    im = image.convert("L")
+    return im.point(lambda x: 0 if x <= _PRINT_CUTOFF else 255)
+
 
 class PrintError(Exception):
     pass
@@ -43,7 +61,7 @@ def print_image(
         # print-head width. rotate='auto' (the library default) can flip a
         # wide continuous image into a geometry the printer reads as the wrong
         # roll type. The renderer already produces the correct orientation.
-        instructions = convert(qlr, [image], label_media, cut=True, rotate="0")
+        instructions = convert(qlr, [image], label_media, cut=True, rotate="0", threshold=PRINT_THRESHOLD)
         identifier = f"tcp://{host}" if backend == "network" else host
         result = send(
             instructions=instructions,
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index 8965aa5..7ae9a44 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -116,15 +116,28 @@ def _render_qr_element(
     if not payload:
         raise RenderError("QR payload is empty after field substitution")
     ec = _QR_CORRECTION.get((correction or "M").upper(), ERROR_CORRECT_M)
-    qr = qrcode.QRCode(error_correction=ec, border=1)
+    # box_size=1 gives the smallest natural image (1px per module) so the
+    # integer scale factor below is maximised and module edges stay crisp.
+    qr = qrcode.QRCode(error_correction=ec, border=1, box_size=1)
     qr.add_data(payload)
     qr.make(fit=True)
     buf = io.BytesIO()
     qr.make_image(fill_color=0, back_color=255).save(buf, "PNG")
     buf.seek(0)
-    img = Image.open(buf)
-    img.load()
-    return img.convert("L").resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
+    nat = Image.open(buf).convert("L")
+    nat.load()
+    nat_w, nat_h = nat.size  # always square
+    scale = min(box_w // nat_w, box_h // nat_h)
+    if scale >= 1:
+        # Integer-multiple upscale: every module maps to exactly scale×scale pixels,
+        # pure black/white — no grey edges that the print threshold could crush.
+        scaled_w, scaled_h = nat_w * scale, nat_h * scale
+        scaled = nat.resize((scaled_w, scaled_h), Image.NEAREST)
+        result = Image.new("L", (box_w, box_h), 255)
+        result.paste(scaled, ((box_w - scaled_w) // 2, (box_h - scaled_h) // 2))
+        return result
+    # Fallback: box smaller than natural QR; NEAREST keeps pixels pure B/W.
+    return nat.resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
 
 
 def _render_barcode_element(
@@ -146,7 +159,10 @@ def _render_barcode_element(
     buf.seek(0)
     img = Image.open(buf)
     img.load()
-    return img.convert("L").resize((max(box_w, 1), max(box_h, 1)), Image.LANCZOS)
+    # Force pure black/white before scaling; NEAREST keeps bars as whole-pixel
+    # columns with no anti-aliased grey that the print threshold could merge.
+    bw = img.convert("L").point(lambda x: 0 if x < 128 else 255)
+    return bw.resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
 
 
 def render_template(template: Template, values: dict[str, str]) -> Image.Image:
diff --git a/backend/labelforge/routes/preview.py b/backend/labelforge/routes/preview.py
index 7286ad5..5c3602d 100644
--- a/backend/labelforge/routes/preview.py
+++ b/backend/labelforge/routes/preview.py
@@ -6,6 +6,7 @@
 
 from labelforge.catalog.loader import get_label
 from labelforge.models import QuickPrintRequest
+from labelforge.printer.client import to_print_bitmap
 from labelforge.render.text import RenderError, render_text
 from labelforge.routes.auth import require_auth
 
@@ -37,5 +38,5 @@ async def preview_quick(request: QuickPrintRequest) -> Response:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
     buf = io.BytesIO()
-    image.save(buf, format="PNG")
+    to_print_bitmap(image).save(buf, format="PNG")
     return Response(content=buf.getvalue(), media_type="image/png")
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index 1619e36..2d5f52a 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -14,7 +14,7 @@
     BatchPrintResponse,
     PrintRequest,
 )
-from labelforge.printer.client import PrintError, print_image
+from labelforge.printer.client import PrintError, print_image, to_print_bitmap
 from labelforge.render.template import render_template
 from labelforge.render.text import RenderError
 from labelforge.routes.auth import require_auth
@@ -121,7 +121,7 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
     buf = io.BytesIO()
-    image.save(buf, format="PNG")
+    to_print_bitmap(image).save(buf, format="PNG")
     return Response(content=buf.getvalue(), media_type="image/png")
 
 

From 91e3aeb8b9b713f7a61c7a6feb3f1563b7c004b1 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:18:27 -0700
Subject: [PATCH 20/84] Record preview-matches-print threshold ADR

---
 docs/decisions.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/decisions.md b/docs/decisions.md
index 09ce095..74f6f1b 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,18 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-20 (e) — Preview must apply the same 1-bit threshold as print
+
+**Decision**: The preview endpoints return the exact 1-bit (black/white) image the printer will rasterize, produced by the same threshold/dither step as the print path — not the pre-threshold greyscale render. There is a single shared definition of "the bitmap that prints," used by both preview and print.
+
+**Why**: A QR element previewed as a crisp code but printed as a solid black block. Cause: the printer's `convert()` thresholds the greyscale render to 1-bit (~70% default, no dither), which crushed the QR's anti-aliased fine modules; preview returned the pre-threshold greyscale, so it looked fine while the print did not. The rendering ADR's promise that "preview is the exact bitmap that prints" only holds if preview applies the same final threshold. Fine detail (QR, barcode, thin lines, small text) is where preview-vs-print divergence shows up — and it showed up on a physical label, the most expensive place to find it.
+
+**Consequence**: QR/barcode elements are rendered as pure black/white scaled by integer factors so thresholding cannot crush them. Threshold/dither settings are explicit and centralized so preview and print provably agree. This refines (does not contradict) the server-side rendering ADR.
+
+**Would revisit if**: a future need for greyscale/dithered output (e.g. photo-ish images on a label) requires preview to represent dithering, at which point the shared step must reproduce the dither, not just the threshold.
+
+---
+
 ## 2026-05-20 (d) — App stays deployment-generic; branch model is PR-gated main + dev working branch
 
 **Decision (deployment)**: labelforge's repo and docs describe the app generically — a single Docker container serving HTTP on 8000, with persistent data under `$DATA_DIR` (default `/data`). No specific host paths, hostnames, registries, orchestrators, or reverse-proxy wiring appear in the app or its public docs. `compose.yml` ships a standalone example using a named volume; operators substitute their own bind mount / proxy / tunnel.

From 60d20ecad5180b4a5fe2d5ece3ca748cb7f38711 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:30:21 -0700
Subject: [PATCH 21/84] Gate QR and barcode elements until print bug is fixed

---
 CHANGELOG.md                          |  4 ++++
 backend/labelforge/render/template.py | 16 ++++++++--------
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 38910f9..18721db 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Known Issues
+
+- QR and barcode template elements render in preview but print as a solid black block (1-bit threshold crushes fine detail). These elements are gated to raise a clear error until fixed. Text, lines, and rectangles print correctly.
+
 ### Added
 - Project structure and design documentation
 - PRD covering quick-print, templates, label catalog, history, HTTP API, printer status, and settings
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index 7ae9a44..e53405c 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -110,6 +110,7 @@ def _render_text_element(
     return sub
 
 
+# TODO: re-enable when QR/barcode 1-bit print bug is fixed
 def _render_qr_element(
     payload: str, correction: str, box_w: int, box_h: int
 ) -> Image.Image:
@@ -140,6 +141,7 @@ def _render_qr_element(
     return nat.resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
 
 
+# TODO: re-enable when QR/barcode 1-bit print bug is fixed
 def _render_barcode_element(
     payload: str, symbology: str, box_w: int, box_h: int
 ) -> Image.Image:
@@ -207,17 +209,15 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
 
             elif obj_type == "image":
                 if obj.get("labelforge_qr_payload") is not None:
-                    payload = resolve_content(obj["labelforge_qr_payload"], values)
-                    sub = _render_qr_element(
-                        payload, obj.get("labelforge_qr_error_correction", "M"), box_w, box_h
+                    raise RenderError(
+                        "QR elements are not yet supported for printing"
+                        " (known bug: prints as a solid block)"
                     )
-                    _paste_onto(canvas, sub, left, top, angle)
                 elif obj.get("labelforge_barcode_payload") is not None:
-                    payload = resolve_content(obj["labelforge_barcode_payload"], values)
-                    sub = _render_barcode_element(
-                        payload, obj.get("labelforge_barcode_symbology", "code128"), box_w, box_h
+                    raise RenderError(
+                        "Barcode elements are not yet supported for printing"
+                        " (known bug: prints as a solid block)"
                     )
-                    _paste_onto(canvas, sub, left, top, angle)
                 else:
                     raise RenderError("Image elements not yet supported")
 

From 303bfdb82d63d94c2bb3fc4c0024fd58a6b69707 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:31:58 -0700
Subject: [PATCH 22/84] Add multi-stage frontend build to Dockerfile

---
 Dockerfile                 |   10 +-
 frontend/package-lock.json | 1156 ++++++++++++++++++++++++++++++++++++
 2 files changed, 1163 insertions(+), 3 deletions(-)
 create mode 100644 frontend/package-lock.json

diff --git a/Dockerfile b/Dockerfile
index 3acec2c..5c84282 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,6 +1,9 @@
-# TODO: Slice N — add a multi-stage frontend build stage (node:lts-alpine, npm ci + npm run build)
-#        before this runtime stage, then COPY --from=frontend /app/frontend/dist /app/frontend/dist
-#        and mount it via FastAPI StaticFiles.
+FROM node:lts-alpine AS frontend
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
 
 FROM python:3.12-slim
 
@@ -26,6 +29,7 @@ RUN pip install --no-cache-dir -e .
 # Default label catalog shipped in the image.  At startup, if
 # ${DATA_DIR}/labels.yml is absent, main.py copies this into the volume.
 COPY labels.yml /app/labels.yml
+COPY --from=frontend /app/frontend/dist /app/frontend/dist
 
 RUN chown -R labelforge:labelforge /app
 USER labelforge
diff --git a/frontend/package-lock.json b/frontend/package-lock.json
new file mode 100644
index 0000000..83e96d3
--- /dev/null
+++ b/frontend/package-lock.json
@@ -0,0 +1,1156 @@
+{
+  "name": "labelforge-frontend",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "labelforge-frontend",
+      "devDependencies": {
+        "typescript": "^5.7.2",
+        "vite": "^6.3.5"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
+      "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz",
+      "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz",
+      "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz",
+      "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz",
+      "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz",
+      "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz",
+      "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz",
+      "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz",
+      "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz",
+      "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz",
+      "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz",
+      "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz",
+      "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz",
+      "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz",
+      "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz",
+      "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz",
+      "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz",
+      "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz",
+      "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz",
+      "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz",
+      "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz",
+      "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz",
+      "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
+      "integrity": "sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.4.tgz",
+      "integrity": "sha512-GxxTKApUpzRhof7poWvCJHRF51C67u1R7D6DiluBE8wKU1u5GWE8t+v81JvJYtbawoBFX1hLv5Ei4eVjkWokaw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.4.tgz",
+      "integrity": "sha512-tua0TaJxMOB1R0V0RS1jFZ/RpURFDJIOR2A6jWwQeawuFyS4gBW+rntLRaQd0EQ4bd6Vp44Z2rXW+YYDBsj6IA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.4.tgz",
+      "integrity": "sha512-CSKq7MsP+5PFIcydhAiR1K0UhEI1A2jWXVKHPCBZ151yOutENwvnPocgVHkivu2kviURtCEB6zUQw0vs8RrhMg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.4.tgz",
+      "integrity": "sha512-+O8OkVdyvXMtJEciu2wS/pzm1IxntEEQx3z5TAVy4l32G0etZn+RsA48ARRrFm6Ri8fvqPQfgrvNxSjKAbnd3g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.4.tgz",
+      "integrity": "sha512-Iw3oMskH3AfNuhU0MSN7vNbdi4me/NiYo2azqPz/Le16zHSa+3RRmliCMWWQmh4lcndccU40xcJuTYJZxNo/lw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.4.tgz",
+      "integrity": "sha512-EIPRXTVQpHyF8WOo219AD2yEltPehLTcTMz2fn6JsatLYSzQf00hj3rulF+yauOlF9/FtM2WpkT/hJh/KJFGhA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.4.tgz",
+      "integrity": "sha512-J3Yh9PzzF1Ovah2At+lHiGQdsYgArxBbXv/zHfSyaiFQEqvNv7DcW98pCrmdjCZBrqBiKrKKe2V+aaSGWuBe/w==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.4.tgz",
+      "integrity": "sha512-BFDEZMYfUvLn37ONE1yMBojPxnMlTFsdyNoqncT0qFq1mAfllL+ATMMJd8TeuVMiX84s1KbcxcZbXInmcO2mRg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.4.tgz",
+      "integrity": "sha512-pc9EYOSlOgdQ2uPl1o9PF6/kLSgaUosia7gOuS8mB69IxJvlclko1MECXysjs5ryez1/5zjYqx3+xYU0TU6R1A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.4.tgz",
+      "integrity": "sha512-NxnomyxYerDh5n4iLrNa+sH+Z+U4BMEE46V2PgQ/hoB909i8gV1M5wPojWg9fk1jWpO3IQnOs20K4wyZuFLEFQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.4.tgz",
+      "integrity": "sha512-nbJnQ8a3z1mtmrwImCYhc6BGpThAyYVRQxw9uKSKG4wR6aAYno9sVjJ0zaZcW9BPJX1GbrDPf+SvdWjgTuDmnw==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.4.tgz",
+      "integrity": "sha512-2EU6acNrQLd8tYvo/LXW535wupT3m6fo7HKo6lr7ktQoItxTyOL1ZCR/GfGCuXl2vR+zmfI6eRXkSemafv+iVg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.4.tgz",
+      "integrity": "sha512-WeBtoMuaMxiiIrO2IYP3xs6GMWkJP2C0EoT8beTLkUPmzV1i/UcOSVw1d5r9KBODtHKilG5yFxsGRnBbK3wJ4A==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.4.tgz",
+      "integrity": "sha512-FJHFfqpKUI3A10WrWKiFbBZ7yVbGT4q4B5o1qKFFojqpaYoh9LrQgqWCmmcxQzVSXYtyB5bzkXrYzlHTs21MYA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.4.tgz",
+      "integrity": "sha512-mcEl6CUT5IAUmQf1m9FYSmVqCJlpQ8r8eyftFUHG8i9OhY7BkBXSUdnLH5DOf0wCOjcP9v/QO93zpmF1SptCCw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.4.tgz",
+      "integrity": "sha512-ynt3JxVd2w2buzoKDWIyiV1pJW93xlQic1THVLXilz429oijRpSHivZAgp65KBu+cMcgf1eVVjdnTLvPxgCuoQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-Boiz5+MsaROEWDf+GGEwF8VMHGhlUoQMtIPjOgA5fv4osupqTVnJteQNKJwUcnUog2G55jYXH7KZFFiJe0TEzQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.4.tgz",
+      "integrity": "sha512-+qfSY27qIrFfI/Hom04KYFw3GKZSGU4lXus51wsb5EuySfFlWRwjkKWoE9emgRw/ukoT4Udsj4W/+xxG8VbPKg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.4.tgz",
+      "integrity": "sha512-VpTfOPHgVXEBeeR8hZ2O0F3aSso+JDWqTWmTmzcQKted54IAdUVbxE+j/MVxUsKa8L20HJhv3vUezVPoquqWjA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.4.tgz",
+      "integrity": "sha512-IPOsh5aRYuLv/nkU51X10Bf75Bsf6+gZdx1X+QP5QM6lIJFHHqbHLG0uJn/hWthzo13UAc2umiUorqZy3axoZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.4.tgz",
+      "integrity": "sha512-4QzE9E81OohJ/HKzHhsqU+zcYYojVOXlFMs1DdyMT6qXl/niOH7AVElmmEdUNHHS/oRkc++d5k6Vy85zFs0DEw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.4.tgz",
+      "integrity": "sha512-zTPgT1YuHHcd+Tmx7h8aml0FWFVelV5N54oHow9SLj+GfoDy/huQ+UV396N/C7KpMDMiPspRktzM1/0r1usYEA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-DRS4G7mi9lJxqEDezIkKCaUIKCrLUUDCUaCsTPCi/rtqaC6D/jjwslMQyiDU50Ka0JKpeXeRBFBAXwArY52vBw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.4.tgz",
+      "integrity": "sha512-QVTUovf40zgTqlFVrKA1uXMVvU2QWEFWfAH8Wdc48IxLvrJMQVMBRjuQyUpzZCDkakImib9eVazbWlC6ksWtJw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/esbuild": {
+      "version": "0.25.12",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
+      "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.25.12",
+        "@esbuild/android-arm": "0.25.12",
+        "@esbuild/android-arm64": "0.25.12",
+        "@esbuild/android-x64": "0.25.12",
+        "@esbuild/darwin-arm64": "0.25.12",
+        "@esbuild/darwin-x64": "0.25.12",
+        "@esbuild/freebsd-arm64": "0.25.12",
+        "@esbuild/freebsd-x64": "0.25.12",
+        "@esbuild/linux-arm": "0.25.12",
+        "@esbuild/linux-arm64": "0.25.12",
+        "@esbuild/linux-ia32": "0.25.12",
+        "@esbuild/linux-loong64": "0.25.12",
+        "@esbuild/linux-mips64el": "0.25.12",
+        "@esbuild/linux-ppc64": "0.25.12",
+        "@esbuild/linux-riscv64": "0.25.12",
+        "@esbuild/linux-s390x": "0.25.12",
+        "@esbuild/linux-x64": "0.25.12",
+        "@esbuild/netbsd-arm64": "0.25.12",
+        "@esbuild/netbsd-x64": "0.25.12",
+        "@esbuild/openbsd-arm64": "0.25.12",
+        "@esbuild/openbsd-x64": "0.25.12",
+        "@esbuild/openharmony-arm64": "0.25.12",
+        "@esbuild/sunos-x64": "0.25.12",
+        "@esbuild/win32-arm64": "0.25.12",
+        "@esbuild/win32-ia32": "0.25.12",
+        "@esbuild/win32-x64": "0.25.12"
+      }
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.12",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.12",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
+      "integrity": "sha512-WHeFSbZYsPu3+bLoNRUuAO+wavNlocOPf3wSHTP7hcFKVnJeWsYlCDbr3mTS14FCizf9ccIxXA8sGL8zKeQN3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.8"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.60.4",
+        "@rollup/rollup-android-arm64": "4.60.4",
+        "@rollup/rollup-darwin-arm64": "4.60.4",
+        "@rollup/rollup-darwin-x64": "4.60.4",
+        "@rollup/rollup-freebsd-arm64": "4.60.4",
+        "@rollup/rollup-freebsd-x64": "4.60.4",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.60.4",
+        "@rollup/rollup-linux-arm-musleabihf": "4.60.4",
+        "@rollup/rollup-linux-arm64-gnu": "4.60.4",
+        "@rollup/rollup-linux-arm64-musl": "4.60.4",
+        "@rollup/rollup-linux-loong64-gnu": "4.60.4",
+        "@rollup/rollup-linux-loong64-musl": "4.60.4",
+        "@rollup/rollup-linux-ppc64-gnu": "4.60.4",
+        "@rollup/rollup-linux-ppc64-musl": "4.60.4",
+        "@rollup/rollup-linux-riscv64-gnu": "4.60.4",
+        "@rollup/rollup-linux-riscv64-musl": "4.60.4",
+        "@rollup/rollup-linux-s390x-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-musl": "4.60.4",
+        "@rollup/rollup-openbsd-x64": "4.60.4",
+        "@rollup/rollup-openharmony-arm64": "4.60.4",
+        "@rollup/rollup-win32-arm64-msvc": "4.60.4",
+        "@rollup/rollup-win32-ia32-msvc": "4.60.4",
+        "@rollup/rollup-win32-x64-gnu": "4.60.4",
+        "@rollup/rollup-win32-x64-msvc": "4.60.4",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.16",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/vite": {
+      "version": "6.4.2",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.2.tgz",
+      "integrity": "sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.25.0",
+        "fdir": "^6.4.4",
+        "picomatch": "^4.0.2",
+        "postcss": "^8.5.3",
+        "rollup": "^4.34.9",
+        "tinyglobby": "^0.2.13"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^18.0.0 || ^20.0.0 || >=22.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^18.0.0 || ^20.0.0 || >=22.0.0",
+        "jiti": ">=1.21.0",
+        "less": "*",
+        "lightningcss": "^1.21.0",
+        "sass": "*",
+        "sass-embedded": "*",
+        "stylus": "*",
+        "sugarss": "*",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    }
+  }
+}

From c3e6919555fc6758acc3802fc40507ffb8eab299 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:32:31 -0700
Subject: [PATCH 23/84] Serve built frontend SPA from FastAPI

---
 backend/labelforge/main.py | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 3db3042..afd9349 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -3,7 +3,9 @@
 from contextlib import asynccontextmanager
 from pathlib import Path
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
 
 from labelforge.catalog.loader import load_catalog
 from labelforge.config import settings
@@ -67,3 +69,19 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
 app.include_router(settings_router.router, prefix="/api")
 app.include_router(templates_router.router, prefix="/api")
 app.include_router(template_print_router.router, prefix="/api")
+
+_FRONTEND_DIST = Path("/app/frontend/dist")
+
+if _FRONTEND_DIST.exists():
+    app.mount(
+        "/assets",
+        StaticFiles(directory=_FRONTEND_DIST / "assets"),
+        name="assets",
+    )
+
+    @app.get("/{full_path:path}", include_in_schema=False)
+    async def spa_fallback(request: Request, full_path: str) -> FileResponse:
+        if full_path.startswith("api/"):
+            from fastapi import HTTPException
+            raise HTTPException(status_code=404)
+        return FileResponse(_FRONTEND_DIST / "index.html")

From 627a4fd78dd26769f72fea3a4da185b18a2892f6 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:33:35 -0700
Subject: [PATCH 24/84] Add client-side routing and nav to the SPA

---
 frontend/index.html             |  4 ++++
 frontend/src/main.ts            |  6 ++++-
 frontend/src/pages/templates.ts |  8 +++++++
 frontend/src/router.ts          | 39 +++++++++++++++++++++++++++++++++
 frontend/src/style.css          | 22 +++++++++++++++++++
 5 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/pages/templates.ts
 create mode 100644 frontend/src/router.ts

diff --git a/frontend/index.html b/frontend/index.html
index 7b26961..bd6a74f 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -6,6 +6,10 @@
     <title>LabelForge</title>
   </head>
   <body>
+    <nav id="nav">
+      <a href="/" data-route="/">Quick Print</a>
+      <a href="/templates" data-route="/templates">Templates</a>
+    </nav>
     <div id="app"></div>
     <script type="module" src="/src/main.ts"></script>
   </body>
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index b3b3711..4fab5fd 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -1,4 +1,8 @@
 import './style.css'
 import { mountQuickPrint } from './pages/quick-print'
+import { mountTemplates } from './pages/templates'
+import { initRouter, register } from './router'
 
-mountQuickPrint(document.getElementById('app')!)
+register('/', mountQuickPrint)
+register('/templates', mountTemplates)
+initRouter()
diff --git a/frontend/src/pages/templates.ts b/frontend/src/pages/templates.ts
new file mode 100644
index 0000000..b67b5d3
--- /dev/null
+++ b/frontend/src/pages/templates.ts
@@ -0,0 +1,8 @@
+export function mountTemplates(root: HTMLElement): void {
+  root.innerHTML = `
+    <div class="quick-print">
+      <h2>Templates</h2>
+      <p>Coming soon.</p>
+    </div>
+  `
+}
diff --git a/frontend/src/router.ts b/frontend/src/router.ts
new file mode 100644
index 0000000..3d200e4
--- /dev/null
+++ b/frontend/src/router.ts
@@ -0,0 +1,39 @@
+type MountFn = (root: HTMLElement) => void
+
+const routes: Record<string, MountFn> = {}
+
+export function register(path: string, mount: MountFn): void {
+  routes[path] = mount
+}
+
+function setActiveNav(path: string): void {
+  document.querySelectorAll<HTMLAnchorElement>('[data-route]').forEach(a => {
+    a.classList.toggle('active', a.dataset.route === path)
+  })
+}
+
+export function navigate(path: string): void {
+  history.pushState(null, '', path)
+  render(path)
+}
+
+function render(path: string): void {
+  const root = document.getElementById('app')
+  if (!root) return
+  const mount = routes[path] ?? routes['/']
+  if (mount) {
+    setActiveNav(path)
+    mount(root)
+  }
+}
+
+export function initRouter(): void {
+  document.addEventListener('click', e => {
+    const target = (e.target as HTMLElement).closest<HTMLAnchorElement>('[data-route]')
+    if (!target) return
+    e.preventDefault()
+    navigate(target.dataset.route!)
+  })
+  window.addEventListener('popstate', () => render(window.location.pathname))
+  render(window.location.pathname)
+}
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 9d8b79c..cf4329a 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -130,6 +130,28 @@ button:disabled {
   border-radius: 4px;
 }
 
+/* nav */
+#nav {
+  max-width: 520px;
+  margin: 0 auto 1rem;
+  display: flex;
+  gap: 1.25rem;
+}
+
+#nav a {
+  text-decoration: none;
+  color: #1a1a1a;
+  font-size: 0.875rem;
+  padding: 0.2rem 0;
+  border-bottom: 2px solid transparent;
+}
+
+#nav a.active {
+  border-bottom-color: #1a6fdb;
+  color: #1a6fdb;
+  font-weight: 600;
+}
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;

From eb451f3c624d9035e1621fd4e46178df500f2f12 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:51:52 -0700
Subject: [PATCH 25/84] Add Fabric.js dependency and template API client

---
 frontend/package.json |  3 +++
 frontend/src/api.ts   | 48 ++++++++++++++++++++++++++++++++++++++++++-
 frontend/src/types.ts | 26 +++++++++++++++++++++++
 3 files changed, 76 insertions(+), 1 deletion(-)

diff --git a/frontend/package.json b/frontend/package.json
index ce02cf0..5d63f68 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -7,6 +7,9 @@
     "build": "tsc && vite build",
     "preview": "vite preview"
   },
+  "dependencies": {
+    "fabric": "6.6.1"
+  },
   "devDependencies": {
     "typescript": "^5.7.2",
     "vite": "^6.3.5"
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index e3da719..854450f 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -1,4 +1,4 @@
-import type { FontInfo, LabelEntry, PrintJobResponse, QuickPrintRequest } from './types'
+import type { FontInfo, LabelEntry, PrintJobResponse, QuickPrintRequest, Template, TemplateCreate } from './types'
 
 export const TOKEN_KEY = 'labelforge_token'
 
@@ -61,6 +61,52 @@ export async function previewQuick(req: QuickPrintRequest): Promise<Blob> {
   return res.blob()
 }
 
+export function listTemplates(): Promise<Template[]> {
+  return apiFetch<Template[]>('/api/templates')
+}
+
+export function getTemplate(name: string): Promise<Template> {
+  return apiFetch<Template>(`/api/templates/${encodeURIComponent(name)}`)
+}
+
+export function createTemplate(body: TemplateCreate): Promise<Template> {
+  return apiFetch<Template>('/api/templates', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+}
+
+export function updateTemplate(name: string, body: Partial<TemplateCreate>): Promise<Template> {
+  return apiFetch<Template>(`/api/templates/${encodeURIComponent(name)}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  })
+}
+
+export function deleteTemplate(name: string): Promise<void> {
+  return apiFetch<void>(`/api/templates/${encodeURIComponent(name)}`, { method: 'DELETE' })
+}
+
+export async function previewTemplate(name: string, fields: Record<string, string>): Promise<Blob> {
+  const res = await fetch(`/api/preview/${encodeURIComponent(name)}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${getToken()}`,
+    },
+    body: JSON.stringify({ fields }),
+  })
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`
+    try {
+      const body = await res.json() as { detail?: unknown }
+      if (body.detail) detail = String(body.detail)
+    } catch { /* use status fallback */ }
+    throw new Error(detail)
+  }
+  return res.blob()
+}
+
 export function getSettings(): Promise<Record<string, unknown>> {
   return apiFetch<Record<string, unknown>>('/api/settings')
 }
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 3c3ebac..39611fd 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -37,3 +37,29 @@ export interface PrintJobResponse {
   status: string;
   preview_url: string | null;
 }
+
+export interface FieldSpec {
+  name: string;
+  type: 'text' | 'number' | 'date' | 'enum';
+  required: boolean;
+  default: string | null;
+  increment: boolean;
+  enum_values: string[];
+}
+
+export interface Template {
+  name: string;
+  display_name: string;
+  label_media: string;
+  canvas_json: Record<string, unknown>;
+  field_schema: FieldSpec[];
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface TemplateCreate {
+  name: string;
+  display_name?: string;
+  label_media: string;
+  canvas_json: Record<string, unknown>;
+}

From a2c5d96c320ea86359f9451075da6f49537c75a4 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:53:15 -0700
Subject: [PATCH 26/84] Add templates list page

---
 frontend/src/main.ts                 |   4 +-
 frontend/src/pages/templates-list.ts | 204 +++++++++++++++++++++++++++
 frontend/src/pages/templates.ts      |   9 +-
 frontend/src/router.ts               |  27 +++-
 frontend/src/style.css               | 165 ++++++++++++++++++++++
 5 files changed, 396 insertions(+), 13 deletions(-)
 create mode 100644 frontend/src/pages/templates-list.ts

diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index 4fab5fd..c55688a 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -1,8 +1,10 @@
 import './style.css'
 import { mountQuickPrint } from './pages/quick-print'
 import { mountTemplates } from './pages/templates'
-import { initRouter, register } from './router'
+import { mountTemplateEditor } from './pages/template-editor'
+import { initRouter, register, registerPrefix } from './router'
 
 register('/', mountQuickPrint)
 register('/templates', mountTemplates)
+registerPrefix('/templates/', mountTemplateEditor)
 initRouter()
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
new file mode 100644
index 0000000..44b114b
--- /dev/null
+++ b/frontend/src/pages/templates-list.ts
@@ -0,0 +1,204 @@
+import { deleteTemplate, listTemplates } from '../api'
+import type { Template } from '../types'
+import { navigate } from '../router'
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function fmtDate(iso: string | undefined): string {
+  if (!iso) return '—'
+  try {
+    return new Date(iso).toLocaleString()
+  } catch {
+    return iso
+  }
+}
+
+export function mountTemplatesList(root: HTMLElement): void {
+  root.innerHTML = `
+    <div class="templates-list">
+      <div class="templates-list-header">
+        <h2>Templates</h2>
+        <button id="btn-new-template">New template</button>
+      </div>
+      <div id="tpl-status" class="status-msg" hidden></div>
+      <div id="tpl-body"></div>
+    </div>
+  `
+
+  const btnNew = root.querySelector<HTMLButtonElement>('#btn-new-template')!
+  const statusEl = root.querySelector<HTMLDivElement>('#tpl-status')!
+  const bodyEl = root.querySelector<HTMLDivElement>('#tpl-body')!
+
+  function showStatus(msg: string, kind: 'success' | 'error'): void {
+    statusEl.textContent = msg
+    statusEl.className = `status-msg ${kind}`
+    statusEl.hidden = false
+  }
+
+  function renderList(templates: Template[]): void {
+    if (templates.length === 0) {
+      bodyEl.innerHTML = `<p class="empty-state">No templates yet. Create one.</p>`
+      return
+    }
+    bodyEl.innerHTML = `
+      <table class="tpl-table">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Media</th>
+            <th>Updated</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody>
+          ${templates.map(t => `
+            <tr data-name="${esc(t.name)}">
+              <td>${esc(t.display_name || t.name)}</td>
+              <td><code>${esc(t.label_media)}</code></td>
+              <td>${esc(fmtDate(t.updated_at))}</td>
+              <td class="tpl-actions">
+                <button class="btn-edit" data-name="${esc(t.name)}">Edit</button>
+                <button class="btn-delete" data-name="${esc(t.name)}">Delete</button>
+              </td>
+            </tr>
+          `).join('')}
+        </tbody>
+      </table>
+    `
+
+    bodyEl.querySelectorAll<HTMLButtonElement>('.btn-edit').forEach(btn => {
+      btn.addEventListener('click', () => navigate(`/templates/${btn.dataset.name!}`))
+    })
+
+    bodyEl.querySelectorAll<HTMLButtonElement>('.btn-delete').forEach(btn => {
+      btn.addEventListener('click', async () => {
+        const name = btn.dataset.name!
+        if (!confirm(`Delete template "${name}"? This cannot be undone.`)) return
+        btn.disabled = true
+        try {
+          await deleteTemplate(name)
+          await load()
+        } catch (err) {
+          showStatus((err as Error).message, 'error')
+          btn.disabled = false
+        }
+      })
+    })
+  }
+
+  async function load(): Promise<void> {
+    bodyEl.innerHTML = `<p>Loading…</p>`
+    statusEl.hidden = true
+    try {
+      const templates = await listTemplates()
+      renderList(templates)
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+      bodyEl.innerHTML = ''
+    }
+  }
+
+  btnNew.addEventListener('click', () => {
+    showNewTemplateModal(root, () => load())
+  })
+
+  void load()
+}
+
+function showNewTemplateModal(root: HTMLElement, onCreated: () => void): void {
+  import('../api').then(({ getLabels }) => {
+    const overlay = document.createElement('div')
+    overlay.className = 'modal-overlay'
+    overlay.innerHTML = `
+      <div class="modal">
+        <h3>New template</h3>
+        <div class="modal-status" hidden></div>
+        <label>
+          Name (slug)
+          <input id="modal-name" type="text" placeholder="my-template" autocomplete="off" />
+          <span class="field-error" id="name-error" hidden></span>
+        </label>
+        <label>
+          Label media
+          <select id="modal-media"><option value="">Loading…</option></select>
+        </label>
+        <div class="modal-actions">
+          <button id="modal-cancel">Cancel</button>
+          <button id="modal-ok" class="btn-primary" disabled>Create</button>
+        </div>
+      </div>
+    `
+    document.body.appendChild(overlay)
+
+    const nameInput = overlay.querySelector<HTMLInputElement>('#modal-name')!
+    const mediaSelect = overlay.querySelector<HTMLSelectElement>('#modal-media')!
+    const cancelBtn = overlay.querySelector<HTMLButtonElement>('#modal-cancel')!
+    const okBtn = overlay.querySelector<HTMLButtonElement>('#modal-ok')!
+    const nameError = overlay.querySelector<HTMLSpanElement>('#name-error')!
+
+    const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
+    const FORM_FACTOR_LABEL: Record<number, string> = { 1: 'Die-cut', 2: 'Continuous', 3: 'Round', 4: 'P-touch Continuous' }
+    const FF_ORDER = [2, 1, 3, 4]
+
+    function esc2(s: string): string {
+      return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    }
+
+    function validate(): boolean {
+      const v = nameInput.value.trim()
+      if (!v) { nameError.textContent = 'Name is required'; nameError.hidden = false; return false }
+      if (!SLUG_RE.test(v)) { nameError.textContent = 'Use lowercase letters, numbers, hyphens only'; nameError.hidden = false; return false }
+      nameError.hidden = true
+      return true
+    }
+
+    function updateOk(): void {
+      okBtn.disabled = !nameInput.value.trim() || !mediaSelect.value
+    }
+
+    nameInput.addEventListener('input', () => { validate(); updateOk() })
+    mediaSelect.addEventListener('change', updateOk)
+
+    getLabels().then(labels => {
+      import('../pages/quick-print').then(() => {
+        const groups = new Map<number, typeof labels>()
+        for (const l of labels) {
+          if (!groups.has(l.form_factor)) groups.set(l.form_factor, [])
+          groups.get(l.form_factor)!.push(l)
+        }
+        for (const entries of groups.values()) entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
+        const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
+        mediaSelect.innerHTML = allKeys
+          .filter(k => groups.has(k))
+          .map(k => {
+            const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
+            const opts = groups.get(k)!.map(l => `<option value="${esc2(l.id)}">${esc2(l.display_name)}</option>`).join('')
+            return `<optgroup label="${esc2(groupLabel)}">${opts}</optgroup>`
+          })
+          .join('')
+        updateOk()
+      })
+    })
+
+    cancelBtn.addEventListener('click', () => overlay.remove())
+    overlay.addEventListener('click', e => { if (e.target === overlay) overlay.remove() })
+
+    okBtn.addEventListener('click', () => {
+      if (!validate()) return
+      const name = nameInput.value.trim()
+      const media = mediaSelect.value
+      overlay.remove()
+      // Navigate to editor — template created on first Save
+      navigate(`/templates/${name}?new=1&media=${encodeURIComponent(media)}`)
+      onCreated()
+    })
+
+    nameInput.focus()
+  })
+}
diff --git a/frontend/src/pages/templates.ts b/frontend/src/pages/templates.ts
index b67b5d3..12984b2 100644
--- a/frontend/src/pages/templates.ts
+++ b/frontend/src/pages/templates.ts
@@ -1,8 +1 @@
-export function mountTemplates(root: HTMLElement): void {
-  root.innerHTML = `
-    <div class="quick-print">
-      <h2>Templates</h2>
-      <p>Coming soon.</p>
-    </div>
-  `
-}
+export { mountTemplatesList as mountTemplates } from './templates-list'
diff --git a/frontend/src/router.ts b/frontend/src/router.ts
index 3d200e4..ab591a6 100644
--- a/frontend/src/router.ts
+++ b/frontend/src/router.ts
@@ -1,14 +1,20 @@
 type MountFn = (root: HTMLElement) => void
 
 const routes: Record<string, MountFn> = {}
+const prefixRoutes: Array<{ prefix: string; mount: MountFn }> = []
 
 export function register(path: string, mount: MountFn): void {
   routes[path] = mount
 }
 
+/** Register a handler for all paths that start with `prefix`. */
+export function registerPrefix(prefix: string, mount: MountFn): void {
+  prefixRoutes.push({ prefix, mount })
+}
+
 function setActiveNav(path: string): void {
   document.querySelectorAll<HTMLAnchorElement>('[data-route]').forEach(a => {
-    a.classList.toggle('active', a.dataset.route === path)
+    a.classList.toggle('active', a.dataset.route === path || path.startsWith(a.dataset.route! + '/'))
   })
 }
 
@@ -20,10 +26,23 @@ export function navigate(path: string): void {
 function render(path: string): void {
   const root = document.getElementById('app')
   if (!root) return
-  const mount = routes[path] ?? routes['/']
-  if (mount) {
+  const exact = routes[path]
+  if (exact) {
+    setActiveNav(path)
+    exact(root)
+    return
+  }
+  for (const { prefix, mount } of prefixRoutes) {
+    if (path.startsWith(prefix)) {
+      setActiveNav(path)
+      mount(root)
+      return
+    }
+  }
+  const fallback = routes['/']
+  if (fallback) {
     setActiveNav(path)
-    mount(root)
+    fallback(root)
   }
 }
 
diff --git a/frontend/src/style.css b/frontend/src/style.css
index cf4329a..e200acb 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -152,6 +152,171 @@ button:disabled {
   font-weight: 600;
 }
 
+/* templates list */
+.templates-list {
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 1.5rem;
+}
+
+.templates-list-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 1.25rem;
+}
+
+.templates-list-header h2 {
+  margin: 0;
+}
+
+.tpl-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+
+.tpl-table th,
+.tpl-table td {
+  text-align: left;
+  padding: 0.4rem 0.6rem;
+  border-bottom: 1px solid #eee;
+}
+
+.tpl-table th {
+  font-size: 0.8rem;
+  color: #666;
+  font-weight: 600;
+}
+
+.tpl-actions {
+  display: flex;
+  gap: 0.5rem;
+  justify-content: flex-end;
+}
+
+.empty-state {
+  color: #888;
+  font-size: 0.9rem;
+}
+
+/* modal */
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0,0,0,0.35);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 100;
+}
+
+.modal {
+  background: #fff;
+  border-radius: 8px;
+  padding: 1.5rem;
+  min-width: 320px;
+  max-width: 420px;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.modal h3 {
+  margin: 0;
+}
+
+.modal label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.modal-actions {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: flex-end;
+  margin-top: 0.5rem;
+}
+
+.btn-primary {
+  background: #1a6fdb;
+  color: #fff;
+  border-color: #1a6fdb;
+  font-weight: 600;
+}
+
+.btn-primary:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.field-error {
+  font-size: 0.8rem;
+  color: #c0392b;
+  font-weight: normal;
+}
+
+/* template editor */
+.editor-shell {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+.editor-toolbar {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid #ddd;
+  background: #fafafa;
+  flex-wrap: wrap;
+}
+
+.editor-toolbar .toolbar-sep {
+  width: 1px;
+  height: 1.25rem;
+  background: #ddd;
+  margin: 0 0.25rem;
+}
+
+.editor-toolbar .editor-title {
+  font-weight: 600;
+  font-size: 0.9rem;
+  margin-right: 0.5rem;
+}
+
+.editor-canvas-wrap {
+  overflow: auto;
+  background: #e0e0e0;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 1.5rem;
+  min-height: 400px;
+}
+
+.editor-canvas-inner {
+  position: relative;
+  box-shadow: 0 2px 12px rgba(0,0,0,0.18);
+}
+
+.editor-status {
+  padding: 0.4rem 0.75rem;
+  font-size: 0.8rem;
+  min-height: 1.6rem;
+}
+
+.editor-status.success { color: #1a5c2a; background: #e6f4ea; }
+.editor-status.error   { color: #7a1a14; background: #fdecea; }
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;

From 40213fd1460c2663723252d480bcfc10a648385a Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:56:01 -0700
Subject: [PATCH 27/84] Add template editor with text elements and save/load

---
 frontend/src/editor/canvas.ts         |  86 +++++++++
 frontend/src/pages/template-editor.ts | 241 ++++++++++++++++++++++++++
 frontend/src/pages/templates-list.ts  |  34 ++--
 3 files changed, 343 insertions(+), 18 deletions(-)
 create mode 100644 frontend/src/editor/canvas.ts
 create mode 100644 frontend/src/pages/template-editor.ts

diff --git a/frontend/src/editor/canvas.ts b/frontend/src/editor/canvas.ts
new file mode 100644
index 0000000..2a5cb04
--- /dev/null
+++ b/frontend/src/editor/canvas.ts
@@ -0,0 +1,86 @@
+import { Canvas, IText } from 'fabric'
+import type { FabricObject } from 'fabric'
+
+export const CUSTOM_PROPS = ['labelforge_raw_content'] as const
+
+/** Create a Fabric Canvas sized to label pixels, displayed scaled to fit the container. */
+export function initCanvas(
+  el: HTMLCanvasElement,
+  labelW: number,
+  labelH: number,
+  containerW: number,
+): { canvas: Canvas; scale: number } {
+  const maxDisplayH = 600
+  const scale = Math.min(1, (containerW - 48) / labelW, maxDisplayH / labelH)
+  const displayW = Math.round(labelW * scale)
+  const displayH = Math.round(labelH * scale)
+
+  const canvas = new Canvas(el, {
+    backgroundColor: '#ffffff',
+    selection: true,
+  })
+  canvas.setDimensions({ width: displayW, height: displayH })
+  canvas.setZoom(scale)
+
+  // Sync labelforge_raw_content whenever text is edited inline
+  canvas.on('text:changed', (e: { target: FabricObject }) => {
+    const obj = e.target as FabricObject & { text?: string }
+    ;(obj as Record<string, unknown>)['labelforge_raw_content'] = obj.text ?? ''
+  })
+
+  return { canvas, scale }
+}
+
+export function addTextElement(canvas: Canvas, defaultFont: string): void {
+  const vp = canvas.viewportTransform ?? [1, 0, 0, 1, 0, 0]
+  const scale = vp[0]
+  const canvasVirtualW = (canvas.width ?? 400) / scale
+  const canvasVirtualH = (canvas.height ?? 200) / scale
+
+  const text = new IText('Text', {
+    left: Math.round(canvasVirtualW * 0.05),
+    top: Math.round(canvasVirtualH * 0.05),
+    fontFamily: defaultFont,
+    fontSize: 48,
+    fill: '#000000',
+  })
+  ;(text as Record<string, unknown>)['labelforge_raw_content'] = 'Text'
+
+  // Keep raw content in sync when text changes
+  text.on('changed', () => {
+    ;(text as Record<string, unknown>)['labelforge_raw_content'] = text.text ?? ''
+  })
+
+  canvas.add(text)
+  canvas.setActiveObject(text)
+  canvas.renderAll()
+}
+
+export function deleteSelected(canvas: Canvas): void {
+  const active = canvas.getActiveObjects()
+  if (active.length === 0) return
+  active.forEach(obj => canvas.remove(obj))
+  canvas.discardActiveObject()
+  canvas.renderAll()
+}
+
+export function getCanvasJSON(canvas: Canvas): Record<string, unknown> {
+  return canvas.toJSON([...CUSTOM_PROPS]) as Record<string, unknown>
+}
+
+export async function loadCanvasJSON(
+  canvas: Canvas,
+  json: Record<string, unknown>,
+): Promise<void> {
+  await canvas.loadFromJSON(json)
+  // Re-attach raw content sync to each loaded text object
+  canvas.getObjects().forEach(obj => {
+    if (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox') {
+      const t = obj as IText
+      t.on('changed', () => {
+        ;(t as Record<string, unknown>)['labelforge_raw_content'] = t.text ?? ''
+      })
+    }
+  })
+  canvas.renderAll()
+}
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
new file mode 100644
index 0000000..5b650a5
--- /dev/null
+++ b/frontend/src/pages/template-editor.ts
@@ -0,0 +1,241 @@
+import { createTemplate, getFonts, getLabels, getTemplate, previewTemplate, updateTemplate } from '../api'
+import { navigate } from '../router'
+import type { LabelEntry } from '../types'
+import {
+  addTextElement,
+  deleteSelected,
+  getCanvasJSON,
+  initCanvas,
+  loadCanvasJSON,
+} from '../editor/canvas'
+import type { Canvas } from 'fabric'
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function parsePath(): { name: string; isNew: boolean; newMedia: string } {
+  const path = window.location.pathname  // /templates/my-name
+  const parts = path.split('/')
+  const name = decodeURIComponent(parts[parts.length - 1] ?? '')
+  const params = new URLSearchParams(window.location.search)
+  const isNew = params.get('new') === '1'
+  const newMedia = params.get('media') ?? ''
+  return { name, isNew, newMedia }
+}
+
+export function mountTemplateEditor(root: HTMLElement): void {
+  const { name, isNew, newMedia } = parsePath()
+
+  root.innerHTML = `
+    <div class="editor-shell">
+      <div class="editor-toolbar">
+        <button id="btn-back">← Back</button>
+        <span class="toolbar-sep"></span>
+        <span class="editor-title" id="editor-title">${esc(name)}</span>
+        <span class="toolbar-sep"></span>
+        <button id="btn-add-text">Add Text</button>
+        <button id="btn-delete">Delete</button>
+        <span class="toolbar-sep"></span>
+        <select id="font-select" title="Font family" style="max-width:160px">
+          <option value="">Loading fonts…</option>
+        </select>
+        <input id="font-size" type="number" min="6" max="400" value="48" title="Font size" style="width:60px" />
+        <span class="toolbar-sep"></span>
+        <button id="btn-preview">Preview</button>
+        <button id="btn-save" class="btn-primary">Save</button>
+      </div>
+      <div id="editor-status" class="editor-status" hidden></div>
+      <div class="editor-canvas-wrap" id="canvas-wrap">
+        <div class="editor-canvas-inner" id="canvas-inner">
+          <canvas id="fabric-canvas"></canvas>
+        </div>
+      </div>
+      <div id="preview-area" class="preview-area" hidden style="padding:1rem">
+        <img id="preview-img" alt="Server render preview" style="max-width:100%;border:1px solid #ddd" />
+      </div>
+    </div>
+  `
+
+  const btnBack = root.querySelector<HTMLButtonElement>('#btn-back')!
+  const btnAddText = root.querySelector<HTMLButtonElement>('#btn-add-text')!
+  const btnDelete = root.querySelector<HTMLButtonElement>('#btn-delete')!
+  const btnSave = root.querySelector<HTMLButtonElement>('#btn-save')!
+  const btnPreview = root.querySelector<HTMLButtonElement>('#btn-preview')!
+  const fontSelect = root.querySelector<HTMLSelectElement>('#font-select')!
+  const fontSizeInput = root.querySelector<HTMLInputElement>('#font-size')!
+  const statusEl = root.querySelector<HTMLDivElement>('#editor-status')!
+  const canvasWrap = root.querySelector<HTMLDivElement>('#canvas-wrap')!
+  const previewArea = root.querySelector<HTMLDivElement>('#preview-area')!
+  const previewImg = root.querySelector<HTMLImageElement>('#preview-img')!
+
+  let fabricCanvas: Canvas | null = null
+  let labelMedia: string = newMedia
+  let existsOnServer = !isNew
+  let defaultFont = 'DejaVuSans'
+  let previewObjectUrl: string | null = null
+
+  function showStatus(msg: string, kind: 'success' | 'error' | ''): void {
+    if (!msg) { statusEl.hidden = true; return }
+    statusEl.textContent = msg
+    statusEl.className = `editor-status ${kind}`
+    statusEl.hidden = false
+  }
+
+  function getContainerWidth(): number {
+    return canvasWrap.clientWidth || 800
+  }
+
+  async function initEditor(label: LabelEntry): Promise<void> {
+    labelMedia = label.id
+    const [w, h] = label.dots_printable
+    const canvasEl = root.querySelector<HTMLCanvasElement>('#fabric-canvas')!
+    const { canvas } = initCanvas(canvasEl, w, h, getContainerWidth())
+    fabricCanvas = canvas
+
+    // Track selection to drive font controls
+    canvas.on('selection:created', updateFontControls)
+    canvas.on('selection:updated', updateFontControls)
+    canvas.on('selection:cleared', () => {})
+  }
+
+  function updateFontControls(): void {
+    if (!fabricCanvas) return
+    const obj = fabricCanvas.getActiveObject() as (Record<string, unknown> & { fontFamily?: string; fontSize?: number }) | null
+    if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+      if (obj.fontFamily) fontSelect.value = String(obj.fontFamily)
+      if (obj.fontSize) fontSizeInput.value = String(Math.round(Number(obj.fontSize)))
+    }
+  }
+
+  fontSelect.addEventListener('change', () => {
+    if (!fabricCanvas) return
+    const obj = fabricCanvas.getActiveObject()
+    if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+      obj.set({ fontFamily: fontSelect.value } as Parameters<typeof obj.set>[0])
+      fabricCanvas.renderAll()
+    }
+  })
+
+  fontSizeInput.addEventListener('change', () => {
+    if (!fabricCanvas) return
+    const sz = parseInt(fontSizeInput.value, 10)
+    if (!isNaN(sz) && sz >= 6) {
+      const obj = fabricCanvas.getActiveObject()
+      if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+        obj.set({ fontSize: sz } as Parameters<typeof obj.set>[0])
+        fabricCanvas.renderAll()
+      }
+    }
+  })
+
+  btnBack.addEventListener('click', () => navigate('/templates'))
+
+  btnAddText.addEventListener('click', () => {
+    if (!fabricCanvas) return
+    addTextElement(fabricCanvas, fontSelect.value || defaultFont)
+  })
+
+  btnDelete.addEventListener('click', () => {
+    if (!fabricCanvas) return
+    deleteSelected(fabricCanvas)
+  })
+
+  btnSave.addEventListener('click', () => void doSave())
+
+  btnPreview.addEventListener('click', () => void doPreview())
+
+  async function doSave(): Promise<void> {
+    if (!fabricCanvas) return
+    const objs = fabricCanvas.getObjects()
+    if (objs.length === 0) {
+      showStatus('Add at least one element before saving.', 'error')
+      return
+    }
+    btnSave.disabled = true
+    showStatus('', '')
+    try {
+      const canvasJson = getCanvasJSON(fabricCanvas)
+      if (existsOnServer) {
+        await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia })
+      } else {
+        await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson })
+        existsOnServer = true
+      }
+      showStatus('Saved.', 'success')
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+    } finally {
+      btnSave.disabled = false
+    }
+  }
+
+  async function doPreview(): Promise<void> {
+    if (!fabricCanvas) return
+    btnPreview.disabled = true
+    showStatus('', '')
+    try {
+      // Save first so server has the latest canvas
+      const objs = fabricCanvas.getObjects()
+      if (objs.length > 0) {
+        const canvasJson = getCanvasJSON(fabricCanvas)
+        if (existsOnServer) {
+          await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia })
+        } else {
+          await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson })
+          existsOnServer = true
+        }
+      }
+      // Build a fields dict: use field name as its own placeholder value for preview
+      const fields: Record<string, string> = {}
+      const blob = await previewTemplate(name, fields)
+      if (previewObjectUrl) URL.revokeObjectURL(previewObjectUrl)
+      previewObjectUrl = URL.createObjectURL(blob)
+      previewImg.src = previewObjectUrl
+      previewArea.hidden = false
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+    } finally {
+      btnPreview.disabled = false
+    }
+  }
+
+  // Bootstrap: load label catalog + fonts, then either load existing template or init blank
+  Promise.all([getLabels(), getFonts()]).then(async ([labels, fonts]) => {
+    // Populate font selector
+    defaultFont = fonts[0]?.name ?? 'DejaVuSans'
+    fontSelect.innerHTML = fonts
+      .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
+      .join('')
+    // Try to select DejaVuSans as default
+    const dvs = fonts.find(f => f.name.includes('DejaVu') || f.name.includes('DejaVuSans'))
+    if (dvs) { fontSelect.value = dvs.name; defaultFont = dvs.name }
+
+    if (isNew) {
+      // New template: use newMedia from query params
+      const label = labels.find(l => l.id === newMedia)
+      if (!label) { showStatus(`Unknown label media: ${newMedia}`, 'error'); return }
+      await initEditor(label)
+    } else {
+      // Load existing template
+      try {
+        const tmpl = await getTemplate(name)
+        labelMedia = tmpl.label_media
+        const label = labels.find(l => l.id === tmpl.label_media)
+        if (!label) { showStatus(`Unknown label media: ${tmpl.label_media}`, 'error'); return }
+        await initEditor(label)
+        if (fabricCanvas && tmpl.canvas_json && Object.keys(tmpl.canvas_json).length > 0) {
+          await loadCanvasJSON(fabricCanvas, tmpl.canvas_json)
+        }
+      } catch (err) {
+        showStatus((err as Error).message, 'error')
+      }
+    }
+  }).catch((err: Error) => {
+    showStatus(`Failed to load: ${err.message}`, 'error')
+  })
+}
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index 44b114b..b7b5b34 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -166,24 +166,22 @@ function showNewTemplateModal(root: HTMLElement, onCreated: () => void): void {
     mediaSelect.addEventListener('change', updateOk)
 
     getLabels().then(labels => {
-      import('../pages/quick-print').then(() => {
-        const groups = new Map<number, typeof labels>()
-        for (const l of labels) {
-          if (!groups.has(l.form_factor)) groups.set(l.form_factor, [])
-          groups.get(l.form_factor)!.push(l)
-        }
-        for (const entries of groups.values()) entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
-        const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
-        mediaSelect.innerHTML = allKeys
-          .filter(k => groups.has(k))
-          .map(k => {
-            const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
-            const opts = groups.get(k)!.map(l => `<option value="${esc2(l.id)}">${esc2(l.display_name)}</option>`).join('')
-            return `<optgroup label="${esc2(groupLabel)}">${opts}</optgroup>`
-          })
-          .join('')
-        updateOk()
-      })
+      const groups = new Map<number, typeof labels>()
+      for (const l of labels) {
+        if (!groups.has(l.form_factor)) groups.set(l.form_factor, [])
+        groups.get(l.form_factor)!.push(l)
+      }
+      for (const entries of groups.values()) entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
+      const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
+      mediaSelect.innerHTML = allKeys
+        .filter(k => groups.has(k))
+        .map(k => {
+          const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
+          const opts = groups.get(k)!.map(l => `<option value="${esc2(l.id)}">${esc2(l.display_name)}</option>`).join('')
+          return `<optgroup label="${esc2(groupLabel)}">${opts}</optgroup>`
+        })
+        .join('')
+      updateOk()
     })
 
     cancelBtn.addEventListener('click', () => overlay.remove())

From 0a0a2f46f94bf75aa63f7778b1a2dcea84e0a718 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Wed, 20 May 2026 23:56:42 -0700
Subject: [PATCH 28/84] Add template preview button to editor

---
 frontend/src/pages/template-editor.ts | 9 ++++++++-
 frontend/src/style.css                | 4 ++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index 5b650a5..214e0cb 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -31,6 +31,10 @@ function parsePath(): { name: string; isNew: boolean; newMedia: string } {
 export function mountTemplateEditor(root: HTMLElement): void {
   const { name, isNew, newMedia } = parsePath()
 
+  // Widen the app container for the editor
+  const appEl = document.getElementById('app')
+  appEl?.classList.add('editor-mode')
+
   root.innerHTML = `
     <div class="editor-shell">
       <div class="editor-toolbar">
@@ -133,7 +137,10 @@ export function mountTemplateEditor(root: HTMLElement): void {
     }
   })
 
-  btnBack.addEventListener('click', () => navigate('/templates'))
+  btnBack.addEventListener('click', () => {
+    document.getElementById('app')?.classList.remove('editor-mode')
+    navigate('/templates')
+  })
 
   btnAddText.addEventListener('click', () => {
     if (!fabricCanvas) return
diff --git a/frontend/src/style.css b/frontend/src/style.css
index e200acb..84c4799 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -15,6 +15,10 @@ body {
   margin: 0 auto;
 }
 
+#app.editor-mode {
+  max-width: 1100px;
+}
+
 h2 {
   margin: 0 0 1.25rem;
 }

From b528b80b8fd5d59419e0b1eae434b6b8901cfc6c Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Thu, 21 May 2026 00:05:51 -0700
Subject: [PATCH 29/84] Fix Fabric 6 TypeScript types in editor

---
 frontend/src/editor/canvas.ts         | 23 +++++++++++++----------
 frontend/src/pages/template-editor.ts | 11 ++++++-----
 frontend/src/pages/templates-list.ts  |  4 ++--
 3 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/frontend/src/editor/canvas.ts b/frontend/src/editor/canvas.ts
index 2a5cb04..936a4d2 100644
--- a/frontend/src/editor/canvas.ts
+++ b/frontend/src/editor/canvas.ts
@@ -1,8 +1,10 @@
-import { Canvas, IText } from 'fabric'
-import type { FabricObject } from 'fabric'
+import { Canvas, FabricObject, IText } from 'fabric'
 
 export const CUSTOM_PROPS = ['labelforge_raw_content'] as const
 
+// Register the custom prop so canvas.toJSON() includes it on every object automatically.
+FabricObject.customProperties.push('labelforge_raw_content')
+
 /** Create a Fabric Canvas sized to label pixels, displayed scaled to fit the container. */
 export function initCanvas(
   el: HTMLCanvasElement,
@@ -22,10 +24,10 @@ export function initCanvas(
   canvas.setDimensions({ width: displayW, height: displayH })
   canvas.setZoom(scale)
 
-  // Sync labelforge_raw_content whenever text is edited inline
-  canvas.on('text:changed', (e: { target: FabricObject }) => {
-    const obj = e.target as FabricObject & { text?: string }
-    ;(obj as Record<string, unknown>)['labelforge_raw_content'] = obj.text ?? ''
+  // Sync labelforge_raw_content whenever text is edited inline.
+  // text:changed target is IText — no manual annotation needed.
+  canvas.on('text:changed', (e) => {
+    e.target.set('labelforge_raw_content', e.target.text ?? '')
   })
 
   return { canvas, scale }
@@ -44,11 +46,11 @@ export function addTextElement(canvas: Canvas, defaultFont: string): void {
     fontSize: 48,
     fill: '#000000',
   })
-  ;(text as Record<string, unknown>)['labelforge_raw_content'] = 'Text'
+  text.set('labelforge_raw_content', 'Text')
 
   // Keep raw content in sync when text changes
   text.on('changed', () => {
-    ;(text as Record<string, unknown>)['labelforge_raw_content'] = text.text ?? ''
+    text.set('labelforge_raw_content', text.text ?? '')
   })
 
   canvas.add(text)
@@ -65,7 +67,8 @@ export function deleteSelected(canvas: Canvas): void {
 }
 
 export function getCanvasJSON(canvas: Canvas): Record<string, unknown> {
-  return canvas.toJSON([...CUSTOM_PROPS]) as Record<string, unknown>
+  // customProperties registered above ensures labelforge_raw_content is included.
+  return canvas.toJSON() as Record<string, unknown>
 }
 
 export async function loadCanvasJSON(
@@ -78,7 +81,7 @@ export async function loadCanvasJSON(
     if (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox') {
       const t = obj as IText
       t.on('changed', () => {
-        ;(t as Record<string, unknown>)['labelforge_raw_content'] = t.text ?? ''
+        t.set('labelforge_raw_content', t.text ?? '')
       })
     }
   })
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index 214e0cb..06ceb14 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -109,10 +109,11 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   function updateFontControls(): void {
     if (!fabricCanvas) return
-    const obj = fabricCanvas.getActiveObject() as (Record<string, unknown> & { fontFamily?: string; fontSize?: number }) | null
+    type TextProps = { fontFamily?: string; fontSize?: number; type?: string }
+    const obj = fabricCanvas.getActiveObject() as unknown as TextProps | null
     if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
-      if (obj.fontFamily) fontSelect.value = String(obj.fontFamily)
-      if (obj.fontSize) fontSizeInput.value = String(Math.round(Number(obj.fontSize)))
+      if (obj.fontFamily) fontSelect.value = obj.fontFamily
+      if (obj.fontSize) fontSizeInput.value = String(Math.round(obj.fontSize))
     }
   }
 
@@ -120,7 +121,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
     if (!fabricCanvas) return
     const obj = fabricCanvas.getActiveObject()
     if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
-      obj.set({ fontFamily: fontSelect.value } as Parameters<typeof obj.set>[0])
+      obj.set('fontFamily', fontSelect.value)
       fabricCanvas.renderAll()
     }
   })
@@ -131,7 +132,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
     if (!isNaN(sz) && sz >= 6) {
       const obj = fabricCanvas.getActiveObject()
       if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
-        obj.set({ fontSize: sz } as Parameters<typeof obj.set>[0])
+        obj.set('fontSize', sz)
         fabricCanvas.renderAll()
       }
     }
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index b7b5b34..0fcf543 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -105,13 +105,13 @@ export function mountTemplatesList(root: HTMLElement): void {
   }
 
   btnNew.addEventListener('click', () => {
-    showNewTemplateModal(root, () => load())
+    showNewTemplateModal(() => load())
   })
 
   void load()
 }
 
-function showNewTemplateModal(root: HTMLElement, onCreated: () => void): void {
+function showNewTemplateModal(onCreated: () => void): void {
   import('../api').then(({ getLabels }) => {
     const overlay = document.createElement('div')
     overlay.className = 'modal-overlay'

From 912016be0cb70b61b81f4f7ede71ff76b0989747 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Thu, 21 May 2026 00:07:15 -0700
Subject: [PATCH 30/84] Update changelog for templates editor foundation slice

---
 CHANGELOG.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 18721db..c6f381f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,18 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 - QR and barcode template elements render in preview but print as a solid black block (1-bit threshold crushes fine detail). These elements are gated to raise a clear error until fixed. Text, lines, and rectangles print correctly.
 
 ### Added
+
+- **Templates editor foundation (text-only slice)** — canvas editor at `/templates/{name}` built on Fabric.js 6.6.1:
+  - Templates list page at `/templates`: shows name, label media, last-updated; Edit and Delete (soft-delete) per row; empty state
+  - New-template modal: slug-validated name (`^[a-z0-9][a-z0-9-]*$`), label media grouped by form factor (same grouping as quick-print)
+  - Editor toolbar: Add Text, Delete selected, font family selector (populated from `/api/fonts`), font size input, Preview, Save, Back
+  - Canvas geometry: internal coordinates are label pixels at print DPI (300 dpi); canvas is displayed scale-to-fit the viewport while all saved coordinates remain in label pixels — the coordinate space the server renderer consumes
+  - `labelforge_raw_content` custom property: set on every text element at creation and kept in sync on every keystroke; registered via `FabricObject.customProperties` so it survives `canvas.toJSON()` / `loadFromJSON()` round-trips and is available to the server's `detect_fields` and `render_template`
+  - Save: calls `POST /api/templates` on first save of a new template, `PUT /api/templates/{name}` on subsequent saves; blocks if canvas is empty
+  - Load: `GET /api/templates/{name}` → `canvas.loadFromJSON()` with custom-prop re-attachment
+  - Preview button: auto-saves then calls `POST /api/preview/{name}`; shows the server-rendered PNG inline — this is the editor↔server geometry agreement check (text placed in the editor should appear at the same position in the preview PNG)
+  - Router extended with prefix-route support (`registerPrefix`) for parameterised paths like `/templates/:name`
+- `fabric@6.6.1` added to frontend dependencies
 - Project structure and design documentation
 - PRD covering quick-print, templates, label catalog, history, HTTP API, printer status, and settings
 - Architecture doc locking stack: FastAPI + SQLite + brother-ql-inventree + Vite/TS + Fabric.js

From baf0092a8984319209b4cedb58f8d4c55d0804e9 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Thu, 21 May 2026 00:10:45 -0700
Subject: [PATCH 31/84] updates

---
 frontend/package-lock.json            | 1571 ++++++++++++++++++++++++-
 frontend/src/api.js                   |  109 ++
 frontend/src/editor/canvas.js         |   69 ++
 frontend/src/main.js                  |    9 +
 frontend/src/pages/quick-print.js     |  248 ++++
 frontend/src/pages/template-editor.js |  247 ++++
 frontend/src/pages/templates-list.js  |  196 +++
 frontend/src/pages/templates.js       |    1 +
 frontend/src/router.js                |   52 +
 frontend/src/types.js                 |    1 +
 10 files changed, 2492 insertions(+), 11 deletions(-)
 create mode 100644 frontend/src/api.js
 create mode 100644 frontend/src/editor/canvas.js
 create mode 100644 frontend/src/main.js
 create mode 100644 frontend/src/pages/quick-print.js
 create mode 100644 frontend/src/pages/template-editor.js
 create mode 100644 frontend/src/pages/templates-list.js
 create mode 100644 frontend/src/pages/templates.js
 create mode 100644 frontend/src/router.js
 create mode 100644 frontend/src/types.js

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 83e96d3..f61178b 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -5,6 +5,9 @@
   "packages": {
     "": {
       "name": "labelforge-frontend",
+      "dependencies": {
+        "fabric": "6.6.1"
+      },
       "devDependencies": {
         "typescript": "^5.7.2",
         "vite": "^6.3.5"
@@ -452,6 +455,27 @@
         "node": ">=18"
       }
     },
+    "node_modules/@mapbox/node-pre-gyp": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/@mapbox/node-pre-gyp/-/node-pre-gyp-1.0.11.tgz",
+      "integrity": "sha512-Yhlar6v9WQgUp/He7BdgzOz8lqMQ8sU+jkCq7Wx8Myc5YFJLbEe7lgui/V7G1qB1DJykHSGwreceSaD60Y0PUQ==",
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "dependencies": {
+        "detect-libc": "^2.0.0",
+        "https-proxy-agent": "^5.0.0",
+        "make-dir": "^3.1.0",
+        "node-fetch": "^2.6.7",
+        "nopt": "^5.0.0",
+        "npmlog": "^5.0.1",
+        "rimraf": "^3.0.2",
+        "semver": "^7.3.5",
+        "tar": "^6.1.11"
+      },
+      "bin": {
+        "node-pre-gyp": "bin/node-pre-gyp"
+      }
+    },
     "node_modules/@rollup/rollup-android-arm-eabi": {
       "version": "4.60.4",
       "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
@@ -841,6 +865,16 @@
         "win32"
       ]
     },
+    "node_modules/@tootallnate/once": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-2.0.1.tgz",
+      "integrity": "sha512-HqmEUIGRJ5fSXchkVgR5F7qn48bDBzv0kWj/Kfu5e6uci4UlEeng4331LnBkWffb++Ei3FOVLxo8JJWMFBDMeQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 10"
+      }
+    },
     "node_modules/@types/estree": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -848,6 +882,410 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/abab": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz",
+      "integrity": "sha512-j2afSsaIENvHZN2B8GOpF566vZ5WVk5opAiMTvWgaQT8DkbOqsTfvNAvHoRGU2zzP8cPoqys+xHTRDWW8L+/BA==",
+      "deprecated": "Use your platform's native atob() and btoa() methods instead",
+      "license": "BSD-3-Clause",
+      "optional": true
+    },
+    "node_modules/abbrev": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
+      "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/acorn": {
+      "version": "8.16.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
+      "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
+      "license": "MIT",
+      "optional": true,
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-globals": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/acorn-globals/-/acorn-globals-7.0.1.tgz",
+      "integrity": "sha512-umOSDSDrfHbTNPuNpC2NSnnA3LUrqpevPb4T9jRx4MagXNS0rs+gwiTcAvqCRmsD6utzsrzNt+ebm00SNWiC3Q==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "acorn": "^8.1.0",
+        "acorn-walk": "^8.0.2"
+      }
+    },
+    "node_modules/acorn-walk": {
+      "version": "8.3.5",
+      "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz",
+      "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "acorn": "^8.11.0"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/agent-base": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
+      "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6.0.0"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/aproba": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/aproba/-/aproba-2.1.0.tgz",
+      "integrity": "sha512-tLIEcj5GuR2RSTnxNKdkK0dJ/GrC7P38sUkiDmDuHfsHmbagTFAxDVIBltoklXEVIQ/f14IL8IMJ5pn9Hez1Ew==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/are-we-there-yet": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-2.0.0.tgz",
+      "integrity": "sha512-Ci/qENmwHnsYo9xKIcUJN5LeDKdJ6R1Z1j9V/J5wyq8nh/mYPEpIKJbBZXtZjG04HiK7zV/p6Vs9952MrMeUIw==",
+      "deprecated": "This package is no longer supported.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "delegates": "^1.0.0",
+        "readable-stream": "^3.6.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/asynckit": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
+      "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/brace-expansion": {
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/call-bind-apply-helpers": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
+      "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/canvas": {
+      "version": "2.11.2",
+      "resolved": "https://registry.npmjs.org/canvas/-/canvas-2.11.2.tgz",
+      "integrity": "sha512-ItanGBMrmRV7Py2Z+Xhs7cT+FNt5K0vPL4p9EZ/UX/Mu7hFbkxSjKF2KVtPwX7UYWp7dRKnrTvReflgrItJbdw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@mapbox/node-pre-gyp": "^1.0.0",
+        "nan": "^2.17.0",
+        "simple-get": "^3.0.3"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/chownr": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/chownr/-/chownr-2.0.0.tgz",
+      "integrity": "sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==",
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/color-support": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/color-support/-/color-support-1.1.3.tgz",
+      "integrity": "sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==",
+      "license": "ISC",
+      "optional": true,
+      "bin": {
+        "color-support": "bin.js"
+      }
+    },
+    "node_modules/combined-stream": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
+      "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "delayed-stream": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/console-control-strings": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/console-control-strings/-/console-control-strings-1.1.0.tgz",
+      "integrity": "sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/cssom": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/cssom/-/cssom-0.5.0.tgz",
+      "integrity": "sha512-iKuQcq+NdHqlAcwUY0o/HL69XQrUaQdMjmStJ8JFmUaiiQErlhrmuigkg/CU4E2J0IyUKUrMAgl36TvN67MqTw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/cssstyle": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-2.3.0.tgz",
+      "integrity": "sha512-AZL67abkUzIuvcHqk7c09cezpGNcxUxU4Ioi/05xHk4DQeTkWmGYftIE6ctU6AEt+Gn4n1lDStOtj7FKycP71A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "cssom": "~0.3.6"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cssstyle/node_modules/cssom": {
+      "version": "0.3.8",
+      "resolved": "https://registry.npmjs.org/cssom/-/cssom-0.3.8.tgz",
+      "integrity": "sha512-b0tGHbfegbhPJpxpiBPU2sCkigAqtM9O121le6bbOlgyV+NyGyCmVfJ6QW9eRjz8CpNfWEOYBIMIGRYkLwsIYg==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/data-urls": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-3.0.2.tgz",
+      "integrity": "sha512-Jy/tj3ldjZJo63sVAvg6LHt2mHvl4V6AgRAmNDtLdm7faqtsx+aJG42rsyCo9JCoRVKwPFzKlIPx3DIibwSIaQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "abab": "^2.0.6",
+        "whatwg-mimetype": "^3.0.0",
+        "whatwg-url": "^11.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/decompress-response": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-4.2.1.tgz",
+      "integrity": "sha512-jOSne2qbyE+/r8G1VU+G/82LBs2Fs4LAsTiLSHOCOMZQl2OKZ6i8i4IyHemTe+/yIXOtTcRQMzPcgyhoFlqPkw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "mimic-response": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/delayed-stream": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
+      "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/delegates": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/delegates/-/delegates-1.0.0.tgz",
+      "integrity": "sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/domexception": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/domexception/-/domexception-4.0.0.tgz",
+      "integrity": "sha512-A2is4PLG+eeSfoTMA95/s4pvAoSo2mKtiM5jlHkAVewmiO8ISFTFKZjH7UAM1Atli/OT/7JHOrJRJiMKUZKYBw==",
+      "deprecated": "Use your platform's native DOMException instead",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "webidl-conversions": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/dunder-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
+      "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "gopd": "^1.2.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/entities": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
+      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/es-define-property": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-errors": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-object-atoms": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
+      "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "es-errors": "^1.3.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-set-tostringtag": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
+      "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.6",
+        "has-tostringtag": "^1.0.2",
+        "hasown": "^2.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
@@ -890,6 +1328,75 @@
         "@esbuild/win32-x64": "0.25.12"
       }
     },
+    "node_modules/escodegen": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz",
+      "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "dependencies": {
+        "esprima": "^4.0.1",
+        "estraverse": "^5.2.0",
+        "esutils": "^2.0.2"
+      },
+      "bin": {
+        "escodegen": "bin/escodegen.js",
+        "esgenerate": "bin/esgenerate.js"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "optionalDependencies": {
+        "source-map": "~0.6.1"
+      }
+    },
+    "node_modules/esprima": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
+      "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "bin": {
+        "esparse": "bin/esparse.js",
+        "esvalidate": "bin/esvalidate.js"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/estraverse": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
+      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/esutils": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
+      "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/fabric": {
+      "version": "6.6.1",
+      "resolved": "https://registry.npmjs.org/fabric/-/fabric-6.6.1.tgz",
+      "integrity": "sha512-QrQkx6I7daFL/WdkrE8VOEiAr/ffLK36NQ0t/vNZt8P7QIXPpjT4HegjOatUW1G6vYlulX4pI1P/5NeqIgsDig==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.20.0"
+      },
+      "optionalDependencies": {
+        "canvas": "^2.11.2",
+        "jsdom": "^20.0.1"
+      }
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -908,6 +1415,56 @@
         }
       }
     },
+    "node_modules/form-data": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
+      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "asynckit": "^0.4.0",
+        "combined-stream": "^1.0.8",
+        "es-set-tostringtag": "^2.1.0",
+        "hasown": "^2.0.2",
+        "mime-types": "^2.1.12"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/fs-minipass": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-2.1.0.tgz",
+      "integrity": "sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/fs-minipass/node_modules/minipass": {
+      "version": "3.3.6",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
+      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fs.realpath": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
+      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
+      "license": "ISC",
+      "optional": true
+    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -923,17 +1480,458 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
-    "node_modules/nanoid": {
-      "version": "3.3.12",
-      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
-      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
-      "dev": true,
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/ai"
-        }
-      ],
+    "node_modules/function-bind": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+      "license": "MIT",
+      "optional": true,
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/gauge": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/gauge/-/gauge-3.0.2.tgz",
+      "integrity": "sha512-+5J6MS/5XksCuXq++uFRsnUd7Ovu1XenbeuIuNRJxYWjgQbPuFhT14lAvsWfqfAmnwluf1OwMjz39HjfLPci0Q==",
+      "deprecated": "This package is no longer supported.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "aproba": "^1.0.3 || ^2.0.0",
+        "color-support": "^1.1.2",
+        "console-control-strings": "^1.0.0",
+        "has-unicode": "^2.0.1",
+        "object-assign": "^4.1.1",
+        "signal-exit": "^3.0.0",
+        "string-width": "^4.2.3",
+        "strip-ansi": "^6.0.1",
+        "wide-align": "^1.1.2"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/get-intrinsic": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
+      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.2",
+        "es-define-property": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "es-object-atoms": "^1.1.1",
+        "function-bind": "^1.1.2",
+        "get-proto": "^1.0.1",
+        "gopd": "^1.2.0",
+        "has-symbols": "^1.1.0",
+        "hasown": "^2.0.2",
+        "math-intrinsics": "^1.1.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/get-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
+      "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "dunder-proto": "^1.0.1",
+        "es-object-atoms": "^1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/glob": {
+      "version": "7.2.3",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
+      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
+      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "fs.realpath": "^1.0.0",
+        "inflight": "^1.0.4",
+        "inherits": "2",
+        "minimatch": "^3.1.1",
+        "once": "^1.3.0",
+        "path-is-absolute": "^1.0.0"
+      },
+      "engines": {
+        "node": "*"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/gopd": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
+      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/has-symbols": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
+      "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/has-tostringtag": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
+      "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "has-symbols": "^1.0.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/has-unicode": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/has-unicode/-/has-unicode-2.0.1.tgz",
+      "integrity": "sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/hasown": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
+      "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/html-encoding-sniffer": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-3.0.0.tgz",
+      "integrity": "sha512-oWv4T4yJ52iKrufjnyZPkrN0CH3QnrUqdB6In1g5Fe1mia8GmF36gnfNySxoZtxD5+NmYw1EElVXiBk93UeskA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "whatwg-encoding": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/http-proxy-agent": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-5.0.0.tgz",
+      "integrity": "sha512-n2hY8YdoRE1i7r6M0w9DIw5GgZN0G25P8zLCRQ8rjXtTU3vsNFBI/vWK/UIeE6g5MUUz6avwAPXmL6Fy9D/90w==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@tootallnate/once": "2",
+        "agent-base": "6",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/https-proxy-agent": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
+      "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "agent-base": "6",
+        "debug": "4"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/inflight": {
+      "version": "1.0.6",
+      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
+      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
+      "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "once": "^1.3.0",
+        "wrappy": "1"
+      }
+    },
+    "node_modules/inherits": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
+      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/jsdom": {
+      "version": "20.0.3",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-20.0.3.tgz",
+      "integrity": "sha512-SYhBvTh89tTfCD/CRdSOm13mOBa42iTaTyfyEWBdKcGdPxPtLFBXuHR8XHb33YNYaP+lLbmSvBTsnoesCNJEsQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "abab": "^2.0.6",
+        "acorn": "^8.8.1",
+        "acorn-globals": "^7.0.0",
+        "cssom": "^0.5.0",
+        "cssstyle": "^2.3.0",
+        "data-urls": "^3.0.2",
+        "decimal.js": "^10.4.2",
+        "domexception": "^4.0.0",
+        "escodegen": "^2.0.0",
+        "form-data": "^4.0.0",
+        "html-encoding-sniffer": "^3.0.0",
+        "http-proxy-agent": "^5.0.0",
+        "https-proxy-agent": "^5.0.1",
+        "is-potential-custom-element-name": "^1.0.1",
+        "nwsapi": "^2.2.2",
+        "parse5": "^7.1.1",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^4.1.2",
+        "w3c-xmlserializer": "^4.0.0",
+        "webidl-conversions": "^7.0.0",
+        "whatwg-encoding": "^2.0.0",
+        "whatwg-mimetype": "^3.0.0",
+        "whatwg-url": "^11.0.0",
+        "ws": "^8.11.0",
+        "xml-name-validator": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "peerDependencies": {
+        "canvas": "^2.5.0"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/make-dir": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz",
+      "integrity": "sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "semver": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/make-dir/node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "license": "ISC",
+      "optional": true,
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
+    "node_modules/math-intrinsics": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
+      "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/mime-db": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
+      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types": {
+      "version": "2.1.35",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
+      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "mime-db": "1.52.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mimic-response": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-2.1.0.tgz",
+      "integrity": "sha512-wXqjST+SLt7R009ySCglWBCFpjUygmCIfD790/kVbiGmUgfYGuB14PiTd5DwVxSV4NcYHjzMkoj5LjQZwTQLEA==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/minipass": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-5.0.0.tgz",
+      "integrity": "sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==",
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/minizlib": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz",
+      "integrity": "sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "minipass": "^3.0.0",
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/minizlib/node_modules/minipass": {
+      "version": "3.3.6",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
+      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/mkdirp": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz",
+      "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==",
+      "license": "MIT",
+      "optional": true,
+      "bin": {
+        "mkdirp": "bin/cmd.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/nan": {
+      "version": "2.27.0",
+      "resolved": "https://registry.npmjs.org/nan/-/nan-2.27.0.tgz",
+      "integrity": "sha512-hC+0LidcL3XE4rp1C4H54KujgXKzbfyTngZTwBByQxsOxCEKZT0MPQ4hOKUH2jU1OYstqdDH4onyHPDzcV0XdQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.12",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
       "license": "MIT",
       "bin": {
         "nanoid": "bin/nanoid.cjs"
@@ -942,6 +1940,132 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/node-fetch": {
+      "version": "2.7.0",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
+      "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "whatwg-url": "^5.0.0"
+      },
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      },
+      "peerDependencies": {
+        "encoding": "^0.1.0"
+      },
+      "peerDependenciesMeta": {
+        "encoding": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/node-fetch/node_modules/tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/node-fetch/node_modules/webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==",
+      "license": "BSD-2-Clause",
+      "optional": true
+    },
+    "node_modules/node-fetch/node_modules/whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
+    "node_modules/nopt": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-5.0.0.tgz",
+      "integrity": "sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "abbrev": "1"
+      },
+      "bin": {
+        "nopt": "bin/nopt.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/npmlog": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/npmlog/-/npmlog-5.0.1.tgz",
+      "integrity": "sha512-AqZtDUWOMKs1G/8lwylVjrdYgqA4d9nu8hc+0gzRxlDb1I10+FHBGMXs6aiQHFdCUUlqH99MUMuLfzWDNDtfxw==",
+      "deprecated": "This package is no longer supported.",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "are-we-there-yet": "^2.0.0",
+        "console-control-strings": "^1.1.0",
+        "gauge": "^3.0.0",
+        "set-blocking": "^2.0.0"
+      }
+    },
+    "node_modules/nwsapi": {
+      "version": "2.2.23",
+      "resolved": "https://registry.npmjs.org/nwsapi/-/nwsapi-2.2.23.tgz",
+      "integrity": "sha512-7wfH4sLbt4M0gCDzGE6vzQBo0bfTKjU7Sfpqy/7gs1qBfYz2vEJH6vXcBKpO3+6Yu1telwd0t9HpyOoLEQQbIQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/object-assign": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
+      "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
+    "node_modules/parse5": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
+      "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/path-is-absolute": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
+      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -991,6 +2115,75 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/psl": {
+      "version": "1.15.0",
+      "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz",
+      "integrity": "sha512-JZd3gMVBAVQkSs6HdNZo9Sdo0LNcQeMNP3CozBJb3JYC/QUYZTnKxP+f8oWRX4rHP5EurWxqAHTSwUCjlNKa1w==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/lupomontero"
+      }
+    },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/querystringify": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz",
+      "integrity": "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/readable-stream": {
+      "version": "3.6.2",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
+      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "inherits": "^2.0.3",
+        "string_decoder": "^1.1.1",
+        "util-deprecate": "^1.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/requires-port": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
+      "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/rimraf": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz",
+      "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==",
+      "deprecated": "Rimraf versions prior to v4 are no longer supported",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "glob": "^7.1.3"
+      },
+      "bin": {
+        "rimraf": "bin.js"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/rollup": {
       "version": "4.60.4",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
@@ -1036,6 +2229,117 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/safer-buffer": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
+    "node_modules/semver": {
+      "version": "7.8.0",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
+      "license": "ISC",
+      "optional": true,
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/set-blocking": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
+      "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/simple-concat": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz",
+      "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/simple-get": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-3.1.1.tgz",
+      "integrity": "sha512-CQ5LTKGfCpvE1K0n2us+kuMPbk/q0EKl82s4aheV9oXjFEz6W/Y7oQFVJuU6QG77hRT4Ghb5RURteF5vnWjupA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "decompress-response": "^4.2.0",
+        "once": "^1.3.1",
+        "simple-concat": "^1.0.0"
+      }
+    },
+    "node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -1046,6 +2350,70 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/string_decoder": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
+      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "safe-buffer": "~5.2.0"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/tar": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",
+      "integrity": "sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==",
+      "deprecated": "Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "chownr": "^2.0.0",
+        "fs-minipass": "^2.0.0",
+        "minipass": "^5.0.0",
+        "minizlib": "^2.1.1",
+        "mkdirp": "^1.0.3",
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.16",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
@@ -1063,6 +2431,35 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tough-cookie": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-4.1.4.tgz",
+      "integrity": "sha512-Loo5UUvLD9ScZ6jh8beX1T6sO1w2/MpCRpEP7V280GKMVUQ0Jzar2U3UJPsrdbziLEMMhu3Ujnq//rhiFuIeag==",
+      "license": "BSD-3-Clause",
+      "optional": true,
+      "dependencies": {
+        "psl": "^1.1.33",
+        "punycode": "^2.1.1",
+        "universalify": "^0.2.0",
+        "url-parse": "^1.5.3"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-3.0.0.tgz",
+      "integrity": "sha512-l7FvfAHlcmulp8kr+flpQZmVwtu7nfRV7NZujtN0OqES8EL4O4e0qqzL0DC5gAvx/ZC/9lk6rhcUwYvkBnBnYA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "punycode": "^2.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/typescript": {
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
@@ -1077,6 +2474,34 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/universalify": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.2.0.tgz",
+      "integrity": "sha512-CJ1QgKmNg3CwvAv/kOFmtnEN05f0D/cn9QntgNOQlQF9dgvVTHj3t+8JPdjqawCHk7V/KA+fbUqzZ9XWhcqPUg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 4.0.0"
+      }
+    },
+    "node_modules/url-parse": {
+      "version": "1.5.10",
+      "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz",
+      "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "querystringify": "^2.1.1",
+        "requires-port": "^1.0.0"
+      }
+    },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/vite": {
       "version": "6.4.2",
       "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.2.tgz",
@@ -1151,6 +2576,130 @@
           "optional": true
         }
       }
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-4.0.0.tgz",
+      "integrity": "sha512-d+BFHzbiCx6zGfz0HyQ6Rg69w9k19nviJspaj4yNscGjrHu94sVP+aRm75yEbCh+r2/yR+7q6hux9LVtbuTGBw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "xml-name-validator": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-7.0.0.tgz",
+      "integrity": "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/whatwg-encoding": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-2.0.0.tgz",
+      "integrity": "sha512-p41ogyeMUrw3jWclHWTQg1k05DSVXPLcVxRTYsXUk+ZooOCZLcoYgPZ/HL/D/N+uQPOtcp1me1WhBEaX02mhWg==",
+      "deprecated": "Use @exodus/bytes instead for a more spec-conformant and faster implementation",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "iconv-lite": "0.6.3"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-3.0.0.tgz",
+      "integrity": "sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-11.0.0.tgz",
+      "integrity": "sha512-RKT8HExMpoYx4igMiVMY83lN6UeITKJlBQ+vR/8ZJ8OCdSiN3RwCq+9gH0+Xzj0+5IrM6i4j/6LuvzbZIQgEcQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tr46": "^3.0.0",
+        "webidl-conversions": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/wide-align": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/wide-align/-/wide-align-1.1.5.tgz",
+      "integrity": "sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^1.0.2 || 2 || 3 || 4"
+      }
+    },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
+      "license": "ISC",
+      "optional": true
+    },
+    "node_modules/ws": {
+      "version": "8.20.1",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.1.tgz",
+      "integrity": "sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/xml-name-validator": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-4.0.0.tgz",
+      "integrity": "sha512-ICP2e+jsHvAj2E2lIHxa5tjXRlKDJo4IdvPvCXbXQGdzSfmSpNVyIKMvoZHjDY9DP0zV17iI85o90vRFXNccRw==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/yallist": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
+      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
+      "license": "ISC",
+      "optional": true
     }
   }
 }
diff --git a/frontend/src/api.js b/frontend/src/api.js
new file mode 100644
index 0000000..9d96247
--- /dev/null
+++ b/frontend/src/api.js
@@ -0,0 +1,109 @@
+export const TOKEN_KEY = 'labelforge_token';
+function getToken() {
+    return localStorage.getItem(TOKEN_KEY) ?? '';
+}
+async function apiFetch(path, options = {}) {
+    const res = await fetch(path, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${getToken()}`,
+            ...options.headers,
+        },
+    });
+    if (!res.ok) {
+        let detail = `HTTP ${res.status}`;
+        try {
+            const body = await res.json();
+            if (body.detail)
+                detail = String(body.detail);
+        }
+        catch { /* use status fallback */ }
+        throw new Error(detail);
+    }
+    return res.json();
+}
+export function getLabels() {
+    return apiFetch('/api/labels');
+}
+export function getFonts() {
+    return apiFetch('/api/fonts');
+}
+export function quickPrint(req) {
+    return apiFetch('/api/print/quick', {
+        method: 'POST',
+        body: JSON.stringify(req),
+    });
+}
+export async function previewQuick(req) {
+    const res = await fetch('/api/preview/quick', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${getToken()}`,
+        },
+        body: JSON.stringify(req),
+    });
+    if (!res.ok) {
+        let detail = `HTTP ${res.status}`;
+        try {
+            const body = await res.json();
+            if (body.detail)
+                detail = String(body.detail);
+        }
+        catch { /* use status fallback */ }
+        throw new Error(detail);
+    }
+    return res.blob();
+}
+export function listTemplates() {
+    return apiFetch('/api/templates');
+}
+export function getTemplate(name) {
+    return apiFetch(`/api/templates/${encodeURIComponent(name)}`);
+}
+export function createTemplate(body) {
+    return apiFetch('/api/templates', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+}
+export function updateTemplate(name, body) {
+    return apiFetch(`/api/templates/${encodeURIComponent(name)}`, {
+        method: 'PUT',
+        body: JSON.stringify(body),
+    });
+}
+export function deleteTemplate(name) {
+    return apiFetch(`/api/templates/${encodeURIComponent(name)}`, { method: 'DELETE' });
+}
+export async function previewTemplate(name, fields) {
+    const res = await fetch(`/api/preview/${encodeURIComponent(name)}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${getToken()}`,
+        },
+        body: JSON.stringify({ fields }),
+    });
+    if (!res.ok) {
+        let detail = `HTTP ${res.status}`;
+        try {
+            const body = await res.json();
+            if (body.detail)
+                detail = String(body.detail);
+        }
+        catch { /* use status fallback */ }
+        throw new Error(detail);
+    }
+    return res.blob();
+}
+export function getSettings() {
+    return apiFetch('/api/settings');
+}
+export function putSettings(partial) {
+    return apiFetch('/api/settings', {
+        method: 'PUT',
+        body: JSON.stringify(partial),
+    });
+}
diff --git a/frontend/src/editor/canvas.js b/frontend/src/editor/canvas.js
new file mode 100644
index 0000000..a52bfd9
--- /dev/null
+++ b/frontend/src/editor/canvas.js
@@ -0,0 +1,69 @@
+import { Canvas, FabricObject, IText } from 'fabric';
+export const CUSTOM_PROPS = ['labelforge_raw_content'];
+// Register the custom prop so canvas.toJSON() includes it on every object automatically.
+FabricObject.customProperties.push('labelforge_raw_content');
+/** Create a Fabric Canvas sized to label pixels, displayed scaled to fit the container. */
+export function initCanvas(el, labelW, labelH, containerW) {
+    const maxDisplayH = 600;
+    const scale = Math.min(1, (containerW - 48) / labelW, maxDisplayH / labelH);
+    const displayW = Math.round(labelW * scale);
+    const displayH = Math.round(labelH * scale);
+    const canvas = new Canvas(el, {
+        backgroundColor: '#ffffff',
+        selection: true,
+    });
+    canvas.setDimensions({ width: displayW, height: displayH });
+    canvas.setZoom(scale);
+    // Sync labelforge_raw_content whenever text is edited inline.
+    // text:changed target is IText — no manual annotation needed.
+    canvas.on('text:changed', (e) => {
+        e.target.set('labelforge_raw_content', e.target.text ?? '');
+    });
+    return { canvas, scale };
+}
+export function addTextElement(canvas, defaultFont) {
+    const vp = canvas.viewportTransform ?? [1, 0, 0, 1, 0, 0];
+    const scale = vp[0];
+    const canvasVirtualW = (canvas.width ?? 400) / scale;
+    const canvasVirtualH = (canvas.height ?? 200) / scale;
+    const text = new IText('Text', {
+        left: Math.round(canvasVirtualW * 0.05),
+        top: Math.round(canvasVirtualH * 0.05),
+        fontFamily: defaultFont,
+        fontSize: 48,
+        fill: '#000000',
+    });
+    text.set('labelforge_raw_content', 'Text');
+    // Keep raw content in sync when text changes
+    text.on('changed', () => {
+        text.set('labelforge_raw_content', text.text ?? '');
+    });
+    canvas.add(text);
+    canvas.setActiveObject(text);
+    canvas.renderAll();
+}
+export function deleteSelected(canvas) {
+    const active = canvas.getActiveObjects();
+    if (active.length === 0)
+        return;
+    active.forEach(obj => canvas.remove(obj));
+    canvas.discardActiveObject();
+    canvas.renderAll();
+}
+export function getCanvasJSON(canvas) {
+    // customProperties registered above ensures labelforge_raw_content is included.
+    return canvas.toJSON();
+}
+export async function loadCanvasJSON(canvas, json) {
+    await canvas.loadFromJSON(json);
+    // Re-attach raw content sync to each loaded text object
+    canvas.getObjects().forEach(obj => {
+        if (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox') {
+            const t = obj;
+            t.on('changed', () => {
+                t.set('labelforge_raw_content', t.text ?? '');
+            });
+        }
+    });
+    canvas.renderAll();
+}
diff --git a/frontend/src/main.js b/frontend/src/main.js
new file mode 100644
index 0000000..95cb3b9
--- /dev/null
+++ b/frontend/src/main.js
@@ -0,0 +1,9 @@
+import './style.css';
+import { mountQuickPrint } from './pages/quick-print';
+import { mountTemplates } from './pages/templates';
+import { mountTemplateEditor } from './pages/template-editor';
+import { initRouter, register, registerPrefix } from './router';
+register('/', mountQuickPrint);
+register('/templates', mountTemplates);
+registerPrefix('/templates/', mountTemplateEditor);
+initRouter();
diff --git a/frontend/src/pages/quick-print.js b/frontend/src/pages/quick-print.js
new file mode 100644
index 0000000..5d4a46b
--- /dev/null
+++ b/frontend/src/pages/quick-print.js
@@ -0,0 +1,248 @@
+import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api';
+const FORM_FACTOR_LABEL = {
+    1: 'Die-cut',
+    2: 'Continuous',
+    3: 'Round',
+    4: 'P-touch Continuous',
+};
+const FF_ORDER = [2, 1, 3, 4];
+function esc(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+export function mountQuickPrint(root) {
+    if (!localStorage.getItem(TOKEN_KEY)) {
+        renderTokenGate(root);
+    }
+    else {
+        renderForm(root);
+    }
+}
+function renderTokenGate(root) {
+    root.innerHTML = `
+    <div class="token-gate">
+      <h2>LabelForge</h2>
+      <p>Enter your API token to continue.</p>
+      <input id="token-input" type="password" placeholder="API token" autocomplete="current-password" />
+      <button id="token-save">Save token</button>
+    </div>
+  `;
+    const input = root.querySelector('#token-input');
+    const btn = root.querySelector('#token-save');
+    function save() {
+        const val = input.value.trim();
+        if (!val)
+            return;
+        localStorage.setItem(TOKEN_KEY, val);
+        renderForm(root);
+    }
+    btn.addEventListener('click', save);
+    input.addEventListener('keydown', (e) => { if (e.key === 'Enter')
+        save(); });
+}
+function renderForm(root) {
+    root.innerHTML = `
+    <div class="quick-print">
+      <h2>Quick Print</h2>
+      <div id="status-msg" class="status-msg" hidden></div>
+      <form id="print-form" autocomplete="off">
+        <div>
+          <label for="text">Text</label>
+          <textarea id="text" rows="4" required></textarea>
+        </div>
+
+        <div>
+          <label for="font">Font</label>
+          <select id="font"><option value="">Loading…</option></select>
+        </div>
+
+        <div>
+          <label for="font-size">Font size</label>
+          <input id="font-size" type="number" min="6" max="200" value="48" />
+        </div>
+
+        <div>
+          <label for="label-media">Label media</label>
+          <select id="label-media"><option value="">Loading…</option></select>
+        </div>
+
+        <div>
+          <label>Style</label>
+          <div class="checkboxes">
+            <label><input id="bold" type="checkbox" /> Bold</label>
+            <label><input id="italic" type="checkbox" /> Italic</label>
+          </div>
+        </div>
+
+        <div>
+          <label>Alignment</label>
+          <div class="radio-group">
+            <label><input type="radio" name="alignment" value="left" checked /> Left</label>
+            <label><input type="radio" name="alignment" value="center" /> Center</label>
+            <label><input type="radio" name="alignment" value="right" /> Right</label>
+          </div>
+        </div>
+
+        <div>
+          <label>Orientation</label>
+          <div class="radio-group">
+            <label><input type="radio" name="orientation" value="standard" checked /> Standard</label>
+            <label><input type="radio" name="orientation" value="rotated" /> Rotated</label>
+          </div>
+        </div>
+
+        <div class="actions">
+          <button type="button" id="btn-preview" disabled>Preview</button>
+          <button type="submit" id="btn-print" disabled>Print</button>
+        </div>
+      </form>
+      <div id="preview-area" class="preview-area" hidden>
+        <img id="preview-img" alt="Label preview" />
+      </div>
+    </div>
+  `;
+    const form = root.querySelector('#print-form');
+    const textarea = root.querySelector('#text');
+    const fontSelect = root.querySelector('#font');
+    const fontSizeInput = root.querySelector('#font-size');
+    const labelSelect = root.querySelector('#label-media');
+    const boldCheck = root.querySelector('#bold');
+    const italicCheck = root.querySelector('#italic');
+    const btnPreview = root.querySelector('#btn-preview');
+    const btnPrint = root.querySelector('#btn-print');
+    const statusMsg = root.querySelector('#status-msg');
+    const previewArea = root.querySelector('#preview-area');
+    const previewImg = root.querySelector('#preview-img');
+    let previewObjectUrl = null;
+    function showStatus(msg, kind) {
+        statusMsg.textContent = msg;
+        statusMsg.className = `status-msg ${kind}`;
+        statusMsg.hidden = false;
+    }
+    function hideStatus() {
+        statusMsg.hidden = true;
+    }
+    function updateButtons() {
+        const empty = textarea.value.trim() === '';
+        btnPrint.disabled = empty;
+        btnPreview.disabled = empty;
+    }
+    function buildRequest() {
+        const alignment = (form.querySelector('input[name="alignment"]:checked')?.value ?? 'left');
+        const orientation = (form.querySelector('input[name="orientation"]:checked')?.value ?? 'standard');
+        return {
+            text: textarea.value,
+            font: fontSelect.value,
+            font_size: parseInt(fontSizeInput.value, 10),
+            alignment,
+            orientation,
+            label_media: labelSelect.value,
+            bold: boldCheck.checked,
+            italic: italicCheck.checked,
+        };
+    }
+    textarea.addEventListener('input', updateButtons);
+    btnPreview.addEventListener('click', async () => {
+        btnPreview.disabled = true;
+        hideStatus();
+        try {
+            const blob = await previewQuick(buildRequest());
+            if (previewObjectUrl)
+                URL.revokeObjectURL(previewObjectUrl);
+            previewObjectUrl = URL.createObjectURL(blob);
+            previewImg.src = previewObjectUrl;
+            previewArea.hidden = false;
+        }
+        catch (err) {
+            showStatus(err.message, 'error');
+        }
+        finally {
+            updateButtons();
+        }
+    });
+    // Load fonts, labels, and settings in parallel; settings failure is non-fatal
+    Promise.all([
+        getFonts(),
+        getLabels(),
+        getSettings().catch((err) => {
+            console.warn('Failed to load settings:', err.message);
+            return null;
+        }),
+    ]).then(([fonts, labels, sett]) => {
+        // Populate fonts dropdown
+        fontSelect.innerHTML = fonts
+            .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
+            .join('');
+        // Group labels by form_factor
+        const groups = new Map();
+        for (const label of labels) {
+            const ff = label.form_factor;
+            if (!groups.has(ff))
+                groups.set(ff, []);
+            groups.get(ff).push(label);
+        }
+        for (const entries of groups.values()) {
+            entries.sort((a, b) => a.display_name.localeCompare(b.display_name));
+        }
+        const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])];
+        labelSelect.innerHTML = allKeys
+            .filter(k => groups.has(k))
+            .map(k => {
+            const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other';
+            const opts = groups
+                .get(k)
+                .map(l => `<option value="${esc(l.id)}">${esc(l.display_name)}</option>`)
+                .join('');
+            return `<optgroup label="${esc(groupLabel)}">${opts}</optgroup>`;
+        })
+            .join('');
+        // Restore form from settings; last_quick_print takes precedence over per-key defaults
+        const lqp = (sett?.last_quick_print ?? null);
+        if (lqp) {
+            fontSelect.value = lqp.font ?? String(sett?.default_font ?? 'DejaVuSans');
+            fontSizeInput.value = String(lqp.font_size ?? sett?.default_font_size ?? 48);
+            labelSelect.value = String(lqp.label_media ?? sett?.default_label_media ?? '62');
+            boldCheck.checked = lqp.bold ?? false;
+            italicCheck.checked = lqp.italic ?? false;
+            const aRadio = form.querySelector(`input[name="alignment"][value="${lqp.alignment ?? 'left'}"]`);
+            if (aRadio)
+                aRadio.checked = true;
+            const oRadio = form.querySelector(`input[name="orientation"][value="${lqp.orientation ?? 'standard'}"]`);
+            if (oRadio)
+                oRadio.checked = true;
+        }
+        else {
+            const defFont = String(sett?.default_font ?? 'DejaVuSans');
+            const defSize = String(sett?.default_font_size ?? 48);
+            const defMedia = String(sett?.default_label_media ?? '62');
+            const defOrientation = String(sett?.default_orientation ?? 'standard');
+            fontSelect.value = defFont;
+            fontSizeInput.value = defSize;
+            labelSelect.value = defMedia;
+            const oRadio = form.querySelector(`input[name="orientation"][value="${defOrientation}"]`);
+            if (oRadio)
+                oRadio.checked = true;
+        }
+    }).catch((err) => {
+        showStatus(`Failed to load form data: ${err.message}`, 'error');
+    });
+    form.addEventListener('submit', async (e) => {
+        e.preventDefault();
+        btnPrint.disabled = true;
+        hideStatus();
+        try {
+            const result = await quickPrint(buildRequest());
+            // "sent" = transmitted to printer network backend, not confirmed printed
+            showStatus(`Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`, 'success');
+        }
+        catch (err) {
+            showStatus(err.message, 'error');
+        }
+        finally {
+            updateButtons();
+        }
+    });
+}
diff --git a/frontend/src/pages/template-editor.js b/frontend/src/pages/template-editor.js
new file mode 100644
index 0000000..5bc3bb1
--- /dev/null
+++ b/frontend/src/pages/template-editor.js
@@ -0,0 +1,247 @@
+import { createTemplate, getFonts, getLabels, getTemplate, previewTemplate, updateTemplate } from '../api';
+import { navigate } from '../router';
+import { addTextElement, deleteSelected, getCanvasJSON, initCanvas, loadCanvasJSON, } from '../editor/canvas';
+function esc(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function parsePath() {
+    const path = window.location.pathname; // /templates/my-name
+    const parts = path.split('/');
+    const name = decodeURIComponent(parts[parts.length - 1] ?? '');
+    const params = new URLSearchParams(window.location.search);
+    const isNew = params.get('new') === '1';
+    const newMedia = params.get('media') ?? '';
+    return { name, isNew, newMedia };
+}
+export function mountTemplateEditor(root) {
+    const { name, isNew, newMedia } = parsePath();
+    // Widen the app container for the editor
+    const appEl = document.getElementById('app');
+    appEl?.classList.add('editor-mode');
+    root.innerHTML = `
+    <div class="editor-shell">
+      <div class="editor-toolbar">
+        <button id="btn-back">← Back</button>
+        <span class="toolbar-sep"></span>
+        <span class="editor-title" id="editor-title">${esc(name)}</span>
+        <span class="toolbar-sep"></span>
+        <button id="btn-add-text">Add Text</button>
+        <button id="btn-delete">Delete</button>
+        <span class="toolbar-sep"></span>
+        <select id="font-select" title="Font family" style="max-width:160px">
+          <option value="">Loading fonts…</option>
+        </select>
+        <input id="font-size" type="number" min="6" max="400" value="48" title="Font size" style="width:60px" />
+        <span class="toolbar-sep"></span>
+        <button id="btn-preview">Preview</button>
+        <button id="btn-save" class="btn-primary">Save</button>
+      </div>
+      <div id="editor-status" class="editor-status" hidden></div>
+      <div class="editor-canvas-wrap" id="canvas-wrap">
+        <div class="editor-canvas-inner" id="canvas-inner">
+          <canvas id="fabric-canvas"></canvas>
+        </div>
+      </div>
+      <div id="preview-area" class="preview-area" hidden style="padding:1rem">
+        <img id="preview-img" alt="Server render preview" style="max-width:100%;border:1px solid #ddd" />
+      </div>
+    </div>
+  `;
+    const btnBack = root.querySelector('#btn-back');
+    const btnAddText = root.querySelector('#btn-add-text');
+    const btnDelete = root.querySelector('#btn-delete');
+    const btnSave = root.querySelector('#btn-save');
+    const btnPreview = root.querySelector('#btn-preview');
+    const fontSelect = root.querySelector('#font-select');
+    const fontSizeInput = root.querySelector('#font-size');
+    const statusEl = root.querySelector('#editor-status');
+    const canvasWrap = root.querySelector('#canvas-wrap');
+    const previewArea = root.querySelector('#preview-area');
+    const previewImg = root.querySelector('#preview-img');
+    let fabricCanvas = null;
+    let labelMedia = newMedia;
+    let existsOnServer = !isNew;
+    let defaultFont = 'DejaVuSans';
+    let previewObjectUrl = null;
+    function showStatus(msg, kind) {
+        if (!msg) {
+            statusEl.hidden = true;
+            return;
+        }
+        statusEl.textContent = msg;
+        statusEl.className = `editor-status ${kind}`;
+        statusEl.hidden = false;
+    }
+    function getContainerWidth() {
+        return canvasWrap.clientWidth || 800;
+    }
+    async function initEditor(label) {
+        labelMedia = label.id;
+        const [w, h] = label.dots_printable;
+        const canvasEl = root.querySelector('#fabric-canvas');
+        const { canvas } = initCanvas(canvasEl, w, h, getContainerWidth());
+        fabricCanvas = canvas;
+        // Track selection to drive font controls
+        canvas.on('selection:created', updateFontControls);
+        canvas.on('selection:updated', updateFontControls);
+        canvas.on('selection:cleared', () => { });
+    }
+    function updateFontControls() {
+        if (!fabricCanvas)
+            return;
+        const obj = fabricCanvas.getActiveObject();
+        if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+            if (obj.fontFamily)
+                fontSelect.value = obj.fontFamily;
+            if (obj.fontSize)
+                fontSizeInput.value = String(Math.round(obj.fontSize));
+        }
+    }
+    fontSelect.addEventListener('change', () => {
+        if (!fabricCanvas)
+            return;
+        const obj = fabricCanvas.getActiveObject();
+        if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+            obj.set('fontFamily', fontSelect.value);
+            fabricCanvas.renderAll();
+        }
+    });
+    fontSizeInput.addEventListener('change', () => {
+        if (!fabricCanvas)
+            return;
+        const sz = parseInt(fontSizeInput.value, 10);
+        if (!isNaN(sz) && sz >= 6) {
+            const obj = fabricCanvas.getActiveObject();
+            if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+                obj.set('fontSize', sz);
+                fabricCanvas.renderAll();
+            }
+        }
+    });
+    btnBack.addEventListener('click', () => {
+        document.getElementById('app')?.classList.remove('editor-mode');
+        navigate('/templates');
+    });
+    btnAddText.addEventListener('click', () => {
+        if (!fabricCanvas)
+            return;
+        addTextElement(fabricCanvas, fontSelect.value || defaultFont);
+    });
+    btnDelete.addEventListener('click', () => {
+        if (!fabricCanvas)
+            return;
+        deleteSelected(fabricCanvas);
+    });
+    btnSave.addEventListener('click', () => void doSave());
+    btnPreview.addEventListener('click', () => void doPreview());
+    async function doSave() {
+        if (!fabricCanvas)
+            return;
+        const objs = fabricCanvas.getObjects();
+        if (objs.length === 0) {
+            showStatus('Add at least one element before saving.', 'error');
+            return;
+        }
+        btnSave.disabled = true;
+        showStatus('', '');
+        try {
+            const canvasJson = getCanvasJSON(fabricCanvas);
+            if (existsOnServer) {
+                await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia });
+            }
+            else {
+                await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson });
+                existsOnServer = true;
+            }
+            showStatus('Saved.', 'success');
+        }
+        catch (err) {
+            showStatus(err.message, 'error');
+        }
+        finally {
+            btnSave.disabled = false;
+        }
+    }
+    async function doPreview() {
+        if (!fabricCanvas)
+            return;
+        btnPreview.disabled = true;
+        showStatus('', '');
+        try {
+            // Save first so server has the latest canvas
+            const objs = fabricCanvas.getObjects();
+            if (objs.length > 0) {
+                const canvasJson = getCanvasJSON(fabricCanvas);
+                if (existsOnServer) {
+                    await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia });
+                }
+                else {
+                    await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson });
+                    existsOnServer = true;
+                }
+            }
+            // Build a fields dict: use field name as its own placeholder value for preview
+            const fields = {};
+            const blob = await previewTemplate(name, fields);
+            if (previewObjectUrl)
+                URL.revokeObjectURL(previewObjectUrl);
+            previewObjectUrl = URL.createObjectURL(blob);
+            previewImg.src = previewObjectUrl;
+            previewArea.hidden = false;
+        }
+        catch (err) {
+            showStatus(err.message, 'error');
+        }
+        finally {
+            btnPreview.disabled = false;
+        }
+    }
+    // Bootstrap: load label catalog + fonts, then either load existing template or init blank
+    Promise.all([getLabels(), getFonts()]).then(async ([labels, fonts]) => {
+        // Populate font selector
+        defaultFont = fonts[0]?.name ?? 'DejaVuSans';
+        fontSelect.innerHTML = fonts
+            .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
+            .join('');
+        // Try to select DejaVuSans as default
+        const dvs = fonts.find(f => f.name.includes('DejaVu') || f.name.includes('DejaVuSans'));
+        if (dvs) {
+            fontSelect.value = dvs.name;
+            defaultFont = dvs.name;
+        }
+        if (isNew) {
+            // New template: use newMedia from query params
+            const label = labels.find(l => l.id === newMedia);
+            if (!label) {
+                showStatus(`Unknown label media: ${newMedia}`, 'error');
+                return;
+            }
+            await initEditor(label);
+        }
+        else {
+            // Load existing template
+            try {
+                const tmpl = await getTemplate(name);
+                labelMedia = tmpl.label_media;
+                const label = labels.find(l => l.id === tmpl.label_media);
+                if (!label) {
+                    showStatus(`Unknown label media: ${tmpl.label_media}`, 'error');
+                    return;
+                }
+                await initEditor(label);
+                if (fabricCanvas && tmpl.canvas_json && Object.keys(tmpl.canvas_json).length > 0) {
+                    await loadCanvasJSON(fabricCanvas, tmpl.canvas_json);
+                }
+            }
+            catch (err) {
+                showStatus(err.message, 'error');
+            }
+        }
+    }).catch((err) => {
+        showStatus(`Failed to load: ${err.message}`, 'error');
+    });
+}
diff --git a/frontend/src/pages/templates-list.js b/frontend/src/pages/templates-list.js
new file mode 100644
index 0000000..c2510c6
--- /dev/null
+++ b/frontend/src/pages/templates-list.js
@@ -0,0 +1,196 @@
+import { deleteTemplate, listTemplates } from '../api';
+import { navigate } from '../router';
+function esc(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function fmtDate(iso) {
+    if (!iso)
+        return '—';
+    try {
+        return new Date(iso).toLocaleString();
+    }
+    catch {
+        return iso;
+    }
+}
+export function mountTemplatesList(root) {
+    root.innerHTML = `
+    <div class="templates-list">
+      <div class="templates-list-header">
+        <h2>Templates</h2>
+        <button id="btn-new-template">New template</button>
+      </div>
+      <div id="tpl-status" class="status-msg" hidden></div>
+      <div id="tpl-body"></div>
+    </div>
+  `;
+    const btnNew = root.querySelector('#btn-new-template');
+    const statusEl = root.querySelector('#tpl-status');
+    const bodyEl = root.querySelector('#tpl-body');
+    function showStatus(msg, kind) {
+        statusEl.textContent = msg;
+        statusEl.className = `status-msg ${kind}`;
+        statusEl.hidden = false;
+    }
+    function renderList(templates) {
+        if (templates.length === 0) {
+            bodyEl.innerHTML = `<p class="empty-state">No templates yet. Create one.</p>`;
+            return;
+        }
+        bodyEl.innerHTML = `
+      <table class="tpl-table">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Media</th>
+            <th>Updated</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody>
+          ${templates.map(t => `
+            <tr data-name="${esc(t.name)}">
+              <td>${esc(t.display_name || t.name)}</td>
+              <td><code>${esc(t.label_media)}</code></td>
+              <td>${esc(fmtDate(t.updated_at))}</td>
+              <td class="tpl-actions">
+                <button class="btn-edit" data-name="${esc(t.name)}">Edit</button>
+                <button class="btn-delete" data-name="${esc(t.name)}">Delete</button>
+              </td>
+            </tr>
+          `).join('')}
+        </tbody>
+      </table>
+    `;
+        bodyEl.querySelectorAll('.btn-edit').forEach(btn => {
+            btn.addEventListener('click', () => navigate(`/templates/${btn.dataset.name}`));
+        });
+        bodyEl.querySelectorAll('.btn-delete').forEach(btn => {
+            btn.addEventListener('click', async () => {
+                const name = btn.dataset.name;
+                if (!confirm(`Delete template "${name}"? This cannot be undone.`))
+                    return;
+                btn.disabled = true;
+                try {
+                    await deleteTemplate(name);
+                    await load();
+                }
+                catch (err) {
+                    showStatus(err.message, 'error');
+                    btn.disabled = false;
+                }
+            });
+        });
+    }
+    async function load() {
+        bodyEl.innerHTML = `<p>Loading…</p>`;
+        statusEl.hidden = true;
+        try {
+            const templates = await listTemplates();
+            renderList(templates);
+        }
+        catch (err) {
+            showStatus(err.message, 'error');
+            bodyEl.innerHTML = '';
+        }
+    }
+    btnNew.addEventListener('click', () => {
+        showNewTemplateModal(() => load());
+    });
+    void load();
+}
+function showNewTemplateModal(onCreated) {
+    import('../api').then(({ getLabels }) => {
+        const overlay = document.createElement('div');
+        overlay.className = 'modal-overlay';
+        overlay.innerHTML = `
+      <div class="modal">
+        <h3>New template</h3>
+        <div class="modal-status" hidden></div>
+        <label>
+          Name (slug)
+          <input id="modal-name" type="text" placeholder="my-template" autocomplete="off" />
+          <span class="field-error" id="name-error" hidden></span>
+        </label>
+        <label>
+          Label media
+          <select id="modal-media"><option value="">Loading…</option></select>
+        </label>
+        <div class="modal-actions">
+          <button id="modal-cancel">Cancel</button>
+          <button id="modal-ok" class="btn-primary" disabled>Create</button>
+        </div>
+      </div>
+    `;
+        document.body.appendChild(overlay);
+        const nameInput = overlay.querySelector('#modal-name');
+        const mediaSelect = overlay.querySelector('#modal-media');
+        const cancelBtn = overlay.querySelector('#modal-cancel');
+        const okBtn = overlay.querySelector('#modal-ok');
+        const nameError = overlay.querySelector('#name-error');
+        const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+        const FORM_FACTOR_LABEL = { 1: 'Die-cut', 2: 'Continuous', 3: 'Round', 4: 'P-touch Continuous' };
+        const FF_ORDER = [2, 1, 3, 4];
+        function esc2(s) {
+            return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        }
+        function validate() {
+            const v = nameInput.value.trim();
+            if (!v) {
+                nameError.textContent = 'Name is required';
+                nameError.hidden = false;
+                return false;
+            }
+            if (!SLUG_RE.test(v)) {
+                nameError.textContent = 'Use lowercase letters, numbers, hyphens only';
+                nameError.hidden = false;
+                return false;
+            }
+            nameError.hidden = true;
+            return true;
+        }
+        function updateOk() {
+            okBtn.disabled = !nameInput.value.trim() || !mediaSelect.value;
+        }
+        nameInput.addEventListener('input', () => { validate(); updateOk(); });
+        mediaSelect.addEventListener('change', updateOk);
+        getLabels().then(labels => {
+            const groups = new Map();
+            for (const l of labels) {
+                if (!groups.has(l.form_factor))
+                    groups.set(l.form_factor, []);
+                groups.get(l.form_factor).push(l);
+            }
+            for (const entries of groups.values())
+                entries.sort((a, b) => a.display_name.localeCompare(b.display_name));
+            const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])];
+            mediaSelect.innerHTML = allKeys
+                .filter(k => groups.has(k))
+                .map(k => {
+                const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other';
+                const opts = groups.get(k).map(l => `<option value="${esc2(l.id)}">${esc2(l.display_name)}</option>`).join('');
+                return `<optgroup label="${esc2(groupLabel)}">${opts}</optgroup>`;
+            })
+                .join('');
+            updateOk();
+        });
+        cancelBtn.addEventListener('click', () => overlay.remove());
+        overlay.addEventListener('click', e => { if (e.target === overlay)
+            overlay.remove(); });
+        okBtn.addEventListener('click', () => {
+            if (!validate())
+                return;
+            const name = nameInput.value.trim();
+            const media = mediaSelect.value;
+            overlay.remove();
+            // Navigate to editor — template created on first Save
+            navigate(`/templates/${name}?new=1&media=${encodeURIComponent(media)}`);
+            onCreated();
+        });
+        nameInput.focus();
+    });
+}
diff --git a/frontend/src/pages/templates.js b/frontend/src/pages/templates.js
new file mode 100644
index 0000000..5a0678d
--- /dev/null
+++ b/frontend/src/pages/templates.js
@@ -0,0 +1 @@
+export { mountTemplatesList as mountTemplates } from './templates-list';
diff --git a/frontend/src/router.js b/frontend/src/router.js
new file mode 100644
index 0000000..c995af0
--- /dev/null
+++ b/frontend/src/router.js
@@ -0,0 +1,52 @@
+const routes = {};
+const prefixRoutes = [];
+export function register(path, mount) {
+    routes[path] = mount;
+}
+/** Register a handler for all paths that start with `prefix`. */
+export function registerPrefix(prefix, mount) {
+    prefixRoutes.push({ prefix, mount });
+}
+function setActiveNav(path) {
+    document.querySelectorAll('[data-route]').forEach(a => {
+        a.classList.toggle('active', a.dataset.route === path || path.startsWith(a.dataset.route + '/'));
+    });
+}
+export function navigate(path) {
+    history.pushState(null, '', path);
+    render(path);
+}
+function render(path) {
+    const root = document.getElementById('app');
+    if (!root)
+        return;
+    const exact = routes[path];
+    if (exact) {
+        setActiveNav(path);
+        exact(root);
+        return;
+    }
+    for (const { prefix, mount } of prefixRoutes) {
+        if (path.startsWith(prefix)) {
+            setActiveNav(path);
+            mount(root);
+            return;
+        }
+    }
+    const fallback = routes['/'];
+    if (fallback) {
+        setActiveNav(path);
+        fallback(root);
+    }
+}
+export function initRouter() {
+    document.addEventListener('click', e => {
+        const target = e.target.closest('[data-route]');
+        if (!target)
+            return;
+        e.preventDefault();
+        navigate(target.dataset.route);
+    });
+    window.addEventListener('popstate', () => render(window.location.pathname));
+    render(window.location.pathname);
+}
diff --git a/frontend/src/types.js b/frontend/src/types.js
new file mode 100644
index 0000000..cb0ff5c
--- /dev/null
+++ b/frontend/src/types.js
@@ -0,0 +1 @@
+export {};

From 6f7afe82b3fa61ad432cc81323d4228ee214bf78 Mon Sep 17 00:00:00 2001
From: crzykidd <mander@crzynet.com>
Date: Sat, 23 May 2026 22:37:20 -0700
Subject: [PATCH 32/84] update

---
 .github/copilot-instructions.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..86e3897
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,28 @@
+## vexp context tools <!-- vexp v2.0.17 -->
+
+**MANDATORY: use `run_pipeline` — do NOT grep, glob, or read files manually.**
+vexp returns pre-indexed, graph-ranked context in a single call.
+
+### Workflow
+1. `run_pipeline` with your task description — ALWAYS FIRST (replaces all other tools)
+2. Make targeted changes based on the context returned
+3. `run_pipeline` again only if you need more context
+
+### Available MCP tools
+- `run_pipeline` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
+  Auto-detects intent. Includes file content. Example: `run_pipeline({ "task": "fix auth bug" })`
+- `get_skeleton` — compact file structure
+- `index_status` — indexing status
+- `expand_vexp_ref` — expand V-REF placeholders in v2 output
+
+### Agentic search
+- Do NOT use built-in file search, grep, or codebase indexing — always call `run_pipeline` first
+- If you spawn sub-agents or background tasks, pass them the context from `run_pipeline`
+  rather than letting them search the codebase independently
+
+### Smart Features
+Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
+
+### Multi-Repo
+`run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope. Run `index_status` to see aliases.
+<!-- /vexp -->
\ No newline at end of file

From d67bc6101f9a9e1ef15b04cc6a4dba52872d7574 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 24 May 2026 00:03:04 -0700
Subject: [PATCH 33/84] Untrack vexp runtime files and ignore vexp.toml

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore           | 12 ++----------
 .vexp/.gitattributes |  2 --
 .vexp/manifest.json  | 27 ---------------------------
 3 files changed, 2 insertions(+), 39 deletions(-)
 delete mode 100644 .vexp/.gitattributes
 delete mode 100644 .vexp/manifest.json

diff --git a/.gitignore b/.gitignore
index ac33dab..f353fee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,22 +47,14 @@ data-dev/
 *.sqlite
 *.sqlite3
 
-# vexp (VS Code extension daemon — all runtime state)
+# vexp (VS Code extension daemon — all runtime state, config regenerable)
 .vexp/
+vexp.toml
 
 # Logs
 *.log
 logs/
 
-# vexp — local index only; manifest.json and .gitattributes are tracked
-.vexp/index.db
-.vexp/index.db-wal
-.vexp/index.db-shm
-.vexp/healthy
-.vexp/daemon.pid
-.vexp/daemon.pipe
-.vexp/vexp.log
-
 # claude 
 .claude/
 
diff --git a/.vexp/.gitattributes b/.vexp/.gitattributes
deleted file mode 100644
index 7ebdf05..0000000
--- a/.vexp/.gitattributes
+++ /dev/null
@@ -1,2 +0,0 @@
-# Generated by vexp — index.db is gitignored, only manifest.json is tracked
-manifest.json merge=union
diff --git a/.vexp/manifest.json b/.vexp/manifest.json
deleted file mode 100644
index d6f26fc..0000000
--- a/.vexp/manifest.json
+++ /dev/null
@@ -1,27 +0,0 @@
-{
-  "file_hashes": {
-    "CHANGELOG.md": "d7bf580fb13c7b575f426b4fefc62a506c1cc615dc813a42f78f499ed9df0146",
-    "CLAUDE.md": "2837c4f80ba6e74a987c949c9bf1e4187c48754fdef7689769b90bda8b228624",
-    "README.md": "f37e9eeb4136973e6bdb5d56cef96148cc4b61eecc241080a9dcfff2505a080a",
-    "docs/PRD.md": "112695a62c4caca08095adf0fcba7cdec26f182d64c2f8d591fa45223a553a85",
-    "docs/architecture.md": "23c129232659739a7e59862b72b724d5dc97d4bad04a9fd3f9ffeefc9f7d6778",
-    "docs/decisions.md": "8ed2d9e4e57170c26395ffa857eb1b766052658e13f9c9f41dba3abb04a95948",
-    "docs/features/api.md": "a93de1dc6b551d270876d63eb3e5db7fddfcc42d14c80f579c8e492a0596c963",
-    "docs/features/history.md": "0a5c43c443c29169c6af8b9f57812eeb227f4c8c9ade775ef8eb9e351eaf903e",
-    "docs/features/label-catalog.md": "5aac08fa21ec923ff18462c59bc06e9ef70005bdcefde8f165409d3887f97ca4",
-    "docs/features/printer-status.md": "578c19ca5f251485acd2c2556bc6dd23c2213eb9a3491c017c1bc13780303e23",
-    "docs/features/quick-print.md": "0d9169bd53c23d661c4ecd8226f4a4392671dd3dddf278b0a64d2a5e5c77c933",
-    "docs/features/settings.md": "40c80d62f5f2d47b6941c7e867f5fb19871becf2e56c5e4924cbd2d5c371bf0b",
-    "docs/features/templates.md": "b4397a068d02f0bfc686a89357ddc6508b7890a20b458c41d2d8e4d61cdfad2e",
-    "docs/glossary.md": "997b9148fad45a6927be253ed0162b845bd34848dd683b052812c58661e798db"
-  },
-  "indexed_at_commit": "24dea5380a133f2d48203c7531d19de61626111d",
-  "indexed_at_timestamp": "2026-05-20T02:38:25.457908200+00:00",
-  "schema_version": 3,
-  "stats": {
-    "total_edges": 163,
-    "total_files": 14,
-    "total_nodes": 177
-  },
-  "vexp_version": "2.0.17"
-}
\ No newline at end of file

From 7595587bcf81143a8b0736e2e29bea1879fc0976 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 18:12:19 -0700
Subject: [PATCH 34/84] Add session workflow and handoff prompt process to
 CLAUDE.md

---
 CLAUDE.md | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 82350c3..43c6db3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -53,11 +53,38 @@ From the session prompt that owns this project:
 - Don't write a 50-line README before there's code
 - Don't propose features not in the PRD
 
+## Session workflow
+
+Every task follows: **plan → decide → execute → document**.
+
+1. **Plan first.** Before writing code, outline what will change and why. For small fixes the plan can be verbal in-session. For larger features, produce a handoff prompt (see below).
+2. **Decide: current session or handoff.** If the plan is scoped and the current session has context, do it here. If it's a large feature slice or a fresh context would be cleaner, write a handoff prompt for a new session.
+3. **Handoff prompts live in `prompts/`.** Checked into git. Format:
+   ```
+   prompts/YYYY-MM-DD-short-description.md
+   ```
+   Frontmatter:
+   ```yaml
+   ---
+   name: YYYY-MM-DD-short-description
+   status: pending          # pending | completed | failed
+   created: YYYY-MM-DD
+   completed:               # filled when done
+   result:                  # one-line summary of outcome
+   ---
+   ```
+   The **last instruction** in every handoff prompt must be: update this file's frontmatter — set status, completed date, and result summary.
+4. **To run a handoff prompt:** `cat prompts/file.md | claude`
+5. **Changelog entry required.** Every change — feature, fix, refactor — gets a short entry in `CHANGELOG.md` under `## [Unreleased]`. Write it for release notes (concise, user-facing language).
+6. **All dev work on `dev`** unless explicitly told otherwise.
+7. **Commit, don't push.** Sessions commit their work with a descriptive message. The owner pushes.
+8. **Planning prompts for large features.** The owner will ask for a planning session prompt when scoping a new feature block. That prompt gets handed to a fresh session to execute.
+
 ## Repo conventions
 
 - Line endings: LF only. `.gitattributes` enforces this. If `git diff --stat` shows all files modified, run `git config core.autocrlf input && git checkout -- .`
 - Branches: `main` is protected — the ONLY way in is a pull request, gated by CodeQL and other checks; never push to `main` directly. `dev` is the working branch (solo work commits straight to `dev`). Use `feature/<name>` branches when more than one person is working; merge those to `dev`, then PR `dev` → `main` for a release.
-- Commits: imperative present tense ("Add template recall endpoint" not "Added"). No conventional-commits prefixes.
+- Commits: imperative present tense ("Add template recall endpoint" not "Added"). No conventional-commits prefixes. No co-author tags.
 - Compose stack lives at the repo root as `compose.yml`. Dev compose at `compose.dev.yml`.
 
 ## Things to never do

From 90e4023cd21a9a639eebfab590379200a0d5f4a7 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 18:19:37 -0700
Subject: [PATCH 35/84] Add template recall UI handoff prompt and fix
 prompt-file docs

---
 CLAUDE.md                                |   2 +-
 prompts/2026-05-25-template-recall-ui.md | 175 +++++++++++++++++++++++
 2 files changed, 176 insertions(+), 1 deletion(-)
 create mode 100644 prompts/2026-05-25-template-recall-ui.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 43c6db3..606b62b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -74,7 +74,7 @@ Every task follows: **plan → decide → execute → document**.
    ---
    ```
    The **last instruction** in every handoff prompt must be: update this file's frontmatter — set status, completed date, and result summary.
-4. **To run a handoff prompt:** `cat prompts/file.md | claude`
+4. **To run a handoff prompt:** `claude "$(cat prompts/file.md)"` (interactive session with file as opening prompt)
 5. **Changelog entry required.** Every change — feature, fix, refactor — gets a short entry in `CHANGELOG.md` under `## [Unreleased]`. Write it for release notes (concise, user-facing language).
 6. **All dev work on `dev`** unless explicitly told otherwise.
 7. **Commit, don't push.** Sessions commit their work with a descriptive message. The owner pushes.
diff --git a/prompts/2026-05-25-template-recall-ui.md b/prompts/2026-05-25-template-recall-ui.md
new file mode 100644
index 0000000..b5fd7d6
--- /dev/null
+++ b/prompts/2026-05-25-template-recall-ui.md
@@ -0,0 +1,175 @@
+---
+name: 2026-05-25-template-recall-ui
+status: pending
+created: 2026-05-25
+completed:
+result:
+---
+
+# Template Recall UI
+
+Build the frontend "recall" flow: pick a template, fill variable fields, preview, print, and batch print. The backend is done — this is frontend-only work.
+
+## Context
+
+Read these before starting:
+- `CLAUDE.md` — project rules, session workflow, stack
+- `docs/features/templates.md` — the "Recall (print from template)" section is the spec
+- `docs/glossary.md` — vocabulary
+
+The app is a Vite + TypeScript SPA (no React/Vue). Pages are plain functions that receive a root `HTMLElement` and render into it with innerHTML + event listeners. See `frontend/src/pages/templates-list.ts` and `frontend/src/pages/quick-print.ts` as patterns.
+
+## What exists already
+
+**Backend endpoints (all working, all require Bearer auth):**
+- `POST /api/print/{name}` — body: `{ "fields": { "key": "value" } }` → prints one label
+- `POST /api/print/{name}/batch` — body: `{ "labels": [{ "key": "value" }, ...] }` → prints N labels with per-label field values
+- `POST /api/preview/{name}` — body: `{ "fields": { "key": "value" } }` → returns PNG blob
+
+**Frontend API client (`frontend/src/api.ts`):**
+- `previewTemplate(name, fields)` — already exists, returns `Promise<Blob>`
+- `printTemplate` — DOES NOT EXIST, needs to be added
+- `batchPrint` — DOES NOT EXIST, needs to be added
+- All other CRUD functions exist (`listTemplates`, `getTemplate`, etc.)
+
+**Types (`frontend/src/types.ts`):**
+- `Template` — has `field_schema: FieldSpec[]`
+- `FieldSpec` — `{ name, type, required, default, increment, enum_values }`
+- `PrintJobResponse` — `{ job_id, status, preview_url }`
+
+**Routing (`frontend/src/router.ts`):**
+- `register(path, mountFn)` — exact path match
+- `registerPrefix(prefix, mountFn)` — prefix match (first match wins)
+- `navigate(path)` — client-side navigation
+- Currently registered in `main.ts`:
+  - `/` → quick-print
+  - `/templates` → templates list
+  - `/templates/` prefix → template editor
+
+**Templates list (`frontend/src/pages/templates-list.ts`):**
+- Each row has Edit and Delete buttons. Needs a **Print** button added that navigates to the recall page.
+
+## What to build
+
+### 1. Add API client functions
+
+In `frontend/src/api.ts`, add:
+
+```typescript
+function printTemplate(name: string, fields: Record<string, string>): Promise<PrintJobResponse> {
+  return apiFetch<PrintJobResponse>(`/api/print/${encodeURIComponent(name)}`, {
+    method: 'POST',
+    body: JSON.stringify({ fields }),
+  })
+}
+```
+
+And a `batchPrint` function that calls `POST /api/print/{name}/batch` with `{ labels: [...] }` and returns `Promise<BatchPrintResponse>`. Add `BatchJobResult` and `BatchPrintResponse` types to `types.ts`:
+
+```typescript
+interface BatchJobResult {
+  job_id: number;
+  status: string;
+}
+
+interface BatchPrintResponse {
+  batch_id: string;
+  jobs: BatchJobResult[];
+  succeeded: number;
+  failed: number;
+}
+```
+
+Export both new API functions.
+
+### 2. Create the recall page
+
+New file: `frontend/src/pages/template-recall.ts`
+
+Export `mountTemplateRecall(root: HTMLElement): void`
+
+**Behavior:**
+
+1. Extract template name from URL path (`/templates/:name/print` → name)
+2. Fetch the template via `getTemplate(name)`
+3. If template has no `field_schema` (no variable fields), show a simple "Preview / Print" UI with no form
+4. If template has fields, auto-generate a form:
+   - One input per field in `field_schema`
+   - Text input for `type: "text"` and `type: "number"` and `type: "date"`
+   - `<select>` for `type: "enum"` populated from `enum_values`
+   - Pre-fill with `default` value if set
+   - Mark required fields (HTML `required` attribute + visual indicator)
+   - Client-side validation: all required fields must be non-empty before Print is enabled
+5. **Preview button**: collect field values from the form, call `previewTemplate(name, fields)`, display the returned PNG below the form. Preview should update live as fields change (debounced, ~500ms after last keystroke).
+6. **Print button**: collect field values, call `printTemplate(name, fields)`, show success/error status message
+7. **Batch section**: if ANY field in `field_schema` has `increment: true`:
+   - Show a "Batch" toggle/checkbox
+   - When enabled, show a "Count" number input (default 1, min 1, max 1000)
+   - Show which fields will increment (read-only info)
+   - Print button in batch mode calls `batchPrint` — construct the `labels` array by advancing increment fields using the same logic as the backend (`advance()` in `fields.py`): increment trailing digits, preserve zero-padding
+   - Show batch result summary (succeeded/failed counts)
+8. **Back link**: navigate to `/templates`
+9. **Header**: show template display_name, label media
+
+### 3. Update routing
+
+The prefix `/templates/` currently catches all sub-paths for the editor. We need to distinguish:
+- `/templates/:name/print` → recall page
+- `/templates/:name` → editor
+
+In `frontend/src/main.ts`, register the more-specific prefix first:
+
+```typescript
+registerPrefix('/templates/', (root) => {
+  const path = window.location.pathname
+  if (path.endsWith('/print')) {
+    mountTemplateRecall(root)
+  } else {
+    mountTemplateEditor(root)
+  }
+})
+```
+
+This replaces the current `registerPrefix('/templates/', mountTemplateEditor)` line. Import `mountTemplateRecall` from the new page module.
+
+### 4. Add Print button to templates list
+
+In `frontend/src/pages/templates-list.ts`, add a **Print** button to each template row (alongside Edit and Delete). It should navigate to `/templates/${name}/print`.
+
+### 5. Styling
+
+Use the existing CSS patterns from `frontend/src/style.css`. The recall page should look consistent with the quick-print page. Key elements:
+- Form inputs styled like existing inputs
+- Preview image displayed at a reasonable size (scale to fit, not full label-pixel resolution)
+- Status messages use the existing `.status-msg` pattern
+- Batch section visually grouped (fieldset or bordered section)
+
+### 6. Changelog
+
+Add entry under `## [Unreleased]` → `### Added`:
+
+```
+- **Template recall UI** — fill variable fields, preview, and print from saved templates at `/templates/{name}/print`; batch printing with auto-increment for numeric fields
+```
+
+## Do NOT
+
+- Do not modify any backend code — the backend is complete
+- Do not add new npm dependencies
+- Do not change the template editor page
+- Do not add features beyond what's described here (no history, no settings)
+- Do not write JS files — TypeScript only (the `.js` files are build artifacts)
+
+## How to verify
+
+1. Run: `docker compose -f compose.dev.yml up --build -d`
+2. Open `http://localhost:8001/templates`
+3. Create a template in the editor with text containing `{name}` and `{number}` placeholders, save it
+4. Click Print on that template in the list
+5. Verify the recall form shows inputs for `name` and `number`
+6. Fill values, click Preview — should show server-rendered PNG
+7. Click Print — should get success response (will fail to actually print if no printer, that's fine — check for a non-error API response)
+
+## Final step
+
+Update this file's frontmatter: set `status` to `completed` or `failed`, fill in `completed` date, and write a one-line `result` summary.

From ca58bfdd43f05a900efc4ac12883d022c175912d Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 18:24:15 -0700
Subject: [PATCH 36/84] Fix handoff prompt run command to escape frontmatter
 dashes

---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 606b62b..e15c31d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -74,7 +74,7 @@ Every task follows: **plan → decide → execute → document**.
    ---
    ```
    The **last instruction** in every handoff prompt must be: update this file's frontmatter — set status, completed date, and result summary.
-4. **To run a handoff prompt:** `claude "$(cat prompts/file.md)"` (interactive session with file as opening prompt)
+4. **To run a handoff prompt:** `claude -- "$(cat prompts/file.md)"` (interactive session with file as opening prompt)
 5. **Changelog entry required.** Every change — feature, fix, refactor — gets a short entry in `CHANGELOG.md` under `## [Unreleased]`. Write it for release notes (concise, user-facing language).
 6. **All dev work on `dev`** unless explicitly told otherwise.
 7. **Commit, don't push.** Sessions commit their work with a descriptive message. The owner pushes.

From 54d57fc950f7c735c9e484c5076a89c8f027af8a Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 18:27:26 -0700
Subject: [PATCH 37/84] Require ADR entry when session makes non-obvious
 decisions

---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index e15c31d..6586401 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -73,7 +73,7 @@ Every task follows: **plan → decide → execute → document**.
    result:                  # one-line summary of outcome
    ---
    ```
-   The **last instruction** in every handoff prompt must be: update this file's frontmatter — set status, completed date, and result summary.
+   The **last instruction** in every handoff prompt must be: update this file's frontmatter — set status, completed date, and result summary. If any non-obvious decisions were made during the session (approach changed, alternative rejected, workaround needed), record them in `docs/decisions.md` as an ADR entry.
 4. **To run a handoff prompt:** `claude -- "$(cat prompts/file.md)"` (interactive session with file as opening prompt)
 5. **Changelog entry required.** Every change — feature, fix, refactor — gets a short entry in `CHANGELOG.md` under `## [Unreleased]`. Write it for release notes (concise, user-facing language).
 6. **All dev work on `dev`** unless explicitly told otherwise.

From e5b4423574257ac4a35389b45ac1c251efe6a8c9 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 18:37:28 -0700
Subject: [PATCH 38/84] Stop tracking compiled JS emitted next to TS source

tsc was emitting .js next to every .ts in frontend/src (no noEmit set),
and those artifacts were committed. Vite compiles the .ts directly and the
Docker build compiles fresh, so the tracked .js were unused dead weight.

- Set noEmit in tsconfig so tsc is typecheck-only
- Untrack the 9 src/**/*.js artifacts
- Ignore frontend/src/**/*.js
---
 .gitignore                            |   2 +
 frontend/src/api.js                   | 109 -----------
 frontend/src/editor/canvas.js         |  69 -------
 frontend/src/main.js                  |   9 -
 frontend/src/pages/quick-print.js     | 248 --------------------------
 frontend/src/pages/template-editor.js | 247 -------------------------
 frontend/src/pages/templates-list.js  | 196 --------------------
 frontend/src/pages/templates.js       |   1 -
 frontend/src/router.js                |  52 ------
 frontend/src/types.js                 |   1 -
 frontend/tsconfig.json                |   1 +
 11 files changed, 3 insertions(+), 932 deletions(-)
 delete mode 100644 frontend/src/api.js
 delete mode 100644 frontend/src/editor/canvas.js
 delete mode 100644 frontend/src/main.js
 delete mode 100644 frontend/src/pages/quick-print.js
 delete mode 100644 frontend/src/pages/template-editor.js
 delete mode 100644 frontend/src/pages/templates-list.js
 delete mode 100644 frontend/src/pages/templates.js
 delete mode 100644 frontend/src/router.js
 delete mode 100644 frontend/src/types.js

diff --git a/.gitignore b/.gitignore
index f353fee..30ecda2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,6 +25,8 @@ node_modules/
 
 # Frontend build output (consumed by FastAPI in container build)
 frontend/dist/
+# Compiled TS output emitted next to source (tsc artifacts; not used by Vite)
+frontend/src/**/*.js
 
 # IDE
 .vscode/
diff --git a/frontend/src/api.js b/frontend/src/api.js
deleted file mode 100644
index 9d96247..0000000
--- a/frontend/src/api.js
+++ /dev/null
@@ -1,109 +0,0 @@
-export const TOKEN_KEY = 'labelforge_token';
-function getToken() {
-    return localStorage.getItem(TOKEN_KEY) ?? '';
-}
-async function apiFetch(path, options = {}) {
-    const res = await fetch(path, {
-        ...options,
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${getToken()}`,
-            ...options.headers,
-        },
-    });
-    if (!res.ok) {
-        let detail = `HTTP ${res.status}`;
-        try {
-            const body = await res.json();
-            if (body.detail)
-                detail = String(body.detail);
-        }
-        catch { /* use status fallback */ }
-        throw new Error(detail);
-    }
-    return res.json();
-}
-export function getLabels() {
-    return apiFetch('/api/labels');
-}
-export function getFonts() {
-    return apiFetch('/api/fonts');
-}
-export function quickPrint(req) {
-    return apiFetch('/api/print/quick', {
-        method: 'POST',
-        body: JSON.stringify(req),
-    });
-}
-export async function previewQuick(req) {
-    const res = await fetch('/api/preview/quick', {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${getToken()}`,
-        },
-        body: JSON.stringify(req),
-    });
-    if (!res.ok) {
-        let detail = `HTTP ${res.status}`;
-        try {
-            const body = await res.json();
-            if (body.detail)
-                detail = String(body.detail);
-        }
-        catch { /* use status fallback */ }
-        throw new Error(detail);
-    }
-    return res.blob();
-}
-export function listTemplates() {
-    return apiFetch('/api/templates');
-}
-export function getTemplate(name) {
-    return apiFetch(`/api/templates/${encodeURIComponent(name)}`);
-}
-export function createTemplate(body) {
-    return apiFetch('/api/templates', {
-        method: 'POST',
-        body: JSON.stringify(body),
-    });
-}
-export function updateTemplate(name, body) {
-    return apiFetch(`/api/templates/${encodeURIComponent(name)}`, {
-        method: 'PUT',
-        body: JSON.stringify(body),
-    });
-}
-export function deleteTemplate(name) {
-    return apiFetch(`/api/templates/${encodeURIComponent(name)}`, { method: 'DELETE' });
-}
-export async function previewTemplate(name, fields) {
-    const res = await fetch(`/api/preview/${encodeURIComponent(name)}`, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${getToken()}`,
-        },
-        body: JSON.stringify({ fields }),
-    });
-    if (!res.ok) {
-        let detail = `HTTP ${res.status}`;
-        try {
-            const body = await res.json();
-            if (body.detail)
-                detail = String(body.detail);
-        }
-        catch { /* use status fallback */ }
-        throw new Error(detail);
-    }
-    return res.blob();
-}
-export function getSettings() {
-    return apiFetch('/api/settings');
-}
-export function putSettings(partial) {
-    return apiFetch('/api/settings', {
-        method: 'PUT',
-        body: JSON.stringify(partial),
-    });
-}
diff --git a/frontend/src/editor/canvas.js b/frontend/src/editor/canvas.js
deleted file mode 100644
index a52bfd9..0000000
--- a/frontend/src/editor/canvas.js
+++ /dev/null
@@ -1,69 +0,0 @@
-import { Canvas, FabricObject, IText } from 'fabric';
-export const CUSTOM_PROPS = ['labelforge_raw_content'];
-// Register the custom prop so canvas.toJSON() includes it on every object automatically.
-FabricObject.customProperties.push('labelforge_raw_content');
-/** Create a Fabric Canvas sized to label pixels, displayed scaled to fit the container. */
-export function initCanvas(el, labelW, labelH, containerW) {
-    const maxDisplayH = 600;
-    const scale = Math.min(1, (containerW - 48) / labelW, maxDisplayH / labelH);
-    const displayW = Math.round(labelW * scale);
-    const displayH = Math.round(labelH * scale);
-    const canvas = new Canvas(el, {
-        backgroundColor: '#ffffff',
-        selection: true,
-    });
-    canvas.setDimensions({ width: displayW, height: displayH });
-    canvas.setZoom(scale);
-    // Sync labelforge_raw_content whenever text is edited inline.
-    // text:changed target is IText — no manual annotation needed.
-    canvas.on('text:changed', (e) => {
-        e.target.set('labelforge_raw_content', e.target.text ?? '');
-    });
-    return { canvas, scale };
-}
-export function addTextElement(canvas, defaultFont) {
-    const vp = canvas.viewportTransform ?? [1, 0, 0, 1, 0, 0];
-    const scale = vp[0];
-    const canvasVirtualW = (canvas.width ?? 400) / scale;
-    const canvasVirtualH = (canvas.height ?? 200) / scale;
-    const text = new IText('Text', {
-        left: Math.round(canvasVirtualW * 0.05),
-        top: Math.round(canvasVirtualH * 0.05),
-        fontFamily: defaultFont,
-        fontSize: 48,
-        fill: '#000000',
-    });
-    text.set('labelforge_raw_content', 'Text');
-    // Keep raw content in sync when text changes
-    text.on('changed', () => {
-        text.set('labelforge_raw_content', text.text ?? '');
-    });
-    canvas.add(text);
-    canvas.setActiveObject(text);
-    canvas.renderAll();
-}
-export function deleteSelected(canvas) {
-    const active = canvas.getActiveObjects();
-    if (active.length === 0)
-        return;
-    active.forEach(obj => canvas.remove(obj));
-    canvas.discardActiveObject();
-    canvas.renderAll();
-}
-export function getCanvasJSON(canvas) {
-    // customProperties registered above ensures labelforge_raw_content is included.
-    return canvas.toJSON();
-}
-export async function loadCanvasJSON(canvas, json) {
-    await canvas.loadFromJSON(json);
-    // Re-attach raw content sync to each loaded text object
-    canvas.getObjects().forEach(obj => {
-        if (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox') {
-            const t = obj;
-            t.on('changed', () => {
-                t.set('labelforge_raw_content', t.text ?? '');
-            });
-        }
-    });
-    canvas.renderAll();
-}
diff --git a/frontend/src/main.js b/frontend/src/main.js
deleted file mode 100644
index 95cb3b9..0000000
--- a/frontend/src/main.js
+++ /dev/null
@@ -1,9 +0,0 @@
-import './style.css';
-import { mountQuickPrint } from './pages/quick-print';
-import { mountTemplates } from './pages/templates';
-import { mountTemplateEditor } from './pages/template-editor';
-import { initRouter, register, registerPrefix } from './router';
-register('/', mountQuickPrint);
-register('/templates', mountTemplates);
-registerPrefix('/templates/', mountTemplateEditor);
-initRouter();
diff --git a/frontend/src/pages/quick-print.js b/frontend/src/pages/quick-print.js
deleted file mode 100644
index 5d4a46b..0000000
--- a/frontend/src/pages/quick-print.js
+++ /dev/null
@@ -1,248 +0,0 @@
-import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api';
-const FORM_FACTOR_LABEL = {
-    1: 'Die-cut',
-    2: 'Continuous',
-    3: 'Round',
-    4: 'P-touch Continuous',
-};
-const FF_ORDER = [2, 1, 3, 4];
-function esc(s) {
-    return s
-        .replace(/&/g, '&amp;')
-        .replace(/"/g, '&quot;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-}
-export function mountQuickPrint(root) {
-    if (!localStorage.getItem(TOKEN_KEY)) {
-        renderTokenGate(root);
-    }
-    else {
-        renderForm(root);
-    }
-}
-function renderTokenGate(root) {
-    root.innerHTML = `
-    <div class="token-gate">
-      <h2>LabelForge</h2>
-      <p>Enter your API token to continue.</p>
-      <input id="token-input" type="password" placeholder="API token" autocomplete="current-password" />
-      <button id="token-save">Save token</button>
-    </div>
-  `;
-    const input = root.querySelector('#token-input');
-    const btn = root.querySelector('#token-save');
-    function save() {
-        const val = input.value.trim();
-        if (!val)
-            return;
-        localStorage.setItem(TOKEN_KEY, val);
-        renderForm(root);
-    }
-    btn.addEventListener('click', save);
-    input.addEventListener('keydown', (e) => { if (e.key === 'Enter')
-        save(); });
-}
-function renderForm(root) {
-    root.innerHTML = `
-    <div class="quick-print">
-      <h2>Quick Print</h2>
-      <div id="status-msg" class="status-msg" hidden></div>
-      <form id="print-form" autocomplete="off">
-        <div>
-          <label for="text">Text</label>
-          <textarea id="text" rows="4" required></textarea>
-        </div>
-
-        <div>
-          <label for="font">Font</label>
-          <select id="font"><option value="">Loading…</option></select>
-        </div>
-
-        <div>
-          <label for="font-size">Font size</label>
-          <input id="font-size" type="number" min="6" max="200" value="48" />
-        </div>
-
-        <div>
-          <label for="label-media">Label media</label>
-          <select id="label-media"><option value="">Loading…</option></select>
-        </div>
-
-        <div>
-          <label>Style</label>
-          <div class="checkboxes">
-            <label><input id="bold" type="checkbox" /> Bold</label>
-            <label><input id="italic" type="checkbox" /> Italic</label>
-          </div>
-        </div>
-
-        <div>
-          <label>Alignment</label>
-          <div class="radio-group">
-            <label><input type="radio" name="alignment" value="left" checked /> Left</label>
-            <label><input type="radio" name="alignment" value="center" /> Center</label>
-            <label><input type="radio" name="alignment" value="right" /> Right</label>
-          </div>
-        </div>
-
-        <div>
-          <label>Orientation</label>
-          <div class="radio-group">
-            <label><input type="radio" name="orientation" value="standard" checked /> Standard</label>
-            <label><input type="radio" name="orientation" value="rotated" /> Rotated</label>
-          </div>
-        </div>
-
-        <div class="actions">
-          <button type="button" id="btn-preview" disabled>Preview</button>
-          <button type="submit" id="btn-print" disabled>Print</button>
-        </div>
-      </form>
-      <div id="preview-area" class="preview-area" hidden>
-        <img id="preview-img" alt="Label preview" />
-      </div>
-    </div>
-  `;
-    const form = root.querySelector('#print-form');
-    const textarea = root.querySelector('#text');
-    const fontSelect = root.querySelector('#font');
-    const fontSizeInput = root.querySelector('#font-size');
-    const labelSelect = root.querySelector('#label-media');
-    const boldCheck = root.querySelector('#bold');
-    const italicCheck = root.querySelector('#italic');
-    const btnPreview = root.querySelector('#btn-preview');
-    const btnPrint = root.querySelector('#btn-print');
-    const statusMsg = root.querySelector('#status-msg');
-    const previewArea = root.querySelector('#preview-area');
-    const previewImg = root.querySelector('#preview-img');
-    let previewObjectUrl = null;
-    function showStatus(msg, kind) {
-        statusMsg.textContent = msg;
-        statusMsg.className = `status-msg ${kind}`;
-        statusMsg.hidden = false;
-    }
-    function hideStatus() {
-        statusMsg.hidden = true;
-    }
-    function updateButtons() {
-        const empty = textarea.value.trim() === '';
-        btnPrint.disabled = empty;
-        btnPreview.disabled = empty;
-    }
-    function buildRequest() {
-        const alignment = (form.querySelector('input[name="alignment"]:checked')?.value ?? 'left');
-        const orientation = (form.querySelector('input[name="orientation"]:checked')?.value ?? 'standard');
-        return {
-            text: textarea.value,
-            font: fontSelect.value,
-            font_size: parseInt(fontSizeInput.value, 10),
-            alignment,
-            orientation,
-            label_media: labelSelect.value,
-            bold: boldCheck.checked,
-            italic: italicCheck.checked,
-        };
-    }
-    textarea.addEventListener('input', updateButtons);
-    btnPreview.addEventListener('click', async () => {
-        btnPreview.disabled = true;
-        hideStatus();
-        try {
-            const blob = await previewQuick(buildRequest());
-            if (previewObjectUrl)
-                URL.revokeObjectURL(previewObjectUrl);
-            previewObjectUrl = URL.createObjectURL(blob);
-            previewImg.src = previewObjectUrl;
-            previewArea.hidden = false;
-        }
-        catch (err) {
-            showStatus(err.message, 'error');
-        }
-        finally {
-            updateButtons();
-        }
-    });
-    // Load fonts, labels, and settings in parallel; settings failure is non-fatal
-    Promise.all([
-        getFonts(),
-        getLabels(),
-        getSettings().catch((err) => {
-            console.warn('Failed to load settings:', err.message);
-            return null;
-        }),
-    ]).then(([fonts, labels, sett]) => {
-        // Populate fonts dropdown
-        fontSelect.innerHTML = fonts
-            .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
-            .join('');
-        // Group labels by form_factor
-        const groups = new Map();
-        for (const label of labels) {
-            const ff = label.form_factor;
-            if (!groups.has(ff))
-                groups.set(ff, []);
-            groups.get(ff).push(label);
-        }
-        for (const entries of groups.values()) {
-            entries.sort((a, b) => a.display_name.localeCompare(b.display_name));
-        }
-        const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])];
-        labelSelect.innerHTML = allKeys
-            .filter(k => groups.has(k))
-            .map(k => {
-            const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other';
-            const opts = groups
-                .get(k)
-                .map(l => `<option value="${esc(l.id)}">${esc(l.display_name)}</option>`)
-                .join('');
-            return `<optgroup label="${esc(groupLabel)}">${opts}</optgroup>`;
-        })
-            .join('');
-        // Restore form from settings; last_quick_print takes precedence over per-key defaults
-        const lqp = (sett?.last_quick_print ?? null);
-        if (lqp) {
-            fontSelect.value = lqp.font ?? String(sett?.default_font ?? 'DejaVuSans');
-            fontSizeInput.value = String(lqp.font_size ?? sett?.default_font_size ?? 48);
-            labelSelect.value = String(lqp.label_media ?? sett?.default_label_media ?? '62');
-            boldCheck.checked = lqp.bold ?? false;
-            italicCheck.checked = lqp.italic ?? false;
-            const aRadio = form.querySelector(`input[name="alignment"][value="${lqp.alignment ?? 'left'}"]`);
-            if (aRadio)
-                aRadio.checked = true;
-            const oRadio = form.querySelector(`input[name="orientation"][value="${lqp.orientation ?? 'standard'}"]`);
-            if (oRadio)
-                oRadio.checked = true;
-        }
-        else {
-            const defFont = String(sett?.default_font ?? 'DejaVuSans');
-            const defSize = String(sett?.default_font_size ?? 48);
-            const defMedia = String(sett?.default_label_media ?? '62');
-            const defOrientation = String(sett?.default_orientation ?? 'standard');
-            fontSelect.value = defFont;
-            fontSizeInput.value = defSize;
-            labelSelect.value = defMedia;
-            const oRadio = form.querySelector(`input[name="orientation"][value="${defOrientation}"]`);
-            if (oRadio)
-                oRadio.checked = true;
-        }
-    }).catch((err) => {
-        showStatus(`Failed to load form data: ${err.message}`, 'error');
-    });
-    form.addEventListener('submit', async (e) => {
-        e.preventDefault();
-        btnPrint.disabled = true;
-        hideStatus();
-        try {
-            const result = await quickPrint(buildRequest());
-            // "sent" = transmitted to printer network backend, not confirmed printed
-            showStatus(`Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`, 'success');
-        }
-        catch (err) {
-            showStatus(err.message, 'error');
-        }
-        finally {
-            updateButtons();
-        }
-    });
-}
diff --git a/frontend/src/pages/template-editor.js b/frontend/src/pages/template-editor.js
deleted file mode 100644
index 5bc3bb1..0000000
--- a/frontend/src/pages/template-editor.js
+++ /dev/null
@@ -1,247 +0,0 @@
-import { createTemplate, getFonts, getLabels, getTemplate, previewTemplate, updateTemplate } from '../api';
-import { navigate } from '../router';
-import { addTextElement, deleteSelected, getCanvasJSON, initCanvas, loadCanvasJSON, } from '../editor/canvas';
-function esc(s) {
-    return s
-        .replace(/&/g, '&amp;')
-        .replace(/"/g, '&quot;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-}
-function parsePath() {
-    const path = window.location.pathname; // /templates/my-name
-    const parts = path.split('/');
-    const name = decodeURIComponent(parts[parts.length - 1] ?? '');
-    const params = new URLSearchParams(window.location.search);
-    const isNew = params.get('new') === '1';
-    const newMedia = params.get('media') ?? '';
-    return { name, isNew, newMedia };
-}
-export function mountTemplateEditor(root) {
-    const { name, isNew, newMedia } = parsePath();
-    // Widen the app container for the editor
-    const appEl = document.getElementById('app');
-    appEl?.classList.add('editor-mode');
-    root.innerHTML = `
-    <div class="editor-shell">
-      <div class="editor-toolbar">
-        <button id="btn-back">← Back</button>
-        <span class="toolbar-sep"></span>
-        <span class="editor-title" id="editor-title">${esc(name)}</span>
-        <span class="toolbar-sep"></span>
-        <button id="btn-add-text">Add Text</button>
-        <button id="btn-delete">Delete</button>
-        <span class="toolbar-sep"></span>
-        <select id="font-select" title="Font family" style="max-width:160px">
-          <option value="">Loading fonts…</option>
-        </select>
-        <input id="font-size" type="number" min="6" max="400" value="48" title="Font size" style="width:60px" />
-        <span class="toolbar-sep"></span>
-        <button id="btn-preview">Preview</button>
-        <button id="btn-save" class="btn-primary">Save</button>
-      </div>
-      <div id="editor-status" class="editor-status" hidden></div>
-      <div class="editor-canvas-wrap" id="canvas-wrap">
-        <div class="editor-canvas-inner" id="canvas-inner">
-          <canvas id="fabric-canvas"></canvas>
-        </div>
-      </div>
-      <div id="preview-area" class="preview-area" hidden style="padding:1rem">
-        <img id="preview-img" alt="Server render preview" style="max-width:100%;border:1px solid #ddd" />
-      </div>
-    </div>
-  `;
-    const btnBack = root.querySelector('#btn-back');
-    const btnAddText = root.querySelector('#btn-add-text');
-    const btnDelete = root.querySelector('#btn-delete');
-    const btnSave = root.querySelector('#btn-save');
-    const btnPreview = root.querySelector('#btn-preview');
-    const fontSelect = root.querySelector('#font-select');
-    const fontSizeInput = root.querySelector('#font-size');
-    const statusEl = root.querySelector('#editor-status');
-    const canvasWrap = root.querySelector('#canvas-wrap');
-    const previewArea = root.querySelector('#preview-area');
-    const previewImg = root.querySelector('#preview-img');
-    let fabricCanvas = null;
-    let labelMedia = newMedia;
-    let existsOnServer = !isNew;
-    let defaultFont = 'DejaVuSans';
-    let previewObjectUrl = null;
-    function showStatus(msg, kind) {
-        if (!msg) {
-            statusEl.hidden = true;
-            return;
-        }
-        statusEl.textContent = msg;
-        statusEl.className = `editor-status ${kind}`;
-        statusEl.hidden = false;
-    }
-    function getContainerWidth() {
-        return canvasWrap.clientWidth || 800;
-    }
-    async function initEditor(label) {
-        labelMedia = label.id;
-        const [w, h] = label.dots_printable;
-        const canvasEl = root.querySelector('#fabric-canvas');
-        const { canvas } = initCanvas(canvasEl, w, h, getContainerWidth());
-        fabricCanvas = canvas;
-        // Track selection to drive font controls
-        canvas.on('selection:created', updateFontControls);
-        canvas.on('selection:updated', updateFontControls);
-        canvas.on('selection:cleared', () => { });
-    }
-    function updateFontControls() {
-        if (!fabricCanvas)
-            return;
-        const obj = fabricCanvas.getActiveObject();
-        if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
-            if (obj.fontFamily)
-                fontSelect.value = obj.fontFamily;
-            if (obj.fontSize)
-                fontSizeInput.value = String(Math.round(obj.fontSize));
-        }
-    }
-    fontSelect.addEventListener('change', () => {
-        if (!fabricCanvas)
-            return;
-        const obj = fabricCanvas.getActiveObject();
-        if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
-            obj.set('fontFamily', fontSelect.value);
-            fabricCanvas.renderAll();
-        }
-    });
-    fontSizeInput.addEventListener('change', () => {
-        if (!fabricCanvas)
-            return;
-        const sz = parseInt(fontSizeInput.value, 10);
-        if (!isNaN(sz) && sz >= 6) {
-            const obj = fabricCanvas.getActiveObject();
-            if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
-                obj.set('fontSize', sz);
-                fabricCanvas.renderAll();
-            }
-        }
-    });
-    btnBack.addEventListener('click', () => {
-        document.getElementById('app')?.classList.remove('editor-mode');
-        navigate('/templates');
-    });
-    btnAddText.addEventListener('click', () => {
-        if (!fabricCanvas)
-            return;
-        addTextElement(fabricCanvas, fontSelect.value || defaultFont);
-    });
-    btnDelete.addEventListener('click', () => {
-        if (!fabricCanvas)
-            return;
-        deleteSelected(fabricCanvas);
-    });
-    btnSave.addEventListener('click', () => void doSave());
-    btnPreview.addEventListener('click', () => void doPreview());
-    async function doSave() {
-        if (!fabricCanvas)
-            return;
-        const objs = fabricCanvas.getObjects();
-        if (objs.length === 0) {
-            showStatus('Add at least one element before saving.', 'error');
-            return;
-        }
-        btnSave.disabled = true;
-        showStatus('', '');
-        try {
-            const canvasJson = getCanvasJSON(fabricCanvas);
-            if (existsOnServer) {
-                await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia });
-            }
-            else {
-                await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson });
-                existsOnServer = true;
-            }
-            showStatus('Saved.', 'success');
-        }
-        catch (err) {
-            showStatus(err.message, 'error');
-        }
-        finally {
-            btnSave.disabled = false;
-        }
-    }
-    async function doPreview() {
-        if (!fabricCanvas)
-            return;
-        btnPreview.disabled = true;
-        showStatus('', '');
-        try {
-            // Save first so server has the latest canvas
-            const objs = fabricCanvas.getObjects();
-            if (objs.length > 0) {
-                const canvasJson = getCanvasJSON(fabricCanvas);
-                if (existsOnServer) {
-                    await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia });
-                }
-                else {
-                    await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson });
-                    existsOnServer = true;
-                }
-            }
-            // Build a fields dict: use field name as its own placeholder value for preview
-            const fields = {};
-            const blob = await previewTemplate(name, fields);
-            if (previewObjectUrl)
-                URL.revokeObjectURL(previewObjectUrl);
-            previewObjectUrl = URL.createObjectURL(blob);
-            previewImg.src = previewObjectUrl;
-            previewArea.hidden = false;
-        }
-        catch (err) {
-            showStatus(err.message, 'error');
-        }
-        finally {
-            btnPreview.disabled = false;
-        }
-    }
-    // Bootstrap: load label catalog + fonts, then either load existing template or init blank
-    Promise.all([getLabels(), getFonts()]).then(async ([labels, fonts]) => {
-        // Populate font selector
-        defaultFont = fonts[0]?.name ?? 'DejaVuSans';
-        fontSelect.innerHTML = fonts
-            .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
-            .join('');
-        // Try to select DejaVuSans as default
-        const dvs = fonts.find(f => f.name.includes('DejaVu') || f.name.includes('DejaVuSans'));
-        if (dvs) {
-            fontSelect.value = dvs.name;
-            defaultFont = dvs.name;
-        }
-        if (isNew) {
-            // New template: use newMedia from query params
-            const label = labels.find(l => l.id === newMedia);
-            if (!label) {
-                showStatus(`Unknown label media: ${newMedia}`, 'error');
-                return;
-            }
-            await initEditor(label);
-        }
-        else {
-            // Load existing template
-            try {
-                const tmpl = await getTemplate(name);
-                labelMedia = tmpl.label_media;
-                const label = labels.find(l => l.id === tmpl.label_media);
-                if (!label) {
-                    showStatus(`Unknown label media: ${tmpl.label_media}`, 'error');
-                    return;
-                }
-                await initEditor(label);
-                if (fabricCanvas && tmpl.canvas_json && Object.keys(tmpl.canvas_json).length > 0) {
-                    await loadCanvasJSON(fabricCanvas, tmpl.canvas_json);
-                }
-            }
-            catch (err) {
-                showStatus(err.message, 'error');
-            }
-        }
-    }).catch((err) => {
-        showStatus(`Failed to load: ${err.message}`, 'error');
-    });
-}
diff --git a/frontend/src/pages/templates-list.js b/frontend/src/pages/templates-list.js
deleted file mode 100644
index c2510c6..0000000
--- a/frontend/src/pages/templates-list.js
+++ /dev/null
@@ -1,196 +0,0 @@
-import { deleteTemplate, listTemplates } from '../api';
-import { navigate } from '../router';
-function esc(s) {
-    return s
-        .replace(/&/g, '&amp;')
-        .replace(/"/g, '&quot;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-}
-function fmtDate(iso) {
-    if (!iso)
-        return '—';
-    try {
-        return new Date(iso).toLocaleString();
-    }
-    catch {
-        return iso;
-    }
-}
-export function mountTemplatesList(root) {
-    root.innerHTML = `
-    <div class="templates-list">
-      <div class="templates-list-header">
-        <h2>Templates</h2>
-        <button id="btn-new-template">New template</button>
-      </div>
-      <div id="tpl-status" class="status-msg" hidden></div>
-      <div id="tpl-body"></div>
-    </div>
-  `;
-    const btnNew = root.querySelector('#btn-new-template');
-    const statusEl = root.querySelector('#tpl-status');
-    const bodyEl = root.querySelector('#tpl-body');
-    function showStatus(msg, kind) {
-        statusEl.textContent = msg;
-        statusEl.className = `status-msg ${kind}`;
-        statusEl.hidden = false;
-    }
-    function renderList(templates) {
-        if (templates.length === 0) {
-            bodyEl.innerHTML = `<p class="empty-state">No templates yet. Create one.</p>`;
-            return;
-        }
-        bodyEl.innerHTML = `
-      <table class="tpl-table">
-        <thead>
-          <tr>
-            <th>Name</th>
-            <th>Media</th>
-            <th>Updated</th>
-            <th></th>
-          </tr>
-        </thead>
-        <tbody>
-          ${templates.map(t => `
-            <tr data-name="${esc(t.name)}">
-              <td>${esc(t.display_name || t.name)}</td>
-              <td><code>${esc(t.label_media)}</code></td>
-              <td>${esc(fmtDate(t.updated_at))}</td>
-              <td class="tpl-actions">
-                <button class="btn-edit" data-name="${esc(t.name)}">Edit</button>
-                <button class="btn-delete" data-name="${esc(t.name)}">Delete</button>
-              </td>
-            </tr>
-          `).join('')}
-        </tbody>
-      </table>
-    `;
-        bodyEl.querySelectorAll('.btn-edit').forEach(btn => {
-            btn.addEventListener('click', () => navigate(`/templates/${btn.dataset.name}`));
-        });
-        bodyEl.querySelectorAll('.btn-delete').forEach(btn => {
-            btn.addEventListener('click', async () => {
-                const name = btn.dataset.name;
-                if (!confirm(`Delete template "${name}"? This cannot be undone.`))
-                    return;
-                btn.disabled = true;
-                try {
-                    await deleteTemplate(name);
-                    await load();
-                }
-                catch (err) {
-                    showStatus(err.message, 'error');
-                    btn.disabled = false;
-                }
-            });
-        });
-    }
-    async function load() {
-        bodyEl.innerHTML = `<p>Loading…</p>`;
-        statusEl.hidden = true;
-        try {
-            const templates = await listTemplates();
-            renderList(templates);
-        }
-        catch (err) {
-            showStatus(err.message, 'error');
-            bodyEl.innerHTML = '';
-        }
-    }
-    btnNew.addEventListener('click', () => {
-        showNewTemplateModal(() => load());
-    });
-    void load();
-}
-function showNewTemplateModal(onCreated) {
-    import('../api').then(({ getLabels }) => {
-        const overlay = document.createElement('div');
-        overlay.className = 'modal-overlay';
-        overlay.innerHTML = `
-      <div class="modal">
-        <h3>New template</h3>
-        <div class="modal-status" hidden></div>
-        <label>
-          Name (slug)
-          <input id="modal-name" type="text" placeholder="my-template" autocomplete="off" />
-          <span class="field-error" id="name-error" hidden></span>
-        </label>
-        <label>
-          Label media
-          <select id="modal-media"><option value="">Loading…</option></select>
-        </label>
-        <div class="modal-actions">
-          <button id="modal-cancel">Cancel</button>
-          <button id="modal-ok" class="btn-primary" disabled>Create</button>
-        </div>
-      </div>
-    `;
-        document.body.appendChild(overlay);
-        const nameInput = overlay.querySelector('#modal-name');
-        const mediaSelect = overlay.querySelector('#modal-media');
-        const cancelBtn = overlay.querySelector('#modal-cancel');
-        const okBtn = overlay.querySelector('#modal-ok');
-        const nameError = overlay.querySelector('#name-error');
-        const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
-        const FORM_FACTOR_LABEL = { 1: 'Die-cut', 2: 'Continuous', 3: 'Round', 4: 'P-touch Continuous' };
-        const FF_ORDER = [2, 1, 3, 4];
-        function esc2(s) {
-            return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-        }
-        function validate() {
-            const v = nameInput.value.trim();
-            if (!v) {
-                nameError.textContent = 'Name is required';
-                nameError.hidden = false;
-                return false;
-            }
-            if (!SLUG_RE.test(v)) {
-                nameError.textContent = 'Use lowercase letters, numbers, hyphens only';
-                nameError.hidden = false;
-                return false;
-            }
-            nameError.hidden = true;
-            return true;
-        }
-        function updateOk() {
-            okBtn.disabled = !nameInput.value.trim() || !mediaSelect.value;
-        }
-        nameInput.addEventListener('input', () => { validate(); updateOk(); });
-        mediaSelect.addEventListener('change', updateOk);
-        getLabels().then(labels => {
-            const groups = new Map();
-            for (const l of labels) {
-                if (!groups.has(l.form_factor))
-                    groups.set(l.form_factor, []);
-                groups.get(l.form_factor).push(l);
-            }
-            for (const entries of groups.values())
-                entries.sort((a, b) => a.display_name.localeCompare(b.display_name));
-            const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])];
-            mediaSelect.innerHTML = allKeys
-                .filter(k => groups.has(k))
-                .map(k => {
-                const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other';
-                const opts = groups.get(k).map(l => `<option value="${esc2(l.id)}">${esc2(l.display_name)}</option>`).join('');
-                return `<optgroup label="${esc2(groupLabel)}">${opts}</optgroup>`;
-            })
-                .join('');
-            updateOk();
-        });
-        cancelBtn.addEventListener('click', () => overlay.remove());
-        overlay.addEventListener('click', e => { if (e.target === overlay)
-            overlay.remove(); });
-        okBtn.addEventListener('click', () => {
-            if (!validate())
-                return;
-            const name = nameInput.value.trim();
-            const media = mediaSelect.value;
-            overlay.remove();
-            // Navigate to editor — template created on first Save
-            navigate(`/templates/${name}?new=1&media=${encodeURIComponent(media)}`);
-            onCreated();
-        });
-        nameInput.focus();
-    });
-}
diff --git a/frontend/src/pages/templates.js b/frontend/src/pages/templates.js
deleted file mode 100644
index 5a0678d..0000000
--- a/frontend/src/pages/templates.js
+++ /dev/null
@@ -1 +0,0 @@
-export { mountTemplatesList as mountTemplates } from './templates-list';
diff --git a/frontend/src/router.js b/frontend/src/router.js
deleted file mode 100644
index c995af0..0000000
--- a/frontend/src/router.js
+++ /dev/null
@@ -1,52 +0,0 @@
-const routes = {};
-const prefixRoutes = [];
-export function register(path, mount) {
-    routes[path] = mount;
-}
-/** Register a handler for all paths that start with `prefix`. */
-export function registerPrefix(prefix, mount) {
-    prefixRoutes.push({ prefix, mount });
-}
-function setActiveNav(path) {
-    document.querySelectorAll('[data-route]').forEach(a => {
-        a.classList.toggle('active', a.dataset.route === path || path.startsWith(a.dataset.route + '/'));
-    });
-}
-export function navigate(path) {
-    history.pushState(null, '', path);
-    render(path);
-}
-function render(path) {
-    const root = document.getElementById('app');
-    if (!root)
-        return;
-    const exact = routes[path];
-    if (exact) {
-        setActiveNav(path);
-        exact(root);
-        return;
-    }
-    for (const { prefix, mount } of prefixRoutes) {
-        if (path.startsWith(prefix)) {
-            setActiveNav(path);
-            mount(root);
-            return;
-        }
-    }
-    const fallback = routes['/'];
-    if (fallback) {
-        setActiveNav(path);
-        fallback(root);
-    }
-}
-export function initRouter() {
-    document.addEventListener('click', e => {
-        const target = e.target.closest('[data-route]');
-        if (!target)
-            return;
-        e.preventDefault();
-        navigate(target.dataset.route);
-    });
-    window.addEventListener('popstate', () => render(window.location.pathname));
-    render(window.location.pathname);
-}
diff --git a/frontend/src/types.js b/frontend/src/types.js
deleted file mode 100644
index cb0ff5c..0000000
--- a/frontend/src/types.js
+++ /dev/null
@@ -1 +0,0 @@
-export {};
diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json
index 1ca183c..dba20f8 100644
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -5,6 +5,7 @@
     "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM"],
     "strict": true,
+    "noEmit": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "skipLibCheck": true

From 23aca4c470c213385fc9363f11ce8696db55b7be Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 20:50:44 -0700
Subject: [PATCH 39/84] Add template recall UI for filling fields, previewing,
 and printing

Recall page at /templates/:name/print:
- Auto-generates a form from the template field schema (text input for
  text/number/date, select for enum), pre-fills defaults, marks required
  fields and gates Print on them
- Debounced live preview and a manual Preview button via POST /api/preview
- Single print via POST /api/print/{name}
- Batch print for templates with increment fields: count input, advances
  trailing digits client-side preserving zero-padding to mirror the
  backend advance(), one POST /api/print/{name}/batch call
- Print button added to each templates-list row
- printTemplate/batchPrint API client fns + BatchPrintResponse types
- Router distinguishes /:name/print (recall) from /:name (editor)
---
 CHANGELOG.md                             |   1 +
 docs/decisions.md                        |  15 ++
 frontend/src/api.ts                      |  16 +-
 frontend/src/main.ts                     |  10 +-
 frontend/src/pages/template-recall.ts    | 243 +++++++++++++++++++++++
 frontend/src/pages/templates-list.ts     |   5 +
 frontend/src/style.css                   |  70 +++++++
 frontend/src/types.ts                    |  12 ++
 prompts/2026-05-25-template-recall-ui.md |   6 +-
 9 files changed, 373 insertions(+), 5 deletions(-)
 create mode 100644 frontend/src/pages/template-recall.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c6f381f..d408743 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Template recall UI** — fill variable fields, preview, and print from saved templates at `/templates/{name}/print`; batch printing with auto-increment for numeric fields
 - **Templates editor foundation (text-only slice)** — canvas editor at `/templates/{name}` built on Fabric.js 6.6.1:
   - Templates list page at `/templates`: shows name, label media, last-updated; Edit and Delete (soft-delete) per row; empty state
   - New-template modal: slug-validated name (`^[a-z0-9][a-z0-9-]*$`), label media grouped by form factor (same grouping as quick-print)
diff --git a/docs/decisions.md b/docs/decisions.md
index 74f6f1b..dda5247 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,21 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-25 — Compiled `.js` is not tracked; `.ts` is the only source in `frontend/src`
+
+**Decision**: `frontend/src` tracks TypeScript only. The `.js` files `tsc` emits next to each `.ts` are build artifacts: `tsconfig.json` sets `noEmit: true` (so `tsc` in the `build` script is typecheck-only), `.gitignore` ignores `frontend/src/**/*.js`, and the 9 previously-committed `src/**/*.js` were untracked.
+
+**Why**: The repo had a compiled `.js` committed beside every `.ts`. Nothing consumed them — Vite compiles the `.ts` directly (esbuild in dev, Rollup in prod) and the Docker image builds from source — so they were stale dead weight that doubled every source diff and risked misleading anyone reading the tree. Committing build output beside source is an anti-pattern for an app with a build step.
+
+**Considered**:
+- Keep committing the `.js` in sync with source — rejected; perpetuates the smell for zero runtime benefit.
+- Untrack only, leave `tsc` emitting — rejected; artifacts would silently reappear on the next local build and risk being re-added.
+- Untrack + `noEmit` + ignore — chosen; removes the artifacts and the mechanism that created them.
+
+**Would revisit if**: the project ever ships hand-authored `.js` in `src` (it shouldn't) or moves to a build that legitimately emits into `src`.
+
+---
+
 ## 2026-05-20 (e) — Preview must apply the same 1-bit threshold as print
 
 **Decision**: The preview endpoints return the exact 1-bit (black/white) image the printer will rasterize, produced by the same threshold/dither step as the print path — not the pre-threshold greyscale render. There is a single shared definition of "the bitmap that prints," used by both preview and print.
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 854450f..a333170 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -1,4 +1,4 @@
-import type { FontInfo, LabelEntry, PrintJobResponse, QuickPrintRequest, Template, TemplateCreate } from './types'
+import type { BatchPrintResponse, FontInfo, LabelEntry, PrintJobResponse, QuickPrintRequest, Template, TemplateCreate } from './types'
 
 export const TOKEN_KEY = 'labelforge_token'
 
@@ -107,6 +107,20 @@ export async function previewTemplate(name: string, fields: Record<string, strin
   return res.blob()
 }
 
+export function printTemplate(name: string, fields: Record<string, string>): Promise<PrintJobResponse> {
+  return apiFetch<PrintJobResponse>(`/api/print/${encodeURIComponent(name)}`, {
+    method: 'POST',
+    body: JSON.stringify({ fields }),
+  })
+}
+
+export function batchPrint(name: string, labels: Record<string, string>[]): Promise<BatchPrintResponse> {
+  return apiFetch<BatchPrintResponse>(`/api/print/${encodeURIComponent(name)}/batch`, {
+    method: 'POST',
+    body: JSON.stringify({ labels }),
+  })
+}
+
 export function getSettings(): Promise<Record<string, unknown>> {
   return apiFetch<Record<string, unknown>>('/api/settings')
 }
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index c55688a..db29e66 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -2,9 +2,17 @@ import './style.css'
 import { mountQuickPrint } from './pages/quick-print'
 import { mountTemplates } from './pages/templates'
 import { mountTemplateEditor } from './pages/template-editor'
+import { mountTemplateRecall } from './pages/template-recall'
 import { initRouter, register, registerPrefix } from './router'
 
 register('/', mountQuickPrint)
 register('/templates', mountTemplates)
-registerPrefix('/templates/', mountTemplateEditor)
+registerPrefix('/templates/', (root) => {
+  const path = window.location.pathname
+  if (path.endsWith('/print')) {
+    mountTemplateRecall(root)
+  } else {
+    mountTemplateEditor(root)
+  }
+})
 initRouter()
diff --git a/frontend/src/pages/template-recall.ts b/frontend/src/pages/template-recall.ts
new file mode 100644
index 0000000..f8330ba
--- /dev/null
+++ b/frontend/src/pages/template-recall.ts
@@ -0,0 +1,243 @@
+import { batchPrint, getTemplate, previewTemplate, printTemplate } from '../api'
+import type { FieldSpec, Template } from '../types'
+import { navigate } from '../router'
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/** Mirror of the backend `advance()` in templates/fields.py — increment trailing digits, preserve zero-padding. */
+function advance(value: string): string {
+  const m = /^(.*?)(\d+)$/.exec(value)
+  if (!m) return value
+  const prefix = m[1]
+  const digits = m[2]
+  const next = parseInt(digits, 10) + 1
+  const nextStr = digits.startsWith('0') ? String(next).padStart(digits.length, '0') : String(next)
+  return prefix + nextStr
+}
+
+/** Extract the template name from `/templates/:name/print`. */
+function nameFromPath(): string {
+  const parts = window.location.pathname.split('/').filter(Boolean)
+  // ['templates', ':name', 'print']
+  return decodeURIComponent(parts[1] ?? '')
+}
+
+export function mountTemplateRecall(root: HTMLElement): void {
+  const name = nameFromPath()
+  root.innerHTML = `<div class="template-recall"><p>Loading…</p></div>`
+
+  getTemplate(name)
+    .then(tpl => renderRecall(root, tpl))
+    .catch((err: Error) => {
+      root.innerHTML = `
+        <div class="template-recall">
+          <a href="#" class="back-link" id="back-link">← Templates</a>
+          <div class="status-msg error">${esc(err.message)}</div>
+        </div>
+      `
+      root.querySelector('#back-link')!.addEventListener('click', e => {
+        e.preventDefault()
+        navigate('/templates')
+      })
+    })
+}
+
+function renderRecall(root: HTMLElement, tpl: Template): void {
+  const fields = tpl.field_schema ?? []
+  const hasFields = fields.length > 0
+  const incrementFields = fields.filter(f => f.increment)
+  const canBatch = incrementFields.length > 0
+
+  root.innerHTML = `
+    <div class="template-recall">
+      <a href="#" class="back-link" id="back-link">← Templates</a>
+      <h2>${esc(tpl.display_name || tpl.name)}</h2>
+      <p class="recall-meta">Media: <code>${esc(tpl.label_media)}</code></p>
+      <div id="status-msg" class="status-msg" hidden></div>
+
+      <form id="recall-form" autocomplete="off">
+        ${hasFields ? fields.map(fieldInput).join('') : '<p class="recall-meta">This template has no variable fields.</p>'}
+
+        ${canBatch ? `
+          <fieldset class="batch-box">
+            <legend>Batch</legend>
+            <label class="batch-toggle">
+              <input type="checkbox" id="batch-enable" /> Print multiple labels
+            </label>
+            <div id="batch-opts" hidden>
+              <label for="batch-count">Count</label>
+              <input type="number" id="batch-count" min="1" max="1000" value="1" />
+              <p class="recall-meta">Auto-increments per label: ${incrementFields.map(f => `<code>${esc(f.name)}</code>`).join(', ')}</p>
+            </div>
+          </fieldset>
+        ` : ''}
+
+        <div class="actions">
+          <button type="button" id="btn-preview">Preview</button>
+          <button type="submit" id="btn-print">Print</button>
+        </div>
+      </form>
+
+      <div id="preview-area" class="preview-area" hidden>
+        <img id="preview-img" alt="Label preview" />
+      </div>
+    </div>
+  `
+
+  const form = root.querySelector<HTMLFormElement>('#recall-form')!
+  const btnPreview = root.querySelector<HTMLButtonElement>('#btn-preview')!
+  const btnPrint = root.querySelector<HTMLButtonElement>('#btn-print')!
+  const statusMsg = root.querySelector<HTMLDivElement>('#status-msg')!
+  const previewArea = root.querySelector<HTMLDivElement>('#preview-area')!
+  const previewImg = root.querySelector<HTMLImageElement>('#preview-img')!
+  const batchEnable = root.querySelector<HTMLInputElement>('#batch-enable')
+  const batchOpts = root.querySelector<HTMLDivElement>('#batch-opts')
+  const batchCount = root.querySelector<HTMLInputElement>('#batch-count')
+
+  let previewObjectUrl: string | null = null
+  let debounceTimer: number | undefined
+
+  root.querySelector('#back-link')!.addEventListener('click', e => {
+    e.preventDefault()
+    navigate('/templates')
+  })
+
+  function showStatus(msg: string, kind: 'success' | 'error'): void {
+    statusMsg.textContent = msg
+    statusMsg.className = `status-msg ${kind}`
+    statusMsg.hidden = false
+  }
+
+  function hideStatus(): void {
+    statusMsg.hidden = true
+  }
+
+  function collectFields(): Record<string, string> {
+    const values: Record<string, string> = {}
+    for (const f of fields) {
+      const el = form.querySelector<HTMLInputElement | HTMLSelectElement>(`[name="${CSS.escape(f.name)}"]`)
+      values[f.name] = el?.value ?? ''
+    }
+    return values
+  }
+
+  function missingRequired(): boolean {
+    return fields.some(f => f.required && collectFields()[f.name].trim() === '')
+  }
+
+  function updateButtons(): void {
+    btnPrint.disabled = missingRequired()
+  }
+
+  function buildBatchLabels(): Record<string, string>[] {
+    const count = Math.max(1, Math.min(1000, parseInt(batchCount?.value ?? '1', 10) || 1))
+    const base = collectFields()
+    const labels: Record<string, string>[] = []
+    let current = { ...base }
+    for (let i = 0; i < count; i++) {
+      labels.push({ ...current })
+      const next = { ...current }
+      for (const f of incrementFields) {
+        next[f.name] = advance(next[f.name])
+      }
+      current = next
+    }
+    return labels
+  }
+
+  function runPreview(): void {
+    if (missingRequired()) return
+    btnPreview.disabled = true
+    hideStatus()
+    previewTemplate(tpl.name, collectFields())
+      .then(blob => {
+        if (previewObjectUrl) URL.revokeObjectURL(previewObjectUrl)
+        previewObjectUrl = URL.createObjectURL(blob)
+        previewImg.src = previewObjectUrl
+        previewArea.hidden = false
+      })
+      .catch((err: Error) => showStatus(err.message, 'error'))
+      .finally(() => { btnPreview.disabled = false })
+  }
+
+  // Live preview, debounced ~500ms after the last keystroke.
+  form.addEventListener('input', () => {
+    updateButtons()
+    window.clearTimeout(debounceTimer)
+    debounceTimer = window.setTimeout(() => {
+      if (!previewArea.hidden) runPreview()
+    }, 500)
+  })
+
+  if (batchEnable && batchOpts) {
+    batchEnable.addEventListener('change', () => {
+      batchOpts.hidden = !batchEnable.checked
+    })
+  }
+
+  btnPreview.addEventListener('click', runPreview)
+
+  form.addEventListener('submit', async (e) => {
+    e.preventDefault()
+    if (missingRequired()) {
+      showStatus('Fill all required fields before printing.', 'error')
+      return
+    }
+    btnPrint.disabled = true
+    hideStatus()
+    try {
+      if (batchEnable?.checked) {
+        const labels = buildBatchLabels()
+        const result = await batchPrint(tpl.name, labels)
+        const kind = result.failed > 0 ? 'error' : 'success'
+        showStatus(
+          `Batch ${result.batch_id}: ${result.succeeded} sent, ${result.failed} failed (${labels.length} requested). "Sent" means transmitted to the printer; delivery is not confirmed.`,
+          kind,
+        )
+      } else {
+        const result = await printTemplate(tpl.name, collectFields())
+        showStatus(
+          `Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`,
+          'success',
+        )
+      }
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+    } finally {
+      updateButtons()
+    }
+  })
+
+  updateButtons()
+}
+
+function fieldInput(f: FieldSpec): string {
+  const id = `field-${f.name}`
+  const req = f.required ? 'required' : ''
+  const star = f.required ? ' <span class="req-star">*</span>' : ''
+  const def = f.default ?? ''
+  let control: string
+  if (f.type === 'enum') {
+    const opts = (f.enum_values ?? [])
+      .map(v => `<option value="${esc(v)}"${v === def ? ' selected' : ''}>${esc(v)}</option>`)
+      .join('')
+    const placeholder = f.required ? '' : '<option value=""></option>'
+    control = `<select id="${esc(id)}" name="${esc(f.name)}" ${req}>${placeholder}${opts}</select>`
+  } else {
+    // text / number / date all use a plain text input (per spec) — avoids native
+    // date-picker silently rejecting non-ISO default values.
+    control = `<input id="${esc(id)}" name="${esc(f.name)}" type="text" value="${esc(def)}" ${req} />`
+  }
+  return `
+    <div class="recall-field">
+      <label for="${esc(id)}">${esc(f.name)}${star} <span class="field-type">${esc(f.type)}</span></label>
+      ${control}
+    </div>
+  `
+}
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index 0fcf543..e4ae1bf 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -63,6 +63,7 @@ export function mountTemplatesList(root: HTMLElement): void {
               <td><code>${esc(t.label_media)}</code></td>
               <td>${esc(fmtDate(t.updated_at))}</td>
               <td class="tpl-actions">
+                <button class="btn-print" data-name="${esc(t.name)}">Print</button>
                 <button class="btn-edit" data-name="${esc(t.name)}">Edit</button>
                 <button class="btn-delete" data-name="${esc(t.name)}">Delete</button>
               </td>
@@ -72,6 +73,10 @@ export function mountTemplatesList(root: HTMLElement): void {
       </table>
     `
 
+    bodyEl.querySelectorAll<HTMLButtonElement>('.btn-print').forEach(btn => {
+      btn.addEventListener('click', () => navigate(`/templates/${btn.dataset.name!}/print`))
+    })
+
     bodyEl.querySelectorAll<HTMLButtonElement>('.btn-edit').forEach(btn => {
       btn.addEventListener('click', () => navigate(`/templates/${btn.dataset.name!}`))
     })
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 84c4799..102bf02 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -46,6 +46,8 @@ label {
 
 textarea,
 input[type="number"],
+input[type="text"],
+input[type="date"],
 select {
   width: 100%;
   padding: 0.4rem 0.5rem;
@@ -321,6 +323,74 @@ button:disabled {
 .editor-status.success { color: #1a5c2a; background: #e6f4ea; }
 .editor-status.error   { color: #7a1a14; background: #fdecea; }
 
+/* template recall */
+.template-recall {
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 1.5rem;
+}
+
+.template-recall .back-link {
+  display: inline-block;
+  font-size: 0.85rem;
+  color: #1a6fdb;
+  text-decoration: none;
+  margin-bottom: 0.75rem;
+}
+
+.recall-meta {
+  font-size: 0.85rem;
+  color: #666;
+  margin: 0 0 0.75rem;
+}
+
+.recall-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.recall-field .field-type {
+  font-weight: normal;
+  font-size: 0.75rem;
+  color: #999;
+}
+
+.req-star {
+  color: #c0392b;
+}
+
+.batch-box {
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  padding: 0.75rem 1rem;
+  margin: 0.5rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.batch-box legend {
+  font-weight: 600;
+  font-size: 0.85rem;
+  padding: 0 0.4rem;
+}
+
+.batch-toggle {
+  font-weight: normal;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  cursor: pointer;
+}
+
+.tpl-actions .btn-print {
+  background: #1a6fdb;
+  color: #fff;
+  border-color: #1a6fdb;
+}
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 39611fd..989e89a 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -38,6 +38,18 @@ export interface PrintJobResponse {
   preview_url: string | null;
 }
 
+export interface BatchJobResult {
+  job_id: number;
+  status: string;
+}
+
+export interface BatchPrintResponse {
+  batch_id: string;
+  jobs: BatchJobResult[];
+  succeeded: number;
+  failed: number;
+}
+
 export interface FieldSpec {
   name: string;
   type: 'text' | 'number' | 'date' | 'enum';
diff --git a/prompts/2026-05-25-template-recall-ui.md b/prompts/2026-05-25-template-recall-ui.md
index b5fd7d6..7f60762 100644
--- a/prompts/2026-05-25-template-recall-ui.md
+++ b/prompts/2026-05-25-template-recall-ui.md
@@ -1,9 +1,9 @@
 ---
 name: 2026-05-25-template-recall-ui
-status: pending
+status: completed
 created: 2026-05-25
-completed:
-result:
+completed: 2026-05-25
+result: Recall page at /templates/:name/print — auto-generated field form, debounced live preview, single + batch print with client-side increment matching backend advance(); Print button added to templates list; printTemplate/batchPrint API added. Build + typecheck pass. (Side cleanup: untracked compiled src .js artifacts, see ADR 2026-05-25.)
 ---
 
 # Template Recall UI

From 6dfa805332abe4d1d09b3db8a315629c92fb5b37 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 25 May 2026 21:05:23 -0700
Subject: [PATCH 40/84] Track .claude/settings.json and CLAUDE.md; add dev tool
 auto-approve permissions

---
 .claude/CLAUDE.md     | 60 +++++++++++++++++++++++++++++++++++++++++++
 .claude/settings.json | 52 +++++++++++++++++++++++++++++++++++++
 .gitignore            |  4 ++-
 3 files changed, 115 insertions(+), 1 deletion(-)
 create mode 100644 .claude/CLAUDE.md
 create mode 100644 .claude/settings.json

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 0000000..09b4011
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,60 @@
+## vexp — Context-Aware AI Coding <!-- vexp v2.0.17 -->
+
+### MANDATORY: use vexp pipeline — do NOT grep or glob the codebase
+For every task — bug fixes, features, refactors, debugging:
+**call `run_pipeline` FIRST**. It executes context search + impact analysis +
+memory recall in a single call, returning compressed results.
+
+Do NOT use grep, glob, Bash, or cat to search/explore the codebase.
+vexp returns pre-indexed, graph-ranked context that is more relevant and
+uses fewer tokens than manual searching. Prefer `get_skeleton` over Read to
+inspect files (detail: minimal/standard/detailed, 70-90% token savings).
+Only use Read when you need exact raw content to edit a specific line.
+
+### Primary Tool
+- `run_pipeline` — **USE THIS FOR EVERYTHING**. Single call that runs
+  capsule + impact + memory server-side. Returns compressed results.
+  Auto-detects intent (debug/modify/refactor/explore) from your task.
+  Includes full file content for pivots.
+  Examples:
+  - `run_pipeline({ "task": "fix JWT validation bug" })` — auto-detect
+  - `run_pipeline({ "task": "refactor db layer", "preset": "refactor" })` — explicit
+  - `run_pipeline({ "task": "add auth", "observation": "using JWT" })` — save insight in same call
+
+### Other MCP tools (use only when run_pipeline is insufficient)
+- `get_skeleton` — **preferred over Read** for inspecting files (minimal/standard/detailed detail levels, 70-90% token savings)
+- `index_status` — indexing status and health check
+- `expand_vexp_ref` — expand V-REF hash placeholders in v2 compact output
+
+### Workflow
+1. `run_pipeline("your task")` — ALWAYS FIRST. Returns pivots + impact + memories in 1 call
+2. Need more detail on a file? Use `get_skeleton({ files: [...], detail: "detailed" })` — avoid Read unless editing
+3. Make targeted changes based on the context returned
+4. `run_pipeline` again ONLY if you need more context during implementation
+5. Do NOT chain multiple vexp calls — one `run_pipeline` replaces capsule + impact + memory + observation
+
+### Subagent / Explore / Plan mode
+- Subagents CAN and MUST call `run_pipeline` — always include the task description
+- The PreToolUse hook blocks Grep/Glob when vexp daemon is running
+- Do NOT spawn Agent(Explore) to freely search — call `run_pipeline` first,
+  then pass the returned context into the agent prompt if needed
+- Always: `run_pipeline` → get context → spawn agent with context
+
+### Smart Features (automatic — no action needed)
+- **Intent Detection**: auto-detects from your task keywords. "fix bug" → Debug, "refactor" → blast-radius, "add" → Modify
+- **Hybrid Search**: keyword + semantic + graph centrality ranking
+- **Session Memory**: auto-captures observations; memories auto-surfaced in results
+- **LSP Bridge**: VS Code captures type-resolved call edges
+- **Change Coupling**: co-changed files included as related context
+
+### Advanced Parameters
+- `preset: "debug"` — forces debug mode (capsule+tests+impact+memory)
+- `preset: "refactor"` — deep impact analysis (depth 5)
+- `max_tokens: 12000` — increase total budget for complex tasks
+- `include_tests: true` — include test files in results
+- `include_file_content: false` — omit full file content (lighter response)
+
+### Multi-Repo Workspaces
+`run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope.
+Use `index_status` to discover available repo aliases.
+<!-- /vexp -->
\ No newline at end of file
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..7c19ba3
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,52 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uname -a && hostname && cat /etc/os-release 2>/dev/null | head -5 && echo \"---\" && cat /proc/version 2>/dev/null)",
+      "Read(//usr/lib/**)",
+      "Read(//proc/**)",
+      "mcp__vexp__index_status",
+      "mcp__vexp__run_pipeline",
+      "mcp__vexp__get_skeleton",
+      "mcp__vexp__expand_vexp_ref",
+      "Bash(git rm *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git status *)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git ls-files *)",
+      "Bash(git show *)",
+      "Bash(gh issue *)",
+      "Bash(gh repo *)",
+      "Bash(command -v tea)",
+      "Bash(tea --version)",
+      "Bash(tea issues *)",
+      "Bash(npm install *)",
+      "Bash(npm run *)",
+      "Bash(npx tsc *)",
+      "Bash(node_modules/.bin/tsc *)",
+      "Bash(find *)",
+      "Bash(grep *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(ls *)",
+      "Bash(mkdir *)",
+      "Bash(docker compose *)",
+      "Bash(docker *)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep|Glob|Regex",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh",
+            "timeout": 3000
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.gitignore b/.gitignore
index 30ecda2..bed9d57 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,8 +57,10 @@ vexp.toml
 *.log
 logs/
 
-# claude 
+# claude
 .claude/
+!.claude/settings.json
+!.claude/CLAUDE.md
 
 # Test artifacts
 .coverage

From 9b5da132b649c60a893578f83bafea8a5d7559e0 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 26 May 2026 21:37:07 -0700
Subject: [PATCH 41/84] Show Brother DK part numbers in label selectors

Label-media dropdowns (quick-print and the new-template modal) render
options as "DK-22205: 62mm Continuous (Black)", falling back to the
display name when an entry has no part number.

- Backfill brother_part for 9 default catalog entries, verified against
  Brother's QL-820NWB consumables list (14/15 now mapped; 52x29 has no
  consumer DK roll, left empty intentionally)
- Add shared frontend/src/labels.ts helper for grouped option markup,
  replacing the duplicated grouping logic in both selectors
- Record the format choice and the empty 52x29 in an ADR
---
 CHANGELOG.md                         |  1 +
 docs/decisions.md                    | 15 +++++++++
 frontend/src/labels.ts               | 48 ++++++++++++++++++++++++++++
 frontend/src/pages/quick-print.ts    | 35 ++------------------
 frontend/src/pages/templates-list.ts | 23 ++-----------
 labels.yml                           | 12 ++++++-
 6 files changed, 80 insertions(+), 54 deletions(-)
 create mode 100644 frontend/src/labels.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d408743..36791d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Brother DK part numbers in label selectors** — the label-media dropdown (quick-print and the new-template modal) now shows the part number with the name, e.g. `DK-22205: 62mm Continuous (Black)`; entries without a part number show the name alone. Backfilled `brother_part` for 9 more default catalog entries (14 of 15 now carry a part number; `52x29` has no consumer DK roll). Grouping/formatting moved into a shared `frontend/src/labels.ts` helper.
 - **Template recall UI** — fill variable fields, preview, and print from saved templates at `/templates/{name}/print`; batch printing with auto-increment for numeric fields
 - **Templates editor foundation (text-only slice)** — canvas editor at `/templates/{name}` built on Fabric.js 6.6.1:
   - Templates list page at `/templates`: shows name, label media, last-updated; Edit and Delete (soft-delete) per row; empty state
diff --git a/docs/decisions.md b/docs/decisions.md
index dda5247..4f648d4 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,21 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-26 — Label selectors show `brother_part: display_name`; `52x29` intentionally has no part number
+
+**Decision**: Label-media `<select>` options render as `{brother_part}: {display_name}` (e.g. `DK-22205: 62mm Continuous (Black)`) when the catalog entry has a `brother_part`, and as the display name alone when it doesn't. The grouping/formatting lives in one shared helper (`frontend/src/labels.ts::buildLabelOptionsHtml`) used by every label selector. The default `labels.yml` was backfilled so 14 of 15 entries carry a `brother_part`; `52x29` is deliberately left without one.
+
+**Why**: The part number is how the owner actually identifies a roll to load, so it belongs in front of the human name in every place a label is chosen. Brother's QL-820NWB consumables list confirmed the part numbers; `52x29` is a `brother_ql`-printable size with **no consumer DK roll**, so there is nothing to map — the empty `brother_part` is correct, not an oversight. The format degrades cleanly (no dangling `: `). Centralizing in one helper keeps quick-print and the new-template modal from drifting and makes a future third selector consistent for free.
+
+**Considered**:
+- Suffix form `display_name (DK-…)` — rejected; the part number is the lookup key, so it reads better leading.
+- Backfill a guessed part for `52x29` — rejected; no such product exists, a fake number would mislead.
+- Edit the two duplicated option blocks in place — rejected in favor of the shared helper (the grouping logic was already duplicated verbatim).
+
+**Would revisit if**: Brother ships a DK roll at 52×29 mm (add its `brother_part`), or a selector needs richer option markup than a flat string (the helper returns an HTML string today).
+
+---
+
 ## 2026-05-25 — Compiled `.js` is not tracked; `.ts` is the only source in `frontend/src`
 
 **Decision**: `frontend/src` tracks TypeScript only. The `.js` files `tsc` emits next to each `.ts` are build artifacts: `tsconfig.json` sets `noEmit: true` (so `tsc` in the `build` script is typecheck-only), `.gitignore` ignores `frontend/src/**/*.js`, and the 9 previously-committed `src/**/*.js` were untracked.
diff --git a/frontend/src/labels.ts b/frontend/src/labels.ts
new file mode 100644
index 0000000..f073878
--- /dev/null
+++ b/frontend/src/labels.ts
@@ -0,0 +1,48 @@
+import type { LabelEntry } from './types'
+
+const FORM_FACTOR_LABEL: Record<number, string> = {
+  1: 'Die-cut',
+  2: 'Continuous',
+  3: 'Round',
+  4: 'P-touch Continuous',
+}
+
+const FF_ORDER = [2, 1, 3, 4]
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+// "DK-22205: 62mm Continuous (Black)" when the catalog entry carries a Brother
+// part number, otherwise just the display name (e.g. 52x29 has no consumer roll).
+export function labelOptionText(l: LabelEntry): string {
+  return l.brother_part ? `${l.brother_part}: ${l.display_name}` : l.display_name
+}
+
+// Grouped <optgroup> markup for a label-media <select>: ordered by form factor
+// (continuous, die-cut, round, …), sorted by display name within each group.
+export function buildLabelOptionsHtml(labels: LabelEntry[]): string {
+  const groups = new Map<number, LabelEntry[]>()
+  for (const l of labels) {
+    if (!groups.has(l.form_factor)) groups.set(l.form_factor, [])
+    groups.get(l.form_factor)!.push(l)
+  }
+  for (const entries of groups.values()) {
+    entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
+  }
+  return [...new Set([...FF_ORDER, ...groups.keys()])]
+    .filter(k => groups.has(k))
+    .map(k => {
+      const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
+      const opts = groups
+        .get(k)!
+        .map(l => `<option value="${esc(l.id)}">${esc(labelOptionText(l))}</option>`)
+        .join('')
+      return `<optgroup label="${esc(groupLabel)}">${opts}</optgroup>`
+    })
+    .join('')
+}
diff --git a/frontend/src/pages/quick-print.ts b/frontend/src/pages/quick-print.ts
index 836e6a0..5b6713e 100644
--- a/frontend/src/pages/quick-print.ts
+++ b/frontend/src/pages/quick-print.ts
@@ -1,14 +1,6 @@
 import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api'
-import type { LabelEntry, QuickPrintRequest } from '../types'
-
-const FORM_FACTOR_LABEL: Record<number, string> = {
-  1: 'Die-cut',
-  2: 'Continuous',
-  3: 'Round',
-  4: 'P-touch Continuous',
-}
-
-const FF_ORDER = [2, 1, 3, 4]
+import type { QuickPrintRequest } from '../types'
+import { buildLabelOptionsHtml } from '../labels'
 
 function esc(s: string): string {
   return s
@@ -192,28 +184,7 @@ function renderForm(root: HTMLElement): void {
       .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
       .join('')
 
-    // Group labels by form_factor
-    const groups = new Map<number, LabelEntry[]>()
-    for (const label of labels) {
-      const ff = label.form_factor
-      if (!groups.has(ff)) groups.set(ff, [])
-      groups.get(ff)!.push(label)
-    }
-    for (const entries of groups.values()) {
-      entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
-    }
-    const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
-    labelSelect.innerHTML = allKeys
-      .filter(k => groups.has(k))
-      .map(k => {
-        const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
-        const opts = groups
-          .get(k)!
-          .map(l => `<option value="${esc(l.id)}">${esc(l.display_name)}</option>`)
-          .join('')
-        return `<optgroup label="${esc(groupLabel)}">${opts}</optgroup>`
-      })
-      .join('')
+    labelSelect.innerHTML = buildLabelOptionsHtml(labels)
 
     // Restore form from settings; last_quick_print takes precedence over per-key defaults
     const lqp = (sett?.last_quick_print ?? null) as QuickPrintRequest | null
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index e4ae1bf..9b9bd24 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -1,6 +1,7 @@
 import { deleteTemplate, listTemplates } from '../api'
 import type { Template } from '../types'
 import { navigate } from '../router'
+import { buildLabelOptionsHtml } from '../labels'
 
 function esc(s: string): string {
   return s
@@ -148,12 +149,6 @@ function showNewTemplateModal(onCreated: () => void): void {
     const nameError = overlay.querySelector<HTMLSpanElement>('#name-error')!
 
     const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
-    const FORM_FACTOR_LABEL: Record<number, string> = { 1: 'Die-cut', 2: 'Continuous', 3: 'Round', 4: 'P-touch Continuous' }
-    const FF_ORDER = [2, 1, 3, 4]
-
-    function esc2(s: string): string {
-      return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-    }
 
     function validate(): boolean {
       const v = nameInput.value.trim()
@@ -171,21 +166,7 @@ function showNewTemplateModal(onCreated: () => void): void {
     mediaSelect.addEventListener('change', updateOk)
 
     getLabels().then(labels => {
-      const groups = new Map<number, typeof labels>()
-      for (const l of labels) {
-        if (!groups.has(l.form_factor)) groups.set(l.form_factor, [])
-        groups.get(l.form_factor)!.push(l)
-      }
-      for (const entries of groups.values()) entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
-      const allKeys = [...new Set([...FF_ORDER, ...groups.keys()])]
-      mediaSelect.innerHTML = allKeys
-        .filter(k => groups.has(k))
-        .map(k => {
-          const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
-          const opts = groups.get(k)!.map(l => `<option value="${esc2(l.id)}">${esc2(l.display_name)}</option>`).join('')
-          return `<optgroup label="${esc2(groupLabel)}">${opts}</optgroup>`
-        })
-        .join('')
+      mediaSelect.innerHTML = buildLabelOptionsHtml(labels)
       updateOk()
     })
 
diff --git a/labels.yml b/labels.yml
index 6f8ae30..e5c9789 100644
--- a/labels.yml
+++ b/labels.yml
@@ -10,31 +10,36 @@ labels:
 
   - id: "12"
     display_name: "12mm Continuous"
+    brother_part: "DK-22214"
     description: "Narrow continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "29"
     display_name: "29mm Continuous"
+    brother_part: "DK-22210"
     description: "Medium-width continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "38"
     display_name: "38mm Continuous"
+    brother_part: "DK-22225"
     description: "Wide continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "50"
     display_name: "50mm Continuous"
+    brother_part: "DK-22223"
     description: "50mm continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "54"
     display_name: "54mm Continuous"
-    description: "54mm continuous tape, black on white."
+    brother_part: "DK-N55224"
+    description: "54mm continuous tape, black on white. Non-adhesive."
     category: continuous
     color_capable: false
 
@@ -66,12 +71,14 @@ labels:
 
   - id: "17x54"
     display_name: "17mm × 54mm Die-cut"
+    brother_part: "DK-11204"
     description: "Small die-cut label."
     category: die-cut
     color_capable: false
 
   - id: "17x87"
     display_name: "17mm × 87mm Die-cut"
+    brother_part: "DK-11203"
     description: "Small elongated die-cut label."
     category: die-cut
     color_capable: false
@@ -89,18 +96,21 @@ labels:
 
   - id: "38x90"
     display_name: "38mm × 90mm Die-cut"
+    brother_part: "DK-11208"
     description: "Medium die-cut label."
     category: die-cut
     color_capable: false
 
   - id: "52x29"
     display_name: "52mm × 29mm Die-cut"
+    # No consumer Brother DK roll exists at this size; library-printable only.
     description: "Wide short die-cut label."
     category: die-cut
     color_capable: false
 
   - id: "62x29"
     display_name: "62mm × 29mm Die-cut"
+    brother_part: "DK-11209"
     description: "Wide short die-cut label."
     category: die-cut
     color_capable: false

From 6034be40f093cf53c60a5cafc99ccb7a1c5edb0f Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 26 May 2026 22:35:44 -0700
Subject: [PATCH 42/84] Make label catalog printer-aware; disable incompatible
 media

Compute a library-derived `supported` flag per label at catalog load
against the configured PRINTER_MODEL, using brother_ql's primitive
restricted_to_models + color fields vs the model's two_color capability
(works_with_model() is unusable: NameError on restricted labels, ignores
two-color). Selectors now render unsupported media as disabled, greyed
options with a tooltip and guard programmatic default selection.

Remove the deprecated printer_requirements field from the model, the
default labels.yml, and the loader. Document the library-derived model
in the label-catalog feature doc and add an ADR.
---
 CHANGELOG.md                                  |  1 +
 backend/labelforge/catalog/loader.py          | 49 ++++++++++-
 backend/labelforge/models/__init__.py         |  9 ++-
 docs/decisions.md                             | 29 +++++++
 docs/features/label-catalog.md                | 36 +++++++--
 frontend/src/labels.ts                        | 28 ++++++-
 frontend/src/pages/quick-print.ts             | 10 ++-
 frontend/src/pages/templates-list.ts          |  8 +-
 frontend/src/types.ts                         |  9 ++-
 labels.yml                                    |  4 -
 .../2026-05-26-printer-label-compatibility.md | 81 +++++++++++++++++++
 11 files changed, 248 insertions(+), 16 deletions(-)
 create mode 100644 prompts/2026-05-26-printer-label-compatibility.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 36791d7..ad5c2bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Printer-aware label catalog** — each label now carries a `supported` flag computed at catalog load against the configured printer (`PRINTER_MODEL`). Media the printer physically can't print — wide-format rolls on a non-QL-1xxx printer, two-color rolls on a mono printer — appear in the selectors greyed out, disabled, and marked `— unavailable` with a tooltip explaining why, instead of being silently offered. On the default QL-820NWB the six wide-format rolls (`102`, `103`, `104`, `102x51`, `102x152`, `103x164`) are now disabled; `62red` stays selectable. Compatibility is derived from the `brother_ql` library, not hand-maintained — the `printer_requirements` field in `labels.yml` is deprecated and ignored.
 - **Brother DK part numbers in label selectors** — the label-media dropdown (quick-print and the new-template modal) now shows the part number with the name, e.g. `DK-22205: 62mm Continuous (Black)`; entries without a part number show the name alone. Backfilled `brother_part` for 9 more default catalog entries (14 of 15 now carry a part number; `52x29` has no consumer DK roll). Grouping/formatting moved into a shared `frontend/src/labels.ts` helper.
 - **Template recall UI** — fill variable fields, preview, and print from saved templates at `/templates/{name}/print`; batch printing with auto-increment for numeric fields
 - **Templates editor foundation (text-only slice)** — canvas editor at `/templates/{name}` built on Fabric.js 6.6.1:
diff --git a/backend/labelforge/catalog/loader.py b/backend/labelforge/catalog/loader.py
index d61facd..0f53ebd 100644
--- a/backend/labelforge/catalog/loader.py
+++ b/backend/labelforge/catalog/loader.py
@@ -3,7 +3,9 @@
 
 import yaml
 from brother_ql.labels import ALL_LABELS, FormFactor
+from brother_ql.models import ALL_MODELS
 
+from labelforge.config import settings
 from labelforge.models import LabelEntry
 
 logger = logging.getLogger(__name__)
@@ -15,11 +17,46 @@
 _FORM_FACTOR_INT: dict[FormFactor, int] = {ff: ff.value for ff in FormFactor}
 
 
+def _compute_compatibility(
+    lib_label, printer_model: str, two_color: bool | None
+) -> tuple[bool, str | None]:
+    """Whether the configured printer can print this media, and why not.
+
+    Library-derived (not from labels.yml). brother_ql's Label.works_with_model()
+    is unusable in the pinned fork: it raises NameError on any restricted label
+    and ignores two-color capability — see docs/decisions.md. Compute from the
+    primitive Label fields instead.
+
+    `two_color is None` means the configured model wasn't found in the library;
+    treat all media as supported rather than wrongly disabling everything.
+    """
+    if two_color is None:
+        return True, None
+    restricted = list(getattr(lib_label, "restricted_to_models", []) or [])
+    if restricted and printer_model not in restricted:
+        return False, "Requires a wide-format printer (QL-1100 series)"
+    if getattr(lib_label, "color", 0) and not two_color:
+        return False, "Requires a two-color printer (QL-800 series)"
+    return True, None
+
+
 def load_catalog(yml_path: Path) -> None:
     global _catalog
 
     lib_labels = {label.identifier: label for label in ALL_LABELS}
 
+    # Compatibility is computed against the configured printer at load time
+    # (printer_model is fixed in config). A future POST /api/admin/reload-catalog
+    # should call this again to recompute.
+    printer_model = settings.printer_model
+    model = next((m for m in ALL_MODELS if m.identifier == printer_model), None)
+    if model is None:
+        logger.warning(
+            "Configured printer_model '%s' not in brother_ql — treating all media as supported",
+            printer_model,
+        )
+    two_color = model.two_color if model is not None else None
+
     yml_entries: dict[str, dict] = {}
     if yml_path.exists():
         with yml_path.open() as fh:
@@ -39,6 +76,9 @@ def load_catalog(yml_path: Path) -> None:
         form_factor_int = _FORM_FACTOR_INT.get(lib_label.form_factor, 0)
         dots = (lib_label.dots_printable[0], lib_label.dots_printable[1])
         tape = (lib_label.tape_size[0], lib_label.tape_size[1])
+        restricted = list(getattr(lib_label, "restricted_to_models", []) or [])
+        color = int(getattr(lib_label, "color", 0) or 0)
+        supported, reason = _compute_compatibility(lib_label, printer_model, two_color)
 
         if lib_id in yml_entries:
             y = yml_entries[lib_id]
@@ -49,12 +89,15 @@ def load_catalog(yml_path: Path) -> None:
                 description=y.get("description"),
                 category=y.get("category"),
                 color_capable=bool(y.get("color_capable", False)),
-                printer_requirements=y.get("printer_requirements") or [],
                 common_use=y.get("common_use") or [],
                 preview_image=y.get("preview_image"),
                 dots_printable=dots,
                 tape_size=tape,
                 form_factor=form_factor_int,
+                restricted_to_models=restricted,
+                color=color,
+                supported=supported,
+                incompatible_reason=reason,
             )
         else:
             entry = LabelEntry(
@@ -63,6 +106,10 @@ def load_catalog(yml_path: Path) -> None:
                 dots_printable=dots,
                 tape_size=tape,
                 form_factor=form_factor_int,
+                restricted_to_models=restricted,
+                color=color,
+                supported=supported,
+                incompatible_reason=reason,
             )
             lib_only += 1
 
diff --git a/backend/labelforge/models/__init__.py b/backend/labelforge/models/__init__.py
index d197ce7..a564b31 100644
--- a/backend/labelforge/models/__init__.py
+++ b/backend/labelforge/models/__init__.py
@@ -12,7 +12,6 @@ class LabelEntry(BaseModel):
     description: str | None = None
     category: str | None = None
     color_capable: bool = False
-    printer_requirements: list[str] = []
     common_use: list[str] = []
     preview_image: str | None = None
     # library-derived fields
@@ -20,6 +19,14 @@ class LabelEntry(BaseModel):
     tape_size: tuple[int, int] = (0, 0)
     # form_factor integer: 1=die-cut, 2=continuous, 3=round, 4=ptouch-continuous
     form_factor: int = 0
+    # models this media is restricted to ([] = works on all); from brother_ql
+    restricted_to_models: list[str] = []
+    # 1 = two-color media (needs a two-color printer), 0 = mono
+    color: int = 0
+    # whether the configured printer can print this media (computed at load)
+    supported: bool = True
+    # human-readable reason when supported is False
+    incompatible_reason: str | None = None
 
 
 class FontInfo(BaseModel):
diff --git a/docs/decisions.md b/docs/decisions.md
index 4f648d4..8056000 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,35 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-26 — Printer↔label compatibility is library-derived, computed at catalog load; `printer_requirements` deprecated
+
+**Decision**: A label's printability on the configured printer is computed at catalog load from primitive `brother_ql` fields, not declared in `labels.yml`. Each catalog entry gains `restricted_to_models` (`Label.restricted_to_models`), `color` (`Label.color`), a computed `supported: bool`, and `incompatible_reason: str | None`. The rule:
+
+```python
+supported = (not label.restricted_to_models or printer_model in label.restricted_to_models) \
+            and (label.color == 0 or model.two_color)
+```
+
+`model` is the entry in `brother_ql.models.ALL_MODELS` whose `identifier == PRINTER_MODEL`; `two_color` flags the QL-800 series. If the configured model isn't found, a warning is logged and all media are treated as supported. Selectors render unsupported media as disabled+greyed `<option>`s with a tooltip and guard programmatic default selection. The `printer_requirements` yml field is **deprecated and ignored** (removed from the model, the default yml, and the loader).
+
+**Why**: The catalog already follows "library is truth, yml is the UX layer" (see the 2026-05-19 label-catalog ADR). A hand-maintained `printer_requirements` list violated that — it drifts from the library and can't express two-color capability, which lives on the printer model, not the media. Deriving compatibility from the library keeps a single source of truth and means new media/printer support from a library bump Just Works. On the configured QL-820NWB this correctly disables the six wide-format rolls the printer physically can't feed while keeping `62red` available.
+
+**Why not `Label.works_with_model()`**: The obvious library helper is unusable in the pinned `brother-ql-inventree>=1.3`. Verified against the installed library:
+- It raises `NameError: name 'models' is not defined` for **any** restricted label (`brother_ql/labels.py:67`) — e.g. `labels['102'].works_with_model('QL-820NWB')` throws.
+- It ignores two-color capability — `labels['62red'].works_with_model('QL-700')` returns `True` even though a mono QL-700 can't print two-color media.
+
+So the helper is both crash-prone and wrong. Computing from `restricted_to_models` + `color` vs `model.two_color` sidesteps both bugs. This is an upstream bug worth reporting to `inventree/brother_ql`; until fixed (and the fix reaches our pin) we do not call `works_with_model()`.
+
+**Considered**:
+- Keep `printer_requirements` in yml — rejected; contradicts the library-truth ADR and can't know two-color.
+- Use `Label.works_with_model()` — rejected; crashes on restricted labels and ignores color (above).
+- Hide unsupported media entirely — rejected; the spec calls for disable+tooltip so the user understands *why* a roll they own isn't offered.
+- Recompute per request — unnecessary; `PRINTER_MODEL` is fixed in config, so compute once at load. A future `POST /api/admin/reload-catalog` recomputes.
+
+**Would revisit if**: a future printer becomes runtime-configurable (then compatibility must recompute on change, not just at load), or upstream fixes `works_with_model()` and the fix reaches our pin (then prefer the library helper over the open-coded rule).
+
+---
+
 ## 2026-05-26 — Label selectors show `brother_part: display_name`; `52x29` intentionally has no part number
 
 **Decision**: Label-media `<select>` options render as `{brother_part}: {display_name}` (e.g. `DK-22205: 62mm Continuous (Black)`) when the catalog entry has a `brother_part`, and as the display name alone when it doesn't. The grouping/formatting lives in one shared helper (`frontend/src/labels.ts::buildLabelOptionsHtml`) used by every label selector. The default `labels.yml` was backfilled so 14 of 15 entries carry a `brother_part`; `52x29` is deliberately left without one.
diff --git a/docs/features/label-catalog.md b/docs/features/label-catalog.md
index 536d944..f6f31dd 100644
--- a/docs/features/label-catalog.md
+++ b/docs/features/label-catalog.md
@@ -47,10 +47,6 @@ labels:
     description: "Two-color paper tape. Requires QL-800 series printer."
     category: continuous
     color_capable: true
-    printer_requirements:
-      - "QL-800"
-      - "QL-810W"
-      - "QL-820NWB"
 
   - id: "29x90"
     display_name: "29mm × 90mm Address Label"
@@ -88,12 +84,40 @@ labels:
 | `description` | no | Long description, shown on hover or in selector |
 | `category` | no | `continuous` / `die-cut` / `round` — drives grouping in the picker |
 | `color_capable` | no | bool — drives a UI hint when red elements are used |
-| `printer_requirements` | no | list of QL models that support this media — drives a warning if a different printer is configured |
+| `printer_requirements` | no | **Deprecated and ignored.** Printer compatibility is now library-derived (see below), not declared per-entry. Remove it from entries; it has no effect. |
 | `common_use` | no | list of tags, used to surface "Recommended for X" hints in the template-create flow |
 | `preview_image` | no | filename relative to `/var/docker/labelforge/label-previews/` |
 
 Unknown fields in `labels.yml` are ignored (forward-compatible).
 
+## Printer compatibility
+
+Whether a given media can actually be printed depends on the **configured printer** (`PRINTER_MODEL`, default `QL-820NWB`), not on `labels.yml`. Compatibility is therefore **derived from the `brother_ql` library**, the same source of truth as the printable list — never hand-maintained. (This is why the old `printer_requirements` yml field is deprecated: a hand-kept printer list drifts from the library and can't know two-color capability.)
+
+Each catalog entry gets two extra library-derived fields plus the computed result:
+
+| Field | Source | Meaning |
+|---|---|---|
+| `restricted_to_models` | `brother_ql` `Label.restricted_to_models` | Models this media is restricted to. Empty = works on all models. Populated only for the six wide-format rolls, all restricted to the QL-1xxx series. |
+| `color` | `brother_ql` `Label.color` | `1` = two-color media (e.g. `62red`), `0` = mono. |
+| `supported` | computed | Whether the configured printer can print this media. |
+| `incompatible_reason` | computed | Human-readable reason shown as a tooltip when `supported` is false. |
+
+The rule, computed once at catalog load against the configured printer's `Model` (looked up by `identifier` in `brother_ql.models.ALL_MODELS`, whose `two_color: bool` flags the QL-800 series):
+
+```python
+supported = (not label.restricted_to_models or printer_model in label.restricted_to_models) \
+            and (label.color == 0 or model.two_color)
+```
+
+- Restricted to other models → `incompatible_reason = "Requires a wide-format printer (QL-1100 series)"`.
+- Two-color media on a mono printer → `incompatible_reason = "Requires a two-color printer (QL-800 series)"`.
+- If `PRINTER_MODEL` is not found in the library, a warning is logged and **all** media are treated as supported (don't wrongly disable everything).
+
+On the default `QL-820NWB`: the six wide rolls (`102`, `103`, `104`, `102x51`, `102x152`, `103x164`) → `supported = false`; everything else including `62red` → `supported = true`.
+
+> Computed at load because `PRINTER_MODEL` is fixed in config. A future `POST /api/admin/reload-catalog` recomputes it. `brother_ql`'s `Label.works_with_model()` is **not** used — it's broken in the pinned fork (raises `NameError` on restricted labels and ignores two-color). See `docs/decisions.md`.
+
 ## Loading
 
 At startup:
@@ -118,7 +142,7 @@ Reload on `SIGHUP` or via an admin endpoint (`POST /api/admin/reload-catalog`).
 - Label picker dropdown groups by `category` (`Continuous`, `Die-cut`, `Round`)
 - Within a category, entries are sorted by `display_name`
 - Color-capable labels show a small red/black indicator
-- When the configured printer doesn't match `printer_requirements`, the entry is shown but disabled with a tooltip
+- Media the configured printer can't print (`supported = false`, see "Printer compatibility") stays visible in its group but is rendered as a **disabled, greyed `<option>`** with a `— unavailable` marker and a `title` tooltip carrying the `incompatible_reason`. The browser won't let a user pick a disabled option; selectors also guard programmatic default/restored selections, falling back to the first supported entry.
 
 ## Defaults shipped in repo
 
diff --git a/frontend/src/labels.ts b/frontend/src/labels.ts
index f073878..17dbc3f 100644
--- a/frontend/src/labels.ts
+++ b/frontend/src/labels.ts
@@ -40,9 +40,35 @@ export function buildLabelOptionsHtml(labels: LabelEntry[]): string {
       const groupLabel = FORM_FACTOR_LABEL[k] ?? 'Other'
       const opts = groups
         .get(k)!
-        .map(l => `<option value="${esc(l.id)}">${esc(labelOptionText(l))}</option>`)
+        .map(l => {
+          if (l.supported) {
+            return `<option value="${esc(l.id)}">${esc(labelOptionText(l))}</option>`
+          }
+          const reason = l.incompatible_reason ?? 'Not supported by the configured printer'
+          return `<option value="${esc(l.id)}" disabled title="${esc(reason)}">${esc(labelOptionText(l))} — unavailable</option>`
+        })
         .join('')
       return `<optgroup label="${esc(groupLabel)}">${opts}</optgroup>`
     })
     .join('')
 }
+
+// First label id the configured printer can actually print, in the same group
+// order the picker renders. Used to redirect a default/restored selection away
+// from media the printer can't handle (the browser blocks picking a disabled
+// <option>, but a programmatic .value set can still land on one).
+export function firstSupportedId(labels: LabelEntry[]): string | undefined {
+  const groups = new Map<number, LabelEntry[]>()
+  for (const l of labels) {
+    if (!groups.has(l.form_factor)) groups.set(l.form_factor, [])
+    groups.get(l.form_factor)!.push(l)
+  }
+  for (const entries of groups.values()) {
+    entries.sort((a, b) => a.display_name.localeCompare(b.display_name))
+  }
+  for (const k of [...new Set([...FF_ORDER, ...groups.keys()])].filter(k => groups.has(k))) {
+    const hit = groups.get(k)!.find(l => l.supported)
+    if (hit) return hit.id
+  }
+  return undefined
+}
diff --git a/frontend/src/pages/quick-print.ts b/frontend/src/pages/quick-print.ts
index 5b6713e..992dedf 100644
--- a/frontend/src/pages/quick-print.ts
+++ b/frontend/src/pages/quick-print.ts
@@ -1,6 +1,6 @@
 import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api'
 import type { QuickPrintRequest } from '../types'
-import { buildLabelOptionsHtml } from '../labels'
+import { buildLabelOptionsHtml, firstSupportedId } from '../labels'
 
 function esc(s: string): string {
   return s
@@ -215,6 +215,14 @@ function renderForm(root: HTMLElement): void {
       )
       if (oRadio) oRadio.checked = true
     }
+
+    // The chosen default/restored media may be unsupported by the configured
+    // printer (its <option> is disabled). Fall back to the first supported id.
+    const chosen = labels.find(l => l.id === labelSelect.value)
+    if (!chosen || !chosen.supported) {
+      const fallback = firstSupportedId(labels)
+      if (fallback) labelSelect.value = fallback
+    }
   }).catch((err: Error) => {
     showStatus(`Failed to load form data: ${err.message}`, 'error')
   })
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index 9b9bd24..5a47353 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -1,7 +1,7 @@
 import { deleteTemplate, listTemplates } from '../api'
 import type { Template } from '../types'
 import { navigate } from '../router'
-import { buildLabelOptionsHtml } from '../labels'
+import { buildLabelOptionsHtml, firstSupportedId } from '../labels'
 
 function esc(s: string): string {
   return s
@@ -167,6 +167,12 @@ function showNewTemplateModal(onCreated: () => void): void {
 
     getLabels().then(labels => {
       mediaSelect.innerHTML = buildLabelOptionsHtml(labels)
+      // Don't let the select default to a disabled (unsupported) option.
+      const chosen = labels.find(l => l.id === mediaSelect.value)
+      if (!chosen || !chosen.supported) {
+        const fallback = firstSupportedId(labels)
+        if (fallback) mediaSelect.value = fallback
+      }
       updateOk()
     })
 
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 989e89a..acc7edf 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -5,13 +5,20 @@ export interface LabelEntry {
   description: string | null;
   category: string | null;
   color_capable: boolean;
-  printer_requirements: string[];
   common_use: string[];
   preview_image: string | null;
   dots_printable: [number, number];
   tape_size: [number, number];
   // 1=die-cut, 2=continuous, 3=round, 4=ptouch-continuous
   form_factor: number;
+  // models this media is restricted to ([] = works on all)
+  restricted_to_models: string[];
+  // 1 = two-color media, 0 = mono
+  color: number;
+  // whether the configured printer can print this media
+  supported: boolean;
+  // human-readable reason when supported is false
+  incompatible_reason: string | null;
 }
 
 export interface FontInfo {
diff --git a/labels.yml b/labels.yml
index e5c9789..655e8b5 100644
--- a/labels.yml
+++ b/labels.yml
@@ -62,10 +62,6 @@ labels:
     description: "Two-color paper tape. Requires QL-800 series printer."
     category: continuous
     color_capable: true
-    printer_requirements:
-      - "QL-800"
-      - "QL-810W"
-      - "QL-820NWB"
 
   # ── Die-cut ───────────────────────────────────────────────────────────────
 
diff --git a/prompts/2026-05-26-printer-label-compatibility.md b/prompts/2026-05-26-printer-label-compatibility.md
new file mode 100644
index 0000000..804e7f8
--- /dev/null
+++ b/prompts/2026-05-26-printer-label-compatibility.md
@@ -0,0 +1,81 @@
+---
+name: 2026-05-26-printer-label-compatibility
+status: completed
+created: 2026-05-26
+completed: 2026-05-26
+result: Catalog now computes a library-derived `supported` flag per label against the configured printer; selectors disable+grey unsupported media with a tooltip; `printer_requirements` removed. Verified against the installed library (QL-820NWB disables the 6 wide rolls, keeps 62red; QL-700 disables 62red; QL-1100 enables wide). ADR added.
+---
+
+# Task: derive label↔printer compatibility from the library and disable incompatible media in the pickers
+
+Read `CLAUDE.md` first. Load `docs/features/label-catalog.md`, `docs/architecture.md`, `docs/glossary.md`, and `docs/features/settings.md`. Work on `dev`, commit don't push, no co-author tags.
+
+## Goal
+
+The label catalog currently lists every label the `brother_ql` library knows about, regardless of whether the configured printer can print it. On the configured QL-820NWB the picker shows 6 wide-format media it physically cannot print. Make the catalog **printer-aware**: each label gets a `supported` flag computed against the configured printer, and the selectors show unsupported media **disabled + greyed with a tooltip** (this is already specified in `docs/features/label-catalog.md` under "UI behavior").
+
+## Decisions already made (do not relitigate)
+
+- **Compatibility is library-derived**, not hand-maintained in `labels.yml`. This is consistent with the ADR "Label catalog: library truth + yml UX layer." Do NOT add a `compatible_printers`/printer array to `labels.yml`.
+- **The `printer_requirements` yml field is deprecated** and replaced by this. Remove it (see below).
+- Picker behavior for incompatible media: **disable + tooltip** (keep it visible in its group, do not hide).
+- **Do NOT use `Label.works_with_model()`** — it is broken in the pinned library (`brother-ql-inventree>=1.3`): it raises `NameError: name 'models' is not defined` (`brother_ql/labels.py:67`) for any restricted label, and it ignores two-color capability (returns `True` for `62red` on a mono `QL-700`). Compute compatibility from primitive fields instead.
+
+## The compatibility rule (verified against the installed library)
+
+```python
+supported = (not label.restricted_to_models or printer_model in label.restricted_to_models) \
+            and (label.color == 0 or model.two_color)
+```
+
+Verified library facts (`brother_ql` from `brother-ql-inventree>=1.3`):
+
+- `Label.restricted_to_models: list[str]` — empty = works on all models. Populated only for these 6 wide-format labels, all restricted to the QL-1xxx series (`QL-1050`, `QL-1060N`, `QL-1100`, `QL-1110NWB`, `QL-1115NWB`):
+  `102`, `103` (→ only `QL-1100`/`QL-1110NWB`), `104`, `102x51`, `102x152`, `103x164` (→ only `QL-1100`/`QL-1110NWB`).
+- `Label.color: int` — `1` for two-color (`62red`), `0` for mono.
+- `Model.two_color: bool` — from `brother_ql.models.ALL_MODELS`. `True` for the 800-series (`QL-800`, `QL-810W`, `QL-820NWB`); `False` otherwise.
+
+**Expected result for the default `printer_model="QL-820NWB"`:** the 6 wide labels above → `supported=False`; everything else (incl. `62red`) → `supported=True`.
+
+## Current state / where things live
+
+- `backend/labelforge/config.py:9` — `printer_model: str = "QL-820NWB"` (from `.env`). Already exists; the catalog must use it.
+- `backend/labelforge/catalog/loader.py` — `load_catalog()` iterates `ALL_LABELS` and builds `LabelEntry` per id. This is where to read `restricted_to_models` + `color` and compute `supported`. Loaded once at startup; `printer_model` is fixed in config, so compute at load time. (A future `POST /api/admin/reload-catalog` should recompute — fine to leave a note.)
+- `backend/labelforge/models/__init__.py` — `LabelEntry` Pydantic model. Currently has `printer_requirements: list[str]` (to be removed).
+- `frontend/src/types.ts` — `LabelEntry` TS interface (mirror the model).
+- `frontend/src/labels.ts` — `buildLabelOptionsHtml(labels)` is the SINGLE place that renders `<option>` markup; both selectors use it. Add the disabled/tooltip rendering here.
+- Selectors that call the helper: `frontend/src/pages/quick-print.ts` and `frontend/src/pages/templates-list.ts` (new-template modal). The template editor has no media selector.
+
+## Implementation
+
+### Backend
+1. In `loader.py`, build a model lookup once: `from brother_ql.models import ALL_MODELS`; find the `Model` whose `identifier == config.settings.printer_model`.
+   - **If the configured model is not found** in `ALL_MODELS`: log a warning and treat **all** labels as supported (don't wrongly disable everything). Capture `two_color = found_model.two_color if found else None`, and when `None` skip the color check.
+2. For each library label, read `restricted_to_models` (coerce to `list[str]`) and `color` (int). Compute `supported` per the rule above.
+3. Compute `incompatible_reason: str | None` for unsupported entries:
+   - restricted and printer not in it → `"Requires a wide-format printer (QL-1100 series)"`.
+   - two-color label on a mono printer → `"Requires a two-color printer (QL-800 series)"`.
+4. Add to `LabelEntry`: `restricted_to_models: list[str] = []`, `color: int = 0`, `supported: bool = True`, `incompatible_reason: str | None = None`. **Remove** `printer_requirements`.
+
+### Frontend
+5. `types.ts`: mirror the model — add `restricted_to_models`, `color`, `supported`, `incompatible_reason`; remove `printer_requirements`.
+6. `labels.ts`: in `buildLabelOptionsHtml`, render unsupported entries as `<option ... disabled title="${esc(incompatible_reason)}">`. Keep them in their form-factor group. Consider a trailing marker (e.g. ` — unavailable`) in the option text for clarity.
+7. Default-selection guard: in `quick-print.ts` and `templates-list.ts`, when applying the default/restored `label_media`, if that id is unsupported fall back to the first supported entry. (A small `firstSupportedId(labels)` helper in `labels.ts` is reasonable.) Browsers won't let a user pick a `disabled` option, but a programmatic `.value` set can still land on one — guard it.
+
+### Data / docs
+8. `labels.yml`: remove the now-dead `printer_requirements:` block from the `62red` entry.
+9. `docs/features/label-catalog.md`: replace the `printer_requirements` row/explanation with the library-derived model (`restricted_to_models` + `color`/`two_color` vs configured `printer_model`); note `printer_requirements` is deprecated/ignored.
+10. `CHANGELOG.md` `## [Unreleased]`: concise user-facing entry.
+11. `docs/decisions.md`: add an ADR (newest at top) — library-derived compatibility computed at catalog load against the configured printer; `works_with_model()` rejected as buggy (cite the `NameError` and the ignored two-color); `printer_requirements` deprecated. Consider noting the upstream bug could be reported to `inventree/brother_ql`.
+
+## Verification
+
+- Backend: load the catalog with `printer_model="QL-820NWB"` and assert `102`/`102x51`/`103x164` → `supported=False`, `62`/`62red`/`62x100` → `supported=True`; with `printer_model="QL-700"` assert `62red` → `supported=False`; with `printer_model="QL-1100"` assert `102` → `supported=True`. (A quick pytest or a throwaway script is fine.)
+- Frontend: `cd frontend && npx tsc --noEmit && npm run build` must pass.
+- Visual: `npm run dev` → quick-print and "New template" → the 6 wide media are greyed with a tooltip; `62red` is selectable.
+
+## Last steps (required)
+
+- Commit to `dev` with a descriptive message (imperative, no co-author tag).
+- Update THIS file's frontmatter: set `status` (`completed`/`failed`), `completed:` date, and a one-line `result:`.
+- If any non-obvious decision/workaround came up beyond what's above, add it to `docs/decisions.md` as an ADR.

From 6023d2d144b4d0abd7062794dca8e5f8ee8d95f0 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 26 May 2026 22:49:05 -0700
Subject: [PATCH 43/84] Use Brother 4-digit US SKU format; name 62x29 as Small
 Address

- brother_part now uses Brother's 4-digit US SKU (e.g. DK-1209), the
  number printed on US/NA boxes, not the 5-digit international form
  (DK-11209); document the convention in a labels.yml comment
- 62x29 confirmed as DK-1209 "Small Address" by a physical print on the
  QL-820NWB; rename its display_name/description to match the product
- Update the CHANGELOG and ADR examples to the 4-digit form
---
 CHANGELOG.md      |  2 +-
 docs/decisions.md |  2 +-
 labels.yml        | 33 +++++++++++++++++----------------
 3 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad5c2bf..0f3ef3a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,7 +11,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 ### Added
 
 - **Printer-aware label catalog** — each label now carries a `supported` flag computed at catalog load against the configured printer (`PRINTER_MODEL`). Media the printer physically can't print — wide-format rolls on a non-QL-1xxx printer, two-color rolls on a mono printer — appear in the selectors greyed out, disabled, and marked `— unavailable` with a tooltip explaining why, instead of being silently offered. On the default QL-820NWB the six wide-format rolls (`102`, `103`, `104`, `102x51`, `102x152`, `103x164`) are now disabled; `62red` stays selectable. Compatibility is derived from the `brother_ql` library, not hand-maintained — the `printer_requirements` field in `labels.yml` is deprecated and ignored.
-- **Brother DK part numbers in label selectors** — the label-media dropdown (quick-print and the new-template modal) now shows the part number with the name, e.g. `DK-22205: 62mm Continuous (Black)`; entries without a part number show the name alone. Backfilled `brother_part` for 9 more default catalog entries (14 of 15 now carry a part number; `52x29` has no consumer DK roll). Grouping/formatting moved into a shared `frontend/src/labels.ts` helper.
+- **Brother DK part numbers in label selectors** — the label-media dropdown (quick-print and the new-template modal) now shows the part number with the name, e.g. `DK-2205: 62mm Continuous (Black)`; entries without a part number show the name alone. Backfilled `brother_part` for 9 more default catalog entries (14 of 15 now carry a part number; `52x29` has no consumer DK roll). Grouping/formatting moved into a shared `frontend/src/labels.ts` helper.
 - **Template recall UI** — fill variable fields, preview, and print from saved templates at `/templates/{name}/print`; batch printing with auto-increment for numeric fields
 - **Templates editor foundation (text-only slice)** — canvas editor at `/templates/{name}` built on Fabric.js 6.6.1:
   - Templates list page at `/templates`: shows name, label media, last-updated; Edit and Delete (soft-delete) per row; empty state
diff --git a/docs/decisions.md b/docs/decisions.md
index 8056000..94cdf5f 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -35,7 +35,7 @@ So the helper is both crash-prone and wrong. Computing from `restricted_to_model
 
 ## 2026-05-26 — Label selectors show `brother_part: display_name`; `52x29` intentionally has no part number
 
-**Decision**: Label-media `<select>` options render as `{brother_part}: {display_name}` (e.g. `DK-22205: 62mm Continuous (Black)`) when the catalog entry has a `brother_part`, and as the display name alone when it doesn't. The grouping/formatting lives in one shared helper (`frontend/src/labels.ts::buildLabelOptionsHtml`) used by every label selector. The default `labels.yml` was backfilled so 14 of 15 entries carry a `brother_part`; `52x29` is deliberately left without one.
+**Decision**: Label-media `<select>` options render as `{brother_part}: {display_name}` (e.g. `DK-2205: 62mm Continuous (Black)`) when the catalog entry has a `brother_part`, and as the display name alone when it doesn't. The grouping/formatting lives in one shared helper (`frontend/src/labels.ts::buildLabelOptionsHtml`) used by every label selector. The default `labels.yml` was backfilled so 14 of 15 entries carry a `brother_part`; `52x29` is deliberately left without one.
 
 **Why**: The part number is how the owner actually identifies a roll to load, so it belongs in front of the human name in every place a label is chosen. Brother's QL-820NWB consumables list confirmed the part numbers; `52x29` is a `brother_ql`-printable size with **no consumer DK roll**, so there is nothing to map — the empty `brother_part` is correct, not an oversight. The format degrades cleanly (no dangling `: `). Centralizing in one helper keeps quick-print and the new-template modal from drifting and makes a future third selector consistent for free.
 
diff --git a/labels.yml b/labels.yml
index 655e8b5..aec5eda 100644
--- a/labels.yml
+++ b/labels.yml
@@ -2,6 +2,7 @@
 # Maps brother_ql library identifiers to user-friendly metadata.
 # Required fields: id, display_name
 # All other fields are optional. Unknown fields are ignored.
+# brother_part uses Brother's 4-digit SKU format (e.g. DK-1209), as printed on US/NA boxes.
 # Reload: restart the app or POST /api/admin/reload-catalog (future slice).
 
 labels:
@@ -10,42 +11,42 @@ labels:
 
   - id: "12"
     display_name: "12mm Continuous"
-    brother_part: "DK-22214"
+    brother_part: "DK-2214"
     description: "Narrow continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "29"
     display_name: "29mm Continuous"
-    brother_part: "DK-22210"
+    brother_part: "DK-2210"
     description: "Medium-width continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "38"
     display_name: "38mm Continuous"
-    brother_part: "DK-22225"
+    brother_part: "DK-2225"
     description: "Wide continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "50"
     display_name: "50mm Continuous"
-    brother_part: "DK-22223"
+    brother_part: "DK-2223"
     description: "50mm continuous tape, black on white."
     category: continuous
     color_capable: false
 
   - id: "54"
     display_name: "54mm Continuous"
-    brother_part: "DK-N55224"
+    brother_part: "DK-N5224"
     description: "54mm continuous tape, black on white. Non-adhesive."
     category: continuous
     color_capable: false
 
   - id: "62"
     display_name: "62mm Continuous (Black)"
-    brother_part: "DK-22205"
+    brother_part: "DK-2205"
     description: "General-purpose paper tape, black on white."
     category: continuous
     color_capable: false
@@ -58,7 +59,7 @@ labels:
 
   - id: "62red"
     display_name: "62mm Continuous (Black + Red)"
-    brother_part: "DK-22251"
+    brother_part: "DK-2251"
     description: "Two-color paper tape. Requires QL-800 series printer."
     category: continuous
     color_capable: true
@@ -67,21 +68,21 @@ labels:
 
   - id: "17x54"
     display_name: "17mm × 54mm Die-cut"
-    brother_part: "DK-11204"
+    brother_part: "DK-1204"
     description: "Small die-cut label."
     category: die-cut
     color_capable: false
 
   - id: "17x87"
     display_name: "17mm × 87mm Die-cut"
-    brother_part: "DK-11203"
+    brother_part: "DK-1203"
     description: "Small elongated die-cut label."
     category: die-cut
     color_capable: false
 
   - id: "29x90"
     display_name: "29mm × 90mm Address Label"
-    brother_part: "DK-11201"
+    brother_part: "DK-1201"
     description: "Standard address label, die-cut."
     category: die-cut
     color_capable: false
@@ -92,7 +93,7 @@ labels:
 
   - id: "38x90"
     display_name: "38mm × 90mm Die-cut"
-    brother_part: "DK-11208"
+    brother_part: "DK-1208"
     description: "Medium die-cut label."
     category: die-cut
     color_capable: false
@@ -105,15 +106,15 @@ labels:
     color_capable: false
 
   - id: "62x29"
-    display_name: "62mm × 29mm Die-cut"
-    brother_part: "DK-11209"
-    description: "Wide short die-cut label."
+    display_name: "62mm × 29mm Small Address"
+    brother_part: "DK-1209"
+    description: "Small address label, die-cut."
     category: die-cut
     color_capable: false
 
   - id: "62x100"
     display_name: "62mm × 100mm Shipping Label"
-    brother_part: "DK-11202"
+    brother_part: "DK-1202"
     description: "Larger die-cut, good for shipping or product labels."
     category: die-cut
     color_capable: false
@@ -125,7 +126,7 @@ labels:
 
   - id: "d24"
     display_name: "24mm Round"
-    brother_part: "DK-11218"
+    brother_part: "DK-1218"
     description: "Round die-cut, 24mm diameter."
     category: round
     color_capable: false

From 3fc668303fea459dcc45d0804a1d406fba52d9fc Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 07:33:24 -0700
Subject: [PATCH 44/84] chore: adopt code-checkin-and-pr, repo-sandbox, vexp
 standards; upgrade handoff-prompt-workflow

---
 .claude/CLAUDE.md                             | 60 ------------
 .claude/hooks/vexp-guard.sh                   | 14 +++
 .claude/settings.json                         | 24 +++++
 .github/workflows/ci.yml                      | 45 +++++++++
 .gitignore                                    | 12 ++-
 .vexpignore                                   | 16 ++++
 CHANGELOG.md                                  |  4 +
 CLAUDE.md                                     | 95 +++++++++++++++++--
 docs/decisions.md                             | 12 +++
 prompts/TEMPLATE.md                           | 50 ++++++++++
 .../2026-05-25-template-recall-ui.md          |  0
 .../2026-05-26-printer-label-compatibility.md |  0
 standards.md                                  | 14 +++
 13 files changed, 274 insertions(+), 72 deletions(-)
 delete mode 100644 .claude/CLAUDE.md
 create mode 100755 .claude/hooks/vexp-guard.sh
 create mode 100644 .vexpignore
 create mode 100644 prompts/TEMPLATE.md
 rename prompts/{ => done}/2026-05-25-template-recall-ui.md (100%)
 rename prompts/{ => done}/2026-05-26-printer-label-compatibility.md (100%)
 create mode 100644 standards.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
deleted file mode 100644
index 09b4011..0000000
--- a/.claude/CLAUDE.md
+++ /dev/null
@@ -1,60 +0,0 @@
-## vexp — Context-Aware AI Coding <!-- vexp v2.0.17 -->
-
-### MANDATORY: use vexp pipeline — do NOT grep or glob the codebase
-For every task — bug fixes, features, refactors, debugging:
-**call `run_pipeline` FIRST**. It executes context search + impact analysis +
-memory recall in a single call, returning compressed results.
-
-Do NOT use grep, glob, Bash, or cat to search/explore the codebase.
-vexp returns pre-indexed, graph-ranked context that is more relevant and
-uses fewer tokens than manual searching. Prefer `get_skeleton` over Read to
-inspect files (detail: minimal/standard/detailed, 70-90% token savings).
-Only use Read when you need exact raw content to edit a specific line.
-
-### Primary Tool
-- `run_pipeline` — **USE THIS FOR EVERYTHING**. Single call that runs
-  capsule + impact + memory server-side. Returns compressed results.
-  Auto-detects intent (debug/modify/refactor/explore) from your task.
-  Includes full file content for pivots.
-  Examples:
-  - `run_pipeline({ "task": "fix JWT validation bug" })` — auto-detect
-  - `run_pipeline({ "task": "refactor db layer", "preset": "refactor" })` — explicit
-  - `run_pipeline({ "task": "add auth", "observation": "using JWT" })` — save insight in same call
-
-### Other MCP tools (use only when run_pipeline is insufficient)
-- `get_skeleton` — **preferred over Read** for inspecting files (minimal/standard/detailed detail levels, 70-90% token savings)
-- `index_status` — indexing status and health check
-- `expand_vexp_ref` — expand V-REF hash placeholders in v2 compact output
-
-### Workflow
-1. `run_pipeline("your task")` — ALWAYS FIRST. Returns pivots + impact + memories in 1 call
-2. Need more detail on a file? Use `get_skeleton({ files: [...], detail: "detailed" })` — avoid Read unless editing
-3. Make targeted changes based on the context returned
-4. `run_pipeline` again ONLY if you need more context during implementation
-5. Do NOT chain multiple vexp calls — one `run_pipeline` replaces capsule + impact + memory + observation
-
-### Subagent / Explore / Plan mode
-- Subagents CAN and MUST call `run_pipeline` — always include the task description
-- The PreToolUse hook blocks Grep/Glob when vexp daemon is running
-- Do NOT spawn Agent(Explore) to freely search — call `run_pipeline` first,
-  then pass the returned context into the agent prompt if needed
-- Always: `run_pipeline` → get context → spawn agent with context
-
-### Smart Features (automatic — no action needed)
-- **Intent Detection**: auto-detects from your task keywords. "fix bug" → Debug, "refactor" → blast-radius, "add" → Modify
-- **Hybrid Search**: keyword + semantic + graph centrality ranking
-- **Session Memory**: auto-captures observations; memories auto-surfaced in results
-- **LSP Bridge**: VS Code captures type-resolved call edges
-- **Change Coupling**: co-changed files included as related context
-
-### Advanced Parameters
-- `preset: "debug"` — forces debug mode (capsule+tests+impact+memory)
-- `preset: "refactor"` — deep impact analysis (depth 5)
-- `max_tokens: 12000` — increase total budget for complex tasks
-- `include_tests: true` — include test files in results
-- `include_file_content: false` — omit full file content (lighter response)
-
-### Multi-Repo Workspaces
-`run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope.
-Use `index_status` to discover available repo aliases.
-<!-- /vexp -->
\ No newline at end of file
diff --git a/.claude/hooks/vexp-guard.sh b/.claude/hooks/vexp-guard.sh
new file mode 100755
index 0000000..9cefc1d
--- /dev/null
+++ b/.claude/hooks/vexp-guard.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+# vexp-guard: block Grep/Glob when vexp daemon is running AND index is healthy.
+# Fast path: if socket file or healthy marker doesn't exist, allow immediately.
+# PID check: verify daemon process is alive (handles stale files after kill -9).
+VEXP_DIR="${CLAUDE_PROJECT_DIR:-.}/.vexp"
+SOCK="$VEXP_DIR/daemon.sock"
+HEALTHY="$VEXP_DIR/healthy"
+PID_FILE="$VEXP_DIR/daemon.pid"
+if [ -S "$SOCK" ] && [ -f "$HEALTHY" ] && [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE" 2>/dev/null)" 2>/dev/null; then
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"vexp daemon is running. Use run_pipeline instead of Grep/Glob."}}'
+else
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"vexp index not ready, allowing direct search fallback."}}'
+fi
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
index 7c19ba3..2e7e232 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -1,6 +1,9 @@
 {
   "permissions": {
     "allow": [
+      "Read(**)",
+      "Edit(**)",
+      "Write(**)",
       "Bash(uname -a && hostname && cat /etc/os-release 2>/dev/null | head -5 && echo \"---\" && cat /proc/version 2>/dev/null)",
       "Read(//usr/lib/**)",
       "Read(//proc/**)",
@@ -35,6 +38,27 @@
       "Bash(docker *)"
     ]
   },
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true,
+    "network": {
+      "allowLocalBinding": true,
+      "allowedDomains": [
+        "localhost",
+        "127.0.0.1",
+        "pypi.org",
+        "files.pythonhosted.org",
+        "registry.npmjs.org"
+      ]
+    },
+    "filesystem": {
+      "allowWrite": [
+        "/tmp/**",
+        "~/.cache/**",
+        "~/.npm/**"
+      ]
+    }
+  },
   "hooks": {
     "PreToolUse": [
       {
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 5058db3..8ae9d0c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -114,3 +114,48 @@ jobs:
           load: false
           cache-from: type=gha
           cache-to: type=gha,mode=max
+
+  config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: pip install pyyaml
+      - name: Validate tracked YAML / JSON / TOML config
+        run: |
+          python - <<'PY'
+          import json, pathlib, subprocess, sys, tomllib
+          import yaml
+          files = subprocess.check_output(
+              ["git", "ls-files", "*.yml", "*.yaml", "*.json", "*.toml"],
+              text=True).split()
+          errors = []
+          for f in files:
+              p, data = pathlib.Path(f), pathlib.Path(f).read_bytes()
+              try:
+                  if p.suffix in (".yml", ".yaml"):
+                      list(yaml.safe_load_all(data))
+                  elif p.suffix == ".json":
+                      json.loads(data)
+                  elif p.suffix == ".toml":
+                      tomllib.loads(data.decode())
+              except Exception as e:
+                  errors.append(f"{f}: {e}")
+          for e in errors:
+              print(f"::error::{e}")
+          if errors:
+              sys.exit(1)
+          print(f"OK: {len(files)} config files parse cleanly")
+          PY
+
+  compose:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Validate compose files
+        run: |
+          for f in compose.yml compose.dev.yml; do
+            [ -f "$f" ] && docker compose -f "$f" config --quiet && echo "OK $f"
+          done
diff --git a/.gitignore b/.gitignore
index bed9d57..63296bd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,7 +49,9 @@ data-dev/
 *.sqlite
 *.sqlite3
 
-# vexp (VS Code extension daemon — all runtime state, config regenerable)
+# vexp (standalone systemd-user daemon — all runtime state is per-host and regenerable;
+# manifest.json intentionally NOT tracked, per the vexp-context-engine standard's
+# "each host owns its index" shape). The .vexpignore at the repo root IS tracked.
 .vexp/
 vexp.toml
 
@@ -57,10 +59,12 @@ vexp.toml
 *.log
 logs/
 
-# claude
-.claude/
+# claude — ignore the dir but track shared artifacts (settings.json, the hooks/ dir).
+# .claude/CLAUDE.md is vexp's per-host auto-generated file: left untracked (the verbatim
+# vexp snippet lives in the tracked root CLAUDE.md instead). settings.local.json stays ignored.
+.claude/*
 !.claude/settings.json
-!.claude/CLAUDE.md
+!.claude/hooks/
 
 # Test artifacts
 .coverage
diff --git a/.vexpignore b/.vexpignore
new file mode 100644
index 0000000..9d4a207
--- /dev/null
+++ b/.vexpignore
@@ -0,0 +1,16 @@
+# .vexpignore — paths excluded from vexp's code index/ranking (gitignore syntax).
+# These files STAY in git; they're just kept out of run_pipeline's ranked context so
+# source code isn't crowded out by process/handoff prose. Tune per project.
+#
+# vexp's built-in excludes already cover: node_modules, .git, dist, .next, target,
+# __pycache__, .vexp. The SecurityFilter already drops .env / credentials. Only add
+# things that ARE committed source-tree files but make poor ranked context.
+
+# Completed/failed handoff prompts — historical, never useful as live code context.
+prompts/done/
+prompts/failed/
+
+# Other common candidates (uncomment per project):
+# standards.md
+# CHANGELOG.md
+# docs/**/*.md        # only if spec/decision docs are crowding out code in results
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f3ef3a..056fe4e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Changed
+
+- **Adopted four crzynet engineering standards**, pinned in a new root `standards.md`: `code-checkin-and-pr @ 1.1.0` (commit messages now use Conventional-Commits prefixes `feat:`/`fix:`/`chore:`/`docs:`; CI gained structured-config and `docker compose config` validation jobs), `handoff-prompt-workflow @ 1.5.0` (completed handoff prompts now archived under `prompts/done/`; `prompts/TEMPLATE.md` added), `repo-sandbox-permissions @ 1.0.0` (repo-wide sandbox in `.claude/settings.json` — auto-approves in-repo work, gates out-of-repo writes and network), and `vexp-context-engine @ 2.1.0` (guard hook now tracked, `.vexpignore` added). Developer/process-facing only — no runtime behavior change.
+
 ### Known Issues
 
 - QR and barcode template elements render in preview but print as a solid black block (1-bit threshold crushes fine detail). These elements are gated to raise a clear error until fixed. Text, lines, and rectangles print correctly.
diff --git a/CLAUDE.md b/CLAUDE.md
index 6586401..ded30f9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,6 +8,10 @@ Context for AI coding sessions in this repo. Read this before doing anything.
 
 Owner: crzykidd. Personal homelab project, public open source. Single-user app — no multi-user features.
 
+## Standards
+
+This project implements shared engineering standards from the crzynet `homelab-configs` repo. **Read [`standards.md`](standards.md) at the repo root on session start** whenever the work could touch branching, commits, PRs, handoff prompts, the sandbox, or codebase search — it pins which standards and versions this repo conforms to. The hard per-session operational rules from those standards are pasted verbatim at the end of this file (Code check-in, Context search).
+
 ## Source of truth
 
 The design is in `docs/`. Do not invent features not described there. If a request expands scope, push back and ask whether the PRD should change first.
@@ -59,22 +63,23 @@ Every task follows: **plan → decide → execute → document**.
 
 1. **Plan first.** Before writing code, outline what will change and why. For small fixes the plan can be verbal in-session. For larger features, produce a handoff prompt (see below).
 2. **Decide: current session or handoff.** If the plan is scoped and the current session has context, do it here. If it's a large feature slice or a fresh context would be cleaner, write a handoff prompt for a new session.
-3. **Handoff prompts live in `prompts/`.** Checked into git. Format:
-   ```
-   prompts/YYYY-MM-DD-short-description.md
-   ```
-   Frontmatter:
+3. **Handoff prompts live in `prompts/`** (checked into git), per the `handoff-prompt-workflow` standard pinned in [`standards.md`](standards.md). The top-level `prompts/` dir is the **live queue** — pending work only. Start new prompts from `prompts/TEMPLATE.md`. Frontmatter:
    ```yaml
    ---
    name: YYYY-MM-DD-short-description
    status: pending          # pending | completed | failed
    created: YYYY-MM-DD
+   model:                   # opus = research/planning, sonnet = coding
    completed:               # filled when done
    result:                  # one-line summary of outcome
    ---
    ```
-   The **last instruction** in every handoff prompt must be: update this file's frontmatter — set status, completed date, and result summary. If any non-obvious decisions were made during the session (approach changed, alternative rejected, workaround needed), record them in `docs/decisions.md` as an ADR entry.
-4. **To run a handoff prompt:** `claude -- "$(cat prompts/file.md)"` (interactive session with file as opening prompt)
+   Before making edits, run `git status --porcelain` and cross-reference the files the plan touches; if any overlap with uncommitted work, list them and ask before touching. The **last instruction** in every handoff prompt: update its own frontmatter (status / completed / result), then `git mv` it into `prompts/done/` (success) or `prompts/failed/` (failure) — created lazily on first use. Record non-obvious decisions (approach changed, alternative rejected, workaround needed) in `docs/decisions.md` as an ADR entry.
+4. **To run a handoff prompt** — the moment you create one, hand the user this exact command (file-path form, never inlined `cat`):
+   ```
+   claude --model <model> "Read prompts/<file>.md and execute it as your task."
+   ```
+   `<model>` matches the prompt's `model:` field (opus = research/planning, sonnet = coding; omit to use the default). Run from the repo root so the relative path resolves.
 5. **Changelog entry required.** Every change — feature, fix, refactor — gets a short entry in `CHANGELOG.md` under `## [Unreleased]`. Write it for release notes (concise, user-facing language).
 6. **All dev work on `dev`** unless explicitly told otherwise.
 7. **Commit, don't push.** Sessions commit their work with a descriptive message. The owner pushes.
@@ -84,7 +89,7 @@ Every task follows: **plan → decide → execute → document**.
 
 - Line endings: LF only. `.gitattributes` enforces this. If `git diff --stat` shows all files modified, run `git config core.autocrlf input && git checkout -- .`
 - Branches: `main` is protected — the ONLY way in is a pull request, gated by CodeQL and other checks; never push to `main` directly. `dev` is the working branch (solo work commits straight to `dev`). Use `feature/<name>` branches when more than one person is working; merge those to `dev`, then PR `dev` → `main` for a release.
-- Commits: imperative present tense ("Add template recall endpoint" not "Added"). No conventional-commits prefixes. No co-author tags.
+- Commits: imperative present tense with a Conventional-Commits prefix — `feat:` (user-facing feature), `fix:` (bug fix), `chore:` (config/tooling/deps), `docs:` (docs only). E.g. `feat: add template recall endpoint`. No co-author tags. See the **Code check-in (operational rules)** section below for the full rule set.
 - Compose stack lives at the repo root as `compose.yml`. Dev compose at `compose.dev.yml`.
 
 ## Things to never do
@@ -97,3 +102,77 @@ Every task follows: **plan → decide → execute → document**.
 - Don't suggest hosted/SaaS replacements for any component
 - Don't write giant explainer comments in code — code should be readable; comments only for non-obvious *why*
 - Don't generate `package.json` / `pyproject.toml` / `Dockerfile` until the relevant slice has been scoped
+
+<!--
+Source: standards/code-checkin-and-pr @ v1.1.0 (crzynet/homelab-configs).
+Paste the section below verbatim into the adopting project's CLAUDE.md.
+The full standard (publishing matrix, retention, CI check definitions) lives at:
+https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/code-checkin-and-pr/README.md
+-->
+
+## Code check-in (operational rules)
+
+This project adopts the `code-checkin-and-pr` standard. The full why-and-how lives at
+the source above; the rules below are the per-session do/don'ts a coding agent must
+honor by default:
+
+- **Never push directly to `main`.** `main` is protected. All changes land via a pull
+  request from `dev` → `main`, and only when every required check is green.
+- **Day-to-day work happens on `dev`** (or a short-lived branch off `dev`). Push to
+  `dev` freely.
+- **Commit message prefixes are required** — Conventional-Commits style:
+  - `feat:` — new user-facing feature
+  - `fix:` — bug fix
+  - `chore:` — config, tooling, dependencies, maintenance
+  - `docs:` — documentation-only changes
+- **Do not add `Co-authored-by:` trailers** unless the user explicitly asks.
+- **Doc updates ship in the same commit as the code they describe** — never as a
+  follow-up commit.
+- **Never bypass hooks** (no `--no-verify`, `--no-gpg-sign`, etc.) unless the user
+  explicitly asks. If a hook fails, fix the underlying issue.
+- **Stable releases are tagged from `main` only.** Don't tag from `dev`.
+
+If you're unsure whether an action would violate one of the above, stop and ask before
+acting.
+
+<!--
+Source: standards/vexp-context-engine @ v2.1.0 (crzynet/homelab-configs).
+Paste the section below verbatim into the adopting project's CLAUDE.md.
+The full standard (scope, the two pushes, the manifest-not-tracked shape,
+adoption + gate + verification procedure) lives at:
+https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/vexp-context-engine/README.md
+-->
+
+## Context search (operational rules)
+
+This project adopts the `vexp-context-engine` standard. The full why-and-how lives at the
+source above; the rules below are the per-session do/don'ts a coding agent must honor by
+default:
+
+- **Call `run_pipeline` FIRST for any code task** — bug fixes, features, refactors,
+  debugging, "how does X work", "where is Y". It runs context search + impact analysis +
+  memory recall in one call and returns ranked, compressed context.
+- **Do NOT `grep`, `glob`, or `cat` to explore the codebase.** vexp returns pre-indexed,
+  graph-ranked context that is more relevant and cheaper than manual searching. A
+  `PreToolUse` guard hook blocks `Grep`/`Glob` while the vexp daemon is healthy; if the
+  daemon is down it allows the fallback.
+- **Prefer `get_skeleton` over `Read` to inspect files** (minimal/standard/detailed —
+  70–90% fewer tokens). Use `Read` only when you need exact raw content to edit a specific
+  line.
+- **Don't chain vexp calls or fan out `Explore` agents to free-search.** One
+  `run_pipeline` replaces capsule + impact + memory; if a subagent needs context, run
+  `run_pipeline` first and pass the result into the agent's prompt.
+- **The vexp daemon runs as a standalone `systemd`-user service — NOT the VS Code
+  extension.** The supervisor is `vexp.service` (`ExecStart=vexp serve`), `enabled` + linger,
+  auto-restarting; it starts/adopts the per-repo daemon on demand. Managing it with
+  `systemctl --user … vexp.service` or `vexp daemon-cmd start|stop|status|logs` is the
+  expected control path, not forbidden. Do **not** run vexp from the VS Code extension
+  (deprecated here — older bundled core, contends for the socket/port).
+- **Start/manage the daemon in the host process namespace (un-sandboxed).** A daemon
+  spawned inside a sandboxed shell gets a throwaway PID namespace + socket the host-side
+  MCP can't reach, and dies when that shell exits. If `index_status` reports "Cannot
+  connect to daemon," run `vexp daemon-cmd start` un-sandboxed and wait for "Socket ready"
+  (first start loads the local LLM, so allow >12s).
+
+If you're unsure whether an action would violate one of the above, stop and ask before
+acting.
diff --git a/docs/decisions.md b/docs/decisions.md
index 94cdf5f..1e80a48 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,18 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-31 — Adopt four homelab-configs standards; flip commits to Conventional-Commits prefixes
+
+**Decision**: Adopt `code-checkin-and-pr @ v1.1.0`, upgrade `handoff-prompt-workflow` to `v1.5.0`, adopt `repo-sandbox-permissions @ v1.0.0` (repo-wide), and formalize `vexp-context-engine @ v2.1.0`. All four are pinned in the new root `standards.md`. As part of `code-checkin-and-pr`, commit messages now **require** Conventional-Commits prefixes (`feat:` / `fix:` / `chore:` / `docs:`).
+
+**Why**: The standards' adoption was incomplete and undocumented — only `handoff-prompt-workflow @ 1.0.0` was in the registry, `standards.md` didn't exist, and vexp was wired with drift (guard hook untracked, stale custom snippet). `standards.md` + verbatim CLAUDE-snippets make conformance auditable in-repo.
+
+**The reversal**: `CLAUDE.md` previously said *"No conventional-commits prefixes."* This directly contradicted `code-checkin-and-pr`, which mandates them. We chose to flip the convention (adopt prefixes) rather than record a permanent deviation, so the standard is implemented cleanly. The "No co-author tags" rule is unchanged — it matches the standard.
+
+**Considered**: (a) Keep no-prefix commits and document a partial-adoption deviation in `standards.md` Notes — rejected; a deviation on the standard's most visible rule undercuts the point of adopting it. (b) Add an Alembic migration system to satisfy CI check #3 — rejected as out of scope; the app uses raw SQLite, so the migration check is marked **N/A** in `standards.md`.
+
+**Revisit if**: the project gains a migration system (wire CI check #3 then), or the GPU offload for vexp's local LLM is provisioned on this host (update the `vexp-context-engine` Notes row from CPU-only).
+
 ## 2026-05-26 — Printer↔label compatibility is library-derived, computed at catalog load; `printer_requirements` deprecated
 
 **Decision**: A label's printability on the configured printer is computed at catalog load from primitive `brother_ql` fields, not declared in `labels.yml`. Each catalog entry gains `restricted_to_models` (`Label.restricted_to_models`), `color` (`Label.color`), a computed `supported: bool`, and `incompatible_reason: str | None`. The rule:
diff --git a/prompts/TEMPLATE.md b/prompts/TEMPLATE.md
new file mode 100644
index 0000000..ba43b8f
--- /dev/null
+++ b/prompts/TEMPLATE.md
@@ -0,0 +1,50 @@
+---
+name: YYYY-MM-DD-short-description
+status: pending          # pending | completed | failed
+created: YYYY-MM-DD
+model:                   # opus = research/planning, sonnet = coding
+completed:               # filled when the work is done
+result:                  # one-line summary of the outcome
+---
+
+# Task: <short imperative title>
+
+<One or two sentences: what this task accomplishes and why.>
+
+## Before you start
+
+- <Docs to read first / conventions to match.>
+- <Constraints — paths come from host-paths.md, map-not-copy, etc.>
+
+## Working tree check
+
+Before making any edits, run `git status --porcelain` and cross-reference the files
+this plan needs to modify. If any of those files have uncommitted changes, list them
+and ask the user before touching them. Surface unrelated dirty files once as
+awareness; don't block. This file (the handoff prompt itself) is exempt — it's
+expected to be modified by "When done" below.
+
+## What to do
+
+1. <Step.>
+2. <Step.>
+
+## Conventions to honor
+
+- <Style / structure / changelog expectations.>
+
+## When done
+
+1. Update this file's frontmatter: set `status` (completed/failed), `completed` (the
+   date), and `result` (one line).
+2. `git mv` this file into `prompts/done/` (on success) or `prompts/failed/` (on
+   failure). Create the subdir if it doesn't exist yet.
+3. Record any non-obvious decisions in the project's `docs/decisions.md`.
+4. Propose ONE commit covering the files this session modified (including the prompt
+   move). Present the file list and a one-line message summarising the changes; ask
+   `commit these as "<message>"? (y/n)`. On `y`, stage those specific paths and
+   commit on the current branch. Never `git add -A`. Never push. By default the
+   message is a plain one-liner and the branch is whatever the session is on. **Only
+   if** the project also adopts `code-checkin-and-pr` do its branch rules (`dev`,
+   never `main`) and commit-prefix conventions (`feat:` / `fix:` / `chore:` /
+   `docs:`, no `Co-authored-by:`) apply on top.
diff --git a/prompts/2026-05-25-template-recall-ui.md b/prompts/done/2026-05-25-template-recall-ui.md
similarity index 100%
rename from prompts/2026-05-25-template-recall-ui.md
rename to prompts/done/2026-05-25-template-recall-ui.md
diff --git a/prompts/2026-05-26-printer-label-compatibility.md b/prompts/done/2026-05-26-printer-label-compatibility.md
similarity index 100%
rename from prompts/2026-05-26-printer-label-compatibility.md
rename to prompts/done/2026-05-26-printer-label-compatibility.md
diff --git a/standards.md b/standards.md
new file mode 100644
index 0000000..869afcd
--- /dev/null
+++ b/standards.md
@@ -0,0 +1,14 @@
+# Standards implemented
+
+This project implements the following [standards](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards)
+from the crzynet `homelab-configs` repo. Each row pins the **version** that this project
+has actually wired up. This file is the in-repo source of truth for "what does this
+codebase conform to" — `CLAUDE.md` points here and the per-session operational rules from
+snippet-bearing standards are pasted verbatim into `CLAUDE.md`.
+
+| Standard | Version | Adopted | Notes |
+|---|---|---|---|
+| [code-checkin-and-pr](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/code-checkin-and-pr/README.md) | 1.1.0 | 2026-05-31 | Full adoption. CI (`ci.yml`) covers backend lint (ruff/mypy/pytest), structured-config validation, `docker compose config`, and PR-only image build; publish matrix (`build-and-push.yml`) + retention (`cleanup-images.yml`) already in place. **Migration check N/A** — no migration system (raw SQLite via `backend/labelforge/db.py`). Commit-prefix convention flipped to Conventional-Commits per ADR 2026-05-31. CLAUDE-snippet pasted verbatim into `CLAUDE.md`. |
+| [handoff-prompt-workflow](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/handoff-prompt-workflow/README.md) | 1.5.0 | 2026-05-31 | Upgraded from v1.0.0. Origin project for this standard. `prompts/` is the live queue; completed prompts archived under `prompts/done/`; `prompts/TEMPLATE.md` added; frontmatter gained `model:`; working-tree check + single-commit-with-ask + launch-command form reflected in `CLAUDE.md`. |
+| [repo-sandbox-permissions](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/repo-sandbox-permissions/README.md) | 1.0.0 | 2026-05-31 | scope: **repo-wide** (`.claude/settings.json`), 2026-05-31. `allowedDomains` = localhost + pypi/files.pythonhosted + registry.npmjs (Python + Node stack); `allowWrite` = `/tmp/**`, `~/.cache/**` (covers uv/ruff/mypy), `~/.npm/**`. `bubblewrap` + `socat` installed on this host. **Restart Claude Code** to activate (`sandbox.enabled` is read at startup). |
+| [vexp-context-engine](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/vexp-context-engine/README.md) | 2.1.0 | 2026-05-31 | Shape B — `.vexp/manifest.json` intentionally not tracked (each host owns its index). Guard hook `.claude/hooks/vexp-guard.sh` now tracked; vexp's auto-generated `.claude/CLAUDE.md` untracked (verbatim snippet lives in `CLAUDE.md`); `.vexpignore` added. Verify (2026-05-31): MCP `index_status` healthy — repo indexed (486 nodes / 448 edges, 0 stale); LLM `Operational: true`. **GPU offload NOT enabled** (CPU backend only) although `/usr/lib/wsl/lib/libcuda.so.1` is present and a GPU appears installed — missing `libggml-cuda.so` is host-side drift for the Ansible vexp role to fix; CPU fallback remains conformant. |

From d5fc08fe0130e4c33ad811fad7c2a605f4d3d734 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 10:29:22 -0700
Subject: [PATCH 45/84] =?UTF-8?q?feat:=20add=20print=20history=20API=20?=
 =?UTF-8?q?=E2=80=94=20preview=20on=20every=20print,=20reprint,=20pin,=20r?=
 =?UTF-8?q?etention=20pruning?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every print path (quick, template, batch) now persists a preview PNG under
${DATA_DIR}/label-previews/{job_id}.png via a shared insert_job_with_preview()
helper. Six new /api/history routes: paginated list (with template/pinned/date
filters), detail, preview.png, reprint (creates new row with reprint_of link),
pin toggle, and delete. Retention pruning (forever/last_n/last_days) runs at
startup and every 6 hours; pinned rows are never pruned; VACUUM fires when
>10% of rows are pruned. ADR recorded for file-on-disk preview storage.
---
 CHANGELOG.md                                  |   1 +
 backend/labelforge/db.py                      |   2 +
 backend/labelforge/history.py                 | 141 ++++++++++
 backend/labelforge/main.py                    |  26 +-
 backend/labelforge/models/__init__.py         |  23 ++
 backend/labelforge/routes/history.py          | 251 ++++++++++++++++++
 backend/labelforge/routes/print.py            |  24 +-
 backend/labelforge/routes/template_print.py   |  52 +---
 docs/decisions.md                             |  16 ++
 docs/features/history.md                      |  20 +-
 .../done/2026-05-31-print-history-backend.md  | 171 ++++++++++++
 11 files changed, 665 insertions(+), 62 deletions(-)
 create mode 100644 backend/labelforge/history.py
 create mode 100644 backend/labelforge/routes/history.py
 create mode 100644 prompts/done/2026-05-31-print-history-backend.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 056fe4e..9f91938 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Print history API** — every print is logged with a preview PNG; browse paginated history at `GET /api/history`, fetch full detail at `GET /api/history/{id}`, serve the preview image at `GET /api/history/{id}/preview.png`, reprint a past job at `POST /api/history/{id}/reprint` (creates a new row linked via `reprint_of`), pin/unpin at `POST /api/history/{id}/pin`, and delete at `DELETE /api/history/{id}`. Retention auto-pruning runs at startup and every 6 hours, honoring the `retention_mode` / `retention_count` / `retention_days` settings. Pinned rows are never pruned.
 - **Printer-aware label catalog** — each label now carries a `supported` flag computed at catalog load against the configured printer (`PRINTER_MODEL`). Media the printer physically can't print — wide-format rolls on a non-QL-1xxx printer, two-color rolls on a mono printer — appear in the selectors greyed out, disabled, and marked `— unavailable` with a tooltip explaining why, instead of being silently offered. On the default QL-820NWB the six wide-format rolls (`102`, `103`, `104`, `102x51`, `102x152`, `103x164`) are now disabled; `62red` stays selectable. Compatibility is derived from the `brother_ql` library, not hand-maintained — the `printer_requirements` field in `labels.yml` is deprecated and ignored.
 - **Brother DK part numbers in label selectors** — the label-media dropdown (quick-print and the new-template modal) now shows the part number with the name, e.g. `DK-2205: 62mm Continuous (Black)`; entries without a part number show the name alone. Backfilled `brother_part` for 9 more default catalog entries (14 of 15 now carry a part number; `52x29` has no consumer DK roll). Grouping/formatting moved into a shared `frontend/src/labels.ts` helper.
 - **Template recall UI** — fill variable fields, preview, and print from saved templates at `/templates/{name}/print`; batch printing with auto-increment for numeric fields
diff --git a/backend/labelforge/db.py b/backend/labelforge/db.py
index d80b377..aeea210 100644
--- a/backend/labelforge/db.py
+++ b/backend/labelforge/db.py
@@ -45,6 +45,8 @@ def _migrate_print_jobs(conn: sqlite3.Connection) -> None:
         conn.execute("ALTER TABLE print_jobs ADD COLUMN field_values TEXT NULL")
     if "batch_id" not in existing:
         conn.execute("ALTER TABLE print_jobs ADD COLUMN batch_id TEXT NULL")
+    if "reprint_of" not in existing:
+        conn.execute("ALTER TABLE print_jobs ADD COLUMN reprint_of INTEGER NULL")
     conn.commit()
 
 
diff --git a/backend/labelforge/history.py b/backend/labelforge/history.py
new file mode 100644
index 0000000..ef2f556
--- /dev/null
+++ b/backend/labelforge/history.py
@@ -0,0 +1,141 @@
+import io
+import json
+import logging
+
+from PIL import Image
+
+from labelforge import settings_store
+from labelforge.config import settings
+from labelforge.db import get_connection
+from labelforge.printer.client import to_print_bitmap
+
+logger = logging.getLogger(__name__)
+
+
+def insert_job_with_preview(
+    image: Image.Image,
+    payload_json: str,
+    label_media: str,
+    template_name: str | None = None,
+    field_values: dict | None = None,
+    batch_id: str | None = None,
+    reprint_of: int | None = None,
+) -> int:
+    db_path = settings.data_dir / "data" / "app.db"
+    conn = get_connection(db_path)
+    try:
+        cursor = conn.execute(
+            """INSERT INTO print_jobs
+               (template_id, payload_json, label_media, field_values, batch_id, reprint_of)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (
+                template_name,
+                payload_json,
+                label_media,
+                json.dumps(field_values) if field_values is not None else None,
+                batch_id,
+                reprint_of,
+            ),
+        )
+        conn.commit()
+        job_id = cursor.lastrowid
+    finally:
+        conn.close()
+
+    _save_preview(job_id, image)
+    return job_id
+
+
+def _save_preview(job_id: int, image: Image.Image) -> None:
+    try:
+        previews_dir = settings.data_dir / "label-previews"
+        previews_dir.mkdir(parents=True, exist_ok=True)
+        buf = io.BytesIO()
+        to_print_bitmap(image).save(buf, format="PNG")
+        (previews_dir / f"{job_id}.png").write_bytes(buf.getvalue())
+
+        db_path = settings.data_dir / "data" / "app.db"
+        conn = get_connection(db_path)
+        try:
+            conn.execute(
+                "UPDATE print_jobs SET preview_path = ? WHERE id = ?",
+                (f"{job_id}.png", job_id),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+    except Exception:
+        logger.warning("Failed to save preview for job %d", job_id, exc_info=True)
+
+
+def prune_history() -> None:
+    try:
+        mode = settings_store.get("retention_mode")
+        if mode == "forever":
+            return
+
+        db_path = settings.data_dir / "data" / "app.db"
+        conn = get_connection(db_path)
+        try:
+            total = conn.execute("SELECT COUNT(*) FROM print_jobs").fetchone()[0]
+
+            if mode == "last_n":
+                count = settings_store.get("retention_count")
+                rows = conn.execute(
+                    """SELECT id, preview_path FROM print_jobs
+                       WHERE pinned = 0
+                       AND id NOT IN (
+                           SELECT id FROM print_jobs WHERE pinned = 0
+                           ORDER BY created_at DESC, id DESC
+                           LIMIT ?
+                       )""",
+                    (count,),
+                ).fetchall()
+            elif mode == "last_days":
+                days = settings_store.get("retention_days")
+                rows = conn.execute(
+                    """SELECT id, preview_path FROM print_jobs
+                       WHERE pinned = 0
+                       AND created_at < datetime('now', ?)""",
+                    (f"-{days} days",),
+                ).fetchall()
+            else:
+                return
+
+            if not rows:
+                return
+
+            ids = [r["id"] for r in rows]
+            preview_paths = [r["preview_path"] for r in rows if r["preview_path"]]
+            pruned = len(ids)
+            db_size_before = db_path.stat().st_size if db_path.exists() else 0
+
+            conn.execute(
+                f"DELETE FROM print_jobs WHERE id IN ({','.join('?' * pruned)})",  # noqa: S608
+                ids,
+            )
+            conn.commit()
+
+            previews_dir = settings.data_dir / "label-previews"
+            for fname in preview_paths:
+                try:
+                    (previews_dir / fname).unlink(missing_ok=True)
+                except Exception:
+                    logger.warning("Could not delete preview file %s", fname, exc_info=True)
+
+            if total > 0 and pruned / total > 0.1:
+                logger.info("Running VACUUM after pruning %.0f%% of rows", 100 * pruned / total)
+                try:
+                    conn.execute("VACUUM")
+                except Exception:
+                    logger.warning("VACUUM failed", exc_info=True)
+
+            db_size_after = db_path.stat().st_size if db_path.exists() else 0
+            logger.info(
+                "prune_history: pruned %d rows (mode=%s), DB %d → %d bytes",
+                pruned, mode, db_size_before, db_size_after,
+            )
+        finally:
+            conn.close()
+    except Exception:
+        logger.error("prune_history failed", exc_info=True)
diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index afd9349..16d4bc4 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -1,3 +1,4 @@
+import asyncio
 import logging
 import shutil
 from contextlib import asynccontextmanager
@@ -7,11 +8,13 @@
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
 
+from labelforge import history as history_module
 from labelforge.catalog.loader import load_catalog
 from labelforge.config import settings
 from labelforge.db import init_db
 from labelforge.render.fonts import load_fonts
 from labelforge.routes import fonts, health, labels
+from labelforge.routes import history as history_router
 from labelforge.routes import print as print_router
 from labelforge.routes import preview as preview_router
 from labelforge.routes import settings as settings_router
@@ -50,8 +53,28 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
     load_catalog(yml_path)
     load_fonts(data_dir / "fonts")
 
+    try:
+        history_module.prune_history()
+    except Exception:
+        logger.error("Startup retention pruning failed", exc_info=True)
+
+    async def _retention_loop() -> None:
+        while True:
+            await asyncio.sleep(6 * 3600)
+            try:
+                history_module.prune_history()
+            except Exception:
+                logger.error("Scheduled retention pruning failed", exc_info=True)
+
+    retention_task = asyncio.create_task(_retention_loop())
+
     yield
-    # Nothing to clean up on shutdown.
+
+    retention_task.cancel()
+    try:
+        await retention_task
+    except asyncio.CancelledError:
+        pass
 
 
 app = FastAPI(
@@ -69,6 +92,7 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
 app.include_router(settings_router.router, prefix="/api")
 app.include_router(templates_router.router, prefix="/api")
 app.include_router(template_print_router.router, prefix="/api")
+app.include_router(history_router.router, prefix="/api")
 
 _FRONTEND_DIST = Path("/app/frontend/dist")
 
diff --git a/backend/labelforge/models/__init__.py b/backend/labelforge/models/__init__.py
index a564b31..b4636c7 100644
--- a/backend/labelforge/models/__init__.py
+++ b/backend/labelforge/models/__init__.py
@@ -109,3 +109,26 @@ class BatchPrintResponse(BaseModel):
     jobs: list[BatchJobResult]
     succeeded: int
     failed: int
+
+
+# ── History ───────────────────────────────────────────────────────────────────
+
+class HistoryItem(BaseModel):
+    id: int
+    template_id: str | None
+    is_quick_print: bool
+    field_values: dict | None
+    label_media: str
+    pinned: bool
+    created_at: str
+    reprint_of: int | None
+    batch_id: str | None
+    preview_url: str
+
+
+class HistoryDetail(HistoryItem):
+    payload_json: dict | None
+
+
+class PinRequest(BaseModel):
+    pinned: bool
diff --git a/backend/labelforge/routes/history.py b/backend/labelforge/routes/history.py
new file mode 100644
index 0000000..52612c5
--- /dev/null
+++ b/backend/labelforge/routes/history.py
@@ -0,0 +1,251 @@
+import json
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi.responses import FileResponse, Response
+
+from labelforge.catalog.loader import get_label
+from labelforge.config import settings
+from labelforge.db import get_connection
+from labelforge.history import insert_job_with_preview
+from labelforge.models import HistoryDetail, HistoryItem, PinRequest, QuickPrintRequest
+from labelforge.printer.client import PrintError, print_image
+from labelforge.render.template import render_template
+from labelforge.render.text import RenderError, render_text
+from labelforge.routes.auth import require_auth
+from labelforge.templates import store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+
+def _db_path():
+    return settings.data_dir / "data" / "app.db"
+
+
+def _row_to_item(row) -> HistoryItem:
+    return HistoryItem(
+        id=row["id"],
+        template_id=row["template_id"],
+        is_quick_print=row["template_id"] is None,
+        field_values=json.loads(row["field_values"]) if row["field_values"] else None,
+        label_media=row["label_media"],
+        pinned=bool(row["pinned"]),
+        created_at=row["created_at"],
+        reprint_of=row["reprint_of"],
+        batch_id=row["batch_id"],
+        preview_url=f"/api/history/{row['id']}/preview.png",
+    )
+
+
+def _row_to_detail(row) -> HistoryDetail:
+    item = _row_to_item(row)
+    payload = None
+    if row["payload_json"]:
+        try:
+            payload = json.loads(row["payload_json"])
+        except Exception:
+            pass
+    return HistoryDetail(**item.model_dump(), payload_json=payload)
+
+
+@router.get("/history", response_model=list[HistoryItem])
+async def list_history(
+    limit: int = Query(50, ge=1, le=200),
+    offset: int = Query(0, ge=0),
+    template: str | None = None,
+    pinned: bool | None = None,
+    from_: str | None = Query(default=None, alias="from"),
+    to: str | None = None,
+) -> list[HistoryItem]:
+    sql = "SELECT * FROM print_jobs WHERE 1=1"
+    params: list = []
+    if template is not None:
+        sql += " AND template_id = ?"
+        params.append(template)
+    if pinned is not None:
+        sql += " AND pinned = ?"
+        params.append(1 if pinned else 0)
+    if from_ is not None:
+        sql += " AND created_at >= ?"
+        params.append(from_)
+    if to is not None:
+        sql += " AND created_at <= ?"
+        params.append(to)
+    sql += " ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?"
+    params.extend([limit, offset])
+
+    conn = get_connection(_db_path())
+    try:
+        rows = conn.execute(sql, params).fetchall()  # noqa: S608
+    finally:
+        conn.close()
+    return [_row_to_item(r) for r in rows]
+
+
+@router.get("/history/{job_id}", response_model=HistoryDetail)
+async def get_history(job_id: int) -> HistoryDetail:
+    conn = get_connection(_db_path())
+    try:
+        row = conn.execute("SELECT * FROM print_jobs WHERE id = ?", (job_id,)).fetchone()
+    finally:
+        conn.close()
+    if row is None:
+        raise HTTPException(status_code=404, detail=f"Print job {job_id} not found")
+    return _row_to_detail(row)
+
+
+@router.get("/history/{job_id}/preview.png", response_class=FileResponse)
+async def history_preview(job_id: int) -> Response:
+    conn = get_connection(_db_path())
+    try:
+        row = conn.execute(
+            "SELECT preview_path FROM print_jobs WHERE id = ?", (job_id,)
+        ).fetchone()
+    finally:
+        conn.close()
+    if row is None:
+        raise HTTPException(status_code=404, detail="Print job not found")
+    if not row["preview_path"]:
+        raise HTTPException(status_code=404, detail="Preview not available")
+    preview_file = settings.data_dir / "label-previews" / row["preview_path"]
+    if not preview_file.exists():
+        raise HTTPException(status_code=404, detail="Preview file not found")
+    return FileResponse(str(preview_file), media_type="image/png")
+
+
+@router.post("/history/{job_id}/reprint")
+async def reprint_history(job_id: int) -> dict:
+    conn = get_connection(_db_path())
+    try:
+        row = conn.execute("SELECT * FROM print_jobs WHERE id = ?", (job_id,)).fetchone()
+    finally:
+        conn.close()
+    if row is None:
+        raise HTTPException(status_code=404, detail=f"Print job {job_id} not found")
+
+    if row["template_id"] is not None:
+        return await _reprint_template(job_id, row)
+    return await _reprint_quick(job_id, row)
+
+
+async def _reprint_template(job_id: int, row) -> dict:
+    tmpl = store.get_template(row["template_id"], include_deleted=True)
+    if tmpl is None:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Template '{row['template_id']}' no longer exists and cannot be reprinted",
+        )
+    if get_label(tmpl.label_media) is None:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Label media '{tmpl.label_media}' is no longer in the catalog",
+        )
+    field_values = json.loads(row["field_values"]) if row["field_values"] else {}
+    try:
+        image = render_template(tmpl, field_values)
+    except RenderError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    try:
+        outcome = print_image(
+            image=image,
+            label_media=tmpl.label_media,
+            model=settings.printer_model,
+            backend=settings.printer_backend,
+            host=settings.printer_host,
+        )
+    except PrintError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    new_id = insert_job_with_preview(
+        image=image,
+        payload_json=row["payload_json"],
+        label_media=tmpl.label_media,
+        template_name=row["template_id"],
+        field_values=field_values,
+        reprint_of=job_id,
+    )
+    return {"job_id": new_id, "status": outcome, "reprint_of": job_id}
+
+
+async def _reprint_quick(job_id: int, row) -> dict:
+    try:
+        request = QuickPrintRequest(**json.loads(row["payload_json"]))
+    except Exception as exc:
+        raise HTTPException(
+            status_code=409, detail=f"Cannot reconstruct quick-print request: {exc}"
+        ) from exc
+    if get_label(request.label_media) is None:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Label media '{request.label_media}' is no longer in the catalog",
+        )
+    try:
+        image = render_text(
+            text=request.text,
+            font_name=request.font,
+            font_size=request.font_size,
+            alignment=request.alignment,
+            orientation=request.orientation,
+            bold=request.bold,
+            italic=request.italic,
+            label_media=request.label_media,
+        )
+    except RenderError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    try:
+        outcome = print_image(
+            image=image,
+            label_media=request.label_media,
+            model=settings.printer_model,
+            backend=settings.printer_backend,
+            host=settings.printer_host,
+        )
+    except PrintError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+    new_id = insert_job_with_preview(
+        image=image,
+        payload_json=row["payload_json"],
+        label_media=request.label_media,
+        reprint_of=job_id,
+    )
+    return {"job_id": new_id, "status": outcome, "reprint_of": job_id}
+
+
+@router.post("/history/{job_id}/pin", response_model=HistoryItem)
+async def pin_history(job_id: int, body: PinRequest) -> HistoryItem:
+    conn = get_connection(_db_path())
+    try:
+        if not conn.execute(
+            "SELECT 1 FROM print_jobs WHERE id = ?", (job_id,)
+        ).fetchone():
+            raise HTTPException(status_code=404, detail=f"Print job {job_id} not found")
+        conn.execute(
+            "UPDATE print_jobs SET pinned = ? WHERE id = ?",
+            (1 if body.pinned else 0, job_id),
+        )
+        conn.commit()
+        row = conn.execute("SELECT * FROM print_jobs WHERE id = ?", (job_id,)).fetchone()
+        return _row_to_item(row)
+    finally:
+        conn.close()
+
+
+@router.delete("/history/{job_id}", status_code=204)
+async def delete_history(job_id: int) -> None:
+    conn = get_connection(_db_path())
+    try:
+        row = conn.execute(
+            "SELECT preview_path FROM print_jobs WHERE id = ?", (job_id,)
+        ).fetchone()
+        if row is None:
+            raise HTTPException(status_code=404, detail=f"Print job {job_id} not found")
+        conn.execute("DELETE FROM print_jobs WHERE id = ?", (job_id,))
+        conn.commit()
+    finally:
+        conn.close()
+    if row["preview_path"]:
+        try:
+            (settings.data_dir / "label-previews" / row["preview_path"]).unlink(missing_ok=True)
+        except Exception:
+            logger.warning("Could not delete preview file for job %d", job_id, exc_info=True)
diff --git a/backend/labelforge/routes/print.py b/backend/labelforge/routes/print.py
index 5430582..4a629b6 100644
--- a/backend/labelforge/routes/print.py
+++ b/backend/labelforge/routes/print.py
@@ -4,8 +4,8 @@
 
 from labelforge.catalog.loader import get_label
 from labelforge.config import settings
-from labelforge.db import get_connection
 from labelforge import settings_store
+from labelforge.history import insert_job_with_preview
 from labelforge.models import PrintJobResponse, QuickPrintRequest
 from labelforge.printer.client import PrintError, print_image
 from labelforge.render.text import RenderError, render_text
@@ -49,21 +49,19 @@ async def quick_print(request: QuickPrintRequest) -> PrintJobResponse:
     except PrintError as exc:
         raise HTTPException(status_code=500, detail=str(exc)) from exc
 
-    db_path = settings.data_dir / "data" / "app.db"
-    conn = get_connection(db_path)
-    try:
-        cursor = conn.execute(
-            "INSERT INTO print_jobs (payload_json, label_media) VALUES (?, ?)",
-            (request.model_dump_json(), request.label_media),
-        )
-        conn.commit()
-        job_id = cursor.lastrowid
-    finally:
-        conn.close()
+    job_id = insert_job_with_preview(
+        image=image,
+        payload_json=request.model_dump_json(),
+        label_media=request.label_media,
+    )
 
     try:
         settings_store.set("last_quick_print", request.model_dump())
     except Exception:
         logger.warning("Failed to record last_quick_print", exc_info=True)
 
-    return PrintJobResponse(job_id=job_id, status=outcome)
+    return PrintJobResponse(
+        job_id=job_id,
+        status=outcome,
+        preview_url=f"/api/history/{job_id}/preview.png",
+    )
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index 2d5f52a..b6691b5 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -1,5 +1,4 @@
 import io
-import json
 import logging
 import uuid
 
@@ -7,7 +6,7 @@
 from fastapi.responses import Response
 
 from labelforge.config import settings
-from labelforge.db import get_connection
+from labelforge.history import insert_job_with_preview
 from labelforge.models import (
     BatchJobResult,
     BatchPrintRequest,
@@ -25,10 +24,6 @@
 router = APIRouter(dependencies=[Depends(require_auth)])
 
 
-def _db_path():
-    return settings.data_dir / "data" / "app.db"
-
-
 def _apply_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
     """Return values dict with defaults filled in; raise HTTPException for missing required."""
     result = dict(values)
@@ -44,33 +39,6 @@ def _apply_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
     return result
 
 
-def _insert_job(
-    template_name: str,
-    label_media: str,
-    field_values: dict,
-    request_json: str,
-    batch_id: str | None = None,
-) -> int:
-    conn = get_connection(_db_path())
-    try:
-        cursor = conn.execute(
-            """INSERT INTO print_jobs
-               (template_id, payload_json, label_media, field_values, batch_id)
-               VALUES (?, ?, ?, ?, ?)""",
-            (
-                template_name,
-                request_json,
-                label_media,
-                json.dumps(field_values),
-                batch_id,
-            ),
-        )
-        conn.commit()
-        return cursor.lastrowid
-    finally:
-        conn.close()
-
-
 @router.post("/print/{name}")
 async def print_template(name: str, body: PrintRequest) -> dict:
     tmpl = store.get_template(name)
@@ -95,9 +63,14 @@ async def print_template(name: str, body: PrintRequest) -> dict:
     except PrintError as exc:
         raise HTTPException(status_code=500, detail=str(exc)) from exc
 
-    job_id = _insert_job(name, tmpl.label_media, values, body.model_dump_json())
+    job_id = insert_job_with_preview(
+        image=image,
+        payload_json=body.model_dump_json(),
+        label_media=tmpl.label_media,
+        template_name=name,
+        field_values=values,
+    )
 
-    # preview_url points at the history preview route, which lands in a later slice.
     return {
         "job_id": job_id,
         "status": outcome,
@@ -153,9 +126,12 @@ async def batch_print(name: str, body: BatchPrintRequest) -> BatchPrintResponse:
                 backend=settings.printer_backend,
                 host=settings.printer_host,
             )
-            job_id = _insert_job(
-                name, tmpl.label_media, values,
-                BatchPrintRequest(labels=[label_values]).model_dump_json(),
+            job_id = insert_job_with_preview(
+                image=image,
+                payload_json=BatchPrintRequest(labels=[label_values]).model_dump_json(),
+                label_media=tmpl.label_media,
+                template_name=name,
+                field_values=values,
                 batch_id=batch_id,
             )
             jobs.append(BatchJobResult(job_id=job_id, status=outcome))
diff --git a/docs/decisions.md b/docs/decisions.md
index 1e80a48..cb49701 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,22 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-31 — Print history: preview stored as file on disk, not inline BLOB
+
+**Decision**: Preview images for print history are stored as PNG files under `${DATA_DIR}/label-previews/{job_id}.png`. The `print_jobs.preview_path` column stores the filename (e.g. `"42.png"`); the history preview route resolves the full path at request time. Previews are written after INSERT (job_id is needed for the filename), so rows exist briefly with `preview_path = NULL`. If preview write fails, the row is kept with `preview_path = NULL` and the preview route returns 404 for that job.
+
+**Why the schema already chose this**: The live `print_jobs` schema already had a `preview_path TEXT NULL` column — not a `preview_png BLOB` column. `history.md` specified a BLOB; the live schema diverged (likely because the data-path contract already reserves `label-previews/` and keeping SQLite small is a long-standing goal). Aligning the implementation with the live schema avoids a destructive migration.
+
+**Why files over BLOBs in general**: Keeps the SQLite file small at scale; HTTP serving (FileResponse) is simpler for binary content; preview files can be examined or deleted directly without touching the DB. For a homelab with retention pruning the footprint is bounded.
+
+**Consequence**: `docs/features/history.md` data model updated to reflect `preview_path` (file ref) rather than `preview_png` (BLOB). A missing or deleted preview file returns 404 from the preview route; the frontend should render a placeholder rather than erroring.
+
+**History frontend deferred**: The `/history` page and retention-settings UI are Slice B — not built in this slice.
+
+**Revisit if**: preview files become inconvenient to manage (backup, migration) compared to keeping everything in one SQLite file — at that point a BLOB column is a viable alternative.
+
+---
+
 ## 2026-05-31 — Adopt four homelab-configs standards; flip commits to Conventional-Commits prefixes
 
 **Decision**: Adopt `code-checkin-and-pr @ v1.1.0`, upgrade `handoff-prompt-workflow` to `v1.5.0`, adopt `repo-sandbox-permissions @ v1.0.0` (repo-wide), and formalize `vexp-context-engine @ v2.1.0`. All four are pinned in the new root `standards.md`. As part of `code-checkin-and-pr`, commit messages now **require** Conventional-Commits prefixes (`feat:` / `fix:` / `chore:` / `docs:`).
diff --git a/docs/features/history.md b/docs/features/history.md
index 5161599..d2333f9 100644
--- a/docs/features/history.md
+++ b/docs/features/history.md
@@ -28,20 +28,20 @@ The user can answer:
 ```
 print_jobs
   id                   integer primary key
-  template_id          integer nullable references templates(id)
-  is_quick_print       boolean
-  field_values         text (json)               -- {"number": "047", ...}
-  quick_print_payload  text (json) nullable      -- snapshot for quick prints
+  template_id          text nullable              -- template name (TEXT), null for quick prints
+  payload_json         text                      -- original request JSON snapshot
+  field_values         text (json) nullable      -- {"number": "047", ...}
   label_media          text                      -- snapshot at print time
-  preview_png          blob                      -- the rendered bitmap
-  printer_response     text (json) nullable      -- captured status / error if relevant
-  pinned               boolean default false
-  created_at           timestamp
+  preview_path         text nullable             -- filename under ${DATA_DIR}/label-previews/
+  batch_id             text nullable
+  reprint_of           integer nullable          -- references print_jobs(id) logically
+  pinned               integer default 0
+  created_at           text                      -- ISO 8601, UTC
 ```
 
-`preview_png` stored inline as a BLOB. Size: for a typical 62×100 label at 300dpi, ~30-100KB. SQLite handles this fine; a million prints would be ~50GB. We're nowhere near that and retention prunes long before.
+**Note**: `template_id` stores the template *name* (TEXT), not a numeric id. `is_quick_print` is derived: `template_id IS NULL`.
 
-If preview size becomes a concern later, move to a file-on-disk strategy keyed by job_id. Not a v1 problem.
+Preview images are stored as PNG files under `${DATA_DIR}/label-previews/{id}.png` (file-on-disk, not a BLOB — see ADR 2026-05-31). `preview_path` stores the filename only; the preview route resolves the full path. A NULL or missing `preview_path` means the preview is unavailable — the route returns 404 and the frontend should render a placeholder.
 
 ## Reprint
 
diff --git a/prompts/done/2026-05-31-print-history-backend.md b/prompts/done/2026-05-31-print-history-backend.md
new file mode 100644
index 0000000..00cd5f5
--- /dev/null
+++ b/prompts/done/2026-05-31-print-history-backend.md
@@ -0,0 +1,171 @@
+---
+name: 2026-05-31-print-history-backend
+status: completed
+created: 2026-05-31
+model: sonnet            # opus = research/planning, sonnet = coding
+completed: 2026-05-31
+result: History API backend live — preview-on-every-print, 6 routes, retention pruning every 6 hours
+---
+
+# Task: Print history backend (list, reprint, pin, retention)
+
+Build the **backend** half of the History feature: persist a preview for every print,
+expose the `/api/history` routes (list, detail, preview PNG, reprint, pin, delete), and
+run retention pruning on a schedule. This closes v1 success criteria 6 (reprint) and 7
+(pin) at the API level. **No frontend in this slice** — the `/history` page and retention
+settings UI are a separate follow-up (Slice B).
+
+## Before you start
+
+- Read `docs/features/history.md` (the design) and `docs/features/settings.md` (retention
+  is configured there). Read `CLAUDE.md` "Code check-in" + "Session workflow".
+- This repo uses **vexp**: call `run_pipeline` first for context; prefer `get_skeleton`
+  over `Read`. Do not grep/glob (guard hook blocks it).
+- Stack facts you can rely on (already verified during planning):
+  - Print rows are written today by `backend/labelforge/routes/print.py` (quick) and
+    `backend/labelforge/routes/template_print.py` (`/print/{name}` and `/print/{name}/batch`).
+    Both currently leave `preview_path` NULL.
+  - `print_jobs` columns today: `id, template_id, payload_json, label_media, preview_path,
+    pinned, created_at, field_values, batch_id`. **Gotcha:** `template_id` stores the
+    template *name* (TEXT), not a numeric id. `field_values` is JSON. `payload_json` is the
+    original request JSON.
+  - Schema + idempotent migrations live in `backend/labelforge/db.py`
+    (`_migrate_print_jobs`). Add new columns there, never with a fresh CREATE.
+  - Rendering: `render_text(...)` and `render_template(tmpl, values)` both return a PIL
+    `Image`. `to_print_bitmap(image)` (in `printer/client.py`) is the canonical PNG path —
+    the existing preview routes already `to_print_bitmap(image).save(buf, "PNG")`.
+  - Retention **settings keys already exist** in `settings_store._REGISTRY`:
+    `retention_mode` (`forever` | `last_n` | `last_days`), `retention_count` (default 500),
+    `retention_days` (default 90). Consume them; do **not** redefine.
+  - Preview files go under `${DATA_DIR}/label-previews/` (per CLAUDE.md data-path
+    contract). `settings.data_dir` is a `Path`.
+  - Routers are registered in `backend/labelforge/main.py` via `app.include_router(...,
+    prefix="/api")`. The app lifespan there is the place to start the retention task.
+  - There is **no test suite**. Verify manually with `curl` (see "Verify").
+
+## Working tree check
+
+Before editing, run `git status --porcelain` and cross-reference the files below. If any
+have uncommitted changes, list them and ask before touching. This prompt file is exempt.
+Files this plan modifies/creates:
+- `backend/labelforge/db.py` (add `reprint_of` column)
+- `backend/labelforge/routes/print.py`, `routes/template_print.py` (persist preview)
+- `backend/labelforge/routes/history.py` (new)
+- `backend/labelforge/history.py` or similar shared helper (new — see step 2)
+- `backend/labelforge/main.py` (register router + start retention task)
+- `backend/labelforge/models/__init__.py` (history response models)
+- `CHANGELOG.md`, `docs/decisions.md`
+
+## What to do
+
+### 1. Schema: add `reprint_of`
+In `db.py::_migrate_print_jobs`, idempotently add `reprint_of INTEGER NULL` (references
+`print_jobs(id)` logically; no FK needed). Keep the existing column-add pattern.
+
+### 2. Persist a preview on every print
+Decision (already made — see ADR step): store previews as **files on disk**, not BLOBs.
+Add a small shared helper (e.g. `backend/labelforge/history.py`) used by all three print
+paths so the insert+preview logic isn't duplicated:
+
+- After a successful `print_image(...)`, persist the row, then write the preview PNG.
+- `job_id` is only known after INSERT, so: INSERT (preview_path NULL) → get `job_id` →
+  write `to_print_bitmap(image)` to `${DATA_DIR}/label-previews/{job_id}.png` → UPDATE the
+  row's `preview_path` with the path (store a path relative to `data_dir`, or just the
+  filename — pick one and be consistent; the preview route resolves it back).
+- Create `${DATA_DIR}/label-previews/` on demand (mkdir parents, exist_ok).
+- Wire this into `routes/print.py` (quick), and both `_insert_job` call sites in
+  `routes/template_print.py` (single + batch). Refactor `_insert_job` to go through the
+  shared helper rather than duplicating the SQL. Keep behavior identical otherwise.
+- If preview write fails, log a warning but do **not** fail the print (the label already
+  printed). Row keeps `preview_path` NULL → list/detail handle missing preview gracefully.
+
+### 3. New `routes/history.py` (register in `main.py`, `prefix="/api"`)
+All routes require auth (`Depends(require_auth)`), matching the other routers. Newest
+first (`ORDER BY created_at DESC, id DESC`).
+
+- `GET /api/history?limit=50&offset=0&template={name}&pinned={true|false}&from={iso}&to={iso}`
+  — paginated list. Each item: `id, template_id` (name or null), `is_quick_print`
+  (derive: `template_id IS NULL`), `field_values` (parsed), `label_media`, `pinned`,
+  `created_at`, `reprint_of`, `batch_id`, `preview_url` = `/api/history/{id}/preview.png`.
+  Do not inline the image bytes in the list response. Clamp `limit` (e.g. 1..200).
+- `GET /api/history/{job_id}` — full detail (same fields + `payload_json` parsed). 404 if
+  absent.
+- `GET /api/history/{job_id}/preview.png` — `FileResponse` of the stored file. If the row
+  or file is missing, return 404 (the frontend renders a placeholder). Never 500 on a
+  missing preview.
+- `POST /api/history/{job_id}/reprint` — re-execute the original print and insert a **new**
+  row with `reprint_of = job_id`:
+  - Template rows (`template_id` not null): look up the template by name **ignoring
+    `deleted_at`** (reprint must work for soft-deleted templates), re-render with the
+    stored `field_values`, print. If the template row is truly gone (hard-deleted), 409
+    with a clear message. If `label_media` is no longer in the catalog, 409 with a warning
+    message (frontend will offer override later; backend just refuses cleanly for now).
+  - Quick rows: rebuild `QuickPrintRequest` from `payload_json` and re-run the quick-print
+    render+print.
+  - Reuse the shared helper from step 2 so the reprint also gets a fresh preview.
+- `POST /api/history/{job_id}/pin` — body `{"pinned": true|false}`; update the row; 404 if
+  absent; return the updated row.
+- `DELETE /api/history/{job_id}` — delete the row **and** its preview file (best-effort
+  unlink). 404 if absent; 204 on success.
+
+Add the Pydantic response models to `models/__init__.py` (e.g. `HistoryItem`,
+`HistoryDetail`, `PinRequest`) following the existing model style.
+
+### 4. Retention pruning (background task)
+Add a `prune_history()` function (in the shared helper module) that:
+- Reads `retention_mode` / `retention_count` / `retention_days` from `settings_store`.
+- `forever` → no-op. `last_n` → keep the `retention_count` most recent **unpinned** rows,
+  delete older unpinned. `last_days` → delete unpinned rows older than `retention_days`.
+- **Pinned rows are never pruned**, regardless of mode.
+- Delete the preview files for pruned rows (best-effort).
+- If >10% of total rows were pruned, run `VACUUM` afterward.
+- Log: count pruned, DB file size before/after.
+
+Run it once at startup (in `main.py` lifespan, after `init_db`) and then every 6 hours via
+an `asyncio` task created in the lifespan; cancel the task cleanly on shutdown (after
+`yield`). Keep it defensive — a pruning error must not crash the app; log and continue.
+
+### Out of scope (do NOT build here)
+- Any frontend (`/history` page, retention settings UI) — that's Slice B.
+- "Use as starting point for new template" — touches the editor; deferred with the QR /
+  canvas-elements work.
+
+## Conventions to honor
+
+- Match surrounding code style (raw `sqlite3` via `get_connection`, `APIRouter` with
+  `Depends(require_auth)`, Pydantic v2 models). One connection per operation, `finally:
+  conn.close()` like the existing routes.
+- Changelog: add a concise, user-facing entry under `## [Unreleased]` → `### Added`
+  ("Print history API — browse, reprint, pin, and auto-prune past prints…"). Doc + code in
+  the **same commit**.
+- Commit on `dev`, Conventional-Commits prefix `feat:`, no `Co-authored-by:` trailers,
+  never push, never `git add -A`.
+
+## Verify
+
+There's no test suite, so verify by hand (the planning owner runs the printer):
+```
+cd backend && uvicorn labelforge.main:app --reload   # or use compose.dev.yml on :8001
+# with $API_TOKEN exported:
+curl -s -H "Authorization: Bearer $API_TOKEN" localhost:8000/api/history | jq
+curl -s -H "Authorization: Bearer $API_TOKEN" localhost:8000/api/history/1 | jq
+curl -s -H "Authorization: Bearer $API_TOKEN" -X POST localhost:8000/api/history/1/pin -d '{"pinned":true}' -H 'content-type: application/json'
+# reprint requires a reachable printer; confirm a new row appears with reprint_of set.
+```
+Leave a one-line "run this to verify" in your final summary.
+
+## When done
+
+1. Update this file's frontmatter: `status` (completed/failed), `completed` (date),
+   `result` (one line).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record non-obvious decisions in `docs/decisions.md` as ADR entries — at minimum:
+   - **Preview storage = file-on-disk** (`${DATA_DIR}/label-previews/{job_id}.png`),
+     diverging from `history.md` which specified an inline `preview_png` BLOB. Rationale:
+     the live schema already chose `preview_path`, the data-path contract already reserves
+     `label-previews/`, and files keep the SQLite DB small. Update `docs/features/history.md`
+     to match (or note the divergence).
+   - History frontend + "use as starting point" deferred to a later slice.
+4. Propose ONE commit covering the modified files (including this prompt's move). Present
+   the file list + a one-line `feat:` message and ask `commit these as "<message>"? (y/n)`.
+   On `y`, stage those specific paths and commit on `dev`. Never push.

From bb2f2a88661ce78da1c2d524a2e0c70ac4153fa6 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 10:42:26 -0700
Subject: [PATCH 46/84] feat: add print history page and retention settings UI

---
 CHANGELOG.md                                |   1 +
 docs/decisions.md                           |  22 ++
 frontend/index.html                         |   2 +
 frontend/src/api.ts                         |  46 +++-
 frontend/src/main.ts                        |   4 +
 frontend/src/pages/history.ts               | 240 ++++++++++++++++++++
 frontend/src/pages/settings.ts              | 109 +++++++++
 frontend/src/style.css                      | 215 ++++++++++++++++++
 frontend/src/types.ts                       |  23 ++
 prompts/done/2026-05-31-print-history-ui.md | 129 +++++++++++
 10 files changed, 790 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/pages/history.ts
 create mode 100644 frontend/src/pages/settings.ts
 create mode 100644 prompts/done/2026-05-31-print-history-ui.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f91938..05708af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Print history page** — browse, reprint, pin, and delete past prints at `/history`; paginated reverse-chronological list with authenticated thumbnail previews, template/quick-print labels, field-value display, and filters (by template name, pinned-only toggle). Reprint creates a new job and refreshes the list; a 409 (template or media gone) surfaces the server's error message. Delete requires confirmation. Pin toggle updates inline without a reload. Retention policy configurable in `/settings` (keep forever / last N / last N days); pinned prints are never pruned; "Run cleanup now" triggers an immediate prune.
 - **Print history API** — every print is logged with a preview PNG; browse paginated history at `GET /api/history`, fetch full detail at `GET /api/history/{id}`, serve the preview image at `GET /api/history/{id}/preview.png`, reprint a past job at `POST /api/history/{id}/reprint` (creates a new row linked via `reprint_of`), pin/unpin at `POST /api/history/{id}/pin`, and delete at `DELETE /api/history/{id}`. Retention auto-pruning runs at startup and every 6 hours, honoring the `retention_mode` / `retention_count` / `retention_days` settings. Pinned rows are never pruned.
 - **Printer-aware label catalog** — each label now carries a `supported` flag computed at catalog load against the configured printer (`PRINTER_MODEL`). Media the printer physically can't print — wide-format rolls on a non-QL-1xxx printer, two-color rolls on a mono printer — appear in the selectors greyed out, disabled, and marked `— unavailable` with a tooltip explaining why, instead of being silently offered. On the default QL-820NWB the six wide-format rolls (`102`, `103`, `104`, `102x51`, `102x152`, `103x164`) are now disabled; `62red` stays selectable. Compatibility is derived from the `brother_ql` library, not hand-maintained — the `printer_requirements` field in `labels.yml` is deprecated and ignored.
 - **Brother DK part numbers in label selectors** — the label-media dropdown (quick-print and the new-template modal) now shows the part number with the name, e.g. `DK-2205: 62mm Continuous (Black)`; entries without a part number show the name alone. Backfilled `brother_part` for 9 more default catalog entries (14 of 15 now carry a part number; `52x29` has no consumer DK roll). Grouping/formatting moved into a shared `frontend/src/labels.ts` helper.
diff --git a/docs/decisions.md b/docs/decisions.md
index cb49701..65db4ca 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,28 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-31 — History UI: authed image loading via fetch+objectURL
+
+**Decision**: `/api/history/{id}/preview.png` requires a bearer token, so `<img src="...">` bare URLs 401. The history page fetches previews via `fetch()` with the `Authorization` header, creates an object URL via `URL.createObjectURL(blob)`, and sets that as `img.src`. Object URLs are revoked on page remount and on filter/pagination resets via a generation counter that skips stale async completions.
+
+**Why**: Matches the existing pattern used by `previewQuick` and `previewTemplate` in `api.ts`. Keeps the token out of query strings (which appear in server logs and browser history).
+
+**Considered**: Embedding tokens in query strings (`?token=...`) — rejected (leaks credential). Server-side session cookies — out of scope (auth is a single bearer token).
+
+**Revisit if**: The session adopts cookie-based auth, at which point `<img src>` works without a fetch wrapper.
+
+---
+
+## 2026-05-31 — History UI: "Load more" pagination over prev/next
+
+**Decision**: The `/history` page uses a "Load more" button (appending to the list) rather than prev/next page navigation.
+
+**Why**: Simpler DOM management; no need to track current page number or re-render the full list on page change. Works well with the "most recent first" order where users typically care about the top of the list.
+
+**Revisit if**: The history list grows large enough that scrolling becomes painful, at which point a fixed-size window with prev/next would be preferable.
+
+---
+
 ## 2026-05-31 — Print history: preview stored as file on disk, not inline BLOB
 
 **Decision**: Preview images for print history are stored as PNG files under `${DATA_DIR}/label-previews/{job_id}.png`. The `print_jobs.preview_path` column stores the filename (e.g. `"42.png"`); the history preview route resolves the full path at request time. Previews are written after INSERT (job_id is needed for the filename), so rows exist briefly with `preview_path = NULL`. If preview write fails, the row is kept with `preview_path = NULL` and the preview route returns 404 for that job.
diff --git a/frontend/index.html b/frontend/index.html
index bd6a74f..0bf7e1b 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -9,6 +9,8 @@
     <nav id="nav">
       <a href="/" data-route="/">Quick Print</a>
       <a href="/templates" data-route="/templates">Templates</a>
+      <a href="/history" data-route="/history">History</a>
+      <a href="/settings" data-route="/settings">Settings</a>
     </nav>
     <div id="app"></div>
     <script type="module" src="/src/main.ts"></script>
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index a333170..4beea95 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -1,4 +1,4 @@
-import type { BatchPrintResponse, FontInfo, LabelEntry, PrintJobResponse, QuickPrintRequest, Template, TemplateCreate } from './types'
+import type { BatchPrintResponse, FontInfo, HistoryDetail, HistoryItem, LabelEntry, PrintJobResponse, QuickPrintRequest, ReprintResponse, Template, TemplateCreate } from './types'
 
 export const TOKEN_KEY = 'labelforge_token'
 
@@ -23,6 +23,7 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
     } catch { /* use status fallback */ }
     throw new Error(detail)
   }
+  if (res.status === 204) return undefined as T
   return res.json() as Promise<T>
 }
 
@@ -121,6 +122,49 @@ export function batchPrint(name: string, labels: Record<string, string>[]): Prom
   })
 }
 
+export function listHistory(params: Record<string, string>): Promise<HistoryItem[]> {
+  const qs = new URLSearchParams(params).toString()
+  return apiFetch<HistoryItem[]>(`/api/history${qs ? '?' + qs : ''}`)
+}
+
+export function getHistory(id: number): Promise<HistoryDetail> {
+  return apiFetch<HistoryDetail>(`/api/history/${id}`)
+}
+
+export async function fetchHistoryPreview(id: number): Promise<Blob> {
+  const res = await fetch(`/api/history/${id}/preview.png`, {
+    headers: { Authorization: `Bearer ${getToken()}` },
+  })
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`
+    try {
+      const body = await res.json() as { detail?: unknown }
+      if (body.detail) detail = String(body.detail)
+    } catch { /* use status fallback */ }
+    throw new Error(detail)
+  }
+  return res.blob()
+}
+
+export function reprintHistory(id: number): Promise<ReprintResponse> {
+  return apiFetch<ReprintResponse>(`/api/history/${id}/reprint`, { method: 'POST' })
+}
+
+export function pinHistory(id: number, pinned: boolean): Promise<HistoryItem> {
+  return apiFetch<HistoryItem>(`/api/history/${id}/pin`, {
+    method: 'POST',
+    body: JSON.stringify({ pinned }),
+  })
+}
+
+export function deleteHistory(id: number): Promise<void> {
+  return apiFetch<void>(`/api/history/${id}`, { method: 'DELETE' })
+}
+
+export function pruneHistory(): Promise<Record<string, unknown>> {
+  return apiFetch<Record<string, unknown>>('/api/admin/prune-history', { method: 'POST' })
+}
+
 export function getSettings(): Promise<Record<string, unknown>> {
   return apiFetch<Record<string, unknown>>('/api/settings')
 }
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index db29e66..2f6e46a 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -3,6 +3,8 @@ import { mountQuickPrint } from './pages/quick-print'
 import { mountTemplates } from './pages/templates'
 import { mountTemplateEditor } from './pages/template-editor'
 import { mountTemplateRecall } from './pages/template-recall'
+import { mountHistory } from './pages/history'
+import { mountSettings } from './pages/settings'
 import { initRouter, register, registerPrefix } from './router'
 
 register('/', mountQuickPrint)
@@ -15,4 +17,6 @@ registerPrefix('/templates/', (root) => {
     mountTemplateEditor(root)
   }
 })
+register('/history', mountHistory)
+register('/settings', mountSettings)
 initRouter()
diff --git a/frontend/src/pages/history.ts b/frontend/src/pages/history.ts
new file mode 100644
index 0000000..7baf650
--- /dev/null
+++ b/frontend/src/pages/history.ts
@@ -0,0 +1,240 @@
+import { deleteHistory, fetchHistoryPreview, listHistory, pinHistory, reprintHistory } from '../api'
+import type { HistoryItem } from '../types'
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function fmtDate(iso: string): string {
+  try {
+    return new Date(iso).toLocaleString()
+  } catch {
+    return iso
+  }
+}
+
+function fmtFields(fields: Record<string, string> | null): string {
+  if (!fields || Object.keys(fields).length === 0) return ''
+  return Object.entries(fields)
+    .map(([k, v]) => `${esc(k)}=${esc(String(v))}`)
+    .join(', ')
+}
+
+// Track object URLs created for thumbnails; revoked on each remount and on successful regen
+let _gen = 0
+let _objectUrls: string[] = []
+
+function revokeAll(): void {
+  for (const url of _objectUrls) URL.revokeObjectURL(url)
+  _objectUrls = []
+  _gen++
+}
+
+async function loadThumb(
+  imgEl: HTMLImageElement,
+  placeholder: HTMLDivElement,
+  id: number,
+  gen: number,
+): Promise<void> {
+  try {
+    const blob = await fetchHistoryPreview(id)
+    if (_gen !== gen) return
+    const url = URL.createObjectURL(blob)
+    _objectUrls.push(url)
+    imgEl.src = url
+    imgEl.hidden = false
+    placeholder.hidden = true
+  } catch {
+    if (_gen !== gen) return
+    // 404 or error: placeholder stays visible
+  }
+}
+
+export function mountHistory(root: HTMLElement): void {
+  revokeAll()
+
+  const LIMIT = 25
+  let offset = 0
+  let filterTemplate = ''
+  let filterPinned = false
+
+  root.innerHTML = `
+    <div class="history-page">
+      <h2>Print History</h2>
+      <div class="history-filters">
+        <label class="filter-label">
+          Template
+          <input type="text" id="filter-template" placeholder="filter by name…" autocomplete="off" />
+        </label>
+        <label class="filter-pinned">
+          <input type="checkbox" id="filter-pinned" /> Pinned only
+        </label>
+      </div>
+      <div id="history-status" class="status-msg" hidden></div>
+      <div id="history-list"></div>
+      <div id="history-more" hidden><button id="btn-load-more">Load more</button></div>
+      <p id="history-empty" class="empty-state" hidden>No print jobs found.</p>
+    </div>
+  `
+
+  const filterTemplateEl = root.querySelector<HTMLInputElement>('#filter-template')!
+  const filterPinnedEl = root.querySelector<HTMLInputElement>('#filter-pinned')!
+  const statusEl = root.querySelector<HTMLDivElement>('#history-status')!
+  const listEl = root.querySelector<HTMLDivElement>('#history-list')!
+  const moreEl = root.querySelector<HTMLDivElement>('#history-more')!
+  const emptyEl = root.querySelector<HTMLParagraphElement>('#history-empty')!
+  const btnLoadMore = root.querySelector<HTMLButtonElement>('#btn-load-more')!
+
+  function showStatus(msg: string, kind: 'success' | 'error'): void {
+    statusEl.textContent = msg
+    statusEl.className = `status-msg ${kind}`
+    statusEl.hidden = false
+  }
+
+  function hideStatus(): void { statusEl.hidden = true }
+
+  function buildRow(item: HistoryItem): HTMLDivElement {
+    const gen = _gen
+    const row = document.createElement('div')
+    row.className = 'history-row'
+
+    const templateLabel = item.template_id
+      ? `<span class="history-tpl-name">${esc(item.template_id)}</span>`
+      : `<span class="badge-quick">Quick print</span>`
+    const fieldsStr = fmtFields(item.field_values)
+    const reprintMarker = item.reprint_of != null
+      ? `<span class="reprint-marker">↩ reprint of #${item.reprint_of}</span>`
+      : ''
+
+    row.innerHTML = `
+      <div class="history-thumb-wrap">
+        <div class="history-thumb-placeholder"></div>
+        <img class="history-thumb" hidden alt="Preview" />
+      </div>
+      <div class="history-row-body">
+        <div class="history-row-name">${templateLabel}</div>
+        ${fieldsStr ? `<div class="history-row-fields">${fieldsStr}</div>` : ''}
+        <div class="history-row-meta">
+          <span>${esc(fmtDate(item.created_at))}</span>
+          ${reprintMarker}
+        </div>
+        <div class="history-row-actions">
+          <button class="btn-pin${item.pinned ? ' btn-pinned' : ''}" data-pinned="${item.pinned}">${item.pinned ? 'Unpin' : 'Pin'}</button>
+          <button class="btn-reprint">Reprint</button>
+          <button class="btn-danger">Delete</button>
+        </div>
+      </div>
+    `
+
+    const imgEl = row.querySelector<HTMLImageElement>('.history-thumb')!
+    const placeholderEl = row.querySelector<HTMLDivElement>('.history-thumb-placeholder')!
+    void loadThumb(imgEl, placeholderEl, item.id, gen)
+
+    const btnPin = row.querySelector<HTMLButtonElement>('.btn-pin')!
+    btnPin.addEventListener('click', async () => {
+      const currentPinned = btnPin.dataset.pinned === 'true'
+      btnPin.disabled = true
+      try {
+        const updated = await pinHistory(item.id, !currentPinned)
+        btnPin.dataset.pinned = String(updated.pinned)
+        btnPin.textContent = updated.pinned ? 'Unpin' : 'Pin'
+        btnPin.classList.toggle('btn-pinned', updated.pinned)
+        item.pinned = updated.pinned
+      } catch (err) {
+        showStatus((err as Error).message, 'error')
+      } finally {
+        btnPin.disabled = false
+      }
+    })
+
+    const btnReprint = row.querySelector<HTMLButtonElement>('.btn-reprint')!
+    btnReprint.addEventListener('click', async () => {
+      btnReprint.disabled = true
+      btnReprint.textContent = 'Reprinting…'
+      hideStatus()
+      try {
+        await reprintHistory(item.id)
+        resetAndLoad()
+      } catch (err) {
+        showStatus((err as Error).message, 'error')
+        btnReprint.textContent = 'Reprint'
+        btnReprint.disabled = false
+      }
+    })
+
+    const btnDelete = row.querySelector<HTMLButtonElement>('.btn-danger')!
+    btnDelete.addEventListener('click', async () => {
+      if (!confirm('Delete this print job? This cannot be undone.')) return
+      btnDelete.disabled = true
+      try {
+        await deleteHistory(item.id)
+        row.remove()
+        if (listEl.children.length === 0 && moreEl.hidden) {
+          emptyEl.hidden = false
+        }
+      } catch (err) {
+        showStatus((err as Error).message, 'error')
+        btnDelete.disabled = false
+      }
+    })
+
+    return row
+  }
+
+  async function loadPage(reset: boolean): Promise<void> {
+    if (reset) {
+      offset = 0
+      revokeAll()
+      listEl.innerHTML = ''
+      moreEl.hidden = true
+      emptyEl.hidden = true
+    }
+    btnLoadMore.disabled = true
+    try {
+      const params: Record<string, string> = {
+        limit: String(LIMIT),
+        offset: String(offset),
+      }
+      if (filterTemplate.trim()) params.template = filterTemplate.trim()
+      if (filterPinned) params.pinned = 'true'
+
+      const items = await listHistory(params)
+      if (items.length === 0 && offset === 0) {
+        emptyEl.hidden = false
+        moreEl.hidden = true
+      } else {
+        emptyEl.hidden = true
+        for (const item of items) listEl.appendChild(buildRow(item))
+        moreEl.hidden = items.length < LIMIT
+        offset += items.length
+      }
+    } catch (err) {
+      showStatus((err as Error).message, 'error')
+    } finally {
+      btnLoadMore.disabled = false
+    }
+  }
+
+  function resetAndLoad(): void {
+    hideStatus()
+    void loadPage(true)
+  }
+
+  let debounce: number | undefined
+  filterTemplateEl.addEventListener('input', () => {
+    filterTemplate = filterTemplateEl.value
+    window.clearTimeout(debounce)
+    debounce = window.setTimeout(resetAndLoad, 350)
+  })
+  filterPinnedEl.addEventListener('change', () => {
+    filterPinned = filterPinnedEl.checked
+    resetAndLoad()
+  })
+  btnLoadMore.addEventListener('click', () => void loadPage(false))
+
+  void loadPage(true)
+}
diff --git a/frontend/src/pages/settings.ts b/frontend/src/pages/settings.ts
new file mode 100644
index 0000000..98f5fdd
--- /dev/null
+++ b/frontend/src/pages/settings.ts
@@ -0,0 +1,109 @@
+import { getSettings, pruneHistory, putSettings } from '../api'
+
+export function mountSettings(root: HTMLElement): void {
+  root.innerHTML = `
+    <div class="settings-page">
+      <h2>Settings</h2>
+      <section class="settings-section">
+        <h3>History &amp; Retention</h3>
+        <div id="retention-status" class="status-msg" hidden></div>
+        <div id="retention-form"><p>Loading…</p></div>
+      </section>
+    </div>
+  `
+
+  const statusEl = root.querySelector<HTMLDivElement>('#retention-status')!
+  const formEl = root.querySelector<HTMLDivElement>('#retention-form')!
+
+  function showStatus(msg: string, kind: 'success' | 'error'): void {
+    statusEl.textContent = msg
+    statusEl.className = `status-msg ${kind}`
+    statusEl.hidden = false
+  }
+
+  function renderForm(settings: Record<string, unknown>): void {
+    const mode = (settings.retention_mode as string) || 'forever'
+    const count = (settings.retention_count as number) ?? 500
+    const days = (settings.retention_days as number) ?? 90
+
+    formEl.innerHTML = `
+      <div class="radio-group retention-modes">
+        <label><input type="radio" name="retention_mode" value="forever" ${mode === 'forever' ? 'checked' : ''} /> Keep forever</label>
+        <label><input type="radio" name="retention_mode" value="last_n" ${mode === 'last_n' ? 'checked' : ''} /> Keep last N</label>
+        <label><input type="radio" name="retention_mode" value="last_days" ${mode === 'last_days' ? 'checked' : ''} /> Keep last N days</label>
+      </div>
+      <div id="count-row" class="setting-row" ${mode !== 'last_n' ? 'hidden' : ''}>
+        <span class="setting-row-label">Keep last</span>
+        <input type="number" id="retention-count" min="1" max="100000" value="${count}" />
+        <span class="setting-hint">most recent unpinned prints</span>
+      </div>
+      <div id="days-row" class="setting-row" ${mode !== 'last_days' ? 'hidden' : ''}>
+        <span class="setting-row-label">Keep prints from last</span>
+        <input type="number" id="retention-days" min="1" max="36500" value="${days}" />
+        <span class="setting-hint">days</span>
+      </div>
+      <p class="setting-hint">Pinned prints are never pruned regardless of mode.</p>
+      <div class="setting-actions">
+        <button id="btn-save" class="btn-primary">Save</button>
+        <button id="btn-prune">Run cleanup now</button>
+      </div>
+    `
+
+    const radios = formEl.querySelectorAll<HTMLInputElement>('input[name="retention_mode"]')
+    const countRow = formEl.querySelector<HTMLDivElement>('#count-row')!
+    const daysRow = formEl.querySelector<HTMLDivElement>('#days-row')!
+    const countInput = formEl.querySelector<HTMLInputElement>('#retention-count')!
+    const daysInput = formEl.querySelector<HTMLInputElement>('#retention-days')!
+    const btnSave = formEl.querySelector<HTMLButtonElement>('#btn-save')!
+    const btnPrune = formEl.querySelector<HTMLButtonElement>('#btn-prune')!
+
+    function getMode(): string {
+      return Array.from(radios).find(r => r.checked)?.value ?? 'forever'
+    }
+
+    function updateVisibility(): void {
+      const m = getMode()
+      countRow.hidden = m !== 'last_n'
+      daysRow.hidden = m !== 'last_days'
+    }
+
+    radios.forEach(r => r.addEventListener('change', updateVisibility))
+
+    btnSave.addEventListener('click', async () => {
+      btnSave.disabled = true
+      statusEl.hidden = true
+      const m = getMode()
+      const patch: Record<string, unknown> = { retention_mode: m }
+      if (m === 'last_n') patch.retention_count = parseInt(countInput.value, 10) || 500
+      if (m === 'last_days') patch.retention_days = parseInt(daysInput.value, 10) || 90
+      try {
+        await putSettings(patch)
+        showStatus('Retention settings saved.', 'success')
+      } catch (err) {
+        showStatus((err as Error).message, 'error')
+      } finally {
+        btnSave.disabled = false
+      }
+    })
+
+    btnPrune.addEventListener('click', async () => {
+      btnPrune.disabled = true
+      btnPrune.textContent = 'Running…'
+      statusEl.hidden = true
+      try {
+        const result = await pruneHistory()
+        const pruned = typeof result.pruned === 'number' ? result.pruned : '?'
+        showStatus(`Cleanup done — ${pruned} job(s) removed.`, 'success')
+      } catch (err) {
+        showStatus((err as Error).message, 'error')
+      } finally {
+        btnPrune.disabled = false
+        btnPrune.textContent = 'Run cleanup now'
+      }
+    })
+  }
+
+  getSettings()
+    .then(s => renderForm(s))
+    .catch(err => showStatus((err as Error).message, 'error'))
+}
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 102bf02..7c3027a 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -391,6 +391,221 @@ button:disabled {
   border-color: #1a6fdb;
 }
 
+/* history page */
+.history-page {
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 1.5rem;
+}
+
+.history-page h2 {
+  margin: 0 0 1rem;
+}
+
+.history-filters {
+  display: flex;
+  gap: 1.25rem;
+  align-items: flex-end;
+  margin-bottom: 1rem;
+  flex-wrap: wrap;
+}
+
+.history-filters .filter-label {
+  flex: 1;
+  min-width: 140px;
+}
+
+.history-filters .filter-pinned {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  font-weight: normal;
+  cursor: pointer;
+  white-space: nowrap;
+  padding-bottom: 0.25rem;
+}
+
+.history-row {
+  display: flex;
+  gap: 0.75rem;
+  padding: 0.7rem 0;
+  border-bottom: 1px solid #eee;
+  align-items: flex-start;
+}
+
+.history-row:last-child {
+  border-bottom: none;
+}
+
+.history-thumb-wrap {
+  flex-shrink: 0;
+  width: 52px;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding-top: 0.1rem;
+}
+
+.history-thumb-placeholder {
+  width: 52px;
+  height: 36px;
+  background: #f0f0f0;
+  border: 1px solid #ddd;
+  border-radius: 3px;
+}
+
+.history-thumb {
+  max-width: 52px;
+  max-height: 52px;
+  border: 1px solid #ddd;
+  border-radius: 3px;
+  object-fit: contain;
+}
+
+.history-row-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.history-row-name {
+  font-weight: 600;
+  font-size: 0.875rem;
+  margin-bottom: 0.15rem;
+}
+
+.history-tpl-name {
+  font-weight: 600;
+}
+
+.history-row-fields {
+  font-size: 0.8rem;
+  color: #555;
+  margin-bottom: 0.15rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.history-row-meta {
+  font-size: 0.78rem;
+  color: #888;
+  display: flex;
+  gap: 0.6rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.35rem;
+}
+
+.reprint-marker {
+  color: #aaa;
+}
+
+.badge-quick {
+  display: inline-block;
+  background: #f0f4ff;
+  border: 1px solid #c0d0f0;
+  color: #2855a0;
+  border-radius: 3px;
+  font-size: 0.75rem;
+  padding: 0 0.4rem;
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+.history-row-actions {
+  display: flex;
+  gap: 0.4rem;
+  flex-wrap: wrap;
+}
+
+.history-row-actions button {
+  padding: 0.2rem 0.6rem;
+  font-size: 0.8rem;
+}
+
+.btn-pinned {
+  background: #fff8e1;
+  border-color: #f0c040;
+  color: #7a5c00;
+}
+
+.btn-danger {
+  color: #c0392b;
+  border-color: #e0a09a;
+}
+
+#history-more {
+  margin-top: 1rem;
+  text-align: center;
+}
+
+/* settings page */
+.settings-page {
+  background: #fff;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 1.5rem;
+}
+
+.settings-page h2 {
+  margin: 0 0 1.5rem;
+}
+
+.settings-section {
+  margin-bottom: 1.5rem;
+}
+
+.settings-section h3 {
+  font-size: 0.95rem;
+  color: #444;
+  margin: 0 0 0.85rem;
+  padding-bottom: 0.4rem;
+  border-bottom: 1px solid #eee;
+}
+
+.retention-modes {
+  flex-direction: column;
+  gap: 0.4rem;
+  margin-bottom: 0.75rem;
+}
+
+.retention-modes label {
+  font-weight: normal;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  cursor: pointer;
+}
+
+.setting-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.setting-row-label {
+  font-size: 0.875rem;
+  white-space: nowrap;
+}
+
+.setting-row input[type="number"] {
+  width: 80px;
+}
+
+.setting-hint {
+  font-size: 0.8rem;
+  color: #888;
+  margin: 0.25rem 0 0.75rem;
+}
+
+.setting-actions {
+  display: flex;
+  gap: 0.75rem;
+  margin-top: 0.75rem;
+}
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index acc7edf..1cd47f8 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -82,3 +82,26 @@ export interface TemplateCreate {
   label_media: string;
   canvas_json: Record<string, unknown>;
 }
+
+export interface HistoryItem {
+  id: number;
+  template_id: string | null;
+  is_quick_print: boolean;
+  field_values: Record<string, string> | null;
+  label_media: string;
+  pinned: boolean;
+  created_at: string;
+  reprint_of: number | null;
+  batch_id: string | null;
+  preview_url: string | null;
+}
+
+export interface HistoryDetail extends HistoryItem {
+  payload_json: Record<string, unknown>;
+}
+
+export interface ReprintResponse {
+  job_id: number;
+  status: string;
+  reprint_of: number;
+}
diff --git a/prompts/done/2026-05-31-print-history-ui.md b/prompts/done/2026-05-31-print-history-ui.md
new file mode 100644
index 0000000..4507c7c
--- /dev/null
+++ b/prompts/done/2026-05-31-print-history-ui.md
@@ -0,0 +1,129 @@
+---
+name: 2026-05-31-print-history-ui
+status: completed
+created: 2026-05-31
+model: sonnet
+completed: 2026-05-31
+result: /history page (list, reprint, pin, delete, load-more, filters) and /settings retention UI built; frontend build passes
+---
+
+# Task: Print history UI + retention settings UI
+
+Build the **frontend** half of the History feature (Slice B). The backend API landed in
+commit `d5fc08f` (`prompts/done/2026-05-31-print-history-backend.md`). This slice adds the
+`/history` page (browse, reprint, pin, delete) and a retention-policy section in settings,
+completing v1 success criteria 6 (reprint) and 7 (pin) end-to-end in the UI.
+
+## Before you start
+
+- Read `docs/features/history.md` (user flow) and `docs/features/settings.md` (retention
+  config). Read `CLAUDE.md` "Code check-in" + "Working style" (vanilla TS, no frameworks).
+- This repo uses **vexp**: call `run_pipeline` first; prefer `get_skeleton` over `Read`;
+  don't grep/glob.
+- Frontend facts (verified during planning):
+  - Vanilla Vite + TS, **no React/Vue**. Fabric.js is only for the canvas editor — not
+    needed here.
+  - Custom router in `frontend/src/router.ts`: `register(path, mountFn)` for exact paths,
+    `registerPrefix(prefix, mountFn)` for parameterised ones. Routes are wired in
+    `frontend/src/main.ts` (e.g. `register('/templates', mountTemplates)`). Nav links use
+    `data-route="..."` anchors.
+  - Pages live in `frontend/src/pages/*.ts` and export a `mountX(root)` function. Model the
+    new page on an existing one — `pages/templates-list.ts` (list + per-row actions) and
+    `pages/template-recall.ts` (preview image + form + print) are the closest analogues.
+  - API helpers live in `frontend/src/api.ts` (`apiFetch<T>(path, opts)` handles the bearer
+    token + errors). Add history calls there. Types go in `frontend/src/types.ts`.
+  - Styles in `frontend/src/style.css` (plain CSS; match existing class conventions).
+
+### Backend API this UI consumes (already live, all require the bearer token)
+- `GET /api/history?limit=&offset=&template=&pinned=&from=&to=` → `HistoryItem[]`.
+  `HistoryItem` = `{ id, template_id (name|null), is_quick_print, field_values (object),
+  label_media, pinned, created_at, reprint_of (id|null), batch_id, preview_url }`.
+- `GET /api/history/{id}` → `HistoryDetail` (= `HistoryItem` + `payload_json`).
+- `GET /api/history/{id}/preview.png` → PNG (use directly as `<img src>`; **note the token**
+  — see "Preview auth" below). Returns 404 when no preview exists.
+- `POST /api/history/{id}/reprint` → `{ job_id, status, reprint_of }`. 409 if the template
+  is hard-deleted or the label media left the catalog — surface the error message.
+- `POST /api/history/{id}/pin` body `{ "pinned": true|false }` → updated `HistoryItem`.
+- `DELETE /api/history/{id}` → 204.
+- Retention settings via existing `GET/PUT /api/settings`: keys `retention_mode`
+  (`forever` | `last_n` | `last_days`), `retention_count` (int), `retention_days` (int).
+
+## Working tree check
+
+Run `git status --porcelain` first; cross-reference the files below and ask before
+touching any that are already dirty (this prompt file exempt). Files this plan touches:
+- `frontend/src/pages/history.ts` (new)
+- `frontend/src/pages/settings.ts` (new) *or* extend an existing settings page if one
+  exists — check first
+- `frontend/src/api.ts`, `frontend/src/types.ts`, `frontend/src/main.ts`,
+  `frontend/src/style.css`
+- the nav markup (wherever the `data-route` links live — likely `index.html` or `main.ts`)
+- `CHANGELOG.md`
+
+## What to do
+
+### 1. API + types
+- Add to `types.ts`: `HistoryItem`, `HistoryDetail` (match the shapes above), and a
+  retention-settings shape.
+- Add to `api.ts`: `listHistory(params)`, `getHistory(id)`, `reprintHistory(id)`,
+  `pinHistory(id, pinned)`, `deleteHistory(id)`, plus `getSettings()` / `updateSettings(patch)`
+  if not already present.
+
+### 2. Preview auth
+`/api/history/{id}/preview.png` requires the bearer token, so a bare `<img src="/api/...">`
+will 401. Mirror however the editor/recall pages already load authed images (likely
+`fetch` → `blob` → `URL.createObjectURL`). Reuse that pattern; **don't** put the token in a
+query string. Revoke object URLs on unmount/refresh to avoid leaks. Show a placeholder box
+on 404 / load error.
+
+### 3. `/history` page (`pages/history.ts`, `register('/history', mountHistory)` in `main.ts`)
+- Reverse-chronological, paginated list (use `limit`/`offset`; a "Load more" button or
+  prev/next is fine — keep it simple).
+- Each row: thumbnail (authed, step 2), template name or a "Quick print" badge, compact
+  `key=value` rendering of `field_values`, timestamp, a pin toggle, a Reprint button, a
+  Delete button. Show a small "↩ reprint of #N" marker when `reprint_of` is set.
+- Pin toggle → `pinHistory`; reflect the returned `pinned` state without a full reload.
+- Reprint → `reprintHistory`; on success prepend/refresh so the new row appears; on 409
+  show the server's error message (e.g. "label media no longer in catalog"). Reprint hits a
+  real printer — make the button state clear (disable while in flight).
+- Delete → confirm, then `deleteHistory`, remove the row.
+- Filters: at minimum a template filter and a pinned-only toggle (date range optional —
+  implement if cheap, else leave a TODO comment, don't fake it).
+- Empty state when there are no jobs.
+- Add a **History** nav link (`data-route="/history"`) alongside the existing nav entries.
+
+### 4. Retention settings UI
+- Add a settings page/section (check whether a settings page already exists; if so, extend
+  it rather than creating a parallel one).
+- Controls: a mode selector (`Keep forever` / `Keep last N` / `Keep N days`) that
+  shows/enables the relevant number input (`retention_count` for `last_n`,
+  `retention_days` for `last_days`). Load current values from `GET /api/settings`; save via
+  `PUT /api/settings` (send only the changed keys). Confirm-on-save feedback.
+- Make clear (helper text) that pinned prints are never pruned.
+
+### Out of scope (do NOT build here)
+- "Use as starting point for new template" (the history.md action that opens the editor) —
+  deferred with the QR / canvas-elements work. A `// TODO` placeholder is fine; don't wire
+  it.
+- Any backend change. If you find an API gap, **stop and ask** rather than editing backend.
+
+## Conventions to honor
+
+- Vanilla TS, match the structure/idioms of existing `pages/*.ts` (no framework, no new
+  deps). Reuse `apiFetch` and existing CSS classes; don't introduce a CSS framework.
+- Changelog: concise user-facing entry under `## [Unreleased]` → `### Added` ("Print
+  history page — browse, reprint, pin, and delete past prints; retention policy in
+  settings").
+- Verify the build: `cd frontend && npm run build` (and `npm run dev` for a manual click-
+  through if a backend is reachable). Leave a one-line "run this to verify" in your summary.
+- Commit on `dev`, prefix `feat:`, no `Co-authored-by:`, never push, never `git add -A`.
+
+## When done
+
+1. Update this file's frontmatter (`status`, `completed`, `result`).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record any non-obvious decisions in `docs/decisions.md` (e.g. the authed-image-loading
+   approach, pagination style chosen).
+4. Propose ONE commit covering the modified files (including this prompt's move). Present
+   the file list + a one-line `feat:` message and ask `commit these as "<message>"? (y/n)`.
+   On `y`, stage those specific paths and commit on `dev`. Never push.

From 270b4752eb696ab673b7c32eb94d8613a13c16d1 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 10:54:48 -0700
Subject: [PATCH 47/84] update docker compose name

---
 compose.dev.yml => docker-compose.dev.yml | 0
 compose.yml => docker-compose.yml         | 0
 2 files changed, 0 insertions(+), 0 deletions(-)
 rename compose.dev.yml => docker-compose.dev.yml (100%)
 rename compose.yml => docker-compose.yml (100%)

diff --git a/compose.dev.yml b/docker-compose.dev.yml
similarity index 100%
rename from compose.dev.yml
rename to docker-compose.dev.yml
diff --git a/compose.yml b/docker-compose.yml
similarity index 100%
rename from compose.yml
rename to docker-compose.yml

From 356e54b93e708c912c3820431b29a97e141e2636 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 14:41:23 -0700
Subject: [PATCH 48/84] feat: add printer status endpoint, pre-print media
 check, and Test Printer UI

- GET /api/printer/status: queries via raw TCP (ESC i S) with HTTP fallback
  to the printer's status page; raises 503 if both paths fail
- Pre-print media check on all three print routes (quick, template, batch);
  returns 409 media_mismatch or printer_error, with ?override=true bypass
- Settings page "Test Printer" button calls the status endpoint and renders
  model, loaded media, ready state, and source inline
- media_compatible() allows 62red loaded when 62 expected (color superset);
  blocks 62 loaded when 62red expected (silent mono)
- status_check and timeout controlled by existing printer_status_check /
  printer_status_timeout_ms settings; degrades gracefully if unreachable
---
 CHANGELOG.md                                  |   1 +
 backend/labelforge/main.py                    |   2 +
 backend/labelforge/printer/client.py          | 198 +++++++++++-
 backend/labelforge/routes/print.py            |  40 ++-
 backend/labelforge/routes/printer.py          |  57 ++++
 backend/labelforge/routes/template_print.py   |  80 ++++-
 docs/decisions.md                             |  30 ++
 frontend/src/api.ts                           |   8 +
 frontend/src/pages/settings.ts                |  52 ++-
 .../done/2026-05-31-printer-status-build.md   | 298 ++++++++++++++++++
 .../done/2026-05-31-printer-status-spike.md   | 109 +++++++
 11 files changed, 865 insertions(+), 10 deletions(-)
 create mode 100644 backend/labelforge/routes/printer.py
 create mode 100644 prompts/done/2026-05-31-printer-status-build.md
 create mode 100644 prompts/done/2026-05-31-printer-status-spike.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 05708af..fe38f1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Printer status check** — `GET /api/printer/status` returns loaded media, ready state, and errors; print endpoints (`POST /api/print/quick`, `/api/print/{name}`, `/api/print/{name}/batch`) block on media mismatch with a 409 (pass `?override=true` to proceed); Settings page "Test Printer" button shows live printer state. Status queried over raw TCP (ESC i S) with HTTP fallback to the printer's status page; degrades gracefully if unreachable. Controlled by `printer_status_check` and `printer_status_timeout_ms` settings.
 - **Print history page** — browse, reprint, pin, and delete past prints at `/history`; paginated reverse-chronological list with authenticated thumbnail previews, template/quick-print labels, field-value display, and filters (by template name, pinned-only toggle). Reprint creates a new job and refreshes the list; a 409 (template or media gone) surfaces the server's error message. Delete requires confirmation. Pin toggle updates inline without a reload. Retention policy configurable in `/settings` (keep forever / last N / last N days); pinned prints are never pruned; "Run cleanup now" triggers an immediate prune.
 - **Print history API** — every print is logged with a preview PNG; browse paginated history at `GET /api/history`, fetch full detail at `GET /api/history/{id}`, serve the preview image at `GET /api/history/{id}/preview.png`, reprint a past job at `POST /api/history/{id}/reprint` (creates a new row linked via `reprint_of`), pin/unpin at `POST /api/history/{id}/pin`, and delete at `DELETE /api/history/{id}`. Retention auto-pruning runs at startup and every 6 hours, honoring the `retention_mode` / `retention_count` / `retention_days` settings. Pinned rows are never pruned.
 - **Printer-aware label catalog** — each label now carries a `supported` flag computed at catalog load against the configured printer (`PRINTER_MODEL`). Media the printer physically can't print — wide-format rolls on a non-QL-1xxx printer, two-color rolls on a mono printer — appear in the selectors greyed out, disabled, and marked `— unavailable` with a tooltip explaining why, instead of being silently offered. On the default QL-820NWB the six wide-format rolls (`102`, `103`, `104`, `102x51`, `102x152`, `103x164`) are now disabled; `62red` stays selectable. Compatibility is derived from the `brother_ql` library, not hand-maintained — the `printer_requirements` field in `labels.yml` is deprecated and ignored.
diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 16d4bc4..62b666a 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -17,6 +17,7 @@
 from labelforge.routes import history as history_router
 from labelforge.routes import print as print_router
 from labelforge.routes import preview as preview_router
+from labelforge.routes import printer as printer_router
 from labelforge.routes import settings as settings_router
 from labelforge.routes import template_print as template_print_router
 from labelforge.routes import templates as templates_router
@@ -89,6 +90,7 @@ async def _retention_loop() -> None:
 app.include_router(fonts.router, prefix="/api")
 app.include_router(print_router.router, prefix="/api")
 app.include_router(preview_router.router, prefix="/api")
+app.include_router(printer_router.router, prefix="/api")
 app.include_router(settings_router.router, prefix="/api")
 app.include_router(templates_router.router, prefix="/api")
 app.include_router(template_print_router.router, prefix="/api")
diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
index b295030..ff68fa5 100644
--- a/backend/labelforge/printer/client.py
+++ b/backend/labelforge/printer/client.py
@@ -1,17 +1,28 @@
 # Import paths verified against brother-ql-inventree 1.3:
-#   brother_ql.raster.BrotherQLRaster       — builds the instruction buffer
-#   brother_ql.conversion.convert           — PIL Image → raster bytes (returns qlr.data)
-#   brother_ql.backends.helpers.send        — transmits bytes to the printer
+#   brother_ql.raster.BrotherQLRaster               — builds the instruction buffer
+#   brother_ql.conversion.convert                   — PIL Image → raster bytes (returns qlr.data)
+#   brother_ql.backends.helpers.send                — transmits bytes to the printer
+#   brother_ql.backends.helpers.backend_factory     — returns {"backend_class": ..., ...}
+#   brother_ql.reader.interpret_response            — parses 32-byte status reply into dict
+#   brother_ql.labels.ALL_LABELS                    — list of Label objects; .tape_size, .identifier, .color
 #
 # Network backend expects printer_identifier in the form "tcp://host[:port]"
 # (port defaults to 9100 when omitted).  The send() helper also accepts
 # backend_identifier values: "network", "linux_kernel", "pyusb".
+#
+# get_printer() raises NotImplementedError for backend="network" (library design).
+# Bypass by instantiating BrotherQLBackendNetwork directly via backend_factory.
 
+import html.parser
 import logging
+import re
+import urllib.request
 
-from brother_ql.backends.helpers import send
+from brother_ql.backends.helpers import backend_factory, send
 from brother_ql.conversion import convert
+from brother_ql.labels import ALL_LABELS
 from brother_ql.raster import BrotherQLRaster
+from brother_ql.reader import interpret_response
 from PIL import Image
 
 logger = logging.getLogger(__name__)
@@ -39,6 +50,185 @@ class PrintError(Exception):
     pass
 
 
+class StatusUnavailable(Exception):
+    pass
+
+
+def _media_id_from_dims(width_mm: int, length_mm: int, tape_color_raw: int | None) -> str | None:
+    matches = [lbl for lbl in ALL_LABELS if lbl.tape_size == (width_mm, length_mm)]
+    if not matches:
+        return None
+    if len(matches) == 1:
+        return matches[0].identifier
+    # Multiple labels share the same tape_size (e.g. "62" and "62red" are both (62, 0)).
+    # TODO: verify DK-22251 tape_color_raw byte against hardware; default "62" until confirmed.
+    _ = tape_color_raw  # reserved for hardware-verified two-color detection
+    return "62"
+
+
+def _color_capable(media_id: str | None) -> bool:
+    if media_id is None:
+        return False
+    lbl = next((l for l in ALL_LABELS if l.identifier == media_id), None)
+    return bool(lbl and int(getattr(lbl, "color", 0) or 0))
+
+
+class _StatusPageParser(html.parser.HTMLParser):
+    """Extract dt/dd key-value pairs from the printer's status.html page."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.pairs: dict[str, str] = {}
+        self._in_dt = False
+        self._in_dd = False
+        self._cur_dt: str | None = None
+        self._buf: str = ""
+
+    def handle_starttag(self, tag: str, attrs: list) -> None:
+        if tag == "dt":
+            self._in_dt = True
+            self._in_dd = False
+            self._buf = ""
+        elif tag == "dd":
+            self._in_dd = True
+            self._in_dt = False
+            self._buf = ""
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "dt":
+            self._cur_dt = self._buf.strip()
+            self._in_dt = False
+        elif tag == "dd":
+            if self._cur_dt:
+                self.pairs[self._cur_dt] = self._buf.strip()
+            self._cur_dt = None
+            self._in_dd = False
+
+    def handle_data(self, data: str) -> None:
+        if self._in_dt or self._in_dd:
+            self._buf += data
+
+
+def media_compatible(loaded_id: str, expected_id: str) -> bool:
+    """Return True when the loaded media can print the expected layout.
+
+    62red is a superset of 62 — allow when more color capability is loaded
+    than the template needs. The reverse (mono loaded, color expected) blocks
+    because the print would silently drop the red channel.
+    """
+    if loaded_id == expected_id:
+        return True
+    if loaded_id == "62red" and expected_id == "62":
+        return True
+    return False
+
+
+def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
+    """Query printer status over TCP (primary) or HTTP (fallback).
+
+    Returns:
+        {
+          "ready": bool,
+          "model": str | None,
+          "media_id": str | None,   # e.g. "62", "62x29", "62red"
+          "width_mm": int | None,
+          "length_mm": int | None,  # 0 for continuous
+          "color_capable": bool,
+          "errors": list[str],
+          "source": "tcp" | "http",
+        }
+    Raises StatusUnavailable if both paths fail or backend != "network".
+    """
+    if backend != "network":
+        raise StatusUnavailable(
+            f"Printer status check only supported for network backend (got '{backend}')"
+        )
+
+    timeout_s = timeout_ms / 1000
+    raw: bytes = b""
+
+    # Primary: raw TCP ESC i S (may return empty on some firmware — HTTP fallback handles it)
+    try:
+        be = backend_factory("network")
+        printer = None
+        try:
+            printer = be["backend_class"](f"tcp://{host}")
+            printer.read_timeout = timeout_s
+            printer.s.settimeout(timeout_s)
+            printer.write(b"\x1b\x69\x53")
+            raw = printer.read(32)
+        finally:
+            if printer is not None:
+                try:
+                    printer.s.close()
+                except Exception:
+                    pass
+    except Exception as exc:
+        logger.debug("TCP status path failed: %s", exc)
+
+    if len(raw) >= 32:
+        try:
+            parsed = interpret_response(raw)
+            width_mm = int(parsed.get("media_width", 0) or 0)
+            length_mm = int(parsed.get("media_length", 0) or 0)
+            tape_color_raw = raw[24]
+            media_id = _media_id_from_dims(width_mm, length_mm, tape_color_raw)
+            errors_list = [str(e) for e in (parsed.get("errors") or [])]
+            return {
+                "ready": not errors_list,
+                "model": str(parsed.get("model") or "") or None,
+                "media_id": media_id,
+                "width_mm": width_mm or None,
+                "length_mm": length_mm,
+                "color_capable": _color_capable(media_id),
+                "errors": errors_list,
+                "source": "tcp",
+            }
+        except Exception as exc:
+            logger.debug("TCP response parse failed: %s", exc)
+
+    # Fallback: HTTP status page (unauthenticated, no readback limitation)
+    try:
+        url = f"http://{host}/general/status.html"
+        with urllib.request.urlopen(url, timeout=timeout_s) as resp:
+            html_content = resp.read().decode("utf-8", errors="replace")
+
+        parser = _StatusPageParser()
+        parser.feed(html_content)
+
+        device_status = parser.pairs.get("Device Status", "")
+        media_type_str = parser.pairs.get("Media Type", "")
+        ready = "READY" in device_status.upper()
+
+        width_mm: int | None = None
+        length_mm: int | None = None
+        if media_type_str:
+            m = re.search(r"(\d+)mm\s*x\s*(\d+)mm", media_type_str, re.IGNORECASE)
+            if m:
+                width_mm = int(m.group(1))
+                length_mm = int(m.group(2))
+            else:
+                m2 = re.search(r"(\d+)mm", media_type_str, re.IGNORECASE)
+                if m2:
+                    width_mm = int(m2.group(1))
+                    length_mm = 0
+
+        media_id = _media_id_from_dims(width_mm, length_mm, None) if width_mm is not None else None
+        return {
+            "ready": ready,
+            "model": None,
+            "media_id": media_id,
+            "width_mm": width_mm,
+            "length_mm": length_mm,
+            "color_capable": _color_capable(media_id),
+            "errors": [],
+            "source": "http",
+        }
+    except Exception as exc:
+        logger.debug("HTTP status path failed: %s", exc)
+        raise StatusUnavailable(f"Printer did not respond: {exc}") from exc
+
+
 def print_image(
     image: Image.Image,
     label_media: str,
diff --git a/backend/labelforge/routes/print.py b/backend/labelforge/routes/print.py
index 4a629b6..a2b7cb6 100644
--- a/backend/labelforge/routes/print.py
+++ b/backend/labelforge/routes/print.py
@@ -7,7 +7,7 @@
 from labelforge import settings_store
 from labelforge.history import insert_job_with_preview
 from labelforge.models import PrintJobResponse, QuickPrintRequest
-from labelforge.printer.client import PrintError, print_image
+from labelforge.printer.client import PrintError, StatusUnavailable, media_compatible, print_image, status_read
 from labelforge.render.text import RenderError, render_text
 from labelforge.routes.auth import require_auth
 
@@ -17,7 +17,7 @@
 
 
 @router.post("/print/quick", response_model=PrintJobResponse)
-async def quick_print(request: QuickPrintRequest) -> PrintJobResponse:
+async def quick_print(request: QuickPrintRequest, override: bool = False) -> PrintJobResponse:
     if not request.text.strip():
         raise HTTPException(status_code=400, detail="Text is required")
 
@@ -38,6 +38,42 @@ async def quick_print(request: QuickPrintRequest) -> PrintJobResponse:
     except RenderError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
+    if settings_store.get("printer_status_check"):
+        timeout_ms = settings_store.get("printer_status_timeout_ms")
+        try:
+            status = status_read(
+                host=settings.printer_host,
+                backend=settings.printer_backend,
+                timeout_ms=timeout_ms,
+            )
+            if status["errors"]:
+                code = status["errors"][0].lower().replace(" ", "_")
+                raise HTTPException(status_code=409, detail={
+                    "error": "printer_error",
+                    "code": code,
+                    "message": f"Printer error: {', '.join(status['errors'])}",
+                    "raw": status,
+                })
+            if status["media_id"] is not None and not media_compatible(status["media_id"], request.label_media):
+                if not override:
+                    raise HTTPException(status_code=409, detail={
+                        "error": "media_mismatch",
+                        "expected": request.label_media,
+                        "loaded": status["media_id"],
+                        "override_allowed": True,
+                        "message": (
+                            f"Printer has {status['media_id']} loaded, "
+                            f"template expects {request.label_media}. "
+                            "Pass override=true to print anyway."
+                        ),
+                    })
+                logger.warning(
+                    "Media mismatch (override): loaded=%s expected=%s",
+                    status["media_id"], request.label_media,
+                )
+        except StatusUnavailable:
+            logger.warning("Printer status unavailable; proceeding without check")
+
     try:
         outcome = print_image(
             image=image,
diff --git a/backend/labelforge/routes/printer.py b/backend/labelforge/routes/printer.py
new file mode 100644
index 0000000..003803a
--- /dev/null
+++ b/backend/labelforge/routes/printer.py
@@ -0,0 +1,57 @@
+import logging
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+
+from labelforge import settings_store
+from labelforge.catalog.loader import get_label
+from labelforge.config import settings
+from labelforge.printer.client import StatusUnavailable, status_read
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["printer"])
+
+
+@router.get("/printer/status")
+async def get_printer_status() -> dict:
+    timeout_ms = settings_store.get("printer_status_timeout_ms")
+
+    try:
+        status = status_read(
+            host=settings.printer_host,
+            backend=settings.printer_backend,
+            timeout_ms=timeout_ms,
+        )
+    except StatusUnavailable as exc:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "status_unavailable", "message": str(exc)},
+        )
+
+    media_id = status["media_id"]
+    loaded_media = None
+    if media_id is not None:
+        label = get_label(media_id)
+        if label:
+            display_name = label.display_name
+        elif status["length_mm"] == 0:
+            display_name = f"{status['width_mm']}mm Continuous"
+        else:
+            display_name = f"{status['width_mm']}mm × {status['length_mm']}mm"
+
+        loaded_media = {
+            "id": media_id,
+            "display_name": display_name,
+            "width_mm": status["width_mm"],
+            "length_mm": status["length_mm"],
+            "color_capable": status["color_capable"],
+        }
+
+    return {
+        "ready": status["ready"],
+        "model": status["model"],
+        "loaded_media": loaded_media,
+        "errors": status["errors"],
+        "source": status["source"],
+    }
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index b6691b5..c83750b 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -5,6 +5,7 @@
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import Response
 
+from labelforge import settings_store
 from labelforge.config import settings
 from labelforge.history import insert_job_with_preview
 from labelforge.models import (
@@ -13,7 +14,7 @@
     BatchPrintResponse,
     PrintRequest,
 )
-from labelforge.printer.client import PrintError, print_image, to_print_bitmap
+from labelforge.printer.client import PrintError, StatusUnavailable, media_compatible, print_image, status_read, to_print_bitmap
 from labelforge.render.template import render_template
 from labelforge.render.text import RenderError
 from labelforge.routes.auth import require_auth
@@ -40,7 +41,7 @@ def _apply_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
 
 
 @router.post("/print/{name}")
-async def print_template(name: str, body: PrintRequest) -> dict:
+async def print_template(name: str, body: PrintRequest, override: bool = False) -> dict:
     tmpl = store.get_template(name)
     if tmpl is None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
@@ -52,6 +53,42 @@ async def print_template(name: str, body: PrintRequest) -> dict:
     except RenderError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
+    if settings_store.get("printer_status_check"):
+        timeout_ms = settings_store.get("printer_status_timeout_ms")
+        try:
+            status = status_read(
+                host=settings.printer_host,
+                backend=settings.printer_backend,
+                timeout_ms=timeout_ms,
+            )
+            if status["errors"]:
+                code = status["errors"][0].lower().replace(" ", "_")
+                raise HTTPException(status_code=409, detail={
+                    "error": "printer_error",
+                    "code": code,
+                    "message": f"Printer error: {', '.join(status['errors'])}",
+                    "raw": status,
+                })
+            if status["media_id"] is not None and not media_compatible(status["media_id"], tmpl.label_media):
+                if not override:
+                    raise HTTPException(status_code=409, detail={
+                        "error": "media_mismatch",
+                        "expected": tmpl.label_media,
+                        "loaded": status["media_id"],
+                        "override_allowed": True,
+                        "message": (
+                            f"Printer has {status['media_id']} loaded, "
+                            f"template expects {tmpl.label_media}. "
+                            "Pass override=true to print anyway."
+                        ),
+                    })
+                logger.warning(
+                    "Media mismatch (override): loaded=%s expected=%s",
+                    status["media_id"], tmpl.label_media,
+                )
+        except StatusUnavailable:
+            logger.warning("Printer status unavailable; proceeding without check")
+
     try:
         outcome = print_image(
             image=image,
@@ -99,7 +136,7 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
 
 
 @router.post("/print/{name}/batch", response_model=BatchPrintResponse)
-async def batch_print(name: str, body: BatchPrintRequest) -> BatchPrintResponse:
+async def batch_print(name: str, body: BatchPrintRequest, override: bool = False) -> BatchPrintResponse:
     count = len(body.labels)
     if count < 1:
         raise HTTPException(status_code=400, detail="Batch count must be >= 1")
@@ -110,6 +147,43 @@ async def batch_print(name: str, body: BatchPrintRequest) -> BatchPrintResponse:
     if tmpl is None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
 
+    # Status check once before the loop — avoids per-label overhead
+    if settings_store.get("printer_status_check"):
+        timeout_ms = settings_store.get("printer_status_timeout_ms")
+        try:
+            status = status_read(
+                host=settings.printer_host,
+                backend=settings.printer_backend,
+                timeout_ms=timeout_ms,
+            )
+            if status["errors"]:
+                code = status["errors"][0].lower().replace(" ", "_")
+                raise HTTPException(status_code=409, detail={
+                    "error": "printer_error",
+                    "code": code,
+                    "message": f"Printer error: {', '.join(status['errors'])}",
+                    "raw": status,
+                })
+            if status["media_id"] is not None and not media_compatible(status["media_id"], tmpl.label_media):
+                if not override:
+                    raise HTTPException(status_code=409, detail={
+                        "error": "media_mismatch",
+                        "expected": tmpl.label_media,
+                        "loaded": status["media_id"],
+                        "override_allowed": True,
+                        "message": (
+                            f"Printer has {status['media_id']} loaded, "
+                            f"template expects {tmpl.label_media}. "
+                            "Pass override=true to print anyway."
+                        ),
+                    })
+                logger.warning(
+                    "Media mismatch (override): loaded=%s expected=%s",
+                    status["media_id"], tmpl.label_media,
+                )
+        except StatusUnavailable:
+            logger.warning("Printer status unavailable; proceeding without check")
+
     batch_id = str(uuid.uuid4())
     jobs: list[BatchJobResult] = []
     succeeded = 0
diff --git a/docs/decisions.md b/docs/decisions.md
index 65db4ca..9c10a69 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,36 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-31 — Printer status over network: ESC i S unreliable; implement raw-TCP + HTTP fallback
+
+**Decision**: The Printer Status feature will use a two-path `status_read()` function in `printer/client.py`:
+
+1. **Primary — raw TCP ESC i S**: Directly instantiate `BrotherQLBackendNetwork(f"tcp://{host}")` (bypassing `get_printer()`, which raises `NotImplementedError` for the network backend), override `read_timeout` from the default 10 ms to the configured `printer_status_timeout_ms` value, then call `get_status()`. Parse the 32-byte response via `brother_ql.reader.interpret_response()`. For DK tape color detection, read `data[24]` directly (the library only parses `tape_color` for TZe-category tapes, not DK).
+
+2. **Fallback — HTTP scrape**: If the TCP path returns empty bytes, fetch `http://{host}/general/status.html` (unauthenticated) and parse `dt`/`dd` pairs for "Device Status" (→ ready bool) and "Media Type" (→ string like `"62mm x 29mm"` → regex-extract width/length → look up in `ALL_LABELS`).
+
+3. **Graceful degrade**: If both paths fail, raise `StatusUnavailable`; callers log and proceed (per `printer-status.md` print-path spec).
+
+Media ID mapping for both paths: search `brother_ql.labels.ALL_LABELS` where `lbl.tape_size == (width_mm, length_mm)`. For continuous 62 mm (length = 0), mono `"62"` and color `"62red"` share the same `tape_size` — disambiguate via `data[24]` on the TCP path; report `color_capable: false` (unknown) on the HTTP path. The exact DK-22251 tape-color byte value needs hardware verification when a two-color roll is loaded.
+
+**Why**: A spike against the QL-820NWB (2026-05-31) showed:
+- `get_printer()` raises `NotImplementedError` for `backend="network"` (intentional library design; comment: "Not implemented due to lack of an available test device").
+- `send()` explicitly skips readback for the network backend: "The network backend doesn't support readback."
+- The library's CLI `discover` command skips `get_status()` for the network backend.
+- Live hardware test: TCP port 9100 connects, but ESC i S returns empty bytes regardless of timeout (10 ms, 500 ms, 2 s, 5 s all tested). Full raster init sequence (200 null bytes + ESC @ + ESC i a 01 + ESC i S) also returns empty.
+- The HTTP interface at `/general/status.html` responded without authentication and returned "READY" + "62mm x 29mm".
+
+`get_status()` is technically callable via direct backend instantiation (the function sends ESC i S and reads; it does not filter on the backend type), so the TCP path is kept as primary in case it works on different firmware versions or printer states. The 10 ms default `read_timeout` is the likely cause of spurious failures if the printer ever does respond.
+
+**Considered**:
+- HTTP-only: simpler, but abandons ESC i S even on printers/firmware where it works; provides no color-capability information.
+- Pure TCP with no HTTP fallback: leaves us with 503 on every status call against the current hardware.
+- Patching `get_printer()` via a fork: rejected — no fork policy without an ADR; bypass by direct instantiation is sufficient.
+
+**Would revisit if**: A firmware update makes ESC i S respond on the QL-820NWB (at which point the HTTP fallback can be dropped); or we test on a USB backend where `get_printer()` and `get_status()` work as intended.
+
+---
+
 ## 2026-05-31 — History UI: authed image loading via fetch+objectURL
 
 **Decision**: `/api/history/{id}/preview.png` requires a bearer token, so `<img src="...">` bare URLs 401. The history page fetches previews via `fetch()` with the `Authorization` header, creates an object URL via `URL.createObjectURL(blob)`, and sets that as `img.src`. Object URLs are revoked on page remount and on filter/pagination resets via a generation counter that skips stale async completions.
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 4beea95..822aad6 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -169,6 +169,14 @@ export function getSettings(): Promise<Record<string, unknown>> {
   return apiFetch<Record<string, unknown>>('/api/settings')
 }
 
+export async function getPrinterStatus(): Promise<{ ok: boolean; body: Record<string, unknown> }> {
+  const res = await fetch('/api/printer/status', {
+    headers: { Authorization: `Bearer ${getToken()}` },
+  })
+  const body = await res.json() as Record<string, unknown>
+  return { ok: res.ok, body }
+}
+
 export function putSettings(partial: Record<string, unknown>): Promise<Record<string, unknown>> {
   return apiFetch<Record<string, unknown>>('/api/settings', {
     method: 'PUT',
diff --git a/frontend/src/pages/settings.ts b/frontend/src/pages/settings.ts
index 98f5fdd..586bbf9 100644
--- a/frontend/src/pages/settings.ts
+++ b/frontend/src/pages/settings.ts
@@ -1,9 +1,16 @@
-import { getSettings, pruneHistory, putSettings } from '../api'
+import { getPrinterStatus, getSettings, pruneHistory, putSettings } from '../api'
 
 export function mountSettings(root: HTMLElement): void {
   root.innerHTML = `
     <div class="settings-page">
       <h2>Settings</h2>
+      <section class="settings-section">
+        <h3>Printer</h3>
+        <div class="setting-actions">
+          <button id="btn-test-printer">Test Printer</button>
+        </div>
+        <div id="printer-test-result" hidden></div>
+      </section>
       <section class="settings-section">
         <h3>History &amp; Retention</h3>
         <div id="retention-status" class="status-msg" hidden></div>
@@ -14,6 +21,49 @@ export function mountSettings(root: HTMLElement): void {
 
   const statusEl = root.querySelector<HTMLDivElement>('#retention-status')!
   const formEl = root.querySelector<HTMLDivElement>('#retention-form')!
+  const btnTestPrinter = root.querySelector<HTMLButtonElement>('#btn-test-printer')!
+  const printerResultEl = root.querySelector<HTMLDivElement>('#printer-test-result')!
+
+  btnTestPrinter.addEventListener('click', async () => {
+    btnTestPrinter.disabled = true
+    btnTestPrinter.textContent = 'Testing…'
+    printerResultEl.hidden = true
+    printerResultEl.className = ''
+    try {
+      const { ok, body } = await getPrinterStatus()
+      if (ok) {
+        const ready = body.ready as boolean
+        const model = body.model as string | null
+        const loaded = body.loaded_media as Record<string, unknown> | null
+        const errors = (body.errors as string[]) ?? []
+        const source = body.source as string | null
+        const readyText = ready ? 'Ready' : 'Not ready'
+        const mediaText = loaded ? (loaded.display_name as string) : 'No media'
+        const modelText = model ?? 'Unknown model'
+        const errText = errors.length ? `<div class="status-msg error">${errors.join(', ')}</div>` : ''
+        printerResultEl.innerHTML = `
+          <div class="printer-status-block">
+            <span class="printer-status-ready ${ready ? 'ok' : 'warn'}">${readyText}</span>
+            <span class="printer-status-model">${modelText}</span>
+            <span class="printer-status-media">${mediaText}</span>
+            ${errText}
+            <span class="printer-status-source">${source ?? ''}</span>
+          </div>`
+        printerResultEl.className = 'status-msg success'
+      } else {
+        const msg = (body.message as string) || `HTTP error`
+        printerResultEl.textContent = msg
+        printerResultEl.className = 'status-msg error'
+      }
+    } catch (err) {
+      printerResultEl.textContent = (err as Error).message
+      printerResultEl.className = 'status-msg error'
+    } finally {
+      printerResultEl.hidden = false
+      btnTestPrinter.disabled = false
+      btnTestPrinter.textContent = 'Test Printer'
+    }
+  })
 
   function showStatus(msg: string, kind: 'success' | 'error'): void {
     statusEl.textContent = msg
diff --git a/prompts/done/2026-05-31-printer-status-build.md b/prompts/done/2026-05-31-printer-status-build.md
new file mode 100644
index 0000000..d75fadf
--- /dev/null
+++ b/prompts/done/2026-05-31-printer-status-build.md
@@ -0,0 +1,298 @@
+---
+name: 2026-05-31-printer-status-build
+status: completed
+created: 2026-05-31
+model: sonnet
+completed: 2026-05-31
+result: Added GET /api/printer/status (TCP+HTTP fallback), pre-print media check on all print routes, and Test Printer button in settings UI
+---
+
+# Task: Build the Printer Status feature
+
+Implement the Printer Status feature end-to-end as designed in `docs/features/printer-status.md`
+and `docs/features/api.md`. The spike in `prompts/done/2026-05-31-printer-status-spike.md`
+confirmed the mechanism and resolved the key risk; encode those findings here so this session
+doesn't need to re-research.
+
+## Before you start
+
+Read these docs (all needed for this task):
+- `docs/features/printer-status.md` — feature spec (API shape, print-path flow, edge cases)
+- `docs/features/api.md` — `GET /api/printer/status` 200/503 shapes; `media_mismatch` 409
+- `backend/labelforge/printer/client.py` — existing print path; status_read goes here
+- `backend/labelforge/config.py` — `printer_host`, `printer_backend`, `printer_model`
+- `backend/labelforge/settings_store.py:27-28` — `printer_status_check` and
+  `printer_status_timeout_ms` already registered; do NOT add them again
+- `docs/decisions.md` — the 2026-05-31 ADR for network status design
+
+Conventions: vexp `run_pipeline` first; `get_skeleton` over `Read`; no grep/glob.
+Commit prefix `feat:`; no `Co-authored-by:`; work on `dev`.
+
+## Working tree check
+
+Before making any edits, run `git status --porcelain` and cross-reference the files this
+plan touches. If any have uncommitted changes, list them and ask before touching. This file
+is exempt.
+
+## Spike findings (encode these — do not re-research)
+
+### Import paths verified against brother-ql-inventree 1.3
+
+```
+brother_ql.backends.helpers.get_status(printer, receive_only=False, target_status=None)
+    — sends b"\x1b\x69\x53" (ESC i S), calls printer.read(), parses via interpret_response()
+
+brother_ql.backends.helpers.backend_factory(backend_identifier)
+    — returns {"backend_class": BrotherQLBackendNetwork, "list_available_devices": ...}
+
+brother_ql.reader.interpret_response(data: bytes) -> dict
+    — parses 32-byte reply into {model, status_type, status_code, phase_type,
+      media_type, media_category, media_width, media_length, tape_color, errors, ...}
+    — IMPORTANT: tape_color is only parsed for media_category == "TZe".
+      For DK tapes (what QL-820NWB uses), tape_color == "".
+      Read data[24] raw for DK color detection.
+
+brother_ql.labels.ALL_LABELS
+    — list of Label objects; lbl.tape_size = (width_mm, length_mm); lbl.identifier = "62"
+    — lbl.color is Color.BLACK_WHITE (0) or Color.BLACK_RED_WHITE (1)
+    — "62" and "62red" both have tape_size=(62, 0); "62x29" has tape_size=(62, 29)
+```
+
+### Why get_printer() cannot be used
+
+`brother_ql.backends.helpers.get_printer()` raises `NotImplementedError` for
+`backend="network"` (intentional library design). Bypass by directly instantiating
+`BrotherQLBackendNetwork`:
+
+```python
+be = backend_factory("network")
+printer = be["backend_class"](f"tcp://{host}")
+```
+
+### Network backend default timeout
+
+`BrotherQLBackendNetwork.read_timeout = 0.01` (10 ms) — too short for a network round-trip.
+Override before calling `get_status()`:
+
+```python
+printer.read_timeout = timeout_s
+printer.s.settimeout(timeout_s)
+```
+
+### Live hardware test result
+
+The QL-820NWB at the configured host does **not respond** to ESC i S over port 9100,
+regardless of timeout (tested: 10 ms, 500 ms, 2 s, 5 s; raw socket and library path).
+The library itself confirms this ("network backend doesn't support readback" in `send()`).
+The TCP path is kept as primary anyway because it may work on different printer firmware
+or states. Callers must handle empty-byte response gracefully.
+
+### HTTP fallback
+
+`http://{host}/general/status.html` (redirected from `/`) responds without authentication.
+Parse `dt`/`dd` pairs:
+
+- `"Device&#32;Status"` dd contains: `"READY"` or error text inside `<span class="moni ...">`.
+- `"Media&#32;Status"` dd: `"Not&#32;Empty"` or `"Empty"`.
+- `"Media&#32;Type"` dd: `"62mm x 29mm / 2.4\" x 1.1\""` or similar.
+
+Media string format: `r"(\d+)mm\s*x\s*(\d+)mm"` extracts (width, length).
+For continuous tapes, the library shows "62mm x 0mm" or just "62mm" — verify and handle
+both. HTTP gives no color-capability info; report `color_capable: false` (unknown/safe default).
+
+## What to do
+
+### 1 — `status_read()` in `backend/labelforge/printer/client.py`
+
+Add `StatusUnavailable` exception and `status_read()` after the existing `PrintError` class.
+
+```python
+class StatusUnavailable(Exception):
+    pass
+
+def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
+    """
+    Query printer status. Returns a dict:
+      {
+        "ready": bool,
+        "model": str | None,
+        "media_id": str | None,      # library identifier, e.g. "62", "62x29", "62red"
+        "width_mm": int | None,
+        "length_mm": int | None,
+        "color_capable": bool,
+        "errors": list[str],
+        "source": "tcp" | "http",
+      }
+    Raises StatusUnavailable if both TCP and HTTP paths fail.
+    Only the "network" backend is supported; other backends raise StatusUnavailable immediately
+    (feature is limited to network-connected printers in v1).
+    """
+```
+
+**TCP path** (only when `backend == "network"`):
+- `backend_factory("network")["backend_class"](f"tcp://{host}")`
+- Set `printer.read_timeout` and `printer.s.settimeout` to `timeout_ms / 1000`
+- Wrap in `get_status(printer)` — but since `get_status` is defined in helpers.py and
+  re-imports `interpret_response`, call it directly; OR manually write/read and call
+  `interpret_response(data)` yourself (simpler, avoids the exception-before-assignment
+  bug in `get_status` when data is empty)
+- If `len(data) < 32`: skip TCP, fall to HTTP
+- Parse: `width = data[10]`, `length = data[17]`, `tape_color_raw = data[24]`
+- `media_id = _media_id_from_dims(width, length, tape_color_raw)`
+- Dispose the backend socket regardless
+
+**HTTP path** (fallback when TCP returns empty):
+- `urllib.request.urlopen(f"http://{host}/general/status.html", timeout=timeout_ms/1000)`
+- Use `html.parser` or regex to extract dt/dd pairs (no external deps)
+- Determine `ready` from Device Status text (READY → True; anything else → False)
+- Parse Media Type string for width/length → `_media_id_from_dims(width, length, None)`
+
+**Media ID helper** `_media_id_from_dims(width_mm, length_mm, tape_color_raw)`:
+- Search `ALL_LABELS` for `lbl.tape_size == (width_mm, length_mm)`
+- Special case continuous 62 mm: if `tape_color_raw is not None`, use raw byte to detect
+  two-color media (TODO: verify exact byte for DK-22251; default to "62" until hardware
+  confirms the DK red color byte); if `tape_color_raw is None` (HTTP path), return "62"
+- Return `None` if no match
+
+**`color_capable`**: derive from `label.color == Color.BLACK_RED_WHITE` once `media_id`
+is resolved via `ALL_LABELS`.
+
+Dispose the TCP socket in a `finally` block even if `interpret_response` throws.
+
+### 2 — Printer router: `backend/labelforge/routes/printer.py` (new file)
+
+```python
+router = APIRouter(tags=["printer"])
+
+@router.get("/printer/status")
+async def get_printer_status():
+    """
+    Returns printer status (200) or 503 if unreachable/timeout.
+    Response matches api.md shape:
+      {"ready": bool, "model": str|null, "loaded_media": {...}, "errors": [...]}
+    """
+```
+
+Map `status_read()` dict to the api.md 200 shape:
+```json
+{
+  "ready": true,
+  "model": "QL-820NWB",
+  "loaded_media": {
+    "id": "62x29",
+    "display_name": "62mm × 29mm (Die-cut)",
+    "width_mm": 62,
+    "length_mm": 29,
+    "color_capable": false
+  },
+  "errors": []
+}
+```
+
+On `StatusUnavailable`: return 503 `{"error": "status_unavailable", "message": "..."}`.
+
+`display_name` can come from the `labels.yml` catalog if the `media_id` is present there;
+fall back to `f"{width_mm}mm × {length_mm}mm"` (or `f"{width_mm}mm Continuous"` for
+length=0).
+
+No auth required (read-only, GET).
+
+### 3 — Register the printer router in `backend/labelforge/main.py`
+
+Currently no printer router is registered. Add:
+
+```python
+from labelforge.routes.printer import router as printer_router
+app.include_router(printer_router, prefix="/api")
+```
+
+Check `main.py` to find the pattern used for existing routers (templates, print, history,
+settings) and match it exactly.
+
+### 4 — Pre-print media check in `backend/labelforge/routes/print.py`
+
+In both `POST /api/print/quick` and `POST /api/print/{name}`, insert the status check
+**after rendering the label image** but **before calling `print_image()`**:
+
+```python
+# status check block
+settings = get_settings()  # or however settings are loaded in this route
+if settings.get("printer_status_check", True):
+    timeout_ms = settings.get("printer_status_timeout_ms", 2000)
+    try:
+        status = status_read(
+            host=config.printer_host,
+            backend=config.printer_backend,
+            timeout_ms=timeout_ms,
+        )
+        if status["errors"]:
+            raise HTTPException(409, {"error": "printer_error", "code": ..., "message": ..., "raw": status})
+        if status["media_id"] is not None:
+            expected_media = <label_media for this request>
+            if not _media_compatible(status["media_id"], expected_media):
+                if not request_override:
+                    raise HTTPException(409, {
+                        "error": "media_mismatch",
+                        "expected": expected_media,
+                        "loaded": status["media_id"],
+                        "override_allowed": true,
+                        "message": "..."
+                    })
+                # else: log warning and proceed
+    except StatusUnavailable:
+        logger.warning("Printer status unavailable; proceeding without check")
+```
+
+`_media_compatible(loaded_id, expected_id)`: two IDs are compatible when the loaded media
+can print the expected layout. Key rule from `printer-status.md`:
+- `"62"` and `"62red"` are compatible when the template uses only black (treat color
+  as a superset); `"62red"` loaded but template is `"62"` → allow.
+- `"62"` loaded but template is `"62red"` → block (silent mono output).
+- Anything else: exact string match.
+
+`override` parameter: check `?override=true` query param (or request body field —
+check how `api.md` specifies it; it says `?override=true` query string).
+
+For `batch` printing: apply the check once per batch, not per label.
+
+### 5 — Settings "Test printer" button (frontend)
+
+In the Settings page (`frontend/src/pages/settings.ts` or wherever settings UI lives):
+
+1. Add a **"Test printer"** button near the printer configuration section.
+2. On click: call `GET /api/printer/status` (with `Authorization: Bearer ...` header via
+   the existing `apiFetch` or similar helper).
+3. Render the result inline below the button:
+   - Success (200): show model, loaded media, ready state as a small info block.
+   - Error (503): show the error message in a warning chip.
+   - Always show the raw source ("tcp" or "http") in small/muted text for debugging.
+4. Clear the result when the settings form is saved or when the page unloads.
+
+Use whatever pattern the existing settings page uses for API calls and result display —
+do not introduce a new pattern.
+
+### 6 — Color capability detection note
+
+Implement `data[24]` reading for the TCP path as noted above. Add a `# TODO: verify
+DK-22251 tape_color_raw byte against hardware` comment where the condition appears. Until
+confirmed, the safe default is to return `"62"` (not `"62red"`) for continuous 62 mm
+when the byte value is ambiguous.
+
+## Conventions to honor
+
+- `run_pipeline` before any code changes; `get_skeleton` over `Read`.
+- No grep/glob while vexp daemon is healthy.
+- `feat:` commit prefix; no `Co-authored-by:`.
+- All work on `dev`. Commit, don't push.
+- Add a `CHANGELOG.md` entry under `## [Unreleased]`.
+- Verify imports: mirror the verified-imports comment block at the top of `client.py`
+  for any new library calls.
+- Do not add `printer_status_check` or `printer_status_timeout_ms` to `settings_store.py`
+  — they are already at lines 27-28.
+
+## When done
+
+1. Update this file's frontmatter: `status: completed`, `completed: 2026-05-31`,
+   `result: <one line>`.
+2. `git mv` this file into `prompts/done/`.
+3. Propose ONE commit: `feat: add printer status endpoint, pre-print media check, and Test printer UI`. File list + message → ask `commit these as "<message>"? (y/n)`. On y, stage specific paths only; commit on `dev`; never push.
diff --git a/prompts/done/2026-05-31-printer-status-spike.md b/prompts/done/2026-05-31-printer-status-spike.md
new file mode 100644
index 0000000..a95e709
--- /dev/null
+++ b/prompts/done/2026-05-31-printer-status-spike.md
@@ -0,0 +1,109 @@
+---
+name: 2026-05-31-printer-status-spike
+status: completed
+created: 2026-05-31
+model: sonnet
+completed: 2026-05-31
+result: ESC i S over port 9100 returns empty on QL-820NWB; get_printer() raises NotImplementedError for network; HTTP fallback at /general/status.html works unauthenticated; build prompt at prompts/2026-05-31-printer-status-build.md
+---
+
+# Task: Spike — can we read printer status over the `network` backend?
+
+Confirm whether `brother-ql-inventree` (>=1.3) can read the QL-820NWB's status
+(loaded media, ready state, errors) over the **network** backend before we commit
+the Printer Status feature design. This is the single highest-risk unknown for that
+feature, and it shapes the entire print-path design. **This is a spike: prove the
+mechanism and write up findings — do not build the feature in this session.**
+
+## Why this is in question
+
+`backend/labelforge/printer/client.py:50-54` states plainly that **the network
+backend cannot read back from the printer** — `send()` returns `'sent'` (transmitted,
+result unknown), and only USB backends confirm an actual print. But
+`docs/features/printer-status.md` assumes the QL-820NWB reports status *over its
+network interface*. These two claims are in tension, and production runs
+`printer_backend=network` (`config.py:11`). Resolve the contradiction with evidence.
+
+The raw-9100 socket is bidirectional in principle (send the status-request command
+`ESC i S` = `1B 69 53`, read the 32-byte reply), so it is *probably* achievable — but
+whether the library's `send()` / network backend surfaces that read is unverified, and
+the library is **not installed in the planning shell**, so it must be introspected in
+the real backend environment (the container or a venv with deps installed).
+
+## Before you start
+
+- Read `docs/features/printer-status.md` (the feature spec — status mapping, error
+  codes, API contract) and `docs/features/api.md` (the `GET /api/printer/status`
+  200/503 shapes and the `media_mismatch` 409 shape).
+- Read `backend/labelforge/printer/client.py` (current print path / send semantics)
+  and `backend/labelforge/config.py` (printer host/model/backend).
+- Settings keys already exist — `printer_status_check` and
+  `printer_status_timeout_ms` are registered in `settings_store.py:27-28`. Do not
+  re-add them.
+- Standards: this is research, so the main risk is the vexp/grep rule and the
+  commit-prefix rule — see `CLAUDE.md`. No feature code lands this session, so the
+  changelog entry is for the docs/decision only.
+
+## Working tree check
+
+Before making any edits, run `git status --porcelain` and cross-reference the files
+this plan touches (the new ADR in `docs/decisions.md`, this prompt, and the build
+prompt you'll author). If any have uncommitted changes, list them and ask before
+touching. This file is exempt.
+
+## What to do
+
+1. **Introspect the installed library** in an environment where deps are present
+   (the container, or `pip install -e .` into a venv). Determine concretely:
+   - Does `brother_ql.backends` expose a status-read path for the `network` backend?
+     Inspect `brother_ql.backends.helpers`, the network backend module, and any
+     `status` module/parser. Note exact import paths and function signatures (mirror
+     the verified-imports comment style at the top of `client.py`).
+   - Is there a parser that turns the 32-byte status reply into a structure like the
+     one in `printer-status.md` (media_type, media_width_mm, media_length_mm, model,
+     error_information, status_type)? If yes, name it. If not, scope the thin wrapper
+     we'd own.
+2. **Test against the real QL-820NWB** (network backend, the configured host). Send a
+   status request and capture the raw reply bytes. Confirm you can read back:
+   - loaded media type + width/length (→ mappable to a library identifier like `"62"`)
+   - ready / error state
+   - the tape-color byte (for DK red-capable detection — in v1 scope per the owner).
+   If reading back over `network` does **not** work, document exactly how it fails
+   (timeout? socket closed? no read API?) and what the fallback is (degrade
+   gracefully: skip check, proceed, log — per `printer-status.md` print-path flow).
+3. **Write up findings** in an ADR entry in `docs/decisions.md`: can we read status
+   over `network` (yes/no/partial), the exact import + call path, the status→library-id
+   mapping approach, color-capability detection feasibility, and the graceful-degrade
+   behavior when status is unavailable.
+4. **Author the build handoff prompt** `prompts/2026-05-31-printer-status-build.md`
+   from `prompts/TEMPLATE.md` (`model: sonnet`), encoding the confirmed design. Its
+   scope (all four, per owner decision):
+   - status-read fn in `printer/client.py` + `GET /api/printer/status` (200/503 per
+     `api.md`) + new printer router registered in `main.py` (note: `main.py` currently
+     registers no printer router — add `app.include_router(..., prefix="/api")`).
+   - pre-print media check in `routes/print.py`: compare loaded vs expected, `409
+     media_mismatch` with `override=true` escape hatch, graceful degrade on
+     timeout/unsupported (honor `printer_status_check` / `printer_status_timeout_ms`).
+   - Settings **Test printer** button (frontend) calling the status endpoint.
+   - color-capability detection (DK red) from the tape-color byte.
+   Hand the owner the exact run command for it (file-path form, sonnet model).
+
+## Conventions to honor
+
+- Don't `grep`/`glob` the codebase — `run_pipeline` first (vexp rule, `CLAUDE.md`).
+- Verify library import paths against the actually-installed version; mirror the
+  verified-imports comment block in `client.py`.
+- All work on `dev`. Commit, don't push. No `Co-authored-by:` trailers.
+- Add a one-line `CHANGELOG.md` entry under `## [Unreleased]` for the decision/ADR
+  if anything user-facing is implied; otherwise the ADR alone is fine for a spike.
+
+## When done
+
+1. Update this file's frontmatter: `status`, `completed` (the date), `result` (one line
+   — did network status-read work, and where the build prompt lives).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record the spike outcome as an ADR in `docs/decisions.md`.
+4. Propose ONE commit covering the files modified (ADR, the new build prompt, this
+   prompt's move). Present the file list + a one-line `docs:` or `chore:` message and
+   ask `commit these as "<message>"? (y/n)`. On `y`, stage those specific paths and
+   commit on `dev`. Never `git add -A`. Never push.

From 6efb5b47cff62dc2ad67fa9f75f00a013ed92a10 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 14:59:11 -0700
Subject: [PATCH 49/84] update

---
 .gitignore | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.gitignore b/.gitignore
index 63296bd..9e111c2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,6 +12,20 @@ __pycache__/
 .venv/
 venv/
 env/
+# uv is not this project's toolchain (Dockerfile uses pip + hatchling); lockfile is a local artifact
+uv.lock
+
+# Sandbox-mounted host dotfiles (not project files)
+.bash_profile
+.bashrc
+.gitconfig
+.gitmodules
+.idea
+.mcp.json
+.profile
+.ripgreprc
+.zprofile
+.zshrc
 
 # Build artifacts
 build/

From e009f6d595dfe0fa8cfdef77f8fff1b155eb45fb Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 16:17:47 -0700
Subject: [PATCH 50/84] feat: add "Loaded in printer" filter to label-media
 selectors

Adds a Show all / Loaded in printer toggle to every label-media dropdown
(Quick Print and New Template modal) via a shared mountLabelMediaSelect
control in labels.ts. Loaded mode queries GET /api/printer/status once,
filters to entries whose tape_size matches the mounted roll's dimensions,
and falls back to the full list with an inline notice if the printer is
unreachable, reports no media, or the loaded roll is not in the catalog.
---
 CHANGELOG.md                                  |   1 +
 docs/features/label-catalog.md                |  10 ++
 docs/features/printer-status.md               |   1 +
 frontend/src/api.ts                           |   6 +-
 frontend/src/labels.ts                        | 130 +++++++++++++++++-
 frontend/src/pages/quick-print.ts             |  32 ++---
 frontend/src/pages/templates-list.ts          |  28 ++--
 frontend/src/style.css                        |  48 +++++++
 frontend/src/types.ts                         |  15 ++
 ...2026-05-31-label-filter-by-loaded-media.md | 124 +++++++++++++++++
 10 files changed, 358 insertions(+), 37 deletions(-)
 create mode 100644 prompts/done/2026-05-31-label-filter-by-loaded-media.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fe38f1a..f4c2893 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Loaded-media filter on label selectors** — the label-media dropdown on Quick Print and the New Template modal now includes a "Show all / Loaded in printer" toggle; switching to Loaded queries the printer once and narrows options to the roll actually mounted (matching mono and two-color variants by dimension). Falls back to the full list with an inline notice if the printer is unreachable, reports no media, or the loaded roll is not in the catalog.
 - **Printer status check** — `GET /api/printer/status` returns loaded media, ready state, and errors; print endpoints (`POST /api/print/quick`, `/api/print/{name}`, `/api/print/{name}/batch`) block on media mismatch with a 409 (pass `?override=true` to proceed); Settings page "Test Printer" button shows live printer state. Status queried over raw TCP (ESC i S) with HTTP fallback to the printer's status page; degrades gracefully if unreachable. Controlled by `printer_status_check` and `printer_status_timeout_ms` settings.
 - **Print history page** — browse, reprint, pin, and delete past prints at `/history`; paginated reverse-chronological list with authenticated thumbnail previews, template/quick-print labels, field-value display, and filters (by template name, pinned-only toggle). Reprint creates a new job and refreshes the list; a 409 (template or media gone) surfaces the server's error message. Delete requires confirmation. Pin toggle updates inline without a reload. Retention policy configurable in `/settings` (keep forever / last N / last N days); pinned prints are never pruned; "Run cleanup now" triggers an immediate prune.
 - **Print history API** — every print is logged with a preview PNG; browse paginated history at `GET /api/history`, fetch full detail at `GET /api/history/{id}`, serve the preview image at `GET /api/history/{id}/preview.png`, reprint a past job at `POST /api/history/{id}/reprint` (creates a new row linked via `reprint_of`), pin/unpin at `POST /api/history/{id}/pin`, and delete at `DELETE /api/history/{id}`. Retention auto-pruning runs at startup and every 6 hours, honoring the `retention_mode` / `retention_count` / `retention_days` settings. Pinned rows are never pruned.
diff --git a/docs/features/label-catalog.md b/docs/features/label-catalog.md
index f6f31dd..66f1fc9 100644
--- a/docs/features/label-catalog.md
+++ b/docs/features/label-catalog.md
@@ -144,6 +144,16 @@ Reload on `SIGHUP` or via an admin endpoint (`POST /api/admin/reload-catalog`).
 - Color-capable labels show a small red/black indicator
 - Media the configured printer can't print (`supported = false`, see "Printer compatibility") stays visible in its group but is rendered as a **disabled, greyed `<option>`** with a `— unavailable` marker and a `title` tooltip carrying the `incompatible_reason`. The browser won't let a user pick a disabled option; selectors also guard programmatic default/restored selections, falling back to the first supported entry.
 
+### Loaded-media filter
+
+Every label-media selector exposes a **Show all / Loaded in printer** mode toggle (implemented as `mountLabelMediaSelect` in `frontend/src/labels.ts`, shared by all selectors). **Show all** (default) lists the complete catalog as described above. **Loaded in printer** calls `GET /api/printer/status` once on first use and narrows options to entries whose `tape_size` matches the loaded roll's `width_mm` and `length_mm` — this naturally groups the mono and two-color variants of a roll (e.g. `62` and `62red` both have `tape_size [62, 0]`) and excludes die-cuts of the same nominal width (`62x29` has `tape_size [62, 29]`).
+
+Edge cases in Loaded mode:
+- Printer unreachable (503) → notice "Couldn't reach printer — showing all"; toggle reverts to Show all.
+- Printer connected but no media reported → notice "Printer reports no media loaded"; toggle reverts to Show all.
+- Loaded media not found in catalog → notice "Loaded media not in catalog — showing all"; full list is shown with the toggle in Loaded position.
+- Printer status is fetched once per control mount and cached — the control does not poll.
+
 ## Defaults shipped in repo
 
 The repo ships a `labels.yml` covering the common DK-* media that match the QL-820NWB's supported list:
diff --git a/docs/features/printer-status.md b/docs/features/printer-status.md
index 47a7989..2abdcbb 100644
--- a/docs/features/printer-status.md
+++ b/docs/features/printer-status.md
@@ -123,6 +123,7 @@ HTTP/1.1 503 Service Unavailable
 - Settings page has a **Test printer** button that calls `GET /api/printer/status` and renders the result inline
 - Print form shows the currently-loaded media as a chip near the print button, polled lazily on form open (not every keystroke)
 - A media mismatch in the print response shows a modal: "Printer has X loaded, template expects Y. [Cancel] [Print anyway]"
+- Label-media selectors include a **Loaded in printer** filter mode (see [label-catalog.md](label-catalog.md#loaded-media-filter)) that queries this endpoint to narrow the dropdown to the mounted roll's matching catalog entries.
 
 ## Edge cases
 
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 822aad6..08cc2c7 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -1,4 +1,4 @@
-import type { BatchPrintResponse, FontInfo, HistoryDetail, HistoryItem, LabelEntry, PrintJobResponse, QuickPrintRequest, ReprintResponse, Template, TemplateCreate } from './types'
+import type { BatchPrintResponse, FontInfo, HistoryDetail, HistoryItem, LabelEntry, PrintJobResponse, PrinterStatus, QuickPrintRequest, ReprintResponse, Template, TemplateCreate } from './types'
 
 export const TOKEN_KEY = 'labelforge_token'
 
@@ -169,11 +169,11 @@ export function getSettings(): Promise<Record<string, unknown>> {
   return apiFetch<Record<string, unknown>>('/api/settings')
 }
 
-export async function getPrinterStatus(): Promise<{ ok: boolean; body: Record<string, unknown> }> {
+export async function getPrinterStatus(): Promise<{ ok: boolean; body: PrinterStatus & Record<string, unknown> }> {
   const res = await fetch('/api/printer/status', {
     headers: { Authorization: `Bearer ${getToken()}` },
   })
-  const body = await res.json() as Record<string, unknown>
+  const body = await res.json() as PrinterStatus & Record<string, unknown>
   return { ok: res.ok, body }
 }
 
diff --git a/frontend/src/labels.ts b/frontend/src/labels.ts
index 17dbc3f..d5dff4f 100644
--- a/frontend/src/labels.ts
+++ b/frontend/src/labels.ts
@@ -1,4 +1,5 @@
-import type { LabelEntry } from './types'
+import type { LabelEntry, PrinterStatus } from './types'
+import { getPrinterStatus } from './api'
 
 const FORM_FACTOR_LABEL: Record<number, string> = {
   1: 'Die-cut',
@@ -72,3 +73,130 @@ export function firstSupportedId(labels: LabelEntry[]): string | undefined {
   }
   return undefined
 }
+
+// True when label dimensions exactly match the loaded roll — groups mono and
+// two-color variants of the same width (e.g. 62 + 62red) and excludes die-cuts
+// of the same width (62x29 has length_mm=29, not 0).
+export function matchesLoadedMedia(label: LabelEntry, loaded: { width_mm: number; length_mm: number }): boolean {
+  return label.tape_size[0] === loaded.width_mm && label.tape_size[1] === loaded.length_mm
+}
+
+export interface LabelMediaSelectHandle {
+  getValue(): string
+  setValue(id: string): void
+}
+
+// Shared label-media selector with a "Show all / Loaded in printer" mode toggle.
+// Renders into `container`, populating via buildLabelOptionsHtml. Printer status
+// is fetched once on the first switch to Loaded mode and cached for the control's
+// lifetime.
+export function mountLabelMediaSelect(opts: {
+  container: HTMLElement
+  labels: LabelEntry[]
+  initialValue?: string
+  onChange: (id: string) => void
+}): LabelMediaSelectHandle {
+  const { container, labels, initialValue, onChange } = opts
+
+  container.innerHTML = `
+    <div class="media-filter-toggle">
+      <button type="button" class="media-filter-btn active" data-mode="all">Show all</button>
+      <button type="button" class="media-filter-btn" data-mode="loaded">Loaded in printer</button>
+    </div>
+    <select class="media-filter-select"></select>
+    <p class="media-filter-notice" hidden></p>
+  `
+
+  const toggleBtns = container.querySelectorAll<HTMLButtonElement>('.media-filter-btn')
+  const sel = container.querySelector<HTMLSelectElement>('.media-filter-select')!
+  const notice = container.querySelector<HTMLParagraphElement>('.media-filter-notice')!
+
+  let mode: 'all' | 'loaded' = 'all'
+  let cachedStatus: { ok: boolean; body: PrinterStatus & Record<string, unknown> } | null = null
+
+  // Populate select; prefers `preferValue` if supported, otherwise first supported entry.
+  function populate(list: LabelEntry[], preferValue?: string): void {
+    const target = preferValue !== undefined ? preferValue : sel.value
+    sel.innerHTML = buildLabelOptionsHtml(list)
+    const inList = list.find(l => l.id === target)
+    if (inList?.supported) {
+      sel.value = target
+    } else {
+      const fb = firstSupportedId(list)
+      if (fb) sel.value = fb
+    }
+  }
+
+  function setToggle(newMode: 'all' | 'loaded'): void {
+    mode = newMode
+    toggleBtns.forEach(btn => {
+      btn.classList.toggle('active', btn.dataset.mode === newMode)
+    })
+  }
+
+  // Initialize in Show-all mode
+  populate(labels, initialValue)
+
+  sel.addEventListener('change', () => onChange(sel.value))
+
+  toggleBtns.forEach(btn => {
+    btn.addEventListener('click', async () => {
+      const newMode = btn.dataset.mode as 'all' | 'loaded'
+      if (newMode === mode) return
+
+      if (newMode === 'all') {
+        setToggle('all')
+        populate(labels)
+        notice.hidden = true
+        onChange(sel.value)
+        return
+      }
+
+      // Switching to "Loaded in printer" — fetch once, then cache
+      if (!cachedStatus) {
+        btn.disabled = true
+        try {
+          cachedStatus = await getPrinterStatus()
+        } catch {
+          cachedStatus = { ok: false, body: { ready: false, model: '', loaded_media: null, errors: [] } as PrinterStatus & Record<string, unknown> }
+        } finally {
+          btn.disabled = false
+        }
+      }
+
+      if (!cachedStatus.ok) {
+        notice.textContent = "Couldn't reach printer — showing all"
+        notice.hidden = false
+        return  // stay in Show-all mode
+      }
+
+      const loaded = cachedStatus.body.loaded_media
+      if (!loaded) {
+        notice.textContent = 'Printer reports no media loaded'
+        notice.hidden = false
+        return  // stay in Show-all mode
+      }
+
+      const filtered = labels.filter(l => matchesLoadedMedia(l, loaded))
+      setToggle('loaded')
+
+      if (filtered.length === 0) {
+        populate(labels)
+        notice.textContent = 'Loaded media not in catalog — showing all'
+        notice.hidden = false
+      } else {
+        populate(filtered)
+        notice.hidden = true
+      }
+      onChange(sel.value)
+    })
+  })
+
+  return {
+    getValue: () => sel.value,
+    setValue: (id: string) => {
+      sel.value = id
+      onChange(id)
+    },
+  }
+}
diff --git a/frontend/src/pages/quick-print.ts b/frontend/src/pages/quick-print.ts
index 992dedf..e539c83 100644
--- a/frontend/src/pages/quick-print.ts
+++ b/frontend/src/pages/quick-print.ts
@@ -1,6 +1,6 @@
 import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api'
 import type { QuickPrintRequest } from '../types'
-import { buildLabelOptionsHtml, firstSupportedId } from '../labels'
+import { mountLabelMediaSelect, type LabelMediaSelectHandle } from '../labels'
 
 function esc(s: string): string {
   return s
@@ -63,8 +63,8 @@ function renderForm(root: HTMLElement): void {
         </div>
 
         <div>
-          <label for="label-media">Label media</label>
-          <select id="label-media"><option value="">Loading…</option></select>
+          <label>Label media</label>
+          <div id="label-media-container"></div>
         </div>
 
         <div>
@@ -107,7 +107,8 @@ function renderForm(root: HTMLElement): void {
   const textarea = root.querySelector<HTMLTextAreaElement>('#text')!
   const fontSelect = root.querySelector<HTMLSelectElement>('#font')!
   const fontSizeInput = root.querySelector<HTMLInputElement>('#font-size')!
-  const labelSelect = root.querySelector<HTMLSelectElement>('#label-media')!
+  const labelMediaContainer = root.querySelector<HTMLDivElement>('#label-media-container')!
+  let labelMediaHandle: LabelMediaSelectHandle | null = null
   const boldCheck = root.querySelector<HTMLInputElement>('#bold')!
   const italicCheck = root.querySelector<HTMLInputElement>('#italic')!
   const btnPreview = root.querySelector<HTMLButtonElement>('#btn-preview')!
@@ -146,7 +147,7 @@ function renderForm(root: HTMLElement): void {
       font_size: parseInt(fontSizeInput.value, 10),
       alignment,
       orientation,
-      label_media: labelSelect.value,
+      label_media: labelMediaHandle?.getValue() ?? '',
       bold: boldCheck.checked,
       italic: italicCheck.checked,
     }
@@ -184,14 +185,13 @@ function renderForm(root: HTMLElement): void {
       .map(f => `<option value="${esc(f.name)}">${esc(f.name)}</option>`)
       .join('')
 
-    labelSelect.innerHTML = buildLabelOptionsHtml(labels)
-
     // Restore form from settings; last_quick_print takes precedence over per-key defaults
     const lqp = (sett?.last_quick_print ?? null) as QuickPrintRequest | null
+    let preferMedia: string
     if (lqp) {
       fontSelect.value = lqp.font ?? String(sett?.default_font ?? 'DejaVuSans')
       fontSizeInput.value = String(lqp.font_size ?? sett?.default_font_size ?? 48)
-      labelSelect.value = String(lqp.label_media ?? sett?.default_label_media ?? '62')
+      preferMedia = String(lqp.label_media ?? sett?.default_label_media ?? '62')
       boldCheck.checked = lqp.bold ?? false
       italicCheck.checked = lqp.italic ?? false
       const aRadio = form.querySelector<HTMLInputElement>(
@@ -205,24 +205,22 @@ function renderForm(root: HTMLElement): void {
     } else {
       const defFont = String(sett?.default_font ?? 'DejaVuSans')
       const defSize = String(sett?.default_font_size ?? 48)
-      const defMedia = String(sett?.default_label_media ?? '62')
       const defOrientation = String(sett?.default_orientation ?? 'standard')
+      preferMedia = String(sett?.default_label_media ?? '62')
       fontSelect.value = defFont
       fontSizeInput.value = defSize
-      labelSelect.value = defMedia
       const oRadio = form.querySelector<HTMLInputElement>(
         `input[name="orientation"][value="${defOrientation}"]`
       )
       if (oRadio) oRadio.checked = true
     }
 
-    // The chosen default/restored media may be unsupported by the configured
-    // printer (its <option> is disabled). Fall back to the first supported id.
-    const chosen = labels.find(l => l.id === labelSelect.value)
-    if (!chosen || !chosen.supported) {
-      const fallback = firstSupportedId(labels)
-      if (fallback) labelSelect.value = fallback
-    }
+    labelMediaHandle = mountLabelMediaSelect({
+      container: labelMediaContainer,
+      labels,
+      initialValue: preferMedia,
+      onChange: () => {},
+    })
   }).catch((err: Error) => {
     showStatus(`Failed to load form data: ${err.message}`, 'error')
   })
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index 5a47353..d414971 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -1,7 +1,7 @@
 import { deleteTemplate, listTemplates } from '../api'
 import type { Template } from '../types'
 import { navigate } from '../router'
-import { buildLabelOptionsHtml, firstSupportedId } from '../labels'
+import { mountLabelMediaSelect, type LabelMediaSelectHandle } from '../labels'
 
 function esc(s: string): string {
   return s
@@ -130,10 +130,8 @@ function showNewTemplateModal(onCreated: () => void): void {
           <input id="modal-name" type="text" placeholder="my-template" autocomplete="off" />
           <span class="field-error" id="name-error" hidden></span>
         </label>
-        <label>
-          Label media
-          <select id="modal-media"><option value="">Loading…</option></select>
-        </label>
+        <label>Label media</label>
+        <div id="modal-media-container"></div>
         <div class="modal-actions">
           <button id="modal-cancel">Cancel</button>
           <button id="modal-ok" class="btn-primary" disabled>Create</button>
@@ -143,10 +141,11 @@ function showNewTemplateModal(onCreated: () => void): void {
     document.body.appendChild(overlay)
 
     const nameInput = overlay.querySelector<HTMLInputElement>('#modal-name')!
-    const mediaSelect = overlay.querySelector<HTMLSelectElement>('#modal-media')!
+    const mediaContainer = overlay.querySelector<HTMLDivElement>('#modal-media-container')!
     const cancelBtn = overlay.querySelector<HTMLButtonElement>('#modal-cancel')!
     const okBtn = overlay.querySelector<HTMLButtonElement>('#modal-ok')!
     const nameError = overlay.querySelector<HTMLSpanElement>('#name-error')!
+    let mediaHandle: LabelMediaSelectHandle | null = null
 
     const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
 
@@ -159,20 +158,17 @@ function showNewTemplateModal(onCreated: () => void): void {
     }
 
     function updateOk(): void {
-      okBtn.disabled = !nameInput.value.trim() || !mediaSelect.value
+      okBtn.disabled = !nameInput.value.trim() || !mediaHandle?.getValue()
     }
 
     nameInput.addEventListener('input', () => { validate(); updateOk() })
-    mediaSelect.addEventListener('change', updateOk)
 
     getLabels().then(labels => {
-      mediaSelect.innerHTML = buildLabelOptionsHtml(labels)
-      // Don't let the select default to a disabled (unsupported) option.
-      const chosen = labels.find(l => l.id === mediaSelect.value)
-      if (!chosen || !chosen.supported) {
-        const fallback = firstSupportedId(labels)
-        if (fallback) mediaSelect.value = fallback
-      }
+      mediaHandle = mountLabelMediaSelect({
+        container: mediaContainer,
+        labels,
+        onChange: () => updateOk(),
+      })
       updateOk()
     })
 
@@ -182,7 +178,7 @@ function showNewTemplateModal(onCreated: () => void): void {
     okBtn.addEventListener('click', () => {
       if (!validate()) return
       const name = nameInput.value.trim()
-      const media = mediaSelect.value
+      const media = mediaHandle?.getValue() ?? ''
       overlay.remove()
       // Navigate to editor — template created on first Save
       navigate(`/templates/${name}?new=1&media=${encodeURIComponent(media)}`)
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 7c3027a..1147673 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -606,6 +606,54 @@ button:disabled {
   margin-top: 0.75rem;
 }
 
+/* label media filter toggle */
+.media-filter-toggle {
+  display: flex;
+  margin-bottom: 0.35rem;
+}
+
+.media-filter-btn {
+  flex: 1;
+  padding: 0.3rem 0.6rem;
+  border: 1px solid #ccc;
+  background: #f5f5f5;
+  font: inherit;
+  font-size: 0.8rem;
+  cursor: pointer;
+  border-radius: 0;
+}
+
+.media-filter-btn:first-child {
+  border-radius: 4px 0 0 4px;
+}
+
+.media-filter-btn:last-child {
+  border-radius: 0 4px 4px 0;
+  border-left: none;
+}
+
+.media-filter-btn.active {
+  background: #1a6fdb;
+  color: #fff;
+  border-color: #1a6fdb;
+  font-weight: 600;
+}
+
+.media-filter-btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.media-filter-notice {
+  font-size: 0.78rem;
+  color: #2855a0;
+  background: #f0f4ff;
+  border: 1px solid #c0d0f0;
+  border-radius: 3px;
+  padding: 0.25rem 0.5rem;
+  margin: 0.3rem 0 0;
+}
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 1cd47f8..2ceaa8e 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -100,6 +100,21 @@ export interface HistoryDetail extends HistoryItem {
   payload_json: Record<string, unknown>;
 }
 
+export interface LoadedMedia {
+  id: string;
+  display_name: string;
+  width_mm: number;
+  length_mm: number;
+  color_capable: boolean;
+}
+
+export interface PrinterStatus {
+  ready: boolean;
+  model: string;
+  loaded_media: LoadedMedia | null;
+  errors: string[];
+}
+
 export interface ReprintResponse {
   job_id: number;
   status: string;
diff --git a/prompts/done/2026-05-31-label-filter-by-loaded-media.md b/prompts/done/2026-05-31-label-filter-by-loaded-media.md
new file mode 100644
index 0000000..98e31c8
--- /dev/null
+++ b/prompts/done/2026-05-31-label-filter-by-loaded-media.md
@@ -0,0 +1,124 @@
+---
+name: 2026-05-31-label-filter-by-loaded-media
+status: completed
+created: 2026-05-31
+model: sonnet
+completed: 2026-05-31
+result: Added mountLabelMediaSelect shared control with Show all / Loaded in printer toggle; wired up to Quick Print and New Template modal; tsc + build pass.
+---
+
+# Task: "Show all" vs "Loaded in printer" filter on the label-media selector
+
+Add a mode toggle to the label-media selector: **Show all** (default) lists the whole
+catalog as today; **Loaded in printer** queries the printer and narrows the options to
+the roll actually mounted. Build it as a **shared control in `labels.ts`** so every
+selector that uses it gets the behavior.
+
+## Before you start
+
+- Read `CLAUDE.md`. Load `docs/features/printer-status.md`, `docs/features/label-catalog.md`,
+  `docs/architecture.md`, `docs/glossary.md`.
+- `run_pipeline` first (vexp rule — don't grep/glob). Pass this task in.
+- Work on `dev`. Commit, don't push. No `Co-authored-by:` trailers.
+- This is **frontend-only** — the backend already provides everything (see Verified facts).
+
+## Working tree check
+
+Run `git status --porcelain` and cross-reference the files below. There may be an
+uncommitted `.gitignore` change unrelated to this work — surface it once as awareness,
+don't touch it. If any *frontend* file below is dirty, list it and ask before editing.
+This prompt file is exempt.
+
+## Decisions already made (do not relitigate)
+
+- **Scope: build it shared in `labels.ts`.** A reusable control both current selectors
+  (and future ones) call — not a per-page copy.
+- **Default mode is "Show all."** Loaded mode is opt-in per page load; no persistence
+  required.
+- **Match rule = same physical dimensions ("exact id + color sibling").** A label
+  matches the loaded media iff `label.tape_size[0] === loaded.width_mm &&
+  label.tape_size[1] === loaded.length_mm`. This naturally yields the mono + two-color
+  pair for one roll (e.g. loaded `62` → `62` **and** `62red`, both `tape_size [62, 0]`)
+  and excludes die-cut variants of the same width (`62x29` is `[62, 29]`). Match on
+  `tape_size`, **not** by string-munging the `red` suffix.
+
+## Verified facts (already in the codebase — don't rebuild)
+
+- `frontend/src/api.ts`:
+  - `getLabels(): Promise<LabelEntry[]>` → `GET /api/labels`.
+  - `getPrinterStatus(): Promise<{ ok: boolean; body: Record<string, unknown> }>` →
+    `GET /api/printer/status`. `ok` is false on 503/unreachable. On success `body`
+    includes `loaded_media` which is either `null` or
+    `{ id, display_name, width_mm, length_mm, color_capable }` (see
+    `backend/labelforge/routes/printer.py`).
+- `frontend/src/types.ts` `LabelEntry` has `id`, `tape_size: [number, number]`
+  (= `[width_mm, length_mm]`, length 0 = continuous), `color`, `supported`,
+  `incompatible_reason`, `display_name`.
+- `frontend/src/labels.ts` — `buildLabelOptionsHtml(labels)` is the SINGLE place
+  `<option>` markup is rendered (renders unsupported entries `disabled` + tooltip), and
+  `firstSupportedId(labels)` exists for default-selection fallback.
+- Call sites that pick label media: `frontend/src/pages/quick-print.ts` and the New
+  Template modal in `frontend/src/pages/templates-list.ts`. (Template editor has no
+  media selector.)
+
+## What to do
+
+### labels.ts — the shared control
+1. Add a match helper, e.g. `matchesLoadedMedia(label, loaded): boolean` returning
+   `label.tape_size[0] === loaded.width_mm && label.tape_size[1] === loaded.length_mm`.
+2. Add a reusable mount function (name your call, e.g.
+   `mountLabelMediaSelect(opts)`), that owns:
+   - a **mode toggle** (segmented buttons or radios: "Show all" | "Loaded in printer"),
+     defaulting to "Show all", rendered adjacent to the `<select>`;
+   - the `<select>`, populated via the existing `buildLabelOptionsHtml(...)` on the
+     **filtered** list (Show all = full list; Loaded = matches only);
+   - an inline **status/notice** line for the Loaded-mode edge cases below;
+   - selection management: an `onChange(id)` callback and the ability to read/set the
+     current value. When switching to Loaded mode, if the current selection isn't in the
+     filtered set, auto-select the first match.
+   Keep `buildLabelOptionsHtml` and `firstSupportedId` as the rendering/fallback
+   primitives — the control composes them.
+3. Loaded-mode behavior: call `getPrinterStatus()` **once** when the user switches to
+   Loaded (cache the result for the control's lifetime — do not poll). Then:
+   - `ok` + `loaded_media` present → filter to matches; if zero matches (loaded roll
+     isn't in the catalog), show notice "Loaded media not in catalog — showing all" and
+     fall back to the full list.
+   - `ok` + `loaded_media` null → notice "Printer reports no media loaded" + fall back
+     to Show all.
+   - `!ok` (unreachable/timeout) → notice "Couldn't reach printer — showing all" and
+     revert the toggle to Show all.
+   Never leave the user with a silently empty selector.
+
+### Wire up the call sites
+4. Refactor `quick-print.ts` and `templates-list.ts` (New Template modal) to use the
+   shared control instead of calling `buildLabelOptionsHtml` directly. Preserve current
+   behavior in Show-all mode: the `firstSupportedId` default/restore guard, and the
+   disabled/greyed unsupported rendering must still work.
+
+### Types / styles / docs
+5. If helpful, add a `PrinterStatus` / `LoadedMedia` interface to `types.ts` and type
+   `getPrinterStatus` against it (optional but preferred over `Record<string, unknown>`).
+6. Style the toggle + notice in `frontend/src/style.css`, matching existing controls.
+7. Update the relevant feature doc — add a short "loaded-media filter" note to
+   `docs/features/label-catalog.md` (UI behavior) and/or `docs/features/printer-status.md`
+   (UI section already mentions the loaded-media chip). Ship doc edits in the SAME commit.
+8. `CHANGELOG.md` `## [Unreleased]`: one concise user-facing line.
+9. Only add an ADR to `docs/decisions.md` if a non-obvious decision arises beyond the
+   dimensional match rule (which is captured here).
+
+## Verification
+
+- `cd frontend && npx tsc --noEmit && npm run build` must pass.
+- Manual (`npm run dev`): toggle to "Loaded in printer" with the printer reachable →
+  options narrow to the mounted roll (and its red/mono sibling); switch back → full
+  list. With the printer off/unreachable → notice shows and it stays on Show all.
+
+## When done
+
+1. Update this file's frontmatter: `status`, `completed` (date), `result` (one line).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record any non-obvious decision in `docs/decisions.md` as an ADR.
+4. Propose ONE commit on `dev` covering the modified files (incl. the prompt move).
+   Present the file list + a one-line `feat:` message and ask
+   `commit these as "<message>"? (y/n)`. Stage those specific paths only — never
+   `git add -A`, never push.

From 45c4fb472f15435e371441b4ed40dbf6f37ab73d Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sun, 31 May 2026 20:58:42 -0700
Subject: [PATCH 51/84] fix: print two-color rolls (62red) and stop false
 media-mismatch blocks

- print_image passes red=True + RGB image for two-color media (e.g. DK-2251),
  so the job declares two-color media; black-only text leaves the red plane empty
- media_compatible treats same-dimension rolls as compatible (status protocol
  can't distinguish 62 vs 62red); differing sizes still block
- frontend surfaces structured 409 error messages instead of [object Object]
- document that tape color is not detectable (verified vs Brother raster manual);
  add LOG_LEVEL=DEBUG raw-status diagnostic; ADR + dead TODO resolved
---
 CHANGELOG.md                         |  6 +++++
 backend/labelforge/printer/client.py | 32 +++++++++++++++++-----
 docs/decisions.md                    | 16 +++++++++++
 docs/features/printer-status.md      |  6 ++++-
 frontend/src/api.ts                  | 40 +++++++++++++++++++++++++---
 5 files changed, 88 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4c2893..5e27237 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 - **Adopted four crzynet engineering standards**, pinned in a new root `standards.md`: `code-checkin-and-pr @ 1.1.0` (commit messages now use Conventional-Commits prefixes `feat:`/`fix:`/`chore:`/`docs:`; CI gained structured-config and `docker compose config` validation jobs), `handoff-prompt-workflow @ 1.5.0` (completed handoff prompts now archived under `prompts/done/`; `prompts/TEMPLATE.md` added), `repo-sandbox-permissions @ 1.0.0` (repo-wide sandbox in `.claude/settings.json` — auto-approves in-repo work, gates out-of-repo writes and network), and `vexp-context-engine @ 2.1.0` (guard hook now tracked, `.vexpignore` added). Developer/process-facing only — no runtime behavior change.
 
+### Fixed
+
+- **Two-color rolls now print** — printing to a two-color roll (DK-2251, 62mm black/red continuous, id `62red`) was rejected by the printer as "wrong roll: check the print data" because the job declared mono media. The print path now passes `red=True` and an RGB image to the rasterizer for two-color media, so the job declares the correct media type. Black-only text prints fine on these rolls (the red plane is left empty).
+- **Pre-print media check no longer blocks same-size color variants** — the printer doesn't reliably report tape color, so the status read can't tell `62` from `62red` (both 62mm continuous) and was wrongly rejecting `62red` prints with a 409. The check now treats rolls of identical physical dimensions as compatible; mismatched sizes (e.g. 62 vs 29) still block.
+- **API error messages no longer show `[object Object]`** — the frontend now surfaces the human-readable `message` from structured `409` errors (media mismatch / printer error) instead of stringifying the whole object.
+
 ### Known Issues
 
 - QR and barcode template elements render in preview but print as a solid black block (1-bit threshold crushes fine detail). These elements are gated to raise a clear error until fixed. Text, lines, and rectangles print correctly.
diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
index ff68fa5..7b88955 100644
--- a/backend/labelforge/printer/client.py
+++ b/backend/labelforge/printer/client.py
@@ -61,8 +61,11 @@ def _media_id_from_dims(width_mm: int, length_mm: int, tape_color_raw: int | Non
     if len(matches) == 1:
         return matches[0].identifier
     # Multiple labels share the same tape_size (e.g. "62" and "62red" are both (62, 0)).
-    # TODO: verify DK-22251 tape_color_raw byte against hardware; default "62" until confirmed.
-    _ = tape_color_raw  # reserved for hardware-verified two-color detection
+    # Tape color is NOT recoverable: Brother's status spec leaves bytes 24-31 reserved
+    # (00h) and exposes no color field, so tape_color_raw is meaningless here. We default
+    # to mono "62"; the user selects "62red" manually and media_compatible() treats
+    # same-dimension rolls as compatible. See docs/decisions.md (2026-05-31, two-color DK).
+    _ = tape_color_raw  # always 00h per spec — kept for signature stability
     return "62"
 
 
@@ -112,13 +115,17 @@ def handle_data(self, data: str) -> None:
 def media_compatible(loaded_id: str, expected_id: str) -> bool:
     """Return True when the loaded media can print the expected layout.
 
-    62red is a superset of 62 — allow when more color capability is loaded
-    than the template needs. The reverse (mono loaded, color expected) blocks
-    because the print would silently drop the red channel.
+    Color-variant rolls of identical physical size (e.g. "62" and "62red", both
+    62mm continuous) are indistinguishable from the status read's dimensions
+    alone — the printer doesn't reliably report tape color over TCP/HTTP — so we
+    don't block on the color guess. The printer itself is the final authority on
+    a true media mismatch. Differing physical sizes (e.g. 62 vs 29) still block.
     """
     if loaded_id == expected_id:
         return True
-    if loaded_id == "62red" and expected_id == "62":
+    loaded = next((lbl for lbl in ALL_LABELS if lbl.identifier == loaded_id), None)
+    expected = next((lbl for lbl in ALL_LABELS if lbl.identifier == expected_id), None)
+    if loaded is not None and expected is not None and loaded.tape_size == expected.tape_size:
         return True
     return False
 
@@ -166,6 +173,10 @@ def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
     except Exception as exc:
         logger.debug("TCP status path failed: %s", exc)
 
+    # Diagnostic: dumps the raw ESC i S status response as hex. Only emitted when
+    # LOG_LEVEL=DEBUG. Handy for inspecting undocumented bytes (e.g. probing
+    # whether a byte encodes tape color); see docs/features/printer-status.md.
+    logger.debug("TCP status raw (%d bytes): %s", len(raw), raw.hex())
     if len(raw) >= 32:
         try:
             parsed = interpret_response(raw)
@@ -247,11 +258,18 @@ def print_image(
     """
     try:
         qlr = BrotherQLRaster(model)
+        # Two-color media (e.g. "62red" / DK-2251) must be printed with red=True
+        # even for black-only text: the job has to declare two-color media or the
+        # printer rejects it as "wrong roll: check the print data". convert() reads
+        # the red plane from an RGB image, so promote L→RGB; a black-on-white image
+        # simply leaves the red plane empty.
+        red = _color_capable(label_media)
+        img = image.convert("RGB") if red else image
         # rotate=0: keep the rendered image's width (696px for 62mm) as the
         # print-head width. rotate='auto' (the library default) can flip a
         # wide continuous image into a geometry the printer reads as the wrong
         # roll type. The renderer already produces the correct orientation.
-        instructions = convert(qlr, [image], label_media, cut=True, rotate="0", threshold=PRINT_THRESHOLD)
+        instructions = convert(qlr, [img], label_media, cut=True, rotate="0", threshold=PRINT_THRESHOLD, red=red)
         identifier = f"tcp://{host}" if backend == "network" else host
         result = send(
             instructions=instructions,
diff --git a/docs/decisions.md b/docs/decisions.md
index 9c10a69..e7194ad 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,22 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-05-31 — Two-color DK rolls: print with `red=True`; tape color is not detectable from status
+
+**Decision**:
+- `print_image()` passes `red=True` and an RGB image to `brother_ql.convert()` whenever the selected media is a two-color label (e.g. `62red` / DK-2251), even for black-only content. Without it the job declares mono media and the printer rejects it on the LCD as "Wrong roll: check the print data".
+- The pre-print `media_compatible()` check treats rolls of identical physical dimensions (`tape_size`) as compatible rather than blocking on a guessed color. Differing sizes (e.g. 62 vs 29) still block.
+
+**Why**: The QL-800/810W/820NWB status protocol does **not** report tape/media color. Verified against Brother's official *Raster Command Reference QL-800/810W/820NWB*: the 32-byte `ESC i S` response carries media width (byte 10), media type = continuous/die-cut (byte 11), and media length (byte 17) only; bytes 12–14, 16, 23 and **24–31 are reserved/fixed `00h`**. The strings "tape color", "text color", "media color" do not appear in the document. The printer enforces the correct DK roll at print time by sensing the physical roll, but never surfaces color in status. So `62` and `62red` (both 62mm continuous, `tape_size (62, 0)`) are indistinguishable from a status read — the earlier plan to read `data[24]` for color (see the ESC i S ADR below) is not viable; that byte is always `00h`.
+
+**Considered**: (a) read `data[24]` for color — rejected, reserved `00h` per spec; (b) scrape the printer's `status.html` — rejected, it doesn't show color either; (c) key off the DK part number — we don't pass DK numbers to the library and can't read the loaded roll's part number.
+
+**Consequence**: The user picks `62` vs `62red` manually; the status panel labels a 62mm continuous roll generically. The "Loaded in printer" filter offers both same-size variants. A `red=True` job prints black-only fine (red plane left empty).
+
+**Would revisit if**: a future firmware/model exposes media color in the status response, or the library gains reliable DK color reading.
+
+---
+
 ## 2026-05-31 — Printer status over network: ESC i S unreliable; implement raw-TCP + HTTP fallback
 
 **Decision**: The Printer Status feature will use a two-path `status_read()` function in `printer/client.py`:
diff --git a/docs/features/printer-status.md b/docs/features/printer-status.md
index 2abdcbb..f0548ae 100644
--- a/docs/features/printer-status.md
+++ b/docs/features/printer-status.md
@@ -70,7 +70,11 @@ The library returns raw bytes from the printer's status protocol. The library's
 
 We need a mapping function: `(media_type, media_width_mm, media_length_mm) → library_identifier` (e.g. `"62"` or `"62x100"`). This logic exists in the library or close to it; if not, it's a thin wrapper we own.
 
-Color capability of the loaded media (whether it's DK-22251 red-capable or DK-22205 mono): the printer reports tape type and the library should distinguish. If it doesn't expose this directly, we read the raw status bytes — there's a specific tape-color byte.
+**Tape color is not detectable.** Verified against Brother's *Raster Command Reference QL-800/810W/820NWB*: the 32-byte status response has no color field (bytes 24–31 are reserved `00h`), and the printer's `status.html` doesn't show it either. So `62` (mono, DK-22205) and `62red` (two-color, DK-22251) are indistinguishable from a status read — both are 62mm continuous, `tape_size (62, 0)`. We default an ambiguous (62, 0) read to `"62"` and rely on the user selecting `62red` manually; the pre-print check treats same-dimension rolls as compatible so it doesn't block the choice. See `docs/decisions.md` (2026-05-31, two-color DK rolls). To print on a two-color roll, `print_image()` passes `red=True` + an RGB image so the job declares two-color media; black-only text leaves the red plane empty.
+
+## Diagnostics
+
+Set `LOG_LEVEL=DEBUG` to log the raw `ESC i S` status response as hex (`TCP status raw (N bytes): …` in `status_read`). Useful for inspecting media width/type/length bytes and error flags on unfamiliar firmware. If `N < 32`, the printer isn't returning TCP status and the HTTP `status.html` fallback is used instead.
 
 ## Error reporting
 
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 08cc2c7..a59f536 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -19,7 +19,15 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
     let detail = `HTTP ${res.status}`
     try {
       const body = await res.json() as { detail?: unknown }
-      if (body.detail) detail = String(body.detail)
+      const d = body.detail
+      if (typeof d === 'string') {
+        detail = d
+      } else if (d && typeof d === 'object' && typeof (d as { message?: unknown }).message === 'string') {
+        // structured errors (e.g. 409 media_mismatch / printer_error) carry a human message
+        detail = (d as { message: string }).message
+      } else if (d != null) {
+        detail = JSON.stringify(d)
+      }
     } catch { /* use status fallback */ }
     throw new Error(detail)
   }
@@ -55,7 +63,15 @@ export async function previewQuick(req: QuickPrintRequest): Promise<Blob> {
     let detail = `HTTP ${res.status}`
     try {
       const body = await res.json() as { detail?: unknown }
-      if (body.detail) detail = String(body.detail)
+      const d = body.detail
+      if (typeof d === 'string') {
+        detail = d
+      } else if (d && typeof d === 'object' && typeof (d as { message?: unknown }).message === 'string') {
+        // structured errors (e.g. 409 media_mismatch / printer_error) carry a human message
+        detail = (d as { message: string }).message
+      } else if (d != null) {
+        detail = JSON.stringify(d)
+      }
     } catch { /* use status fallback */ }
     throw new Error(detail)
   }
@@ -101,7 +117,15 @@ export async function previewTemplate(name: string, fields: Record<string, strin
     let detail = `HTTP ${res.status}`
     try {
       const body = await res.json() as { detail?: unknown }
-      if (body.detail) detail = String(body.detail)
+      const d = body.detail
+      if (typeof d === 'string') {
+        detail = d
+      } else if (d && typeof d === 'object' && typeof (d as { message?: unknown }).message === 'string') {
+        // structured errors (e.g. 409 media_mismatch / printer_error) carry a human message
+        detail = (d as { message: string }).message
+      } else if (d != null) {
+        detail = JSON.stringify(d)
+      }
     } catch { /* use status fallback */ }
     throw new Error(detail)
   }
@@ -139,7 +163,15 @@ export async function fetchHistoryPreview(id: number): Promise<Blob> {
     let detail = `HTTP ${res.status}`
     try {
       const body = await res.json() as { detail?: unknown }
-      if (body.detail) detail = String(body.detail)
+      const d = body.detail
+      if (typeof d === 'string') {
+        detail = d
+      } else if (d && typeof d === 'object' && typeof (d as { message?: unknown }).message === 'string') {
+        // structured errors (e.g. 409 media_mismatch / printer_error) carry a human message
+        detail = (d as { message: string }).message
+      } else if (d != null) {
+        detail = JSON.stringify(d)
+      }
     } catch { /* use status fallback */ }
     throw new Error(detail)
   }

From c7b166446ed19b6f83b5f1efec582c36f852b96e Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 1 Jun 2026 20:42:39 -0700
Subject: [PATCH 52/84] feat: add printer status-check toggle and timeout to
 Settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The printer_status_check and printer_status_timeout_ms settings were
backend-only with no UI; the Settings → Printer section now exposes a
toggle and a timeout field, populated from getSettings and saved via PUT.
---
 CHANGELOG.md                   |  1 +
 frontend/src/pages/settings.ts | 50 +++++++++++++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5e27237..762cc90 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Printer status controls in Settings** — the Settings → Printer section now has a "Status check enabled" toggle and a status-timeout (ms) field, wired to the `printer_status_check` / `printer_status_timeout_ms` settings. These existed only on the backend before, with no way to change them from the UI.
 - **Loaded-media filter on label selectors** — the label-media dropdown on Quick Print and the New Template modal now includes a "Show all / Loaded in printer" toggle; switching to Loaded queries the printer once and narrows options to the roll actually mounted (matching mono and two-color variants by dimension). Falls back to the full list with an inline notice if the printer is unreachable, reports no media, or the loaded roll is not in the catalog.
 - **Printer status check** — `GET /api/printer/status` returns loaded media, ready state, and errors; print endpoints (`POST /api/print/quick`, `/api/print/{name}`, `/api/print/{name}/batch`) block on media mismatch with a 409 (pass `?override=true` to proceed); Settings page "Test Printer" button shows live printer state. Status queried over raw TCP (ESC i S) with HTTP fallback to the printer's status page; degrades gracefully if unreachable. Controlled by `printer_status_check` and `printer_status_timeout_ms` settings.
 - **Print history page** — browse, reprint, pin, and delete past prints at `/history`; paginated reverse-chronological list with authenticated thumbnail previews, template/quick-print labels, field-value display, and filters (by template name, pinned-only toggle). Reprint creates a new job and refreshes the list; a 409 (template or media gone) surfaces the server's error message. Delete requires confirmation. Pin toggle updates inline without a reload. Retention policy configurable in `/settings` (keep forever / last N / last N days); pinned prints are never pruned; "Run cleanup now" triggers an immediate prune.
diff --git a/frontend/src/pages/settings.ts b/frontend/src/pages/settings.ts
index 586bbf9..db0eea2 100644
--- a/frontend/src/pages/settings.ts
+++ b/frontend/src/pages/settings.ts
@@ -6,6 +6,7 @@ export function mountSettings(root: HTMLElement): void {
       <h2>Settings</h2>
       <section class="settings-section">
         <h3>Printer</h3>
+        <div id="printer-settings"><p>Loading…</p></div>
         <div class="setting-actions">
           <button id="btn-test-printer">Test Printer</button>
         </div>
@@ -23,6 +24,7 @@ export function mountSettings(root: HTMLElement): void {
   const formEl = root.querySelector<HTMLDivElement>('#retention-form')!
   const btnTestPrinter = root.querySelector<HTMLButtonElement>('#btn-test-printer')!
   const printerResultEl = root.querySelector<HTMLDivElement>('#printer-test-result')!
+  const printerSettingsEl = root.querySelector<HTMLDivElement>('#printer-settings')!
 
   btnTestPrinter.addEventListener('click', async () => {
     btnTestPrinter.disabled = true
@@ -153,7 +155,53 @@ export function mountSettings(root: HTMLElement): void {
     })
   }
 
+  function renderPrinterSettings(settings: Record<string, unknown>): void {
+    const checkEnabled = settings.printer_status_check !== false
+    const timeout = (settings.printer_status_timeout_ms as number) ?? 2000
+
+    printerSettingsEl.innerHTML = `
+      <label class="setting-row">
+        <input type="checkbox" id="status-check-enabled" ${checkEnabled ? 'checked' : ''} />
+        <span class="setting-row-label">Status check enabled</span>
+        <span class="setting-hint">query the printer before each print</span>
+      </label>
+      <div class="setting-row">
+        <span class="setting-row-label">Status timeout</span>
+        <input type="number" id="status-timeout" min="100" max="60000" step="100" value="${timeout}" />
+        <span class="setting-hint">ms to wait for a status response</span>
+      </div>
+      <div class="setting-actions">
+        <button id="btn-save-printer" class="btn-primary">Save</button>
+      </div>
+      <div id="printer-save-status" class="status-msg" hidden></div>
+    `
+
+    const checkbox = printerSettingsEl.querySelector<HTMLInputElement>('#status-check-enabled')!
+    const timeoutInput = printerSettingsEl.querySelector<HTMLInputElement>('#status-timeout')!
+    const btnSavePrinter = printerSettingsEl.querySelector<HTMLButtonElement>('#btn-save-printer')!
+    const printerSaveStatus = printerSettingsEl.querySelector<HTMLDivElement>('#printer-save-status')!
+
+    btnSavePrinter.addEventListener('click', async () => {
+      btnSavePrinter.disabled = true
+      printerSaveStatus.hidden = true
+      try {
+        await putSettings({
+          printer_status_check: checkbox.checked,
+          printer_status_timeout_ms: parseInt(timeoutInput.value, 10) || 2000,
+        })
+        printerSaveStatus.textContent = 'Printer settings saved.'
+        printerSaveStatus.className = 'status-msg success'
+      } catch (err) {
+        printerSaveStatus.textContent = (err as Error).message
+        printerSaveStatus.className = 'status-msg error'
+      } finally {
+        printerSaveStatus.hidden = false
+        btnSavePrinter.disabled = false
+      }
+    })
+  }
+
   getSettings()
-    .then(s => renderForm(s))
+    .then(s => { renderForm(s); renderPrinterSettings(s) })
     .catch(err => showStatus((err as Error).message, 'error'))
 }

From 65dd292e0179aeac43d3f7e8dafb9612d30934f7 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 1 Jun 2026 20:47:57 -0700
Subject: [PATCH 53/84] feat: note color-detection limit on the loaded-media
 picker

When 'Loaded in printer' matches same-size mono/two-color variants
(e.g. 62 / 62red), show a note above the picker explaining the printer
can't report tape color so the variant must be picked manually.
---
 CHANGELOG.md           |  1 +
 frontend/src/labels.ts |  8 ++++++++
 frontend/src/style.css | 17 +++++++++++++++++
 3 files changed, 26 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 762cc90..b10419a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Color-limitation note on the label picker** — when "Loaded in printer" matches a roll that has both mono and two-color variants of the same size (e.g. `62` / `62red`), a note above the picker explains that the printer doesn't report tape color, so the right variant must be chosen manually.
 - **Printer status controls in Settings** — the Settings → Printer section now has a "Status check enabled" toggle and a status-timeout (ms) field, wired to the `printer_status_check` / `printer_status_timeout_ms` settings. These existed only on the backend before, with no way to change them from the UI.
 - **Loaded-media filter on label selectors** — the label-media dropdown on Quick Print and the New Template modal now includes a "Show all / Loaded in printer" toggle; switching to Loaded queries the printer once and narrows options to the roll actually mounted (matching mono and two-color variants by dimension). Falls back to the full list with an inline notice if the printer is unreachable, reports no media, or the loaded roll is not in the catalog.
 - **Printer status check** — `GET /api/printer/status` returns loaded media, ready state, and errors; print endpoints (`POST /api/print/quick`, `/api/print/{name}`, `/api/print/{name}/batch`) block on media mismatch with a 409 (pass `?override=true` to proceed); Settings page "Test Printer" button shows live printer state. Status queried over raw TCP (ESC i S) with HTTP fallback to the printer's status page; degrades gracefully if unreachable. Controlled by `printer_status_check` and `printer_status_timeout_ms` settings.
diff --git a/frontend/src/labels.ts b/frontend/src/labels.ts
index d5dff4f..3565fb1 100644
--- a/frontend/src/labels.ts
+++ b/frontend/src/labels.ts
@@ -103,6 +103,7 @@ export function mountLabelMediaSelect(opts: {
       <button type="button" class="media-filter-btn active" data-mode="all">Show all</button>
       <button type="button" class="media-filter-btn" data-mode="loaded">Loaded in printer</button>
     </div>
+    <p class="media-filter-colornote" hidden>The printer doesn't report tape color, so "Loaded in printer" can't tell a two-color roll (e.g. <code>62red</code>) from its mono equivalent — both same-size variants are shown. Pick the one that matches your roll.</p>
     <select class="media-filter-select"></select>
     <p class="media-filter-notice" hidden></p>
   `
@@ -110,6 +111,7 @@ export function mountLabelMediaSelect(opts: {
   const toggleBtns = container.querySelectorAll<HTMLButtonElement>('.media-filter-btn')
   const sel = container.querySelector<HTMLSelectElement>('.media-filter-select')!
   const notice = container.querySelector<HTMLParagraphElement>('.media-filter-notice')!
+  const colorNote = container.querySelector<HTMLParagraphElement>('.media-filter-colornote')!
 
   let mode: 'all' | 'loaded' = 'all'
   let cachedStatus: { ok: boolean; body: PrinterStatus & Record<string, unknown> } | null = null
@@ -148,6 +150,7 @@ export function mountLabelMediaSelect(opts: {
         setToggle('all')
         populate(labels)
         notice.hidden = true
+        colorNote.hidden = true
         onChange(sel.value)
         return
       }
@@ -167,6 +170,7 @@ export function mountLabelMediaSelect(opts: {
       if (!cachedStatus.ok) {
         notice.textContent = "Couldn't reach printer — showing all"
         notice.hidden = false
+        colorNote.hidden = true
         return  // stay in Show-all mode
       }
 
@@ -174,6 +178,7 @@ export function mountLabelMediaSelect(opts: {
       if (!loaded) {
         notice.textContent = 'Printer reports no media loaded'
         notice.hidden = false
+        colorNote.hidden = true
         return  // stay in Show-all mode
       }
 
@@ -184,9 +189,12 @@ export function mountLabelMediaSelect(opts: {
         populate(labels)
         notice.textContent = 'Loaded media not in catalog — showing all'
         notice.hidden = false
+        colorNote.hidden = true
       } else {
         populate(filtered)
         notice.hidden = true
+        // Only relevant when same-size mono/two-color variants are both shown.
+        colorNote.hidden = filtered.length <= 1
       }
       onChange(sel.value)
     })
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 1147673..2fd1756 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -654,6 +654,23 @@ button:disabled {
   margin: 0.3rem 0 0;
 }
 
+.media-filter-colornote {
+  font-size: 0.78rem;
+  color: #8a5a00;
+  background: #fff7e6;
+  border: 1px solid #f0d8a0;
+  border-radius: 3px;
+  padding: 0.25rem 0.5rem;
+  margin: 0.3rem 0;
+}
+
+.media-filter-colornote code {
+  font-size: 0.95em;
+  background: rgba(0, 0, 0, 0.05);
+  padding: 0 0.2em;
+  border-radius: 2px;
+}
+
 /* token gate */
 .token-gate input[type="password"] {
   width: 100%;

From 0feaf4861263d90a22e45226427f89bb1be6f0b8 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Mon, 1 Jun 2026 20:51:41 -0700
Subject: [PATCH 54/84] docs: note Brother P-touch Editor also requires manual
 DK color selection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Corroborates the two-color ADR — the QL/DK hardware exposes no color, so
even Brother's own software needs manual BK-RD vs Monochrome selection.
---
 docs/decisions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/decisions.md b/docs/decisions.md
index e7194ad..d32fe22 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -10,7 +10,7 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 - `print_image()` passes `red=True` and an RGB image to `brother_ql.convert()` whenever the selected media is a two-color label (e.g. `62red` / DK-2251), even for black-only content. Without it the job declares mono media and the printer rejects it on the LCD as "Wrong roll: check the print data".
 - The pre-print `media_compatible()` check treats rolls of identical physical dimensions (`tape_size`) as compatible rather than blocking on a guessed color. Differing sizes (e.g. 62 vs 29) still block.
 
-**Why**: The QL-800/810W/820NWB status protocol does **not** report tape/media color. Verified against Brother's official *Raster Command Reference QL-800/810W/820NWB*: the 32-byte `ESC i S` response carries media width (byte 10), media type = continuous/die-cut (byte 11), and media length (byte 17) only; bytes 12–14, 16, 23 and **24–31 are reserved/fixed `00h`**. The strings "tape color", "text color", "media color" do not appear in the document. The printer enforces the correct DK roll at print time by sensing the physical roll, but never surfaces color in status. So `62` and `62red` (both 62mm continuous, `tape_size (62, 0)`) are indistinguishable from a status read — the earlier plan to read `data[24]` for color (see the ESC i S ADR below) is not viable; that byte is always `00h`.
+**Why**: The QL-800/810W/820NWB status protocol does **not** report tape/media color. Verified against Brother's official *Raster Command Reference QL-800/810W/820NWB*: the 32-byte `ESC i S` response carries media width (byte 10), media type = continuous/die-cut (byte 11), and media length (byte 17) only; bytes 12–14, 16, 23 and **24–31 are reserved/fixed `00h`**. The strings "tape color", "text color", "media color" do not appear in the document. The printer enforces the correct DK roll at print time by sensing the physical roll, but never surfaces color in status. So `62` and `62red` (both 62mm continuous, `tape_size (62, 0)`) are indistinguishable from a status read — the earlier plan to read `data[24]` for color (see the ESC i S ADR below) is not viable; that byte is always `00h`. Brother's own P-touch Editor doesn't auto-detect DK color either: the user manually picks the roll and a BK-RD vs Monochrome mode, and selecting Monochrome on a DK-2251 produces the same printer-side "wrong roll type" error ([Brother FAQ a_id/142492](https://help.brother-usa.com/app/answers/detail/a_id/142492/)). (Color *is* auto-detected on P-touch label makers, but only because TZe tape cassettes are physically keyed — DK rolls have no such keying.)
 
 **Considered**: (a) read `data[24]` for color — rejected, reserved `00h` per spec; (b) scrape the printer's `status.html` — rejected, it doesn't show color either; (c) key off the DK part number — we don't pass DK numbers to the library and can't read the loaded roll's part number.
 

From a8fa2a925e509efe58daa839b5bcece042ac1538 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 2 Jun 2026 06:58:15 -0700
Subject: [PATCH 55/84] fix: render Fabric v6 template elements (PascalCase
 type names)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fabric.js v6 serializes element `type` as the PascalCase class name
(IText, Line, Image) where v5 used lowercase/hyphenated (i-text). The
server renderer and detect_fields still matched the v5 names, so every
text element was skipped — previews/prints came out blank and no
variable fields were detected. Normalize the type (lowercase, strip
hyphen) in both, and apply the same fix to the editor's font controls.
---
 CHANGELOG.md                           |  2 +-
 backend/labelforge/render/template.py  | 11 +++++++----
 backend/labelforge/templates/fields.py |  5 +++--
 frontend/src/editor/canvas.ts          | 12 +++++++++++-
 frontend/src/pages/template-editor.ts  |  7 ++++---
 5 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b10419a..0394162 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Fixed
 
-- **Two-color rolls now print** — printing to a two-color roll (DK-2251, 62mm black/red continuous, id `62red`) was rejected by the printer as "wrong roll: check the print data" because the job declared mono media. The print path now passes `red=True` and an RGB image to the rasterizer for two-color media, so the job declares the correct media type. Black-only text prints fine on these rolls (the red plane is left empty).
+- **Template text now renders and prints** — the canvas editor uses Fabric.js v6, which serializes element types as PascalCase class names (`IText`, `Line`, `Image`); the server renderer and field detection still matched the Fabric v5 lowercase/hyphenated names (`i-text`), so every text element was silently skipped — previews and prints of any template came out blank and no variable fields were detected. Both now normalize the type (lowercase, strip hyphen) and handle v5 and v6 serializations. The editor's font family/size controls (which had the same mismatch) again update the selected text. The frontend fix requires a container image rebuild to take effect; the renderer/field-detection fix is backend-only. — printing to a two-color roll (DK-2251, 62mm black/red continuous, id `62red`) was rejected by the printer as "wrong roll: check the print data" because the job declared mono media. The print path now passes `red=True` and an RGB image to the rasterizer for two-color media, so the job declares the correct media type. Black-only text prints fine on these rolls (the red plane is left empty).
 - **Pre-print media check no longer blocks same-size color variants** — the printer doesn't reliably report tape color, so the status read can't tell `62` from `62red` (both 62mm continuous) and was wrongly rejecting `62red` prints with a 409. The check now treats rolls of identical physical dimensions as compatible; mismatched sizes (e.g. 62 vs 29) still block.
 - **API error messages no longer show `[object Object]`** — the frontend now surfaces the human-readable `message` from structured `409` errors (media mismatch / printer error) instead of stringifying the whole object.
 
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index e53405c..588d3e9 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -196,6 +196,9 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
 
     for obj in objects:
         obj_type = obj.get("type", "")
+        # Fabric v6 serializes `type` as the PascalCase class name (IText, Line,
+        # Rect, Image); v5 used lowercase/hyphenated (i-text). Normalize both.
+        norm_type = obj_type.lower().replace("-", "")
         left = int(obj.get("left", 0))
         top = int(obj.get("top", 0))
         angle = float(obj.get("angle", 0))
@@ -203,11 +206,11 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
         box_h = max(1, int(obj.get("height", 10) * float(obj.get("scaleY", 1.0))))
 
         try:
-            if obj_type in ("i-text", "text", "textbox"):
+            if norm_type in ("itext", "text", "textbox"):
                 sub = _render_text_element(obj, values, box_w, box_h)
                 _paste_onto(canvas, sub, left, top, angle)
 
-            elif obj_type == "image":
+            elif norm_type == "image":
                 if obj.get("labelforge_qr_payload") is not None:
                     raise RenderError(
                         "QR elements are not yet supported for printing"
@@ -221,7 +224,7 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
                 else:
                     raise RenderError("Image elements not yet supported")
 
-            elif obj_type == "line":
+            elif norm_type == "line":
                 # x1,y1,x2,y2 are offsets from the element's left,top origin.
                 x1 = left + int(obj.get("x1", 0))
                 y1 = top + int(obj.get("y1", 0))
@@ -229,7 +232,7 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
                 y2 = top + int(obj.get("y2", box_h))
                 draw.line([(x1, y1), (x2, y2)], fill=0, width=max(1, int(obj.get("strokeWidth", 1))))
 
-            elif obj_type in ("rect", "Rect"):
+            elif norm_type == "rect":
                 fill_v = _canvas_color_to_l(obj.get("fill"))
                 sw = max(1, int(obj.get("strokeWidth", 1)))
                 sub = Image.new("L", (box_w, box_h), 255)
diff --git a/backend/labelforge/templates/fields.py b/backend/labelforge/templates/fields.py
index ec73593..4fe532a 100644
--- a/backend/labelforge/templates/fields.py
+++ b/backend/labelforge/templates/fields.py
@@ -13,8 +13,9 @@ def detect_fields(canvas_json: dict) -> list[str]:
     seen: dict[str, None] = {}  # ordered set via dict
     for obj in canvas_json.get("objects", []):
         raw: str | None = None
-        t = obj.get("type", "")
-        if t in ("i-text", "text", "textbox"):
+        # Fabric v6 emits PascalCase type names (IText); v5 used i-text. Normalize.
+        t = obj.get("type", "").lower().replace("-", "")
+        if t in ("itext", "text", "textbox"):
             raw = obj.get("labelforge_raw_content") or obj.get("text", "")
         elif obj.get("labelforge_qr_payload") is not None:
             raw = obj["labelforge_qr_payload"]
diff --git a/frontend/src/editor/canvas.ts b/frontend/src/editor/canvas.ts
index 936a4d2..6be1fdd 100644
--- a/frontend/src/editor/canvas.ts
+++ b/frontend/src/editor/canvas.ts
@@ -5,6 +5,16 @@ export const CUSTOM_PROPS = ['labelforge_raw_content'] as const
 // Register the custom prop so canvas.toJSON() includes it on every object automatically.
 FabricObject.customProperties.push('labelforge_raw_content')
 
+/**
+ * True for any Fabric text object. Fabric v6 reports `type` as the PascalCase
+ * class name ('IText', 'Textbox'); v5 used lowercase/hyphenated ('i-text').
+ * Normalize so both serializations match.
+ */
+export function isTextType(type: string | undefined): boolean {
+  const t = (type ?? '').toLowerCase().replace(/-/g, '')
+  return t === 'itext' || t === 'text' || t === 'textbox'
+}
+
 /** Create a Fabric Canvas sized to label pixels, displayed scaled to fit the container. */
 export function initCanvas(
   el: HTMLCanvasElement,
@@ -78,7 +88,7 @@ export async function loadCanvasJSON(
   await canvas.loadFromJSON(json)
   // Re-attach raw content sync to each loaded text object
   canvas.getObjects().forEach(obj => {
-    if (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox') {
+    if (isTextType(obj.type)) {
       const t = obj as IText
       t.on('changed', () => {
         t.set('labelforge_raw_content', t.text ?? '')
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index 06ceb14..b182336 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -6,6 +6,7 @@ import {
   deleteSelected,
   getCanvasJSON,
   initCanvas,
+  isTextType,
   loadCanvasJSON,
 } from '../editor/canvas'
 import type { Canvas } from 'fabric'
@@ -111,7 +112,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
     if (!fabricCanvas) return
     type TextProps = { fontFamily?: string; fontSize?: number; type?: string }
     const obj = fabricCanvas.getActiveObject() as unknown as TextProps | null
-    if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+    if (obj && isTextType(obj.type)) {
       if (obj.fontFamily) fontSelect.value = obj.fontFamily
       if (obj.fontSize) fontSizeInput.value = String(Math.round(obj.fontSize))
     }
@@ -120,7 +121,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
   fontSelect.addEventListener('change', () => {
     if (!fabricCanvas) return
     const obj = fabricCanvas.getActiveObject()
-    if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+    if (obj && isTextType(obj.type)) {
       obj.set('fontFamily', fontSelect.value)
       fabricCanvas.renderAll()
     }
@@ -131,7 +132,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
     const sz = parseInt(fontSizeInput.value, 10)
     if (!isNaN(sz) && sz >= 6) {
       const obj = fabricCanvas.getActiveObject()
-      if (obj && (obj.type === 'i-text' || obj.type === 'text' || obj.type === 'textbox')) {
+      if (obj && isTextType(obj.type)) {
         obj.set('fontSize', sz)
         fabricCanvas.renderAll()
       }

From 65a74b25d17d224210c733dfa990ae1897b52f2b Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 2 Jun 2026 14:20:00 -0700
Subject: [PATCH 56/84] fix: give continuous-media templates a non-zero editor
 canvas
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Continuous rolls report a printable length of 0 (endless roll). The
canvas editor used dots_printable[1] directly, so opening a template on
62/62red produced a zero-height canvas — added elements were invisible
and saved at top=0, which read as 'Add Text does nothing'. Continuous
templates now open at a default working length; print length stays
content-driven server-side (docs/features/templates.md).
---
 CHANGELOG.md                          | 1 +
 frontend/src/editor/canvas.ts         | 7 +++++++
 frontend/src/pages/template-editor.ts | 6 +++++-
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0394162..785a524 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Fixed
 
+- **Continuous-media templates are now editable** — opening the canvas editor on a continuous roll (e.g. `62`, `62red`) produced a zero-height canvas, because continuous media report a printable length of `0` (endless roll) and the editor used that directly. Elements added to it were invisible (and saved at `top=0`), which looked like "Add Text does nothing." Continuous templates now open at a default working length (~34mm); print length is still derived from content server-side, per the templates design doc. Requires a container image rebuild.
 - **Template text now renders and prints** — the canvas editor uses Fabric.js v6, which serializes element types as PascalCase class names (`IText`, `Line`, `Image`); the server renderer and field detection still matched the Fabric v5 lowercase/hyphenated names (`i-text`), so every text element was silently skipped — previews and prints of any template came out blank and no variable fields were detected. Both now normalize the type (lowercase, strip hyphen) and handle v5 and v6 serializations. The editor's font family/size controls (which had the same mismatch) again update the selected text. The frontend fix requires a container image rebuild to take effect; the renderer/field-detection fix is backend-only. — printing to a two-color roll (DK-2251, 62mm black/red continuous, id `62red`) was rejected by the printer as "wrong roll: check the print data" because the job declared mono media. The print path now passes `red=True` and an RGB image to the rasterizer for two-color media, so the job declares the correct media type. Black-only text prints fine on these rolls (the red plane is left empty).
 - **Pre-print media check no longer blocks same-size color variants** — the printer doesn't reliably report tape color, so the status read can't tell `62` from `62red` (both 62mm continuous) and was wrongly rejecting `62red` prints with a 409. The check now treats rolls of identical physical dimensions as compatible; mismatched sizes (e.g. 62 vs 29) still block.
 - **API error messages no longer show `[object Object]`** — the frontend now surfaces the human-readable `message` from structured `409` errors (media mismatch / printer error) instead of stringifying the whole object.
diff --git a/frontend/src/editor/canvas.ts b/frontend/src/editor/canvas.ts
index 6be1fdd..5b7d041 100644
--- a/frontend/src/editor/canvas.ts
+++ b/frontend/src/editor/canvas.ts
@@ -2,6 +2,13 @@ import { Canvas, FabricObject, IText } from 'fabric'
 
 export const CUSTOM_PROPS = ['labelforge_raw_content'] as const
 
+// Continuous media report a printable length of 0 (endless roll). The editor
+// still needs a finite working canvas, so continuous templates open at this
+// initial length (≈34mm at 300dpi). Print length is derived from content
+// server-side, so this is only the starting editing area.
+// See docs/features/templates.md.
+export const DEFAULT_CONTINUOUS_LENGTH_DOTS = 400
+
 // Register the custom prop so canvas.toJSON() includes it on every object automatically.
 FabricObject.customProperties.push('labelforge_raw_content')
 
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index b182336..f67a332 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -2,6 +2,7 @@ import { createTemplate, getFonts, getLabels, getTemplate, previewTemplate, upda
 import { navigate } from '../router'
 import type { LabelEntry } from '../types'
 import {
+  DEFAULT_CONTINUOUS_LENGTH_DOTS,
   addTextElement,
   deleteSelected,
   getCanvasJSON,
@@ -97,7 +98,10 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   async function initEditor(label: LabelEntry): Promise<void> {
     labelMedia = label.id
-    const [w, h] = label.dots_printable
+    const [w, rawH] = label.dots_printable
+    // Continuous media report length 0; open at a default working length so the
+    // editor canvas isn't zero-height (print length is content-driven server-side).
+    const h = rawH > 0 ? rawH : DEFAULT_CONTINUOUS_LENGTH_DOTS
     const canvasEl = root.querySelector<HTMLCanvasElement>('#fabric-canvas')!
     const { canvas } = initCanvas(canvasEl, w, h, getContainerWidth())
     fabricCanvas = canvas

From a91f4ceb25b8061d8438bc84736d9ecd4aad07f1 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 2 Jun 2026 20:09:25 -0700
Subject: [PATCH 57/84] feat: make app-level auth optional via DISABLE_AUTH

Add a DISABLE_AUTH env flag (default false) that short-circuits the
require_auth dependency, for deployments fronted by a reverse proxy that
handles authentication. Default stays secure: auth enforced, and the app
refuses to start without API_TOKEN. When disabled, GET /api/health reports
auth_required=false and the SPA skips its token-entry gate.

Amends ADR 2026-05-19 (auth). Docs, .env.example, and CHANGELOG updated.
---
 .env.example                        | 10 ++++++++--
 CHANGELOG.md                        |  4 ++++
 CLAUDE.md                           |  2 +-
 backend/labelforge/config.py        | 15 ++++++++++++++-
 backend/labelforge/routes/auth.py   |  8 +++++++-
 backend/labelforge/routes/health.py |  5 ++++-
 docs/decisions.md                   | 17 +++++++++++++++++
 docs/features/api.md                |  4 +++-
 frontend/src/api.ts                 | 19 +++++++++++++++++++
 frontend/src/main.ts                |  6 +++++-
 frontend/src/pages/quick-print.ts   |  4 ++--
 11 files changed, 84 insertions(+), 10 deletions(-)

diff --git a/.env.example b/.env.example
index d8a2af3..e411aee 100644
--- a/.env.example
+++ b/.env.example
@@ -1,8 +1,14 @@
 # labelforge environment — copy to .env and fill in your values.
 # All variables are read by pydantic-settings; names are case-insensitive.
 
-# REQUIRED: shared secret for the HTTP API.  All /api/* routes (except /api/health)
-# require:  Authorization: Bearer <API_TOKEN>
+# Set DISABLE_AUTH=true to run with NO app-level auth — every /api/* route is
+# open. Intended only for deployments fronted by a reverse proxy that enforces
+# auth (e.g. Traefik forward-auth/basic-auth). Default false.
+DISABLE_AUTH=false
+
+# REQUIRED (unless DISABLE_AUTH=true): shared secret for the HTTP API.  All
+# /api/* routes (except /api/health) require:  Authorization: Bearer <API_TOKEN>
+# The app refuses to start if this is unset while auth is enabled.
 API_TOKEN=changeme
 
 # REQUIRED: IP or hostname of the Brother QL printer.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 785a524..192614a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 - **Adopted four crzynet engineering standards**, pinned in a new root `standards.md`: `code-checkin-and-pr @ 1.1.0` (commit messages now use Conventional-Commits prefixes `feat:`/`fix:`/`chore:`/`docs:`; CI gained structured-config and `docker compose config` validation jobs), `handoff-prompt-workflow @ 1.5.0` (completed handoff prompts now archived under `prompts/done/`; `prompts/TEMPLATE.md` added), `repo-sandbox-permissions @ 1.0.0` (repo-wide sandbox in `.claude/settings.json` — auto-approves in-repo work, gates out-of-repo writes and network), and `vexp-context-engine @ 2.1.0` (guard hook now tracked, `.vexpignore` added). Developer/process-facing only — no runtime behavior change.
 
+### Added
+
+- **Optional app-level auth (`DISABLE_AUTH`)** — set `DISABLE_AUTH=true` to run with no Bearer-token auth, for deployments fronted by a reverse proxy (e.g. Traefik) that handles authentication. Default is unchanged and secure: auth on, and the app refuses to start without `API_TOKEN`. When disabled, every `/api/*` route is open, `GET /api/health` reports `auth_required: false`, and the web UI skips its token-entry gate. See ADR 2026-06-02.
+
 ### Fixed
 
 - **Continuous-media templates are now editable** — opening the canvas editor on a continuous roll (e.g. `62`, `62red`) produced a zero-height canvas, because continuous media report a printable length of `0` (endless roll) and the editor used that directly. Elements added to it were invisible (and saved at `top=0`), which looked like "Add Text does nothing." Continuous templates now open at a default working length (~34mm); print length is still derived from content server-side, per the templates design doc. Requires a container image rebuild.
diff --git a/CLAUDE.md b/CLAUDE.md
index ded30f9..1173d57 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -37,7 +37,7 @@ When working on a task, load the relevant feature doc(s) plus `architecture.md`
 ## Non-negotiables
 
 - **License is GPL-3.0.** Cannot be relaxed (the printer library is GPL-3.0).
-- **No SSO** (Authentik, Authelia, etc.). Auth is a single shared secret from `.env`. Do not propose SSO under any circumstances.
+- **No SSO** (Authentik, Authelia, etc.). Auth is a single shared secret from `.env`. Do not propose SSO under any circumstances. App-level auth can be disabled with `DISABLE_AUTH=true` (default-off, for deployments fronted by a reverse proxy that handles auth — see ADR 2026-06-02); that is *not* SSO and does not relax this rule. Still no multi-user / accounts.
 - **No SaaS dependencies.** Self-hosted only. No cloud functions, no hosted databases, no third-party APIs that aren't user-controllable.
 - **No Next.js, no SSR frameworks.** Frontend is a static SPA served from the FastAPI container.
 - **No alternative printer libraries** without an ADR. We picked `brother-ql-inventree` after evaluation.
diff --git a/backend/labelforge/config.py b/backend/labelforge/config.py
index 57cf0a7..3ae07a4 100644
--- a/backend/labelforge/config.py
+++ b/backend/labelforge/config.py
@@ -1,10 +1,15 @@
 from pathlib import Path
 
+from pydantic import model_validator
 from pydantic_settings import BaseSettings
 
 
 class Settings(BaseSettings):
-    api_token: str
+    # When DISABLE_AUTH=true the app runs with no app-level auth (intended for
+    # deployments fronted by a reverse proxy that handles auth, e.g. Traefik).
+    # Default is secure: auth on, and the app refuses to start without a token.
+    disable_auth: bool = False
+    api_token: str = ""
     printer_host: str
     printer_model: str = "QL-820NWB"
     # one of: network, linux_kernel, pyusb
@@ -15,5 +20,13 @@ class Settings(BaseSettings):
 
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
 
+    @model_validator(mode="after")
+    def _require_token_unless_disabled(self) -> "Settings":
+        if not self.disable_auth and not self.api_token:
+            raise ValueError(
+                "API_TOKEN is required (set DISABLE_AUTH=true to run without app-level auth)"
+            )
+        return self
+
 
 settings = Settings()
diff --git a/backend/labelforge/routes/auth.py b/backend/labelforge/routes/auth.py
index 72170f3..a8de501 100644
--- a/backend/labelforge/routes/auth.py
+++ b/backend/labelforge/routes/auth.py
@@ -5,7 +5,13 @@
 
 
 async def require_auth(authorization: str | None = Header(None)) -> None:
-    """FastAPI dependency: enforce Bearer token on all protected routes."""
+    """FastAPI dependency: enforce Bearer token on all protected routes.
+
+    No-op when DISABLE_AUTH=true (deployment is expected to be fronted by a
+    reverse proxy that handles authentication).
+    """
+    if settings.disable_auth:
+        return
     if authorization is None:
         raise HTTPException(status_code=401, detail="Authorization header required")
     if not authorization.startswith("Bearer "):
diff --git a/backend/labelforge/routes/health.py b/backend/labelforge/routes/health.py
index 5fcfcde..11b4560 100644
--- a/backend/labelforge/routes/health.py
+++ b/backend/labelforge/routes/health.py
@@ -1,8 +1,11 @@
 from fastapi import APIRouter
 
+from labelforge.config import settings
+
 router = APIRouter()
 
 
 @router.get("/health")
 async def health() -> dict:
-    return {"status": "ok"}
+    # auth_required lets the SPA decide whether to show the token gate.
+    return {"status": "ok", "auth_required": not settings.disable_auth}
diff --git a/docs/decisions.md b/docs/decisions.md
index d32fe22..58bbb93 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,23 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-02 — App-level auth is optional (`DISABLE_AUTH`), default-on; proxy can own auth
+
+**Decision**: App-level Bearer auth becomes opt-out via a `DISABLE_AUTH` env flag. Default is unchanged and secure: auth on, and the app refuses to start without `API_TOKEN`. When `DISABLE_AUTH=true`, the `require_auth` dependency short-circuits (every `/api/*` route is open) and `GET /api/health` reports `auth_required: false` so the SPA skips its token gate. The intended deployment for the disabled mode is behind a reverse proxy (Traefik forward-auth / basic-auth) that authenticates instead.
+
+This amends **2026-05-19 — Auth** (the env token stays the default mechanism; it's now skippable, not removed). Multi-user accounts were considered and rejected again — single-user remains a hard non-goal.
+
+**Why**: Owner runs this behind Traefik and prefers to authenticate at the edge rather than maintain a second secret in the app. Per-app token auth is friction when the proxy already gates the route.
+
+**Considered**:
+- User accounts / login (rejected — multi-user is a hard non-goal; `CLAUDE.md`).
+- Rip auth out entirely (rejected — not reversible without a revert; an unconfigured instance would be silently open). The flag keeps default-secure behavior and is a one-line env change.
+- Silently treat an empty `API_TOKEN` as "no auth" (rejected — too easy to ship an accidentally-open instance; disabling auth must be explicit).
+
+**Would revisit if**: we later want per-integration tokens (see 2026-05-19) or the proxy-auth assumption stops holding (e.g. exposing the app directly).
+
+---
+
 ## 2026-05-31 — Two-color DK rolls: print with `red=True`; tape color is not detectable from status
 
 **Decision**:
diff --git a/docs/features/api.md b/docs/features/api.md
index 98f6cef..e97bca1 100644
--- a/docs/features/api.md
+++ b/docs/features/api.md
@@ -12,7 +12,9 @@ Every template is callable from anywhere in the homelab. A Home Assistant automa
 
 ## Auth
 
-Single shared secret in `.env` as `API_TOKEN`. Required as `Authorization: Bearer <token>` on:
+**Optional, default-on (see ADR 2026-06-02).** Setting `DISABLE_AUTH=true` runs the app with no app-level auth — every `/api/*` route is open, intended for deployments fronted by a reverse proxy (e.g. Traefik) that authenticates at the edge. With auth disabled, `GET /api/health` returns `"auth_required": false` and the SPA skips its token gate. The rest of this section describes the default (auth enabled) mode.
+
+Single shared secret in `.env` as `API_TOKEN` (required unless `DISABLE_AUTH=true`; the app refuses to start otherwise). Required as `Authorization: Bearer <token>` on:
 
 - All `POST`, `PUT`, `DELETE` endpoints
 - `GET /api/admin/*`
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index a59f536..e75993b 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -6,6 +6,25 @@ function getToken(): string {
   return localStorage.getItem(TOKEN_KEY) ?? ''
 }
 
+// Whether the backend enforces app-level auth. Resolved once at startup from
+// /api/health (unauthenticated). Defaults to true so we fail closed if the
+// probe fails. See initAuthMode().
+let authRequired = true
+
+export function isAuthRequired(): boolean {
+  return authRequired
+}
+
+export async function initAuthMode(): Promise<void> {
+  try {
+    const res = await fetch('/api/health')
+    const body = await res.json() as { auth_required?: boolean }
+    authRequired = body.auth_required !== false
+  } catch {
+    authRequired = true  // fail closed
+  }
+}
+
 async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
   const res = await fetch(path, {
     ...options,
diff --git a/frontend/src/main.ts b/frontend/src/main.ts
index 2f6e46a..9e46ae3 100644
--- a/frontend/src/main.ts
+++ b/frontend/src/main.ts
@@ -1,4 +1,5 @@
 import './style.css'
+import { initAuthMode } from './api'
 import { mountQuickPrint } from './pages/quick-print'
 import { mountTemplates } from './pages/templates'
 import { mountTemplateEditor } from './pages/template-editor'
@@ -19,4 +20,7 @@ registerPrefix('/templates/', (root) => {
 })
 register('/history', mountHistory)
 register('/settings', mountSettings)
-initRouter()
+
+// Resolve auth mode before routing so the token gate can be skipped when the
+// backend runs with DISABLE_AUTH=true. Always routes, even if the probe fails.
+void initAuthMode().finally(() => initRouter())
diff --git a/frontend/src/pages/quick-print.ts b/frontend/src/pages/quick-print.ts
index e539c83..4e764ad 100644
--- a/frontend/src/pages/quick-print.ts
+++ b/frontend/src/pages/quick-print.ts
@@ -1,4 +1,4 @@
-import { getFonts, getLabels, getSettings, previewQuick, quickPrint, TOKEN_KEY } from '../api'
+import { getFonts, getLabels, getSettings, isAuthRequired, previewQuick, quickPrint, TOKEN_KEY } from '../api'
 import type { QuickPrintRequest } from '../types'
 import { mountLabelMediaSelect, type LabelMediaSelectHandle } from '../labels'
 
@@ -11,7 +11,7 @@ function esc(s: string): string {
 }
 
 export function mountQuickPrint(root: HTMLElement): void {
-  if (!localStorage.getItem(TOKEN_KEY)) {
+  if (isAuthRequired() && !localStorage.getItem(TOKEN_KEY)) {
     renderTokenGate(root)
   } else {
     renderForm(root)

From 8beb27be88d69005223dff6dc82505c41875052e Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Tue, 2 Jun 2026 20:31:44 -0700
Subject: [PATCH 58/84] chore: de-adopt vexp-context-engine (sunset v3.0.0)

vexp was retired homelab-wide; the standard is now a removal guide. Remove
all repo wiring: the .claude/hooks/vexp-guard.sh guard hook, .vexpignore,
the mcp__vexp__* allow entries + PreToolUse hook in .claude/settings.json,
the Context-search section in CLAUDE.md, the vexp .gitignore block, and the
vexp-only .github/copilot-instructions.md. Flip the standards.md row to
sunset; note in CHANGELOG + decisions log. Sandbox/permission blocks
preserved. Host daemon teardown belongs to the ansible repo.
---
 .claude/hooks/vexp-guard.sh     | 14 -----------
 .claude/settings.json           | 18 --------------
 .github/copilot-instructions.md | 28 ---------------------
 .gitignore                      | 13 ++++------
 .vexpignore                     | 16 ------------
 CHANGELOG.md                    |  1 +
 CLAUDE.md                       | 44 +--------------------------------
 docs/decisions.md               | 14 +++++++++++
 standards.md                    |  2 +-
 9 files changed, 22 insertions(+), 128 deletions(-)
 delete mode 100755 .claude/hooks/vexp-guard.sh
 delete mode 100644 .github/copilot-instructions.md
 delete mode 100644 .vexpignore

diff --git a/.claude/hooks/vexp-guard.sh b/.claude/hooks/vexp-guard.sh
deleted file mode 100755
index 9cefc1d..0000000
--- a/.claude/hooks/vexp-guard.sh
+++ /dev/null
@@ -1,14 +0,0 @@
-#!/bin/bash
-# vexp-guard: block Grep/Glob when vexp daemon is running AND index is healthy.
-# Fast path: if socket file or healthy marker doesn't exist, allow immediately.
-# PID check: verify daemon process is alive (handles stale files after kill -9).
-VEXP_DIR="${CLAUDE_PROJECT_DIR:-.}/.vexp"
-SOCK="$VEXP_DIR/daemon.sock"
-HEALTHY="$VEXP_DIR/healthy"
-PID_FILE="$VEXP_DIR/daemon.pid"
-if [ -S "$SOCK" ] && [ -f "$HEALTHY" ] && [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE" 2>/dev/null)" 2>/dev/null; then
-  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"vexp daemon is running. Use run_pipeline instead of Grep/Glob."}}'
-else
-  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"vexp index not ready, allowing direct search fallback."}}'
-fi
-exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
index 2e7e232..887ffc4 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -7,10 +7,6 @@
       "Bash(uname -a && hostname && cat /etc/os-release 2>/dev/null | head -5 && echo \"---\" && cat /proc/version 2>/dev/null)",
       "Read(//usr/lib/**)",
       "Read(//proc/**)",
-      "mcp__vexp__index_status",
-      "mcp__vexp__run_pipeline",
-      "mcp__vexp__get_skeleton",
-      "mcp__vexp__expand_vexp_ref",
       "Bash(git rm *)",
       "Bash(git add *)",
       "Bash(git commit *)",
@@ -58,19 +54,5 @@
         "~/.npm/**"
       ]
     }
-  },
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Grep|Glob|Regex",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh",
-            "timeout": 3000
-          }
-        ]
-      }
-    ]
   }
 }
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
deleted file mode 100644
index 86e3897..0000000
--- a/.github/copilot-instructions.md
+++ /dev/null
@@ -1,28 +0,0 @@
-## vexp context tools <!-- vexp v2.0.17 -->
-
-**MANDATORY: use `run_pipeline` — do NOT grep, glob, or read files manually.**
-vexp returns pre-indexed, graph-ranked context in a single call.
-
-### Workflow
-1. `run_pipeline` with your task description — ALWAYS FIRST (replaces all other tools)
-2. Make targeted changes based on the context returned
-3. `run_pipeline` again only if you need more context
-
-### Available MCP tools
-- `run_pipeline` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: `run_pipeline({ "task": "fix auth bug" })`
-- `get_skeleton` — compact file structure
-- `index_status` — indexing status
-- `expand_vexp_ref` — expand V-REF placeholders in v2 output
-
-### Agentic search
-- Do NOT use built-in file search, grep, or codebase indexing — always call `run_pipeline` first
-- If you spawn sub-agents or background tasks, pass them the context from `run_pipeline`
-  rather than letting them search the codebase independently
-
-### Smart Features
-Intent auto-detection, hybrid ranking, session memory, auto-expanding budget.
-
-### Multi-Repo
-`run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope. Run `index_status` to see aliases.
-<!-- /vexp -->
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 9e111c2..fea3deb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -63,22 +63,19 @@ data-dev/
 *.sqlite
 *.sqlite3
 
-# vexp (standalone systemd-user daemon — all runtime state is per-host and regenerable;
-# manifest.json intentionally NOT tracked, per the vexp-context-engine standard's
-# "each host owns its index" shape). The .vexpignore at the repo root IS tracked.
+# Leftover vexp index dir — vexp is de-adopted (see standards.md), but its host
+# daemon keeps regenerating .vexp/ until host teardown lands in the ansible repo.
+# Ignored only to prevent accidentally committing regenerated index state.
 .vexp/
-vexp.toml
 
 # Logs
 *.log
 logs/
 
-# claude — ignore the dir but track shared artifacts (settings.json, the hooks/ dir).
-# .claude/CLAUDE.md is vexp's per-host auto-generated file: left untracked (the verbatim
-# vexp snippet lives in the tracked root CLAUDE.md instead). settings.local.json stays ignored.
+# claude — ignore the dir but track the shared settings.json. Any per-host
+# auto-generated .claude/CLAUDE.md and settings.local.json stay ignored.
 .claude/*
 !.claude/settings.json
-!.claude/hooks/
 
 # Test artifacts
 .coverage
diff --git a/.vexpignore b/.vexpignore
deleted file mode 100644
index 9d4a207..0000000
--- a/.vexpignore
+++ /dev/null
@@ -1,16 +0,0 @@
-# .vexpignore — paths excluded from vexp's code index/ranking (gitignore syntax).
-# These files STAY in git; they're just kept out of run_pipeline's ranked context so
-# source code isn't crowded out by process/handoff prose. Tune per project.
-#
-# vexp's built-in excludes already cover: node_modules, .git, dist, .next, target,
-# __pycache__, .vexp. The SecurityFilter already drops .env / credentials. Only add
-# things that ARE committed source-tree files but make poor ranked context.
-
-# Completed/failed handoff prompts — historical, never useful as live code context.
-prompts/done/
-prompts/failed/
-
-# Other common candidates (uncomment per project):
-# standards.md
-# CHANGELOG.md
-# docs/**/*.md        # only if spec/decision docs are crowding out code in results
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 192614a..9cc0b9b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Changed
 
+- **De-adopted the `vexp-context-engine` standard** (now sunset at v3.0.0 — vexp retired homelab-wide). Removed all repo wiring: the `.claude/hooks/vexp-guard.sh` guard hook and `.vexpignore`, the `mcp__vexp__*` permission entries and `PreToolUse` hook in `.claude/settings.json`, the "Context search" operational-rules section in `CLAUDE.md`, and the vexp `.gitignore` block. Coding sessions use normal `grep`/`glob`/`Read` again. Developer/process-facing only — no runtime change.
 - **Adopted four crzynet engineering standards**, pinned in a new root `standards.md`: `code-checkin-and-pr @ 1.1.0` (commit messages now use Conventional-Commits prefixes `feat:`/`fix:`/`chore:`/`docs:`; CI gained structured-config and `docker compose config` validation jobs), `handoff-prompt-workflow @ 1.5.0` (completed handoff prompts now archived under `prompts/done/`; `prompts/TEMPLATE.md` added), `repo-sandbox-permissions @ 1.0.0` (repo-wide sandbox in `.claude/settings.json` — auto-approves in-repo work, gates out-of-repo writes and network), and `vexp-context-engine @ 2.1.0` (guard hook now tracked, `.vexpignore` added). Developer/process-facing only — no runtime behavior change.
 
 ### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 1173d57..98baf92 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,7 +10,7 @@ Owner: crzykidd. Personal homelab project, public open source. Single-user app 
 
 ## Standards
 
-This project implements shared engineering standards from the crzynet `homelab-configs` repo. **Read [`standards.md`](standards.md) at the repo root on session start** whenever the work could touch branching, commits, PRs, handoff prompts, the sandbox, or codebase search — it pins which standards and versions this repo conforms to. The hard per-session operational rules from those standards are pasted verbatim at the end of this file (Code check-in, Context search).
+This project implements shared engineering standards from the crzynet `homelab-configs` repo. **Read [`standards.md`](standards.md) at the repo root on session start** whenever the work could touch branching, commits, PRs, handoff prompts, or the sandbox — it pins which standards and versions this repo conforms to. The hard per-session operational rules from those standards are pasted verbatim at the end of this file (Code check-in).
 
 ## Source of truth
 
@@ -134,45 +134,3 @@ honor by default:
 
 If you're unsure whether an action would violate one of the above, stop and ask before
 acting.
-
-<!--
-Source: standards/vexp-context-engine @ v2.1.0 (crzynet/homelab-configs).
-Paste the section below verbatim into the adopting project's CLAUDE.md.
-The full standard (scope, the two pushes, the manifest-not-tracked shape,
-adoption + gate + verification procedure) lives at:
-https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/vexp-context-engine/README.md
--->
-
-## Context search (operational rules)
-
-This project adopts the `vexp-context-engine` standard. The full why-and-how lives at the
-source above; the rules below are the per-session do/don'ts a coding agent must honor by
-default:
-
-- **Call `run_pipeline` FIRST for any code task** — bug fixes, features, refactors,
-  debugging, "how does X work", "where is Y". It runs context search + impact analysis +
-  memory recall in one call and returns ranked, compressed context.
-- **Do NOT `grep`, `glob`, or `cat` to explore the codebase.** vexp returns pre-indexed,
-  graph-ranked context that is more relevant and cheaper than manual searching. A
-  `PreToolUse` guard hook blocks `Grep`/`Glob` while the vexp daemon is healthy; if the
-  daemon is down it allows the fallback.
-- **Prefer `get_skeleton` over `Read` to inspect files** (minimal/standard/detailed —
-  70–90% fewer tokens). Use `Read` only when you need exact raw content to edit a specific
-  line.
-- **Don't chain vexp calls or fan out `Explore` agents to free-search.** One
-  `run_pipeline` replaces capsule + impact + memory; if a subagent needs context, run
-  `run_pipeline` first and pass the result into the agent's prompt.
-- **The vexp daemon runs as a standalone `systemd`-user service — NOT the VS Code
-  extension.** The supervisor is `vexp.service` (`ExecStart=vexp serve`), `enabled` + linger,
-  auto-restarting; it starts/adopts the per-repo daemon on demand. Managing it with
-  `systemctl --user … vexp.service` or `vexp daemon-cmd start|stop|status|logs` is the
-  expected control path, not forbidden. Do **not** run vexp from the VS Code extension
-  (deprecated here — older bundled core, contends for the socket/port).
-- **Start/manage the daemon in the host process namespace (un-sandboxed).** A daemon
-  spawned inside a sandboxed shell gets a throwaway PID namespace + socket the host-side
-  MCP can't reach, and dies when that shell exits. If `index_status` reports "Cannot
-  connect to daemon," run `vexp daemon-cmd start` un-sandboxed and wait for "Socket ready"
-  (first start loads the local LLM, so allow >12s).
-
-If you're unsure whether an action would violate one of the above, stop and ask before
-acting.
diff --git a/docs/decisions.md b/docs/decisions.md
index 58bbb93..d34b361 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,20 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-02 — De-adopt vexp-context-engine (sunset)
+
+**Decision**: Removed the `vexp-context-engine` standard from this repo, following its v3.0.0 sunset (vexp retired homelab-wide — it didn't pay for its host-provisioning + guard-hook + per-session-rule tax). De-wired the repo per the v3.0.0 removal guide: deleted the guard hook + `.vexpignore`, the `mcp__vexp__*` allow entries and `PreToolUse` block in `.claude/settings.json`, the "Context search" section in `CLAUDE.md`, the vexp `.gitignore` block, and the on-disk `.vexp/` / auto-generated `.claude/CLAUDE.md`. `standards.md` row flipped to sunset.
+
+**Why**: The upstream standard is deprecated and instructs existing adopters to remove it. Coding agents return to normal `grep`/`glob`/`Read`.
+
+**Considered**: Keep vexp running locally despite the sunset (rejected — it's unmaintained, and the guard hook actively fights the agent's normal tools).
+
+**Would revisit if**: a maintained graph-RAG context engine is re-introduced homelab-wide.
+
+**Note**: Host-level teardown (uninstalling the vexp daemon/CLI on this WSL box) belongs to the `ansible` repo, not this app repo.
+
+---
+
 ## 2026-06-02 — App-level auth is optional (`DISABLE_AUTH`), default-on; proxy can own auth
 
 **Decision**: App-level Bearer auth becomes opt-out via a `DISABLE_AUTH` env flag. Default is unchanged and secure: auth on, and the app refuses to start without `API_TOKEN`. When `DISABLE_AUTH=true`, the `require_auth` dependency short-circuits (every `/api/*` route is open) and `GET /api/health` reports `auth_required: false` so the SPA skips its token gate. The intended deployment for the disabled mode is behind a reverse proxy (Traefik forward-auth / basic-auth) that authenticates instead.
diff --git a/standards.md b/standards.md
index 869afcd..a6e4b12 100644
--- a/standards.md
+++ b/standards.md
@@ -11,4 +11,4 @@ snippet-bearing standards are pasted verbatim into `CLAUDE.md`.
 | [code-checkin-and-pr](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/code-checkin-and-pr/README.md) | 1.1.0 | 2026-05-31 | Full adoption. CI (`ci.yml`) covers backend lint (ruff/mypy/pytest), structured-config validation, `docker compose config`, and PR-only image build; publish matrix (`build-and-push.yml`) + retention (`cleanup-images.yml`) already in place. **Migration check N/A** — no migration system (raw SQLite via `backend/labelforge/db.py`). Commit-prefix convention flipped to Conventional-Commits per ADR 2026-05-31. CLAUDE-snippet pasted verbatim into `CLAUDE.md`. |
 | [handoff-prompt-workflow](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/handoff-prompt-workflow/README.md) | 1.5.0 | 2026-05-31 | Upgraded from v1.0.0. Origin project for this standard. `prompts/` is the live queue; completed prompts archived under `prompts/done/`; `prompts/TEMPLATE.md` added; frontmatter gained `model:`; working-tree check + single-commit-with-ask + launch-command form reflected in `CLAUDE.md`. |
 | [repo-sandbox-permissions](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/repo-sandbox-permissions/README.md) | 1.0.0 | 2026-05-31 | scope: **repo-wide** (`.claude/settings.json`), 2026-05-31. `allowedDomains` = localhost + pypi/files.pythonhosted + registry.npmjs (Python + Node stack); `allowWrite` = `/tmp/**`, `~/.cache/**` (covers uv/ruff/mypy), `~/.npm/**`. `bubblewrap` + `socat` installed on this host. **Restart Claude Code** to activate (`sandbox.enabled` is read at startup). |
-| [vexp-context-engine](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/vexp-context-engine/README.md) | 2.1.0 | 2026-05-31 | Shape B — `.vexp/manifest.json` intentionally not tracked (each host owns its index). Guard hook `.claude/hooks/vexp-guard.sh` now tracked; vexp's auto-generated `.claude/CLAUDE.md` untracked (verbatim snippet lives in `CLAUDE.md`); `.vexpignore` added. Verify (2026-05-31): MCP `index_status` healthy — repo indexed (486 nodes / 448 edges, 0 stale); LLM `Operational: true`. **GPU offload NOT enabled** (CPU backend only) although `/usr/lib/wsl/lib/libcuda.so.1` is present and a GPU appears installed — missing `libggml-cuda.so` is host-side drift for the Ansible vexp role to fix; CPU fallback remains conformant. |
+| ~~[vexp-context-engine](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/vexp-context-engine/README.md)~~ | 3.0.0 _(sunset)_ | de-adopted 2026-06-02 | **DE-ADOPTED** per the v3.0.0 removal guide (vexp retired homelab-wide). Repo wiring removed: `git rm .claude/hooks/vexp-guard.sh` + `.vexpignore`; dropped the `mcp__vexp__*` allow entries and the `PreToolUse` guard-hook block from `.claude/settings.json` (sandbox/permissions preserved); deleted the "Context search (operational rules)" section + vexp prose from `CLAUDE.md`; removed the vexp `.gitignore` block and the `!.claude/hooks/` un-ignore; deleted `.vexp/`, `vexp.toml`, and the auto-generated `.claude/CLAUDE.md` on disk. **Host teardown** (uninstall the vexp daemon/CLI on this WSL host) belongs to the `ansible` repo — this is a pure app repo. |

From b3b29d6ace0ee111db8decb9f1780ad331dde470 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Wed, 3 Jun 2026 21:26:50 -0700
Subject: [PATCH 59/84] fix: correct initial canvas aspect for continuous-roll
 templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DEFAULT_CONTINUOUS_LENGTH_DOTS was 400 dots (~34mm), giving a landscape
696×400 canvas for the 62mm roll. 1000 dots (~84mm) keeps the initial
display portrait (418×600 scaled) without changing print behavior —
print length is still content-derived server-side.
---
 frontend/src/editor/canvas.ts                 |  11 +-
 .../done/2026-06-03-template-editor-fixes.md  | 169 ++++++++++++++++++
 2 files changed, 176 insertions(+), 4 deletions(-)
 create mode 100644 prompts/done/2026-06-03-template-editor-fixes.md

diff --git a/frontend/src/editor/canvas.ts b/frontend/src/editor/canvas.ts
index 5b7d041..11e5def 100644
--- a/frontend/src/editor/canvas.ts
+++ b/frontend/src/editor/canvas.ts
@@ -4,10 +4,13 @@ export const CUSTOM_PROPS = ['labelforge_raw_content'] as const
 
 // Continuous media report a printable length of 0 (endless roll). The editor
 // still needs a finite working canvas, so continuous templates open at this
-// initial length (≈34mm at 300dpi). Print length is derived from content
+// initial length (≈84mm at 300dpi). Print length is derived from content
 // server-side, so this is only the starting editing area.
+// 1000 dots keeps the initial canvas portrait for the 62mm roll (696px wide):
+// scale = min(1, 600/1000=0.6) → 418×600 display, not the landscape 696×400
+// that 400 dots produced.
 // See docs/features/templates.md.
-export const DEFAULT_CONTINUOUS_LENGTH_DOTS = 400
+export const DEFAULT_CONTINUOUS_LENGTH_DOTS = 1000
 
 // Register the custom prop so canvas.toJSON() includes it on every object automatically.
 FabricObject.customProperties.push('labelforge_raw_content')
@@ -50,7 +53,7 @@ export function initCanvas(
   return { canvas, scale }
 }
 
-export function addTextElement(canvas: Canvas, defaultFont: string): void {
+export function addTextElement(canvas: Canvas, defaultFont: string, fill = '#000000'): void {
   const vp = canvas.viewportTransform ?? [1, 0, 0, 1, 0, 0]
   const scale = vp[0]
   const canvasVirtualW = (canvas.width ?? 400) / scale
@@ -61,7 +64,7 @@ export function addTextElement(canvas: Canvas, defaultFont: string): void {
     top: Math.round(canvasVirtualH * 0.05),
     fontFamily: defaultFont,
     fontSize: 48,
-    fill: '#000000',
+    fill,
   })
   text.set('labelforge_raw_content', 'Text')
 
diff --git a/prompts/done/2026-06-03-template-editor-fixes.md b/prompts/done/2026-06-03-template-editor-fixes.md
new file mode 100644
index 0000000..1553319
--- /dev/null
+++ b/prompts/done/2026-06-03-template-editor-fixes.md
@@ -0,0 +1,169 @@
+---
+name: 2026-06-03-template-editor-fixes
+status: completed
+created: 2026-06-03
+model: sonnet
+completed: 2026-06-03
+result: All three parts implemented — canvas portrait fix (DEFAULT_CONTINUOUS_LENGTH_DOTS 400→1000), Save As toolbar button with modal, full two-color RGB rendering + red text control gated to color-capable media. One deviation: canvas width could not be visually reproduced (headless env); fix is based on scale-math analysis.
+---
+
+# Task: Fix template editor — canvas width, Save As (retarget media), red text
+
+Three issues on the canvas editor (`/templates/{name}`), all reported together after the
+recent "text renders now" fixes:
+
+1. **Canvas is too wide / wrong aspect** — the editing area looks stretched; the width
+   regressed somewhere.
+2. **No way to choose a different label** from the editor. (NB: this control was never in
+   the editor — see the design note below. The faithful fix is to surface the documented
+   **Save As** flow, not a live media-mutation dropdown.)
+3. **No way to set text to red** — two-color rolls (`62red` / DK-2251) support black+red,
+   but there's no color control and the renderer is hardcoded mono. The user wants the
+   **full** slice: UI control + RGB render + actual two-color print.
+
+Do these as three separate, independently-committable parts in this order (width → Save As
+→ red). If context runs short, stop after a completed part and update this prompt's status
+so the remainder can be picked up.
+
+## Before you start
+
+- Read `docs/features/templates.md` (canvas size, toolbar, "locked to media" rule),
+  `docs/architecture.md`, and `docs/glossary.md`. Skim `docs/decisions.md` for the existing
+  two-color note.
+- Read the existing two-color print decision context: `render_template` in
+  `backend/labelforge/render/template.py` has a docstring saying *"Two-color (62red)
+  rendering is a later slice; always renders mono."* — Part 3 re-opens that. It needs an
+  ADR entry.
+- **Design constraint (do NOT violate):** `templates.md` states a template is *locked to
+  its label media*; the sanctioned way to use a design on different media is **Save As
+  (clone to a new name + new media)**. The documented toolbar is: undo, redo, zoom, fit,
+  save, **save-as**, preview, print. So Part 2 = add Save As, **not** a control that mutates
+  the current template's media. If you become convinced a live media switch is genuinely
+  wanted, STOP and ask — it needs a PRD/ADR change first.
+- This project adopts `code-checkin-and-pr`: work on `dev`, Conventional-Commits prefixes,
+  no `Co-authored-by:`, docs ship in the same commit as the code. Changelog entry required.
+
+## Working tree check
+
+Before making any edits, run `git status --porcelain` and cross-reference the files this
+plan touches. If any have uncommitted changes, list them and ask before touching. This
+prompt file is exempt.
+
+## Key files
+
+- `frontend/src/pages/template-editor.ts` — editor page (toolbar, bootstrap, save/preview)
+- `frontend/src/editor/canvas.ts` — `initCanvas`, `addTextElement`, scale math, custom props
+- `frontend/src/style.css` — `#app.editor-mode` (max-width 1100px), `.editor-canvas-wrap`,
+  `.editor-canvas-inner` (~lines 18, 302–315)
+- `frontend/src/labels.ts` — `mountLabelMediaSelect` (reuse for the Save As modal media picker)
+- `frontend/src/pages/templates-list.ts` — `showNewTemplateModal` (copy its modal pattern)
+- `frontend/src/api.ts` / `frontend/src/types.ts` — add a `duplicateTemplate` API call; the
+  `LabelEntry.color` field (`1` = two-color media) gates the red control
+- `backend/labelforge/render/template.py` — `render_template`, `_render_text_element`,
+  `_paste_onto`, `_canvas_color_to_l` (Part 3)
+- `backend/labelforge/printer/client.py:259-272` — print path already does
+  `convert(..., red=red)` reading the red plane from an RGB image; **no change needed there**,
+  it just needs `render_template` to actually emit red pixels
+- `backend/labelforge/routes/preview.py`, `routes/template_print.py` — preview/print entry
+  points; verify the preview PNG carries color (it should, once the renderer returns RGB)
+- `backend/labelforge/routes/templates.py:82` + `templates/store.py:150` — the
+  `POST /api/templates/{name}/duplicate` endpoint already exists (used by Save As)
+
+## What to do
+
+### Part 1 — Fix the canvas width/aspect regression
+
+1. Reproduce first. Run the app (use the `/run` skill or `npm run dev` in `frontend/` against
+   the backend) and open the editor on **both** a die-cut label (e.g. `29x90`) and a
+   continuous roll (`62`). Screenshot each. The canvas should match the label's aspect ratio,
+   scaled to fit the viewport, with no horizontal overflow.
+2. Diagnose. Likely suspects, in order:
+   - `initCanvas` scale math in `canvas.ts:26-41`:
+     `scale = Math.min(1, (containerW - 48) / labelW, maxDisplayH / labelH)`. For a 62mm roll
+     `labelW≈696`; with `editor-mode` container ≈1100 the width term exceeds 1 so scale clamps
+     to 1 and the canvas renders at native 696px — check whether that, combined with the
+     continuous default length (`DEFAULT_CONTINUOUS_LENGTH_DOTS = 400`), is what reads as
+     "too wide / wrong shape."
+   - `getContainerWidth()` timing — it reads `canvasWrap.clientWidth` inside the post-fetch
+     bootstrap; confirm the element is laid out (non-zero, ~1100) at that point, not 0/garbage.
+   - `#app.editor-mode { max-width: 1100px }` vs the canvas — is the *page* what got wide, or
+     the *canvas*? Fix whichever is actually wrong.
+3. Fix so the displayed canvas matches the label proportions and fits without overflow.
+   Acceptance: a wide-short address label looks wide and short; a tall `29x90` looks tall and
+   narrow; no horizontal scrollbar at normal window width.
+
+### Part 2 — Save As in the editor toolbar (retarget media the sanctioned way)
+
+1. Add a **Save As** button to the editor toolbar (between Save and Preview is fine).
+2. On click, open a modal mirroring `showNewTemplateModal` in `templates-list.ts`: slug-
+   validated new name + a label-media picker via `mountLabelMediaSelect`. Pre-fill the media
+   with the current template's media.
+3. Add `duplicateTemplate(name, { name, label_media })` to `api.ts` calling
+   `POST /api/templates/{name}/duplicate` (endpoint already exists). The current editor must
+   be **saved first** (so the clone copies the latest canvas) — reuse the existing save path.
+4. On success, navigate to the new template's editor (`/templates/{newName}`).
+5. Also surface the **current media** read-only in the toolbar (e.g. next to the title) so the
+   user can see what they're editing. Do **not** add a dropdown that mutates the open
+   template's media.
+
+### Part 3 — Full two-color (red) text
+
+**Backend (`render/template.py`):**
+1. Branch the canvas mode on media color: if `label.color == 1` (two-color), render onto an
+   **RGB** white canvas; otherwise keep the current mode-`L` path unchanged (preserve existing
+   mono behavior exactly).
+2. Add a `_canvas_color_to_rgb(fill)` helper mapping element `fill` → `(0,0,0)` (black) or
+   `(255,0,0)` (red). Treat `#ff0000`, `#f00`, `red`, `rgb(255,0,0)` as red; everything else as
+   black. Pure `(255,0,0)` is what `convert(red=True)` routes to the red plane.
+3. `_render_text_element` currently returns an `L` coverage mask (text=0 on 255). Keep
+   producing that mask, then composite a solid color through it: on RGB,
+   `canvas.paste(Image.new("RGB", sub.size, rgb), (left, top), mask=ImageOps.invert(sub))`.
+   Refactor `_paste_onto` to take a target color (or add an RGB variant) so rotation/antialias
+   handling is shared. Text color comes from the element's `fill`.
+4. Lines and rects: on the RGB path, honor their color too (`draw.line(..., fill=rgb)`, rect
+   fill/outline). Don't regress the mono path.
+5. Update the `render_template` docstring — remove "always renders mono"; describe the
+   two-color path.
+
+**Preview/print:**
+6. Verify `POST /api/preview/{name}` (Part of `routes/preview.py` / `template_print.py`) returns
+   a PNG that shows red for two-color media. If a threshold/`_threshold_preview` step is in the
+   template-preview path, make sure it doesn't crush color to mono (that helper is for
+   quick-print exact-bitmap, not template color preview).
+7. The print path (`printer/client.py`) already promotes to RGB and passes `red=True` for
+   two-color media — confirm an actual red-plane print results now that the renderer emits red.
+   Test print (or at least raster-convert) a `62red` template with one black and one red text
+   element.
+
+**Frontend (`template-editor.ts` + `canvas.ts`):**
+8. Add a text-color control to the toolbar (a Black/Red toggle or `<select>`). Show/enable it
+   **only when the loaded label is two-color** (`label.color === 1`); hide or disable for mono
+   media (mono = black only).
+9. On change, set the active text object's `fill` to `#000000` / `#ff0000` and `renderAll()`.
+   `fill` is a standard Fabric prop already included in `toJSON()` — no custom property needed.
+10. Sync the control in `updateFontControls` (reflect the selected object's current fill), and
+    make `addTextElement` default new text to the currently-selected color.
+
+## Conventions to honor
+
+- One concern per commit; three commits is fine (`fix:` width, `feat:` Save As, `feat:` red
+  text) — or fewer if you prefer, but keep docs with their code.
+- Changelog: add `[Unreleased]` entries; update the **Known Issues** block — two-color text now
+  prints (QR/barcode remain the open item).
+- Update `docs/features/templates.md`: document the red text control, that two-color media
+  enables it, and that Save As lives in the toolbar.
+- Match existing TS style (no framework, `esc()` for HTML, vanilla DOM) and Python style
+  (type hints, terse "why" comments only).
+- Note the container-image rebuild requirement for any frontend change in the changelog, as
+  prior entries do.
+
+## When done
+
+1. Update this file's frontmatter (`status`, `completed`, `result`).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record the non-obvious decisions in `docs/decisions.md` — at minimum an ADR re-opening
+   **two-color template rendering** (supersedes the "later slice" note), and the decision that
+   media retargeting stays **Save As only** (template locked to media), not a live switch.
+4. Propose commits (per part). Present the file list + one-line message(s); ask
+   `commit these as "<message>"? (y/n)`. On `y`, stage those specific paths and commit on
+   `dev`. Never `git add -A`. Never push.

From c960e929b64aef9d91114ebaa8b987bb46815356 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Wed, 3 Jun 2026 21:27:08 -0700
Subject: [PATCH 60/84] feat: add Save As and two-color text to template editor

Save As: toolbar button saves current canvas then opens a clone modal
(new slug + media picker pre-filled with current media); on confirm
calls POST /api/templates/{name}/duplicate and opens the new copy.
Current media is shown read-only next to the template title.

Two-color text: Black/Red toggle in toolbar, gated to color-capable
media (label.color === 1). Renderer now returns RGB for two-color
labels, compositing each element's fill/stroke color as black (0,0,0)
or red (255,0,0). Template preview preserves color instead of
thresholding to mono.
---
 CHANGELOG.md                                |  13 ++
 backend/labelforge/render/template.py       |  89 +++++++++++--
 backend/labelforge/routes/template_print.py |   5 +-
 docs/decisions.md                           |  30 +++++
 docs/features/templates.md                  |  16 +++
 frontend/src/api.ts                         |   7 +
 frontend/src/pages/template-editor.ts       | 134 +++++++++++++++++++-
 frontend/src/style.css                      |   8 ++
 8 files changed, 284 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9cc0b9b..50310e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,19 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Added
+
+- **Save As in template editor** — toolbar now has a **Save As** button that saves the current canvas first, then opens a modal for a new template slug and label media (pre-filled with the current media). Clones the template via `POST /api/templates/{name}/duplicate` and opens the editor on the copy. This is the documented way to re-use a design on different media; the existing template's media is never mutated. The current media is also shown as a read-only badge next to the template name. Requires a container image rebuild.
+- **Full two-color (red) text in templates** — templates on two-color media (`62red` / DK-2251) can now use red text in addition to black. A **Black / Red** toggle appears in the editor toolbar only when the loaded label is two-color (hidden for mono media). Selecting an element and changing the toggle updates its Fabric `fill` to `#000000` or `#ff0000`; new text elements inherit the current selection. The server renderer now emits an RGB image for two-color media, compositing each text element's `fill` as the ink color (red → red plane, black → black plane); lines honor `stroke`, rects honor `fill` and `stroke`. The preview PNG for two-color templates now returns a color image rather than thresholded mono, so the preview reflects actual print output. Printing is unchanged (the print path already promoted L→RGB and passed `red=True` for two-color media). Requires a container image rebuild.
+
+### Fixed
+
+- **Template editor canvas aspect on continuous rolls** — opening the editor on a continuous roll (e.g. `62`, `62red`) showed a landscape canvas (696 × 400px for 62mm) because the initial working height was set to 400 dots (~34mm). This made the canvas visually wider than tall, which reads as wrong for a label roll. The default working height is now 1000 dots (~84mm), which gives a portrait display (418 × 600px scaled) for the 62mm roll. Print length is still content-driven server-side. Requires a container image rebuild.
+
+### Known Issues
+
+- QR and barcode template elements render in preview but print as a solid black block (1-bit threshold crushes fine detail). These elements are gated to raise a clear error until fixed. Text, lines, and rectangles print correctly, including in red on two-color media.
+
 ### Changed
 
 - **De-adopted the `vexp-context-engine` standard** (now sunset at v3.0.0 — vexp retired homelab-wide). Removed all repo wiring: the `.claude/hooks/vexp-guard.sh` guard hook and `.vexpignore`, the `mcp__vexp__*` permission entries and `PreToolUse` hook in `.claude/settings.json`, the "Context search" operational-rules section in `CLAUDE.md`, and the vexp `.gitignore` block. Coding sessions use normal `grep`/`glob`/`Read` again. Developer/process-facing only — no runtime change.
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index 588d3e9..56dbc80 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -36,6 +36,23 @@ def _canvas_color_to_l(color: str | None) -> int | None:
     return 0
 
 
+def _canvas_color_to_rgb(color: str | None) -> tuple[int, int, int] | None:
+    """Map a CSS color to an RGB tuple for two-color rendering.
+
+    Returns None for transparent/no-fill, (255,0,0) for red, (0,0,0) for black
+    (the only two ink colors on a two-color DK roll). White is treated as the
+    paper color (opaque white — use None for transparent backgrounds instead).
+    """
+    if not color or color.lower().strip() in ("transparent", "rgba(0,0,0,0)", "none"):
+        return None
+    lc = color.lower().strip()
+    if lc in ("#fff", "#ffffff", "white", "rgb(255,255,255)"):
+        return (255, 255, 255)
+    if lc in ("#ff0000", "#f00", "red", "rgb(255,0,0)"):
+        return (255, 0, 0)
+    return (0, 0, 0)
+
+
 def _resolve_font_path(family: str, weight: str | None, style: str | None) -> str | None:
     """Return the best matching font file path, falling back to base family on miss."""
     bold = bool(weight and str(weight).lower() in ("bold", "700", "800", "900"))
@@ -67,9 +84,20 @@ def _resolve_font_path(family: str, weight: str | None, style: str | None) -> st
 
 
 def _paste_onto(
-    canvas: Image.Image, sub: Image.Image, left: int, top: int, angle: float
+    canvas: Image.Image,
+    sub: Image.Image,
+    left: int,
+    top: int,
+    angle: float,
+    rgb: tuple[int, int, int] | None = None,
 ) -> None:
-    """Paste sub-image onto canvas; invert-mask whites out, rotate around element centre."""
+    """Paste sub-image (mode-L coverage mask) onto canvas.
+
+    sub must be mode-L: 0 = ink (opaque), 255 = paper (transparent).
+    rgb: when set, composites a solid RGB patch through the coverage mask onto
+    an RGB canvas — used for coloured text/shapes on two-color media. When None,
+    pastes the grayscale sub directly (mono path).
+    """
     if abs(angle) > 0.01:
         # Preserve centre point across expand-rotation.
         cx = left + sub.width // 2
@@ -80,7 +108,10 @@ def _paste_onto(
     # Dark pixels (value≈0) → mask 255 (opaque); white (255) → mask 0 (skip).
     # Preserves antialiasing in intermediate greys.
     mask = sub.point(lambda p: 255 - p)
-    canvas.paste(sub, (left, top), mask=mask)
+    if rgb is not None:
+        canvas.paste(Image.new("RGB", sub.size, rgb), (left, top), mask=mask)
+    else:
+        canvas.paste(sub, (left, top), mask=mask)
 
 
 def _render_text_element(
@@ -170,8 +201,11 @@ def _render_barcode_element(
 def render_template(template: Template, values: dict[str, str]) -> Image.Image:
     """Rasterize *template* with *values* substituted for placeholders.
 
-    Returns a mode='L' PIL Image (0=black, 255=white) sized for the print head.
-    Two-color (62red) rendering is a later slice; always renders mono.
+    Returns a PIL Image sized for the print head. Mode is 'L' (0=black, 255=white)
+    for mono media. For two-color media (label.color == 1, e.g. 62red / DK-2251)
+    mode is 'RGB': black pixels are (0,0,0), red pixels are (255,0,0), paper is
+    (255,255,255). The print path promotes L→RGB and passes red=True for two-color
+    media; an RGB image here means red pixels land on the red print plane.
     """
     label = get_label(template.label_media)
     if label is None:
@@ -180,6 +214,7 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
     canvas_w = label.dots_printable[0]
     objects = template.canvas_json.get("objects", [])
     is_continuous = label.form_factor in _CONTINUOUS_FORM_FACTORS
+    two_color = label.color == 1
 
     if is_continuous:
         bottommost = 0
@@ -191,7 +226,10 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
     else:
         canvas_h = label.dots_printable[1]
 
-    canvas = Image.new("L", (canvas_w, canvas_h), 255)
+    if two_color:
+        canvas: Image.Image = Image.new("RGB", (canvas_w, canvas_h), (255, 255, 255))
+    else:
+        canvas = Image.new("L", (canvas_w, canvas_h), 255)
     draw = ImageDraw.Draw(canvas)
 
     for obj in objects:
@@ -208,7 +246,11 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
         try:
             if norm_type in ("itext", "text", "textbox"):
                 sub = _render_text_element(obj, values, box_w, box_h)
-                _paste_onto(canvas, sub, left, top, angle)
+                if two_color:
+                    rgb = _canvas_color_to_rgb(obj.get("fill")) or (0, 0, 0)
+                    _paste_onto(canvas, sub, left, top, angle, rgb=rgb)
+                else:
+                    _paste_onto(canvas, sub, left, top, angle)
 
             elif norm_type == "image":
                 if obj.get("labelforge_qr_payload") is not None:
@@ -225,20 +267,39 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
                     raise RenderError("Image elements not yet supported")
 
             elif norm_type == "line":
-                # x1,y1,x2,y2 are offsets from the element's left,top origin.
                 x1 = left + int(obj.get("x1", 0))
                 y1 = top + int(obj.get("y1", 0))
                 x2 = left + int(obj.get("x2", box_w))
                 y2 = top + int(obj.get("y2", box_h))
-                draw.line([(x1, y1), (x2, y2)], fill=0, width=max(1, int(obj.get("strokeWidth", 1))))
+                stroke_color: tuple[int, int, int] | int
+                if two_color:
+                    stroke_color = _canvas_color_to_rgb(obj.get("stroke") or "#000000") or (0, 0, 0)
+                else:
+                    stroke_color = 0
+                draw.line([(x1, y1), (x2, y2)], fill=stroke_color, width=max(1, int(obj.get("strokeWidth", 1))))
 
             elif norm_type == "rect":
-                fill_v = _canvas_color_to_l(obj.get("fill"))
                 sw = max(1, int(obj.get("strokeWidth", 1)))
-                sub = Image.new("L", (box_w, box_h), 255)
-                sub_draw = ImageDraw.Draw(sub)
-                sub_draw.rectangle([0, 0, box_w - 1, box_h - 1], fill=fill_v, outline=0, width=sw)
-                _paste_onto(canvas, sub, left, top, angle)
+                if two_color:
+                    fill_rgb = _canvas_color_to_rgb(obj.get("fill"))
+                    outline_rgb = _canvas_color_to_rgb(obj.get("stroke") or "#000000") or (0, 0, 0)
+                    # Draw fill and outline as separate L masks so each can carry its own
+                    # color and rotation is handled by _paste_onto.
+                    if fill_rgb is not None:
+                        fill_sub = Image.new("L", (box_w, box_h), 255)
+                        fill_sub_draw = ImageDraw.Draw(fill_sub)
+                        fill_sub_draw.rectangle([sw, sw, box_w - 1 - sw, box_h - 1 - sw], fill=0)
+                        _paste_onto(canvas, fill_sub, left, top, angle, rgb=fill_rgb)
+                    outline_sub = Image.new("L", (box_w, box_h), 255)
+                    outline_sub_draw = ImageDraw.Draw(outline_sub)
+                    outline_sub_draw.rectangle([0, 0, box_w - 1, box_h - 1], outline=0, width=sw)
+                    _paste_onto(canvas, outline_sub, left, top, angle, rgb=outline_rgb)
+                else:
+                    fill_v = _canvas_color_to_l(obj.get("fill"))
+                    sub = Image.new("L", (box_w, box_h), 255)
+                    sub_draw = ImageDraw.Draw(sub)
+                    sub_draw.rectangle([0, 0, box_w - 1, box_h - 1], fill=fill_v, outline=0, width=sw)
+                    _paste_onto(canvas, sub, left, top, angle)
 
             else:
                 logger.debug("Skipping unhandled element type %r", obj_type)
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index c83750b..8955111 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -131,7 +131,10 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
     buf = io.BytesIO()
-    to_print_bitmap(image).save(buf, format="PNG")
+    # Two-color templates render as RGB; preserve color in the preview PNG.
+    # Mono templates apply the print threshold so preview == print.
+    preview = image if image.mode == "RGB" else to_print_bitmap(image)
+    preview.save(buf, format="PNG")
     return Response(content=buf.getvalue(), media_type="image/png")
 
 
diff --git a/docs/decisions.md b/docs/decisions.md
index d34b361..86e069d 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,36 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-03 — Two-color template rendering (supersedes "later slice" note)
+
+**Decision**: `render_template` now supports two-color (black + red) media. When `label.color == 1` (e.g. `62red` / DK-2251) the renderer returns a mode-`RGB` image instead of mode-`L`: black pixels are `(0,0,0)`, red pixels are `(255,0,0)`, paper is `(255,255,255)`. The print path in `printer/client.py` already promoted `L→RGB` and passed `red=True` for two-color media (2026-05-31 ADR) — it consumes the RGB image correctly without change. Text color comes from the Fabric element's `fill` property (`#000000` / `#ff0000`); lines use `stroke`; rects use `fill`/`stroke`. The template-preview PNG also returns RGB (color-accurate) instead of the threshold-crushed mono.
+
+The "Two-color (62red) rendering is a later slice; always renders mono" docstring note is superseded by this implementation.
+
+**Why**: Two-color DK rolls are a first-class media in the catalog and the most useful differentiated feature of those rolls. The print path infrastructure was already in place; only the renderer and frontend controls were missing. QR/barcode elements remain mono (raised as `RenderError`) — a separate fix is needed for those.
+
+**Considered**:
+- Separate `render_template_color()` function — rejected; branching on `label.color` inside the existing function keeps the call-site unchanged.
+- Always return RGB — rejected; doubles memory for mono jobs and changes the mono threshold behavior.
+
+**Would revisit if**: QR/barcode color rendering is implemented (extend the two-color path to those element types).
+
+---
+
+## 2026-06-03 — Template media retargeting: Save As only; live media switch is not in scope
+
+**Decision**: A template is locked to its label media. The editor toolbar exposes a **Save As** button that clones the template to a new name and optionally a new media via `POST /api/templates/{name}/duplicate`. No dropdown or control that mutates the open template's `label_media` exists in the editor. The current media is shown as a read-only badge next to the template name.
+
+**Why**: Mutating a template's media in the editor would silently invalidate all saved element positions (they're in print-DPI pixel coordinates sized for the original media). Save As makes the user explicitly create a new template and adjust the layout, preventing silent corruption. This matches the design in `docs/features/templates.md` ("A template is locked to its label media").
+
+**Considered**:
+- A live media-switch dropdown in the editor that rescales element positions — rejected; position rescaling is lossy (different aspect ratios, different DPIs across form factors) and the complexity is not justified for a single-user homelab tool.
+- Auto-redirect to a new template on media change (same as Save As, just triggered differently) — rejected; the explicit Save As click makes the copy intent clear and avoids accidental renames.
+
+**Would revisit if**: a "reflow to new media" feature is scoped in a PRD change with explicit rescaling rules.
+
+---
+
 ## 2026-06-02 — De-adopt vexp-context-engine (sunset)
 
 **Decision**: Removed the `vexp-context-engine` standard from this repo, following its v3.0.0 sunset (vexp retired homelab-wide — it didn't pay for its host-provisioning + guard-hook + per-session-rule tax). De-wired the repo per the v3.0.0 removal guide: deleted the guard hook + `.vexpignore`, the `mcp__vexp__*` allow entries and `PreToolUse` block in `.claude/settings.json`, the "Context search" section in `CLAUDE.md`, the vexp `.gitignore` block, and the on-disk `.vexp/` / auto-generated `.claude/CLAUDE.md`. `standards.md` row flipped to sunset.
diff --git a/docs/features/templates.md b/docs/features/templates.md
index 3e73e1c..edd48ff 100644
--- a/docs/features/templates.md
+++ b/docs/features/templates.md
@@ -92,6 +92,22 @@ For continuous media (62mm endless), the canvas has a fixed width and a user-set
 
 Top: undo, redo, zoom, fit, save, save-as, preview, print
 
+The current label media is shown as a read-only badge next to the template name so
+the user can see what they are editing without opening any menu.
+
+**Save As** opens a modal for entering a new slug name and picking a label media
+(pre-filled with the current media). It saves the current canvas first, then calls
+`POST /api/templates/{name}/duplicate`. On success, the editor navigates to the new
+template. This is the only sanctioned way to retarget a design to different media —
+the current template's media is never mutated in the editor.
+
+**Text color** — a Black / Red toggle appears in the toolbar **only when the loaded
+label is two-color** (`label.color === 1`, e.g. `62red` / DK-2251). For mono media
+the control is hidden and all text is always black. When visible, changing the
+control sets the active text element's `fill` property; new text elements default to
+the currently-selected color. The server renderer honors the `fill` value and
+composites red or black ink onto the print image.
+
 Left: element type palette (text, QR, barcode, image, line, rect)
 
 Right: properties panel for selected element + global panels (fields, label info)
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index e75993b..3b0a780 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -123,6 +123,13 @@ export function deleteTemplate(name: string): Promise<void> {
   return apiFetch<void>(`/api/templates/${encodeURIComponent(name)}`, { method: 'DELETE' })
 }
 
+export function duplicateTemplate(source: string, body: { name: string; label_media: string }): Promise<Template> {
+  return apiFetch<Template>(`/api/templates/${encodeURIComponent(source)}/duplicate`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  })
+}
+
 export async function previewTemplate(name: string, fields: Record<string, string>): Promise<Blob> {
   const res = await fetch(`/api/preview/${encodeURIComponent(name)}`, {
     method: 'POST',
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index f67a332..d6423be 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -1,4 +1,4 @@
-import { createTemplate, getFonts, getLabels, getTemplate, previewTemplate, updateTemplate } from '../api'
+import { createTemplate, duplicateTemplate, getFonts, getLabels, getTemplate, previewTemplate, updateTemplate } from '../api'
 import { navigate } from '../router'
 import type { LabelEntry } from '../types'
 import {
@@ -10,6 +10,8 @@ import {
   isTextType,
   loadCanvasJSON,
 } from '../editor/canvas'
+import { mountLabelMediaSelect } from '../labels'
+import type { LabelMediaSelectHandle } from '../labels'
 import type { Canvas } from 'fabric'
 
 function esc(s: string): string {
@@ -43,6 +45,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
         <button id="btn-back">← Back</button>
         <span class="toolbar-sep"></span>
         <span class="editor-title" id="editor-title">${esc(name)}</span>
+        <code class="editor-media-badge" id="editor-media">${esc(isNew ? newMedia : '')}</code>
         <span class="toolbar-sep"></span>
         <button id="btn-add-text">Add Text</button>
         <button id="btn-delete">Delete</button>
@@ -51,7 +54,13 @@ export function mountTemplateEditor(root: HTMLElement): void {
           <option value="">Loading fonts…</option>
         </select>
         <input id="font-size" type="number" min="6" max="400" value="48" title="Font size" style="width:60px" />
+        <span class="toolbar-sep" id="sep-color" hidden></span>
+        <select id="text-color" title="Text color" hidden>
+          <option value="#000000">Black</option>
+          <option value="#ff0000">Red</option>
+        </select>
         <span class="toolbar-sep"></span>
+        <button id="btn-save-as">Save As</button>
         <button id="btn-preview">Preview</button>
         <button id="btn-save" class="btn-primary">Save</button>
       </div>
@@ -71,9 +80,13 @@ export function mountTemplateEditor(root: HTMLElement): void {
   const btnAddText = root.querySelector<HTMLButtonElement>('#btn-add-text')!
   const btnDelete = root.querySelector<HTMLButtonElement>('#btn-delete')!
   const btnSave = root.querySelector<HTMLButtonElement>('#btn-save')!
+  const btnSaveAs = root.querySelector<HTMLButtonElement>('#btn-save-as')!
   const btnPreview = root.querySelector<HTMLButtonElement>('#btn-preview')!
   const fontSelect = root.querySelector<HTMLSelectElement>('#font-select')!
   const fontSizeInput = root.querySelector<HTMLInputElement>('#font-size')!
+  const textColorSelect = root.querySelector<HTMLSelectElement>('#text-color')!
+  const colorSep = root.querySelector<HTMLSpanElement>('#sep-color')!
+  const mediaBadge = root.querySelector<HTMLElement>('#editor-media')!
   const statusEl = root.querySelector<HTMLDivElement>('#editor-status')!
   const canvasWrap = root.querySelector<HTMLDivElement>('#canvas-wrap')!
   const previewArea = root.querySelector<HTMLDivElement>('#preview-area')!
@@ -81,9 +94,11 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   let fabricCanvas: Canvas | null = null
   let labelMedia: string = newMedia
+  let labelColorCapable = false
   let existsOnServer = !isNew
   let defaultFont = 'DejaVuSans'
   let previewObjectUrl: string | null = null
+  let cachedLabels: LabelEntry[] = []
 
   function showStatus(msg: string, kind: 'success' | 'error' | ''): void {
     if (!msg) { statusEl.hidden = true; return }
@@ -98,6 +113,9 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   async function initEditor(label: LabelEntry): Promise<void> {
     labelMedia = label.id
+    labelColorCapable = label.color === 1
+    mediaBadge.textContent = label.id
+
     const [w, rawH] = label.dots_printable
     // Continuous media report length 0; open at a default working length so the
     // editor canvas isn't zero-height (print length is content-driven server-side).
@@ -106,6 +124,12 @@ export function mountTemplateEditor(root: HTMLElement): void {
     const { canvas } = initCanvas(canvasEl, w, h, getContainerWidth())
     fabricCanvas = canvas
 
+    // Show color control only for two-color media (e.g. 62red / DK-2251)
+    if (labelColorCapable) {
+      colorSep.hidden = false
+      textColorSelect.hidden = false
+    }
+
     // Track selection to drive font controls
     canvas.on('selection:created', updateFontControls)
     canvas.on('selection:updated', updateFontControls)
@@ -114,11 +138,15 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   function updateFontControls(): void {
     if (!fabricCanvas) return
-    type TextProps = { fontFamily?: string; fontSize?: number; type?: string }
+    type TextProps = { fontFamily?: string; fontSize?: number; fill?: string; type?: string }
     const obj = fabricCanvas.getActiveObject() as unknown as TextProps | null
     if (obj && isTextType(obj.type)) {
       if (obj.fontFamily) fontSelect.value = obj.fontFamily
       if (obj.fontSize) fontSizeInput.value = String(Math.round(obj.fontSize))
+      if (labelColorCapable && obj.fill) {
+        const f = (obj.fill as string).toLowerCase()
+        textColorSelect.value = (f === '#ff0000' || f === 'red') ? '#ff0000' : '#000000'
+      }
     }
   }
 
@@ -143,6 +171,15 @@ export function mountTemplateEditor(root: HTMLElement): void {
     }
   })
 
+  textColorSelect.addEventListener('change', () => {
+    if (!fabricCanvas) return
+    const obj = fabricCanvas.getActiveObject()
+    if (obj && isTextType(obj.type)) {
+      obj.set('fill', textColorSelect.value)
+      fabricCanvas.renderAll()
+    }
+  })
+
   btnBack.addEventListener('click', () => {
     document.getElementById('app')?.classList.remove('editor-mode')
     navigate('/templates')
@@ -150,7 +187,8 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   btnAddText.addEventListener('click', () => {
     if (!fabricCanvas) return
-    addTextElement(fabricCanvas, fontSelect.value || defaultFont)
+    const fill = labelColorCapable ? textColorSelect.value : '#000000'
+    addTextElement(fabricCanvas, fontSelect.value || defaultFont, fill)
   })
 
   btnDelete.addEventListener('click', () => {
@@ -160,6 +198,8 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   btnSave.addEventListener('click', () => void doSave())
 
+  btnSaveAs.addEventListener('click', () => void doSaveAs())
+
   btnPreview.addEventListener('click', () => void doPreview())
 
   async function doSave(): Promise<void> {
@@ -187,6 +227,14 @@ export function mountTemplateEditor(root: HTMLElement): void {
     }
   }
 
+  async function doSaveAs(): Promise<void> {
+    // Save current state first so the clone copies the latest canvas
+    await doSave()
+    // Only proceed if we're saved on the server
+    if (!existsOnServer) return
+    showSaveAsModal(name, labelMedia, cachedLabels)
+  }
+
   async function doPreview(): Promise<void> {
     if (!fabricCanvas) return
     btnPreview.disabled = true
@@ -219,6 +267,8 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   // Bootstrap: load label catalog + fonts, then either load existing template or init blank
   Promise.all([getLabels(), getFonts()]).then(async ([labels, fonts]) => {
+    cachedLabels = labels
+
     // Populate font selector
     defaultFont = fonts[0]?.name ?? 'DejaVuSans'
     fontSelect.innerHTML = fonts
@@ -252,3 +302,81 @@ export function mountTemplateEditor(root: HTMLElement): void {
     showStatus(`Failed to load: ${err.message}`, 'error')
   })
 }
+
+function showSaveAsModal(sourceName: string, currentMedia: string, allLabels: LabelEntry[]): void {
+  const overlay = document.createElement('div')
+  overlay.className = 'modal-overlay'
+  overlay.innerHTML = `
+    <div class="modal">
+      <h3>Save As</h3>
+      <div class="modal-status" id="sa-status" hidden></div>
+      <label>
+        New name (slug)
+        <input id="sa-name" type="text" placeholder="my-template-copy" autocomplete="off" />
+        <span class="field-error" id="sa-name-error" hidden></span>
+      </label>
+      <label>Label media</label>
+      <div id="sa-media-container"></div>
+      <div class="modal-actions">
+        <button id="sa-cancel">Cancel</button>
+        <button id="sa-ok" class="btn-primary" disabled>Save As</button>
+      </div>
+    </div>
+  `
+  document.body.appendChild(overlay)
+
+  const nameInput = overlay.querySelector<HTMLInputElement>('#sa-name')!
+  const mediaContainer = overlay.querySelector<HTMLDivElement>('#sa-media-container')!
+  const cancelBtn = overlay.querySelector<HTMLButtonElement>('#sa-cancel')!
+  const okBtn = overlay.querySelector<HTMLButtonElement>('#sa-ok')!
+  const nameError = overlay.querySelector<HTMLSpanElement>('#sa-name-error')!
+  const statusEl = overlay.querySelector<HTMLDivElement>('#sa-status')!
+  let mediaHandle: LabelMediaSelectHandle | null = null
+
+  const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
+
+  function validate(): boolean {
+    const v = nameInput.value.trim()
+    if (!v) { nameError.textContent = 'Name is required'; nameError.hidden = false; return false }
+    if (!SLUG_RE.test(v)) { nameError.textContent = 'Use lowercase letters, numbers, hyphens only'; nameError.hidden = false; return false }
+    nameError.hidden = true
+    return true
+  }
+
+  function updateOk(): void {
+    okBtn.disabled = !nameInput.value.trim() || !mediaHandle?.getValue()
+  }
+
+  nameInput.addEventListener('input', () => { validate(); updateOk() })
+
+  mediaHandle = mountLabelMediaSelect({
+    container: mediaContainer,
+    labels: allLabels,
+    initialValue: currentMedia,
+    onChange: () => updateOk(),
+  })
+  updateOk()
+
+  cancelBtn.addEventListener('click', () => overlay.remove())
+  overlay.addEventListener('click', e => { if (e.target === overlay) overlay.remove() })
+
+  okBtn.addEventListener('click', () => {
+    if (!validate()) return
+    const newName = nameInput.value.trim()
+    const newMedia = mediaHandle?.getValue() ?? ''
+    okBtn.disabled = true
+
+    duplicateTemplate(sourceName, { name: newName, label_media: newMedia })
+      .then(() => {
+        overlay.remove()
+        navigate(`/templates/${newName}`)
+      })
+      .catch((err: Error) => {
+        statusEl.textContent = err.message
+        statusEl.hidden = false
+        okBtn.disabled = false
+      })
+  })
+
+  nameInput.focus()
+}
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 2fd1756..3d763db 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -299,6 +299,14 @@ button:disabled {
   margin-right: 0.5rem;
 }
 
+.editor-media-badge {
+  font-size: 0.75rem;
+  background: #eef2f8;
+  color: #3a5a8a;
+  border-radius: 4px;
+  padding: 0.1rem 0.4rem;
+}
+
 .editor-canvas-wrap {
   overflow: auto;
   background: #e0e0e0;

From 8c9c944aa135f8df2892d82ae722a520fbbfd6f1 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Wed, 3 Jun 2026 22:46:54 -0700
Subject: [PATCH 61/84] New Prompt

---
 ...6-06-03-template-preview-and-media-edit.md | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 prompts/2026-06-03-template-preview-and-media-edit.md

diff --git a/prompts/2026-06-03-template-preview-and-media-edit.md b/prompts/2026-06-03-template-preview-and-media-edit.md
new file mode 100644
index 0000000..8fb1533
--- /dev/null
+++ b/prompts/2026-06-03-template-preview-and-media-edit.md
@@ -0,0 +1,110 @@
+---
+name: 2026-06-03-template-preview-and-media-edit
+status: pending          # pending | completed | failed
+created: 2026-06-03
+model: sonnet            # coding slice
+completed:               # filled when the work is done
+result:                  # one-line summary of the outcome
+---
+
+# Task: Fix editor Preview with variables and surface the color control
+
+Two follow-ups on the canvas editor (`/templates/{name}`), after the Save As + two-color
+slice (commit c960e92) landed:
+
+1. **Preview fails when the template has a variable** (e.g. `{type}`). Preview returns
+   *"Missing required field: 'type'"* — you can't preview layout without inventing values.
+2. **The text-color control is invisible on most templates** — it only appears for two-color
+   media (`62red`), and is fully `hidden` otherwise, so the feature is undiscoverable.
+
+(Changing an existing template's media is already covered by **Save As** — pick a new label
+when cloning — so it is intentionally out of scope here.)
+
+Do them in order (preview → color discoverability). Both are small and independent.
+
+## Before you start
+
+- Read `docs/features/templates.md` (esp. "locked to media", canvas size, field detection),
+  `docs/glossary.md`, and `docs/decisions.md`.
+- **Placeholder syntax is single-brace `{name}`** (`backend/labelforge/templates/fields.py:5`,
+  regex `\{([a-zA-Z0-9_]+)\}`). The user typed `{{type}}`; the regex still matches the inner
+  `{type}`, so `type` becomes a required field. Part 1 must work for the correct `{type}` form;
+  optionally add a one-line syntax hint in the editor (see Part 1, step 4) to stop the
+  double-brace confusion.
+- `code-checkin-and-pr`: work on `dev`, Conventional-Commits prefixes, no `Co-authored-by:`,
+  docs ship with code, changelog entry required.
+
+## Working tree check
+
+Run `git status --porcelain` first; if any file this plan touches has uncommitted changes, list
+them and ask before editing. This prompt file is exempt.
+
+## Key files
+
+- `backend/labelforge/routes/template_print.py` — `_apply_defaults` (raises on missing
+  required), `preview_template` (`POST /preview/{name}`, line ~120). **Print paths must keep
+  requiring real values — only preview gets sample-fill.**
+- `backend/labelforge/templates/fields.py` — `detect_fields`, `resolve_content`
+- `backend/labelforge/models/__init__.py:94` — `PrintRequest { fields }`
+- `frontend/src/pages/template-editor.ts` — `doPreview` (sends empty `fields`, line ~255),
+  the `#text-color` control + `labelColorCapable` gating (lines ~57, 128, 174, 190),
+  `initEditor`, the toolbar, `showSaveAsModal`
+- `frontend/src/editor/canvas.ts` — `initCanvas`, `addTextElement`
+- `frontend/src/labels.ts` — `mountLabelMediaSelect`
+- `frontend/src/api.ts` — `previewTemplate`, `updateTemplate`, `duplicateTemplate`
+
+## What to do
+
+### Part 1 — Preview must not require field values
+
+The editor's Preview is a *layout* check; it should render with sample values, never demand
+real ones. Fix server-side so the behavior is consistent for any caller previewing.
+
+1. In `preview_template` (`template_print.py`), stop calling the strict `_apply_defaults`.
+   Instead fill values so nothing is missing: for each field in `tmpl.field_schema`, use the
+   provided value if present, else `field.default` if set, else a **sample = the field name
+   itself** (so `{type}` renders as the literal text `type`). Never raise "Missing required
+   field" from the preview route. Add a small helper (e.g. `_apply_sample_defaults`) next to
+   `_apply_defaults`; leave `_apply_defaults` unchanged for the print routes.
+2. Any field value the caller *did* pass still wins (so the recall/print preview that passes
+   real values keeps showing them).
+3. Confirm `resolve_content` won't raise: since every detected field now has a value, the
+   `ValueError("Missing required field")` path in `fields.py` can't trigger from preview.
+4. (Nice-to-have, same commit) Add a tiny hint in the editor toolbar or status area noting the
+   placeholder syntax is `{fieldname}` (single braces) — this is what tripped up `{{type}}`.
+
+Acceptance: open a template containing `{type}`, click Preview with no values entered — the PNG
+renders (showing `type` where the variable is) instead of an error.
+
+### Part 2 — Make the color control discoverable
+
+Right now `#text-color` is `hidden` unless the media is two-color, so users never learn it
+exists. Always show it; gate only the *red* option on media capability.
+
+1. Remove the blanket `hidden` on the color control + its separator (`template-editor.ts:57-61,
+   128-131`). Always render it.
+2. On mono media: keep the **Red** `<option>` present but `disabled`, with a `title`/tooltip
+   like "Requires a two-color label (e.g. 62red)". Black is the only selectable value.
+3. On two-color media: Red is selectable (current behavior).
+4. Keep the existing selection-sync (`updateFontControls`) and `addTextElement` default-fill
+   logic working for both states.
+
+Acceptance: on a `62` template the color dropdown is visible with Red greyed-out + tooltip; on
+`62red` Red is selectable and applies.
+
+## Conventions to honor
+
+- Separate commits per part is fine (`fix:` preview, `feat:` color discoverability).
+- Changelog `[Unreleased]` entries for each. Note the container-image rebuild requirement for the
+  frontend changes, as prior entries do.
+- Match existing vanilla-TS style (`esc()`, plain DOM) and Python style (type hints, terse "why"
+  comments only). No framework.
+
+## When done
+
+1. Update this file's frontmatter (`status`, `completed`, `result`).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record any non-obvious decisions in `docs/decisions.md`.
+4. Propose commits (per part). Present file list + one-line message(s); ask
+   `commit these as "<message>"? (y/n)`. On `y`, stage those specific paths and commit on `dev`.
+   Never `git add -A`. Never push.

From 0aa54aadba6dce0731637ae15a11da941cdfdeab Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Thu, 4 Jun 2026 06:53:50 -0700
Subject: [PATCH 62/84] fix: preview fills missing variable fields with sample
 values

---
 backend/labelforge/routes/template_print.py     | 17 ++++++++++++++++-
 ...026-06-03-template-preview-and-media-edit.md |  0
 2 files changed, 16 insertions(+), 1 deletion(-)
 rename prompts/{ => done}/2026-06-03-template-preview-and-media-edit.md (100%)

diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index 8955111..c2c4fdd 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -40,6 +40,20 @@ def _apply_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
     return result
 
 
+def _apply_sample_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
+    """Return values dict with caller-supplied values first, then defaults, then field name as sample.
+
+    Never raises — every field gets a value, so preview always renders.
+    """
+    result = dict(values)
+    for field in template_fields:
+        if field.name not in result:
+            # Use stored default if set; otherwise show the field name itself so
+            # {type} renders as the literal text "type" — makes variables visible in preview.
+            result[field.name] = field.default if field.default is not None else field.name
+    return result
+
+
 @router.post("/print/{name}")
 async def print_template(name: str, body: PrintRequest, override: bool = False) -> dict:
     tmpl = store.get_template(name)
@@ -123,7 +137,8 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
     if tmpl is None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
 
-    values = _apply_defaults(tmpl.field_schema, body.fields)
+    # Preview is a layout check — fill missing fields with samples rather than failing.
+    values = _apply_sample_defaults(tmpl.field_schema, body.fields)
 
     try:
         image = render_template(tmpl, values)
diff --git a/prompts/2026-06-03-template-preview-and-media-edit.md b/prompts/done/2026-06-03-template-preview-and-media-edit.md
similarity index 100%
rename from prompts/2026-06-03-template-preview-and-media-edit.md
rename to prompts/done/2026-06-03-template-preview-and-media-edit.md

From 9f32a630e1126ccb48f38c54e5b18203674f5ae8 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Thu, 4 Jun 2026 06:54:00 -0700
Subject: [PATCH 63/84] feat: text-color control always visible; Red disabled
 on mono media

---
 CHANGELOG.md                                  |  8 +++++++
 frontend/src/pages/template-editor.ts         | 23 +++++++++----------
 ...6-06-03-template-preview-and-media-edit.md |  6 ++---
 3 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 50310e5..88801eb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Text-color control always visible in template editor** — the Black / Red color dropdown in the toolbar is now visible for all templates, not just two-color media. On mono media the Red option is present but disabled, with a tooltip explaining it requires a two-color label (e.g. 62red); on two-color media Red is selectable as before. Hovering over the Add Text button now also shows a tooltip noting `{fieldname}` placeholder syntax. Requires a container image rebuild.
+
+### Fixed
+
+- **Template preview no longer fails when the template has variable fields** — clicking Preview in the editor on a template containing `{fieldname}` placeholders previously returned "Missing required field" because the preview route used the same strict field-validation as the print route. The preview route now fills missing fields with their stored default (if any) or the field name itself as a sample value, so `{type}` renders as the literal text `type`. Passing real field values from the recall UI still works and takes precedence. Requires a container image rebuild.
+
+### Added
+
 - **Save As in template editor** — toolbar now has a **Save As** button that saves the current canvas first, then opens a modal for a new template slug and label media (pre-filled with the current media). Clones the template via `POST /api/templates/{name}/duplicate` and opens the editor on the copy. This is the documented way to re-use a design on different media; the existing template's media is never mutated. The current media is also shown as a read-only badge next to the template name. Requires a container image rebuild.
 - **Full two-color (red) text in templates** — templates on two-color media (`62red` / DK-2251) can now use red text in addition to black. A **Black / Red** toggle appears in the editor toolbar only when the loaded label is two-color (hidden for mono media). Selecting an element and changing the toggle updates its Fabric `fill` to `#000000` or `#ff0000`; new text elements inherit the current selection. The server renderer now emits an RGB image for two-color media, compositing each text element's `fill` as the ink color (red → red plane, black → black plane); lines honor `stroke`, rects honor `fill` and `stroke`. The preview PNG for two-color templates now returns a color image rather than thresholded mono, so the preview reflects actual print output. Printing is unchanged (the print path already promoted L→RGB and passed `red=True` for two-color media). Requires a container image rebuild.
 
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index d6423be..a2ad4c8 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -47,15 +47,15 @@ export function mountTemplateEditor(root: HTMLElement): void {
         <span class="editor-title" id="editor-title">${esc(name)}</span>
         <code class="editor-media-badge" id="editor-media">${esc(isNew ? newMedia : '')}</code>
         <span class="toolbar-sep"></span>
-        <button id="btn-add-text">Add Text</button>
+        <button id="btn-add-text" title="Add a text element. Use {fieldname} placeholders (single braces) for variable fields.">Add Text</button>
         <button id="btn-delete">Delete</button>
         <span class="toolbar-sep"></span>
         <select id="font-select" title="Font family" style="max-width:160px">
           <option value="">Loading fonts…</option>
         </select>
         <input id="font-size" type="number" min="6" max="400" value="48" title="Font size" style="width:60px" />
-        <span class="toolbar-sep" id="sep-color" hidden></span>
-        <select id="text-color" title="Text color" hidden>
+        <span class="toolbar-sep" id="sep-color"></span>
+        <select id="text-color" title="Text color">
           <option value="#000000">Black</option>
           <option value="#ff0000">Red</option>
         </select>
@@ -85,7 +85,6 @@ export function mountTemplateEditor(root: HTMLElement): void {
   const fontSelect = root.querySelector<HTMLSelectElement>('#font-select')!
   const fontSizeInput = root.querySelector<HTMLInputElement>('#font-size')!
   const textColorSelect = root.querySelector<HTMLSelectElement>('#text-color')!
-  const colorSep = root.querySelector<HTMLSpanElement>('#sep-color')!
   const mediaBadge = root.querySelector<HTMLElement>('#editor-media')!
   const statusEl = root.querySelector<HTMLDivElement>('#editor-status')!
   const canvasWrap = root.querySelector<HTMLDivElement>('#canvas-wrap')!
@@ -124,11 +123,10 @@ export function mountTemplateEditor(root: HTMLElement): void {
     const { canvas } = initCanvas(canvasEl, w, h, getContainerWidth())
     fabricCanvas = canvas
 
-    // Show color control only for two-color media (e.g. 62red / DK-2251)
-    if (labelColorCapable) {
-      colorSep.hidden = false
-      textColorSelect.hidden = false
-    }
+    // Red option enabled only for two-color media; always visible so users know it exists.
+    const redOpt = textColorSelect.querySelector<HTMLOptionElement>('option[value="#ff0000"]')!
+    redOpt.disabled = !labelColorCapable
+    if (!labelColorCapable) redOpt.title = 'Requires a two-color label (e.g. 62red)'
 
     // Track selection to drive font controls
     canvas.on('selection:created', updateFontControls)
@@ -143,9 +141,10 @@ export function mountTemplateEditor(root: HTMLElement): void {
     if (obj && isTextType(obj.type)) {
       if (obj.fontFamily) fontSelect.value = obj.fontFamily
       if (obj.fontSize) fontSizeInput.value = String(Math.round(obj.fontSize))
-      if (labelColorCapable && obj.fill) {
+      if (obj.fill) {
         const f = (obj.fill as string).toLowerCase()
-        textColorSelect.value = (f === '#ff0000' || f === 'red') ? '#ff0000' : '#000000'
+        const wantRed = (f === '#ff0000' || f === 'red') && labelColorCapable
+        textColorSelect.value = wantRed ? '#ff0000' : '#000000'
       }
     }
   }
@@ -187,7 +186,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
 
   btnAddText.addEventListener('click', () => {
     if (!fabricCanvas) return
-    const fill = labelColorCapable ? textColorSelect.value : '#000000'
+    const fill = textColorSelect.value  // Red is disabled on mono media; always safe to read
     addTextElement(fabricCanvas, fontSelect.value || defaultFont, fill)
   })
 
diff --git a/prompts/done/2026-06-03-template-preview-and-media-edit.md b/prompts/done/2026-06-03-template-preview-and-media-edit.md
index 8fb1533..56bd87b 100644
--- a/prompts/done/2026-06-03-template-preview-and-media-edit.md
+++ b/prompts/done/2026-06-03-template-preview-and-media-edit.md
@@ -1,10 +1,10 @@
 ---
 name: 2026-06-03-template-preview-and-media-edit
-status: pending          # pending | completed | failed
+status: completed
 created: 2026-06-03
 model: sonnet            # coding slice
-completed:               # filled when the work is done
-result:                  # one-line summary of the outcome
+completed: 2026-06-03
+result: preview route now fills missing fields with sample values; color control always visible with Red disabled on mono
 ---
 
 # Task: Fix editor Preview with variables and surface the color control

From d45638b1d65b0dba417e75beb2724f5a6aefaa53 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Thu, 4 Jun 2026 20:25:44 -0700
Subject: [PATCH 64/84] feat: load previous values on template recall;
 retention keeps latest job per template

---
 CHANGELOG.md                                  |   4 +
 backend/labelforge/history.py                 |  34 +++++-
 backend/labelforge/routes/templates.py        |  13 ++
 docs/decisions.md                             |  28 +++++
 docs/features/history.md                      |   2 +-
 docs/features/settings.md                     |   4 +-
 frontend/src/api.ts                           |   6 +-
 frontend/src/pages/template-recall.ts         |  31 ++++-
 frontend/src/types.ts                         |   5 +
 .../2026-06-04-continuous-render-cutoff.md    | 102 ++++++++++++++++
 .../done/2026-06-04-template-last-values.md   | 112 ++++++++++++++++++
 11 files changed, 328 insertions(+), 13 deletions(-)
 create mode 100644 prompts/done/2026-06-04-continuous-render-cutoff.md
 create mode 100644 prompts/done/2026-06-04-template-last-values.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88801eb..b37bb8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,10 +6,14 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Load previous values on template recall** — the recall form now has a **Load previous values** button (only for templates with variable fields). Clicking it fills the form with the field values from the last time this template was printed, so you can make quick adjustments without re-typing. The button is disabled when the template has no print history. The most recent print job for each template is now also protected from retention pruning, so these values survive cleanup. Requires a container image rebuild.
+
 - **Text-color control always visible in template editor** — the Black / Red color dropdown in the toolbar is now visible for all templates, not just two-color media. On mono media the Red option is present but disabled, with a tooltip explaining it requires a two-color label (e.g. 62red); on two-color media Red is selectable as before. Hovering over the Add Text button now also shows a tooltip noting `{fieldname}` placeholder syntax. Requires a container image rebuild.
 
 ### Fixed
 
+- **Continuous templates now extend to fit large text** — previewing or printing a continuous-roll template (e.g. 62mm endless) where the last text element uses a large font no longer cuts off the bottom of that text. Previously the render trusted the editor's browser-measured font height, which is shorter than what Pillow actually draws at the same point size; the canvas was too short and the last line was clipped. The renderer now measures rasterized text height with Pillow before sizing the canvas. Die-cut template rendering is unchanged.
+
 - **Template preview no longer fails when the template has variable fields** — clicking Preview in the editor on a template containing `{fieldname}` placeholders previously returned "Missing required field" because the preview route used the same strict field-validation as the print route. The preview route now fills missing fields with their stored default (if any) or the field name itself as a sample value, so `{type}` renders as the literal text `type`. Passing real field values from the recall UI still works and takes precedence. Requires a container image rebuild.
 
 ### Added
diff --git a/backend/labelforge/history.py b/backend/labelforge/history.py
index ef2f556..100e77b 100644
--- a/backend/labelforge/history.py
+++ b/backend/labelforge/history.py
@@ -68,6 +68,24 @@ def _save_preview(job_id: int, image: Image.Image) -> None:
         logger.warning("Failed to save preview for job %d", job_id, exc_info=True)
 
 
+def get_latest_field_values(template_name: str) -> tuple[dict | None, str | None]:
+    """Return (field_values, created_at) for the newest print of template_name, or (None, None)."""
+    db_path = settings.data_dir / "data" / "app.db"
+    conn = get_connection(db_path)
+    try:
+        row = conn.execute(
+            """SELECT field_values, created_at FROM print_jobs
+               WHERE template_id = ? AND field_values IS NOT NULL
+               ORDER BY created_at DESC, id DESC LIMIT 1""",
+            (template_name,),
+        ).fetchone()
+    finally:
+        conn.close()
+    if row is None:
+        return None, None
+    return json.loads(row["field_values"]), row["created_at"]
+
+
 def prune_history() -> None:
     try:
         mode = settings_store.get("retention_mode")
@@ -79,24 +97,32 @@ def prune_history() -> None:
         try:
             total = conn.execute("SELECT COUNT(*) FROM print_jobs").fetchone()[0]
 
+            # Newest job per template is always kept so recall pre-fill survives pruning.
+            _keep_latest = (
+                "id NOT IN (SELECT MAX(id) FROM print_jobs"
+                " WHERE template_id IS NOT NULL GROUP BY template_id)"
+            )
+
             if mode == "last_n":
                 count = settings_store.get("retention_count")
                 rows = conn.execute(
-                    """SELECT id, preview_path FROM print_jobs
+                    f"""SELECT id, preview_path FROM print_jobs
                        WHERE pinned = 0
                        AND id NOT IN (
                            SELECT id FROM print_jobs WHERE pinned = 0
                            ORDER BY created_at DESC, id DESC
                            LIMIT ?
-                       )""",
+                       )
+                       AND {_keep_latest}""",  # noqa: S608
                     (count,),
                 ).fetchall()
             elif mode == "last_days":
                 days = settings_store.get("retention_days")
                 rows = conn.execute(
-                    """SELECT id, preview_path FROM print_jobs
+                    f"""SELECT id, preview_path FROM print_jobs
                        WHERE pinned = 0
-                       AND created_at < datetime('now', ?)""",
+                       AND created_at < datetime('now', ?)
+                       AND {_keep_latest}""",  # noqa: S608
                     (f"-{days} days",),
                 ).fetchall()
             else:
diff --git a/backend/labelforge/routes/templates.py b/backend/labelforge/routes/templates.py
index acffa32..6c4722c 100644
--- a/backend/labelforge/routes/templates.py
+++ b/backend/labelforge/routes/templates.py
@@ -4,6 +4,7 @@
 from pydantic import BaseModel
 
 from labelforge.catalog.loader import get_label
+from labelforge.history import get_latest_field_values
 from labelforge.models import Template, TemplateCreate, TemplateUpdate
 from labelforge.routes.auth import require_auth
 from labelforge.templates import store
@@ -74,6 +75,18 @@ async def delete_template(name: str) -> None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
 
 
+class _LastValuesResponse(BaseModel):
+    values: dict | None = None
+    printed_at: str | None = None
+
+
+@router.get("/templates/{name}/last-values", response_model=_LastValuesResponse)
+async def get_template_last_values(name: str) -> _LastValuesResponse:
+    _load_or_404(name)
+    values, printed_at = get_latest_field_values(name)
+    return _LastValuesResponse(values=values, printed_at=printed_at)
+
+
 class _DuplicateRequest(BaseModel):
     name: str
     label_media: str
diff --git a/docs/decisions.md b/docs/decisions.md
index 86e069d..e4fdfd6 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,34 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-04 — Template recall pre-fill uses print history; retention preserves latest job per template
+
+**Decision**: The "Load previous values" button on the recall form reads `field_values` from the newest `print_jobs` row for that template. No new table or column was needed — `field_values` was already stored at print time. `GET /api/templates/{name}/last-values` returns `{values, printed_at}`.
+
+Retention pruning (`prune_history`) now always exempts the highest `id` per `template_id` from deletion in both `last_n` and `last_days` modes (quick-print rows have `template_id = NULL` and are not protected). This is bounded by template count (single-user, small) and does not meaningfully undermine the configured N.
+
+**Why**: The data was already there; the feature is a query and a button. Protecting the latest job per template avoids a surprising edge case where `last_n = 1` + a burst of quick prints silently erases recall pre-fill.
+
+**Would revisit if**: A dedicated "last values" column is needed (e.g. to survive template deletion); at that point a migration to copy the latest values would be appropriate.
+
+---
+
+## 2026-06-04 — Continuous label length measured from Pillow-rasterized text, not Fabric metrics
+
+**Decision**: For continuous-roll templates, `render_template` computes canvas height from PIL-measured text extents, not from Fabric's serialized `height`. Text elements are pre-rendered to PIL sub-images before the canvas is created; the sub-image's `.height` (measured with `multiline_textbbox`) drives `bottommost` for the continuous canvas sizing. Non-text elements (line, rect) still use `height * scaleY` from Fabric — those are reliable.
+
+`_render_text_element` also sizes its sub-image from the same PIL measurement (not `box_h` from Fabric), so text is never clipped inside its own element box regardless of media type. The draw origin is shifted by `-bbox[1]` to cancel any positive ascender gap, keeping the ink flush with the top of the sub-image without affecting the paste position (which is still taken from Fabric's `top`).
+
+**Why**: Fabric measures text with the browser's font engine; PIL measures with FreeType directly. The two disagree — PIL renders taller at the same `fontSize`, with the gap widening as font size grows. For continuous media, trusting Fabric's `height` produced a canvas too short to contain the last line. The root cause was the two-renderer divergence described in the 2026-05-20 server-side rendering ADR: "Divergence shows up as 'preview/print doesn't match the editor.'" This fix makes the server renderer authoritative for its own geometry.
+
+**Considered**:
+- Correct only the canvas height, leave sub-image sized by Fabric `box_h` — rejected; text still clips inside its element box for die-cut media.
+- Add a per-element measurement pass separate from the render pass — rejected; pre-rendering text elements once and reusing the sub-image is cleaner and avoids double font loads.
+
+**Would revisit if**: Fabric's font metrics are made to match PIL (e.g. by using the same font rendering engine server-side), at which point the browser measurement could be trusted for canvas sizing again.
+
+---
+
 ## 2026-06-03 — Two-color template rendering (supersedes "later slice" note)
 
 **Decision**: `render_template` now supports two-color (black + red) media. When `label.color == 1` (e.g. `62red` / DK-2251) the renderer returns a mode-`RGB` image instead of mode-`L`: black pixels are `(0,0,0)`, red pixels are `(255,0,0)`, paper is `(255,255,255)`. The print path in `printer/client.py` already promoted `L→RGB` and passed `red=True` for two-color media (2026-05-31 ADR) — it consumes the RGB image correctly without change. Text color comes from the Fabric element's `fill` property (`#000000` / `#ff0000`); lines use `stroke`; rects use `fill`/`stroke`. The template-preview PNG also returns RGB (color-accurate) instead of the threshold-crushed mono.
diff --git a/docs/features/history.md b/docs/features/history.md
index d2333f9..8976aa1 100644
--- a/docs/features/history.md
+++ b/docs/features/history.md
@@ -75,7 +75,7 @@ User-configurable via Settings ([`settings.md`](settings.md)). Two modes, choose
 - **Keep N days**: retain unpinned rows newer than N days, prune older
 - **Keep forever**: no pruning (default until the user configures otherwise)
 
-Pinned rows are never pruned regardless of mode.
+Pinned rows are never pruned regardless of mode. Additionally, the most recent print job for each template is always kept regardless of mode — this backs the "Load previous values" recall pre-fill feature.
 
 ### Pruning execution
 
diff --git a/docs/features/settings.md b/docs/features/settings.md
index f310654..57bc555 100644
--- a/docs/features/settings.md
+++ b/docs/features/settings.md
@@ -19,8 +19,8 @@ Defaults live in code; the DB only stores overrides. Reading a setting that has
 | Key | Type | Default | Description |
 |---|---|---|---|
 | `retention_mode` | enum | `forever` | `forever` / `last_n` / `last_days` |
-| `retention_count` | int | `500` | When mode = `last_n`, keep this many unpinned rows |
-| `retention_days` | int | `90` | When mode = `last_days`, keep unpinned rows newer than N days |
+| `retention_count` | int | `500` | When mode = `last_n`, keep this many unpinned rows (the most recent print per template is always kept regardless) |
+| `retention_days` | int | `90` | When mode = `last_days`, keep unpinned rows newer than N days (the most recent print per template is always kept regardless) |
 | `default_label_media` | string | `"62"` | Pre-selected in quick-print and new-template flows |
 | `default_font` | string | `"DejaVuSans"` | Pre-selected in quick-print |
 | `default_font_size` | int | `48` | Pre-selected in quick-print |
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 3b0a780..6493dab 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -1,4 +1,4 @@
-import type { BatchPrintResponse, FontInfo, HistoryDetail, HistoryItem, LabelEntry, PrintJobResponse, PrinterStatus, QuickPrintRequest, ReprintResponse, Template, TemplateCreate } from './types'
+import type { BatchPrintResponse, FontInfo, HistoryDetail, HistoryItem, LabelEntry, PrintJobResponse, PrinterStatus, QuickPrintRequest, ReprintResponse, Template, TemplateCreate, TemplateLastValues } from './types'
 
 export const TOKEN_KEY = 'labelforge_token'
 
@@ -130,6 +130,10 @@ export function duplicateTemplate(source: string, body: { name: string; label_me
   })
 }
 
+export function getLastValues(name: string): Promise<TemplateLastValues> {
+  return apiFetch<TemplateLastValues>(`/api/templates/${encodeURIComponent(name)}/last-values`)
+}
+
 export async function previewTemplate(name: string, fields: Record<string, string>): Promise<Blob> {
   const res = await fetch(`/api/preview/${encodeURIComponent(name)}`, {
     method: 'POST',
diff --git a/frontend/src/pages/template-recall.ts b/frontend/src/pages/template-recall.ts
index f8330ba..6e345b2 100644
--- a/frontend/src/pages/template-recall.ts
+++ b/frontend/src/pages/template-recall.ts
@@ -1,7 +1,11 @@
-import { batchPrint, getTemplate, previewTemplate, printTemplate } from '../api'
-import type { FieldSpec, Template } from '../types'
+import { batchPrint, getLastValues, getTemplate, previewTemplate, printTemplate } from '../api'
+import type { FieldSpec, Template, TemplateLastValues } from '../types'
 import { navigate } from '../router'
 
+function fmtDate(iso: string): string {
+  return new Date(iso).toLocaleString(undefined, { month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' })
+}
+
 function esc(s: string): string {
   return s
     .replace(/&/g, '&amp;')
@@ -32,8 +36,11 @@ export function mountTemplateRecall(root: HTMLElement): void {
   const name = nameFromPath()
   root.innerHTML = `<div class="template-recall"><p>Loading…</p></div>`
 
-  getTemplate(name)
-    .then(tpl => renderRecall(root, tpl))
+  Promise.all([
+    getTemplate(name),
+    getLastValues(name).catch(() => ({ values: null, printed_at: null } satisfies TemplateLastValues)),
+  ])
+    .then(([tpl, lastVals]) => renderRecall(root, tpl, lastVals))
     .catch((err: Error) => {
       root.innerHTML = `
         <div class="template-recall">
@@ -48,7 +55,7 @@ export function mountTemplateRecall(root: HTMLElement): void {
     })
 }
 
-function renderRecall(root: HTMLElement, tpl: Template): void {
+function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastValues): void {
   const fields = tpl.field_schema ?? []
   const hasFields = fields.length > 0
   const incrementFields = fields.filter(f => f.increment)
@@ -79,6 +86,7 @@ function renderRecall(root: HTMLElement, tpl: Template): void {
         ` : ''}
 
         <div class="actions">
+          ${hasFields ? `<button type="button" id="btn-load-prev"${lastVals.values ? '' : ' disabled'}>Load previous values${lastVals.printed_at ? ` (${fmtDate(lastVals.printed_at)})` : ''}</button>` : ''}
           <button type="button" id="btn-preview">Preview</button>
           <button type="submit" id="btn-print">Print</button>
         </div>
@@ -93,6 +101,7 @@ function renderRecall(root: HTMLElement, tpl: Template): void {
   const form = root.querySelector<HTMLFormElement>('#recall-form')!
   const btnPreview = root.querySelector<HTMLButtonElement>('#btn-preview')!
   const btnPrint = root.querySelector<HTMLButtonElement>('#btn-print')!
+  const btnLoadPrev = root.querySelector<HTMLButtonElement>('#btn-load-prev')
   const statusMsg = root.querySelector<HTMLDivElement>('#status-msg')!
   const previewArea = root.querySelector<HTMLDivElement>('#preview-area')!
   const previewImg = root.querySelector<HTMLImageElement>('#preview-img')!
@@ -183,6 +192,18 @@ function renderRecall(root: HTMLElement, tpl: Template): void {
 
   btnPreview.addEventListener('click', runPreview)
 
+  btnLoadPrev?.addEventListener('click', () => {
+    const vals = lastVals.values
+    if (!vals) return
+    for (const f of fields) {
+      if (!(f.name in vals)) continue
+      const el = form.querySelector<HTMLInputElement | HTMLSelectElement>(`[name="${CSS.escape(f.name)}"]`)
+      if (el) el.value = vals[f.name]
+    }
+    updateButtons()
+    if (!previewArea.hidden) runPreview()
+  })
+
   form.addEventListener('submit', async (e) => {
     e.preventDefault()
     if (missingRequired()) {
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 2ceaa8e..cdb0be1 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -83,6 +83,11 @@ export interface TemplateCreate {
   canvas_json: Record<string, unknown>;
 }
 
+export interface TemplateLastValues {
+  values: Record<string, string> | null;
+  printed_at: string | null;
+}
+
 export interface HistoryItem {
   id: number;
   template_id: string | null;
diff --git a/prompts/done/2026-06-04-continuous-render-cutoff.md b/prompts/done/2026-06-04-continuous-render-cutoff.md
new file mode 100644
index 0000000..15e410e
--- /dev/null
+++ b/prompts/done/2026-06-04-continuous-render-cutoff.md
@@ -0,0 +1,102 @@
+---
+name: 2026-06-04-continuous-render-cutoff
+status: completed
+created: 2026-06-04
+model: sonnet            # coding + reproduce
+completed: 2026-06-04
+result: Pre-render text subs from PIL metrics; continuous canvas height uses sub.height; die-cut unchanged
+---
+
+# Task: Fix continuous-label render cutting off (length under-extends with large text)
+
+On a **continuous** roll (e.g. `62`, `62red`), the server render/preview of a template comes out
+too short — the bottom is cut off. It's worse when the last line uses a large font: the label
+doesn't extend all the way to fit it.
+
+## Root cause (verify, then fix)
+
+In `backend/labelforge/render/template.py`, both the continuous canvas height and the text raster
+box trust Fabric's serialized `height`, which is a **browser font-metric** value. The server
+draws text with **PIL**, whose pixel height for the same `fontSize` differs (and the gap widens
+with font size). Two coupled symptoms:
+
+- **Canvas too short (continuous):** `render_template` computes
+  `canvas_h = max(top + height*scaleY) + _PADDING` (lines ~220-225) from Fabric's `height`. When
+  PIL renders taller than that, the last line spills past `canvas_h` and is cut.
+- **Text clipped inside its box:** `_render_text_element` sizes its sub-image to
+  `box_h = height*scaleY` (line ~244) and draws into it; PIL text taller than `box_h` is clipped
+  at the bottom even before compositing.
+
+The fix is to size both from the **actual PIL-measured** text height, not Fabric's `height`.
+
+## Before you start
+
+- Read `docs/features/templates.md` (Canvas size — continuous length is content-driven
+  server-side) and skim `docs/decisions.md` (server-side render decision).
+- `code-checkin-and-pr`: work on `dev`, Conventional-Commits prefixes, no `Co-authored-by:`,
+  docs ship with code, changelog entry required.
+- Backend-only change (`render/template.py`). The frontend editor canvas uses a fixed working
+  length (`DEFAULT_CONTINUOUS_LENGTH_DOTS`) and is *not* authoritative for print length — don't
+  touch it; the server render is the source of truth for continuous length.
+
+## Working tree check
+
+Run `git status --porcelain` first; if `render/template.py` (or anything else this touches) has
+uncommitted changes, list them and ask before editing. This prompt file is exempt.
+
+## What to do
+
+1. **Reproduce.** Run the app (`/run` skill or backend + `npm run dev`). Create/open a continuous
+   (`62`) template with a couple of text lines where the **last** line uses a large font
+   (e.g. 100+). Preview it (`POST /api/preview/{name}`) and confirm the bottom is cut off.
+   Capture the rendered PNG so you can confirm the fix later.
+
+2. **Measure real text height.** In `_render_text_element`, after building the PIL font, measure
+   the rendered text box with `ImageDraw.Draw(scratch).multiline_textbbox((0, 0), text,
+   font=pil_font, align=align, spacing=...)` (use the same `spacing` you pass to
+   `multiline_text`, default 4). Size the sub-image to the measured extent (not Fabric `box_h`):
+   - height = `ceil(bbox_bottom)` plus a few px descender allowance; width = `max(box_w,
+     ceil(bbox_right))` so alignment within the box is preserved.
+   - If the bbox top offset (`bbox[1]`) is non-zero, draw at `(0, -bbox[1])` so the ink isn't
+     shifted down. Keep `left/top` paste position unchanged (Fabric `top` is still the element's
+     top) so existing die-cut layouts don't move.
+
+3. **Size the continuous canvas from real extents.** Change the `is_continuous` height calc so the
+   bottommost extent uses the **measured** rendered height for text elements (reuse the same
+   measurement helper), falling back to `height*scaleY` for non-text elements (line/rect/image,
+   whose `height` is reliable). Cleanest: factor a small two-pass — compute each element's
+   `(top + real_height)` once, take the max, add `_PADDING`. Avoid measuring the font twice per
+   element if easy (cache or compute once), but correctness first.
+
+4. **Keep die-cut behavior unchanged.** For non-continuous media `canvas_h` stays
+   `label.dots_printable[1]`; text that overflows a fixed die-cut should still clip to the label
+   (don't grow the canvas there). Only continuous media grows to fit.
+
+5. **Verify, don't build a harness.** This project has **no** Python test setup (no
+   `pyproject.toml`, no `tests/`, no pytest) — do **not** stand one up for this fix. Instead
+   verify behaviorally: re-run the reproduction preview and confirm the full last line is visible
+   and the continuous label extends to fit it, and confirm a die-cut template renders unchanged.
+   A short throwaway `python -c`/scratch script calling `render_template` on a crafted
+   continuous template to assert the output height covers the last line is fine as a sanity check,
+   but don't commit a test file or a harness.
+
+Acceptance: the reproduction template previews with the full last line visible and the label
+extends to fit it; die-cut renders are unchanged.
+
+## Conventions to honor
+
+- One `fix:` commit (code + test + changelog). Keep the changelog entry user-facing.
+- Changelog `[Unreleased]` → Fixed: continuous templates now extend to fit large text; previously
+  a large last line was cut off because the render trusted the editor's font metrics instead of
+  measuring the rasterized text.
+- Match existing Python style (type hints, terse "why"-only comments). No new deps.
+
+## When done
+
+1. Update this file's frontmatter (`status`, `completed`, `result`).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record any non-obvious decision in `docs/decisions.md` (e.g. "continuous length measured from
+   rasterized text, not Fabric metrics").
+4. Propose ONE commit. Present the file list + one-line message; ask
+   `commit these as "<message>"? (y/n)`. On `y`, stage those specific paths and commit on `dev`.
+   Never `git add -A`. Never push.
diff --git a/prompts/done/2026-06-04-template-last-values.md b/prompts/done/2026-06-04-template-last-values.md
new file mode 100644
index 0000000..7dfb2c9
--- /dev/null
+++ b/prompts/done/2026-06-04-template-last-values.md
@@ -0,0 +1,112 @@
+---
+name: 2026-06-04-template-last-values
+status: completed
+created: 2026-06-04
+model: sonnet
+completed: 2026-06-04
+result: Added Load previous values button to recall form backed by print history; retention now preserves latest job per template
+---
+
+# Task: "Load previous values" on template recall, backed by retained print history
+
+When recalling a template to print, the user wants to optionally reload the field values they
+last printed, to make quick changes. We already store every print's `field_values` in the
+`print_jobs` history table — so this is a query + a button, plus a prune tweak so the latest
+values are never pruned away.
+
+Two parts:
+1. A **"Load previous values"** button on the recall form that, if a prior print of this
+   template exists, fills the inputs with those values. Form still opens with field defaults
+   (current behavior) — loading previous values is an explicit, opt-in action.
+2. **Prune always keeps the most recent job per template**, so "previous values" survive
+   retention pruning.
+
+## Before you start
+
+- Read `docs/features/history.md` (retention/pruning), `docs/features/templates.md` (recall
+  flow), and `docs/features/settings.md` (retention settings). Skim `docs/decisions.md`.
+- Data already exists: `print_jobs(template_id, field_values JSON, created_at, pinned, ...)` —
+  schema in `backend/labelforge/db.py:5`; writes in `backend/labelforge/history.py:15`
+  (`insert_job_with_preview`, stores `field_values` as JSON). "Last values" = the newest
+  `print_jobs` row for a `template_id`. **No new table or column is needed.**
+- `code-checkin-and-pr`: work on `dev`, Conventional-Commits prefixes, no `Co-authored-by:`,
+  docs ship with code, changelog entry required.
+
+## Working tree check
+
+Run `git status --porcelain` first; if any file this plan touches has uncommitted changes, list
+them and ask before editing. This prompt file is exempt.
+
+## Key files
+
+- `backend/labelforge/history.py` — add the latest-values query; modify `prune_history` (line ~71)
+- `backend/labelforge/routes/templates.py` — add `GET /api/templates/{name}/last-values`
+- `backend/labelforge/db.py` — schema reference only (no migration needed)
+- `frontend/src/api.ts` — add `getLastValues(name)`
+- `frontend/src/pages/template-recall.ts` — render + wire the button (form, `fieldInput`,
+  `collectFields`, `updateButtons`, `runPreview`)
+- `frontend/src/types.ts` — response type if you add one
+
+## What to do
+
+### Part 1 — Last-values endpoint
+
+1. In `history.py`, add `get_latest_field_values(template_name: str) -> dict | None`: select the
+   newest non-null `field_values` for that template —
+   `SELECT field_values FROM print_jobs WHERE template_id = ? AND field_values IS NOT NULL
+   ORDER BY created_at DESC, id DESC LIMIT 1` — and `json.loads` it (return `None` if no row).
+2. In `routes/templates.py`, add `GET /api/templates/{name}/last-values` (auth like the other
+   template routes). 404 if the template doesn't exist; otherwise return
+   `{"values": <dict> | null, "printed_at": <iso> | null}` (include the row's `created_at` as
+   `printed_at` so the UI can label the button, e.g. "Load previous (Jun 3, 2:14 PM)"). Keep it
+   simple if surfacing the timestamp adds much code — `{"values": ... }` alone is acceptable.
+
+### Part 2 — Recall UI: "Load previous values" button
+
+1. In `template-recall.ts`, fetch last-values alongside `getTemplate` (parallelize). Keep the
+   form opening with field **defaults** as today.
+2. Render a **"Load previous values"** button in the form actions (next to Preview/Print), only
+   when the template has fields. Disable it (or hide it) when no previous values exist.
+3. On click, fill each input/select from the previous values for fields that **still exist** in
+   the current `field_schema` (ignore stale keys; leave fields with no stored value at their
+   default). Then call `updateButtons()` and, if the preview pane is open, `runPreview()`.
+4. Respect existing behavior: required-field validation, batch increment, and live debounced
+   preview must keep working after values are loaded.
+
+### Part 3 — Prune keeps the latest job per template
+
+1. In `prune_history` (`history.py`), exclude the newest job of each template from deletion in
+   **both** the `last_n` and `last_days` branches. Add to each delete-candidate query:
+   `AND id NOT IN (SELECT MAX(id) FROM print_jobs WHERE template_id IS NOT NULL GROUP BY template_id)`.
+   (`MAX(id)` = newest per template since id is monotonic; quick-print rows have `template_id`
+   NULL and are not protected — that's fine, they have no recall form.)
+2. This guarantee is bounded by the number of templates (single-user, small), so it doesn't
+   meaningfully undermine "keep last N". Note the behavior in `docs/features/history.md` and
+   `docs/features/settings.md` (retention): *the most recent print of each template is always
+   kept, to back template recall.* Pinned rows are still always kept.
+
+Acceptance:
+- Print a template with values, go to its recall page → "Load previous values" is enabled;
+  clicking it fills the last-printed values; Preview/Print still work.
+- A template never printed → button disabled/hidden, form shows defaults.
+- With retention `last_n = 1`, print template A, then print 5 quick labels → A's last values are
+  still loadable (its latest job survived pruning).
+
+## Conventions to honor
+
+- Commits: `feat:` for the endpoint+UI; the prune change can ride in the same commit or a small
+  `feat:`/`fix:` of its own — keep docs with the code. Changelog `[Unreleased]` → Added (Load
+  previous values) and Changed (retention keeps latest per template). Note the container rebuild
+  for the frontend change.
+- Match existing vanilla-TS style (`esc()`, plain DOM, `CSS.escape` for selectors) and Python
+  style (type hints, parameterized SQL, terse "why" comments).
+
+## When done
+
+1. Update this file's frontmatter (`status`, `completed`, `result`).
+2. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+3. Record the decision in `docs/decisions.md`: template recall pre-fill is derived from print
+   history (no new storage), and retention now always preserves the latest job per template.
+4. Propose commit(s). Present the file list + one-line message(s); ask
+   `commit these as "<message>"? (y/n)`. On `y`, stage those specific paths and commit on `dev`.
+   Never `git add -A`. Never push.

From 7e3eace1a6ac5c318ee549230ee171a5d0c6a7b7 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Thu, 4 Jun 2026 21:16:22 -0700
Subject: [PATCH 65/84] fix: measure PIL text extents for continuous canvas
 height and sub-image sizing

---
 backend/labelforge/render/template.py | 35 ++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 6 deletions(-)

diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index 56dbc80..18f74a0 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -1,5 +1,6 @@
 import io
 import logging
+import math
 
 import barcode as _barcode_lib
 import qrcode
@@ -135,9 +136,16 @@ def _render_text_element(
     if align not in ("left", "center", "right"):
         align = "left"
 
-    sub = Image.new("L", (max(box_w, 1), max(box_h, 1)), 255)
+    # Measure actual PIL text extent — browser font metrics in Fabric differ from PIL's.
+    scratch = Image.new("L", (1, 1))
+    bbox = ImageDraw.Draw(scratch).multiline_textbbox((0, 0), text, font=pil_font, align=align, spacing=4)
+    real_w = max(box_w, math.ceil(bbox[2]))
+    real_h = math.ceil(bbox[3]) + 4  # +4px descender margin
+
+    sub = Image.new("L", (max(real_w, 1), max(real_h, 1)), 255)
     draw = ImageDraw.Draw(sub)
-    draw.multiline_text((0, 0), text, font=pil_font, fill=0, align=align)
+    # Cancel any positive ascender gap so ink starts at y=0, not shifted down.
+    draw.multiline_text((0, -bbox[1]), text, font=pil_font, fill=0, align=align, spacing=4)
     return sub
 
 
@@ -216,11 +224,26 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
     is_continuous = label.form_factor in _CONTINUOUS_FORM_FACTORS
     two_color = label.color == 1
 
+    # Pre-render text elements once so PIL-measured extents inform continuous canvas height.
+    text_subs: dict[int, Image.Image] = {}
+    for i, obj in enumerate(objects):
+        norm_type = obj.get("type", "").lower().replace("-", "")
+        if norm_type in ("itext", "text", "textbox"):
+            box_w = max(1, int(obj.get("width", 10) * float(obj.get("scaleX", 1.0))))
+            box_h = max(1, int(obj.get("height", 10) * float(obj.get("scaleY", 1.0))))
+            try:
+                text_subs[i] = _render_text_element(obj, values, box_w, box_h)
+            except RenderError:
+                raise
+            except Exception as exc:
+                raise RenderError(f"Failed to render element 'text': {exc}") from exc
+
     if is_continuous:
         bottommost = 0
-        for obj in objects:
+        for i, obj in enumerate(objects):
             t = int(obj.get("top", 0))
-            h = int(obj.get("height", 0) * float(obj.get("scaleY", 1.0)))
+            # Text: use PIL-measured height; other elements: Fabric height is reliable.
+            h = text_subs[i].height if i in text_subs else int(obj.get("height", 0) * float(obj.get("scaleY", 1.0)))
             bottommost = max(bottommost, t + h)
         canvas_h = max(bottommost + _PADDING, 1)
     else:
@@ -232,7 +255,7 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
         canvas = Image.new("L", (canvas_w, canvas_h), 255)
     draw = ImageDraw.Draw(canvas)
 
-    for obj in objects:
+    for i, obj in enumerate(objects):
         obj_type = obj.get("type", "")
         # Fabric v6 serializes `type` as the PascalCase class name (IText, Line,
         # Rect, Image); v5 used lowercase/hyphenated (i-text). Normalize both.
@@ -245,7 +268,7 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
 
         try:
             if norm_type in ("itext", "text", "textbox"):
-                sub = _render_text_element(obj, values, box_w, box_h)
+                sub = text_subs[i]  # pre-rendered above
                 if two_color:
                     rgb = _canvas_color_to_rgb(obj.get("fill")) or (0, 0, 0)
                     _paste_onto(canvas, sub, left, top, angle, rgb=rgb)

From 3f2a5cbacf6fe90bf65ba25935db3a0009000b47 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 17:11:50 -0700
Subject: [PATCH 66/84] chore: fix CI compose + ruff lint for release

Compose job: iterate over docker-compose.yml / docker-compose.dev.yml (correct
filenames) with a hardened loop that skips absent files instead of failing under
bash -e. CLAUDE.md convention note updated to match.

Ruff: import order (I001) in main.py and routes/print.py; datetime.UTC (UP017)
in templates/store.py; E741 ambiguous name in printer/client.py; E501 long-line
wraps in printer/client.py, render/template.py, routes/print.py, and
routes/template_print.py. Applied ruff format across 12 files.
---
 .github/workflows/ci.yml                      |   8 +-
 CHANGELOG.md                                  |   4 +
 CLAUDE.md                                     |   2 +-
 backend/labelforge/history.py                 |   5 +-
 backend/labelforge/main.py                    |   7 +-
 backend/labelforge/models/__init__.py         |   3 +
 backend/labelforge/printer/client.py          |   9 +-
 backend/labelforge/render/fonts.py            |  15 ++-
 backend/labelforge/render/template.py         |  32 +++--
 backend/labelforge/routes/auth.py             |   1 -
 backend/labelforge/routes/fonts.py            |   5 +-
 backend/labelforge/routes/history.py          |  12 +-
 backend/labelforge/routes/print.py            |  56 +++++---
 backend/labelforge/routes/template_print.py   | 112 ++++++++++------
 backend/labelforge/settings_store.py          |   4 +-
 backend/labelforge/templates/store.py         |  12 +-
 .../done/2026-06-05-ci-green-for-release.md   | 126 ++++++++++++++++++
 17 files changed, 296 insertions(+), 117 deletions(-)
 create mode 100644 prompts/done/2026-06-05-ci-green-for-release.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8ae9d0c..1b89ef5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -156,6 +156,10 @@ jobs:
       - uses: actions/checkout@v6
       - name: Validate compose files
         run: |
-          for f in compose.yml compose.dev.yml; do
-            [ -f "$f" ] && docker compose -f "$f" config --quiet && echo "OK $f"
+          for f in docker-compose.yml docker-compose.dev.yml; do
+            if [ -f "$f" ]; then
+              docker compose -f "$f" config --quiet && echo "OK $f"
+            else
+              echo "skip $f (not present)"
+            fi
           done
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b37bb8b..cf14383 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Changed
+
+- **CI: compose validation now targets `docker-compose.yml` / `docker-compose.dev.yml`** — the compose job previously looked for `compose.yml` / `compose.dev.yml` (wrong filenames) and used a `bash -e` one-liner that treated a missing file as a failure. The loop is now hardened to skip absent files and only fail on a bad `docker compose config`. The `CLAUDE.md` convention note is corrected to match the actual filenames. Backend linting (ruff) is also clean: import order fixed in `routes/print.py`, `datetime.UTC` modernisation in `templates/store.py`, and long-line wraps across several `backend/` files.
+
 ### Added
 
 - **Load previous values on template recall** — the recall form now has a **Load previous values** button (only for templates with variable fields). Clicking it fills the form with the field values from the last time this template was printed, so you can make quick adjustments without re-typing. The button is disabled when the template has no print history. The most recent print job for each template is now also protected from retention pruning, so these values survive cleanup. Requires a container image rebuild.
diff --git a/CLAUDE.md b/CLAUDE.md
index 98baf92..e5667cc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -90,7 +90,7 @@ Every task follows: **plan → decide → execute → document**.
 - Line endings: LF only. `.gitattributes` enforces this. If `git diff --stat` shows all files modified, run `git config core.autocrlf input && git checkout -- .`
 - Branches: `main` is protected — the ONLY way in is a pull request, gated by CodeQL and other checks; never push to `main` directly. `dev` is the working branch (solo work commits straight to `dev`). Use `feature/<name>` branches when more than one person is working; merge those to `dev`, then PR `dev` → `main` for a release.
 - Commits: imperative present tense with a Conventional-Commits prefix — `feat:` (user-facing feature), `fix:` (bug fix), `chore:` (config/tooling/deps), `docs:` (docs only). E.g. `feat: add template recall endpoint`. No co-author tags. See the **Code check-in (operational rules)** section below for the full rule set.
-- Compose stack lives at the repo root as `compose.yml`. Dev compose at `compose.dev.yml`.
+- Compose stack lives at the repo root as `docker-compose.yml`. Dev compose at `docker-compose.dev.yml`.
 
 ## Things to never do
 
diff --git a/backend/labelforge/history.py b/backend/labelforge/history.py
index 100e77b..25f07a8 100644
--- a/backend/labelforge/history.py
+++ b/backend/labelforge/history.py
@@ -159,7 +159,10 @@ def prune_history() -> None:
             db_size_after = db_path.stat().st_size if db_path.exists() else 0
             logger.info(
                 "prune_history: pruned %d rows (mode=%s), DB %d → %d bytes",
-                pruned, mode, db_size_before, db_size_after,
+                pruned,
+                mode,
+                db_size_before,
+                db_size_after,
             )
         finally:
             conn.close()
diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 62b666a..01f43c2 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -15,8 +15,8 @@
 from labelforge.render.fonts import load_fonts
 from labelforge.routes import fonts, health, labels
 from labelforge.routes import history as history_router
-from labelforge.routes import print as print_router
 from labelforge.routes import preview as preview_router
+from labelforge.routes import print as print_router
 from labelforge.routes import printer as printer_router
 from labelforge.routes import settings as settings_router
 from labelforge.routes import template_print as template_print_router
@@ -43,9 +43,7 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
             shutil.copy(default_yml, yml_path)
             logger.info("Copied default labels.yml to %s", yml_path)
         else:
-            logger.warning(
-                "labels.yml missing at %s and no default at /app/labels.yml", yml_path
-            )
+            logger.warning("labels.yml missing at %s and no default at /app/labels.yml", yml_path)
 
     db_path = data_dir / "data" / "app.db"
     init_db(db_path)
@@ -109,5 +107,6 @@ async def _retention_loop() -> None:
     async def spa_fallback(request: Request, full_path: str) -> FileResponse:
         if full_path.startswith("api/"):
             from fastapi import HTTPException
+
             raise HTTPException(status_code=404)
         return FileResponse(_FRONTEND_DIST / "index.html")
diff --git a/backend/labelforge/models/__init__.py b/backend/labelforge/models/__init__.py
index b4636c7..541cdd1 100644
--- a/backend/labelforge/models/__init__.py
+++ b/backend/labelforge/models/__init__.py
@@ -55,6 +55,7 @@ class PrintJobResponse(BaseModel):
 
 # ── Templates ────────────────────────────────────────────────────────────────
 
+
 class FieldSpec(BaseModel):
     name: str
     type: Literal["text", "number", "date", "enum"] = "text"
@@ -91,6 +92,7 @@ class TemplateUpdate(BaseModel):
 
 # ── Print / batch ─────────────────────────────────────────────────────────────
 
+
 class PrintRequest(BaseModel):
     fields: dict[str, str] = {}
 
@@ -113,6 +115,7 @@ class BatchPrintResponse(BaseModel):
 
 # ── History ───────────────────────────────────────────────────────────────────
 
+
 class HistoryItem(BaseModel):
     id: int
     template_id: str | None
diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
index 7b88955..06cfaf5 100644
--- a/backend/labelforge/printer/client.py
+++ b/backend/labelforge/printer/client.py
@@ -4,7 +4,8 @@
 #   brother_ql.backends.helpers.send                — transmits bytes to the printer
 #   brother_ql.backends.helpers.backend_factory     — returns {"backend_class": ..., ...}
 #   brother_ql.reader.interpret_response            — parses 32-byte status reply into dict
-#   brother_ql.labels.ALL_LABELS                    — list of Label objects; .tape_size, .identifier, .color
+#   brother_ql.labels.ALL_LABELS                    — list of Label objects;
+#     .tape_size, .identifier, .color
 #
 # Network backend expects printer_identifier in the form "tcp://host[:port]"
 # (port defaults to 9100 when omitted).  The send() helper also accepts
@@ -72,7 +73,7 @@ def _media_id_from_dims(width_mm: int, length_mm: int, tape_color_raw: int | Non
 def _color_capable(media_id: str | None) -> bool:
     if media_id is None:
         return False
-    lbl = next((l for l in ALL_LABELS if l.identifier == media_id), None)
+    lbl = next((lbl for lbl in ALL_LABELS if lbl.identifier == media_id), None)
     return bool(lbl and int(getattr(lbl, "color", 0) or 0))
 
 
@@ -269,7 +270,9 @@ def print_image(
         # print-head width. rotate='auto' (the library default) can flip a
         # wide continuous image into a geometry the printer reads as the wrong
         # roll type. The renderer already produces the correct orientation.
-        instructions = convert(qlr, [img], label_media, cut=True, rotate="0", threshold=PRINT_THRESHOLD, red=red)
+        instructions = convert(
+            qlr, [img], label_media, cut=True, rotate="0", threshold=PRINT_THRESHOLD, red=red
+        )
         identifier = f"tcp://{host}" if backend == "network" else host
         result = send(
             instructions=instructions,
diff --git a/backend/labelforge/render/fonts.py b/backend/labelforge/render/fonts.py
index 68dcc98..988cdbd 100644
--- a/backend/labelforge/render/fonts.py
+++ b/backend/labelforge/render/fonts.py
@@ -8,8 +8,17 @@
 _EXTENSIONS = {".ttf", ".otf"}
 # Style keyword tokens used to split family from style in filename stems.
 _STYLE_TOKENS = {
-    "Bold", "Italic", "Light", "Thin", "Medium", "Regular",
-    "Black", "Condensed", "Oblique", "SemiBold", "ExtraBold",
+    "Bold",
+    "Italic",
+    "Light",
+    "Thin",
+    "Medium",
+    "Regular",
+    "Black",
+    "Condensed",
+    "Oblique",
+    "SemiBold",
+    "ExtraBold",
 }
 
 _font_cache: list["FontInfo"] = []
@@ -17,7 +26,7 @@
 
 @dataclass
 class FontInfo:
-    name: str   # filename stem — used as font identifier in the API
+    name: str  # filename stem — used as font identifier in the API
     path: str
     family: str
     style: str
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index 18f74a0..c837e8a 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -115,9 +115,7 @@ def _paste_onto(
         canvas.paste(sub, (left, top), mask=mask)
 
 
-def _render_text_element(
-    obj: dict, values: dict[str, str], box_w: int, box_h: int
-) -> Image.Image:
+def _render_text_element(obj: dict, values: dict[str, str], box_w: int, box_h: int) -> Image.Image:
     raw = obj.get("labelforge_raw_content") or obj.get("text", "")
     text = resolve_content(raw, values)
 
@@ -138,7 +136,9 @@ def _render_text_element(
 
     # Measure actual PIL text extent — browser font metrics in Fabric differ from PIL's.
     scratch = Image.new("L", (1, 1))
-    bbox = ImageDraw.Draw(scratch).multiline_textbbox((0, 0), text, font=pil_font, align=align, spacing=4)
+    bbox = ImageDraw.Draw(scratch).multiline_textbbox(
+        (0, 0), text, font=pil_font, align=align, spacing=4
+    )
     real_w = max(box_w, math.ceil(bbox[2]))
     real_h = math.ceil(bbox[3]) + 4  # +4px descender margin
 
@@ -150,9 +150,7 @@ def _render_text_element(
 
 
 # TODO: re-enable when QR/barcode 1-bit print bug is fixed
-def _render_qr_element(
-    payload: str, correction: str, box_w: int, box_h: int
-) -> Image.Image:
+def _render_qr_element(payload: str, correction: str, box_w: int, box_h: int) -> Image.Image:
     if not payload:
         raise RenderError("QR payload is empty after field substitution")
     ec = _QR_CORRECTION.get((correction or "M").upper(), ERROR_CORRECT_M)
@@ -181,9 +179,7 @@ def _render_qr_element(
 
 
 # TODO: re-enable when QR/barcode 1-bit print bug is fixed
-def _render_barcode_element(
-    payload: str, symbology: str, box_w: int, box_h: int
-) -> Image.Image:
+def _render_barcode_element(payload: str, symbology: str, box_w: int, box_h: int) -> Image.Image:
     if not payload:
         raise RenderError("Barcode payload is empty after field substitution")
     symb = (symbology or "code128").lower().replace("-", "").replace("_", "")
@@ -243,7 +239,11 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
         for i, obj in enumerate(objects):
             t = int(obj.get("top", 0))
             # Text: use PIL-measured height; other elements: Fabric height is reliable.
-            h = text_subs[i].height if i in text_subs else int(obj.get("height", 0) * float(obj.get("scaleY", 1.0)))
+            h = (
+                text_subs[i].height
+                if i in text_subs
+                else int(obj.get("height", 0) * float(obj.get("scaleY", 1.0)))
+            )
             bottommost = max(bottommost, t + h)
         canvas_h = max(bottommost + _PADDING, 1)
     else:
@@ -299,7 +299,11 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
                     stroke_color = _canvas_color_to_rgb(obj.get("stroke") or "#000000") or (0, 0, 0)
                 else:
                     stroke_color = 0
-                draw.line([(x1, y1), (x2, y2)], fill=stroke_color, width=max(1, int(obj.get("strokeWidth", 1))))
+                draw.line(
+                    [(x1, y1), (x2, y2)],
+                    fill=stroke_color,
+                    width=max(1, int(obj.get("strokeWidth", 1))),
+                )
 
             elif norm_type == "rect":
                 sw = max(1, int(obj.get("strokeWidth", 1)))
@@ -321,7 +325,9 @@ def render_template(template: Template, values: dict[str, str]) -> Image.Image:
                     fill_v = _canvas_color_to_l(obj.get("fill"))
                     sub = Image.new("L", (box_w, box_h), 255)
                     sub_draw = ImageDraw.Draw(sub)
-                    sub_draw.rectangle([0, 0, box_w - 1, box_h - 1], fill=fill_v, outline=0, width=sw)
+                    sub_draw.rectangle(
+                        [0, 0, box_w - 1, box_h - 1], fill=fill_v, outline=0, width=sw
+                    )
                     _paste_onto(canvas, sub, left, top, angle)
 
             else:
diff --git a/backend/labelforge/routes/auth.py b/backend/labelforge/routes/auth.py
index a8de501..e2528cf 100644
--- a/backend/labelforge/routes/auth.py
+++ b/backend/labelforge/routes/auth.py
@@ -1,4 +1,3 @@
-
 from fastapi import Header, HTTPException
 
 from labelforge.config import settings
diff --git a/backend/labelforge/routes/fonts.py b/backend/labelforge/routes/fonts.py
index 7e2418b..1bc38f7 100644
--- a/backend/labelforge/routes/fonts.py
+++ b/backend/labelforge/routes/fonts.py
@@ -9,7 +9,4 @@
 
 @router.get("/fonts", response_model=list[FontInfo])
 async def list_fonts() -> list[FontInfo]:
-    return [
-        FontInfo(name=f.name, path=f.path, family=f.family, style=f.style)
-        for f in get_fonts()
-    ]
+    return [FontInfo(name=f.name, path=f.path, family=f.family, style=f.style) for f in get_fonts()]
diff --git a/backend/labelforge/routes/history.py b/backend/labelforge/routes/history.py
index 52612c5..8d2473f 100644
--- a/backend/labelforge/routes/history.py
+++ b/backend/labelforge/routes/history.py
@@ -100,9 +100,7 @@ async def get_history(job_id: int) -> HistoryDetail:
 async def history_preview(job_id: int) -> Response:
     conn = get_connection(_db_path())
     try:
-        row = conn.execute(
-            "SELECT preview_path FROM print_jobs WHERE id = ?", (job_id,)
-        ).fetchone()
+        row = conn.execute("SELECT preview_path FROM print_jobs WHERE id = ?", (job_id,)).fetchone()
     finally:
         conn.close()
     if row is None:
@@ -216,9 +214,7 @@ async def _reprint_quick(job_id: int, row) -> dict:
 async def pin_history(job_id: int, body: PinRequest) -> HistoryItem:
     conn = get_connection(_db_path())
     try:
-        if not conn.execute(
-            "SELECT 1 FROM print_jobs WHERE id = ?", (job_id,)
-        ).fetchone():
+        if not conn.execute("SELECT 1 FROM print_jobs WHERE id = ?", (job_id,)).fetchone():
             raise HTTPException(status_code=404, detail=f"Print job {job_id} not found")
         conn.execute(
             "UPDATE print_jobs SET pinned = ? WHERE id = ?",
@@ -235,9 +231,7 @@ async def pin_history(job_id: int, body: PinRequest) -> HistoryItem:
 async def delete_history(job_id: int) -> None:
     conn = get_connection(_db_path())
     try:
-        row = conn.execute(
-            "SELECT preview_path FROM print_jobs WHERE id = ?", (job_id,)
-        ).fetchone()
+        row = conn.execute("SELECT preview_path FROM print_jobs WHERE id = ?", (job_id,)).fetchone()
         if row is None:
             raise HTTPException(status_code=404, detail=f"Print job {job_id} not found")
         conn.execute("DELETE FROM print_jobs WHERE id = ?", (job_id,))
diff --git a/backend/labelforge/routes/print.py b/backend/labelforge/routes/print.py
index a2b7cb6..6b88fd6 100644
--- a/backend/labelforge/routes/print.py
+++ b/backend/labelforge/routes/print.py
@@ -2,12 +2,18 @@
 
 from fastapi import APIRouter, Depends, HTTPException
 
+from labelforge import settings_store
 from labelforge.catalog.loader import get_label
 from labelforge.config import settings
-from labelforge import settings_store
 from labelforge.history import insert_job_with_preview
 from labelforge.models import PrintJobResponse, QuickPrintRequest
-from labelforge.printer.client import PrintError, StatusUnavailable, media_compatible, print_image, status_read
+from labelforge.printer.client import (
+    PrintError,
+    StatusUnavailable,
+    media_compatible,
+    print_image,
+    status_read,
+)
 from labelforge.render.text import RenderError, render_text
 from labelforge.routes.auth import require_auth
 
@@ -48,28 +54,36 @@ async def quick_print(request: QuickPrintRequest, override: bool = False) -> Pri
             )
             if status["errors"]:
                 code = status["errors"][0].lower().replace(" ", "_")
-                raise HTTPException(status_code=409, detail={
-                    "error": "printer_error",
-                    "code": code,
-                    "message": f"Printer error: {', '.join(status['errors'])}",
-                    "raw": status,
-                })
-            if status["media_id"] is not None and not media_compatible(status["media_id"], request.label_media):
+                raise HTTPException(
+                    status_code=409,
+                    detail={
+                        "error": "printer_error",
+                        "code": code,
+                        "message": f"Printer error: {', '.join(status['errors'])}",
+                        "raw": status,
+                    },
+                )
+            media_id = status["media_id"]
+            if media_id is not None and not media_compatible(media_id, request.label_media):
                 if not override:
-                    raise HTTPException(status_code=409, detail={
-                        "error": "media_mismatch",
-                        "expected": request.label_media,
-                        "loaded": status["media_id"],
-                        "override_allowed": True,
-                        "message": (
-                            f"Printer has {status['media_id']} loaded, "
-                            f"template expects {request.label_media}. "
-                            "Pass override=true to print anyway."
-                        ),
-                    })
+                    raise HTTPException(
+                        status_code=409,
+                        detail={
+                            "error": "media_mismatch",
+                            "expected": request.label_media,
+                            "loaded": media_id,
+                            "override_allowed": True,
+                            "message": (
+                                f"Printer has {media_id} loaded, "
+                                f"template expects {request.label_media}. "
+                                "Pass override=true to print anyway."
+                            ),
+                        },
+                    )
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
-                    status["media_id"], request.label_media,
+                    media_id,
+                    request.label_media,
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index c2c4fdd..a40a24c 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -14,7 +14,14 @@
     BatchPrintResponse,
     PrintRequest,
 )
-from labelforge.printer.client import PrintError, StatusUnavailable, media_compatible, print_image, status_read, to_print_bitmap
+from labelforge.printer.client import (
+    PrintError,
+    StatusUnavailable,
+    media_compatible,
+    print_image,
+    status_read,
+    to_print_bitmap,
+)
 from labelforge.render.template import render_template
 from labelforge.render.text import RenderError
 from labelforge.routes.auth import require_auth
@@ -41,7 +48,8 @@ def _apply_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
 
 
 def _apply_sample_defaults(template_fields, values: dict[str, str]) -> dict[str, str]:
-    """Return values dict with caller-supplied values first, then defaults, then field name as sample.
+    """Return values dict with caller-supplied values first, then defaults,
+    then field name as sample.
 
     Never raises — every field gets a value, so preview always renders.
     """
@@ -77,28 +85,36 @@ async def print_template(name: str, body: PrintRequest, override: bool = False)
             )
             if status["errors"]:
                 code = status["errors"][0].lower().replace(" ", "_")
-                raise HTTPException(status_code=409, detail={
-                    "error": "printer_error",
-                    "code": code,
-                    "message": f"Printer error: {', '.join(status['errors'])}",
-                    "raw": status,
-                })
-            if status["media_id"] is not None and not media_compatible(status["media_id"], tmpl.label_media):
+                raise HTTPException(
+                    status_code=409,
+                    detail={
+                        "error": "printer_error",
+                        "code": code,
+                        "message": f"Printer error: {', '.join(status['errors'])}",
+                        "raw": status,
+                    },
+                )
+            media_id = status["media_id"]
+            if media_id is not None and not media_compatible(media_id, tmpl.label_media):
                 if not override:
-                    raise HTTPException(status_code=409, detail={
-                        "error": "media_mismatch",
-                        "expected": tmpl.label_media,
-                        "loaded": status["media_id"],
-                        "override_allowed": True,
-                        "message": (
-                            f"Printer has {status['media_id']} loaded, "
-                            f"template expects {tmpl.label_media}. "
-                            "Pass override=true to print anyway."
-                        ),
-                    })
+                    raise HTTPException(
+                        status_code=409,
+                        detail={
+                            "error": "media_mismatch",
+                            "expected": tmpl.label_media,
+                            "loaded": media_id,
+                            "override_allowed": True,
+                            "message": (
+                                f"Printer has {media_id} loaded, "
+                                f"template expects {tmpl.label_media}. "
+                                "Pass override=true to print anyway."
+                            ),
+                        },
+                    )
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
-                    status["media_id"], tmpl.label_media,
+                    media_id,
+                    tmpl.label_media,
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
@@ -154,7 +170,9 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
 
 
 @router.post("/print/{name}/batch", response_model=BatchPrintResponse)
-async def batch_print(name: str, body: BatchPrintRequest, override: bool = False) -> BatchPrintResponse:
+async def batch_print(
+    name: str, body: BatchPrintRequest, override: bool = False
+) -> BatchPrintResponse:
     count = len(body.labels)
     if count < 1:
         raise HTTPException(status_code=400, detail="Batch count must be >= 1")
@@ -176,28 +194,36 @@ async def batch_print(name: str, body: BatchPrintRequest, override: bool = False
             )
             if status["errors"]:
                 code = status["errors"][0].lower().replace(" ", "_")
-                raise HTTPException(status_code=409, detail={
-                    "error": "printer_error",
-                    "code": code,
-                    "message": f"Printer error: {', '.join(status['errors'])}",
-                    "raw": status,
-                })
-            if status["media_id"] is not None and not media_compatible(status["media_id"], tmpl.label_media):
+                raise HTTPException(
+                    status_code=409,
+                    detail={
+                        "error": "printer_error",
+                        "code": code,
+                        "message": f"Printer error: {', '.join(status['errors'])}",
+                        "raw": status,
+                    },
+                )
+            media_id = status["media_id"]
+            if media_id is not None and not media_compatible(media_id, tmpl.label_media):
                 if not override:
-                    raise HTTPException(status_code=409, detail={
-                        "error": "media_mismatch",
-                        "expected": tmpl.label_media,
-                        "loaded": status["media_id"],
-                        "override_allowed": True,
-                        "message": (
-                            f"Printer has {status['media_id']} loaded, "
-                            f"template expects {tmpl.label_media}. "
-                            "Pass override=true to print anyway."
-                        ),
-                    })
+                    raise HTTPException(
+                        status_code=409,
+                        detail={
+                            "error": "media_mismatch",
+                            "expected": tmpl.label_media,
+                            "loaded": media_id,
+                            "override_allowed": True,
+                            "message": (
+                                f"Printer has {media_id} loaded, "
+                                f"template expects {tmpl.label_media}. "
+                                "Pass override=true to print anyway."
+                            ),
+                        },
+                    )
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
-                    status["media_id"], tmpl.label_media,
+                    media_id,
+                    tmpl.label_media,
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
@@ -246,6 +272,4 @@ async def batch_print(name: str, body: BatchPrintRequest, override: bool = False
             ).model_dump(),
         )
 
-    return BatchPrintResponse(
-        batch_id=batch_id, jobs=jobs, succeeded=succeeded, failed=failed
-    )
+    return BatchPrintResponse(batch_id=batch_id, jobs=jobs, succeeded=succeeded, failed=failed)
diff --git a/backend/labelforge/settings_store.py b/backend/labelforge/settings_store.py
index 0e82a6b..04cd231 100644
--- a/backend/labelforge/settings_store.py
+++ b/backend/labelforge/settings_store.py
@@ -57,9 +57,7 @@ def validate(key: str, value: Any) -> None:
     elif not isinstance(value, vtype):
         raise ValueError(f"Setting '{key}' expects {vtype.__name__}, got {type(value).__name__}")
     if "enum" in entry and value not in entry["enum"]:
-        raise ValueError(
-            f"Setting '{key}' must be one of {sorted(entry['enum'])}, got {value!r}"
-        )
+        raise ValueError(f"Setting '{key}' must be one of {sorted(entry['enum'])}, got {value!r}")
 
 
 def get_all() -> dict[str, Any]:
diff --git a/backend/labelforge/templates/store.py b/backend/labelforge/templates/store.py
index 6d81b97..cbc2ad2 100644
--- a/backend/labelforge/templates/store.py
+++ b/backend/labelforge/templates/store.py
@@ -1,7 +1,7 @@
 import json
 import re
 import sqlite3
-from datetime import datetime, timezone
+from datetime import datetime
 
 from labelforge.config import settings
 from labelforge.db import get_connection
@@ -15,7 +15,7 @@ def _db_path():
 
 
 def _now_utc() -> str:
-    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
 def _row_to_template(row: sqlite3.Row) -> Template:
@@ -92,9 +92,7 @@ def create_template(data: TemplateCreate) -> Template:
             ),
         )
         conn.commit()
-        row = conn.execute(
-            "SELECT * FROM templates WHERE name = ?", (data.name,)
-        ).fetchone()
+        row = conn.execute("SELECT * FROM templates WHERE name = ?", (data.name,)).fetchone()
         return _row_to_template(row)
     finally:
         conn.close()
@@ -179,9 +177,7 @@ def duplicate(name: str, new_name: str, new_label_media: str) -> Template:
             ),
         )
         conn.commit()
-        row = conn.execute(
-            "SELECT * FROM templates WHERE name = ?", (new_name,)
-        ).fetchone()
+        row = conn.execute("SELECT * FROM templates WHERE name = ?", (new_name,)).fetchone()
         return _row_to_template(row)
     finally:
         conn.close()
diff --git a/prompts/done/2026-06-05-ci-green-for-release.md b/prompts/done/2026-06-05-ci-green-for-release.md
new file mode 100644
index 0000000..4b97716
--- /dev/null
+++ b/prompts/done/2026-06-05-ci-green-for-release.md
@@ -0,0 +1,126 @@
+---
+name: 2026-06-05-ci-green-for-release
+status: completed
+created: 2026-06-05
+model: sonnet            # opus = research/planning, sonnet = coding
+completed: 2026-06-05
+result: CI compose job fixed (docker-compose.yml filenames + hardened loop); CLAUDE.md convention corrected; ruff lint clean (import order, datetime.UTC, all E501 long lines)
+---
+
+# Task: Get CI green on `dev` ahead of the first release PR
+
+Two CI jobs are red and block the eventual `dev → main` release PR: the **compose**
+validation job and the **python** (ruff) job. Fix both so every required check passes.
+These are mechanical lint/config fixes — no runtime behavior changes.
+
+## Before you start
+
+- The compose files are **`docker-compose.yml`** / **`docker-compose.dev.yml`** and
+  **stay that way** — `docker-compose.yml` is the standard naming across the owner's dev
+  projects. Do **not** rename them. The CI compose job is wrong (it looks for
+  `compose.yml`), and `CLAUDE.md` documents the wrong convention; both get corrected to
+  match the actual filenames.
+- The CI definition is `.github/workflows/ci.yml`. The relevant jobs are `python`
+  (runs `ruff check .`, `ruff format --check .`, `mypy backend`, `pytest -q`) and
+  `compose` (currently loops over `compose.yml compose.dev.yml` running
+  `docker compose config` — wrong filenames, and `bash -e` makes the failing `[ -f ]`
+  test the script's last command → exit 1).
+- ruff config is in `pyproject.toml`: `line-length = 100`, `select = ["E","F","I","W","B","UP"]`.
+- Work on `dev`. This repo adopts `code-checkin-and-pr` — Conventional-Commits prefixes,
+  no `Co-authored-by:`, docs ship with code.
+
+## Working tree check
+
+Before making any edits, run `git status --porcelain` and cross-reference the files this
+plan touches (`.github/workflows/ci.yml`, `CLAUDE.md`, and several files under
+`backend/labelforge/`). If any have uncommitted changes, list them and ask before
+touching. This handoff file is exempt.
+
+## What to do
+
+### 1. Compose job (point CI at the real filenames + harden the loop)
+
+Keep the files named `docker-compose.yml` / `docker-compose.dev.yml`. Fix everything
+else to match that.
+
+- In `.github/workflows/ci.yml`, change the `compose` job's loop to iterate over
+  `docker-compose.yml docker-compose.dev.yml`, and harden it so a genuinely-absent file
+  is a skip rather than a `bash -e` failure:
+
+  ```yaml
+        run: |
+          for f in docker-compose.yml docker-compose.dev.yml; do
+            if [ -f "$f" ]; then
+              docker compose -f "$f" config --quiet && echo "OK $f"
+            else
+              echo "skip $f (not present)"
+            fi
+          done
+  ```
+
+- Correct `CLAUDE.md` so the documented convention matches reality. In the **Repo
+  conventions** section it currently reads: *"Compose stack lives at the repo root as
+  `compose.yml`. Dev compose at `compose.dev.yml`."* Change those to `docker-compose.yml`
+  and `docker-compose.dev.yml`.
+- The compose files themselves are already valid Compose v2 (have `name:` + `services:`,
+  no legacy `version:` key) — do **not** rename or restructure them; leave them as-is.
+
+### 2. Python job (ruff)
+
+Reproduce CI locally from the repo root (CI runs ruff against `.`, mypy against `backend`):
+
+- `pip install -e .[dev]` (or use the existing venv).
+- `ruff check --fix .` — auto-resolves the import-sort (`I001`) and `datetime.UTC`
+  (`UP017`) findings (the "4 fixable" ones), including:
+  - `backend/labelforge/main.py` — unsorted import block.
+  - `backend/labelforge/routes/print.py` — unsorted import block.
+  - `backend/labelforge/templates/store.py:18` — `datetime.now(timezone.utc)` →
+    `datetime.now(datetime.UTC)` (adjust the import accordingly).
+- Manually fix the remaining `E501` (line-too-long, 100) — ruff won't auto-wrap these:
+  - `backend/labelforge/printer/client.py:7` — split the long `# ... .color` comment
+    across two comment lines.
+  - `backend/labelforge/routes/print.py` and
+    `backend/labelforge/routes/template_print.py` — the long
+    `from labelforge.printer.client import PrintError, StatusUnavailable, media_compatible, print_image, status_read, to_print_bitmap`
+    line: convert to a parenthesized multiline import.
+  - `backend/labelforge/routes/template_print.py:72`, `:142`, `:170` — wrap the long
+    `media_compatible(status["media_id"], tmpl.label_media)` conditionals and the
+    `batch_print(...)` signature. Prefer extracting a local
+    (e.g. `media_id = status["media_id"]`) over awkward line continuations.
+- The findings list in the failing run is representative, not exhaustive ("Found 15
+  errors"). Do **not** hand-fix from this list — make the actual commands pass:
+  `ruff check .` reports **zero** errors and `ruff format --check .` passes. Run
+  `ruff format .` and review its diff; if it reformats anything, that change is required
+  for CI and should be included (keep it scoped to files ruff actually touches).
+- Confirm the rest of the python job still passes: `mypy backend` and `pytest -q`.
+
+### 3. Changelog
+
+Add one `chore:`-flavored entry under `## [Unreleased]` in `CHANGELOG.md` (developer/
+process-facing, no runtime change) noting the compose CI job fix (correct
+`docker-compose.yml` / `docker-compose.dev.yml` filenames + hardened loop), the matching
+`CLAUDE.md` convention correction, and the ruff lint/format cleanup.
+
+## Conventions to honor
+
+- LF line endings only (`.gitattributes` enforces). If `git diff --stat` shows the whole
+  tree modified, run `git config core.autocrlf input && git checkout -- .`.
+- Keep the diff scoped: lint fixes only, no opportunistic refactors beyond what ruff
+  requires.
+- No runtime/behavior changes — this is purely CI-green plumbing.
+
+## When done
+
+1. Verify locally, then report the one-line result:
+   `ruff check . && ruff format --check . && mypy backend && pytest -q` all pass, and the
+   compose loop (`for f in docker-compose.yml docker-compose.dev.yml; do docker compose -f "$f" config -q && echo OK $f; done`)
+   succeeds.
+2. Update this file's frontmatter: set `status`, `completed` (2026-06-05), and `result`.
+3. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+4. Record any non-obvious decision (e.g. standardizing on `docker-compose.yml` naming
+   across projects) in `docs/decisions.md` if it rises to an ADR; a one-liner is fine if
+   it doesn't.
+5. Propose ONE commit covering the CI workflow edit, the `CLAUDE.md` convention fix, the
+   backend lint fixes, the changelog, and this prompt move. Present the file list and a
+   one-line message; ask `commit these as "chore: fix CI compose + ruff lint for release"? (y/n)`.
+   On `y`, stage those specific paths (never `git add -A`) and commit on `dev`. Never push.

From 3785b68ad7b1b5cde880cc86ac1f74d27c43cf61 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 17:12:30 -0700
Subject: [PATCH 67/84] new prompt

---
 ...2026-06-05-catalog-reconcile-on-upgrade.md | 162 ++++++++++++++++++
 1 file changed, 162 insertions(+)
 create mode 100644 prompts/2026-06-05-catalog-reconcile-on-upgrade.md

diff --git a/prompts/2026-06-05-catalog-reconcile-on-upgrade.md b/prompts/2026-06-05-catalog-reconcile-on-upgrade.md
new file mode 100644
index 0000000..e6816ec
--- /dev/null
+++ b/prompts/2026-06-05-catalog-reconcile-on-upgrade.md
@@ -0,0 +1,162 @@
+---
+name: 2026-06-05-catalog-reconcile-on-upgrade
+status: pending          # pending | completed | failed
+created: 2026-06-05
+model: sonnet            # opus = research/planning, sonnet = coding
+completed:               # filled when the work is done
+result:                  # one-line summary of the outcome
+---
+
+# Task: Reconcile the shipped `labels.yml` into the operator's copy on upgrade (issue #16)
+
+Closes GitHub issue **#16** ("labels.yml doesn't refresh when upgrading"). Today the
+bundled default catalog is copied into `$DATA_DIR/labels.yml` **only on first run**
+(`backend/labelforge/main.py:39-44`, `if not yml_path.exists()`). After that, upgrades
+never deliver new media or corrected metadata (e.g. fixed `brother_part` SKUs) to an
+existing install. We will add a **non-destructive 3-way merge** at startup that updates
+the operator's file without clobbering their customizations.
+
+## Before you start
+
+- Read `docs/features/label-catalog.md` (the two-source model: library = physical truth,
+  `labels.yml` = UX metadata keyed by `id`), `docs/architecture.md`, and
+  `docs/decisions.md`. Load `backend/labelforge/main.py` and
+  `backend/labelforge/catalog/loader.py` — the loader already anticipates this work (see
+  the `POST /api/admin/reload-catalog` comment near line 49).
+- **Source is the bundled image default at `/app/labels.yml`, NOT the internet.** CLAUDE.md
+  says "Don't auto-update the label catalog from the internet" — this feature reads only
+  the default shipped inside the image, so it does not violate that rule. Call this out in
+  the ADR so the distinction is on record.
+- Stack is locked: **PyYAML** for the catalog (no `ruamel.yaml` — that would be a stack
+  change needing its own ADR). Accept that a PyYAML round-trip drops comments/formatting
+  from the operator's file; mitigate with a mandatory backup-before-write (see below).
+- Single-user homelab app — no migrations framework, no multi-user concerns.
+- Work on `dev`. Conventional-Commits prefixes, no `Co-authored-by:`, docs ship with code.
+
+## Working tree check
+
+Run `git status --porcelain` first. This plan touches `backend/labelforge/main.py`, adds
+`backend/labelforge/catalog/reconcile.py` (+ tests), and may add a route + a config field.
+A separate CI-fix session may be in flight touching `backend/labelforge/main.py` (import
+sort), `.github/workflows/ci.yml`, `CLAUDE.md`, and other `backend/labelforge/` lint fixes
+— if `main.py` (or anything you need) shows uncommitted changes, **stop and ask** rather
+than risk a conflicting edit. Also note: there's an untracked junk file
+`backend/labelforge/routes/template_print.py.tmp.*` — leave it alone (not yours to commit).
+
+## Design (follow this)
+
+### State
+
+- `default_path = /app/labels.yml` — the image's bundled default (read-only truth for "what
+  the current release ships").
+- `yml_path = $DATA_DIR/labels.yml` — the operator's live file (what `load_catalog` reads).
+- `baseline_path = $DATA_DIR/data/labels.default.yml` — **new**: a copy of the bundled
+  default as it was the *last time we synced*. This is both the change-detector and the
+  "old default" leg of the 3-way merge. Store it under `$DATA_DIR/data/` (alongside
+  `app.db`), not at the data-dir root, so it isn't mistaken for an operator file.
+
+### Startup flow (replaces the `if not yml_path.exists()` block in `main.py`)
+
+1. **First run** (`yml_path` missing): copy `default_path` → `yml_path` **and** copy
+   `default_path` → `baseline_path`. Done (no merge needed).
+2. **No baseline yet but operator file exists** (existing install upgrading *to* this
+   feature): we cannot know which fields the operator customized, so do the safe thing —
+   **add brand-new entries only** (ids in default but not in the operator file), never
+   touch existing entries — then write `baseline_path = copy of default_path`. Log clearly
+   that field-level corrections will apply on the *next* default change, not this one.
+3. **Baseline exists**: if `default_path` bytes == `baseline_path` bytes → nothing changed,
+   no-op. Otherwise run the 3-way merge (below), back up the operator file, write the
+   merged result to `yml_path`, then overwrite `baseline_path` with `default_path`.
+4. Backup-before-write: before overwriting `yml_path`, copy it to
+   `$DATA_DIR/labels.yml.bak` (single rolling backup is fine). Log the path.
+5. Wrap the whole reconcile in try/except and log-but-continue on failure — a botched merge
+   must never stop the app from starting. On failure, leave the operator file untouched and
+   load whatever is currently on disk.
+
+### Merge algorithm — put it in a pure, testable function
+
+Add `backend/labelforge/catalog/reconcile.py` with a **pure** function operating on parsed
+data (no file IO), e.g.:
+
+```python
+def merge_catalog(operator: dict, old_default: dict, new_default: dict) -> tuple[dict, list[str]]:
+    """3-way merge of labels.yml documents keyed by entry id.
+    Returns (merged_document, change_log_lines). Operator always wins on conflict."""
+```
+
+Rules (entries are `{"labels": [ {id, display_name, ...}, ... ]}`, keyed by `id`):
+
+- **New entry** (id in `new_default`, not in `operator`): add it verbatim. Log `added <id>`.
+- **Existing entry** (id in both): copy the operator entry, then for each field present in
+  `new_default[id]`:
+  - `old = old_default[id].get(field)`, `op = operator[id].get(field)`, `new = new_default[id][field]`.
+  - If `op == old` (operator never customized this field relative to baseline) **and**
+    `new != op`: take `new`. Log `updated <id>.<field>`.
+  - Else (operator customized it, i.e. `op != old`): **keep the operator's value.**
+  - Fields the operator added that aren't in the default: keep them untouched.
+- **Operator-only entry** (id in `operator`, not in `new_default`): keep as-is. This covers
+  custom media the operator added. **Never delete it** — even if it was a default entry that
+  a later release removed. Log nothing or `kept custom <id>` at debug.
+- Ordering: preserve the operator's existing entry order; append brand-new entries after,
+  in `new_default` order. Round-trip with `yaml.safe_dump(..., sort_keys=False, allow_unicode=True)`.
+
+The file-IO wrapper (also in `reconcile.py`) does the hash/bytes compare, backup, dump, and
+baseline update, and returns a summary for logging and the reload endpoint.
+
+### Config toggle (operator stays in control)
+
+Add `catalog_auto_merge: bool = True` to `Settings` in `backend/labelforge/config.py`
+(env `CATALOG_AUTO_MERGE`). When `False`, skip the write entirely but still **detect and
+log** that an updated default is available (and update nothing). Default on; the backup +
+operator-wins rules make on-by-default safe.
+
+### Secondary (build only if the core above is clean): reload without restart
+
+Add `POST /api/admin/reload-catalog` (auth-gated, mirror the `Depends(require_auth)` pattern
+in `routes/settings.py`; a new `routes/admin.py` is fine — register it in `main.py`). It
+re-runs the reconcile + `load_catalog(yml_path)` and returns a JSON summary (counts of
+added/updated entries, whether a write happened). Remove the now-satisfied "A future POST
+/api/admin/reload-catalog" comment in `loader.py`. If this turns out non-trivial, leave the
+comment and note it as deferred in the ADR — do not let it block the core feature.
+
+## Tests (required — merge correctness is the whole point)
+
+Create `backend/tests/test_reconcile.py` (mirror wherever existing pytest tests live; if
+there's no `backend/tests/` yet, create it). Cover at minimum:
+
+- default unchanged → no-op, operator file byte-identical.
+- new entry in default → added to operator output.
+- operator-customized field (op != baseline) → preserved even when default changed it.
+- uncustomized field (op == baseline) with changed default → updated to new value
+  (this is the `brother_part` SKU-correction case — assert it explicitly).
+- operator-only custom entry → preserved.
+- default removed an entry → still preserved in operator output (no deletion).
+- no-baseline transition → add-new-only, existing entries untouched, baseline then written.
+
+## Conventions to honor
+
+- LF endings only. Comments only for non-obvious *why*. Keep `merge_catalog` pure so the
+  tests don't touch the filesystem.
+- Changelog: add an entry under `## [Unreleased]` → `### Fixed` (it fixes #16), user-facing:
+  upgrades now deliver new/corrected default catalog entries without overwriting operator
+  customizations; a `labels.yml.bak` backup is written before any change; opt out with
+  `CATALOG_AUTO_MERGE=false`. Mention the container rebuild requirement.
+- Update `docs/features/label-catalog.md` with a short "Upgrade reconciliation" section
+  describing the 3-way merge, the `$DATA_DIR/data/labels.default.yml` baseline, the `.bak`
+  backup, operator-wins semantics, and the no-deletion rule.
+
+## When done
+
+1. Verify: `ruff check . && ruff format --check . && mypy backend && pytest -q` all green
+   (the new tests included). Give the one-line "run this to verify".
+2. Update this file's frontmatter (`status`, `completed` = 2026-06-05, `result`).
+3. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+4. Add an ADR to `docs/decisions.md`: the 3-way-merge-with-baseline approach, why
+   operator-wins + never-delete, the PyYAML comment-loss tradeoff (and ruamel deferred), and
+   the "bundled default, not internet" distinction vs the no-auto-update rule.
+5. Propose ONE commit covering `main.py`, the new `reconcile.py` + tests, the config field,
+   the optional route, the changelog, the doc, the ADR, and this prompt move. Present the
+   file list and a one-line message; ask
+   `commit these as "fix: reconcile default labels.yml into operator copy on upgrade (#16)"? (y/n)`.
+   On `y`, stage those specific paths (never `git add -A`) and commit on `dev`. Never push.
+   Leave the issue open for the owner to close after verifying on a real upgrade.

From ab56cd68e27374237813088058acbff5a191684e Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 17:21:04 -0700
Subject: [PATCH 68/84] fix: reconcile default labels.yml into operator copy on
 upgrade (#16)

---
 CHANGELOG.md                                  |  16 ++
 backend/labelforge/catalog/loader.py          |   4 +-
 backend/labelforge/catalog/reconcile.py       | 189 ++++++++++++++
 backend/labelforge/config.py                  |   1 +
 backend/labelforge/main.py                    |  23 +-
 backend/labelforge/routes/admin.py            |  43 +++
 backend/tests/__init__.py                     |   0
 backend/tests/test_reconcile.py               | 244 ++++++++++++++++++
 docs/decisions.md                             |  43 +++
 docs/features/label-catalog.md                |  60 ++++-
 ...2026-06-05-catalog-reconcile-on-upgrade.md |  10 +-
 11 files changed, 616 insertions(+), 17 deletions(-)
 create mode 100644 backend/labelforge/catalog/reconcile.py
 create mode 100644 backend/labelforge/routes/admin.py
 create mode 100644 backend/tests/__init__.py
 create mode 100644 backend/tests/test_reconcile.py
 rename prompts/{ => done}/2026-06-05-catalog-reconcile-on-upgrade.md (97%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf14383..2dabac1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,22 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Fixed
+
+- **Upgrade now delivers new and corrected default catalog entries** (#16) — upgrading the
+  container image no longer leaves the operator's `labels.yml` stale. On startup, labelforge
+  performs a non-destructive 3-way merge: new entries from the bundled default are added,
+  corrected field values (e.g. `brother_part` SKU fixes) are applied to fields the operator
+  never customized, and any operator customizations or custom media entries are preserved and
+  never deleted. A backup is written to `$DATA_DIR/labels.yml.bak` before any change. Opt out
+  with `CATALOG_AUTO_MERGE=false`. Requires a container image rebuild.
+
+### Added
+
+- **`POST /api/admin/reload-catalog`** — re-runs catalog reconciliation and reloads the catalog
+  from disk without restarting the container. Returns a JSON summary of entries added/updated
+  and whether the operator file was rewritten. Requires API token.
+
 ### Changed
 
 - **CI: compose validation now targets `docker-compose.yml` / `docker-compose.dev.yml`** — the compose job previously looked for `compose.yml` / `compose.dev.yml` (wrong filenames) and used a `bash -e` one-liner that treated a missing file as a failure. The loop is now hardened to skip absent files and only fail on a bad `docker compose config`. The `CLAUDE.md` convention note is corrected to match the actual filenames. Backend linting (ruff) is also clean: import order fixed in `routes/print.py`, `datetime.UTC` modernisation in `templates/store.py`, and long-line wraps across several `backend/` files.
diff --git a/backend/labelforge/catalog/loader.py b/backend/labelforge/catalog/loader.py
index 0f53ebd..155b7f0 100644
--- a/backend/labelforge/catalog/loader.py
+++ b/backend/labelforge/catalog/loader.py
@@ -46,8 +46,8 @@ def load_catalog(yml_path: Path) -> None:
     lib_labels = {label.identifier: label for label in ALL_LABELS}
 
     # Compatibility is computed against the configured printer at load time
-    # (printer_model is fixed in config). A future POST /api/admin/reload-catalog
-    # should call this again to recompute.
+    # (printer_model is fixed in config). POST /api/admin/reload-catalog calls
+    # this again to recompute.
     printer_model = settings.printer_model
     model = next((m for m in ALL_MODELS if m.identifier == printer_model), None)
     if model is None:
diff --git a/backend/labelforge/catalog/reconcile.py b/backend/labelforge/catalog/reconcile.py
new file mode 100644
index 0000000..f23cc3d
--- /dev/null
+++ b/backend/labelforge/catalog/reconcile.py
@@ -0,0 +1,189 @@
+import logging
+import shutil
+from pathlib import Path
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+def merge_catalog(operator: dict, old_default: dict, new_default: dict) -> tuple[dict, list[str]]:
+    """3-way merge of labels.yml documents keyed by entry id.
+
+    Returns (merged_document, change_log_lines). Operator always wins on conflict.
+
+    Rules:
+    - New entry (id in new_default, not in operator): added verbatim.
+    - Existing entry: for each field in new_default, take the new value only when
+      the operator never customized it (op_val == old_val). Otherwise keep op_val.
+    - Operator-only entry: kept as-is regardless of what the default says.
+    """
+
+    def _entries(doc: dict) -> list[dict]:
+        return [e for e in (doc.get("labels") or []) if isinstance(e, dict) and "id" in e]
+
+    op_by_id = {e["id"]: e for e in _entries(operator)}
+    old_by_id = {e["id"]: e for e in _entries(old_default)}
+    new_by_id = {e["id"]: e for e in _entries(new_default)}
+
+    changes: list[str] = []
+    merged_labels: list[dict] = []
+
+    # Pass 1: operator's entries in their original order
+    for op_entry in _entries(operator):
+        entry_id = op_entry["id"]
+
+        if entry_id not in new_by_id:
+            # Operator-only or removed-from-default: keep as-is, never delete
+            merged_labels.append(dict(op_entry))
+            continue
+
+        merged = dict(op_entry)
+        old_entry = old_by_id.get(entry_id, {})
+        new_entry = new_by_id[entry_id]
+
+        for field, new_val in new_entry.items():
+            if field == "id":
+                continue
+            old_val = old_entry.get(field)
+            op_val = op_entry.get(field)
+            if op_val == old_val and new_val != op_val:
+                merged[field] = new_val
+                changes.append(f"updated {entry_id}.{field}")
+
+        merged_labels.append(merged)
+
+    # Pass 2: brand-new entries from new_default not present in operator
+    op_ids = set(op_by_id)
+    for new_entry in _entries(new_default):
+        if new_entry["id"] not in op_ids:
+            merged_labels.append(dict(new_entry))
+            changes.append(f"added {new_entry['id']}")
+
+    return {"labels": merged_labels}, changes
+
+
+def reconcile_catalog_files(
+    default_path: Path,
+    yml_path: Path,
+    baseline_path: Path,
+    auto_merge: bool = True,
+) -> dict:
+    """Reconcile the bundled default catalog into the operator's copy.
+
+    Called at startup and from the reload-catalog admin endpoint.
+    Returns a summary dict: {wrote, added, updated, backed_up, reason}.
+    Never raises — callers log and continue on failure.
+    """
+    summary: dict = {"wrote": False, "added": 0, "updated": 0, "backed_up": False, "reason": ""}
+
+    if not default_path.exists():
+        summary["reason"] = f"no default at {default_path}"
+        return summary
+
+    default_bytes = default_path.read_bytes()
+
+    # Case 1: First run — no operator file yet
+    if not yml_path.exists():
+        shutil.copy(default_path, yml_path)
+        baseline_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(default_path, baseline_path)
+        summary["reason"] = "first-run: copied default to operator file and baseline"
+        logger.info("First-run: copied %s → %s and %s", default_path, yml_path, baseline_path)
+        return summary
+
+    # Case 2: Operator file exists but no baseline (upgrading to this feature for the first time)
+    if not baseline_path.exists():
+        if auto_merge:
+            with yml_path.open() as fh:
+                op_doc = yaml.safe_load(fh) or {}
+            with default_path.open() as fh:
+                new_doc = yaml.safe_load(fh) or {}
+
+            op_ids = {
+                e["id"] for e in (op_doc.get("labels") or []) if isinstance(e, dict) and "id" in e
+            }
+            new_entries = [
+                e
+                for e in (new_doc.get("labels") or [])
+                if isinstance(e, dict) and "id" in e and e["id"] not in op_ids
+            ]
+
+            if new_entries:
+                bak = yml_path.parent / (yml_path.name + ".bak")
+                shutil.copy(yml_path, bak)
+                summary["backed_up"] = True
+                op_doc.setdefault("labels", []).extend(new_entries)
+                yml_path.write_text(yaml.safe_dump(op_doc, sort_keys=False, allow_unicode=True))
+                summary["added"] = len(new_entries)
+                summary["wrote"] = True
+                logger.info(
+                    "No-baseline transition: added %d new catalog entries. "
+                    "Field-level corrections apply on the next default change. Backup: %s",
+                    len(new_entries),
+                    bak,
+                )
+            else:
+                logger.info(
+                    "No-baseline transition: no new catalog entries to add. "
+                    "Field-level corrections will apply on the next default change."
+                )
+        else:
+            logger.info(
+                "CATALOG_AUTO_MERGE=false: no baseline present; "
+                "updated default is available but not applied"
+            )
+
+        baseline_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(default_path, baseline_path)
+        summary["reason"] = (
+            f"no-baseline transition: {summary['added']} entries added, baseline written"
+        )
+        return summary
+
+    # Case 3: Baseline exists — check whether the default has changed
+    baseline_bytes = baseline_path.read_bytes()
+    if default_bytes == baseline_bytes:
+        summary["reason"] = "default unchanged, no-op"
+        return summary
+
+    if not auto_merge:
+        logger.info("CATALOG_AUTO_MERGE=false: updated default catalog detected but not applied")
+        summary["reason"] = "auto_merge disabled, update detected but not applied"
+        return summary
+
+    # Default changed — run full 3-way merge
+    with yml_path.open() as fh:
+        op_doc = yaml.safe_load(fh) or {}
+    with baseline_path.open() as fh:
+        old_doc = yaml.safe_load(fh) or {}
+    with default_path.open() as fh:
+        new_doc = yaml.safe_load(fh) or {}
+
+    merged_doc, changes = merge_catalog(op_doc, old_doc, new_doc)
+
+    added = sum(1 for c in changes if c.startswith("added "))
+    updated_fields = sum(1 for c in changes if c.startswith("updated "))
+
+    bak = yml_path.parent / (yml_path.name + ".bak")
+    shutil.copy(yml_path, bak)
+    summary["backed_up"] = True
+    logger.info("Backed up operator labels.yml → %s", bak)
+
+    yml_path.write_text(yaml.safe_dump(merged_doc, sort_keys=False, allow_unicode=True))
+    shutil.copy(default_path, baseline_path)
+
+    summary["wrote"] = True
+    summary["added"] = added
+    summary["updated"] = updated_fields
+    summary["reason"] = f"merged: {added} entries added, {updated_fields} fields updated"
+
+    for line in changes:
+        logger.info("Catalog reconcile: %s", line)
+    logger.info(
+        "Catalog reconcile complete: %d entries added, %d fields updated",
+        added,
+        updated_fields,
+    )
+
+    return summary
diff --git a/backend/labelforge/config.py b/backend/labelforge/config.py
index 3ae07a4..6034bd4 100644
--- a/backend/labelforge/config.py
+++ b/backend/labelforge/config.py
@@ -17,6 +17,7 @@ class Settings(BaseSettings):
     data_dir: Path = Path("/data")
     default_label_media: str = "62"
     log_level: str = "INFO"
+    catalog_auto_merge: bool = True
 
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
 
diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 01f43c2..4c635d5 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -1,6 +1,5 @@
 import asyncio
 import logging
-import shutil
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -10,9 +9,11 @@
 
 from labelforge import history as history_module
 from labelforge.catalog.loader import load_catalog
+from labelforge.catalog.reconcile import reconcile_catalog_files
 from labelforge.config import settings
 from labelforge.db import init_db
 from labelforge.render.fonts import load_fonts
+from labelforge.routes import admin as admin_router
 from labelforge.routes import fonts, health, labels
 from labelforge.routes import history as history_router
 from labelforge.routes import preview as preview_router
@@ -37,13 +38,18 @@ async def lifespan(app: FastAPI):  # noqa: ARG001
     logger.info("Data directory: %s", data_dir)
 
     yml_path = data_dir / "labels.yml"
-    if not yml_path.exists():
-        default_yml = Path("/app/labels.yml")
-        if default_yml.exists():
-            shutil.copy(default_yml, yml_path)
-            logger.info("Copied default labels.yml to %s", yml_path)
-        else:
-            logger.warning("labels.yml missing at %s and no default at /app/labels.yml", yml_path)
+    baseline_path = data_dir / "data" / "labels.default.yml"
+    default_yml = Path("/app/labels.yml")
+    try:
+        summary = reconcile_catalog_files(
+            default_yml,
+            yml_path,
+            baseline_path,
+            auto_merge=settings.catalog_auto_merge,
+        )
+        logger.info("Catalog reconcile: %s", summary["reason"])
+    except Exception:
+        logger.error("Catalog reconcile failed — loading existing file as-is", exc_info=True)
 
     db_path = data_dir / "data" / "app.db"
     init_db(db_path)
@@ -83,6 +89,7 @@ async def _retention_loop() -> None:
     lifespan=lifespan,
 )
 
+app.include_router(admin_router.router, prefix="/api")
 app.include_router(health.router, prefix="/api")
 app.include_router(labels.router, prefix="/api")
 app.include_router(fonts.router, prefix="/api")
diff --git a/backend/labelforge/routes/admin.py b/backend/labelforge/routes/admin.py
new file mode 100644
index 0000000..b72cdfe
--- /dev/null
+++ b/backend/labelforge/routes/admin.py
@@ -0,0 +1,43 @@
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Depends
+
+from labelforge.catalog.loader import load_catalog
+from labelforge.catalog.reconcile import reconcile_catalog_files
+from labelforge.config import settings
+from labelforge.routes.auth import require_auth
+
+router = APIRouter(dependencies=[Depends(require_auth)])
+
+_DEFAULT_PATH = Path("/app/labels.yml")
+
+
+@router.post("/admin/reload-catalog")
+async def reload_catalog() -> dict[str, Any]:
+    """Re-run catalog reconciliation and reload from disk.
+
+    Returns a summary of what changed (entries added/updated, whether the
+    operator file was rewritten) plus the resulting catalog size.
+    """
+    yml_path = settings.data_dir / "labels.yml"
+    baseline_path = settings.data_dir / "data" / "labels.default.yml"
+
+    summary = reconcile_catalog_files(
+        _DEFAULT_PATH,
+        yml_path,
+        baseline_path,
+        auto_merge=settings.catalog_auto_merge,
+    )
+    load_catalog(yml_path)
+
+    from labelforge.catalog.loader import get_catalog
+
+    return {
+        "wrote": summary["wrote"],
+        "added": summary["added"],
+        "updated": summary["updated"],
+        "backed_up": summary["backed_up"],
+        "reason": summary["reason"],
+        "catalog_size": len(get_catalog()),
+    }
diff --git a/backend/tests/__init__.py b/backend/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/tests/test_reconcile.py b/backend/tests/test_reconcile.py
new file mode 100644
index 0000000..ca95c8f
--- /dev/null
+++ b/backend/tests/test_reconcile.py
@@ -0,0 +1,244 @@
+"""Tests for the catalog 3-way merge logic.
+
+merge_catalog is pure (no file IO), so these tests run without any filesystem setup.
+reconcile_catalog_files tests use tmp_path.
+"""
+
+import shutil
+
+import yaml
+from labelforge.catalog.reconcile import merge_catalog, reconcile_catalog_files
+
+
+def _doc(*entries):
+    return {"labels": list(entries)}
+
+
+def _e(id, **kwargs):
+    return {"id": id, **kwargs}
+
+
+# ── merge_catalog (pure function) ────────────────────────────────────────────
+
+
+def test_default_unchanged_no_op():
+    entry = _e("62", display_name="62mm", brother_part="DK-2205")
+    doc = _doc(entry)
+    result, changes = merge_catalog(doc, doc, doc)
+    assert result["labels"] == [dict(entry)]
+    assert changes == []
+
+
+def test_new_default_entry_added():
+    existing = _e("62", display_name="62mm")
+    new_entry = _e("29", display_name="29mm")
+    op = _doc(existing)
+    old_default = _doc(existing)
+    new_default = _doc(existing, new_entry)
+
+    result, changes = merge_catalog(op, old_default, new_default)
+    ids = [e["id"] for e in result["labels"]]
+    assert "62" in ids
+    assert "29" in ids
+    assert "added 29" in changes
+
+
+def test_operator_customized_field_preserved():
+    """op != baseline → operator wins even when default changed it."""
+    old = _e("62", brother_part="DK-OLD", display_name="62mm")
+    op_entry = _e("62", brother_part="DK-OP", display_name="62mm")  # customized
+    new = _e("62", brother_part="DK-NEW", display_name="62mm")
+
+    result, changes = merge_catalog(_doc(op_entry), _doc(old), _doc(new))
+    found = next(e for e in result["labels"] if e["id"] == "62")
+    assert found["brother_part"] == "DK-OP"
+    assert not any("brother_part" in c for c in changes)
+
+
+def test_uncustomized_field_updated_from_default():
+    """SKU correction: op == baseline, so the corrected default value is taken."""
+    old = _e("62x29", brother_part="DK-WRONG", display_name="62x29mm")
+    op_entry = _e("62x29", brother_part="DK-WRONG", display_name="62x29mm")  # unchanged
+    new = _e("62x29", brother_part="DK-1209", display_name="62x29mm")
+
+    result, changes = merge_catalog(_doc(op_entry), _doc(old), _doc(new))
+    found = next(e for e in result["labels"] if e["id"] == "62x29")
+    assert found["brother_part"] == "DK-1209"
+    assert "updated 62x29.brother_part" in changes
+
+
+def test_operator_only_custom_entry_preserved():
+    default_entry = _e("62", display_name="62mm")
+    custom = _e("custom-roll", display_name="My Roll")
+    op = _doc(default_entry, custom)
+    default = _doc(default_entry)
+
+    result, changes = merge_catalog(op, default, default)
+    ids = [e["id"] for e in result["labels"]]
+    assert "custom-roll" in ids
+    assert "62" in ids
+
+
+def test_default_removed_entry_preserved():
+    """An entry the default dropped must never be deleted from operator's file."""
+    entry_62 = _e("62", display_name="62mm")
+    entry_29 = _e("29", display_name="29mm")
+    op = _doc(entry_62, entry_29)
+    old_default = _doc(entry_62, entry_29)
+    new_default = _doc(entry_62)  # 29 dropped from default
+
+    result, changes = merge_catalog(op, old_default, new_default)
+    ids = [e["id"] for e in result["labels"]]
+    assert "29" in ids
+    assert "62" in ids
+
+
+def test_new_entries_appended_after_operator_entries():
+    """Brand-new default entries appear after the operator's existing entries."""
+    op_entry = _e("62", display_name="62mm")
+    new_entry = _e("29", display_name="29mm")
+    op = _doc(op_entry)
+    old_default = _doc(op_entry)
+    new_default = _doc(op_entry, new_entry)
+
+    result, _ = merge_catalog(op, old_default, new_default)
+    ids = [e["id"] for e in result["labels"]]
+    assert ids.index("62") < ids.index("29")
+
+
+def test_operator_extra_fields_kept():
+    """Fields the operator added that aren't in the default are preserved."""
+    old = _e("62", display_name="62mm")
+    op_entry = _e("62", display_name="62mm", custom_note="rack shelf 3")
+    new = _e("62", display_name="62mm")
+
+    result, changes = merge_catalog(_doc(op_entry), _doc(old), _doc(new))
+    found = next(e for e in result["labels"] if e["id"] == "62")
+    assert found.get("custom_note") == "rack shelf 3"
+    assert changes == []
+
+
+# ── reconcile_catalog_files (file IO) ────────────────────────────────────────
+
+
+def _write_yaml(path, data):
+    path.write_text(yaml.safe_dump(data, sort_keys=False, allow_unicode=True))
+
+
+def test_no_baseline_transition(tmp_path):
+    """Upgrade from pre-reconcile: adds new entries only, existing untouched, baseline written."""
+    default_path = tmp_path / "default.yml"
+    yml_path = tmp_path / "labels.yml"
+    baseline_path = tmp_path / "data" / "labels.default.yml"
+
+    _write_yaml(
+        default_path,
+        _doc(
+            _e("62", display_name="62mm", brother_part="DK-2205"),
+            _e("29", display_name="29mm", brother_part="DK-2210"),
+        ),
+    )
+    _write_yaml(
+        yml_path,
+        _doc(
+            _e("62", display_name="My Custom 62mm", brother_part="DK-2205"),
+        ),
+    )
+
+    summary = reconcile_catalog_files(default_path, yml_path, baseline_path)
+
+    assert summary["added"] == 1
+    assert summary["wrote"] is True
+    assert baseline_path.exists()
+    assert baseline_path.read_bytes() == default_path.read_bytes()
+
+    result = yaml.safe_load(yml_path.read_text())
+    entry_62 = next(e for e in result["labels"] if e["id"] == "62")
+    assert entry_62["display_name"] == "My Custom 62mm"  # operator value preserved
+    ids = [e["id"] for e in result["labels"]]
+    assert "29" in ids
+
+
+def test_no_baseline_no_new_entries(tmp_path):
+    """No-baseline transition with no new entries: no write, baseline still created."""
+    default_path = tmp_path / "default.yml"
+    yml_path = tmp_path / "labels.yml"
+    baseline_path = tmp_path / "data" / "labels.default.yml"
+
+    doc = _doc(_e("62", display_name="62mm"))
+    _write_yaml(default_path, doc)
+    _write_yaml(yml_path, doc)
+
+    original_bytes = yml_path.read_bytes()
+    summary = reconcile_catalog_files(default_path, yml_path, baseline_path)
+
+    assert summary["wrote"] is False
+    assert yml_path.read_bytes() == original_bytes
+    assert baseline_path.exists()
+
+
+def test_first_run_copies_default(tmp_path):
+    """No operator file: default is copied to both yml_path and baseline_path."""
+    default_path = tmp_path / "default.yml"
+    yml_path = tmp_path / "labels.yml"
+    baseline_path = tmp_path / "data" / "labels.default.yml"
+
+    _write_yaml(default_path, _doc(_e("62", display_name="62mm")))
+    reconcile_catalog_files(default_path, yml_path, baseline_path)
+
+    assert yml_path.exists()
+    assert baseline_path.exists()
+    assert yml_path.read_bytes() == default_path.read_bytes()
+    assert baseline_path.read_bytes() == default_path.read_bytes()
+
+
+def test_baseline_unchanged_noop(tmp_path):
+    """Default bytes == baseline bytes: no write."""
+    default_path = tmp_path / "default.yml"
+    yml_path = tmp_path / "labels.yml"
+    baseline_path = tmp_path / "data" / "labels.default.yml"
+    baseline_path.parent.mkdir(parents=True)
+
+    doc = _doc(_e("62", display_name="62mm"))
+    _write_yaml(default_path, doc)
+    _write_yaml(yml_path, doc)
+    shutil.copy(default_path, baseline_path)
+
+    original_bytes = yml_path.read_bytes()
+    summary = reconcile_catalog_files(default_path, yml_path, baseline_path)
+
+    assert summary["wrote"] is False
+    assert yml_path.read_bytes() == original_bytes
+
+
+def test_full_merge_on_changed_default(tmp_path):
+    """Baseline differs from default: 3-way merge runs, backup written, baseline updated."""
+    default_path = tmp_path / "default.yml"
+    yml_path = tmp_path / "labels.yml"
+    baseline_path = tmp_path / "data" / "labels.default.yml"
+    baseline_path.parent.mkdir(parents=True)
+
+    old_doc = _doc(_e("62", brother_part="DK-OLD", display_name="62mm"))
+    op_doc = _doc(_e("62", brother_part="DK-OLD", display_name="62mm"))  # not customized
+    new_doc = _doc(
+        _e("62", brother_part="DK-2205", display_name="62mm"),
+        _e("29", display_name="29mm"),
+    )
+
+    _write_yaml(yml_path, op_doc)
+    _write_yaml(baseline_path, old_doc)
+    _write_yaml(default_path, new_doc)
+
+    summary = reconcile_catalog_files(default_path, yml_path, baseline_path)
+
+    assert summary["wrote"] is True
+    assert summary["backed_up"] is True
+    assert summary["added"] == 1
+    assert summary["updated"] >= 1
+
+    result = yaml.safe_load(yml_path.read_text())
+    entry_62 = next(e for e in result["labels"] if e["id"] == "62")
+    assert entry_62["brother_part"] == "DK-2205"  # corrected
+    assert any(e["id"] == "29" for e in result["labels"])  # new entry added
+    assert baseline_path.read_bytes() == default_path.read_bytes()
+    assert (yml_path.parent / (yml_path.name + ".bak")).exists()
diff --git a/docs/decisions.md b/docs/decisions.md
index e4fdfd6..d132318 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,49 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-05 — Catalog reconciliation: 3-way merge with baseline, operator-wins, never-delete
+
+**Decision**: On startup, labelforge performs a non-destructive 3-way merge of the bundled
+`/app/labels.yml` into the operator's `$DATA_DIR/labels.yml`. A baseline copy
+(`$DATA_DIR/data/labels.default.yml`) records the default as of the last sync. Merge logic:
+if a field's operator value equals the baseline value (never customized), a changed default
+value is applied; if the operator changed it, the operator wins. Entries the operator added or
+that a later default removed are never deleted. A rolling backup (`$DATA_DIR/labels.yml.bak`)
+is written before any write. The feature is opt-out via `CATALOG_AUTO_MERGE=false`. Closes #16.
+
+**Source of truth for reconciliation is the bundled image default, NOT the internet.** This is
+intentionally distinct from "don't auto-update the catalog from the internet" (`CLAUDE.md`):
+reconcile reads only the default shipped inside the image; no network access occurs.
+
+**PyYAML is used for the round-trip** (not `ruamel.yaml`). PyYAML drops YAML comments and
+non-standard formatting from the operator file on write. Mitigation: the backup preserves the
+original. This is an accepted trade-off; the operator file is user-editable but not expected to
+carry extensive comments.
+
+**Why operator-wins + never-delete**: The operator may have customized `brother_part`, tweaked
+`display_name`, or added custom media entries that have no default counterpart. Silently
+overwriting these would break their setup. "Never delete" covers the case where an operator
+has a physical roll for an entry a future default drops — their printer still works.
+
+**Why the baseline (3-source model, not 2)**: Without a baseline, distinguishing "operator
+customized this field" from "operator left it at the old default value" is impossible when the
+default changes. The baseline is the missing anchor that makes intent deterministic.
+
+**Considered**:
+- `ruamel.yaml` for comment-preserving round-trips — deferred. `ruamel.yaml` is not in the
+  locked stack (PyYAML is); adding it would need its own ADR. The backup mitigates the loss.
+- Simple overwrite on upgrade — rejected; clobbers operator customizations, the root cause of #16.
+- Operator-file-wins on every field, no merge — rejected; defeats the purpose (SKU corrections
+  and new entries would never arrive).
+- Delete entries removed from the default — rejected; custom media the operator added would
+  silently vanish.
+
+**Would revisit if**: comment-preserving round-trips become a strong operator ask (add
+`ruamel.yaml` with an ADR); or the locked stack adds a structured YAML library with better
+semantics.
+
+---
+
 ## 2026-06-04 — Template recall pre-fill uses print history; retention preserves latest job per template
 
 **Decision**: The "Load previous values" button on the recall form reads `field_values` from the newest `print_jobs` row for that template. No new table or column was needed — `field_values` was already stored at print time. `GET /api/templates/{name}/last-values` returns `{values, printed_at}`.
diff --git a/docs/features/label-catalog.md b/docs/features/label-catalog.md
index 66f1fc9..3dbaeeb 100644
--- a/docs/features/label-catalog.md
+++ b/docs/features/label-catalog.md
@@ -122,14 +122,68 @@ On the default `QL-820NWB`: the six wide rolls (`102`, `103`, `104`, `102x51`, `
 
 At startup:
 
-1. Load `labels.yml` from `/var/docker/labelforge/labels.yml`
-2. If missing, copy the default shipped at `/app/labels.yml` (image asset) to the volume on first run
+1. Reconcile `$DATA_DIR/labels.yml` from the bundled default (see "Upgrade reconciliation" below)
+2. Load `$DATA_DIR/labels.yml`
 3. Validate against schema (Pydantic model); log warnings for malformed entries, skip them
 4. Call `brother_ql.labels` for the printable set
 5. Build merged catalog in memory; cache for the process lifetime
 6. Log: catalog size, count of yml-only (hidden) entries, count of library-only (fallback) entries
 
-Reload on `SIGHUP` or via an admin endpoint (`POST /api/admin/reload-catalog`). No file watcher in v1 — restart or reload is fine.
+Reload via `POST /api/admin/reload-catalog` (auth-gated). No file watcher — restart or reload is fine.
+
+## Upgrade reconciliation
+
+Each image ships a default catalog at `/app/labels.yml`. On startup labelforge performs a
+non-destructive **3-way merge** to deliver new and corrected entries from the bundled default
+without overwriting operator customizations.
+
+### State files
+
+| Path | Purpose |
+|---|---|
+| `/app/labels.yml` | Bundled default — read-only truth for what this release ships |
+| `$DATA_DIR/labels.yml` | Operator's live file (what the app reads) |
+| `$DATA_DIR/data/labels.default.yml` | Baseline — a copy of the default as of the last sync |
+
+### Startup flows
+
+- **First run** (`$DATA_DIR/labels.yml` absent): default is copied to both the operator file and
+  the baseline. No merge needed.
+- **No baseline** (existing install upgrading to this feature for the first time): brand-new
+  entries (ids in default but not in operator file) are appended; existing entries are never
+  touched. Baseline is written. Field-level corrections apply on the next default change.
+- **Baseline present, default unchanged** (bytes equal): no-op.
+- **Baseline present, default changed**: full 3-way merge runs (see below).
+
+A backup is written to `$DATA_DIR/labels.yml.bak` before any write (single rolling copy).
+
+### 3-way merge rules
+
+Entries are keyed by `id`. For each entry:
+
+- **New entry** (id in default, not in operator): added verbatim at the end.
+- **Existing entry** (id in both): for each field in the new default —
+  - If `operator_value == baseline_value` (never customized) **and** the default changed it:
+    take the new value from the default (e.g. a corrected `brother_part` SKU).
+  - If `operator_value != baseline_value` (operator customized it): **keep the operator's value.**
+  - Fields the operator added that aren't in the default: kept untouched.
+- **Operator-only entry** (id not in default): kept as-is. Custom media the operator added is
+  **never deleted**, even if a later default release removed the entry.
+
+Ordering: operator's existing entries in their original order, new default entries appended after.
+
+### Operator controls
+
+- `CATALOG_AUTO_MERGE=false` — disable writes entirely. Startup still detects and logs when an
+  updated default is available, but the operator file is never touched.
+
+### Notes
+
+- PyYAML is used for the round-trip. YAML comments and non-standard formatting in the operator
+  file are lost when a write occurs (the backup preserves the original). `ruamel.yaml`
+  (comment-preserving) was deferred; see ADR 2026-06-05.
+- The source for reconciliation is always the bundled image default, **never the internet**.
+  This does not violate the "no auto-update from the internet" rule.
 
 ## API
 
diff --git a/prompts/2026-06-05-catalog-reconcile-on-upgrade.md b/prompts/done/2026-06-05-catalog-reconcile-on-upgrade.md
similarity index 97%
rename from prompts/2026-06-05-catalog-reconcile-on-upgrade.md
rename to prompts/done/2026-06-05-catalog-reconcile-on-upgrade.md
index e6816ec..86424cc 100644
--- a/prompts/2026-06-05-catalog-reconcile-on-upgrade.md
+++ b/prompts/done/2026-06-05-catalog-reconcile-on-upgrade.md
@@ -1,10 +1,12 @@
 ---
 name: 2026-06-05-catalog-reconcile-on-upgrade
-status: pending          # pending | completed | failed
+status: completed
 created: 2026-06-05
-model: sonnet            # opus = research/planning, sonnet = coding
-completed:               # filled when the work is done
-result:                  # one-line summary of the outcome
+model: sonnet
+completed: 2026-06-05
+result: >-
+  3-way merge at startup (reconcile.py + 13 tests), CATALOG_AUTO_MERGE config toggle,
+  POST /api/admin/reload-catalog route, ADR + changelog + doc update; closes #16
 ---
 
 # Task: Reconcile the shipped `labels.yml` into the operator's copy on upgrade (issue #16)

From 61c62f29b0e74e3617130dd24336bd330b7c27f3 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 17:28:33 -0700
Subject: [PATCH 69/84] chore: target Dependabot at dev and relax cadence to
 monthly

---
 .github/dependabot.yml | 16 ++++++++--------
 CHANGELOG.md           |  2 ++
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 5b31257..0849edf 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -2,9 +2,9 @@ version: 2
 updates:
   - package-ecosystem: github-actions
     directory: /
+    target-branch: dev
     schedule:
-      interval: weekly
-      day: monday
+      interval: monthly
       time: '06:00'
       timezone: Etc/UTC
     open-pull-requests-limit: 5
@@ -20,9 +20,9 @@ updates:
 
   - package-ecosystem: pip
     directory: /
+    target-branch: dev
     schedule:
-      interval: weekly
-      day: monday
+      interval: monthly
       time: '06:00'
       timezone: Etc/UTC
     open-pull-requests-limit: 5
@@ -39,9 +39,9 @@ updates:
 
   - package-ecosystem: npm
     directory: /frontend
+    target-branch: dev
     schedule:
-      interval: weekly
-      day: monday
+      interval: monthly
       time: '06:00'
       timezone: Etc/UTC
     open-pull-requests-limit: 5
@@ -58,9 +58,9 @@ updates:
 
   - package-ecosystem: docker
     directory: /
+    target-branch: dev
     schedule:
-      interval: weekly
-      day: monday
+      interval: monthly
       time: '06:00'
       timezone: Etc/UTC
     open-pull-requests-limit: 5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2dabac1..a92c1b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,8 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 - **CI: compose validation now targets `docker-compose.yml` / `docker-compose.dev.yml`** — the compose job previously looked for `compose.yml` / `compose.dev.yml` (wrong filenames) and used a `bash -e` one-liner that treated a missing file as a failure. The loop is now hardened to skip absent files and only fail on a bad `docker compose config`. The `CLAUDE.md` convention note is corrected to match the actual filenames. Backend linting (ruff) is also clean: import order fixed in `routes/print.py`, `datetime.UTC` modernisation in `templates/store.py`, and long-line wraps across several `backend/` files.
 
+- **Dependabot now targets `dev`, never `main`, and runs monthly** — all four ecosystems (github-actions, pip, npm, docker) in `.github/dependabot.yml` now set `target-branch: dev`, so dependency-bump PRs open against the working branch and only reach `main` through a managed release PR. Previously they defaulted to `main`, cluttering the release queue with PRs that could never be allowed to auto-merge. The version-update cadence is also relaxed from weekly to monthly to suit a low-maintenance released project (security updates, when enabled, are advisory-driven and unaffected by this schedule). Process-only — no runtime change.
+
 ### Added
 
 - **Load previous values on template recall** — the recall form now has a **Load previous values** button (only for templates with variable fields). Clicking it fills the form with the field values from the last time this template was printed, so you can make quick adjustments without re-typing. The button is disabled when the template has no print history. The most recent print job for each template is now also protected from retention pruning, so these values survive cleanup. Requires a container image rebuild.

From 1a6e673ae63504d579343873e2a62f99f69778ce Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 17:59:19 -0700
Subject: [PATCH 70/84] chore: enable mypy in CI and fix backend type errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add mypy (>=1.11) and types-PyYAML to the dev extra; configure
[tool.mypy] with the pydantic plugin and per-module ignore_missing_imports
overrides for unstubbed third-party libs (brother_ql, qrcode, barcode).

Fix the 11 backend type errors surfaced by enabling the check:
- render/template.py: Image.BICUBIC/NEAREST → Image.Resampling.* (Pillow 9.1+ deprecation)
- printer/client.py: hoist width_mm/length_mm declarations to avoid no-redef; guard both in _media_id_from_dims call
- history.py: assert cursor.lastrowid is not None after INSERT
- render/text.py: int() cast on textbbox pixel delta
- routes/printer.py: widen return annotation to dict | JSONResponse
---
 CHANGELOG.md                              |   4 +-
 backend/labelforge/history.py             |   1 +
 backend/labelforge/printer/client.py      |  12 ++-
 backend/labelforge/render/template.py     |   8 +-
 backend/labelforge/render/text.py         |   2 +-
 backend/labelforge/routes/printer.py      |   2 +-
 prompts/done/2026-06-05-enable-mypy-ci.md | 108 ++++++++++++++++++++++
 pyproject.toml                            |  10 ++
 8 files changed, 137 insertions(+), 10 deletions(-)
 create mode 100644 prompts/done/2026-06-05-enable-mypy-ci.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a92c1b5..a6b9897 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,7 +22,9 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Changed
 
-- **CI: compose validation now targets `docker-compose.yml` / `docker-compose.dev.yml`** — the compose job previously looked for `compose.yml` / `compose.dev.yml` (wrong filenames) and used a `bash -e` one-liner that treated a missing file as a failure. The loop is now hardened to skip absent files and only fail on a bad `docker compose config`. The `CLAUDE.md` convention note is corrected to match the actual filenames. Backend linting (ruff) is also clean: import order fixed in `routes/print.py`, `datetime.UTC` modernisation in `templates/store.py`, and long-line wraps across several `backend/` files.
+- **CI now type-checks the backend with mypy** — `mypy` (≥1.11) and `types-PyYAML` are added to the dev extra; a `[tool.mypy]` section in `pyproject.toml` enables the pydantic plugin and per-module stub overrides for unstubbed third-party libs (`brother_ql`, `qrcode`, `barcode`). Enabling type-checking surfaced a latent Pillow resampling deprecation (`Image.BICUBIC` / `Image.NEAREST` → `Image.Resampling.*`) and tightened several return types. Developer-facing only — no runtime behavior change.
+
+- **CI: compose validation now targets `docker-compose.yml` / `docker-compose.dev.yml`** — the compose job previously looked for `compose.yml` / `compose.dev.yml` (wrong filenames) and used a `bash -e` one-liner that treated a missing file as a failure. The loop is now hardened to skip absent files and only fail on a bad `docker compose config`. It also seeds a throwaway `.env` from the tracked `.env.example` first, since the compose files reference `env_file: .env` (which is gitignored) and `config` would otherwise fail to resolve it. The `CLAUDE.md` convention note is corrected to match the actual filenames. Backend linting (ruff) is also clean: import order fixed in `routes/print.py`, `datetime.UTC` modernisation in `templates/store.py`, and long-line wraps across several `backend/` files.
 
 - **Dependabot now targets `dev`, never `main`, and runs monthly** — all four ecosystems (github-actions, pip, npm, docker) in `.github/dependabot.yml` now set `target-branch: dev`, so dependency-bump PRs open against the working branch and only reach `main` through a managed release PR. Previously they defaulted to `main`, cluttering the release queue with PRs that could never be allowed to auto-merge. The version-update cadence is also relaxed from weekly to monthly to suit a low-maintenance released project (security updates, when enabled, are advisory-driven and unaffected by this schedule). Process-only — no runtime change.
 
diff --git a/backend/labelforge/history.py b/backend/labelforge/history.py
index 25f07a8..652ffe7 100644
--- a/backend/labelforge/history.py
+++ b/backend/labelforge/history.py
@@ -39,6 +39,7 @@ def insert_job_with_preview(
         )
         conn.commit()
         job_id = cursor.lastrowid
+        assert job_id is not None
     finally:
         conn.close()
 
diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
index 06cfaf5..f8947d0 100644
--- a/backend/labelforge/printer/client.py
+++ b/backend/labelforge/printer/client.py
@@ -154,6 +154,8 @@ def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
 
     timeout_s = timeout_ms / 1000
     raw: bytes = b""
+    width_mm: int | None = None
+    length_mm: int | None = None
 
     # Primary: raw TCP ESC i S (may return empty on some firmware — HTTP fallback handles it)
     try:
@@ -212,8 +214,8 @@ def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
         media_type_str = parser.pairs.get("Media Type", "")
         ready = "READY" in device_status.upper()
 
-        width_mm: int | None = None
-        length_mm: int | None = None
+        width_mm = None
+        length_mm = None
         if media_type_str:
             m = re.search(r"(\d+)mm\s*x\s*(\d+)mm", media_type_str, re.IGNORECASE)
             if m:
@@ -225,7 +227,11 @@ def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
                     width_mm = int(m2.group(1))
                     length_mm = 0
 
-        media_id = _media_id_from_dims(width_mm, length_mm, None) if width_mm is not None else None
+        media_id = (
+            _media_id_from_dims(width_mm, length_mm, None)
+            if width_mm is not None and length_mm is not None
+            else None
+        )
         return {
             "ready": ready,
             "model": None,
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index c837e8a..a920a93 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -103,7 +103,7 @@ def _paste_onto(
         # Preserve centre point across expand-rotation.
         cx = left + sub.width // 2
         cy = top + sub.height // 2
-        sub = sub.rotate(-angle, expand=True, resample=Image.BICUBIC, fillcolor=255)
+        sub = sub.rotate(-angle, expand=True, resample=Image.Resampling.BICUBIC, fillcolor=255)
         left = cx - sub.width // 2
         top = cy - sub.height // 2
     # Dark pixels (value≈0) → mask 255 (opaque); white (255) → mask 0 (skip).
@@ -170,12 +170,12 @@ def _render_qr_element(payload: str, correction: str, box_w: int, box_h: int) ->
         # Integer-multiple upscale: every module maps to exactly scale×scale pixels,
         # pure black/white — no grey edges that the print threshold could crush.
         scaled_w, scaled_h = nat_w * scale, nat_h * scale
-        scaled = nat.resize((scaled_w, scaled_h), Image.NEAREST)
+        scaled = nat.resize((scaled_w, scaled_h), Image.Resampling.NEAREST)
         result = Image.new("L", (box_w, box_h), 255)
         result.paste(scaled, ((box_w - scaled_w) // 2, (box_h - scaled_h) // 2))
         return result
     # Fallback: box smaller than natural QR; NEAREST keeps pixels pure B/W.
-    return nat.resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
+    return nat.resize((max(box_w, 1), max(box_h, 1)), Image.Resampling.NEAREST)
 
 
 # TODO: re-enable when QR/barcode 1-bit print bug is fixed
@@ -199,7 +199,7 @@ def _render_barcode_element(payload: str, symbology: str, box_w: int, box_h: int
     # Force pure black/white before scaling; NEAREST keeps bars as whole-pixel
     # columns with no anti-aliased grey that the print threshold could merge.
     bw = img.convert("L").point(lambda x: 0 if x < 128 else 255)
-    return bw.resize((max(box_w, 1), max(box_h, 1)), Image.NEAREST)
+    return bw.resize((max(box_w, 1), max(box_h, 1)), Image.Resampling.NEAREST)
 
 
 def render_template(template: Template, values: dict[str, str]) -> Image.Image:
diff --git a/backend/labelforge/render/text.py b/backend/labelforge/render/text.py
index 2e9d5cc..813dfd5 100644
--- a/backend/labelforge/render/text.py
+++ b/backend/labelforge/render/text.py
@@ -95,7 +95,7 @@ def render_text(
 
 def _measure_line_height(font: ImageFont.FreeTypeFont, draw: ImageDraw.ImageDraw) -> int:
     bbox = draw.textbbox((0, 0), "Ag|", font=font)
-    return (bbox[3] - bbox[1]) + 4  # +4px inter-line gap
+    return int(bbox[3] - bbox[1]) + 4  # +4px inter-line gap
 
 
 def _wrap_text(
diff --git a/backend/labelforge/routes/printer.py b/backend/labelforge/routes/printer.py
index 003803a..907eb70 100644
--- a/backend/labelforge/routes/printer.py
+++ b/backend/labelforge/routes/printer.py
@@ -14,7 +14,7 @@
 
 
 @router.get("/printer/status")
-async def get_printer_status() -> dict:
+async def get_printer_status() -> dict | JSONResponse:
     timeout_ms = settings_store.get("printer_status_timeout_ms")
 
     try:
diff --git a/prompts/done/2026-06-05-enable-mypy-ci.md b/prompts/done/2026-06-05-enable-mypy-ci.md
new file mode 100644
index 0000000..f019324
--- /dev/null
+++ b/prompts/done/2026-06-05-enable-mypy-ci.md
@@ -0,0 +1,108 @@
+---
+name: 2026-06-05-enable-mypy-ci
+status: completed
+created: 2026-06-05
+model: sonnet            # opus = research/planning, sonnet = coding
+completed: 2026-06-05
+result: mypy added to dev deps, [tool.mypy] config with pydantic plugin + per-module overrides, 11 type errors fixed (Pillow resampling, client.py no-redef, history.py assert, text.py int cast, printer.py return type)
+---
+
+# Task: Make the CI `mypy backend` step real and green
+
+CI runs `mypy backend` (`.github/workflows/ci.yml`, `python` job) but **mypy is not in the
+dev dependencies and there is no `[tool.mypy]` config**, so the step fails with
+`mypy: command not found` (exit 127) and the code has never actually been type-checked.
+Turning it on already paid off once: it caught a live `AttributeError` crash in
+`templates/store.py` (since fixed). This task installs mypy, configures it, and fixes the
+remaining type errors so the step passes.
+
+## Before you start
+
+- Read `docs/architecture.md`. Load the files listed under "Errors to fix" before editing.
+- ruff config and dev extras live in `pyproject.toml`. The dev extra currently has
+  `pytest`, `httpx`, `ruff` — **no mypy**.
+- Stack is locked: Pillow for rendering, `brother-ql-inventree`, FastAPI, pydantic-settings.
+- Work on `dev`. Conventional-Commits prefixes, no `Co-authored-by:`, docs ship with code.
+- **Fix root causes, don't just silence mypy.** Reach for `# type: ignore[code]` only where a
+  fix isn't appropriate (noted per-item below). Each ignore must be specific (carry the
+  error code) and have a one-line reason.
+
+## Working tree check
+
+Run `git status --porcelain` first. This touches `pyproject.toml` and ~7 files under
+`backend/labelforge/`. If any show uncommitted changes you didn't expect, list them and ask.
+
+## What to do
+
+### 1. Add mypy + config
+
+- Add `mypy` to `[project.optional-dependencies].dev` in `pyproject.toml`.
+- Add a `[tool.mypy]` section: `python_version = "3.12"`, `mypy_path = "backend"`,
+  `packages = ["labelforge"]` (or rely on the CI `mypy backend` invocation — keep it
+  consistent with how CI calls it). Enable the **pydantic plugin**:
+  `plugins = ["pydantic.mypy"]`.
+- The third-party libs have no type stubs (≈14 `import-untyped` errors: `brother_ql.*`,
+  `qrcode.*`, `barcode.*`, `yaml`, etc.). Handle them with **per-module overrides**, not a
+  blanket global ignore, e.g.:
+  ```toml
+  [[tool.mypy.overrides]]
+  module = ["brother_ql.*", "qrcode.*", "barcode.*", "PIL.*"]
+  ignore_missing_imports = true
+  ```
+  For `yaml`, prefer adding `types-PyYAML` to the dev extra (real stubs) over ignoring it.
+  Run mypy and add any remaining unstubbed modules to the override list rather than going
+  global. Goal: keep type-checking strict on **our** code.
+
+### 2. Fix the real errors (11)
+
+Run `mypy backend` after each cluster to confirm. Current findings:
+
+- **Pillow resampling — `render/template.py:106,173,178,202`** (`attr-defined`:
+  `Image.BICUBIC` / `Image.NEAREST`). These top-level constants were removed from the type
+  stubs (and are deprecated at runtime since Pillow 9.1). Replace with the modern enum:
+  `Image.Resampling.BICUBIC`, `Image.Resampling.NEAREST`. Runtime-equivalent and future-proofs
+  the pending Pillow 12 bump.
+- **`printer/client.py:215-216`** (`no-redef`: `width_mm`, `length_mm`). Not a logic bug —
+  the TCP branch (≈line 184) assigns these and returns early; the HTTP-fallback branch then
+  *re-annotates* them (`width_mm: int | None = None`), which mypy reads as a redefinition.
+  Drop the type annotation on the fallback assignments (plain `width_mm = None`), or hoist a
+  single annotated declaration above both branches. Don't change behavior.
+- **`history.py:45-46`** (`arg-type` / `return-value`: `int | None`). `job_id =
+  cursor.lastrowid` is typed `int | None`. After an INSERT it's reliably set, so guard it:
+  `job_id = cursor.lastrowid; assert job_id is not None` before `_save_preview(job_id, …)` and
+  `return job_id`. (Assert is fine here — a None lastrowid would be a genuine DB failure.)
+- **`render/text.py:98`** (`return-value`: got `float`, expected `int`). Inspect the
+  computation; if the function should return an int (pixel/dot count), wrap the result in
+  `int(...)` (or `round(...)` if that's the intent — check surrounding usage). If it can
+  legitimately be fractional, widen the annotation instead. Decide from context, note which.
+- **`routes/printer.py:27`** (`return-value`: `JSONResponse` vs `dict`). The handler returns
+  a `JSONResponse` (for a non-200 path) but is annotated `-> dict`. Widen the return
+  annotation to cover both (e.g. `dict[str, Any] | JSONResponse`, or the appropriate FastAPI
+  `Response` supertype). Don't strip the JSONResponse — it's intentional (status code).
+- **`config.py:33`** (`call-arg`: missing `printer_host` for `Settings`). `Settings()` is
+  populated from env by pydantic-settings; `printer_host` is required-from-env with no
+  literal default. The `pydantic.mypy` plugin may resolve this once enabled — check first.
+  If it doesn't, add a specific `# type: ignore[call-arg]` on that line with a one-line
+  reason (BaseSettings fields are populated from the environment at runtime). Do **not** give
+  `printer_host` a fake default to placate mypy.
+
+## Conventions to honor
+
+- LF endings. Keep `# type: ignore` rare, specific (with code), and justified.
+- Changelog: add a `### Changed` entry under `## [Unreleased]` — CI now type-checks the
+  backend with mypy (added to dev deps + `[tool.mypy]` config); notes that enabling it fixed
+  a latent Pillow-resampling deprecation and tightened several return types. Developer-facing,
+  no runtime behavior change (the `store.py` crash fix is already logged separately).
+
+## When done
+
+1. Verify all green: `ruff check . && ruff format --check . && mypy backend && pytest -q`.
+   Give the one-line "run this to verify".
+2. Update this file's frontmatter (`status`, `completed` = 2026-06-05, `result`).
+3. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+4. Record in `docs/decisions.md` only if a non-obvious call was made (e.g. per-module ignore
+   strategy, or any `type: ignore` rationale worth keeping).
+5. Propose ONE commit covering `pyproject.toml`, the backend fixes, the changelog, and this
+   prompt move. Present the file list and a one-line message; ask
+   `commit these as "chore: enable mypy in CI and fix backend type errors"? (y/n)`. On `y`,
+   stage those specific paths (never `git add -A`) and commit on `dev`. Never push.
diff --git a/pyproject.toml b/pyproject.toml
index 5ca22c9..c84c295 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -28,6 +28,8 @@ dev = [
     "pytest>=8.3",
     "httpx>=0.27",
     "ruff>=0.7",
+    "mypy>=1.11",
+    "types-PyYAML>=6.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -39,3 +41,11 @@ target-version = "py312"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.12"
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["brother_ql.*", "qrcode.*", "barcode.*"]
+ignore_missing_imports = true

From 215d57f5a63553d193fc61e9df137fa3a9cce45c Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 18:01:43 -0700
Subject: [PATCH 71/84] env fixe

---
 .github/workflows/ci.yml              | 3 +++
 backend/labelforge/templates/store.py | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1b89ef5..4b65246 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -156,6 +156,9 @@ jobs:
       - uses: actions/checkout@v6
       - name: Validate compose files
         run: |
+          # compose files reference `env_file: .env`, which is gitignored.
+          # Seed a throwaway .env from the tracked example so `config` can resolve it.
+          [ -f .env ] || cp .env.example .env
           for f in docker-compose.yml docker-compose.dev.yml; do
             if [ -f "$f" ]; then
               docker compose -f "$f" config --quiet && echo "OK $f"
diff --git a/backend/labelforge/templates/store.py b/backend/labelforge/templates/store.py
index cbc2ad2..4486119 100644
--- a/backend/labelforge/templates/store.py
+++ b/backend/labelforge/templates/store.py
@@ -1,7 +1,7 @@
 import json
 import re
 import sqlite3
-from datetime import datetime
+from datetime import UTC, datetime
 
 from labelforge.config import settings
 from labelforge.db import get_connection
@@ -15,7 +15,7 @@ def _db_path():
 
 
 def _now_utc() -> str:
-    return datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
 def _row_to_template(row: sqlite3.Row) -> Template:

From 44109f41a55b9743ead3ee88cdfa1b8ce0323b32 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 19:27:01 -0700
Subject: [PATCH 72/84] chore: adopt release-prep-and-cut standard (v1.0.0)

- .claude/commands/release-prep.md + release-cut.md added (slash commands)
- build-and-push.yml: release:published replaces tags:v*.*.* trigger (ADR 2026-06-05)
- .gitignore: un-ignore .claude/commands/ so slash commands are tracked
- CLAUDE.md: Release process (operational rules) section pasted verbatim; Build Status block added
- standards.md: release-prep-and-cut @ 1.0.0 registered
- README.md: version line + What's New section added; status blurb updated
- docs/decisions.md: ADR for publish trigger reconciliation
- CHANGELOG.md: adoption entry added; stale [version] template header removed
---
 .claude/commands/release-cut.md               | 105 ++++++++
 .claude/commands/release-prep.md              | 243 ++++++++++++++++++
 .github/workflows/build-and-push.yml          |   4 +-
 .gitignore                                    |   6 +-
 CHANGELOG.md                                  |  16 +-
 CLAUDE.md                                     |  46 +++-
 README.md                                     |   8 +-
 docs/decisions.md                             |  18 ++
 .../2026-06-05-adopt-release-prep-and-cut.md  | 129 ++++++++++
 standards.md                                  |   1 +
 10 files changed, 558 insertions(+), 18 deletions(-)
 create mode 100644 .claude/commands/release-cut.md
 create mode 100644 .claude/commands/release-prep.md
 create mode 100644 prompts/done/2026-06-05-adopt-release-prep-and-cut.md

diff --git a/.claude/commands/release-cut.md b/.claude/commands/release-cut.md
new file mode 100644
index 0000000..fbd53c2
--- /dev/null
+++ b/.claude/commands/release-cut.md
@@ -0,0 +1,105 @@
+---
+description: Cut a GitHub release after the dev→main PR has merged and main CI is green
+argument-hint: <version>   (e.g. 0.3.6 — must match what /release-prep prepared)
+---
+
+<!--
+Template from standards/release-prep-and-cut @ v1.0.0
+(crzynet/homelab-configs/standards/release-prep-and-cut/README.md).
+labelforge values: VERSION_FILE=pyproject.toml, MAIN_CI_WORKFLOW=CI, PUBLISH_WORKFLOW=Build and Push
+-->
+
+# Release Cut
+
+You are publishing the GitHub release for **v$ARGUMENTS**. Run this ONLY
+after:
+
+- `/release-prep $ARGUMENTS` has merged into `main`, and
+- the push-to-`main` CI + image-publish workflows are green and `:latest`
+  images are in the registry.
+
+Publishing the release triggers the `release: published` workflow, which
+builds and pushes the production `:latest`, `:v$ARGUMENTS`, and `:v<major>`
+images. So this step is the point of no return for production images —
+verify before tagging.
+
+## Execution rules
+
+- `$ARGUMENTS` SHOULD be bare semver (no `v` prefix). If a leading `v` was
+  typed (`v0.3.6`), strip it silently. After stripping, if the value does
+  not match `MAJOR.MINOR.PATCH` exactly, STOP and ask for a valid version.
+- The bare value MUST equal the current version in `pyproject.toml` on
+  `main`. If it does not, STOP.
+- The release tag is `v$ARGUMENTS` (with the `v` prefix — matches the
+  existing tag convention and the Docker `type=semver` extraction). Before
+  calling `gh`, assert the tag string matches `^v[0-9]+\.[0-9]+\.[0-9]+$`
+  exactly. If it does not, STOP — never create a malformed tag.
+- Do NOT add `Co-authored-by` lines anywhere.
+- If any verification step fails, STOP and report. Do not create the tag.
+
+## Step 1 — Verify we are releasing the right commit
+
+1. `git fetch origin` and check out `main`: `git checkout main && git pull`.
+2. Confirm the version in `pyproject.toml` equals `$ARGUMENTS`. If not, the
+   prep PR is not merged (or the wrong version was passed) — STOP.
+3. Confirm the working tree is clean.
+4. Confirm `git log` shows the `chore(release): prepare v$ARGUMENTS` commit on
+   `main`. If absent, STOP — the PR has not been merged.
+
+## Step 2 — Verify CI is green on main
+
+Use `gh` to confirm the latest runs on `main` for this commit succeeded:
+
+1. `gh run list --branch main --limit 10` and confirm the most recent runs
+   for the release commit concluded `success` for BOTH `CI`
+   and `Build and Push`.
+2. If a run is still in progress, tell the user to wait and STOP — do not tag
+   a commit whose images may not exist yet.
+3. If a run failed, STOP and report which job failed.
+
+## Step 3 — Confirm the version tag does not already exist
+
+`git tag -l "v$ARGUMENTS"` and `gh release view v$ARGUMENTS` — if either
+exists, STOP and report. Never overwrite an existing release/tag.
+
+## Step 4 — Assemble the release notes
+
+Extract the `## [$ARGUMENTS] — <date>` section from `CHANGELOG.md` (everything
+from that header up to, but not including, the next `## [` header). This is
+the release body — the changelog is the single source of truth, matching the
+PR description `/release-prep` created.
+
+## Step 5 — Create the release
+
+Write the extracted section to a temp file and pass it via `--notes-file`.
+Create an annotated tag on the current `main` HEAD and publish the release in
+one step with `gh`:
+
+```
+gh release create v$ARGUMENTS \
+  --target main \
+  --title "v$ARGUMENTS" \
+  --notes-file <tmp>
+```
+
+Do not try to inline multi-line release notes.
+
+## Step 6 — Verify the production build fired
+
+1. `gh run list --workflow "Build and Push" --limit 3` and confirm a run
+   triggered by the `release` event for `v$ARGUMENTS` has started or
+   succeeded.
+2. Report its status.
+
+## Step 7 — Report
+
+Print:
+
+- The release URL.
+- The tag created (`v$ARGUMENTS`).
+- The status of the production image build.
+- A reminder of the expected image tags once the build finishes: `:latest`,
+  `:v$ARGUMENTS`, `:v<major>.<minor>`, `:v<major>` — the `v` prefix is added
+  by the `prefix=v` rule in `build-and-push.yml`'s `metadata-action`.
+
+Done — the release is live.
diff --git a/.claude/commands/release-prep.md b/.claude/commands/release-prep.md
new file mode 100644
index 0000000..1b3e95c
--- /dev/null
+++ b/.claude/commands/release-prep.md
@@ -0,0 +1,243 @@
+---
+description: Prepare a release — bump version, roll changelog, sync docs, validate, commit, push to dev, open PR
+argument-hint: <version>   (e.g. 0.3.6)
+---
+
+<!--
+Template from standards/release-prep-and-cut @ v1.0.0
+(crzynet/homelab-configs/standards/release-prep-and-cut/README.md).
+labelforge values: VERSION_FILE=pyproject.toml, CHANGELOG_ARCHIVE_DIR=docs/
+-->
+
+# Release Prep
+
+You are preparing release **v$ARGUMENTS**. This command does ONLY the prep + PR
+steps. It does **not** merge and does **not** create the GitHub release — the
+human merges, and `/release-cut` (run after `main` CI is green) creates the
+release.
+
+## Execution rules
+
+- Work on the `dev` branch. Never push directly to `main`.
+- Do NOT add `Co-authored-by` lines to the commit.
+- Do NOT create the GitHub release or tag in this command.
+- If any validation step fails, STOP and report — do not commit broken state.
+- Make exactly ONE commit covering version + changelog + all doc updates.
+- `$ARGUMENTS` is the target version. It SHOULD be bare semver, no `v` prefix
+  (e.g. `0.3.6`). If a leading `v` was typed (`v0.3.6`), strip it silently and
+  proceed with the bare number. After stripping, if the value is empty or does
+  not match `MAJOR.MINOR.PATCH` exactly (three integers, dot-separated, no
+  pre-release/build suffix), STOP and ask for a valid version.
+- Reminder on the `v` convention: the version is stored and used BARE
+  everywhere (`pyproject.toml`, changelog header, README badge, in-code image
+  tags). The `v` prefix is added in exactly one place — the git tag / GitHub
+  release — and that happens in `/release-cut`, not here.
+
+## Step 0 — Preflight
+
+1. Confirm the current branch is `dev`. If not, STOP and report.
+2. Confirm the working tree is clean (`git status --porcelain` empty). If
+   there are uncommitted changes, STOP and show them — the user must decide.
+3. Read the current version from `pyproject.toml`. Parse both the current
+   version and `$ARGUMENTS` into `(MAJOR, MINOR, PATCH)` integer triples for
+   comparison.
+
+### 0a — Hard stops (never proceed past these)
+
+- **Not newer.** If `$ARGUMENTS` is not strictly greater than the current
+  version (compared as integer triples, not string compare), STOP and report.
+  This blocks re-running an already-shipped version, going backward, or a typo
+  that lands on an old number. Equal-to-current also stops.
+- **Tag already exists.** Run `git fetch --tags` then check both
+  `git tag -l "v$ARGUMENTS"` and `gh release view "v$ARGUMENTS"`. If either
+  exists, STOP and report — the release already exists and must not be
+  clobbered.
+
+### 0b — Bump-tier classification (warn + confirm)
+
+Classify the jump from current → target. Only a clean single-patch bump
+proceeds silently; everything else pauses for explicit confirmation.
+
+- **Patch bump** = MAJOR and MINOR unchanged, PATCH increased.
+  - If PATCH increased by exactly 1 (e.g. `0.3.3` → `0.3.4`): proceed, no
+    prompt.
+  - If PATCH skipped ahead (e.g. `0.3.3` → `0.3.7`): WARN that N patch
+    versions were skipped, show the expected next patch (current with
+    PATCH+1), and require explicit confirmation before proceeding.
+
+- **Minor bump** = MINOR increased (MAJOR unchanged), e.g. `0.3.3` → `0.4.0`.
+  ALWAYS warn and require confirmation, even for the clean `.0` case. Message:
+  this is a **new minor release**, which is infrequent — confirm it's
+  intended. Note that a new minor also fires the changelog archive trigger
+  (Step 3). If the target is a minor bump but PATCH is not `0` (e.g.
+  `0.3.3` → `0.4.2`), additionally flag that new minors normally start at
+  `.0`.
+
+- **Major bump** = MAJOR increased, e.g. `0.3.3` → `1.0.0`. ALWAYS warn with
+  strong language and require explicit confirmation: this is a **major
+  release**, the rarest and most consequential bump, and it produces a new
+  `:<major>` image tag. If MINOR or PATCH is not `0` (e.g. `1.2.0`),
+  additionally flag that major releases normally start at `X.0.0`.
+
+When warning, always show the three "expected next" successors from the
+current version so the user can see what they may have meant:
+next patch (`MAJOR.MINOR.PATCH+1`), next minor (`MAJOR.MINOR+1.0`),
+next major (`MAJOR+1.0.0`).
+
+Do not proceed on any warned tier without a clear affirmative ("yes",
+"confirmed", etc.) in the chat. If the user declines, STOP.
+
+### 0c — Remaining setup
+
+4. Determine whether this is a **new minor** (MINOR differs from current) or
+   a **patch within the current minor**. This decides whether the archive
+   trigger fires (Step 3). (A major bump is also "new minor" for archive
+   purposes — the previous minor series gets archived regardless.)
+5. Capture today's date as `YYYY-MM-DD` for the changelog header.
+
+## Step 1 — Bump the version
+
+Update `pyproject.toml` so the literal `version = "<current>"` reflects
+`$ARGUMENTS`. This is the single source of truth — CI and the in-app version
+display both read from it. Do not touch helper functions or surrounding code.
+
+## Step 2 — Roll the changelog
+
+In `CHANGELOG.md`:
+
+1. Change the `## [Unreleased]` header to `## [$ARGUMENTS] — <today>`.
+2. Insert a fresh empty `## [Unreleased]` block (matching whatever HTML-comment
+   skeleton the file already uses) directly above the new version header.
+3. Leave the rolled section's entries exactly as written by the dev work — do
+   not rewrite them, but DO sanity-check that every entry is user-facing prose
+   and sits under a correct category heading (Added / Changed / Fixed /
+   Security / Deprecated / Removed). Fix obvious miscategorisation only.
+4. If the `[Unreleased]` section is empty (no entries to ship), STOP and
+   report — there is nothing to release.
+
+## Step 3 — Per-minor archive trigger (NEW MINOR ONLY)
+
+Only if Step 0 determined this is the **first release of a new minor** (e.g.
+cutting `0.4.0` while the active file holds `0.3.x`):
+
+1. Move the entire previous minor series (all `0.3.x` blocks, in this example)
+   out of `CHANGELOG.md` into a new `docs/CHANGELOG-<prev-minor>.x.md` (e.g.
+   `docs/CHANGELOG-0.3.x.md`), newest-first within that file, matching the
+   format of any existing archive file.
+2. Prepend a link to the new archive in the "Archived releases" index at the
+   bottom of `CHANGELOG.md`.
+3. Confirm the active `CHANGELOG.md` now holds only `[Unreleased]` plus the
+   new current minor series (just the `$ARGUMENTS` block at this point).
+
+For a **patch release** (e.g. `0.3.6`), do NOT archive anything — skip this
+step entirely.
+
+## Step 4 — Sync the README
+
+In `README.md`:
+
+1. Update the version badge: in `**Version:** <current>`, replace the current
+   version with `$ARGUMENTS` (e.g. `**Version:** 0.0.1` → `**Version:** $ARGUMENTS`).
+2. Add a `### v$ARGUMENTS (<today>)` entry at the top of the `## What's New`
+   section, summarising this release in user-facing language drawn from the
+   changelog entries you just rolled. Keep it consistent with the voice of the
+   existing entries.
+3. Update any top-of-file new-in banner / one-line status blurb to reference
+   `$ARGUMENTS` if it currently names a specific version.
+
+## Step 5 — Sync long-form docs
+
+For each of these docs:
+
+- **`README.md`**: version line and `## What's New` entry — handled in Step 4.
+- **`CLAUDE.md`**: update the **Build Status** block — set "Last shipped:
+  v$ARGUMENTS" and update "Target for next release" as appropriate.
+
+Do not invent new sections — only adjust version-referencing content that
+already exists.
+
+## Step 6 — Validate locally BEFORE committing
+
+Run the same checks CI will run, so a red PR is caught now. Run each in order.
+If ANY check fails, STOP, report exactly what failed, and do not commit.
+
+1. `ruff check .`
+2. `ruff format --check .`
+3. `mypy backend`
+4. `pytest -q`
+5. Config validation (`config` job from `ci.yml` — validate all tracked YAML/JSON/TOML):
+   ```bash
+   python - <<'PY'
+   import json, pathlib, subprocess, sys, tomllib
+   import yaml
+   files = subprocess.check_output(
+       ["git", "ls-files", "*.yml", "*.yaml", "*.json", "*.toml"],
+       text=True).split()
+   errors = []
+   for f in files:
+       p, data = pathlib.Path(f), pathlib.Path(f).read_bytes()
+       try:
+           if p.suffix in (".yml", ".yaml"):
+               list(yaml.safe_load_all(data))
+           elif p.suffix == ".json":
+               json.loads(data)
+           elif p.suffix == ".toml":
+               tomllib.loads(data.decode())
+       except Exception as e:
+           errors.append(f"{f}: {e}")
+   for e in errors:
+       print(f"::error::{e}")
+   if errors:
+       sys.exit(1)
+   print(f"OK: {len(files)} config files parse cleanly")
+   PY
+   ```
+6. `[ -f .env ] || cp .env.example .env`
+7. `docker compose -f docker-compose.yml config --quiet`
+8. `docker compose -f docker-compose.dev.yml config --quiet`
+
+Also grep for version-string drift: confirm no stale `<old-version>`
+references remain in `README.md`, `pyproject.toml`, or `CLAUDE.md`.
+Report any other occurrences you find rather than blindly editing.
+
+## Step 7 — Commit
+
+Stage everything and make ONE commit. Use a conventional-commit subject and a
+body that lists what changed. Template:
+
+```
+chore(release): prepare v$ARGUMENTS
+
+- pyproject.toml bumped to $ARGUMENTS
+- CHANGELOG: rolled [Unreleased] → [$ARGUMENTS] — <today>
+- README: version badge + What's New entry
+- CLAUDE.md: Build Status block updated
+<- archive line ONLY if a new-minor archive was performed>
+```
+
+No `Co-authored-by` lines.
+
+## Step 8 — Push and open the PR
+
+1. `git push origin dev`.
+2. Open a PR `dev` → `main` with `gh pr create`:
+   - Title: `Release v$ARGUMENTS`
+   - Body: this release's CHANGELOG section (the `[$ARGUMENTS]` block you just
+     rolled), so the PR description is the release notes. This is the same
+     text `/release-cut` will use as the GitHub release body — single source
+     of truth.
+3. Capture the PR URL.
+
+## Step 9 — Report and STOP
+
+Print a short summary:
+
+- The PR URL.
+- Confirmation that local validation passed.
+- The exact next steps for the human, verbatim:
+  1. Review the PR on GitHub and wait for CI to go green.
+  2. Merge the PR into `main`.
+  3. Wait for the push-to-`main` build to publish `:latest` to the registry.
+  4. Run `/release-cut $ARGUMENTS` to tag and publish the GitHub release.
+
+Do NOT proceed past this point. Do not merge. Do not tag.
diff --git a/.github/workflows/build-and-push.yml b/.github/workflows/build-and-push.yml
index 3d7d499..58d403e 100644
--- a/.github/workflows/build-and-push.yml
+++ b/.github/workflows/build-and-push.yml
@@ -3,8 +3,8 @@ name: Build and Push
 on:
   push:
     branches: [main, dev]
-    tags:
-      - 'v*.*.*'
+  release:
+    types: [published]
 
 concurrency:
   group: build-${{ github.ref }}
diff --git a/.gitignore b/.gitignore
index fea3deb..77d115a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,10 +72,12 @@ data-dev/
 *.log
 logs/
 
-# claude — ignore the dir but track the shared settings.json. Any per-host
-# auto-generated .claude/CLAUDE.md and settings.local.json stay ignored.
+# claude — ignore the dir but track the shared settings.json and slash commands.
+# Any per-host auto-generated .claude/CLAUDE.md and settings.local.json stay ignored.
 .claude/*
 !.claude/settings.json
+!.claude/commands/
+!.claude/commands/*.md
 
 # Test artifacts
 .coverage
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6b9897..28b0b2a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Changed
+
+- **Adopted `release-prep-and-cut` standard (v1.0.0)** — `/release-prep` and `/release-cut` slash commands added to `.claude/commands/`; publish workflow (`build-and-push.yml`) now fires on `release: published` (tag-push trigger removed); `CLAUDE.md` and `standards.md` updated. Developer/process-facing only — no runtime change.
+
 ### Fixed
 
 - **Upgrade now delivers new and corrected default catalog entries** (#16) — upgrading the
@@ -134,15 +138,3 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 - Printer status: empirically confirmed the network print path (TCP 9100) does not answer status requests; the printer's EWS page (HTTP port 80) does report loaded media and is the chosen status source (opt-in). See ADR 2026-05-20 (c).
 - Deferred to later slices: Fabric.js canvas editor, history UI + retention, printer-status feature (EWS scrape), settings UI, two-color (62red) rendering, image elements / image upload.
 
----
-
-Format for future entries:
-
-## [version] — YYYY-MM-DD
-
-### Added
-### Changed
-### Deprecated
-### Removed
-### Fixed
-### Security
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
index e5667cc..a4994b8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,9 +8,14 @@ Context for AI coding sessions in this repo. Read this before doing anything.
 
 Owner: crzykidd. Personal homelab project, public open source. Single-user app — no multi-user features.
 
+## Build Status
+
+- **Last shipped:** — (no release yet)
+- **Target for next release:** TBD
+
 ## Standards
 
-This project implements shared engineering standards from the crzynet `homelab-configs` repo. **Read [`standards.md`](standards.md) at the repo root on session start** whenever the work could touch branching, commits, PRs, handoff prompts, or the sandbox — it pins which standards and versions this repo conforms to. The hard per-session operational rules from those standards are pasted verbatim at the end of this file (Code check-in).
+This project implements shared engineering standards from the crzynet `homelab-configs` repo. **Read [`standards.md`](standards.md) at the repo root on session start** whenever the work could touch branching, commits, PRs, handoff prompts, or the sandbox — it pins which standards and versions this repo conforms to. The hard per-session operational rules from those standards are pasted verbatim at the end of this file (Code check-in; Release process).
 
 ## Source of truth
 
@@ -134,3 +139,42 @@ honor by default:
 
 If you're unsure whether an action would violate one of the above, stop and ask before
 acting.
+
+<!--
+Source: standards/release-prep-and-cut @ v1.0.0 (crzynet/homelab-configs).
+Paste the section below verbatim into the adopting project's CLAUDE.md.
+The full standard (two-phase prep/cut workflow, archive trigger, validation
+steps, adoption checklist) lives at:
+https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/release-prep-and-cut/README.md
+-->
+
+## Release process (operational rules)
+
+This project adopts the `release-prep-and-cut` standard. The full why-and-how
+lives at the source above; the rules below are the per-session do/don'ts a
+coding agent must honor by default:
+
+- **The version is stored BARE in the source-of-truth file** — no `v` prefix
+  anywhere in code. The `v` prefix is added in exactly one place: the git tag
+  and matching GitHub release name. Don't add it to README badges, CHANGELOG
+  headers, in-code image tags, or anywhere else.
+- **`CHANGELOG.md` is the single source of truth for release notes.** The PR
+  description (set by `/release-prep`) and the GitHub release body (set by
+  `/release-cut`) reuse the **same section verbatim**. Never author release
+  notes twice.
+- **One commit per release prep.** Version bump + changelog roll + every doc
+  sync ship in a single `chore(release): prepare v<version>` commit. No
+  `Co-authored-by:` trailers.
+- **Never re-tag.** If `v<version>` already exists as a local tag, a remote
+  tag, or a GitHub release, STOP. Never delete-and-recreate; never `--force`.
+  Pick the next version instead.
+- **`/release-cut` only after the PR has merged and CI is green.** The
+  publish-to-`main` workflow must have already pushed `:latest` images to the
+  registry before `/release-cut` runs. If you cannot confirm both — STOP and
+  tell the user to wait.
+- **The release tag is the only thing the cut command writes to `main`.** Both
+  the prep commit and any follow-up docs commit land on `dev` and reach `main`
+  only via PR. Never push directly to `main` as part of a release.
+
+If you're unsure whether an action would violate one of the above, stop and
+ask before acting.
diff --git a/README.md b/README.md
index fda8fbd..88c4c1b 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,13 @@
 
 Self-hosted web app for designing, saving, and printing labels to Brother QL series printers.
 
-**Status**: Early development. Not yet usable.
+**Status**: Pre-release. Core print and template features working; not yet packaged for deployment.
+
+**Version:** 0.0.1
+
+## What's New
+
+_No releases yet. See `CHANGELOG.md` for upcoming changes._
 
 ## What it does
 
diff --git a/docs/decisions.md b/docs/decisions.md
index d132318..0131869 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,24 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-05 — Release publish trigger: `release: published` replaces tag-push for production builds
+
+**Decision**: Removed the `tags: v*.*.*` trigger from `build-and-push.yml`. `release: published` is now the sole trigger for production image builds. The `push: branches: [main, dev]` trigger is retained for rolling dev/latest builds.
+
+**Why**: `gh release create v<version>` (run by `/release-cut`) both creates the GitHub release AND pushes the git tag. With both `tags: v*.*.*` and `release: published` active, a single `/release-cut` invocation would fire the build workflow twice on the same commit — wasting CI minutes and risking a race between two concurrent builds pushing identical `:latest` image layers. Removing the tag-push trigger makes `release: published` the single, deterministic gate for release builds. This aligns with the `code-checkin-and-pr` standard's publishing matrix and is required by the `release-prep-and-cut` standard's `/release-cut` step 6 (verifies the build triggered by the `release` event specifically).
+
+**Image tags on release**: The `metadata-action`'s `type=semver,prefix=v` rules produce `:v<version>`, `:v<major>.<minor>`, `:v<major>` (with a `v` prefix on image tags, matching the existing tag convention). `:latest` is also produced by `type=raw,value=latest,enable=startsWith(github.ref, 'refs/tags/v')`. This implements the `code-checkin-and-pr` matrix (`:latest`, `:<semver>`, `:<major>`) with an added `v` prefix from the existing config.
+
+**Context**: Part of adopting `release-prep-and-cut @ 1.0.0`.
+
+**Considered**:
+- Keep `tags: v*.*.*` only, remove `release: published` — rejected; the `release-prep-and-cut` standard requires `/release-cut` to verify a build triggered by the `release` event.
+- Keep both triggers and deduplicate in the workflow — rejected; fragile and over-engineered for a solo project.
+
+**Would revisit if**: Docker image tag conventions change (e.g. dropping the `v` prefix from image tags); or if the release workflow needs pre-release staging triggered by draft releases.
+
+---
+
 ## 2026-06-05 — Catalog reconciliation: 3-way merge with baseline, operator-wins, never-delete
 
 **Decision**: On startup, labelforge performs a non-destructive 3-way merge of the bundled
diff --git a/prompts/done/2026-06-05-adopt-release-prep-and-cut.md b/prompts/done/2026-06-05-adopt-release-prep-and-cut.md
new file mode 100644
index 0000000..8349803
--- /dev/null
+++ b/prompts/done/2026-06-05-adopt-release-prep-and-cut.md
@@ -0,0 +1,129 @@
+---
+name: 2026-06-05-adopt-release-prep-and-cut
+status: completed
+created: 2026-06-05
+model: sonnet
+completed: 2026-06-05
+result: release-prep-and-cut v1.0.0 adopted — slash commands in .claude/commands/, CLAUDE-snippet pasted, build-and-push.yml trigger reconciled to release:published, standards.md + CHANGELOG.md + README.md + ADR updated
+---
+
+# Task: Adopt the `release-prep-and-cut` standard in labelforge (@ v1.0.0)
+
+labelforge is about to cut its first release but has **not** adopted the homelab
+`release-prep-and-cut` standard that governs how releases are prepped and published. This
+task wires it up: copy the two slash-command templates into `.claude/commands/` with
+labelforge's values filled in, reconcile the publish trigger, paste the CLAUDE snippet,
+register the adoption, and clean up two pre-existing snags. **It does NOT cut a release** —
+it only installs the machinery so a later `/release-prep <version>` works.
+
+## Before you start
+
+- **Read the standard, fully**, from the local source-of-truth clone:
+  - `~/projects/homelab-configs/standards/release-prep-and-cut/README.md` (the rules)
+  - `.../release-prep-and-cut/release-prep.md` and `.../release-cut.md` (the two templates
+    you'll copy — each has a placeholder header block at the top)
+  - `.../release-prep-and-cut/CLAUDE-snippet.md` (paste-verbatim block)
+  - `~/projects/homelab-configs/standards/code-checkin-and-pr/README.md` — it **owns the
+    image-publishing matrix that fires on `release: published`**; release-cut composes with
+    it. Read its publish-matrix section before touching `build-and-push.yml` (see step 4).
+- Read labelforge's `standards.md` (the in-repo registry) and the existing
+  `### Code check-in (operational rules)` section in `CLAUDE.md` to match style/placement.
+- Map-not-copy: link back to the standard, don't restate its prose.
+- Work on `dev`. Conventional-Commits prefixes, no `Co-authored-by:`, docs ship with code.
+
+## Working tree check
+
+Run `git status --porcelain` first. **Sequencing matters:** this depends on two things that
+should land before it — (a) the queued `prompts/2026-06-05-enable-mypy-ci.md` work (it sets
+the real `<LOCAL_CHECKS>` — mypy must actually pass), and (b) an uncommitted datetime/compose
+fix the owner may still be committing. If `CHANGELOG.md`, `pyproject.toml`, or `.github/`
+files show unexpected uncommitted changes, **stop and ask** rather than commit over them.
+
+## labelforge placeholder values (use these)
+
+| Placeholder | Value |
+|---|---|
+| `<VERSION_FILE>` | `pyproject.toml` |
+| `<VERSION_LITERAL>` | `version = "<current>"` (the `[project]` version line) |
+| `<README_BADGE_PATTERN>` | labelforge's README has **no** version badge today. Add a simple one (e.g. a static shields.io `version-<current>-blue` badge) near the title, OR if you'd rather not introduce a badge, set this to a plain `**Version:** <current>` line. Pick one and be consistent in both templates. |
+| `<README_WHATSNEW_SECTION>` | `## What's New` — **create this section** (README has none yet); put it just under the title/intro, above `## What it does`. Also update the `**Status**: Early development. Not yet usable.` line — at first release that claim is no longer true. |
+| `<DOCS_TO_SYNC>` | `README.md` (badge/version + What's New entry); `CLAUDE.md` (add a small **Build Status** block: current release target / last shipped release — mirror the standard's example). `docs/PRD.md` has **no** revision-history table — only add version syncing there if you choose to add such a table; otherwise omit. The app already surfaces `App version` in Settings (`docs/features/settings.md:57`) read from `pyproject.toml`, so no code change is needed for the in-app display. |
+| `<LOCAL_CHECKS>` | The exact commands CI's `python`/`config`/`compose` jobs run: `ruff check .` · `ruff format --check .` · `mypy backend` · `pytest -q` · the tracked-config YAML/JSON/TOML validation (see the `config` job in `ci.yml`) · `cp .env.example .env` then `docker compose -f docker-compose.yml config --quiet` and `-f docker-compose.dev.yml config --quiet`. Copy them faithfully so prep runs the same gates CI does. |
+| `<CHANGELOG_ARCHIVE_DIR>` | `docs/` (archive files `docs/CHANGELOG-<minor>.x.md`) |
+| `<MAIN_CI_WORKFLOW>` | `CI` (`.github/workflows/ci.yml`) |
+| `<PUBLISH_WORKFLOW>` | `Build and Push` (`.github/workflows/build-and-push.yml`) |
+| `<RELEASE_IMAGE_TAGS>` | `:latest`, `:<version>`, `:<major>` — verify against `build-and-push.yml`'s actual `metadata-action` tag rules and correct the list if they differ |
+
+## What to do
+
+1. **Copy the two templates** into `.claude/commands/` (create the dir):
+   `release-prep.md` and `release-cut.md`. Replace **every** `<PLACEHOLDER>` using the table
+   above. When done, `grep -n '<[A-Z_]\+>' .claude/commands/*.md` must return nothing — no
+   unsubstituted placeholders. Keep the source-attribution comment that links back to the
+   standard.
+
+2. **Paste `CLAUDE-snippet.md` verbatim** into `CLAUDE.md` as a new
+   `## Release process (operational rules)` section (place it near the existing
+   `## Code check-in (operational rules)` block — they're siblings). Don't reword it.
+
+3. **Add the Build Status block to `CLAUDE.md`** referenced by `<DOCS_TO_SYNC>` (current
+   release target / last shipped release), so `/release-prep` has something to sync.
+
+4. **Reconcile the publish trigger** (the one real design decision — record it as an ADR).
+   `build-and-push.yml` currently fires on `push` to `main`/`dev` and on `tags: v*.*.*`.
+   The standard's `/release-cut` does `gh release create v<version>`, and both this standard
+   and `code-checkin-and-pr` assume the publish matrix fires on **`release: published`**.
+   Align it: add a `release: { types: [published] }` trigger that builds the
+   `:latest` / `:<version>` / `:<major>` image tags. To avoid a *double* build (creating a
+   GitHub release also creates the `v*` tag, which the existing `tags:` trigger would catch),
+   **remove the `tags: v*.*.*` trigger** so the release event is the single source of the
+   release build; keep the branch-push trigger for `dev`/`main` dev images. Verify the
+   `metadata-action` tag rules still emit the three release tags on the `release` event.
+   Confirm this matches `code-checkin-and-pr`'s matrix; if that standard mandates a specific
+   shape, follow it and note any deviation.
+
+5. **Register the adoption** in `standards.md`: add a new row at the top (newest first),
+   `release-prep-and-cut | 1.0.0 | 2026-06-05 | …` with notes covering: templates copied to
+   `.claude/commands/`, CLAUDE-snippet pasted, publish trigger reconciled to
+   `release: published` (ADR ref), `<VERSION_FILE>` = `pyproject.toml`. Also update the
+   `CLAUDE.md` line that points at `standards.md` if its wording needs it.
+
+6. **Cleanup — stray CHANGELOG placeholder.** `CHANGELOG.md` has a leftover
+   `## [version] — YYYY-MM-DD` template header (around line 139) sitting below real content.
+   Remove it — it's not a real release section and would confuse the prep/archive logic.
+   (Leave the real `## [Unreleased]` block untouched.)
+
+7. **Do NOT bump the version or roll the changelog** — that's `/release-prep`'s job, run
+   later by the owner. This task only installs the commands and wiring.
+
+## Conventions to honor
+
+- LF endings. The `.claude/commands/*.md` files are agent-facing command specs — keep the
+  standard's structure intact; only substitute placeholders and the attribution link.
+- Changelog: add a `### Changed` entry under `## [Unreleased]` — labelforge adopts the
+  `release-prep-and-cut` standard (`/release-prep` + `/release-cut` slash commands added;
+  publish workflow now fires on `release: published`; CLAUDE.md + standards.md updated).
+  Developer/process-facing, no runtime change.
+- The homelab-configs **registry** (`projects/labelforge/README.md` + `projects/README.md`)
+  also needs an adoption row per the standard — but that's a **different repo**
+  (`~/projects/homelab-configs`), out of scope for this labelforge commit. Note it in your
+  final summary so the owner can do it there.
+
+## When done
+
+1. Verify: `grep` finds no leftover `<PLACEHOLDER>` in `.claude/commands/`; `ruff check . &&
+   ruff format --check . && mypy backend && pytest -q` still green; both compose files still
+   `config`-validate. Give the one-line "run this to verify".
+2. Update this file's frontmatter (`status`, `completed` = 2026-06-05, `result`).
+3. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+4. Record the publish-trigger reconciliation (tag-push → `release: published`) as an ADR in
+   `docs/decisions.md`.
+5. Propose ONE commit covering `.claude/commands/release-prep.md` + `release-cut.md`,
+   `CLAUDE.md`, `standards.md`, `README.md`, `.github/workflows/build-and-push.yml`,
+   `CHANGELOG.md`, `docs/decisions.md`, and this prompt move. Present the file list and a
+   one-line message; ask
+   `commit these as "chore: adopt release-prep-and-cut standard (v1.0.0)"? (y/n)`. On `y`,
+   stage those specific paths (never `git add -A`) and commit on `dev`. Never push.
+6. In your final summary, hand the owner the launch command for a first release once they're
+   ready: `/release-prep <version>` (e.g. `/release-prep 0.1.0`), and remind them the
+   homelab-configs registry row still needs adding in that repo.
diff --git a/standards.md b/standards.md
index a6e4b12..dbf28d8 100644
--- a/standards.md
+++ b/standards.md
@@ -8,6 +8,7 @@ snippet-bearing standards are pasted verbatim into `CLAUDE.md`.
 
 | Standard | Version | Adopted | Notes |
 |---|---|---|---|
+| [release-prep-and-cut](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/release-prep-and-cut/README.md) | 1.0.0 | 2026-06-05 | Templates copied to `.claude/commands/release-prep.md` + `release-cut.md`; CLAUDE-snippet pasted verbatim into `CLAUDE.md`; publish trigger reconciled — `tags: v*.*.*` removed from `build-and-push.yml`, `release: published` is now the single release-build gate (see ADR 2026-06-05); `VERSION_FILE` = `pyproject.toml`; `CHANGELOG_ARCHIVE_DIR` = `docs/`. |
 | [code-checkin-and-pr](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/code-checkin-and-pr/README.md) | 1.1.0 | 2026-05-31 | Full adoption. CI (`ci.yml`) covers backend lint (ruff/mypy/pytest), structured-config validation, `docker compose config`, and PR-only image build; publish matrix (`build-and-push.yml`) + retention (`cleanup-images.yml`) already in place. **Migration check N/A** — no migration system (raw SQLite via `backend/labelforge/db.py`). Commit-prefix convention flipped to Conventional-Commits per ADR 2026-05-31. CLAUDE-snippet pasted verbatim into `CLAUDE.md`. |
 | [handoff-prompt-workflow](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/handoff-prompt-workflow/README.md) | 1.5.0 | 2026-05-31 | Upgraded from v1.0.0. Origin project for this standard. `prompts/` is the live queue; completed prompts archived under `prompts/done/`; `prompts/TEMPLATE.md` added; frontmatter gained `model:`; working-tree check + single-commit-with-ask + launch-command form reflected in `CLAUDE.md`. |
 | [repo-sandbox-permissions](https://gitea.crzynet.com/crzynet/homelab-configs/src/branch/main/standards/repo-sandbox-permissions/README.md) | 1.0.0 | 2026-05-31 | scope: **repo-wide** (`.claude/settings.json`), 2026-05-31. `allowedDomains` = localhost + pypi/files.pythonhosted + registry.npmjs (Python + Node stack); `allowWrite` = `/tmp/**`, `~/.cache/**` (covers uv/ruff/mypy), `~/.npm/**`. `bubblewrap` + `socat` installed on this host. **Restart Claude Code** to activate (`sandbox.enabled` is read at startup). |

From ac5359db61e22f3a0f30a9ac45acf4c96a932e24 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Fri, 5 Jun 2026 20:14:38 -0700
Subject: [PATCH 73/84] fix: set response_model=None on printer status route;
 add app-startup smoke test

---
 backend/labelforge/routes/printer.py |  2 +-
 backend/tests/conftest.py            |  8 ++++++++
 backend/tests/test_app_smoke.py      | 24 ++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 backend/tests/conftest.py
 create mode 100644 backend/tests/test_app_smoke.py

diff --git a/backend/labelforge/routes/printer.py b/backend/labelforge/routes/printer.py
index 907eb70..7d85c32 100644
--- a/backend/labelforge/routes/printer.py
+++ b/backend/labelforge/routes/printer.py
@@ -13,7 +13,7 @@
 router = APIRouter(tags=["printer"])
 
 
-@router.get("/printer/status")
+@router.get("/printer/status", response_model=None)
 async def get_printer_status() -> dict | JSONResponse:
     timeout_ms = settings_store.get("printer_status_timeout_ms")
 
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
new file mode 100644
index 0000000..71e03c8
--- /dev/null
+++ b/backend/tests/conftest.py
@@ -0,0 +1,8 @@
+import os
+
+# config.py instantiates Settings() at import time, which requires PRINTER_HOST and
+# either API_TOKEN or DISABLE_AUTH. CI has no .env file (it's gitignored), so set
+# CI-safe defaults before any test module imports the app. setdefault means a real
+# local .env / environment still wins.
+os.environ.setdefault("PRINTER_HOST", "127.0.0.1")
+os.environ.setdefault("DISABLE_AUTH", "true")
diff --git a/backend/tests/test_app_smoke.py b/backend/tests/test_app_smoke.py
new file mode 100644
index 0000000..d3cb4d6
--- /dev/null
+++ b/backend/tests/test_app_smoke.py
@@ -0,0 +1,24 @@
+"""Smoke test: the app must import and build its OpenAPI schema.
+
+Catches import-time / route-registration failures that per-module unit tests miss —
+e.g. an invalid FastAPI `response_model` (a return annotation unioning a Response type)
+raises when the route is registered, taking the whole app down at startup while every
+isolated unit test stays green. CI had no such guard before this test.
+"""
+
+
+def test_app_imports_and_core_routes_registered():
+    from labelforge.main import app
+
+    paths = {route.path for route in app.routes}
+    assert "/api/health" in paths
+    assert "/api/printer/status" in paths
+
+
+def test_openapi_schema_builds():
+    # Generating the schema exercises response-model construction for every route;
+    # an invalid return annotation raises here rather than only at container startup.
+    from labelforge.main import app
+
+    schema = app.openapi()
+    assert schema["info"]["title"]

From 6e9ea82521b982554c6a12556c064abea6682ef6 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 08:25:52 -0700
Subject: [PATCH 74/84] feat: print a template on a different label media at
 print time

---
 CHANGELOG.md                                  |  16 ++
 backend/labelforge/models/__init__.py         |   2 +
 backend/labelforge/render/template.py         |  37 ++-
 backend/labelforge/routes/history.py          |  13 +-
 backend/labelforge/routes/template_print.py   |  64 ++++--
 backend/tests/test_media_override.py          | 217 ++++++++++++++++++
 docs/decisions.md                             |  53 +++++
 docs/features/templates.md                    |  29 ++-
 docs/glossary.md                              |   4 +-
 frontend/src/api.ts                           |  37 ++-
 frontend/src/pages/template-editor.ts         |   2 +-
 frontend/src/pages/template-recall.ts         | 187 +++++++++++++--
 frontend/src/style.css                        |  29 +++
 frontend/src/types.ts                         |   1 +
 .../2026-06-06-print-time-media-override.md   | 156 +++++++++++++
 15 files changed, 791 insertions(+), 56 deletions(-)
 create mode 100644 backend/tests/test_media_override.py
 create mode 100644 prompts/done/2026-06-06-print-time-media-override.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 28b0b2a..ad4fa55 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,22 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+### Added
+
+- **Print a template on a different label media at recall time (one-off)** — the recall page
+  now shows a media selector instead of a read-only badge. Same-width media appear first
+  (most likely to fit the design without adjustment); a "Loaded in printer" toggle narrows
+  the list to the roll currently mounted. The stored template media is never mutated. The
+  chosen media is logged to history and reproduced faithfully on reprint. The Print button is
+  gated until a fresh preview has been taken after any media change. Requires a container
+  image rebuild.
+- **Mono + red notice on recall** — when a template contains red elements and a mono
+  (single-color) media is selected, an inline notice explains that red will print in black.
+  The renderer already maps red → black automatically; no action is needed.
+- **Overflow warning on recall** — when a die-cut media is chosen and the content extends
+  past its printable height, an inline warning appears near the preview. Printing still
+  proceeds — the user decides from the preview whether to adjust or proceed.
+
 ### Changed
 
 - **Adopted `release-prep-and-cut` standard (v1.0.0)** — `/release-prep` and `/release-cut` slash commands added to `.claude/commands/`; publish workflow (`build-and-push.yml`) now fires on `release: published` (tag-push trigger removed); `CLAUDE.md` and `standards.md` updated. Developer/process-facing only — no runtime change.
diff --git a/backend/labelforge/models/__init__.py b/backend/labelforge/models/__init__.py
index 541cdd1..2f4a604 100644
--- a/backend/labelforge/models/__init__.py
+++ b/backend/labelforge/models/__init__.py
@@ -95,10 +95,12 @@ class TemplateUpdate(BaseModel):
 
 class PrintRequest(BaseModel):
     fields: dict[str, str] = {}
+    label_media: str | None = None  # None = use the template's stored media
 
 
 class BatchPrintRequest(BaseModel):
     labels: list[dict[str, str]]
+    label_media: str | None = None  # None = use the template's stored media
 
 
 class BatchJobResult(BaseModel):
diff --git a/backend/labelforge/render/template.py b/backend/labelforge/render/template.py
index a920a93..0663133 100644
--- a/backend/labelforge/render/template.py
+++ b/backend/labelforge/render/template.py
@@ -202,18 +202,49 @@ def _render_barcode_element(payload: str, symbology: str, box_w: int, box_h: int
     return bw.resize((max(box_w, 1), max(box_h, 1)), Image.Resampling.NEAREST)
 
 
-def render_template(template: Template, values: dict[str, str]) -> Image.Image:
+def detect_overflow(template: Template, media_id: str) -> bool:
+    """True when any element's bottom edge exceeds the printable height for a die-cut media.
+
+    Continuous media never overflows (canvas length is content-driven). Returns False
+    for continuous media or when the media is unknown.
+    """
+    label = get_label(media_id)
+    if label is None:
+        return False
+    if label.form_factor in _CONTINUOUS_FORM_FACTORS:
+        return False
+    max_h = label.dots_printable[1]
+    for obj in template.canvas_json.get("objects", []):
+        top = int(obj.get("top", 0))
+        h = int(obj.get("height", 0) * float(obj.get("scaleY", 1.0)))
+        if top + h > max_h:
+            return True
+    return False
+
+
+def render_template(
+    template: Template,
+    values: dict[str, str],
+    *,
+    media_override: str | None = None,
+) -> Image.Image:
     """Rasterize *template* with *values* substituted for placeholders.
 
+    media_override: when set, render as if the template were on this media rather
+    than template.label_media. The stored template is never mutated. Used for
+    print-time one-off media selection (e.g. print a 62red design on 62x29).
+
     Returns a PIL Image sized for the print head. Mode is 'L' (0=black, 255=white)
     for mono media. For two-color media (label.color == 1, e.g. 62red / DK-2251)
     mode is 'RGB': black pixels are (0,0,0), red pixels are (255,0,0), paper is
     (255,255,255). The print path promotes L→RGB and passes red=True for two-color
     media; an RGB image here means red pixels land on the red print plane.
+    On mono media any red element is rendered as black (via _canvas_color_to_l/rgb).
     """
-    label = get_label(template.label_media)
+    effective_media = media_override or template.label_media
+    label = get_label(effective_media)
     if label is None:
-        raise RenderError(f"Unknown label media: {template.label_media!r}")
+        raise RenderError(f"Unknown label media: {effective_media!r}")
 
     canvas_w = label.dots_printable[0]
     objects = template.canvas_json.get("objects", [])
diff --git a/backend/labelforge/routes/history.py b/backend/labelforge/routes/history.py
index 8d2473f..eeb9e51 100644
--- a/backend/labelforge/routes/history.py
+++ b/backend/labelforge/routes/history.py
@@ -135,20 +135,23 @@ async def _reprint_template(job_id: int, row) -> dict:
             status_code=409,
             detail=f"Template '{row['template_id']}' no longer exists and cannot be reprinted",
         )
-    if get_label(tmpl.label_media) is None:
+    # Reprint on the media from the original history row, not the template's stored media.
+    # This reproduces one-off media overrides from the recall page exactly.
+    row_media = row["label_media"]
+    if get_label(row_media) is None:
         raise HTTPException(
             status_code=409,
-            detail=f"Label media '{tmpl.label_media}' is no longer in the catalog",
+            detail=f"Label media '{row_media}' is no longer in the catalog",
         )
     field_values = json.loads(row["field_values"]) if row["field_values"] else {}
     try:
-        image = render_template(tmpl, field_values)
+        image = render_template(tmpl, field_values, media_override=row_media)
     except RenderError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     try:
         outcome = print_image(
             image=image,
-            label_media=tmpl.label_media,
+            label_media=row_media,
             model=settings.printer_model,
             backend=settings.printer_backend,
             host=settings.printer_host,
@@ -158,7 +161,7 @@ async def _reprint_template(job_id: int, row) -> dict:
     new_id = insert_job_with_preview(
         image=image,
         payload_json=row["payload_json"],
-        label_media=tmpl.label_media,
+        label_media=row_media,
         template_name=row["template_id"],
         field_values=field_values,
         reprint_of=job_id,
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index a40a24c..9fd3fdd 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -6,6 +6,7 @@
 from fastapi.responses import Response
 
 from labelforge import settings_store
+from labelforge.catalog.loader import get_label
 from labelforge.config import settings
 from labelforge.history import insert_job_with_preview
 from labelforge.models import (
@@ -22,7 +23,7 @@
     status_read,
     to_print_bitmap,
 )
-from labelforge.render.template import render_template
+from labelforge.render.template import detect_overflow, render_template
 from labelforge.render.text import RenderError
 from labelforge.routes.auth import require_auth
 from labelforge.templates import store
@@ -62,16 +63,30 @@ def _apply_sample_defaults(template_fields, values: dict[str, str]) -> dict[str,
     return result
 
 
+def _resolve_effective_media(body_label_media: str | None, tmpl_label_media: str) -> str:
+    """Validate and return the effective media id, raising HTTPException on invalid input."""
+    if body_label_media is None:
+        return tmpl_label_media
+    label = get_label(body_label_media)
+    if label is None or not label.supported:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Label media '{body_label_media}' is not a supported catalog entry",
+        )
+    return body_label_media
+
+
 @router.post("/print/{name}")
 async def print_template(name: str, body: PrintRequest, override: bool = False) -> dict:
     tmpl = store.get_template(name)
     if tmpl is None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
 
+    effective_media = _resolve_effective_media(body.label_media, tmpl.label_media)
     values = _apply_defaults(tmpl.field_schema, body.fields)
 
     try:
-        image = render_template(tmpl, values)
+        image = render_template(tmpl, values, media_override=body.label_media)
     except RenderError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
@@ -95,18 +110,18 @@ async def print_template(name: str, body: PrintRequest, override: bool = False)
                     },
                 )
             media_id = status["media_id"]
-            if media_id is not None and not media_compatible(media_id, tmpl.label_media):
+            if media_id is not None and not media_compatible(media_id, effective_media):
                 if not override:
                     raise HTTPException(
                         status_code=409,
                         detail={
                             "error": "media_mismatch",
-                            "expected": tmpl.label_media,
+                            "expected": effective_media,
                             "loaded": media_id,
                             "override_allowed": True,
                             "message": (
                                 f"Printer has {media_id} loaded, "
-                                f"template expects {tmpl.label_media}. "
+                                f"template expects {effective_media}. "
                                 "Pass override=true to print anyway."
                             ),
                         },
@@ -114,7 +129,7 @@ async def print_template(name: str, body: PrintRequest, override: bool = False)
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
                     media_id,
-                    tmpl.label_media,
+                    effective_media,
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
@@ -122,7 +137,7 @@ async def print_template(name: str, body: PrintRequest, override: bool = False)
     try:
         outcome = print_image(
             image=image,
-            label_media=tmpl.label_media,
+            label_media=effective_media,
             model=settings.printer_model,
             backend=settings.printer_backend,
             host=settings.printer_host,
@@ -133,16 +148,19 @@ async def print_template(name: str, body: PrintRequest, override: bool = False)
     job_id = insert_job_with_preview(
         image=image,
         payload_json=body.model_dump_json(),
-        label_media=tmpl.label_media,
+        label_media=effective_media,
         template_name=name,
         field_values=values,
     )
 
+    overflow = detect_overflow(tmpl, effective_media)
+
     return {
         "job_id": job_id,
         "status": outcome,
         "template": name,
-        "label_media": tmpl.label_media,
+        "label_media": effective_media,
+        "overflow": overflow,
         "preview_url": f"/api/history/{job_id}/preview.png",
     }
 
@@ -153,11 +171,13 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
     if tmpl is None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
 
+    effective_media = _resolve_effective_media(body.label_media, tmpl.label_media)
+
     # Preview is a layout check — fill missing fields with samples rather than failing.
     values = _apply_sample_defaults(tmpl.field_schema, body.fields)
 
     try:
-        image = render_template(tmpl, values)
+        image = render_template(tmpl, values, media_override=body.label_media)
     except RenderError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
 
@@ -166,7 +186,13 @@ async def preview_template(name: str, body: PrintRequest) -> Response:
     # Mono templates apply the print threshold so preview == print.
     preview = image if image.mode == "RGB" else to_print_bitmap(image)
     preview.save(buf, format="PNG")
-    return Response(content=buf.getvalue(), media_type="image/png")
+
+    overflow = detect_overflow(tmpl, effective_media)
+    headers: dict[str, str] = {}
+    if overflow:
+        headers["X-Label-Overflow"] = "true"
+
+    return Response(content=buf.getvalue(), media_type="image/png", headers=headers)
 
 
 @router.post("/print/{name}/batch", response_model=BatchPrintResponse)
@@ -183,6 +209,8 @@ async def batch_print(
     if tmpl is None:
         raise HTTPException(status_code=404, detail=f"Template '{name}' not found")
 
+    effective_media = _resolve_effective_media(body.label_media, tmpl.label_media)
+
     # Status check once before the loop — avoids per-label overhead
     if settings_store.get("printer_status_check"):
         timeout_ms = settings_store.get("printer_status_timeout_ms")
@@ -204,18 +232,18 @@ async def batch_print(
                     },
                 )
             media_id = status["media_id"]
-            if media_id is not None and not media_compatible(media_id, tmpl.label_media):
+            if media_id is not None and not media_compatible(media_id, effective_media):
                 if not override:
                     raise HTTPException(
                         status_code=409,
                         detail={
                             "error": "media_mismatch",
-                            "expected": tmpl.label_media,
+                            "expected": effective_media,
                             "loaded": media_id,
                             "override_allowed": True,
                             "message": (
                                 f"Printer has {media_id} loaded, "
-                                f"template expects {tmpl.label_media}. "
+                                f"template expects {effective_media}. "
                                 "Pass override=true to print anyway."
                             ),
                         },
@@ -223,7 +251,7 @@ async def batch_print(
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
                     media_id,
-                    tmpl.label_media,
+                    effective_media,
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
@@ -236,10 +264,10 @@ async def batch_print(
     for label_values in body.labels:
         try:
             values = _apply_defaults(tmpl.field_schema, label_values)
-            image = render_template(tmpl, values)
+            image = render_template(tmpl, values, media_override=body.label_media)
             outcome = print_image(
                 image=image,
-                label_media=tmpl.label_media,
+                label_media=effective_media,
                 model=settings.printer_model,
                 backend=settings.printer_backend,
                 host=settings.printer_host,
@@ -247,7 +275,7 @@ async def batch_print(
             job_id = insert_job_with_preview(
                 image=image,
                 payload_json=BatchPrintRequest(labels=[label_values]).model_dump_json(),
-                label_media=tmpl.label_media,
+                label_media=effective_media,
                 template_name=name,
                 field_values=values,
                 batch_id=batch_id,
diff --git a/backend/tests/test_media_override.py b/backend/tests/test_media_override.py
new file mode 100644
index 0000000..283ec0d
--- /dev/null
+++ b/backend/tests/test_media_override.py
@@ -0,0 +1,217 @@
+"""Tests for print-time media override: render on a non-stored media, reprint
+binds to the history row's media, and overflow detection on die-cut targets.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from unittest.mock import patch
+
+from labelforge.models import LabelEntry, Template
+from PIL import Image
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+
+def _make_label(
+    id_: str,
+    *,
+    form_factor: int = 2,  # 2 = continuous
+    dots_printable: tuple[int, int] = (696, 0),
+    tape_size: tuple[int, int] = (62, 0),
+    color: int = 0,
+    supported: bool = True,
+) -> LabelEntry:
+    return LabelEntry(
+        id=id_,
+        display_name=id_,
+        dots_printable=dots_printable,
+        tape_size=tape_size,
+        form_factor=form_factor,
+        color=color,
+        supported=supported,
+    )
+
+
+def _make_template(label_media: str = "62red", canvas_json: dict | None = None) -> Template:
+    return Template(
+        name="test-tmpl",
+        display_name="Test Template",
+        label_media=label_media,
+        canvas_json=canvas_json or {"objects": []},
+        field_schema=[],
+        created_at="2026-01-01T00:00:00",
+        updated_at="2026-01-01T00:00:00",
+    )
+
+
+# ── render_template with media_override ───────────────────────────────────────
+
+
+def test_render_template_override_uses_effective_media():
+    """Rendering with media_override='62' (mono) should return an L-mode image."""
+    label_62red = _make_label("62red", color=1, form_factor=2)
+    label_62 = _make_label("62", color=0, form_factor=2)
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62red": label_62red, "62": label_62}.get(id_)
+
+    tmpl = _make_template(label_media="62red")
+
+    with patch("labelforge.render.template.get_label", side_effect=_get_label):
+        from labelforge.render.template import render_template
+
+        img = render_template(tmpl, {}, media_override="62")
+
+    assert img.mode == "L", "Mono override should produce a grayscale image"
+
+
+def test_render_template_no_override_is_unchanged():
+    """No override should behave as before (two-color template → RGB image)."""
+    label_62red = _make_label("62red", color=1, form_factor=2)
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62red": label_62red}.get(id_)
+
+    tmpl = _make_template(label_media="62red")
+
+    with patch("labelforge.render.template.get_label", side_effect=_get_label):
+        from labelforge.render.template import render_template
+
+        img = render_template(tmpl, {})
+
+    assert img.mode == "RGB", "Two-color template without override should produce RGB image"
+
+
+def test_render_template_override_die_cut_sizes_to_label():
+    """Rendering with a die-cut override sizes the canvas to the die-cut dimensions."""
+    label_62red = _make_label("62red", color=1, form_factor=2, dots_printable=(696, 0))
+    # 62x29 die-cut: 696 × 271 printable dots
+    label_62x29 = _make_label(
+        "62x29", color=0, form_factor=1, dots_printable=(696, 271), tape_size=(62, 29)
+    )
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62red": label_62red, "62x29": label_62x29}.get(id_)
+
+    tmpl = _make_template(label_media="62red")
+
+    with patch("labelforge.render.template.get_label", side_effect=_get_label):
+        from labelforge.render.template import render_template
+
+        img = render_template(tmpl, {}, media_override="62x29")
+
+    assert img.size == (696, 271), f"Expected (696, 271), got {img.size}"
+
+
+# ── detect_overflow ────────────────────────────────────────────────────────────
+
+
+def test_detect_overflow_continuous_never_overflows():
+    """Continuous media should never be reported as overflowing."""
+    label_62 = _make_label("62", form_factor=2, dots_printable=(696, 0))
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62": label_62}.get(id_)
+
+    # Template with an object that would overflow a die-cut
+    canvas = {"objects": [{"type": "Rect", "top": 0, "height": 5000, "scaleY": 1.0}]}
+    tmpl = _make_template(canvas_json=canvas)
+
+    with patch("labelforge.render.template.get_label", side_effect=_get_label):
+        from labelforge.render.template import detect_overflow
+
+        assert detect_overflow(tmpl, "62") is False
+
+
+def test_detect_overflow_die_cut_within_bounds():
+    """Content that fits within the die-cut should not be flagged."""
+    label_62x29 = _make_label("62x29", form_factor=1, dots_printable=(696, 271), tape_size=(62, 29))
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62x29": label_62x29}.get(id_)
+
+    canvas = {"objects": [{"type": "Rect", "top": 10, "height": 100, "scaleY": 1.0}]}
+    tmpl = _make_template(canvas_json=canvas)
+
+    with patch("labelforge.render.template.get_label", side_effect=_get_label):
+        from labelforge.render.template import detect_overflow
+
+        assert detect_overflow(tmpl, "62x29") is False
+
+
+def test_detect_overflow_die_cut_exceeds_bounds():
+    """Content extending past the die-cut height should be flagged."""
+    label_62x29 = _make_label("62x29", form_factor=1, dots_printable=(696, 271), tape_size=(62, 29))
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62x29": label_62x29}.get(id_)
+
+    # top=200 + height=200 = 400 > 271 printable dots
+    canvas = {"objects": [{"type": "Rect", "top": 200, "height": 200, "scaleY": 1.0}]}
+    tmpl = _make_template(canvas_json=canvas)
+
+    with patch("labelforge.render.template.get_label", side_effect=_get_label):
+        from labelforge.render.template import detect_overflow
+
+        assert detect_overflow(tmpl, "62x29") is True
+
+
+def test_detect_overflow_unknown_media_returns_false():
+    """Unknown media should not raise — return False."""
+    with patch("labelforge.render.template.get_label", return_value=None):
+        from labelforge.render.template import detect_overflow
+
+        tmpl = _make_template()
+        assert detect_overflow(tmpl, "nonexistent") is False
+
+
+# ── reprint uses history row's media ──────────────────────────────────────────
+
+
+def test_reprint_uses_row_media_not_template_media():
+    """_reprint_template should render on the history row's label_media, not
+    the template's stored label_media. This ensures one-off overrides at recall
+    time are reproduced faithfully on reprint.
+    """
+    label_62 = _make_label("62", color=0, form_factor=2)
+    label_62red = _make_label("62red", color=1, form_factor=2)
+
+    def _get_label(id_: str) -> LabelEntry | None:
+        return {"62": label_62, "62red": label_62red}.get(id_)
+
+    tmpl = _make_template(label_media="62red")  # template stored on 62red
+    row = {
+        "template_id": "test-tmpl",
+        "label_media": "62",  # was printed on mono 62
+        "field_values": json.dumps({}),
+        "payload_json": json.dumps({}),
+        "reprint_of": None,
+    }
+
+    calls: list[dict] = []
+
+    def _mock_render(template, values, *, media_override=None):
+        calls.append({"media_override": media_override})
+        # Return a tiny mono image so downstream code doesn't crash.
+        return Image.new("L", (10, 10), 255)
+
+    with (
+        patch("labelforge.routes.history.store") as mock_store,
+        patch("labelforge.routes.history.get_label", side_effect=_get_label),
+        patch("labelforge.routes.history.render_template", side_effect=_mock_render),
+        patch("labelforge.routes.history.print_image", return_value="sent"),
+        patch("labelforge.routes.history.insert_job_with_preview", return_value=99),
+    ):
+        mock_store.get_template.return_value = tmpl
+
+        from labelforge.routes.history import _reprint_template
+
+        result = asyncio.run(_reprint_template(99, row))
+
+    assert len(calls) == 1, "render_template should have been called once"
+    assert calls[0]["media_override"] == "62", (
+        "reprint should render on the history row's media ('62'), not the template's ('62red')"
+    )
+    assert result["reprint_of"] == 99
diff --git a/docs/decisions.md b/docs/decisions.md
index 0131869..fc7dbd9 100644
--- a/docs/decisions.md
+++ b/docs/decisions.md
@@ -4,6 +4,59 @@ Architecture Decision Records, newest at the top. Each entry: what we decided, w
 
 ---
 
+## 2026-06-06 — Print-time media override: one-off, warn-but-allow, red→black automatic, reprint binds to history
+
+**Decision**: A template can be printed on any supported media at recall time without mutating
+the stored template. The behavior:
+
+- **One-off, non-persistent**: the media choice applies to the current print/preview only.
+  `template.label_media` is never modified. Save As remains the way to permanently retarget
+  a design.
+- **Overflow on die-cut: warn but allow**: when the chosen media is a die-cut and content
+  extends beyond its printable height (`label.dots_printable[1]`), the preview response
+  returns `X-Label-Overflow: true` (header) and the print response includes `"overflow": true`
+  in the JSON body. The recall UI shows an inline warning. Printing is never blocked.
+- **Red → black on mono: automatic, no toggle**: the renderer's existing `_canvas_color_to_l`
+  already maps any non-white color (including red) to 0 (black). Choosing a mono media for
+  a two-color template requires no additional renderer work — the preview will show the result.
+  An inline notice in the recall UI informs the user.
+- **Reprint binds to the historical media**: `_reprint_template` now renders with
+  `media_override=row["label_media"]` (the row's actual print media) rather than
+  `tmpl.label_media`. This makes one-off overrides reproducible from history.
+
+**Supersedes**: the glossary rule "a template belongs to exactly one label media (a 62mm Spool
+template cannot be printed on a 29×90 die-cut)" — see `docs/glossary.md`. The spirit of the
+rule (Save As for persistent retargeting; editor media is immutable) is preserved. What changes
+is the recall path: a one-off override is now supported.
+
+**Why**: The same physical design (e.g. a spool label) fits on rolls of the same width but
+different geometries (continuous vs die-cut, different die-cut lengths). The user physically
+swaps rolls and the pre-print media compatibility check already guards mismatches. Blocking
+the print when geometry is close (same width, different length) is friction with no safety
+benefit — the preview shows the result before ink touches paper.
+
+**Why same-width-first grouping**: When the list of all media is shown unsorted, the user must
+scan to find the relevant alternatives. Same-width media share the design's coordinate system
+width and are the most natural substitutes. Surfacing them first addresses the "overwhelming
+list" concern without removing any option.
+
+**Considered**:
+- Block cross-width prints entirely — rejected; a 62mm design on 62x29 is the exact motivating
+  case (user has a die-cut roll loaded, wants the label to auto-crop). The warn path is safer.
+- A "save this media to the template" affordance — rejected; Save As already covers persistent
+  retargeting, and adding a second save path creates confusion about which one is canonical.
+- Recolor toggle for red→black (explicit opt-in) — rejected; the preview already shows the
+  result, and an automatic mapping is simpler. A notice informs the user.
+- Keep history logging the template's stored media — rejected; the historical row would then
+  be wrong (it logged a 62red print when a 62 roll was used), and reprint would reproduce
+  the wrong media.
+
+**Would revisit if**: a future override needs to be persistent without a full Save As (e.g.
+"set this media as the new default for the template") — at that point a dedicated endpoint
+or UI affordance would be appropriate.
+
+---
+
 ## 2026-06-05 — Release publish trigger: `release: published` replaces tag-push for production builds
 
 **Decision**: Removed the `tags: v*.*.*` trigger from `build-and-push.yml`. `release: published` is now the sole trigger for production image builds. The `push: branches: [main, dev]` trigger is retained for rolling dev/latest builds.
diff --git a/docs/features/templates.md b/docs/features/templates.md
index edd48ff..fed106e 100644
--- a/docs/features/templates.md
+++ b/docs/features/templates.md
@@ -24,7 +24,10 @@ The core feature. A template is a saved, named label design with a freeform canv
 
 ### Save As (clone with different label media)
 
-A template is locked to its label media. To re-use a design on a different media:
+A template's stored media can be permanently changed only via Save As. For a one-off print on
+different media, use the recall page's media selector instead (no new template created).
+
+To permanently re-use a design on a different media:
 
 1. Open template
 2. Click **Save As**
@@ -41,11 +44,25 @@ History rows referencing a deleted template keep their `template_id` and resolve
 ### Recall (print from template)
 
 1. From `/templates`, click **Print** on a template
-2. Form auto-generated from the template's field schema
-3. Required fields validated client-side and server-side
-4. **Preview** button → true preview reflecting filled values
-5. **Print** button → prints, logs to history
-6. **Batch** toggle → see [`templates - batch`](#batch--increment) below
+2. **Media selector** — pick which label media to print on (default: the template's stored media).
+   Same-width media are listed first (most likely to fit the design). A "Loaded in printer"
+   toggle narrows the list to the roll currently mounted (fetches printer status once). This is
+   a one-off choice — the stored template media is never mutated.
+3. **Mono + red notice** — if the template contains red elements and the chosen media is
+   mono (single-color), an inline notice explains that red will print as black. The renderer
+   automatically maps red → black; no toggle is needed.
+4. Form auto-generated from the template's field schema
+5. Required fields validated client-side and server-side
+6. **Preview** button → true preview reflecting filled values on the chosen media. The Print
+   button is gated until a fresh preview has been taken after any media change.
+7. **Overflow warning** — if the chosen media is a die-cut and content extends beyond its
+   printable height, an inline warning appears ("Content may be clipped"). Printing still
+   proceeds; the user decides from the preview.
+8. **Print** button → prints on the chosen media, logs to history with the chosen media.
+9. **Batch** toggle → see [`templates - batch`](#batch--increment) below
+
+One-off media overrides are captured in history with the actual printed media. Reprinting a
+history row reproduces the original media choice, not the template's stored media.
 
 ## Data model
 
diff --git a/docs/glossary.md b/docs/glossary.md
index d4bb5b7..c70e6e5 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -14,7 +14,9 @@ The merged set of available label media — library's printable list intersected
 
 ### Template
 
-A saved, named label design. Belongs to exactly one label media (a 62mm Spool template cannot be printed on a 29×90 die-cut). Contains an ordered list of elements and an auto-derived field schema. Identified by a slug-like name (`spool`, `file-folder`, `box`).
+A saved, named label design. Has a *default/home* label media stored with it, but can be printed on a different compatible media at recall time (one-off — the stored media is never mutated). The recall page lets the user pick any supported media; same-width options appear first. Contains an ordered list of elements and an auto-derived field schema. Identified by a slug-like name (`spool`, `file-folder`, `box`).
+
+See also: **Save As** (the way to permanently retarget a design to a new media), **Print-time media override** (the one-off recall path).
 
 ### Element
 
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 6493dab..00eb27d 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -134,20 +134,26 @@ export function getLastValues(name: string): Promise<TemplateLastValues> {
   return apiFetch<TemplateLastValues>(`/api/templates/${encodeURIComponent(name)}/last-values`)
 }
 
-export async function previewTemplate(name: string, fields: Record<string, string>): Promise<Blob> {
+export async function previewTemplate(
+  name: string,
+  fields: Record<string, string>,
+  labelMedia?: string,
+): Promise<{ blob: Blob; overflow: boolean }> {
+  const body: Record<string, unknown> = { fields }
+  if (labelMedia !== undefined) body.label_media = labelMedia
   const res = await fetch(`/api/preview/${encodeURIComponent(name)}`, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${getToken()}`,
     },
-    body: JSON.stringify({ fields }),
+    body: JSON.stringify(body),
   })
   if (!res.ok) {
     let detail = `HTTP ${res.status}`
     try {
-      const body = await res.json() as { detail?: unknown }
-      const d = body.detail
+      const errBody = await res.json() as { detail?: unknown }
+      const d = errBody.detail
       if (typeof d === 'string') {
         detail = d
       } else if (d && typeof d === 'object' && typeof (d as { message?: unknown }).message === 'string') {
@@ -159,20 +165,33 @@ export async function previewTemplate(name: string, fields: Record<string, strin
     } catch { /* use status fallback */ }
     throw new Error(detail)
   }
-  return res.blob()
+  const overflow = res.headers.get('X-Label-Overflow') === 'true'
+  return { blob: await res.blob(), overflow }
 }
 
-export function printTemplate(name: string, fields: Record<string, string>): Promise<PrintJobResponse> {
+export function printTemplate(
+  name: string,
+  fields: Record<string, string>,
+  labelMedia?: string,
+): Promise<PrintJobResponse> {
+  const body: Record<string, unknown> = { fields }
+  if (labelMedia !== undefined) body.label_media = labelMedia
   return apiFetch<PrintJobResponse>(`/api/print/${encodeURIComponent(name)}`, {
     method: 'POST',
-    body: JSON.stringify({ fields }),
+    body: JSON.stringify(body),
   })
 }
 
-export function batchPrint(name: string, labels: Record<string, string>[]): Promise<BatchPrintResponse> {
+export function batchPrint(
+  name: string,
+  labels: Record<string, string>[],
+  labelMedia?: string,
+): Promise<BatchPrintResponse> {
+  const body: Record<string, unknown> = { labels }
+  if (labelMedia !== undefined) body.label_media = labelMedia
   return apiFetch<BatchPrintResponse>(`/api/print/${encodeURIComponent(name)}/batch`, {
     method: 'POST',
-    body: JSON.stringify({ labels }),
+    body: JSON.stringify(body),
   })
 }
 
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index a2ad4c8..0e1e919 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -252,7 +252,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
       }
       // Build a fields dict: use field name as its own placeholder value for preview
       const fields: Record<string, string> = {}
-      const blob = await previewTemplate(name, fields)
+      const { blob } = await previewTemplate(name, fields)
       if (previewObjectUrl) URL.revokeObjectURL(previewObjectUrl)
       previewObjectUrl = URL.createObjectURL(blob)
       previewImg.src = previewObjectUrl
diff --git a/frontend/src/pages/template-recall.ts b/frontend/src/pages/template-recall.ts
index 6e345b2..f3568ca 100644
--- a/frontend/src/pages/template-recall.ts
+++ b/frontend/src/pages/template-recall.ts
@@ -1,5 +1,6 @@
-import { batchPrint, getLastValues, getTemplate, previewTemplate, printTemplate } from '../api'
-import type { FieldSpec, Template, TemplateLastValues } from '../types'
+import { batchPrint, getLabels, getLastValues, getTemplate, previewTemplate, printTemplate } from '../api'
+import type { FieldSpec, LabelEntry, Template, TemplateLastValues } from '../types'
+import { mountLabelMediaSelect } from '../labels'
 import { navigate } from '../router'
 
 function fmtDate(iso: string): string {
@@ -32,6 +33,53 @@ function nameFromPath(): string {
   return decodeURIComponent(parts[1] ?? '')
 }
 
+/** True when any canvas object uses a red fill or stroke color. */
+function templateHasRed(tpl: Template): boolean {
+  const redValues = new Set(['#ff0000', '#f00', 'red', 'rgb(255,0,0)'])
+  const objects = (tpl.canvas_json?.objects ?? []) as Array<Record<string, unknown>>
+  for (const obj of objects) {
+    const fill = (obj.fill as string | undefined)?.toLowerCase().trim() ?? ''
+    const stroke = (obj.stroke as string | undefined)?.toLowerCase().trim() ?? ''
+    if (redValues.has(fill) || redValues.has(stroke)) return true
+  }
+  return false
+}
+
+/** Group labels: same-width-as-template first, then all others. */
+function partitionByWidth(labels: LabelEntry[], templateWidthMm: number): { sameWidth: LabelEntry[]; other: LabelEntry[] } {
+  const sameWidth: LabelEntry[] = []
+  const other: LabelEntry[] = []
+  for (const l of labels) {
+    if (l.tape_size[0] === templateWidthMm) {
+      sameWidth.push(l)
+    } else {
+      other.push(l)
+    }
+  }
+  return { sameWidth, other }
+}
+
+/** Build optgroup HTML for the grouped recall media selector.
+ *
+ * Same-width media appear first (most likely to fit without clipping).
+ * Within each group, only supported media are selectable.
+ */
+function buildRecallOptionsHtml(sameWidth: LabelEntry[], other: LabelEntry[], widthMm: number): string {
+  function renderOpt(l: LabelEntry): string {
+    const text = l.brother_part ? `${l.brother_part}: ${l.display_name}` : l.display_name
+    if (l.supported) {
+      return `<option value="${esc(l.id)}">${esc(text)}</option>`
+    }
+    const reason = l.incompatible_reason ?? 'Not supported by the configured printer'
+    return `<option value="${esc(l.id)}" disabled title="${esc(reason)}">${esc(text)} — unavailable</option>`
+  }
+  const sw = sameWidth.map(renderOpt).join('')
+  const ot = other.map(renderOpt).join('')
+  const swLabel = `Same width (${widthMm}mm)`
+  return (sw ? `<optgroup label="${esc(swLabel)}">${sw}</optgroup>` : '') +
+         (ot ? `<optgroup label="Other media">${ot}</optgroup>` : '')
+}
+
 export function mountTemplateRecall(root: HTMLElement): void {
   const name = nameFromPath()
   root.innerHTML = `<div class="template-recall"><p>Loading…</p></div>`
@@ -39,8 +87,9 @@ export function mountTemplateRecall(root: HTMLElement): void {
   Promise.all([
     getTemplate(name),
     getLastValues(name).catch(() => ({ values: null, printed_at: null } satisfies TemplateLastValues)),
+    getLabels(),
   ])
-    .then(([tpl, lastVals]) => renderRecall(root, tpl, lastVals))
+    .then(([tpl, lastVals, allLabels]) => renderRecall(root, tpl, lastVals, allLabels))
     .catch((err: Error) => {
       root.innerHTML = `
         <div class="template-recall">
@@ -55,19 +104,33 @@ export function mountTemplateRecall(root: HTMLElement): void {
     })
 }
 
-function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastValues): void {
+function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastValues, allLabels: LabelEntry[]): void {
   const fields = tpl.field_schema ?? []
   const hasFields = fields.length > 0
   const incrementFields = fields.filter(f => f.increment)
   const canBatch = incrementFields.length > 0
+  const hasRed = templateHasRed(tpl)
+
+  // Only supported media in the selector
+  const supportedLabels = allLabels.filter(l => l.supported)
+
+  // Find template's label width for grouping
+  const tplLabel = allLabels.find(l => l.id === tpl.label_media)
+  const tplWidthMm = tplLabel?.tape_size[0] ?? 0
 
   root.innerHTML = `
     <div class="template-recall">
       <a href="#" class="back-link" id="back-link">← Templates</a>
       <h2>${esc(tpl.display_name || tpl.name)}</h2>
-      <p class="recall-meta">Media: <code>${esc(tpl.label_media)}</code></p>
       <div id="status-msg" class="status-msg" hidden></div>
 
+      <div class="recall-media-selector">
+        <p class="recall-meta">Print media (default: <code>${esc(tpl.label_media)}</code>):</p>
+        <div id="media-selector-container"></div>
+        <p id="mono-red-notice" class="recall-notice info" hidden>This label is black-only — red elements will print in black.</p>
+        <p id="overflow-notice" class="recall-notice warn" hidden>Content may be clipped — it's taller than this label.</p>
+      </div>
+
       <form id="recall-form" autocomplete="off">
         ${hasFields ? fields.map(fieldInput).join('') : '<p class="recall-meta">This template has no variable fields.</p>'}
 
@@ -88,7 +151,7 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
         <div class="actions">
           ${hasFields ? `<button type="button" id="btn-load-prev"${lastVals.values ? '' : ' disabled'}>Load previous values${lastVals.printed_at ? ` (${fmtDate(lastVals.printed_at)})` : ''}</button>` : ''}
           <button type="button" id="btn-preview">Preview</button>
-          <button type="submit" id="btn-print">Print</button>
+          <button type="submit" id="btn-print" disabled>Print</button>
         </div>
       </form>
 
@@ -108,9 +171,15 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
   const batchEnable = root.querySelector<HTMLInputElement>('#batch-enable')
   const batchOpts = root.querySelector<HTMLDivElement>('#batch-opts')
   const batchCount = root.querySelector<HTMLInputElement>('#batch-count')
+  const monoRedNotice = root.querySelector<HTMLParagraphElement>('#mono-red-notice')!
+  const overflowNotice = root.querySelector<HTMLParagraphElement>('#overflow-notice')!
+  const mediaSelectorContainer = root.querySelector<HTMLDivElement>('#media-selector-container')!
 
   let previewObjectUrl: string | null = null
   let debounceTimer: number | undefined
+  // True when the selected media has changed since the last preview was run.
+  // Print is blocked until a fresh preview confirms the user has seen the output.
+  let previewStale = false
 
   root.querySelector('#back-link')!.addEventListener('click', e => {
     e.preventDefault()
@@ -141,7 +210,86 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
   }
 
   function updateButtons(): void {
-    btnPrint.disabled = missingRequired()
+    // Print requires: all required fields filled AND a fresh preview after any media change.
+    btnPrint.disabled = missingRequired() || previewStale
+  }
+
+  // Wire the reusable label-media selector with same-width-first grouping.
+  // We build the HTML directly rather than using buildLabelOptionsHtml so we can
+  // inject custom optgroups. The toggle (Show all / Loaded in printer) comes from
+  // mountLabelMediaSelect, but the option content is replaced after mount via the
+  // handle — simpler to just override innerHTML of the inner <select> element.
+  //
+  // Chosen approach: mount with all supported labels (provides the toggle machinery),
+  // then immediately replace option content with our grouped version.
+  const mediaHandle = mountLabelMediaSelect({
+    container: mediaSelectorContainer,
+    labels: supportedLabels,
+    initialValue: tpl.label_media,
+    onChange: (id: string) => {
+      onMediaChange(id)
+    },
+  })
+
+  // Replace the option content with same-width-first grouping, preserving current value.
+  const innerSelect = mediaSelectorContainer.querySelector<HTMLSelectElement>('.media-filter-select')!
+  function repopulateGrouped(list: LabelEntry[]): void {
+    const { sameWidth: sw, other: ot } = partitionByWidth(list, tplWidthMm)
+    innerSelect.innerHTML = buildRecallOptionsHtml(sw, ot, tplWidthMm)
+    // Restore the current value if still available; otherwise fall to first supported
+    if (mediaHandle.getValue() && innerSelect.querySelector(`option[value="${CSS.escape(mediaHandle.getValue())}"]`)) {
+      innerSelect.value = mediaHandle.getValue()
+    } else {
+      const first = innerSelect.querySelector<HTMLOptionElement>('option:not([disabled])')
+      if (first) innerSelect.value = first.value
+    }
+  }
+  repopulateGrouped(supportedLabels)
+
+  // Patch the "Show all" toggle to also rebuild with grouping.
+  // We can't override mountLabelMediaSelect internals, so we intercept via the
+  // select's change event (which fires after mountLabelMediaSelect updates it).
+  // The simplest robust approach: re-run grouping whenever the mode toggle fires.
+  const toggleBtns = mediaSelectorContainer.querySelectorAll<HTMLButtonElement>('.media-filter-btn')
+  toggleBtns.forEach(btn => {
+    // Add a second listener that runs after the one mounted by mountLabelMediaSelect.
+    btn.addEventListener('click', () => {
+      // Allow mountLabelMediaSelect's listener to run first (same tick), then regroup.
+      window.setTimeout(() => {
+        // Collect whichever labels are now visible (all or filtered) from the current options.
+        const visibleIds = new Set(
+          Array.from(innerSelect.options).map(o => o.value)
+        )
+        const visibleLabels = supportedLabels.filter(l => visibleIds.has(l.id))
+        repopulateGrouped(visibleLabels)
+      }, 0)
+    })
+  })
+
+  function getCurrentMedia(): string {
+    return innerSelect.value || tpl.label_media
+  }
+
+  function onMediaChange(id: string): void {
+    // Update mono+red notice
+    const label = supportedLabels.find(l => l.id === id)
+    const isMono = label ? label.color === 0 : true
+    monoRedNotice.hidden = !(hasRed && isMono)
+
+    // Mark preview as stale — force user to preview before printing.
+    previewStale = true
+    overflowNotice.hidden = true
+    updateButtons()
+
+    // Immediately trigger preview so the user sees the new layout.
+    window.clearTimeout(debounceTimer)
+    debounceTimer = window.setTimeout(() => runPreview(), 0)
+  }
+
+  // Initialize notice state for the template's default media
+  const initialLabel = supportedLabels.find(l => l.id === tpl.label_media)
+  if (initialLabel && hasRed && initialLabel.color === 0) {
+    monoRedNotice.hidden = false
   }
 
   function buildBatchLabels(): Record<string, string>[] {
@@ -164,12 +312,19 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
     if (missingRequired()) return
     btnPreview.disabled = true
     hideStatus()
-    previewTemplate(tpl.name, collectFields())
-      .then(blob => {
+    const chosenMedia = getCurrentMedia()
+    // Only pass label_media override when it differs from the template's stored media.
+    const mediaOverride = chosenMedia !== tpl.label_media ? chosenMedia : undefined
+    previewTemplate(tpl.name, collectFields(), mediaOverride)
+      .then(({ blob, overflow }) => {
         if (previewObjectUrl) URL.revokeObjectURL(previewObjectUrl)
         previewObjectUrl = URL.createObjectURL(blob)
         previewImg.src = previewObjectUrl
         previewArea.hidden = false
+        overflowNotice.hidden = !overflow
+        // Preview is fresh — allow printing.
+        previewStale = false
+        updateButtons()
       })
       .catch((err: Error) => showStatus(err.message, 'error'))
       .finally(() => { btnPreview.disabled = false })
@@ -210,19 +365,25 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
       showStatus('Fill all required fields before printing.', 'error')
       return
     }
+    if (previewStale) {
+      showStatus('Preview the label with the selected media before printing.', 'error')
+      return
+    }
     btnPrint.disabled = true
     hideStatus()
+    const chosenMedia = getCurrentMedia()
+    const mediaOverride = chosenMedia !== tpl.label_media ? chosenMedia : undefined
     try {
       if (batchEnable?.checked) {
-        const labels = buildBatchLabels()
-        const result = await batchPrint(tpl.name, labels)
+        const batchLabels = buildBatchLabels()
+        const result = await batchPrint(tpl.name, batchLabels, mediaOverride)
         const kind = result.failed > 0 ? 'error' : 'success'
         showStatus(
-          `Batch ${result.batch_id}: ${result.succeeded} sent, ${result.failed} failed (${labels.length} requested). "Sent" means transmitted to the printer; delivery is not confirmed.`,
+          `Batch ${result.batch_id}: ${result.succeeded} sent, ${result.failed} failed (${batchLabels.length} requested). "Sent" means transmitted to the printer; delivery is not confirmed.`,
           kind,
         )
       } else {
-        const result = await printTemplate(tpl.name, collectFields())
+        const result = await printTemplate(tpl.name, collectFields(), mediaOverride)
         showStatus(
           `Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`,
           'success',
diff --git a/frontend/src/style.css b/frontend/src/style.css
index 3d763db..a3ef58a 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -688,3 +688,32 @@ button:disabled {
   font: inherit;
   margin-bottom: 0.5rem;
 }
+
+/* recall page — media selector section */
+.recall-media-selector {
+  margin-bottom: 1rem;
+}
+
+.recall-media-selector .recall-meta {
+  margin-bottom: 0.35rem;
+}
+
+/* inline recall notices (mono+red, overflow) */
+.recall-notice {
+  font-size: 0.82rem;
+  border-radius: 3px;
+  padding: 0.3rem 0.55rem;
+  margin: 0.4rem 0 0;
+}
+
+.recall-notice.warn {
+  color: #8a5a00;
+  background: #fff7e6;
+  border: 1px solid #f0d8a0;
+}
+
+.recall-notice.info {
+  color: #2855a0;
+  background: #f0f4ff;
+  border: 1px solid #c0d0f0;
+}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index cdb0be1..0ab8a2c 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -43,6 +43,7 @@ export interface PrintJobResponse {
   job_id: number;
   status: string;
   preview_url: string | null;
+  overflow?: boolean;
 }
 
 export interface BatchJobResult {
diff --git a/prompts/done/2026-06-06-print-time-media-override.md b/prompts/done/2026-06-06-print-time-media-override.md
new file mode 100644
index 0000000..738d1df
--- /dev/null
+++ b/prompts/done/2026-06-06-print-time-media-override.md
@@ -0,0 +1,156 @@
+---
+name: 2026-06-06-print-time-media-override
+status: completed
+created: 2026-06-06
+model: sonnet            # opus = research/planning, sonnet = coding
+completed: 2026-06-06
+result: Print-time media override: recall page media selector, mono+red notice, overflow warning, reprint binds to history row media; 8 new backend tests; all green.
+---
+
+# Task: Print a template on a different label media at print time
+
+Let the user choose a **different label media when printing a template** (one-off, the
+template's stored media is never mutated). Covers the real case: a design saved on `62red`
+(62mm two-color continuous) that the user also wants to print on `62x29` (DK-1209, 62mm
+die-cut). When the chosen media is mono and the template uses red, red prints as black —
+surface that. When the chosen media is smaller and content overflows, warn but allow.
+Changing the media forces a fresh preview so the user can see whether it fits.
+
+This **overturns a documented design rule** — the glossary currently says *"a template
+belongs to exactly one label media (a 62mm Spool template cannot be printed on a 29×90
+die-cut)."* Updating that rule + an ADR is part of this task.
+
+## Before you start
+
+- Read `docs/features/templates.md` (recall/print + "Save As" sections), `docs/glossary.md`
+  (Template / Label media entries — the rule you're changing), `docs/features/label-catalog.md`,
+  and `docs/decisions.md` (newest ADRs).
+- Load these implementation anchors:
+  - `backend/labelforge/render/template.py` — `render_template(template, values)` reads
+    `template.label_media`. Note `_canvas_color_to_l` already maps **any non-white color
+    (incl. red) → 0 (black)**, so mono rendering of a red template already prints red as
+    black. No renderer recolor work is needed for "print in black."
+  - `backend/labelforge/routes/template_print.py` — `print_template` / `preview_template`
+    (+ batch); uses `tmpl.label_media` for render, the `media_compatible` status check, and
+    history logging.
+  - `backend/labelforge/routes/history.py` — `_reprint_template` (see the reprint fix below).
+  - `backend/labelforge/models/__init__.py` — `PrintRequest` (`fields`), `BatchPrintRequest`.
+  - `frontend/src/labels.ts` — **reusable** label-media selector with the "Show all / Loaded
+    in printer" toggle and `matchesLoadedMedia()`. **Reuse it** on recall; do not build a new
+    one.
+  - `frontend/src/pages/template-recall.ts` — the recall page (read-only `Media:` badge at
+    ~line 68; preview wiring `runPreview`/debounce ~line 167+).
+- One-off only (per owner): the choice applies to this print/preview; the stored template is
+  untouched. History captures the actual media, and reprint reproduces it (below) — that's
+  the "recall from history" path. Do **not** add a "save this media to the template" affordance
+  (Save As already covers persistent retargeting).
+- Ships **before** the 0.1.0 release — `/release-prep` waits for this. Work on `dev`.
+
+## Working tree check
+
+`git status --porcelain` first. This touches `render/template.py`, `routes/template_print.py`,
+`routes/history.py`, `models/__init__.py`, `frontend/src/pages/template-recall.ts`,
+`frontend/src/labels.ts` (and maybe `api.ts`/`types.ts`), plus docs. If any show unexpected
+uncommitted changes, list them and ask.
+
+## What to do — backend
+
+1. **Models**: add `label_media: str | None = None` to `PrintRequest` and
+   `BatchPrintRequest`. `None` = use the template's stored media (unchanged behavior).
+
+2. **Renderer**: give `render_template` an effective-media override. Recommended signature:
+   `render_template(template, values, *, media_override: str | None = None)`. Internally
+   resolve `effective_media = media_override or template.label_media` and `get_label(...)`
+   on that. Everything downstream (canvas width, continuous-vs-die-cut, `two_color`) keys off
+   the resolved label, **not** `template.label_media`. Keep the default-None path byte-for-byte
+   equivalent to today.
+
+3. **Print / preview / batch routes** (`template_print.py`): when `body.label_media` is set:
+   - Validate it's a real, **supported** catalog entry (`get_label` non-None and
+     `.supported`); 400 otherwise.
+   - Render with `media_override=body.label_media`.
+   - Run the existing printer `media_compatible` status check against the **chosen** media,
+     not `tmpl.label_media` (same 409 + `override=true` escape hatch as today).
+   - Log history with the chosen media as `label_media` (so the row reflects what was printed).
+   - The print JSON response already returns `label_media` — make sure it returns the chosen one.
+
+4. **Overflow detection (warn, never block)**: for a **die-cut** effective media, detect when
+   rendered content extends beyond the label's printable height (compare the content's
+   bottommost extent to `label.dots_printable[1]`). Surface it without blocking:
+   - `preview_template` returns an image `Response` — add a response header
+     `X-Label-Overflow: true` when content overflows (the recall UI reads it).
+   - `print_template` (JSON) — add `"overflow": true/false` to the response body.
+   Continuous media never overflows (length is content-driven). Do not raise; printing still
+   proceeds — the user decides from the preview.
+
+5. **Reprint honors historical media** (`history.py` `_reprint_template`): it currently renders
+   with `tmpl.label_media`. Change it to render on the **row's** media:
+   `render_template(tmpl, field_values, media_override=row["label_media"])`, and keep the
+   existing "label media no longer in catalog" guard pointed at `row["label_media"]`. This is
+   what makes a one-off media print reproducible from history (the owner's "recall in history"
+   path). Mono+red reprints naturally re-derive red→black via the renderer.
+
+## What to do — frontend (recall page)
+
+6. **Media selector** replacing the read-only badge: render the reusable selector from
+   `labels.ts`, defaulting to the template's media. Address the owner's "the full list is
+   overwhelming" concern:
+   - **Group/sort same-width-as-template first** (compare `tape_size[0]`), e.g. an optgroup
+     "Same width (62mm)" above an "Other media" group, so the relevant rows are at the top.
+   - Keep the existing **"Loaded in printer"** toggle (queries `GET /api/printer/status` once,
+     narrows to the mounted roll via `matchesLoadedMedia`) — this is the fastest path to "what's
+     actually in the printer right now."
+   - Only list `supported` media.
+
+7. **Force preview on media change**: when the selected media changes, immediately run the
+   preview and reveal the preview area. Gate the **Print** button so it can't fire on a media
+   the user hasn't previewed since changing it (e.g. mark preview stale on change; require a
+   fresh preview first). Pass `label_media` in the preview/print/batch API calls.
+
+8. **Mono + red notice**: if the selected media is mono (`color === 0`) and the template
+   contains any red element (scan `canvas_json` objects for a red `fill`/`stroke` —
+   `#ff0000`/`#f00`/`red`/`rgb(255,0,0)`; a small helper mirroring the backend's red set is
+   fine), show an inline notice: *"This label is black-only — red elements will print in
+   black."* The forced preview already shows this (renderer maps red→black on mono). No toggle
+   needed; proceeding is printing in black.
+
+9. **Overflow warning**: when preview returns `X-Label-Overflow: true`, show an inline
+   *"Content may be clipped — it's taller than this label"* warning near the preview. Still
+   allow Print.
+
+10. **Batch parity**: pass the chosen `label_media` through the batch path too, so increment
+    prints honor the override.
+
+## Conventions to honor
+
+- LF endings. Match existing recall-page style; reuse `labels.ts` rather than duplicating
+  selector logic. Comments only for non-obvious *why*.
+- **Docs (ship with the code):**
+  - `docs/glossary.md` — revise the Template entry: a template has a *default/home* media but
+    can be printed on another compatible media at print time (one-off); the stored media is
+    unchanged. Fix the "cannot be printed on a 29×90 die-cut" line.
+  - `docs/features/templates.md` — document the recall media selector, the mono+red notice,
+    the overflow warning, and that one-off media is captured in history + reproduced on reprint.
+- **Changelog**: `### Added` under `## [Unreleased]` — print a template on a different label
+  media at recall time (one-off); same-width media surfaced first + "Loaded in printer" filter;
+  mono+red prints in black with a notice; smaller media warns about clipping but still prints;
+  the choice is logged to history and honored on reprint. Note the container-rebuild requirement.
+
+## When done
+
+1. Verify green: `ruff check . && ruff format --check . && mypy backend && pytest -q`; add a
+   backend test for the override (render on a non-stored media; reprint uses `row.label_media`;
+   overflow flag on a die-cut). Build the frontend (`npm run build`) so the recall changes
+   compile. Manually confirm: pick `62x29` on a `62red` template → forced preview + clip
+   warning; pick a mono `62` → red-as-black notice. Give the one-line "run this to verify".
+2. Update this file's frontmatter (`status`, `completed` = 2026-06-06, `result`).
+3. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+4. **ADR in `docs/decisions.md`**: print-time media override — one-off (non-persistent),
+   warn-but-allow on die-cut overflow, red→black automatic on mono (no toggle), reprint binds
+   to the historical media. Record that this supersedes the glossary "one template = one media"
+   rule, and why (same physical width makes a design portable across length/geometry; the user
+   physically swaps rolls and the pre-print media check + override already guard mismatches).
+5. Propose ONE commit covering backend, frontend, docs, changelog, ADR, tests, and this prompt
+   move. Present the file list and a one-line message; ask
+   `commit these as "feat: print a template on a different label media at print time"? (y/n)`.
+   On `y`, stage those specific paths (never `git add -A`) and commit on `dev`. Never push.

From ccc8e779b60f57471794aa945535ca31f3f84c8a Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 08:35:10 -0700
Subject: [PATCH 75/84] fix: default recall media to the template's own media;
 offer override on loaded-roll mismatch

---
 CHANGELOG.md                          |  9 +++--
 frontend/src/api.ts                   | 21 ++++++++++--
 frontend/src/pages/template-recall.ts | 47 +++++++++++++++++++--------
 3 files changed, 58 insertions(+), 19 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad4fa55..5b595be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,12 +7,15 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 ### Added
 
 - **Print a template on a different label media at recall time (one-off)** — the recall page
-  now shows a media selector instead of a read-only badge. Same-width media appear first
+  now shows a media selector instead of a read-only badge, defaulting to the template's own
+  media (e.g. a two-color template defaults to `62red`). Same-width media appear first
   (most likely to fit the design without adjustment); a "Loaded in printer" toggle narrows
   the list to the roll currently mounted. The stored template media is never mutated. The
   chosen media is logged to history and reproduced faithfully on reprint. The Print button is
-  gated until a fresh preview has been taken after any media change. Requires a container
-  image rebuild.
+  gated until a fresh preview has been taken after any media change. If the chosen media
+  doesn't match the roll actually loaded, the printer-status check still blocks with a 409,
+  but the recall page now offers a "print anyway" confirmation to override it. Requires a
+  container image rebuild.
 - **Mono + red notice on recall** — when a template contains red elements and a mono
   (single-color) media is selected, an inline notice explains that red will print in black.
   The renderer already maps red → black automatically; no action is needed.
diff --git a/frontend/src/api.ts b/frontend/src/api.ts
index 00eb27d..36df9f1 100644
--- a/frontend/src/api.ts
+++ b/frontend/src/api.ts
@@ -2,6 +2,15 @@ import type { BatchPrintResponse, FontInfo, HistoryDetail, HistoryItem, LabelEnt
 
 export const TOKEN_KEY = 'labelforge_token'
 
+// Carries HTTP status and whether a 409 (e.g. media mismatch) can be retried with
+// override=true, so callers can offer a "print anyway" path.
+export class ApiError extends Error {
+  constructor(message: string, public status: number, public overrideAllowed: boolean) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
 function getToken(): string {
   return localStorage.getItem(TOKEN_KEY) ?? ''
 }
@@ -36,6 +45,7 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
   })
   if (!res.ok) {
     let detail = `HTTP ${res.status}`
+    let overrideAllowed = false
     try {
       const body = await res.json() as { detail?: unknown }
       const d = body.detail
@@ -44,11 +54,12 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
       } else if (d && typeof d === 'object' && typeof (d as { message?: unknown }).message === 'string') {
         // structured errors (e.g. 409 media_mismatch / printer_error) carry a human message
         detail = (d as { message: string }).message
+        if ((d as { override_allowed?: unknown }).override_allowed === true) overrideAllowed = true
       } else if (d != null) {
         detail = JSON.stringify(d)
       }
     } catch { /* use status fallback */ }
-    throw new Error(detail)
+    throw new ApiError(detail, res.status, overrideAllowed)
   }
   if (res.status === 204) return undefined as T
   return res.json() as Promise<T>
@@ -173,10 +184,12 @@ export function printTemplate(
   name: string,
   fields: Record<string, string>,
   labelMedia?: string,
+  override?: boolean,
 ): Promise<PrintJobResponse> {
   const body: Record<string, unknown> = { fields }
   if (labelMedia !== undefined) body.label_media = labelMedia
-  return apiFetch<PrintJobResponse>(`/api/print/${encodeURIComponent(name)}`, {
+  const qs = override ? '?override=true' : ''
+  return apiFetch<PrintJobResponse>(`/api/print/${encodeURIComponent(name)}${qs}`, {
     method: 'POST',
     body: JSON.stringify(body),
   })
@@ -186,10 +199,12 @@ export function batchPrint(
   name: string,
   labels: Record<string, string>[],
   labelMedia?: string,
+  override?: boolean,
 ): Promise<BatchPrintResponse> {
   const body: Record<string, unknown> = { labels }
   if (labelMedia !== undefined) body.label_media = labelMedia
-  return apiFetch<BatchPrintResponse>(`/api/print/${encodeURIComponent(name)}/batch`, {
+  const qs = override ? '?override=true' : ''
+  return apiFetch<BatchPrintResponse>(`/api/print/${encodeURIComponent(name)}/batch${qs}`, {
     method: 'POST',
     body: JSON.stringify(body),
   })
diff --git a/frontend/src/pages/template-recall.ts b/frontend/src/pages/template-recall.ts
index f3568ca..954d84c 100644
--- a/frontend/src/pages/template-recall.ts
+++ b/frontend/src/pages/template-recall.ts
@@ -1,4 +1,4 @@
-import { batchPrint, getLabels, getLastValues, getTemplate, previewTemplate, printTemplate } from '../api'
+import { ApiError, batchPrint, getLabels, getLastValues, getTemplate, previewTemplate, printTemplate } from '../api'
 import type { FieldSpec, LabelEntry, Template, TemplateLastValues } from '../types'
 import { mountLabelMediaSelect } from '../labels'
 import { navigate } from '../router'
@@ -222,7 +222,7 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
   //
   // Chosen approach: mount with all supported labels (provides the toggle machinery),
   // then immediately replace option content with our grouped version.
-  const mediaHandle = mountLabelMediaSelect({
+  mountLabelMediaSelect({
     container: mediaSelectorContainer,
     labels: supportedLabels,
     initialValue: tpl.label_media,
@@ -231,20 +231,22 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
     },
   })
 
-  // Replace the option content with same-width-first grouping, preserving current value.
+  // Replace the option content with same-width-first grouping, preserving a desired value.
+  // Note: setting innerHTML resets the <select> value, so the caller must pass the value to
+  // keep (captured BEFORE this runs) — reading the select here would see the post-wipe reset.
   const innerSelect = mediaSelectorContainer.querySelector<HTMLSelectElement>('.media-filter-select')!
-  function repopulateGrouped(list: LabelEntry[]): void {
+  function repopulateGrouped(list: LabelEntry[], desiredValue: string): void {
     const { sameWidth: sw, other: ot } = partitionByWidth(list, tplWidthMm)
     innerSelect.innerHTML = buildRecallOptionsHtml(sw, ot, tplWidthMm)
-    // Restore the current value if still available; otherwise fall to first supported
-    if (mediaHandle.getValue() && innerSelect.querySelector(`option[value="${CSS.escape(mediaHandle.getValue())}"]`)) {
-      innerSelect.value = mediaHandle.getValue()
+    if (desiredValue && innerSelect.querySelector(`option[value="${CSS.escape(desiredValue)}"]`)) {
+      innerSelect.value = desiredValue
     } else {
       const first = innerSelect.querySelector<HTMLOptionElement>('option:not([disabled])')
       if (first) innerSelect.value = first.value
     }
   }
-  repopulateGrouped(supportedLabels)
+  // Default to the template's own media (e.g. a red template defaults to 62red).
+  repopulateGrouped(supportedLabels, tpl.label_media)
 
   // Patch the "Show all" toggle to also rebuild with grouping.
   // We can't override mountLabelMediaSelect internals, so we intercept via the
@@ -261,7 +263,8 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
           Array.from(innerSelect.options).map(o => o.value)
         )
         const visibleLabels = supportedLabels.filter(l => visibleIds.has(l.id))
-        repopulateGrouped(visibleLabels)
+        // Preserve the selection the toggle just produced (capture before regroup wipes it).
+        repopulateGrouped(visibleLabels, innerSelect.value)
       }, 0)
     })
   })
@@ -373,24 +376,42 @@ function renderRecall(root: HTMLElement, tpl: Template, lastVals: TemplateLastVa
     hideStatus()
     const chosenMedia = getCurrentMedia()
     const mediaOverride = chosenMedia !== tpl.label_media ? chosenMedia : undefined
-    try {
+
+    async function attemptPrint(override: boolean): Promise<void> {
       if (batchEnable?.checked) {
         const batchLabels = buildBatchLabels()
-        const result = await batchPrint(tpl.name, batchLabels, mediaOverride)
+        const result = await batchPrint(tpl.name, batchLabels, mediaOverride, override)
         const kind = result.failed > 0 ? 'error' : 'success'
         showStatus(
           `Batch ${result.batch_id}: ${result.succeeded} sent, ${result.failed} failed (${batchLabels.length} requested). "Sent" means transmitted to the printer; delivery is not confirmed.`,
           kind,
         )
       } else {
-        const result = await printTemplate(tpl.name, collectFields(), mediaOverride)
+        const result = await printTemplate(tpl.name, collectFields(), mediaOverride, override)
         showStatus(
           `Sent — job #${result.job_id} (status: ${result.status}). "Sent" means the job was transmitted to the printer; delivery is not confirmed.`,
           'success',
         )
       }
+    }
+
+    try {
+      await attemptPrint(false)
     } catch (err) {
-      showStatus((err as Error).message, 'error')
+      // A 409 media mismatch (loaded roll ≠ selected media) is overridable — offer to print anyway.
+      if (err instanceof ApiError && err.overrideAllowed) {
+        if (window.confirm(`${err.message}\n\nPrint anyway on the currently loaded roll?`)) {
+          try {
+            await attemptPrint(true)
+          } catch (err2) {
+            showStatus((err2 as Error).message, 'error')
+          }
+        } else {
+          showStatus(err.message, 'error')
+        }
+      } else {
+        showStatus((err as Error).message, 'error')
+      }
     } finally {
       updateButtons()
     }

From 4ac89f08bab6d6c784b3da0ec9e80fc19391c2a0 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 09:36:00 -0700
Subject: [PATCH 76/84] feat: friendly template names and DK-part label in the
 template list

---
 CHANGELOG.md                                  |  11 ++
 docs/features/templates.md                    |  17 +-
 frontend/src/pages/template-editor.ts         |  19 +-
 frontend/src/pages/templates-list.ts          | 171 +++++++++++-------
 ...-06-template-friendly-name-and-dk-label.md | 107 +++++++++++
 5 files changed, 250 insertions(+), 75 deletions(-)
 create mode 100644 prompts/done/2026-06-06-template-friendly-name-and-dk-label.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b595be..5672f83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,17 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Added
 
+- **Friendly template names** — when creating a template, type a human-readable name (e.g.
+  `Spool Label`); the URL slug (`spool-label`) is auto-derived and shown as a live read-only
+  hint. The friendly name is stored as `display_name`, shown in the template list and as the
+  editor title. Renaming `display_name` after creation is not yet available in the UI. Requires
+  a container image rebuild.
+
+- **DK part number in the template list** — the Media column now shows the Brother DK part
+  number with dimensions (e.g. `DK-1209 (62×29mm)`) instead of the raw media id. Two-color
+  media gets a `Red` suffix (e.g. `DK-2251 (62mm) Red`). If the media id is not in the catalog,
+  the raw id is shown as before. Requires a container image rebuild.
+
 - **Print a template on a different label media at recall time (one-off)** — the recall page
   now shows a media selector instead of a read-only badge, defaulting to the template's own
   media (e.g. a two-color template defaults to `62red`). Same-width media appear first
diff --git a/docs/features/templates.md b/docs/features/templates.md
index fed106e..be74fa6 100644
--- a/docs/features/templates.md
+++ b/docs/features/templates.md
@@ -8,7 +8,9 @@ The core feature. A template is a saved, named label design with a freeform canv
 
 1. Navigate to `/templates` → list of existing templates
 2. Click **New template**
-3. Modal: pick a name (slug-validated: lowercase, hyphens, no spaces) and a label media
+3. Modal: type a friendly name (e.g. `Spool Label`) — the URL slug is auto-derived (`spool-label`)
+   and shown as a read-only hint. Pick a label media. The OK button is gated on a valid slug
+   (non-empty, matches `^[a-z0-9][a-z0-9-]*$`) and a selected media.
 4. Land in editor with a blank canvas sized exactly to that label media at print DPI
 5. Add elements from a toolbar (text, QR, barcode, image, line, rect)
 6. Position, resize, rotate, layer
@@ -109,6 +111,7 @@ For continuous media (62mm endless), the canvas has a fixed width and a user-set
 
 Top: undo, redo, zoom, fit, save, save-as, preview, print
 
+The editor title shows the friendly `display_name` (falls back to the slug when they match).
 The current label media is shown as a read-only badge next to the template name so
 the user can see what they are editing without opening any menu.
 
@@ -166,6 +169,18 @@ Edge cases:
 - Negative or zero count: 400, "Batch count must be >= 1"
 - Batch count > 1000: 400, "Batch count exceeds maximum (1000)" — sanity guard
 
+## Template list
+
+The template list shows:
+- **Name** — `display_name` (falls back to the slug)
+- **Media** — the Brother DK part number with size, e.g. `DK-1209 (62×29mm)` for a die-cut,
+  `DK-2251 (62mm) Red` for a two-color continuous roll. If the media id is not in the catalog
+  (deleted or custom entry), the raw id is shown in `<code>` as a fallback.
+- **Updated** — last-modified timestamp
+
+Renaming `display_name` after creation is not yet supported in the UI (the `TemplateUpdate`
+model supports it via the API; a rename modal is left for a future iteration).
+
 ## API
 
 See [`api.md`](api.md) for the full API surface. Template endpoints:
diff --git a/frontend/src/pages/template-editor.ts b/frontend/src/pages/template-editor.ts
index 0e1e919..6b8fe59 100644
--- a/frontend/src/pages/template-editor.ts
+++ b/frontend/src/pages/template-editor.ts
@@ -22,18 +22,21 @@ function esc(s: string): string {
     .replace(/>/g, '&gt;')
 }
 
-function parsePath(): { name: string; isNew: boolean; newMedia: string } {
+function parsePath(): { name: string; isNew: boolean; newMedia: string; newDisplayName: string } {
   const path = window.location.pathname  // /templates/my-name
   const parts = path.split('/')
   const name = decodeURIComponent(parts[parts.length - 1] ?? '')
   const params = new URLSearchParams(window.location.search)
   const isNew = params.get('new') === '1'
   const newMedia = params.get('media') ?? ''
-  return { name, isNew, newMedia }
+  const newDisplayName = params.get('display_name') ?? ''
+  return { name, isNew, newMedia, newDisplayName }
 }
 
 export function mountTemplateEditor(root: HTMLElement): void {
-  const { name, isNew, newMedia } = parsePath()
+  const { name, isNew, newMedia, newDisplayName } = parsePath()
+  // Friendly name shown in the toolbar title; falls back to the slug
+  let displayName = newDisplayName || name
 
   // Widen the app container for the editor
   const appEl = document.getElementById('app')
@@ -44,7 +47,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
       <div class="editor-toolbar">
         <button id="btn-back">← Back</button>
         <span class="toolbar-sep"></span>
-        <span class="editor-title" id="editor-title">${esc(name)}</span>
+        <span class="editor-title" id="editor-title">${esc(displayName)}</span>${displayName !== name ? `<span class="editor-title-slug" id="editor-title-slug">${esc(name)}</span>` : ''}
         <code class="editor-media-badge" id="editor-media">${esc(isNew ? newMedia : '')}</code>
         <span class="toolbar-sep"></span>
         <button id="btn-add-text" title="Add a text element. Use {fieldname} placeholders (single braces) for variable fields.">Add Text</button>
@@ -215,7 +218,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
       if (existsOnServer) {
         await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia })
       } else {
-        await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson })
+        await createTemplate({ name, display_name: newDisplayName || undefined, label_media: labelMedia, canvas_json: canvasJson })
         existsOnServer = true
       }
       showStatus('Saved.', 'success')
@@ -246,7 +249,7 @@ export function mountTemplateEditor(root: HTMLElement): void {
         if (existsOnServer) {
           await updateTemplate(name, { canvas_json: canvasJson, label_media: labelMedia })
         } else {
-          await createTemplate({ name, label_media: labelMedia, canvas_json: canvasJson })
+          await createTemplate({ name, display_name: newDisplayName || undefined, label_media: labelMedia, canvas_json: canvasJson })
           existsOnServer = true
         }
       }
@@ -287,6 +290,10 @@ export function mountTemplateEditor(root: HTMLElement): void {
       try {
         const tmpl = await getTemplate(name)
         labelMedia = tmpl.label_media
+        // Update title to show the stored display_name
+        displayName = tmpl.display_name || name
+        const titleEl = root.querySelector<HTMLElement>('#editor-title')
+        if (titleEl) titleEl.textContent = displayName
         const label = labels.find(l => l.id === tmpl.label_media)
         if (!label) { showStatus(`Unknown label media: ${tmpl.label_media}`, 'error'); return }
         await initEditor(label)
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index d414971..222744c 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -1,8 +1,20 @@
-import { deleteTemplate, listTemplates } from '../api'
-import type { Template } from '../types'
+import { deleteTemplate, getLabels, listTemplates } from '../api'
+import type { LabelEntry, Template } from '../types'
 import { navigate } from '../router'
 import { mountLabelMediaSelect, type LabelMediaSelectHandle } from '../labels'
 
+function slugify(s: string): string {
+  return s.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+function formatMediaLabel(label: LabelEntry): string {
+  const part = label.brother_part || label.display_name || label.id
+  const [w, h] = label.tape_size
+  const size = h > 0 ? `(${w}×${h}mm)` : `(${w}mm)`
+  const red = label.color === 1 ? ' Red' : ''
+  return `${part} ${size}${red}`
+}
+
 function esc(s: string): string {
   return s
     .replace(/&/g, '&amp;')
@@ -42,7 +54,7 @@ export function mountTemplatesList(root: HTMLElement): void {
     statusEl.hidden = false
   }
 
-  function renderList(templates: Template[]): void {
+  function renderList(templates: Template[], labelMap: Map<string, LabelEntry>): void {
     if (templates.length === 0) {
       bodyEl.innerHTML = `<p class="empty-state">No templates yet. Create one.</p>`
       return
@@ -58,10 +70,15 @@ export function mountTemplatesList(root: HTMLElement): void {
           </tr>
         </thead>
         <tbody>
-          ${templates.map(t => `
+          ${templates.map(t => {
+            const label = labelMap.get(t.label_media)
+            const mediaCellHtml = label
+              ? esc(formatMediaLabel(label))
+              : `<code>${esc(t.label_media)}</code>`
+            return `
             <tr data-name="${esc(t.name)}">
               <td>${esc(t.display_name || t.name)}</td>
-              <td><code>${esc(t.label_media)}</code></td>
+              <td>${mediaCellHtml}</td>
               <td>${esc(fmtDate(t.updated_at))}</td>
               <td class="tpl-actions">
                 <button class="btn-print" data-name="${esc(t.name)}">Print</button>
@@ -69,7 +86,7 @@ export function mountTemplatesList(root: HTMLElement): void {
                 <button class="btn-delete" data-name="${esc(t.name)}">Delete</button>
               </td>
             </tr>
-          `).join('')}
+          `}).join('')}
         </tbody>
       </table>
     `
@@ -102,8 +119,9 @@ export function mountTemplatesList(root: HTMLElement): void {
     bodyEl.innerHTML = `<p>Loading…</p>`
     statusEl.hidden = true
     try {
-      const templates = await listTemplates()
-      renderList(templates)
+      const [templates, labels] = await Promise.all([listTemplates(), getLabels()])
+      const labelMap = new Map(labels.map(l => [l.id, l]))
+      renderList(templates, labelMap)
     } catch (err) {
       showStatus((err as Error).message, 'error')
       bodyEl.innerHTML = ''
@@ -118,73 +136,90 @@ export function mountTemplatesList(root: HTMLElement): void {
 }
 
 function showNewTemplateModal(onCreated: () => void): void {
-  import('../api').then(({ getLabels }) => {
-    const overlay = document.createElement('div')
-    overlay.className = 'modal-overlay'
-    overlay.innerHTML = `
-      <div class="modal">
-        <h3>New template</h3>
-        <div class="modal-status" hidden></div>
-        <label>
-          Name (slug)
-          <input id="modal-name" type="text" placeholder="my-template" autocomplete="off" />
-          <span class="field-error" id="name-error" hidden></span>
-        </label>
-        <label>Label media</label>
-        <div id="modal-media-container"></div>
-        <div class="modal-actions">
-          <button id="modal-cancel">Cancel</button>
-          <button id="modal-ok" class="btn-primary" disabled>Create</button>
-        </div>
+  const overlay = document.createElement('div')
+  overlay.className = 'modal-overlay'
+  overlay.innerHTML = `
+    <div class="modal">
+      <h3>New template</h3>
+      <div class="modal-status" hidden></div>
+      <label>
+        Name
+        <input id="modal-name" type="text" placeholder="Spool Label" autocomplete="off" />
+        <span class="slug-hint" id="slug-hint" hidden></span>
+        <span class="field-error" id="name-error" hidden></span>
+      </label>
+      <label>Label media</label>
+      <div id="modal-media-container"></div>
+      <div class="modal-actions">
+        <button id="modal-cancel">Cancel</button>
+        <button id="modal-ok" class="btn-primary" disabled>Create</button>
       </div>
-    `
-    document.body.appendChild(overlay)
-
-    const nameInput = overlay.querySelector<HTMLInputElement>('#modal-name')!
-    const mediaContainer = overlay.querySelector<HTMLDivElement>('#modal-media-container')!
-    const cancelBtn = overlay.querySelector<HTMLButtonElement>('#modal-cancel')!
-    const okBtn = overlay.querySelector<HTMLButtonElement>('#modal-ok')!
-    const nameError = overlay.querySelector<HTMLSpanElement>('#name-error')!
-    let mediaHandle: LabelMediaSelectHandle | null = null
-
-    const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
-
-    function validate(): boolean {
-      const v = nameInput.value.trim()
-      if (!v) { nameError.textContent = 'Name is required'; nameError.hidden = false; return false }
-      if (!SLUG_RE.test(v)) { nameError.textContent = 'Use lowercase letters, numbers, hyphens only'; nameError.hidden = false; return false }
-      nameError.hidden = true
-      return true
+    </div>
+  `
+  document.body.appendChild(overlay)
+
+  const nameInput = overlay.querySelector<HTMLInputElement>('#modal-name')!
+  const slugHint = overlay.querySelector<HTMLSpanElement>('#slug-hint')!
+  const mediaContainer = overlay.querySelector<HTMLDivElement>('#modal-media-container')!
+  const cancelBtn = overlay.querySelector<HTMLButtonElement>('#modal-cancel')!
+  const okBtn = overlay.querySelector<HTMLButtonElement>('#modal-ok')!
+  const nameError = overlay.querySelector<HTMLSpanElement>('#name-error')!
+  let mediaHandle: LabelMediaSelectHandle | null = null
+
+  const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/
+
+  function validate(): boolean {
+    const friendly = nameInput.value.trim()
+    if (!friendly) {
+      nameError.textContent = 'Name is required'
+      nameError.hidden = false
+      slugHint.hidden = true
+      return false
     }
-
-    function updateOk(): void {
-      okBtn.disabled = !nameInput.value.trim() || !mediaHandle?.getValue()
+    const slug = slugify(friendly)
+    if (!slug || !SLUG_RE.test(slug)) {
+      nameError.textContent = 'Name must contain at least one letter or number'
+      nameError.hidden = false
+      slugHint.hidden = true
+      return false
     }
+    nameError.hidden = true
+    slugHint.textContent = `URL: ${slug}`
+    slugHint.hidden = false
+    return true
+  }
 
-    nameInput.addEventListener('input', () => { validate(); updateOk() })
+  function updateOk(): void {
+    const friendly = nameInput.value.trim()
+    const slug = slugify(friendly)
+    okBtn.disabled = !slug || !SLUG_RE.test(slug) || !mediaHandle?.getValue()
+  }
 
-    getLabels().then(labels => {
-      mediaHandle = mountLabelMediaSelect({
-        container: mediaContainer,
-        labels,
-        onChange: () => updateOk(),
-      })
-      updateOk()
-    })
+  nameInput.addEventListener('input', () => { validate(); updateOk() })
 
-    cancelBtn.addEventListener('click', () => overlay.remove())
-    overlay.addEventListener('click', e => { if (e.target === overlay) overlay.remove() })
-
-    okBtn.addEventListener('click', () => {
-      if (!validate()) return
-      const name = nameInput.value.trim()
-      const media = mediaHandle?.getValue() ?? ''
-      overlay.remove()
-      // Navigate to editor — template created on first Save
-      navigate(`/templates/${name}?new=1&media=${encodeURIComponent(media)}`)
-      onCreated()
+  getLabels().then(labels => {
+    mediaHandle = mountLabelMediaSelect({
+      container: mediaContainer,
+      labels,
+      onChange: () => updateOk(),
     })
+    updateOk()
+  })
 
-    nameInput.focus()
+  cancelBtn.addEventListener('click', () => overlay.remove())
+  overlay.addEventListener('click', e => { if (e.target === overlay) overlay.remove() })
+
+  okBtn.addEventListener('click', () => {
+    if (!validate()) return
+    const friendly = nameInput.value.trim()
+    const slug = slugify(friendly)
+    const media = mediaHandle?.getValue() ?? ''
+    overlay.remove()
+    // Navigate to editor — template created on first Save
+    // Pass display_name so the editor can include it in the create call
+    navigate(`/templates/${slug}?new=1&media=${encodeURIComponent(media)}&display_name=${encodeURIComponent(friendly)}`)
+    onCreated()
   })
+
+  nameInput.focus()
 }
diff --git a/prompts/done/2026-06-06-template-friendly-name-and-dk-label.md b/prompts/done/2026-06-06-template-friendly-name-and-dk-label.md
new file mode 100644
index 0000000..9390491
--- /dev/null
+++ b/prompts/done/2026-06-06-template-friendly-name-and-dk-label.md
@@ -0,0 +1,107 @@
+---
+name: 2026-06-06-template-friendly-name-and-dk-label
+status: completed
+created: 2026-06-06
+model: sonnet            # opus = research/planning, sonnet = coding
+completed: 2026-06-06
+result: frontend-only; friendly name modal (slug auto-derived), DK-part label in list, display_name threaded through editor create flow
+---
+
+# Task: Template friendly names + DK-part label in the list
+
+Two template UX improvements (frontend-only — the backend already supports both):
+
+1. **Friendly name.** When creating a template the user should type a human name like
+   `Spool Label`; the URL slug (`spool-label`) is derived from it automatically. The friendly
+   name is stored as `display_name` and shown in the list and editor.
+2. **Real label in the list.** The templates list currently shows the raw media id
+   (`<code>62x29</code>`). Show the Brother **DK part number with size and a Red suffix**
+   instead — e.g. `DK-1209 (62×29mm)` for a die-cut, `DK-2251 (62mm) Red` for two-color.
+
+## Before you start
+
+- **No backend changes needed.** `Template` / `TemplateCreate` / `TemplateUpdate` already
+  carry `display_name` (`backend/labelforge/models/__init__.py`), and `store.create_template`
+  already persists it (defaulting `display_name = data.name` when omitted). The list already
+  renders `t.display_name || t.name`. The gaps are entirely in the frontend.
+- Anchors to read:
+  - `frontend/src/pages/templates-list.ts` — the New Template modal (collects `Name (slug)`
+    at ~line 129, validates against `SLUG_RE`, then navigates
+    `/templates/<name>?new=1&media=<media>` — creation is deferred to the editor's first Save)
+    and the list table (media cell at ~line 64).
+  - `frontend/src/pages/template-editor.ts` — `parsePath()` reads `new`/`media` from the URL;
+    `createTemplate({ name, label_media, canvas_json })` at ~line 218 (the create-on-save path)
+    and the editor title/media badge at ~lines 47-48.
+  - `frontend/src/labels.ts` — `LabelEntry` shape; `tape_size: [width_mm, length_mm]`,
+    `color` (1 = two-color), `brother_part`, `display_name`. Reuse for the DK formatter.
+  - `frontend/src/api.ts` — `createTemplate`, `getLabels`; confirm the frontend `TemplateCreate`
+    type in `types.ts` includes `display_name` (add it if missing).
+- Work on `dev`. Conventional-Commits, no `Co-authored-by:`, docs ship with code.
+
+## Working tree check
+
+`git status --porcelain` first. This touches `frontend/src/pages/templates-list.ts`,
+`frontend/src/pages/template-editor.ts`, maybe `frontend/src/api.ts` / `types.ts`, plus docs.
+If anything unexpected is dirty, list it and ask.
+
+## What to do
+
+### 1. Friendly name on create
+
+- In the New Template modal, relabel the input from **"Name (slug)"** to **"Name"** with
+  placeholder `Spool Label`. The user types a free-form friendly name.
+- Add a small `slugify(s)` helper: `s.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')`. Show the derived slug live as a read-only hint beneath the input
+  (e.g. *"URL: `spool-label`"*), so the user sees what it becomes.
+- Validate the **derived slug** (non-empty, matches the existing `SLUG_RE`
+  `^[a-z0-9][a-z0-9-]*$`); show the error against the friendly input. Keep the OK button gated
+  on a valid slug + a selected media. Server-side uniqueness still applies on create.
+- Thread the friendly name through to creation. Since creation is deferred to the editor,
+  pass it in the navigation URL alongside `media`, e.g.
+  `/templates/<slug>?new=1&media=<media>&display_name=<encodeURIComponent(friendly)>`.
+- In `template-editor.ts`: parse `display_name` from the URL in `parsePath()`, and include it
+  in the create call — `createTemplate({ name, display_name, label_media, canvas_json })`.
+  Make sure the frontend `TemplateCreate` type allows `display_name?`.
+- Editor title: show the friendly `display_name` (fall back to the slug) instead of the bare
+  slug. The slug can remain visible as secondary text if it reads cleanly; don't overbuild.
+- Out of scope: renaming `display_name` after creation (the model supports it via
+  `TemplateUpdate`, but leave a rename UI for later — note it in the changelog as not-yet).
+
+### 2. DK-part label in the list
+
+- In `templates-list.ts`, fetch the catalog once (`getLabels()`) when rendering the list and
+  build an `id → LabelEntry` map. (The list currently only fetches templates.)
+- Add a `formatMediaLabel(label: LabelEntry): string`:
+  - `part = label.brother_part || label.display_name || label.id`
+  - size from `tape_size = [w, h]`: die-cut → `(${w}×${h}mm)`; continuous (`h` is `0`) →
+    `(${w}mm)`
+  - red suffix: `label.color === 1 ? ' Red' : ''`
+  - result e.g. `DK-1209 (62×29mm)`, `DK-2251 (62mm) Red`
+- Render the media cell using this instead of the raw id. **Fallback**: if `label_media` isn't
+  in the catalog (deleted/unknown media), show the raw id in `<code>` as today so nothing
+  breaks. Keep the cell readable (it need not be `<code>` for the formatted case).
+
+## Conventions to honor
+
+- LF endings. Reuse `LabelEntry`/`getLabels`; don't duplicate catalog logic. Match existing
+  templates-list / editor style.
+- **Docs**: `docs/features/templates.md` — note that New Template takes a friendly name (slug
+  derived), and the list shows the DK part number + size (+ Red for two-color).
+- **Changelog** (`### Added` under `## [Unreleased]`): friendly template names (type a name,
+  slug auto-derived, shown in list + editor); the template list now shows the Brother DK part
+  number with size and a Red marker for two-color media instead of the raw media id. Note the
+  container-rebuild requirement.
+
+## When done
+
+1. Verify: `cd frontend && npm run build` compiles; `ruff check . && mypy backend && pytest -q`
+   still green (no backend change, but confirm nothing regressed). Manually: create a template
+   named `Spool Label` → slug `spool-label`, list shows the friendly name + e.g.
+   `DK-1209 (62×29mm)`; a `62red` template shows `… (62mm) Red`. One-line "run this to verify".
+2. Update this file's frontmatter (`status`, `completed` = 2026-06-06, `result`).
+3. `git mv` this file into `prompts/done/` (success) or `prompts/failed/` (failure).
+4. ADR only if a non-obvious decision arose (likely none — note in the summary if so).
+5. Stage everything but **do not commit** — leave it staged-and-ready and report: the file
+   list, the proposed one-line commit message
+   (`feat: friendly template names and DK-part label in the template list`), verification
+   results, and any decisions/deviations. The human reviews and commits.

From 729ccc4b37174c55b9e3f6b76ce44fe3aee6c9e3 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 10:13:37 -0700
Subject: [PATCH 77/84] fix: compact icon buttons for template list actions to
 stop card overflow

---
 CHANGELOG.md                         | 13 ++++++++
 frontend/src/pages/templates-list.ts | 19 ++++++++----
 frontend/src/style.css               | 45 +++++++++++++++++++++++++++-
 3 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5672f83..e70ad7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,10 +36,23 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Changed
 
+- **Template list actions are now compact icon buttons** — the per-row Print / Edit / Delete
+  buttons were full-size text buttons that, together with a verbose timestamp, overflowed the
+  card. They're now small icon buttons (with tooltips and accessible labels), the Updated
+  column shows a shorter date (no seconds) on a single line, and the table fits within the card
+  without widening the layout. Requires a container image rebuild.
+
 - **Adopted `release-prep-and-cut` standard (v1.0.0)** — `/release-prep` and `/release-cut` slash commands added to `.claude/commands/`; publish workflow (`build-and-push.yml`) now fires on `release: published` (tag-push trigger removed); `CLAUDE.md` and `standards.md` updated. Developer/process-facing only — no runtime change.
 
 ### Fixed
 
+- **"Run cleanup now" works again** — the Settings → History & Retention "Run cleanup now"
+  button returned **Method Not Allowed**: the frontend posted to `/api/admin/prune-history`,
+  but that route was never implemented, so the request fell through to the SPA catch-all (a
+  GET) and 405'd. The endpoint now exists (auth-gated, like the other admin routes) and
+  `prune_history()` returns the number of jobs removed, so the button reports e.g. "Cleanup
+  done — 3 job(s) removed." Requires a container image rebuild.
+
 - **Upgrade now delivers new and corrected default catalog entries** (#16) — upgrading the
   container image no longer leaves the operator's `labels.yml` stale. On startup, labelforge
   performs a non-destructive 3-way merge: new entries from the bundled default are added,
diff --git a/frontend/src/pages/templates-list.ts b/frontend/src/pages/templates-list.ts
index 222744c..0e9d255 100644
--- a/frontend/src/pages/templates-list.ts
+++ b/frontend/src/pages/templates-list.ts
@@ -23,10 +23,19 @@ function esc(s: string): string {
     .replace(/>/g, '&gt;')
 }
 
+// Inline line icons (no icon-font dependency). 16px, inherit currentColor.
+const ICON_PRINT = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 6 2 18 2 18 9"/><path d="M6 18H4a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-2"/><rect x="6" y="14" width="12" height="8"/></svg>`
+const ICON_EDIT = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z"/></svg>`
+const ICON_DELETE = `<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>`
+
 function fmtDate(iso: string | undefined): string {
   if (!iso) return '—'
   try {
-    return new Date(iso).toLocaleString()
+    // Compact: drop seconds so the column stays on one line (e.g. "6/6/2026, 8:51 AM").
+    return new Date(iso).toLocaleString(undefined, {
+      year: 'numeric', month: 'numeric', day: 'numeric',
+      hour: 'numeric', minute: '2-digit',
+    })
   } catch {
     return iso
   }
@@ -79,11 +88,11 @@ export function mountTemplatesList(root: HTMLElement): void {
             <tr data-name="${esc(t.name)}">
               <td>${esc(t.display_name || t.name)}</td>
               <td>${mediaCellHtml}</td>
-              <td>${esc(fmtDate(t.updated_at))}</td>
+              <td class="tpl-updated">${esc(fmtDate(t.updated_at))}</td>
               <td class="tpl-actions">
-                <button class="btn-print" data-name="${esc(t.name)}">Print</button>
-                <button class="btn-edit" data-name="${esc(t.name)}">Edit</button>
-                <button class="btn-delete" data-name="${esc(t.name)}">Delete</button>
+                <button class="icon-btn btn-print" data-name="${esc(t.name)}" title="Print" aria-label="Print ${esc(t.display_name || t.name)}">${ICON_PRINT}</button>
+                <button class="icon-btn btn-edit" data-name="${esc(t.name)}" title="Edit" aria-label="Edit ${esc(t.display_name || t.name)}">${ICON_EDIT}</button>
+                <button class="icon-btn btn-delete" data-name="${esc(t.name)}" title="Delete" aria-label="Delete ${esc(t.display_name || t.name)}">${ICON_DELETE}</button>
               </td>
             </tr>
           `}).join('')}
diff --git a/frontend/src/style.css b/frontend/src/style.css
index a3ef58a..99ab742 100644
--- a/frontend/src/style.css
+++ b/frontend/src/style.css
@@ -198,8 +198,45 @@ button:disabled {
 
 .tpl-actions {
   display: flex;
-  gap: 0.5rem;
+  gap: 0.35rem;
   justify-content: flex-end;
+  white-space: nowrap;
+}
+
+.tpl-updated {
+  white-space: nowrap;
+  color: #666;
+  font-size: 0.85rem;
+}
+
+/* compact icon button used for the per-row template actions */
+.icon-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  padding: 0;
+  border: 1px solid #d3d6db;
+  border-radius: 5px;
+  background: #fff;
+  color: #4a5260;
+  transition: background 0.12s, border-color 0.12s, color 0.12s;
+}
+
+.icon-btn svg {
+  display: block;
+}
+
+.icon-btn:hover {
+  background: #f3f4f6;
+  border-color: #b9bec6;
+}
+
+.tpl-actions .btn-delete:hover {
+  background: #fdeaea;
+  border-color: #e6a6a6;
+  color: #c0392b;
 }
 
 .empty-state {
@@ -399,6 +436,12 @@ button:disabled {
   border-color: #1a6fdb;
 }
 
+.tpl-actions .btn-print:hover {
+  background: #155cb8;
+  border-color: #155cb8;
+  color: #fff;
+}
+
 /* history page */
 .history-page {
   background: #fff;

From 7e5bb8e6044ebf6004d9c8ca895e211772db7986 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 10:13:37 -0700
Subject: [PATCH 78/84] fix: add prune-history admin route so "Run cleanup now"
 works (was 405)

---
 backend/labelforge/history.py      | 11 +++++++----
 backend/labelforge/routes/admin.py |  8 ++++++++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/backend/labelforge/history.py b/backend/labelforge/history.py
index 652ffe7..57fda1e 100644
--- a/backend/labelforge/history.py
+++ b/backend/labelforge/history.py
@@ -87,11 +87,12 @@ def get_latest_field_values(template_name: str) -> tuple[dict | None, str | None
     return json.loads(row["field_values"]), row["created_at"]
 
 
-def prune_history() -> None:
+def prune_history() -> int:
+    """Prune history per the retention policy. Returns the number of jobs removed."""
     try:
         mode = settings_store.get("retention_mode")
         if mode == "forever":
-            return
+            return 0
 
         db_path = settings.data_dir / "data" / "app.db"
         conn = get_connection(db_path)
@@ -127,10 +128,10 @@ def prune_history() -> None:
                     (f"-{days} days",),
                 ).fetchall()
             else:
-                return
+                return 0
 
             if not rows:
-                return
+                return 0
 
             ids = [r["id"] for r in rows]
             preview_paths = [r["preview_path"] for r in rows if r["preview_path"]]
@@ -165,7 +166,9 @@ def prune_history() -> None:
                 db_size_before,
                 db_size_after,
             )
+            return pruned
         finally:
             conn.close()
     except Exception:
         logger.error("prune_history failed", exc_info=True)
+        return 0
diff --git a/backend/labelforge/routes/admin.py b/backend/labelforge/routes/admin.py
index b72cdfe..0298779 100644
--- a/backend/labelforge/routes/admin.py
+++ b/backend/labelforge/routes/admin.py
@@ -3,6 +3,7 @@
 
 from fastapi import APIRouter, Depends
 
+from labelforge import history as history_module
 from labelforge.catalog.loader import load_catalog
 from labelforge.catalog.reconcile import reconcile_catalog_files
 from labelforge.config import settings
@@ -41,3 +42,10 @@ async def reload_catalog() -> dict[str, Any]:
         "reason": summary["reason"],
         "catalog_size": len(get_catalog()),
     }
+
+
+@router.post("/admin/prune-history")
+async def prune_history_now() -> dict[str, int]:
+    """Run history retention pruning immediately. Returns the number of jobs removed."""
+    pruned = history_module.prune_history()
+    return {"pruned": pruned}

From f10e7965af5bb2f2424ee3ddbe055add02c6c339 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 10:22:18 -0700
Subject: [PATCH 79/84] docs: reconcile README, PRD, and architecture with
 shipped features

---
 CHANGELOG.md         |  8 ++++++
 README.md            | 62 ++++++++++++++++++++++++++++++++++++++------
 docs/PRD.md          |  2 ++
 docs/architecture.md |  8 +++---
 4 files changed, 68 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e70ad7b..f58a07e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,6 +36,14 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ### Changed
 
+- **Docs reconciled with shipped features** — the README's "What it does" was rewritten to
+  cover everything now implemented (two-color printing, printer-status/loaded-media detection,
+  the label catalog, settings/retention, print-time media override, batch printing, and
+  `DISABLE_AUTH`), and gained a "Running it" section with a configuration table. The PRD's
+  in-scope list now includes two shipped features it omitted (one-off media override at recall;
+  two-color red text in templates), and `architecture.md` was corrected to reference the real
+  compose filenames (`docker-compose.yml` / `docker-compose.dev.yml`). Docs-only.
+
 - **Template list actions are now compact icon buttons** — the per-row Print / Edit / Delete
   buttons were full-size text buttons that, together with a verbose timestamp, overflowed the
   card. They're now small icon buttons (with tooltips and accessible labels), the Updated
diff --git a/README.md b/README.md
index 88c4c1b..46678d5 100644
--- a/README.md
+++ b/README.md
@@ -2,22 +2,37 @@
 
 Self-hosted web app for designing, saving, and printing labels to Brother QL series printers.
 
-**Status**: Pre-release. Core print and template features working; not yet packaged for deployment.
+**Status**: Pre-release. All v1 features are working and the app is packaged as a single Docker image; no release has been tagged yet.
 
 **Version:** 0.0.1
 
 ## What's New
 
-_No releases yet. See `CHANGELOG.md` for upcoming changes._
+_No releases tagged yet. See [`CHANGELOG.md`](CHANGELOG.md) for the running list of changes._
 
 ## What it does
 
-- Quick-print mode (text + font, like brother_ql_web)
-- Save labels as named templates with variable fields
-- Recall templates, fill variables, print
-- Full HTTP API — every template is callable for homelab integrations
-- Print history with reprint and pinning
-- Freeform canvas editor (text, QR codes, barcodes, images, shapes)
+- **Quick-print mode** — type text, pick a font/size/alignment, print (like brother_ql_web)
+- **Named templates** — design a label on a freeform canvas (text, QR codes, barcodes,
+  images, lines, rectangles) and save it under a friendly name
+- **Variable fields** — `{placeholder}` syntax in element text auto-generates a fill-in form
+  on recall; numeric fields support increment/batch printing
+- **Two-color printing** — black + red on two-color media (DK-2251 / `62red`); red maps to
+  black automatically on mono media
+- **Print history** — browse, reprint, pin, and delete past prints, with thumbnails and
+  configurable retention (keep forever / last N / last N days); pinned prints are never pruned
+- **Label catalog** — `labels.yml` merges the printer library's truth with editable UX
+  metadata (friendly names, Brother DK part numbers); media the printer can't handle is
+  shown disabled
+- **Printer status** — auto-detect the loaded roll and warn (or block) on a media mismatch,
+  with a print-anyway override
+- **Print on different media at recall** — one-off print of a template on another label size
+  without mutating the saved template
+- **Settings page** — retention policy, default media, and printer-status options, all editable
+  in the UI
+- **Full HTTP API** — every template is callable via `POST /api/print/{name}` for homelab
+  integrations (Home Assistant, etc.); auth is a single Bearer token, or disable app-level
+  auth entirely behind a trusted reverse proxy
 
 ## Printer setup (required)
 
@@ -54,6 +69,37 @@ If a job is rejected as `wrong roll type` even with the settings above:
   still return HTTP 200 with `status: "sent"` — `sent` means *transmitted*,
   not *confirmed printed*. Watch the physical printer.
 
+## Running it
+
+The app ships as a single Docker image (multi-stage build: frontend → static assets served
+by FastAPI). Copy `.env.example` to `.env`, fill in the values, and start the stack:
+
+```
+cp .env.example .env      # set API_TOKEN and PRINTER_HOST at minimum
+docker compose up -d       # uses docker-compose.yml
+```
+
+For local development with hot-reload, use `docker-compose.dev.yml`.
+
+### Configuration
+
+All config is environment-driven (see `.env.example` for the full list). The essentials:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `API_TOKEN` | _(required)_ | Bearer token for all `/api/*` routes. App refuses to start without it unless `DISABLE_AUTH=true`. |
+| `PRINTER_HOST` | _(required)_ | IP/hostname of the Brother QL printer. |
+| `PRINTER_MODEL` | `QL-820NWB` | Must match a `brother_ql` model id. Drives label-catalog compatibility. |
+| `PRINTER_BACKEND` | `network` | `network` \| `linux_kernel` \| `pyusb`. |
+| `DEFAULT_LABEL_MEDIA` | `62` | Pre-selected media in the UI. |
+| `DATA_DIR` | `/data` | Where SQLite, `labels.yml`, fonts, and previews live in the container. |
+| `DISABLE_AUTH` | `false` | Run with no app-level auth (for a reverse proxy that handles auth). Not SSO; still single-user. |
+| `CATALOG_AUTO_MERGE` | `true` | On startup, non-destructively merge new/corrected default catalog entries into the operator's `labels.yml` (a `.bak` is written first). |
+| `LOG_LEVEL` | `INFO` | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR`. |
+
+Persistent data lives under `$DATA_DIR`; back it with a named volume or bind mount. The
+interactive API docs are at `/docs`.
+
 ## Design docs
 
 See [`docs/PRD.md`](docs/PRD.md) for scope, then [`docs/features/`](docs/features/) for per-feature designs.
diff --git a/docs/PRD.md b/docs/PRD.md
index 5102122..54eaa07 100644
--- a/docs/PRD.md
+++ b/docs/PRD.md
@@ -28,8 +28,10 @@ Single Docker container, deployed on `docker10` via Dockhand. External access vi
 
 - Quick-print mode (text + font + size + label media — like brother_ql_web, kept)
 - Named templates with a freeform canvas layout (text, QR, barcode, image, line, rect)
+- Two-color (black + red) text in templates on two-color media; red maps to black on mono media
 - Variable fields auto-detected from `{placeholder}` syntax in element content
 - Template recall: form auto-generated from field schema, fill, preview, print
+- One-off print of a template on a different label media at recall time (stored media unchanged)
 - Increment / batch printing for numeric fields
 - Print history with reprint, pinning, and configurable retention
 - HTTP API: every template callable via `POST /api/print/{name}` with JSON field values
diff --git a/docs/architecture.md b/docs/architecture.md
index e5fc46a..78995e0 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -22,7 +22,7 @@
 
 ### Storage
 
-- **SQLite** at `$DATA_DIR/data/app.db` — templates, history, settings, API tokens
+- **SQLite** at `$DATA_DIR/data/app.db` — templates, history, settings (auth is a single shared secret from the environment, not stored here)
 - **`labels.yml`** at `$DATA_DIR/labels.yml` — user-editable label catalog metadata
 - **Fonts** at `$DATA_DIR/fonts/` — `.ttf` / `.otf` files, drop-in
 - **Label preview images** (optional) at `$DATA_DIR/label-previews/` — referenced from `labels.yml`
@@ -46,8 +46,8 @@ labelforge/
 ├── CLAUDE.md
 ├── .gitignore
 ├── .gitattributes
-├── compose.yml                   # single-service stack; bring your own proxy
-├── compose.dev.yml               # local dev: bind mounts, no Traefik labels
+├── docker-compose.yml            # single-service stack; bring your own proxy
+├── docker-compose.dev.yml        # local dev: bind mounts, no Traefik labels
 ├── Dockerfile                    # multi-stage: frontend build → python runtime
 ├── pyproject.toml                # backend deps + tool config
 ├── docs/
@@ -127,7 +127,7 @@ merge: only identifiers in the intersection are user-facing.
 
 - Single Docker image built from the included `Dockerfile` (multi-stage: frontend build → python runtime). No build step at deploy time once the image is built.
 - Runs as one container serving plain HTTP on port `8000`. Put it behind whatever reverse proxy or tunnel you use; proxy wiring is deployment-specific and intentionally not baked into the app.
-- Persistent data lives under `$DATA_DIR` (default `/data`); back it with a named volume or a host bind mount. See `compose.yml` for a standalone example and `compose.dev.yml` for local hot-reload dev.
+- Persistent data lives under `$DATA_DIR` (default `/data`); back it with a named volume or a host bind mount. See `docker-compose.yml` for a standalone example and `docker-compose.dev.yml` for local hot-reload dev.
 - Env-driven config: printer host/port, API token, default label media, data dir, log level. See `.env.example`.
 
 ## Out of scope for v1

From fc8e5c94547b7fd23f22b5c688ea5d79b1a5a134 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 10:33:50 -0700
Subject: [PATCH 80/84] chore(release): prepare v0.1.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- pyproject.toml bumped to 0.1.0
- CHANGELOG: rolled [Unreleased] → [0.1.0] — 2026-06-06
- README: version badge + What's New entry, Status updated
- CLAUDE.md: Build Status block updated (Last shipped v0.1.0)
---
 CHANGELOG.md   |  2 ++
 CLAUDE.md      |  2 +-
 README.md      | 14 +++++++++++---
 pyproject.toml |  2 +-
 4 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f58a07e..8c9b599 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [Unreleased]
 
+## [0.1.0] — 2026-06-06
+
 ### Added
 
 - **Friendly template names** — when creating a template, type a human-readable name (e.g.
diff --git a/CLAUDE.md b/CLAUDE.md
index a4994b8..14244b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,7 +10,7 @@ Owner: crzykidd. Personal homelab project, public open source. Single-user app 
 
 ## Build Status
 
-- **Last shipped:** — (no release yet)
+- **Last shipped:** v0.1.0 (first release)
 - **Target for next release:** TBD
 
 ## Standards
diff --git a/README.md b/README.md
index 46678d5..1625a91 100644
--- a/README.md
+++ b/README.md
@@ -2,13 +2,21 @@
 
 Self-hosted web app for designing, saving, and printing labels to Brother QL series printers.
 
-**Status**: Pre-release. All v1 features are working and the app is packaged as a single Docker image; no release has been tagged yet.
+**Status**: First release (v0.1.0) — all v1 features are working and the app is packaged as a single Docker image.
 
-**Version:** 0.0.1
+**Version:** 0.1.0
 
 ## What's New
 
-_No releases tagged yet. See [`CHANGELOG.md`](CHANGELOG.md) for the running list of changes._
+### v0.1.0 (2026-06-06)
+
+First release. The full v1 feature set is here: quick-print, a Fabric.js canvas
+template editor with variable `{placeholder}` fields, template recall with batch/increment
+printing, two-color (black + red) printing on DK-2251, print history (reprint, pin, delete,
+configurable retention), a hybrid `labels.yml` catalog with friendly names and Brother DK part
+numbers, printer-status detection with a media-mismatch override, one-off media override at
+recall, a settings UI, and a full Bearer-token HTTP API (every template callable for homelab
+integrations). See [`CHANGELOG.md`](CHANGELOG.md) for the complete list.
 
 ## What it does
 
diff --git a/pyproject.toml b/pyproject.toml
index c84c295..3cc6fb5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "labelforge"
-version = "0.0.1"
+version = "0.1.0"
 description = "Self-hosted web app for printing labels to Brother QL series printers"
 readme = "README.md"
 requires-python = ">=3.12"

From ce4e6f9e4356cbe1a845fcdd2a5a33de5d083f07 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 10:41:52 -0700
Subject: [PATCH 81/84] fix: scrub CR/LF from user values in log lines (CWE-117
 log injection)

Add a scrub() helper and apply it to the user-influenced values that reach
log calls flagged by CodeQL py/log-injection: the history job_id path param
and the requested label media on media-mismatch warnings.
---
 CHANGELOG.md                                |  8 ++++++++
 backend/labelforge/logutil.py               | 11 +++++++++++
 backend/labelforge/routes/history.py        |  3 ++-
 backend/labelforge/routes/print.py          |  5 +++--
 backend/labelforge/routes/template_print.py |  9 +++++----
 5 files changed, 29 insertions(+), 7 deletions(-)
 create mode 100644 backend/labelforge/logutil.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c9b599..1e986c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
 
 ## [0.1.0] — 2026-06-06
 
+### Security
+
+- **Log-injection hardening (CWE-117)** — user-influenced values that reach a log line
+  (the history `job_id` path parameter and the requested label media on a media-mismatch
+  warning) are now passed through a `scrub()` helper that strips CR/LF before interpolation,
+  so a crafted value can't forge additional log entries. No behaviour change for legitimate
+  input.
+
 ### Added
 
 - **Friendly template names** — when creating a template, type a human-readable name (e.g.
diff --git a/backend/labelforge/logutil.py b/backend/labelforge/logutil.py
new file mode 100644
index 0000000..9ebe628
--- /dev/null
+++ b/backend/labelforge/logutil.py
@@ -0,0 +1,11 @@
+"""Helpers for safely logging user-influenced values."""
+
+
+def scrub(value: object) -> str:
+    """Strip CR/LF from a value before it is interpolated into a log line.
+
+    A user-controlled value written verbatim into a log can forge new log
+    entries (CWE-117 / log injection) by smuggling newlines. Removing the
+    line-break characters neutralises that without otherwise altering the value.
+    """
+    return str(value).replace("\r\n", "").replace("\r", "").replace("\n", "")
diff --git a/backend/labelforge/routes/history.py b/backend/labelforge/routes/history.py
index eeb9e51..d25c238 100644
--- a/backend/labelforge/routes/history.py
+++ b/backend/labelforge/routes/history.py
@@ -8,6 +8,7 @@
 from labelforge.config import settings
 from labelforge.db import get_connection
 from labelforge.history import insert_job_with_preview
+from labelforge.logutil import scrub
 from labelforge.models import HistoryDetail, HistoryItem, PinRequest, QuickPrintRequest
 from labelforge.printer.client import PrintError, print_image
 from labelforge.render.template import render_template
@@ -245,4 +246,4 @@ async def delete_history(job_id: int) -> None:
         try:
             (settings.data_dir / "label-previews" / row["preview_path"]).unlink(missing_ok=True)
         except Exception:
-            logger.warning("Could not delete preview file for job %d", job_id, exc_info=True)
+            logger.warning("Could not delete preview file for job %s", scrub(job_id), exc_info=True)
diff --git a/backend/labelforge/routes/print.py b/backend/labelforge/routes/print.py
index 6b88fd6..12e214e 100644
--- a/backend/labelforge/routes/print.py
+++ b/backend/labelforge/routes/print.py
@@ -6,6 +6,7 @@
 from labelforge.catalog.loader import get_label
 from labelforge.config import settings
 from labelforge.history import insert_job_with_preview
+from labelforge.logutil import scrub
 from labelforge.models import PrintJobResponse, QuickPrintRequest
 from labelforge.printer.client import (
     PrintError,
@@ -82,8 +83,8 @@ async def quick_print(request: QuickPrintRequest, override: bool = False) -> Pri
                     )
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
-                    media_id,
-                    request.label_media,
+                    scrub(media_id),
+                    scrub(request.label_media),
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
diff --git a/backend/labelforge/routes/template_print.py b/backend/labelforge/routes/template_print.py
index 9fd3fdd..9329b79 100644
--- a/backend/labelforge/routes/template_print.py
+++ b/backend/labelforge/routes/template_print.py
@@ -9,6 +9,7 @@
 from labelforge.catalog.loader import get_label
 from labelforge.config import settings
 from labelforge.history import insert_job_with_preview
+from labelforge.logutil import scrub
 from labelforge.models import (
     BatchJobResult,
     BatchPrintRequest,
@@ -128,8 +129,8 @@ async def print_template(name: str, body: PrintRequest, override: bool = False)
                     )
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
-                    media_id,
-                    effective_media,
+                    scrub(media_id),
+                    scrub(effective_media),
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")
@@ -250,8 +251,8 @@ async def batch_print(
                     )
                 logger.warning(
                     "Media mismatch (override): loaded=%s expected=%s",
-                    media_id,
-                    effective_media,
+                    scrub(media_id),
+                    scrub(effective_media),
                 )
         except StatusUnavailable:
             logger.warning("Printer status unavailable; proceeding without check")

From 102c2c3cd7b1e1fabb7e565d906e63cb622ce498 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 10:51:59 -0700
Subject: [PATCH 82/84] fix: document intentionally-empty except handlers
 (CodeQL py/empty-except)

Add explanatory comments to the shutdown-task cancellation and malformed-payload
handlers, and log the best-effort printer-socket close at debug instead of pass.
---
 CHANGELOG.md                         | 4 ++++
 backend/labelforge/main.py           | 1 +
 backend/labelforge/printer/client.py | 4 ++--
 backend/labelforge/routes/history.py | 1 +
 4 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e986c5..d3f5b49 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
   warning) are now passed through a `scrub()` helper that strips CR/LF before interpolation,
   so a crafted value can't forge additional log entries. No behaviour change for legitimate
   input.
+- **Code-scanning cleanup** — documented three intentionally-empty exception handlers flagged
+  by CodeQL `py/empty-except` (shutdown-task cancellation, best-effort printer-socket close,
+  malformed stored-payload fallback); the socket-close handler now logs at debug instead of
+  silently swallowing. No behaviour change.
 
 ### Added
 
diff --git a/backend/labelforge/main.py b/backend/labelforge/main.py
index 4c635d5..2350ab5 100644
--- a/backend/labelforge/main.py
+++ b/backend/labelforge/main.py
@@ -79,6 +79,7 @@ async def _retention_loop() -> None:
     try:
         await retention_task
     except asyncio.CancelledError:
+        # Expected: the task we just cancelled re-raises CancelledError on await.
         pass
 
 
diff --git a/backend/labelforge/printer/client.py b/backend/labelforge/printer/client.py
index f8947d0..01abdca 100644
--- a/backend/labelforge/printer/client.py
+++ b/backend/labelforge/printer/client.py
@@ -171,8 +171,8 @@ def status_read(host: str, backend: str, timeout_ms: int = 2000) -> dict:
             if printer is not None:
                 try:
                     printer.s.close()
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.debug("Failed to close printer socket cleanly: %s", exc)
     except Exception as exc:
         logger.debug("TCP status path failed: %s", exc)
 
diff --git a/backend/labelforge/routes/history.py b/backend/labelforge/routes/history.py
index d25c238..e381c55 100644
--- a/backend/labelforge/routes/history.py
+++ b/backend/labelforge/routes/history.py
@@ -47,6 +47,7 @@ def _row_to_detail(row) -> HistoryDetail:
         try:
             payload = json.loads(row["payload_json"])
         except Exception:
+            # Malformed stored payload — return the row without the decoded payload.
             pass
     return HistoryDetail(**item.model_dump(), payload_json=payload)
 

From b82da2666bfc80828ea3cff066939bcf77ab8770 Mon Sep 17 00:00:00 2001
From: Matthew Andersen <mander@crzynet.com>
Date: Sat, 6 Jun 2026 11:00:51 -0700
Subject: [PATCH 83/84] fix: don't expose exception detail in printer-status
 503 (CodeQL py/stack-trace-exposure)

Log the StatusUnavailable exception server-side and return a generic message
instead of str(exc) in the GET /api/printer/status error body.
---
 CHANGELOG.md                         | 4 ++++
 backend/labelforge/routes/printer.py | 8 ++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d3f5b49..d487f7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,10 @@ All notable changes to labelforge are recorded here. Format follows [Keep a Chan
   by CodeQL `py/empty-except` (shutdown-task cancellation, best-effort printer-socket close,
   malformed stored-payload fallback); the socket-close handler now logs at debug instead of
   silently swallowing. No behaviour change.
+- **No exception detail in the printer-status error response (CWE-209)** — `GET /api/printer/status`
+  returned the raw exception text in its 503 body when status was unavailable, which CodeQL
+  flagged as information exposure. It now logs the exception server-side and returns a generic
+  "Printer status is currently unavailable." message.
 
 ### Added
 
diff --git a/backend/labelforge/routes/printer.py b/backend/labelforge/routes/printer.py
index 7d85c32..d3df5cf 100644
--- a/backend/labelforge/routes/printer.py
+++ b/backend/labelforge/routes/printer.py
@@ -23,10 +23,14 @@ async def get_printer_status() -> dict | JSONResponse:
             backend=settings.printer_backend,
             timeout_ms=timeout_ms,
         )
-    except StatusUnavailable as exc:
+    except StatusUnavailable:
+        logger.exception("Printer status unavailable")
         return JSONResponse(
             status_code=503,
-            content={"error": "status_unavailable", "message": str(exc)},
+            content={
+                "error": "status_unavailable",
+                "message": "Printer status is currently unavailable.",
+            },
         )
 
     media_id = status["media_id"]

From 9c7bd95eb8bc44a4f8ebbc43f54a577eceeb3f9a Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Sat, 6 Jun 2026 18:04:51 +0000
Subject: [PATCH 84/84] Bump: Bump fabric from 6.6.1 to 7.4.0 in /frontend

Bumps [fabric](https://github.com/fabricjs/fabric.js) from 6.6.1 to 7.4.0.
- [Release notes](https://github.com/fabricjs/fabric.js/releases)
- [Changelog](https://github.com/fabricjs/fabric.js/blob/master/CHANGELOG.md)
- [Commits](https://github.com/fabricjs/fabric.js/commits)

---
updated-dependencies:
- dependency-name: fabric
  dependency-version: 7.4.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 frontend/package-lock.json | 1580 ++++++++++++------------------------
 frontend/package.json      |    2 +-
 2 files changed, 510 insertions(+), 1072 deletions(-)

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index f61178b..b22926e 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -6,13 +6,142 @@
     "": {
       "name": "labelforge-frontend",
       "dependencies": {
-        "fabric": "6.6.1"
+        "fabric": "7.4.0"
       },
       "devDependencies": {
         "typescript": "^5.7.2",
         "vite": "^6.3.5"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-3.2.0.tgz",
+      "integrity": "sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@csstools/css-calc": "^2.1.3",
+        "@csstools/css-color-parser": "^3.0.9",
+        "@csstools/css-parser-algorithms": "^3.0.4",
+        "@csstools/css-tokenizer": "^3.0.3",
+        "lru-cache": "^10.4.3"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-5.1.0.tgz",
+      "integrity": "sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "optional": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-2.1.4.tgz",
+      "integrity": "sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-3.1.0.tgz",
+      "integrity": "sha512-nbtKwh3a6xNVIp/VRuXV64yTKnb1IjTAEEh3irzS+HkKjAOYLTGNb9pmVNntZ8iVBHcWDA2Dof0QtPgFI1BaTA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@csstools/color-helpers": "^5.1.0",
+        "@csstools/css-calc": "^2.1.4"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^3.0.5",
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "3.0.5",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-3.0.5.tgz",
+      "integrity": "sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^3.0.4"
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-3.0.4.tgz",
+      "integrity": "sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@esbuild/aix-ppc64": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
@@ -455,27 +584,6 @@
         "node": ">=18"
       }
     },
-    "node_modules/@mapbox/node-pre-gyp": {
-      "version": "1.0.11",
-      "resolved": "https://registry.npmjs.org/@mapbox/node-pre-gyp/-/node-pre-gyp-1.0.11.tgz",
-      "integrity": "sha512-Yhlar6v9WQgUp/He7BdgzOz8lqMQ8sU+jkCq7Wx8Myc5YFJLbEe7lgui/V7G1qB1DJykHSGwreceSaD60Y0PUQ==",
-      "license": "BSD-3-Clause",
-      "optional": true,
-      "dependencies": {
-        "detect-libc": "^2.0.0",
-        "https-proxy-agent": "^5.0.0",
-        "make-dir": "^3.1.0",
-        "node-fetch": "^2.6.7",
-        "nopt": "^5.0.0",
-        "npmlog": "^5.0.1",
-        "rimraf": "^3.0.2",
-        "semver": "^7.3.5",
-        "tar": "^6.1.11"
-      },
-      "bin": {
-        "node-pre-gyp": "bin/node-pre-gyp"
-      }
-    },
     "node_modules/@rollup/rollup-android-arm-eabi": {
       "version": "4.60.4",
       "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
@@ -568,9 +676,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -585,9 +690,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -602,9 +704,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -619,9 +718,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -636,9 +732,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -653,9 +746,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -670,9 +760,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -687,9 +774,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -704,9 +788,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -721,9 +802,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -738,9 +816,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -755,9 +830,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -772,9 +844,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -865,16 +934,6 @@
         "win32"
       ]
     },
-    "node_modules/@tootallnate/once": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/@tootallnate/once/-/once-2.0.1.tgz",
-      "integrity": "sha512-HqmEUIGRJ5fSXchkVgR5F7qn48bDBzv0kWj/Kfu5e6uci4UlEeng4331LnBkWffb++Ei3FOVLxo8JJWMFBDMeQ==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 10"
-      }
-    },
     "node_modules/@types/estree": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -882,245 +941,122 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/abab": {
-      "version": "2.0.6",
-      "resolved": "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz",
-      "integrity": "sha512-j2afSsaIENvHZN2B8GOpF566vZ5WVk5opAiMTvWgaQT8DkbOqsTfvNAvHoRGU2zzP8cPoqys+xHTRDWW8L+/BA==",
-      "deprecated": "Use your platform's native atob() and btoa() methods instead",
-      "license": "BSD-3-Clause",
-      "optional": true
-    },
-    "node_modules/abbrev": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
-      "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==",
-      "license": "ISC",
-      "optional": true
-    },
-    "node_modules/acorn": {
-      "version": "8.16.0",
-      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
-      "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
-      "license": "MIT",
-      "optional": true,
-      "bin": {
-        "acorn": "bin/acorn"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
-    "node_modules/acorn-globals": {
-      "version": "7.0.1",
-      "resolved": "https://registry.npmjs.org/acorn-globals/-/acorn-globals-7.0.1.tgz",
-      "integrity": "sha512-umOSDSDrfHbTNPuNpC2NSnnA3LUrqpevPb4T9jRx4MagXNS0rs+gwiTcAvqCRmsD6utzsrzNt+ebm00SNWiC3Q==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "acorn": "^8.1.0",
-        "acorn-walk": "^8.0.2"
-      }
-    },
-    "node_modules/acorn-walk": {
-      "version": "8.3.5",
-      "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz",
-      "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "acorn": "^8.11.0"
-      },
-      "engines": {
-        "node": ">=0.4.0"
-      }
-    },
     "node_modules/agent-base": {
-      "version": "6.0.2",
-      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",
-      "integrity": "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "debug": "4"
-      },
-      "engines": {
-        "node": ">= 6.0.0"
-      }
-    },
-    "node_modules/ansi-regex": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
-      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "version": "7.1.4",
+      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+      "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
       "license": "MIT",
       "optional": true,
       "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/aproba": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/aproba/-/aproba-2.1.0.tgz",
-      "integrity": "sha512-tLIEcj5GuR2RSTnxNKdkK0dJ/GrC7P38sUkiDmDuHfsHmbagTFAxDVIBltoklXEVIQ/f14IL8IMJ5pn9Hez1Ew==",
-      "license": "ISC",
-      "optional": true
-    },
-    "node_modules/are-we-there-yet": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-2.0.0.tgz",
-      "integrity": "sha512-Ci/qENmwHnsYo9xKIcUJN5LeDKdJ6R1Z1j9V/J5wyq8nh/mYPEpIKJbBZXtZjG04HiK7zV/p6Vs9952MrMeUIw==",
-      "deprecated": "This package is no longer supported.",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "delegates": "^1.0.0",
-        "readable-stream": "^3.6.0"
-      },
-      "engines": {
-        "node": ">=10"
+        "node": ">= 14"
       }
     },
-    "node_modules/asynckit": {
-      "version": "0.4.0",
-      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
-      "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/balanced-match": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
-      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+    "node_modules/base64-js": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
       "license": "MIT",
       "optional": true
     },
-    "node_modules/brace-expansion": {
-      "version": "1.1.14",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
-      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
+    "node_modules/bl": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
+      "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "balanced-match": "^1.0.0",
-        "concat-map": "0.0.1"
+        "buffer": "^5.5.0",
+        "inherits": "^2.0.4",
+        "readable-stream": "^3.4.0"
       }
     },
-    "node_modules/call-bind-apply-helpers": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
-      "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+    "node_modules/buffer": {
+      "version": "5.7.1",
+      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
+      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "es-errors": "^1.3.0",
-        "function-bind": "^1.1.2"
-      },
-      "engines": {
-        "node": ">= 0.4"
+        "base64-js": "^1.3.1",
+        "ieee754": "^1.1.13"
       }
     },
     "node_modules/canvas": {
-      "version": "2.11.2",
-      "resolved": "https://registry.npmjs.org/canvas/-/canvas-2.11.2.tgz",
-      "integrity": "sha512-ItanGBMrmRV7Py2Z+Xhs7cT+FNt5K0vPL4p9EZ/UX/Mu7hFbkxSjKF2KVtPwX7UYWp7dRKnrTvReflgrItJbdw==",
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/canvas/-/canvas-3.2.3.tgz",
+      "integrity": "sha512-PzE5nJZPz72YUAfo8oTp0u3fqqY7IzlTubneAihqDYAUcBk7ryeCmBbdJBEdaH0bptSOe2VT2Zwcb3UaFyaSWw==",
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "@mapbox/node-pre-gyp": "^1.0.0",
-        "nan": "^2.17.0",
-        "simple-get": "^3.0.3"
+        "node-addon-api": "^7.0.0",
+        "prebuild-install": "^7.1.3"
       },
       "engines": {
-        "node": ">=6"
+        "node": "^18.12.0 || >= 20.9.0"
       }
     },
     "node_modules/chownr": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/chownr/-/chownr-2.0.0.tgz",
-      "integrity": "sha512-bIomtDF5KGpdogkLd9VspvFzk9KfpyyGlS8YFVZl7TGPBHL5snIOnxeshwVgPteQ9b4Eydl+pVbIyE1DcvCWgQ==",
-      "license": "ISC",
-      "optional": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/color-support": {
-      "version": "1.1.3",
-      "resolved": "https://registry.npmjs.org/color-support/-/color-support-1.1.3.tgz",
-      "integrity": "sha512-qiBjkpbMLO/HL68y+lh4q0/O1MZFj2RX6X/KmMa3+gJD3z+WwI1ZzDHysvqHGS3mP6mznPckpXmw1nI9cJjyRg==",
-      "license": "ISC",
-      "optional": true,
-      "bin": {
-        "color-support": "bin.js"
-      }
-    },
-    "node_modules/combined-stream": {
-      "version": "1.0.8",
-      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
-      "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "delayed-stream": "~1.0.0"
-      },
-      "engines": {
-        "node": ">= 0.8"
-      }
-    },
-    "node_modules/concat-map": {
-      "version": "0.0.1",
-      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
-      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/console-control-strings": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/console-control-strings/-/console-control-strings-1.1.0.tgz",
-      "integrity": "sha512-ty/fTekppD2fIwRvnZAVdeOiGd1c7YXEixbgJTNzqcxJWKQnjJ/V1bNEEE6hygpM3WjwHFUVK6HTjWSzV4a8sQ==",
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz",
+      "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==",
       "license": "ISC",
       "optional": true
     },
-    "node_modules/cssom": {
-      "version": "0.5.0",
-      "resolved": "https://registry.npmjs.org/cssom/-/cssom-0.5.0.tgz",
-      "integrity": "sha512-iKuQcq+NdHqlAcwUY0o/HL69XQrUaQdMjmStJ8JFmUaiiQErlhrmuigkg/CU4E2J0IyUKUrMAgl36TvN67MqTw==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/cssstyle": {
-      "version": "2.3.0",
-      "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-2.3.0.tgz",
-      "integrity": "sha512-AZL67abkUzIuvcHqk7c09cezpGNcxUxU4Ioi/05xHk4DQeTkWmGYftIE6ctU6AEt+Gn4n1lDStOtj7FKycP71A==",
+      "version": "4.6.0",
+      "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-4.6.0.tgz",
+      "integrity": "sha512-2z+rWdzbbSZv6/rhtvzvqeZQHrBaqgogqt85sqFNbabZOuFbCVFb8kPeEtZjiKkbrm395irpNKiYeFeLiQnFPg==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "cssom": "~0.3.6"
+        "@asamuzakjp/css-color": "^3.2.0",
+        "rrweb-cssom": "^0.8.0"
       },
       "engines": {
-        "node": ">=8"
+        "node": ">=18"
       }
     },
-    "node_modules/cssstyle/node_modules/cssom": {
-      "version": "0.3.8",
-      "resolved": "https://registry.npmjs.org/cssom/-/cssom-0.3.8.tgz",
-      "integrity": "sha512-b0tGHbfegbhPJpxpiBPU2sCkigAqtM9O121le6bbOlgyV+NyGyCmVfJ6QW9eRjz8CpNfWEOYBIMIGRYkLwsIYg==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/data-urls": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-3.0.2.tgz",
-      "integrity": "sha512-Jy/tj3ldjZJo63sVAvg6LHt2mHvl4V6AgRAmNDtLdm7faqtsx+aJG42rsyCo9JCoRVKwPFzKlIPx3DIibwSIaQ==",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-5.0.0.tgz",
+      "integrity": "sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "abab": "^2.0.6",
-        "whatwg-mimetype": "^3.0.0",
-        "whatwg-url": "^11.0.0"
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^14.0.0"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/debug": {
@@ -1149,35 +1085,31 @@
       "optional": true
     },
     "node_modules/decompress-response": {
-      "version": "4.2.1",
-      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-4.2.1.tgz",
-      "integrity": "sha512-jOSne2qbyE+/r8G1VU+G/82LBs2Fs4LAsTiLSHOCOMZQl2OKZ6i8i4IyHemTe+/yIXOtTcRQMzPcgyhoFlqPkw==",
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
+      "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "mimic-response": "^2.0.0"
+        "mimic-response": "^3.1.0"
       },
       "engines": {
-        "node": ">=8"
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/delayed-stream": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
-      "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
+    "node_modules/deep-extend": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
+      "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
       "license": "MIT",
       "optional": true,
       "engines": {
-        "node": ">=0.4.0"
+        "node": ">=4.0.0"
       }
     },
-    "node_modules/delegates": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/delegates/-/delegates-1.0.0.tgz",
-      "integrity": "sha512-bd2L678uiWATM6m5Z1VzNCErI3jiGzt6HGY8OVICs40JQq/HALfbyNJmp0UDakEY4pMMaN0Ly5om/B1VI/+xfQ==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/detect-libc": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -1188,42 +1120,16 @@
         "node": ">=8"
       }
     },
-    "node_modules/domexception": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/domexception/-/domexception-4.0.0.tgz",
-      "integrity": "sha512-A2is4PLG+eeSfoTMA95/s4pvAoSo2mKtiM5jlHkAVewmiO8ISFTFKZjH7UAM1Atli/OT/7JHOrJRJiMKUZKYBw==",
-      "deprecated": "Use your platform's native DOMException instead",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "webidl-conversions": "^7.0.0"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
-    "node_modules/dunder-proto": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
-      "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+    "node_modules/end-of-stream": {
+      "version": "1.4.5",
+      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
+      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "call-bind-apply-helpers": "^1.0.1",
-        "es-errors": "^1.3.0",
-        "gopd": "^1.2.0"
-      },
-      "engines": {
-        "node": ">= 0.4"
+        "once": "^1.4.0"
       }
     },
-    "node_modules/emoji-regex": {
-      "version": "8.0.0",
-      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
-      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/entities": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
@@ -1237,55 +1143,6 @@
         "url": "https://github.com/fb55/entities?sponsor=1"
       }
     },
-    "node_modules/es-define-property": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
-      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
-    "node_modules/es-errors": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
-      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
-    "node_modules/es-object-atoms": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
-      "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "es-errors": "^1.3.0"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
-    "node_modules/es-set-tostringtag": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
-      "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "es-errors": "^1.3.0",
-        "get-intrinsic": "^1.2.6",
-        "has-tostringtag": "^1.0.2",
-        "hasown": "^2.0.2"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
@@ -1328,73 +1185,27 @@
         "@esbuild/win32-x64": "0.25.12"
       }
     },
-    "node_modules/escodegen": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/escodegen/-/escodegen-2.1.0.tgz",
-      "integrity": "sha512-2NlIDTwUWJN0mRPQOdtQBzbUHvdGY2P1VXSyU83Q3xKxM7WHX2Ql8dKq782Q9TgQUNOLEzEYu9bzLNj1q88I5w==",
-      "license": "BSD-2-Clause",
-      "optional": true,
-      "dependencies": {
-        "esprima": "^4.0.1",
-        "estraverse": "^5.2.0",
-        "esutils": "^2.0.2"
-      },
-      "bin": {
-        "escodegen": "bin/escodegen.js",
-        "esgenerate": "bin/esgenerate.js"
-      },
-      "engines": {
-        "node": ">=6.0"
-      },
-      "optionalDependencies": {
-        "source-map": "~0.6.1"
-      }
-    },
-    "node_modules/esprima": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz",
-      "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==",
-      "license": "BSD-2-Clause",
-      "optional": true,
-      "bin": {
-        "esparse": "bin/esparse.js",
-        "esvalidate": "bin/esvalidate.js"
-      },
-      "engines": {
-        "node": ">=4"
-      }
-    },
-    "node_modules/estraverse": {
-      "version": "5.3.0",
-      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
-      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
-      "license": "BSD-2-Clause",
-      "optional": true,
-      "engines": {
-        "node": ">=4.0"
-      }
-    },
-    "node_modules/esutils": {
+    "node_modules/expand-template": {
       "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
-      "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==",
-      "license": "BSD-2-Clause",
+      "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz",
+      "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==",
+      "license": "(MIT OR WTFPL)",
       "optional": true,
       "engines": {
-        "node": ">=0.10.0"
+        "node": ">=6"
       }
     },
     "node_modules/fabric": {
-      "version": "6.6.1",
-      "resolved": "https://registry.npmjs.org/fabric/-/fabric-6.6.1.tgz",
-      "integrity": "sha512-QrQkx6I7daFL/WdkrE8VOEiAr/ffLK36NQ0t/vNZt8P7QIXPpjT4HegjOatUW1G6vYlulX4pI1P/5NeqIgsDig==",
+      "version": "7.4.0",
+      "resolved": "https://registry.npmjs.org/fabric/-/fabric-7.4.0.tgz",
+      "integrity": "sha512-NalYDc3eifTl1C33zryQwpH6+XA/2ClxQrH9vkASkZw3tbkRmorpikhYMmxhUTmi7O3e9ODz0vOT8qfaCh9IVA==",
       "license": "MIT",
       "engines": {
-        "node": ">=16.20.0"
+        "node": ">=20.0.0"
       },
       "optionalDependencies": {
-        "canvas": "^2.11.2",
-        "jsdom": "^20.0.1"
+        "canvas": "^3.2.0",
+        "jsdom": "^26.1.0"
       }
     },
     "node_modules/fdir": {
@@ -1415,54 +1226,11 @@
         }
       }
     },
-    "node_modules/form-data": {
-      "version": "4.0.5",
-      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
-      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "asynckit": "^0.4.0",
-        "combined-stream": "^1.0.8",
-        "es-set-tostringtag": "^2.1.0",
-        "hasown": "^2.0.2",
-        "mime-types": "^2.1.12"
-      },
-      "engines": {
-        "node": ">= 6"
-      }
-    },
-    "node_modules/fs-minipass": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/fs-minipass/-/fs-minipass-2.1.0.tgz",
-      "integrity": "sha512-V/JgOLFCS+R6Vcq0slCuaeWEdNC3ouDlJMNIsacH2VtALiu9mV4LPrHc5cDl8k5aw6J8jwgWWpiTo5RYhmIzvg==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "minipass": "^3.0.0"
-      },
-      "engines": {
-        "node": ">= 8"
-      }
-    },
-    "node_modules/fs-minipass/node_modules/minipass": {
-      "version": "3.3.6",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
-      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/fs.realpath": {
+    "node_modules/fs-constants": {
       "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
-      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
-      "license": "ISC",
+      "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
+      "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
+      "license": "MIT",
       "optional": true
     },
     "node_modules/fsevents": {
@@ -1480,201 +1248,52 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
-    "node_modules/function-bind": {
-      "version": "1.1.2",
-      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
-      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
-      "license": "MIT",
-      "optional": true,
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
-    "node_modules/gauge": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/gauge/-/gauge-3.0.2.tgz",
-      "integrity": "sha512-+5J6MS/5XksCuXq++uFRsnUd7Ovu1XenbeuIuNRJxYWjgQbPuFhT14lAvsWfqfAmnwluf1OwMjz39HjfLPci0Q==",
-      "deprecated": "This package is no longer supported.",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "aproba": "^1.0.3 || ^2.0.0",
-        "color-support": "^1.1.2",
-        "console-control-strings": "^1.0.0",
-        "has-unicode": "^2.0.1",
-        "object-assign": "^4.1.1",
-        "signal-exit": "^3.0.0",
-        "string-width": "^4.2.3",
-        "strip-ansi": "^6.0.1",
-        "wide-align": "^1.1.2"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/get-intrinsic": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
-      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "call-bind-apply-helpers": "^1.0.2",
-        "es-define-property": "^1.0.1",
-        "es-errors": "^1.3.0",
-        "es-object-atoms": "^1.1.1",
-        "function-bind": "^1.1.2",
-        "get-proto": "^1.0.1",
-        "gopd": "^1.2.0",
-        "has-symbols": "^1.1.0",
-        "hasown": "^2.0.2",
-        "math-intrinsics": "^1.1.0"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
-    "node_modules/get-proto": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
-      "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "dunder-proto": "^1.0.1",
-        "es-object-atoms": "^1.0.0"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
-    "node_modules/glob": {
-      "version": "7.2.3",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
-      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
-      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "fs.realpath": "^1.0.0",
-        "inflight": "^1.0.4",
-        "inherits": "2",
-        "minimatch": "^3.1.1",
-        "once": "^1.3.0",
-        "path-is-absolute": "^1.0.0"
-      },
-      "engines": {
-        "node": "*"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
-    "node_modules/gopd": {
-      "version": "1.2.0",
-      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
-      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+    "node_modules/github-from-package": {
+      "version": "0.0.0",
+      "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz",
+      "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==",
       "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
-    "node_modules/has-symbols": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
-      "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
-    "node_modules/has-tostringtag": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
-      "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "has-symbols": "^1.0.3"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
-    "node_modules/has-unicode": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/has-unicode/-/has-unicode-2.0.1.tgz",
-      "integrity": "sha512-8Rf9Y83NBReMnx0gFzA8JImQACstCYWUplepDa9xprwwtmgEZUF0h/i5xSA625zB/I37EtrswSST6OXxwaaIJQ==",
-      "license": "ISC",
       "optional": true
     },
-    "node_modules/hasown": {
-      "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
-      "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "function-bind": "^1.1.2"
-      },
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
     "node_modules/html-encoding-sniffer": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-3.0.0.tgz",
-      "integrity": "sha512-oWv4T4yJ52iKrufjnyZPkrN0CH3QnrUqdB6In1g5Fe1mia8GmF36gnfNySxoZtxD5+NmYw1EElVXiBk93UeskA==",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz",
+      "integrity": "sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "whatwg-encoding": "^2.0.0"
+        "whatwg-encoding": "^3.1.1"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/http-proxy-agent": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-5.0.0.tgz",
-      "integrity": "sha512-n2hY8YdoRE1i7r6M0w9DIw5GgZN0G25P8zLCRQ8rjXtTU3vsNFBI/vWK/UIeE6g5MUUz6avwAPXmL6Fy9D/90w==",
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
+      "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "@tootallnate/once": "2",
-        "agent-base": "6",
-        "debug": "4"
+        "agent-base": "^7.1.0",
+        "debug": "^4.3.4"
       },
       "engines": {
-        "node": ">= 6"
+        "node": ">= 14"
       }
     },
     "node_modules/https-proxy-agent": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-5.0.1.tgz",
-      "integrity": "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==",
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+      "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "agent-base": "6",
+        "agent-base": "^7.1.2",
         "debug": "4"
       },
       "engines": {
-        "node": ">= 6"
+        "node": ">= 14"
       }
     },
     "node_modules/iconv-lite": {
@@ -1690,17 +1309,26 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/inflight": {
-      "version": "1.0.6",
-      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
-      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
-      "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "once": "^1.3.0",
-        "wrappy": "1"
-      }
+    "node_modules/ieee754": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
+      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "BSD-3-Clause",
+      "optional": true
     },
     "node_modules/inherits": {
       "version": "2.0.4",
@@ -1709,15 +1337,12 @@
       "license": "ISC",
       "optional": true
     },
-    "node_modules/is-fullwidth-code-point": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
-      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">=8"
-      }
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
+      "license": "ISC",
+      "optional": true
     },
     "node_modules/is-potential-custom-element-name": {
       "version": "1.0.1",
@@ -1727,44 +1352,38 @@
       "optional": true
     },
     "node_modules/jsdom": {
-      "version": "20.0.3",
-      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-20.0.3.tgz",
-      "integrity": "sha512-SYhBvTh89tTfCD/CRdSOm13mOBa42iTaTyfyEWBdKcGdPxPtLFBXuHR8XHb33YNYaP+lLbmSvBTsnoesCNJEsQ==",
+      "version": "26.1.0",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-26.1.0.tgz",
+      "integrity": "sha512-Cvc9WUhxSMEo4McES3P7oK3QaXldCfNWp7pl2NNeiIFlCoLr3kfq9kb1fxftiwk1FLV7CvpvDfonxtzUDeSOPg==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "abab": "^2.0.6",
-        "acorn": "^8.8.1",
-        "acorn-globals": "^7.0.0",
-        "cssom": "^0.5.0",
-        "cssstyle": "^2.3.0",
-        "data-urls": "^3.0.2",
-        "decimal.js": "^10.4.2",
-        "domexception": "^4.0.0",
-        "escodegen": "^2.0.0",
-        "form-data": "^4.0.0",
-        "html-encoding-sniffer": "^3.0.0",
-        "http-proxy-agent": "^5.0.0",
-        "https-proxy-agent": "^5.0.1",
+        "cssstyle": "^4.2.1",
+        "data-urls": "^5.0.0",
+        "decimal.js": "^10.5.0",
+        "html-encoding-sniffer": "^4.0.0",
+        "http-proxy-agent": "^7.0.2",
+        "https-proxy-agent": "^7.0.6",
         "is-potential-custom-element-name": "^1.0.1",
-        "nwsapi": "^2.2.2",
-        "parse5": "^7.1.1",
+        "nwsapi": "^2.2.16",
+        "parse5": "^7.2.1",
+        "rrweb-cssom": "^0.8.0",
         "saxes": "^6.0.0",
         "symbol-tree": "^3.2.4",
-        "tough-cookie": "^4.1.2",
-        "w3c-xmlserializer": "^4.0.0",
+        "tough-cookie": "^5.1.1",
+        "w3c-xmlserializer": "^5.0.0",
         "webidl-conversions": "^7.0.0",
-        "whatwg-encoding": "^2.0.0",
-        "whatwg-mimetype": "^3.0.0",
-        "whatwg-url": "^11.0.0",
-        "ws": "^8.11.0",
-        "xml-name-validator": "^4.0.0"
+        "whatwg-encoding": "^3.1.1",
+        "whatwg-mimetype": "^4.0.0",
+        "whatwg-url": "^14.1.1",
+        "ws": "^8.18.0",
+        "xml-name-validator": "^5.0.0"
       },
       "engines": {
-        "node": ">=14"
+        "node": ">=18"
       },
       "peerDependencies": {
-        "canvas": "^2.5.0"
+        "canvas": "^3.0.0"
       },
       "peerDependenciesMeta": {
         "canvas": {
@@ -1772,140 +1391,42 @@
         }
       }
     },
-    "node_modules/make-dir": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-3.1.0.tgz",
-      "integrity": "sha512-g3FeP20LNwhALb/6Cz6Dd4F2ngze0jz7tbzrD2wAV+o9FeNHe4rL+yK2md0J/fiSf1sa1ADhXqi5+oVwOM/eGw==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "semver": "^6.0.0"
-      },
-      "engines": {
-        "node": ">=8"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "node_modules/make-dir/node_modules/semver": {
-      "version": "6.3.1",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
-      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+    "node_modules/lru-cache": {
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
       "license": "ISC",
-      "optional": true,
-      "bin": {
-        "semver": "bin/semver.js"
-      }
-    },
-    "node_modules/math-intrinsics": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
-      "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 0.4"
-      }
-    },
-    "node_modules/mime-db": {
-      "version": "1.52.0",
-      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
-      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 0.6"
-      }
-    },
-    "node_modules/mime-types": {
-      "version": "2.1.35",
-      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
-      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "mime-db": "1.52.0"
-      },
-      "engines": {
-        "node": ">= 0.6"
-      }
+      "optional": true
     },
     "node_modules/mimic-response": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-2.1.0.tgz",
-      "integrity": "sha512-wXqjST+SLt7R009ySCglWBCFpjUygmCIfD790/kVbiGmUgfYGuB14PiTd5DwVxSV4NcYHjzMkoj5LjQZwTQLEA==",
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz",
+      "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==",
       "license": "MIT",
       "optional": true,
       "engines": {
-        "node": ">=8"
+        "node": ">=10"
       },
       "funding": {
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/minimatch": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
-      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "brace-expansion": "^1.1.7"
-      },
-      "engines": {
-        "node": "*"
-      }
-    },
-    "node_modules/minipass": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-5.0.0.tgz",
-      "integrity": "sha512-3FnjYuehv9k6ovOEbyOswadCDPX1piCfhV8ncmYtHOjuPwylVWsghTLo7rabjC3Rx5xD4HDx8Wm1xnMF7S5qFQ==",
-      "license": "ISC",
-      "optional": true,
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/minizlib": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz",
-      "integrity": "sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==",
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
       "license": "MIT",
       "optional": true,
-      "dependencies": {
-        "minipass": "^3.0.0",
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">= 8"
-      }
-    },
-    "node_modules/minizlib/node_modules/minipass": {
-      "version": "3.3.6",
-      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
-      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "yallist": "^4.0.0"
-      },
-      "engines": {
-        "node": ">=8"
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/mkdirp": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz",
-      "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==",
+    "node_modules/mkdirp-classic": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz",
+      "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==",
       "license": "MIT",
-      "optional": true,
-      "bin": {
-        "mkdirp": "bin/cmd.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
+      "optional": true
     },
     "node_modules/ms": {
       "version": "2.1.3",
@@ -1914,13 +1435,6 @@
       "license": "MIT",
       "optional": true
     },
-    "node_modules/nan": {
-      "version": "2.27.0",
-      "resolved": "https://registry.npmjs.org/nan/-/nan-2.27.0.tgz",
-      "integrity": "sha512-hC+0LidcL3XE4rp1C4H54KujgXKzbfyTngZTwBByQxsOxCEKZT0MPQ4hOKUH2jU1OYstqdDH4onyHPDzcV0XdQ==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/nanoid": {
       "version": "3.3.12",
       "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
@@ -1940,81 +1454,32 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
-    "node_modules/node-fetch": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz",
-      "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "whatwg-url": "^5.0.0"
-      },
-      "engines": {
-        "node": "4.x || >=6.0.0"
-      },
-      "peerDependencies": {
-        "encoding": "^0.1.0"
-      },
-      "peerDependenciesMeta": {
-        "encoding": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/node-fetch/node_modules/tr46": {
-      "version": "0.0.3",
-      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
-      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==",
+    "node_modules/napi-build-utils": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz",
+      "integrity": "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==",
       "license": "MIT",
       "optional": true
     },
-    "node_modules/node-fetch/node_modules/webidl-conversions": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
-      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==",
-      "license": "BSD-2-Clause",
-      "optional": true
-    },
-    "node_modules/node-fetch/node_modules/whatwg-url": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
-      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+    "node_modules/node-abi": {
+      "version": "3.92.0",
+      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.92.0.tgz",
+      "integrity": "sha512-KdHvFWZjEKDf0cakgFjebl371GPsISX2oZHcuyKqM7DtogIsHrqKeLTo8wBHxaXRAQlY2PsPlZmfo+9ZCxEREQ==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "tr46": "~0.0.3",
-        "webidl-conversions": "^3.0.0"
-      }
-    },
-    "node_modules/nopt": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/nopt/-/nopt-5.0.0.tgz",
-      "integrity": "sha512-Tbj67rffqceeLpcRXrT7vKAN8CwfPeIBgM7E6iBkmKLV7bEMwpGgYLGv0jACUsECaa/vuxP0IjEont6umdMgtQ==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "abbrev": "1"
-      },
-      "bin": {
-        "nopt": "bin/nopt.js"
+        "semver": "^7.3.5"
       },
       "engines": {
-        "node": ">=6"
+        "node": ">=10"
       }
     },
-    "node_modules/npmlog": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/npmlog/-/npmlog-5.0.1.tgz",
-      "integrity": "sha512-AqZtDUWOMKs1G/8lwylVjrdYgqA4d9nu8hc+0gzRxlDb1I10+FHBGMXs6aiQHFdCUUlqH99MUMuLfzWDNDtfxw==",
-      "deprecated": "This package is no longer supported.",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "are-we-there-yet": "^2.0.0",
-        "console-control-strings": "^1.1.0",
-        "gauge": "^3.0.0",
-        "set-blocking": "^2.0.0"
-      }
+    "node_modules/node-addon-api": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/node-addon-api/-/node-addon-api-7.1.1.tgz",
+      "integrity": "sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==",
+      "license": "MIT",
+      "optional": true
     },
     "node_modules/nwsapi": {
       "version": "2.2.23",
@@ -2023,16 +1488,6 @@
       "license": "MIT",
       "optional": true
     },
-    "node_modules/object-assign": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
-      "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/once": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
@@ -2056,16 +1511,6 @@
         "url": "https://github.com/inikulin/parse5?sponsor=1"
       }
     },
-    "node_modules/path-is-absolute": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
-      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -2115,17 +1560,43 @@
         "node": "^10 || ^12 || >=14"
       }
     },
-    "node_modules/psl": {
-      "version": "1.15.0",
-      "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz",
-      "integrity": "sha512-JZd3gMVBAVQkSs6HdNZo9Sdo0LNcQeMNP3CozBJb3JYC/QUYZTnKxP+f8oWRX4rHP5EurWxqAHTSwUCjlNKa1w==",
+    "node_modules/prebuild-install": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
+      "integrity": "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==",
+      "deprecated": "No longer maintained. Please contact the author of the relevant native addon; alternatives are available.",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "punycode": "^2.3.1"
+        "detect-libc": "^2.0.0",
+        "expand-template": "^2.0.3",
+        "github-from-package": "0.0.0",
+        "minimist": "^1.2.3",
+        "mkdirp-classic": "^0.5.3",
+        "napi-build-utils": "^2.0.0",
+        "node-abi": "^3.3.0",
+        "pump": "^3.0.0",
+        "rc": "^1.2.7",
+        "simple-get": "^4.0.0",
+        "tar-fs": "^2.0.0",
+        "tunnel-agent": "^0.6.0"
       },
-      "funding": {
-        "url": "https://github.com/sponsors/lupomontero"
+      "bin": {
+        "prebuild-install": "bin.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/pump": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.4.tgz",
+      "integrity": "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "end-of-stream": "^1.1.0",
+        "once": "^1.3.1"
       }
     },
     "node_modules/punycode": {
@@ -2138,12 +1609,21 @@
         "node": ">=6"
       }
     },
-    "node_modules/querystringify": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz",
-      "integrity": "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==",
-      "license": "MIT",
-      "optional": true
+    "node_modules/rc": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",
+      "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==",
+      "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
+      "optional": true,
+      "dependencies": {
+        "deep-extend": "^0.6.0",
+        "ini": "~1.3.0",
+        "minimist": "^1.2.0",
+        "strip-json-comments": "~2.0.1"
+      },
+      "bin": {
+        "rc": "cli.js"
+      }
     },
     "node_modules/readable-stream": {
       "version": "3.6.2",
@@ -2160,30 +1640,6 @@
         "node": ">= 6"
       }
     },
-    "node_modules/requires-port": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
-      "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/rimraf": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz",
-      "integrity": "sha512-JZkJMZkAGFFPP2YqXZXPbMlMBgsxzE8ILs4lMIX/2o0L9UBw9O/Y3o6wFw/i9YLapcUJWwqbi3kdxIPdC62TIA==",
-      "deprecated": "Rimraf versions prior to v4 are no longer supported",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "glob": "^7.1.3"
-      },
-      "bin": {
-        "rimraf": "bin.js"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/rollup": {
       "version": "4.60.4",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
@@ -2229,6 +1685,13 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/rrweb-cssom": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.8.0.tgz",
+      "integrity": "sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/safe-buffer": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
@@ -2271,9 +1734,9 @@
       }
     },
     "node_modules/semver": {
-      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
-      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
+      "version": "7.8.2",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.2.tgz",
+      "integrity": "sha512-c8jsqUZm3omBOI66G90z1Dyw5z622G8oLG+omfsHBJf3CWQTlOcwOjvOG6wtiNfW6anKm/eA39LMwMtMez2TiQ==",
       "license": "ISC",
       "optional": true,
       "bin": {
@@ -2283,20 +1746,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/set-blocking": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
-      "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
-      "license": "ISC",
-      "optional": true
-    },
-    "node_modules/signal-exit": {
-      "version": "3.0.7",
-      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
-      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
-      "license": "ISC",
-      "optional": true
-    },
     "node_modules/simple-concat": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz",
@@ -2319,27 +1768,31 @@
       "optional": true
     },
     "node_modules/simple-get": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-3.1.1.tgz",
-      "integrity": "sha512-CQ5LTKGfCpvE1K0n2us+kuMPbk/q0EKl82s4aheV9oXjFEz6W/Y7oQFVJuU6QG77hRT4Ghb5RURteF5vnWjupA==",
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz",
+      "integrity": "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "decompress-response": "^4.2.0",
+        "decompress-response": "^6.0.0",
         "once": "^1.3.1",
         "simple-concat": "^1.0.0"
       }
     },
-    "node_modules/source-map": {
-      "version": "0.6.1",
-      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz",
-      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
-      "license": "BSD-3-Clause",
-      "optional": true,
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -2360,32 +1813,14 @@
         "safe-buffer": "~5.2.0"
       }
     },
-    "node_modules/string-width": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
-      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+    "node_modules/strip-json-comments": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
+      "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==",
       "license": "MIT",
       "optional": true,
-      "dependencies": {
-        "emoji-regex": "^8.0.0",
-        "is-fullwidth-code-point": "^3.0.0",
-        "strip-ansi": "^6.0.1"
-      },
       "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/strip-ansi": {
-      "version": "6.0.1",
-      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
-      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "ansi-regex": "^5.0.1"
-      },
-      "engines": {
-        "node": ">=8"
+        "node": ">=0.10.0"
       }
     },
     "node_modules/symbol-tree": {
@@ -2395,23 +1830,34 @@
       "license": "MIT",
       "optional": true
     },
-    "node_modules/tar": {
-      "version": "6.2.1",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-6.2.1.tgz",
-      "integrity": "sha512-DZ4yORTwrbTj/7MZYq2w+/ZFdI6OZ/f9SFHR+71gIVUZhOQPHzVCLpvRnPgyaMpfWxxk/4ONva3GQSyNIKRv6A==",
-      "deprecated": "Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
-      "license": "ISC",
+    "node_modules/tar-fs": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.4.tgz",
+      "integrity": "sha512-mDAjwmZdh7LTT6pNleZ05Yt65HC3E+NiQzl672vQG38jIrehtJk/J3mNwIg+vShQPcLF/LV7CMnDW6vjj6sfYQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "chownr": "^1.1.1",
+        "mkdirp-classic": "^0.5.2",
+        "pump": "^3.0.0",
+        "tar-stream": "^2.1.4"
+      }
+    },
+    "node_modules/tar-stream": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
+      "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
+      "license": "MIT",
       "optional": true,
       "dependencies": {
-        "chownr": "^2.0.0",
-        "fs-minipass": "^2.0.0",
-        "minipass": "^5.0.0",
-        "minizlib": "^2.1.1",
-        "mkdirp": "^1.0.3",
-        "yallist": "^4.0.0"
+        "bl": "^4.0.3",
+        "end-of-stream": "^1.4.1",
+        "fs-constants": "^1.0.0",
+        "inherits": "^2.0.3",
+        "readable-stream": "^3.1.1"
       },
       "engines": {
-        "node": ">=10"
+        "node": ">=6"
       }
     },
     "node_modules/tinyglobby": {
@@ -2431,33 +1877,63 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tldts": {
+      "version": "6.1.86",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-6.1.86.tgz",
+      "integrity": "sha512-WMi/OQ2axVTf/ykqCQgXiIct+mSQDFdH2fkwhPwgEwvJ1kSzZRiinb0zF2Xb8u4+OqPChmyI6MEu4EezNJz+FQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tldts-core": "^6.1.86"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "6.1.86",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-6.1.86.tgz",
+      "integrity": "sha512-Je6p7pkk+KMzMv2XXKmAE3McmolOQFdxkKw0R8EYNr7sELW46JqnNeTX8ybPiQgvg1ymCoF8LXs5fzFaZvJPTA==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/tough-cookie": {
-      "version": "4.1.4",
-      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-4.1.4.tgz",
-      "integrity": "sha512-Loo5UUvLD9ScZ6jh8beX1T6sO1w2/MpCRpEP7V280GKMVUQ0Jzar2U3UJPsrdbziLEMMhu3Ujnq//rhiFuIeag==",
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-5.1.2.tgz",
+      "integrity": "sha512-FVDYdxtnj0G6Qm/DhNPSb8Ju59ULcup3tuJxkFb5K8Bv2pUXILbf0xZWU8PX8Ov19OXljbUyveOFwRMwkXzO+A==",
       "license": "BSD-3-Clause",
       "optional": true,
       "dependencies": {
-        "psl": "^1.1.33",
-        "punycode": "^2.1.1",
-        "universalify": "^0.2.0",
-        "url-parse": "^1.5.3"
+        "tldts": "^6.1.32"
       },
       "engines": {
-        "node": ">=6"
+        "node": ">=16"
       }
     },
     "node_modules/tr46": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/tr46/-/tr46-3.0.0.tgz",
-      "integrity": "sha512-l7FvfAHlcmulp8kr+flpQZmVwtu7nfRV7NZujtN0OqES8EL4O4e0qqzL0DC5gAvx/ZC/9lk6rhcUwYvkBnBnYA==",
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-5.1.1.tgz",
+      "integrity": "sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "punycode": "^2.1.1"
+        "punycode": "^2.3.1"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
+      }
+    },
+    "node_modules/tunnel-agent": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",
+      "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "safe-buffer": "^5.0.1"
+      },
+      "engines": {
+        "node": "*"
       }
     },
     "node_modules/typescript": {
@@ -2474,27 +1950,6 @@
         "node": ">=14.17"
       }
     },
-    "node_modules/universalify": {
-      "version": "0.2.0",
-      "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.2.0.tgz",
-      "integrity": "sha512-CJ1QgKmNg3CwvAv/kOFmtnEN05f0D/cn9QntgNOQlQF9dgvVTHj3t+8JPdjqawCHk7V/KA+fbUqzZ9XWhcqPUg==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">= 4.0.0"
-      }
-    },
-    "node_modules/url-parse": {
-      "version": "1.5.10",
-      "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz",
-      "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "querystringify": "^2.1.1",
-        "requires-port": "^1.0.0"
-      }
-    },
     "node_modules/util-deprecate": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
@@ -2578,16 +2033,16 @@
       }
     },
     "node_modules/w3c-xmlserializer": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-4.0.0.tgz",
-      "integrity": "sha512-d+BFHzbiCx6zGfz0HyQ6Rg69w9k19nviJspaj4yNscGjrHu94sVP+aRm75yEbCh+r2/yR+7q6hux9LVtbuTGBw==",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "xml-name-validator": "^4.0.0"
+        "xml-name-validator": "^5.0.0"
       },
       "engines": {
-        "node": ">=14"
+        "node": ">=18"
       }
     },
     "node_modules/webidl-conversions": {
@@ -2601,9 +2056,9 @@
       }
     },
     "node_modules/whatwg-encoding": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-2.0.0.tgz",
-      "integrity": "sha512-p41ogyeMUrw3jWclHWTQg1k05DSVXPLcVxRTYsXUk+ZooOCZLcoYgPZ/HL/D/N+uQPOtcp1me1WhBEaX02mhWg==",
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz",
+      "integrity": "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==",
       "deprecated": "Use @exodus/bytes instead for a more spec-conformant and faster implementation",
       "license": "MIT",
       "optional": true,
@@ -2611,41 +2066,31 @@
         "iconv-lite": "0.6.3"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/whatwg-mimetype": {
-      "version": "3.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-3.0.0.tgz",
-      "integrity": "sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q==",
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz",
+      "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==",
       "license": "MIT",
       "optional": true,
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/whatwg-url": {
-      "version": "11.0.0",
-      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-11.0.0.tgz",
-      "integrity": "sha512-RKT8HExMpoYx4igMiVMY83lN6UeITKJlBQ+vR/8ZJ8OCdSiN3RwCq+9gH0+Xzj0+5IrM6i4j/6LuvzbZIQgEcQ==",
+      "version": "14.2.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-14.2.0.tgz",
+      "integrity": "sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "tr46": "^3.0.0",
+        "tr46": "^5.1.0",
         "webidl-conversions": "^7.0.0"
       },
       "engines": {
-        "node": ">=12"
-      }
-    },
-    "node_modules/wide-align": {
-      "version": "1.1.5",
-      "resolved": "https://registry.npmjs.org/wide-align/-/wide-align-1.1.5.tgz",
-      "integrity": "sha512-eDMORYaPNZ4sQIuuYPDHdQvf4gyCF9rEEV/yPxGfwPkRodwEgiMUUXTx/dex+Me0wxx53S+NgUHaP7y3MGlDmg==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "string-width": "^1.0.2 || 2 || 3 || 4"
+        "node": ">=18"
       }
     },
     "node_modules/wrappy": {
@@ -2656,9 +2101,9 @@
       "optional": true
     },
     "node_modules/ws": {
-      "version": "8.20.1",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.1.tgz",
-      "integrity": "sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==",
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
       "license": "MIT",
       "optional": true,
       "engines": {
@@ -2678,13 +2123,13 @@
       }
     },
     "node_modules/xml-name-validator": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-4.0.0.tgz",
-      "integrity": "sha512-ICP2e+jsHvAj2E2lIHxa5tjXRlKDJo4IdvPvCXbXQGdzSfmSpNVyIKMvoZHjDY9DP0zV17iI85o90vRFXNccRw==",
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
       "license": "Apache-2.0",
       "optional": true,
       "engines": {
-        "node": ">=12"
+        "node": ">=18"
       }
     },
     "node_modules/xmlchars": {
@@ -2693,13 +2138,6 @@
       "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
       "license": "MIT",
       "optional": true
-    },
-    "node_modules/yallist": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
-      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
-      "license": "ISC",
-      "optional": true
     }
   }
 }
diff --git a/frontend/package.json b/frontend/package.json
index 5d63f68..dea90db 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -8,7 +8,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "fabric": "6.6.1"
+    "fabric": "7.4.0"
   },
   "devDependencies": {
     "typescript": "^5.7.2",