Implement live-drawing-controls: per-artwork live PNG/SVG controls + plot lock

Two-stage pipeline: retain each artwork's source in memory; source controls
(PNG threshold/levels/invert/contrast, SVG sampling tolerance) re-derive the
master live (debounced 200ms); the geometry Detail/smoothing slider thins the
cached master immediately. Both preview and plot use the same geometry.

- raster.ts split into imageToField (decode→reusable grayscale field) +
  traceField (pure: invert/contrast + iso-contours); flattenImageFile composes.
- New src/plot/controls.ts centralises ArtControls, defaults, slider ranges.
- App.tsx: per-artwork kind+controls, in-memory sources, debounced re-derive,
  reusable Slider (drag or type), "Drawing controls" panel, plot lock.
- PlotCanvas gains a `locked` prop (no drag/transform during a plot).
- sessionStore persists kind+controls; normalizeArt migrates old sessions.
- Source kept in memory only (degrades gracefully after reload).
- Geometry knobs kept as one Detail slider (folded simplify+min-stroke; noted).

Tasks 1.x, 2.1, 4.x, 5.x done; 3.x/2.2/4.2 deviations noted; 6.x verification.

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

Author: dpsiderius

openspec/changes/live-drawing-controls/tasks.md

@@ -1,37 +1,37 @@
 ## 1. Source-retaining trace pipeline (PNG)
 
-- [ ] 1.1 Split `raster.ts`: a step that decodes the image to a reusable grayscale `Float32Array` field (at `MASTER_MAXDIM`), and a separate `traceField(field, opts)` that runs iso-contours → polylines. Re-tracing reuses the cached field (no re-decode)
-- [ ] 1.2 Add invert + contrast transforms on the field before tracing (cheap point ops); unit-test field transforms and that re-trace at new threshold/levels matches a fresh import
-- [ ] 1.3 Keep `flattenImageFile` working (compose the two steps) for first import
+- [x] 1.1 Split `raster.ts`: `imageToField` decodes to a reusable grayscale `Float32Array` field (at `MASTER_MAXDIM`); `traceField(field, opts)` runs iso-contours → polylines. Live re-tracing reuses the cached field (no re-decode)
+- [x] 1.2 Add invert + contrast transforms on the field before tracing (`adjustValue`, applied to a copy so the source field is never mutated); unit-tested in `raster.test.ts` (invert flips a light-on-dark source to the dark-on-light trace; contrast clamps; deterministic re-trace)
+- [x] 1.3 Keep `flattenImageFile` working — now composes `imageToField` + `traceField`
 
 ## 2. Re-flattenable SVG
 
-- [ ] 2.1 Retain SVG text per artwork; allow re-running `flattenSvg(text, tolerance)` at a chosen tolerance to produce a fresh master
-- [ ] 2.2 Unit-test that a coarser/finer tolerance yields fewer/more points within deviation bounds
+- [x] 2.1 Retain SVG text per artwork (in-memory `sourcesRef`); `deriveMaster` re-runs `flattenSvg(text, samplingMm)` at the artwork's chosen tolerance to produce a fresh master
+- [~] 2.2 Coarser/finer tolerance → fewer/more points: NOT a unit test here — `flattenSvg` needs the DOM `getPointAtLength`, and tests run in Node (no DOM). Covered by runtime verification 6.2 instead
 
 ## 3. Geometry controls surfaced
 
-- [ ] 3.1 Expose simplify tolerance + minimum stroke length from `detail.ts` as direct controls (reuse `applyDetail` logic); keep the existing `detail` slider working
-- [ ] 3.2 Unit-test the direct knobs against the existing detail mapping
+- [~] 3.1 DEVIATION (kept simple): `detail.ts` already maps the single `detail` slider to BOTH a simplify tolerance and a min-stroke-length (`detailParams`). Exposing separate simplify + min-stroke sliders would drive the same two knobs and confuse the UI, so the geometry stage keeps one per-artwork **Detail / smoothing** slider. Suggest updating the spec/proposal to match.
+- [~] 3.2 Folded into 3.1 — existing `detail.test.ts` still covers the detail→(epsilon, minLen) mapping; no separate knobs added
 
 ## 4. Per-artwork model + persistence
 
