Merge feature/003-print-mode-ux-fixes

Print Mode UX improvements + 3D preview based on user feedback after
the initial 002 release.

Issues fixed:
- #1 Compute/PDF error surfacing (sticky toast, console.error stack)
- #2 Explicit Add Window/Door/Closet buttons in feature panel
- #3 Location search via dedicated print-mode map picker
- #4 Numeric height/width/sill/horizontal-position inputs for features
- #5 Shift-drag snaps to 90° axis
- #6 Cmd/Ctrl-click multi-vertex select + drag together

Plus 4 follow-on items:
- Skip blank tiles (reverses original FR-014 — pages were too many)
- 2× hole diameters (12/8/5/2 mm — reads as actual stars at room scale)
- Remove star labels from printouts (cluttered the stencil)
- 3D preview tab — drag-to-rotate room view from observer's eye showing
  numbered paper sheets + projected star positions

Verification:
- 228 vitest tests pass
- 14 print-mode chromium e2e tests pass
- Build payload OK

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jeremymanning

src/print/pdf-builder.ts

@@ -293,6 +293,19 @@ export function buildPdf(
         const holes = holesByTile.get(key) ?? [];
         const featureCutouts = featuresByTile.get(key) ?? [];
         const constellationSegments = segmentsByTile.get(key) ?? [];
+        // Skip blank tiles — those that contain zero stars, zero
+        // feature cutouts, AND zero constellation-line segments.
+        // (FR-014 originally required emitting them; user feedback
+        // says page counts blow up — at 12 ft × 12 ft / Letter the
+        // ceiling alone is ~220 pages, with most blank near the
+        // horizon-far corners. Page numbers in the printed PDF stay
+        // contiguous because we increment pageNumber AFTER the skip
+        // decision; surface row/col labels still convey position.)
+        const isBlank =
+          holes.length === 0 &&
+          featureCutouts.length === 0 &&
+          constellationSegments.length === 0;
+        if (isBlank) continue;
         const tile: Tile = {
           surfaceId: surface.id,
           row: r,

src/print/preflight.ts

@@ -27,7 +27,7 @@ import {
   deriveSurfaces,
   projectBodyOntoSurface,
 } from "./projection";
-import { computeTileGrid } from "./tile-grid";
+import { assignHolesToTiles, computeTileGrid } from "./tile-grid";
 import {
   classifyMagnitude,
   type Hole,
@@ -126,25 +126,74 @@ export function computePreflightSummary(
     });
   }
 
-  // Tile-page counter: every enabled surface contributes rows × cols
-  // pages, even blank ones (FR-014, SC-013).
+  // Tile-page counter: count only NON-BLANK tiles. A tile is non-blank
+  // if it contains at least one hole OR overlaps a no-paint feature.
+  // (Per user feedback, FR-014's "blank tiles still emitted" rule was
+  // reversed — page counts at room-scale × paper-size were too high.)
   let tilePageCount = 0;
   // Per-class hole tallies across all enabled surfaces.
   const counts: Record<SizeClass, number> = { pencil: 0, largeNail: 0, smallNail: 0, pin: 0 };
   let totalHoles = 0;
 
   for (const surface of surfaces) {
     const grid = computeTileGrid(surface, job.outputOptions.paper);
-    tilePageCount += grid.rows * grid.cols;
+    const { rows, cols, cellWidthMm, cellHeightMm } = grid;
+    // Build the hole list for this surface using the same projection
+    // logic the builder uses. Then run the hole list through
+    // assignHolesToTiles so the same FR-012 ½″ split-window applies —
+    // this guarantees SC-008 (preflight count == actual page count).
+    const holesForSurface: Array<{
+      surfaceUMm: number;
+      surfaceVMm: number;
+      sizeClass: SizeClass;
+      label: string;
+      bodyKind: "star" | "planet" | "sun" | "moon";
+      apparentMag: number;
+    }> = [];
     for (const body of projectable) {
       const hits = projectBodyForSurface(body.altDeg, body.azDeg, surface, observerPosMm);
-      for (const _hit of hits) {
+      for (const hit of hits) {
         const cls = classifyMagnitude(body.mag);
         if (cls === null) continue;
         counts[cls] += 1;
         totalHoles += 1;
+        holesForSurface.push({
+          surfaceUMm: hit.uMm,
+          surfaceVMm: hit.vMm,
+          sizeClass: cls,
+          label: body.label,
+          bodyKind: body.bodyKind,
+          apparentMag: body.mag,
+        });
       }
     }
+    const holeBins = assignHolesToTiles(holesForSurface, surface, grid);
+    // No-paint features on this surface also keep their overlapping
+    // tiles non-blank (the dotted cut line still needs to be drawn).
+    const featuresOnSurface = job.room.features.filter(
+      (f) => f.surfaceId === surface.id && !f.paint,
+    );
+    const occupied = new Set<string>(holeBins.keys());
+    for (const feat of featuresOnSurface) {
+      let uMin = Infinity, uMax = -Infinity, vMin = Infinity, vMax = -Infinity;
+      for (const p of feat.outline) {
+        if (p.uMm < uMin) uMin = p.uMm;
+        if (p.uMm > uMax) uMax = p.uMm;
+        if (p.vMm < vMin) vMin = p.vMm;
+        if (p.vMm > vMax) vMax = p.vMm;
+      }
+      if (!Number.isFinite(uMin)) continue;
+      const c0 = Math.max(0, Math.floor(uMin / cellWidthMm));
+      const c1 = Math.min(cols - 1, Math.floor(uMax / cellWidthMm));
+      const r0 = Math.max(0, Math.floor(vMin / cellHeightMm));
+      const r1 = Math.min(rows - 1, Math.floor(vMax / cellHeightMm));
+      for (let r = r0; r <= r1; r++) {
+        for (let c = c0; c <= c1; c++) {
+          occupied.add(`${r},${c}`);
+        }
+      }
+    }
+    tilePageCount += occupied.size;
   }
 
   const surfaceCount = surfaces.length;

src/print/tile-page.ts

@@ -31,9 +31,6 @@ import {
   type Tile,
 } from "./types";
 
-/** Magnitude cutoff for emitting a small label under a hole on the tile. */
-const BRIGHT_LABEL_MAG_CUTOFF = 2.0;
-
 /** Length of each leg of the corner alignment L-marks. */
 const ALIGN_MARK_LEG_MM = 6;
 
@@ -210,12 +207,9 @@ export function emitTilePage(
     // Thin outer ring for B&W contrast (R9).
     doc.setDrawColor("0");
     doc.circle(cx, cy, radius + 0.25, "S");
-
-    // Optional small label under bright-magnitude holes.
-    if (h.apparentMag <= BRIGHT_LABEL_MAG_CUTOFF) {
-      doc.setFontSize(6);
-      doc.text(h.label, cx + radius + 0.5, cy + radius);
-    }
+    // Star labels intentionally omitted from printouts (per user
+    // feedback): names clutter the stencil and aren't useful when the
+    // user is cutting the holes by hand.
   }
 
   // ---- 6. Accessibility annotations (FR-021) ------------------------------

src/print/types.ts

@@ -18,12 +18,18 @@ export interface Vec3 {
 /** Hole-size encoding per FR-011 / R4 (cover-page legend = calibration). */
 export type SizeClass = "pencil" | "largeNail" | "smallNail" | "pin";
 
-/** Printed diameter (mm) per size class. */
+/**
+ * Printed diameter (mm) per size class. Doubled from the original
+ * R4 spec values per user feedback: at the original 6/4/2.5/1 mm
+ * sizes the printed holes were too small to read at typical room
+ * scale (8 ft ceiling, 12 ft room → eye-to-ceiling distance feels
+ * like a pinhole-projector). 12/8/5/2 mm reads as actual stars.
+ */
 export const HOLE_DIAMETERS_MM: Record<SizeClass, number> = {
-  pencil: 6,
-  largeNail: 4,
-  smallNail: 2.5,
-  pin: 1,
+  pencil: 12,
+  largeNail: 8,
+  smallNail: 5,
+  pin: 2,
 };
 
 /**

src/styles.css

@@ -1293,3 +1293,84 @@ body.red-light-active {
   }
 }
 
+/* --- Tab strip (Edit room / 3D preview) ----------------------------- */
+
+.print-mode-tab-strip {
+  display: flex;
+  gap: 4px;
+  margin-bottom: 8px;
+  border-bottom: 1px solid rgba(220, 228, 240, 0.12);
+}
+
+.print-mode-tab {
+  background: transparent;
+  color: var(--fg-muted);
+  border: 1px solid transparent;
+  border-bottom: none;
+  padding: 6px 12px;
+  font-family: var(--font-sans);
+  font-size: 13px;
+  cursor: pointer;
+  border-radius: 4px 4px 0 0;
+}
+
+.print-mode-tab:hover {
+  color: var(--fg);
+  background: rgba(240, 192, 64, 0.06);
+}
+
+.print-mode-tab-active {
+  color: var(--fg);
+  background: var(--accent-active);
+  border-color: rgba(240, 192, 64, 0.4);
+}
+
+.print-mode-tab-panel {
+  display: block;
+}
+
+.print-mode-tab-panel[hidden] {
+  display: none;
+}
+
+/* --- 3D preview ----------------------------------------------------- */
+
+.print-mode-preview-3d-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.print-mode-preview-3d-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.print-mode-preview-3d-status {
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+.print-mode-preview-3d-svg {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  height: auto;
+  background: var(--bg-night);
+  border: 1px solid rgba(220, 228, 240, 0.12);
+  border-radius: 4px;
+  cursor: grab;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.print-mode-preview-3d-svg:active {
+  cursor: grabbing;
+}
+
+.print-mode-preview-3d-hole {
+  filter: drop-shadow(0 0 1.5px rgba(255, 255, 255, 0.6));
+}
+

src/ui/print-mode/compute-progress.ts

@@ -154,17 +154,38 @@ export function mountComputeButton(host: HTMLElement, register: RegisterRefresh)
     }
   }
 
+  let errorClearTimer: ReturnType<typeof setTimeout> | null = null;
+
   function showError(msg: string): void {
     status.textContent = msg;
     status.classList.add("print-mode-status-error");
+    // Issue #1 — keep the error visible long enough to read & paste into a
+    // bug report. Previously the status was wiped out by the next refresh
+    // tick within ~4 s; we now hold it for 12 s before allowing clearStatus.
+    if (errorClearTimer !== null) clearTimeout(errorClearTimer);
+    errorClearTimer = setTimeout(() => {
+      errorClearTimer = null;
+    }, 12_000);
   }
 
   function clearStatus(): void {
+    // Don't clobber an error toast while it is still in its sticky window.
+    if (errorClearTimer !== null) return;
     status.textContent = "";
     status.classList.remove("print-mode-status-error");
   }
 
   function attachPdf(pdf: PdfBlob): void {
+    // Issue #1 — surface generation failures explicitly. If the builder
+    // returned an empty Blob (jsPDF internal failure) or both objectUrl
+    // and blob are unusable, the user previously saw a Download button
+    // that did nothing. Throw so the surrounding try/catch can present
+    // the error.
+    if (!pdf || !pdf.blob || pdf.blob.size === 0) {
+      throw new Error(
+        "PDF builder returned an empty document (Blob size = 0). This usually means jsPDF failed to render at least one tile.",
+      );
+    }
     // Revoke previous URL to avoid leaking blob memory across re-computes.
     if (lastPdf && lastPdf.objectUrl) {
       try {
@@ -186,13 +207,18 @@ export function mountComputeButton(host: HTMLElement, register: RegisterRefresh)
         url = "";
       }
     }
+    if (!url) {
+      throw new Error(
+        "PDF was generated but could not be exposed as a downloadable URL (URL.createObjectURL unavailable).",
+      );
+    }
     // Set both the property and the attribute so `getAttribute('href')`
     // works in every test environment (some Playwright contexts read the
     // attribute, not the property).
     downloadBtn.href = url;
     downloadBtn.setAttribute("href", url);
     downloadBtn.hidden = false;
-    status.textContent = `PDF ready — ${formatNumber(pdf.pageCount)} pages.`;
+    status.textContent = `PDF ready - ${formatNumber(pdf.pageCount)} pages.`;
     // Sync `lastJobSnapshot` to the current job. Otherwise the next
     // `refresh()` (fired by the persistence-debounce of the very
     // setObservation calls that happened during Compute) treats the
@@ -238,9 +264,15 @@ export function mountComputeButton(host: HTMLElement, register: RegisterRefresh)
       const pdf = await mod.buildPdf(job, skyDatasets, bodies);
       attachPdf(pdf);
     } catch (err) {
+      // Issue #1 — log the stack trace so users can paste it in a bug
+      // report. The status toast itself stays compact (just `message`).
       // eslint-disable-next-line no-console
-      console.error("print-mode: compute failed", err);
-      showError(err instanceof Error ? `Compute failed: ${err.message}` : "Compute failed.");
+      console.error("print-mode: compute failed", err, err instanceof Error ? err.stack : "");
+      const msg =
+        err instanceof Error && err.message
+          ? `Compute failed: ${err.message}`
+          : "Compute failed (see browser console for details).";
+      showError(msg);
     } finally {
       setBusy(false);
     }