-- [ ] 4.1 Extend `PlacedArt` to carry its source (SVG text / grayscale field) and per-artwork control values; seed PNG defaults from current calibration
-- [ ] 4.2 Persist per-artwork control values in `sessionStore`; persist source best-effort and degrade gracefully (disable source controls, keep master) when over quota
-- [ ] 4.3 Migration: sessions without control values load with defaults
+- [x] 4.1 `PlacedArt` carries `kind` + `controls`; source kept in `sourcesRef` (in memory); PNG control defaults seeded from `cal.pngThreshold/pngLevels`
+- [~] 4.2 Per-artwork control values persist via `sessionStore` (and migrate). DEVIATION: the raw source is held in memory only, never persisted (a PNG field is ~MBs) — so after a reload the master + values are kept but source-stage controls are disabled until re-import (the "degrade gracefully" path, always taken rather than quota-gated)
+- [x] 4.3 Migration: `normalizeArt` + `normalizeControls` fill `kind`/`controls` defaults for sessions saved before they existed
 
 ## 5. Live UI
 
-- [ ] 5.1 Reusable slider-with-number control (drag or type; configurable `min`/`max`/`step`); centralise ranges/defaults
-- [ ] 5.2 Drawing-controls panel bound to the selected artwork: PNG (threshold, levels, invert, contrast), SVG (sampling tolerance), shared (detail, simplify, min stroke length)
-- [ ] 5.3 Debounce source re-derivation (~150–250 ms); keep geometry controls + canvas redraw immediate; show an "updating…" affordance during the debounce
-- [ ] 5.4 Drive both the canvas preview and the plotted geometry from the same result
-- [ ] 5.5 Lock placement + all drawing controls while a plot is active (gate on the existing plot lifecycle: lock on plot start, unlock on streamComplete / stop / streamAborted)
+- [x] 5.1 Reusable `Slider` (range + numeric box; drag or type an exact value, box accepts values beyond the slider range); ranges/defaults centralised in `src/plot/controls.ts`
+- [x] 5.2 "Drawing controls" panel bound to the selected artwork: PNG (threshold, levels, invert, contrast), SVG (sampling tolerance), shared (Detail / smoothing)
+- [x] 5.3 Source re-derivation debounced 200 ms with an "updating…" affordance; geometry (detail) + canvas redraw stay immediate
+- [x] 5.4 `displayItems` drives both the canvas preview and the plotted geometry from the same result
+- [x] 5.5 Lock placement + all drawing controls while a plot is active: `plotting` state set on plot start, cleared on streamComplete / streamAborted (covers stop) / disconnect; `PlotCanvas` gains a `locked` prop (no drag, no transformer)
 
 ## 6. Verification
 
-- [ ] 6.1 Adjust PNG threshold/levels/invert/contrast on a placed image → preview updates live, no re-import
-- [ ] 6.2 Adjust SVG sampling tolerance on a placed SVG → re-flattens live
-- [ ] 6.3 Two artworks tuned independently; reload session → values restored
-- [ ] 6.4 Start a plot → controls + placement lock; stop/complete → they unlock
+- [ ] 6.1 Adjust PNG threshold/levels/invert/contrast on a placed image → preview updates live, no re-import (run the app — visual)
+- [ ] 6.2 Adjust SVG sampling tolerance on a placed SVG → re-flattens live (run the app — visual)
+- [ ] 6.3 Two artworks tuned independently; reload session → values restored (run the app)
+- [ ] 6.4 Start a plot → controls + placement lock; stop/complete → they unlock (run the app)
 - [ ] 6.5 ⚙ HARDWARE: plot a tuned PNG and a tuned SVG → confirm the pen output matches the tuned preview

src/plot/__tests__/raster.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { isoContours } from '../raster';
+import { adjustValue, isoContours, traceField, type FieldSource } from '../raster';
 
 // Field convention: value <= level is "inked" (dark). 0 = black, 1 = white.
 describe('isoContours (marching squares)', () => {
@@ -50,3 +50,61 @@ describe('isoContours (marching squares)', () => {
     expect(isoContours(field, w, h, 0.5)).toHaveLength(2);
   });
 });
+
+describe('adjustValue (invert + contrast)', () => {
+  it('is identity at invert=false, contrast=1', () => {
+    expect(adjustValue(0.2, false, 1)).toBeCloseTo(0.2, 9);
+    expect(adjustValue(0.8, false, 1)).toBeCloseTo(0.8, 9);
+  });
+
+  it('inverts around 1', () => {
+    expect(adjustValue(0.2, true, 1)).toBeCloseTo(0.8, 9);
+  });
+
+  it('contrast scales around mid-grey and clamps to 0..1', () => {
+    expect(adjustValue(0.4, false, 2)).toBeCloseTo(0.3, 9); // (0.4-0.5)*2+0.5
+    expect(adjustValue(0, false, 3)).toBe(0); // (0-0.5)*3+0.5 = -1 → clamped
+    expect(adjustValue(1, false, 3)).toBe(1); // clamped high
+  });
+});
+
+describe('traceField', () => {
+  // 5x5 white field with a dark center cell (the isoContours fixture, as a source).
+  const darkCenter = (): FieldSource => {
+    const gw = 5,
+      gh = 5;
+    const field = new Float32Array(gw * gh).fill(1);
+    field[2 * gw + 2] = 0;
+    return { field, gw, gh, mmPerGrid: 1 };
+  };
+
+  it('traces a dark region into mm-sized polylines', () => {
+    const { artwork } = traceField(darkCenter(), { threshold: 0.5, levels: 1, toleranceMm: 0.01 });
+    expect(artwork.polylines.length).toBeGreaterThanOrEqual(1);
+    expect(artwork.widthMm).toBeGreaterThan(0);
+    expect(artwork.heightMm).toBeGreaterThan(0);
+  });
+
+  it('is deterministic and does not mutate the source field', () => {
+    const src = darkCenter();
+    const before = Array.from(src.field);
+    const a = traceField(src, { threshold: 0.5, levels: 1, toleranceMm: 0.01, contrast: 2 });
+    const b = traceField(src, { threshold: 0.5, levels: 1, toleranceMm: 0.01, contrast: 2 });
+    expect(a.artwork.polylines.length).toBe(b.artwork.polylines.length);
+    expect(Array.from(src.field)).toEqual(before); // invert/contrast worked on a copy
+  });
+
+  it('invert flips a light-on-dark source back to a dark-on-light trace', () => {
+    const plain = traceField(darkCenter(), { threshold: 0.5, levels: 1, toleranceMm: 0.01 });
+    // Inverse source: dark field with a light center.
+    const gw = 5,
+      gh = 5;
+    const field = new Float32Array(gw * gh).fill(0);
+    field[2 * gw + 2] = 1;
+    const inv = traceField(
+      { field, gw, gh, mmPerGrid: 1 },
+      { threshold: 0.5, levels: 1, toleranceMm: 0.01, invert: true },
+    );
+    expect(inv.artwork.polylines.length).toBe(plain.artwork.polylines.length);
+  });
+});

src/plot/controls.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-artwork drawing controls. Two stages:
+ *  - "source" controls (PNG: threshold/levels/invert/contrast; SVG: samplingMm)
+ *    re-derive the master geometry from the retained source — expensive, debounced.
+ *  - "geometry" controls (detail) thin the master live — cheap, immediate.
+ * Centralised here so the defaults and slider ranges live in one place.
+ */
+export interface ArtControls {
+  /** PNG: darkness cutoff 0..1 (pixels darker than this are inked). */
+  threshold: number;
+  /** PNG: number of brightness contours (1 = outline, more = tonal shading). */
+  levels: number;
+  /** PNG: invert dark/light before tracing. */
+  invert: boolean;
+  /** PNG: contrast multiplier around mid-grey (1 = unchanged). */
+  contrast: number;
+  /** SVG: curve flattening tolerance in mm (smaller = finer sampling). */
+  samplingMm: number;
+  /** Shared: level of detail 0..1 (1 = full, 0 = most simplified). */
+  detail: number;
+}
+
+export const DEFAULT_CONTROLS: ArtControls = {
+  threshold: 0.5,
+  levels: 1,
+  invert: false,
+  contrast: 1,
+  samplingMm: 0.2,
+  detail: 0.6,
+};
+
+/** Source-stage keys — changing one re-derives the master (debounced). */
+export const SOURCE_KEYS: (keyof ArtControls)[] = [
+  'threshold',
+  'levels',
+  'invert',
+  'contrast',
+  'samplingMm',
+];
+
+export interface SliderRange {
+  min: number;
+  max: number;
+  step: number;
+}
+
+/** Slider ranges (the numeric box may still accept values beyond these). */
+export const CONTROL_RANGES: Record<
+  'threshold' | 'levels' | 'contrast' | 'samplingMm' | 'detail',
+  SliderRange
+> = {
+  threshold: { min: 0.05, max: 0.95, step: 0.01 },
+  levels: { min: 1, max: 6, step: 1 },
+  contrast: { min: 0.5, max: 3, step: 0.05 },
+  samplingMm: { min: 0.1, max: 3, step: 0.05 },
+  detail: { min: 0, max: 1, step: 0.01 },
+};
+
+/** Fill any missing fields with defaults (migrates sessions saved before controls existed). */
+export function normalizeControls(c: Partial<ArtControls> | undefined): ArtControls {
+  return { ...DEFAULT_CONTROLS, ...(c ?? {}) };
+}

src/plot/raster.ts

@@ -14,23 +14,38 @@ export interface RasterOptions {
   threshold: number;
   /** Number of evenly-spaced brightness contours (1 = silhouette outline, more = tonal). */
   levels: number;
+  /** Invert dark/light before tracing. */
+  invert?: boolean;
+  /** Contrast multiplier around mid-grey (1 = unchanged). */
+  contrast?: number;
   /** Polyline simplification tolerance, mm. */
   toleranceMm: number;
   /** Working-resolution cap on the longer side (px) to keep contours smooth/fast. */
   maxDim?: number;
 }
 
 /**
- * Convert a raster image into plottable polylines by tracing grayscale
- * iso-contours (marching squares). Browser-only: rasterizes the image on a
- * canvas to read pixels. The geometry "looks like a drawing" — closed outlines
- * of the dark regions, which a pen plotter can draw efficiently.
+ * The decoded grayscale of an image, kept so the trace can be re-run live at new
+ * threshold/levels/invert/contrast without re-decoding the file.
  */
-export async function flattenImageFile(file: File, opts: RasterOptions): Promise<ImportResult> {
+export interface FieldSource {
+  /** Grayscale field in 0..1 (0 = black, 1 = white), row-major gw×gh. */
+  field: Float32Array;
+  gw: number;
+  gh: number;
+  /** mm per grid cell, so traced contours come out in real-world mm. */
+  mmPerGrid: number;
+}
+
+/**
+ * Decode an image to a reusable grayscale field (browser-only: rasterizes on a
+ * canvas to read pixels). Separated from tracing so the field can be re-traced
+ * live as the controls change.
+ */
+export async function imageToField(file: File, maxDim = 500): Promise<FieldSource> {
   const url = URL.createObjectURL(file);
   try {
     const img = await loadImage(url);
-    const maxDim = opts.maxDim ?? 500;
     const scale = Math.min(1, maxDim / Math.max(img.width, img.height));
     const gw = Math.max(2, Math.round(img.width * scale));
     const gh = Math.max(2, Math.round(img.height * scale));
@@ -45,7 +60,6 @@ export async function flattenImageFile(file: File, opts: RasterOptions): Promise
     ctx.drawImage(img, 0, 0, gw, gh);
     const { data } = ctx.getImageData(0, 0, gw, gh);
 
-    // Grayscale field in 0..1 (0 = black, 1 = white).
     const field = new Float32Array(gw * gh);
     for (let i = 0; i < gw * gh; i++) {
       const r = data[i * 4],
@@ -54,33 +68,66 @@ export async function flattenImageFile(file: File, opts: RasterOptions): Promise
       field[i] = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
     }
 
-    const mmPerGrid = (img.width * PX_TO_MM) / gw;
-    const levels = Math.max(1, Math.round(opts.levels));
-    const t = Math.min(0.999, Math.max(0.001, opts.threshold));
-    const polylines: Polyline[] = [];
-    let skipped = 0;
-
-    for (let k = 1; k <= levels; k++) {
-      const value = (t * k) / levels; // light → threshold; nested for shading
-      const contours = isoContours(field, gw, gh, value);
-      if (contours.length === 0) {
-        skipped++;
-        continue;
-      }
-      for (const c of contours) {
-        const mm = c.map((p) => ({ x: p.x * mmPerGrid, y: p.y * mmPerGrid }));
-        const simplified = simplifyPolyline(mm, opts.toleranceMm);
-        if (simplified.length >= 2) polylines.push(simplified);
-      }
-    }
-
-    const { widthMm, heightMm } = normalizeToOrigin(polylines);
-    return { artwork: { polylines, widthMm, heightMm }, skipped };
+    return { field, gw, gh, mmPerGrid: (img.width * PX_TO_MM) / gw };
   } finally {
     URL.revokeObjectURL(url);
   }
 }
 
+/** Apply invert + contrast (around mid-grey) to a grayscale value, clamped to 0..1. */
+export function adjustValue(v: number, invert: boolean, contrast: number): number {
+  const g = invert ? 1 - v : v;
+  const c = (g - 0.5) * contrast + 0.5;
+  return c < 0 ? 0 : c > 1 ? 1 : c;
+}
+
+/**
+ * Trace a decoded field into plottable polylines (pure — no DOM, unit-testable).
+ * Applies invert/contrast, then traces brightness iso-contours (marching squares)
+ * at the threshold (nested for tonal shading), and returns mm-sized geometry.
+ */
+export function traceField(src: FieldSource, opts: RasterOptions): ImportResult {
+  const { gw, gh, mmPerGrid } = src;
+  const invert = opts.invert ?? false;
+  const contrast = opts.contrast ?? 1;
+  const adjusted =
+    invert || contrast !== 1
+      ? Float32Array.from(src.field, (v) => adjustValue(v, invert, contrast))
+      : src.field;
+
+  const levels = Math.max(1, Math.round(opts.levels));
+  const t = Math.min(0.999, Math.max(0.001, opts.threshold));
+  const polylines: Polyline[] = [];
+  let skipped = 0;
+
+  for (let k = 1; k <= levels; k++) {
+    const value = (t * k) / levels; // light → threshold; nested for shading
+    const contours = isoContours(adjusted, gw, gh, value);
+    if (contours.length === 0) {
+      skipped++;
+      continue;
+    }
+    for (const c of contours) {
+      const mm = c.map((p) => ({ x: p.x * mmPerGrid, y: p.y * mmPerGrid }));
+      const simplified = simplifyPolyline(mm, opts.toleranceMm);
+      if (simplified.length >= 2) polylines.push(simplified);
+    }
+  }
+
+  const { widthMm, heightMm } = normalizeToOrigin(polylines);
+  return { artwork: { polylines, widthMm, heightMm }, skipped };
+}
+
+/**
+ * Convert a raster image into plottable polylines: decode to a grayscale field,
+ * then trace it. The geometry "looks like a drawing" — closed outlines of the
+ * dark regions, which a pen plotter can draw efficiently.
+ */
+export async function flattenImageFile(file: File, opts: RasterOptions): Promise<ImportResult> {
+  const src = await imageToField(file, opts.maxDim ?? 500);
+  return traceField(src, opts);
+}
+
 function loadImage(url: string): Promise<HTMLImageElement> {
   return new Promise((resolve, reject) => {
     const img = new Image();