@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/features/sticker-trace/components/StickerTraceStudio.js

@@ -0,0 +1,171 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Up to this point the tracer was logic with no surface — the codec, the
+ *      core and the live hook all worked and nobody could open them. This is
+ *      the first thing a human can actually tune a scan with.
+ * WHAT: Pick a local file, move the parameters, watch the outlines redraw.
+ *
+ * 🛑 The bytes NEVER leave the tab. The file goes straight into the canvas
+ * codec, so tuning costs no upload, no Storage object and no Function
+ * invocation — which is the whole reason the codec is a port. Uploading only
+ * happens later, when the operator commits to a run.
+ *
+ * EXPORTS: StickerTraceStudio
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:tools/sticker-tracer
+ * @tag sideEffects:none
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Card, FilePickerButton, Grid, Heading, Row, Section, Span, Stack, Text, } from "../../../ui/index.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FieldSelect } from "../../../ui/forms/FieldSelect.js";
+import { paramsForTier } from "../../../_internal/shared/features/sticker-trace/config.js";
+import { CUT_CONTOUR_CSS } from "../../../_internal/shared/features/sticker-trace/cut-contour.js";
+import { PARAM_HELP, TIER_HELP } from "../constants/help-content.js";
+import { useLiveTrace } from "../hooks/useLiveTrace.js";
+import { canvasCodec } from "../../../_internal/client/features/sticker-trace/canvas-codec.js";
+import { normalizeError } from "../../../errors/normalize.js";
+/*
+ * Only `draft` is offered. The hook runs on the main thread and draft's
+ * 1200px cap is what keeps one trace near a second; `standard`'s 3000 would
+ * block the tab for several. The heavier tiers are a property of a RUN, chosen
+ * when the operator commits — offering them here would be a control that
+ * freezes the page.
+ */
+const TIER = "draft";
+/**
+ * The four parameters worth a live control.
+ *
+ * 🛑 Deliberately NOT every parameter. `TraceParams` has two dozen members and
+ * a form of two dozen sliders is a form nobody reads — these are the four the
+ * corpus work actually moved when a scan came out wrong, and the rest keep
+ * their tier defaults. The full set belongs in the run's advanced panel, where
+ * it is edited deliberately rather than dragged.
+ */
+/*
+ * The four parameters worth a live control.
+ *
+ * 🛑 Deliberately NOT every parameter. `TraceParams` has two dozen members and
+ * a form of two dozen sliders is a form nobody reads — these are the four the
+ * corpus work actually moved when a scan came out wrong, and the rest keep
+ * their tier defaults.
+ *
+ * 🛑 The hint text comes from PARAM_HELP, not from a literal here. It used to
+ * be a second, shorter paraphrase of the same explanation, which is the copy
+ * that drifts: the inline hint is the one people actually read, so it has to be
+ * the same words the help panel shows.
+ */
+const CONTROLS = [
+    { key: "ridgeHysteresisLow", step: 0.01 },
+    { key: "ridgeHysteresisHigh", step: 0.01 },
+    { key: "paperTolerance", step: 1 },
+    { key: "minPartAreaMm2", step: 5 },
+];
+export function StickerTraceStudio({ renderCommit }) {
+    const [file, setFile] = useState(null);
+    const [source, setSource] = useState(null);
+    const [params, setParams] = useState(() => paramsForTier(TIER));
+    const canvasRef = useRef(null);
+    const { parts, diagnostics, raster, tracing, lastMs, error } = useLiveTrace(source, params);
+    /*
+     * The scan's natural size, probed once per file.
+     *
+     * Deliberately separate from the trace: `probe` reads the header only and
+     * does not decode pixels, so this costs nothing next to the trace itself —
+     * and it is the only number the commit flow may record as the scan's size.
+     */
+    const [natural, setNatural] = useState(null);
+    const [probeError, setProbeError] = useState(null);
+    useEffect(() => {
+        if (!source) {
+            setNatural(null);
+            return;
+        }
+        let live = true;
+        setProbeError(null);
+        void canvasCodec
+            .probe(source)
+            .then((p) => {
+            if (live)
+                setNatural({ widthPx: p.width, heightPx: p.height });
+        })
+            .catch((err) => {
+            const n = normalizeError(err);
+            // A failed probe must not silently fall back to the raster's size —
+            // that is the downscaled one, and a wrong scan size is invisible until
+            // a millimetre figure reaches a cut file. Null blocks the commit.
+            // Recorded on state rather than logged: this is a client component, and
+            // the operator is the one who needs to know the commit is blocked.
+            if (live) {
+                setNatural(null);
+                setProbeError(n.message);
+            }
+        });
+        return () => {
+            live = false;
+        };
+    }, [source]);
+    const onFile = useCallback((picked) => {
+        setFile(picked);
+        void picked.arrayBuffer().then((buf) => setSource(new Uint8Array(buf)));
+    }, []);
+    const setParam = useCallback((key, value) => {
+        setParams((p) => ({ ...p, [key]: value }));
+    }, []);
+    /*
+     * Draw the raster, then stroke every part's outline over it.
+     *
+     * 🛑 The outlines are stroked from the BÉZIER PATHS, not from the alpha
+     * masks. A mask would show what the rasteriser produced; the paths are what
+     * the machine will actually cut, and the two can differ — which is precisely
+     * what an operator needs to see before committing.
+     */
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas || !raster)
+            return;
+        canvas.width = raster.width;
+        canvas.height = raster.height;
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return;
+        ctx.putImageData(new ImageData(new Uint8ClampedArray(raster.data), raster.width, raster.height), 0, 0);
+        ctx.lineWidth = Math.max(1, raster.width / 600);
+        /*
+         * The CutContour spot colour, from the shared domain constant — the same
+         * value the print-shop SVG export will carry. A themed stroke would drift
+         * from the export and change with the viewer's theme while the cut file
+         * did not.
+         */
+        ctx.strokeStyle = CUT_CONTOUR_CSS;
+        for (const part of parts) {
+            const p = part.path;
+            ctx.beginPath();
+            ctx.moveTo(p.start.x, p.start.y);
+            for (const seg of p.segments) {
+                ctx.bezierCurveTo(seg.c1.x, seg.c1.y, seg.c2.x, seg.c2.y, seg.to.x, seg.to.y);
+            }
+            ctx.closePath();
+            ctx.stroke();
+        }
+    }, [raster, parts]);
+    const bgLabel = useMemo(() => (diagnostics ? (diagnostics.paperColour ? "paper" : "art") : "—"), [diagnostics]);
+    return (_jsx(Section, { children: _jsxs(Stack, { gap: "comfortable", children: [_jsxs(Row, { gap: "comfortable", align: "center", children: [_jsx(FilePickerButton, { onFile: onFile, accept: "image/*", children: file ? "Choose a different scan" : "Choose a scan" }), file ? _jsx(Text, { size: "sm", color: "muted", children: file.name }) : null] }), error ? (_jsx(Card, { variant: "default", children: _jsx(Text, { color: "error", role: "alert", children: error }) })) : null, probeError ? (_jsx(Card, { variant: "default", children: _jsxs(Text, { color: "error", role: "alert", children: ["Could not read this scan's dimensions (", probeError, "). You can still tune it, but it cannot be committed as a run until that works \u2014 a run needs the real pixel size, not the preview's."] }) })) : null, source ? (_jsxs(Grid, { cols: "cards", children: [_jsx(Card, { variant: "default", children: _jsxs(Stack, { gap: "comfortable", children: [_jsx(Heading, { level: 3, children: "Parameters" }), CONTROLS.map((c) => (_jsxs(Stack, { gap: "dense", children: [_jsx(FieldInput, { name: c.key, type: "number", label: PARAM_HELP[c.key]?.title ?? c.key, step: c.step, value: String(params[c.key]), onChange: (v) => {
+                                                    const n = Number(v);
+                                                    // A half-typed "0." parses NaN; keeping the old value
+                                                    // beats re-tracing against a NaN and blanking the canvas.
+                                                    if (Number.isFinite(n))
+                                                        setParam(c.key, n);
+                                                } }), _jsx(Text, { size: "xs", color: "muted", children: PARAM_HELP[c.key]?.body })] }, c.key))), _jsx(FieldSelect, { name: "tier", label: "Tier", value: TIER, disabled: true, options: [{ value: TIER, label: TIER_HELP[TIER].title }], onChange: () => undefined }), _jsx(Text, { size: "xs", color: "muted", children: TIER_HELP[TIER].body })] }) }), _jsx(Card, { variant: "default", children: _jsxs(Stack, { gap: "dense", children: [_jsx(Heading, { level: 3, children: "Result" }), _jsxs(Text, { children: [_jsx(Span, { weight: "bold", children: parts.length }), " part(s)", diagnostics ? ` · ${diagnostics.droppedSheetSized} sheet-sized` : "", diagnostics ? ` · ${diagnostics.droppedBelowMinArea} too small` : ""] }), _jsxs(Text, { size: "sm", color: "muted", children: ["background: ", bgLabel, diagnostics
+                                                ? ` · ridge ${(diagnostics.ridgeCoverage * 100).toFixed(1)}%`
+                                                : "", lastMs !== null ? ` · ${lastMs} ms` : "", tracing ? " · tracing…" : ""] }), diagnostics && parts.length === 0 && diagnostics.droppedSheetSized >= 1 ? (_jsx(Text, { size: "sm", color: "warning", children: "No parts, and one component covers the whole sheet \u2014 this looks like several sheets in one scan, which is unsupported. Scan them individually or crop." })) : null] }) })] })) : (_jsx(Text, { color: "muted", children: "Pick a scanned sticker sheet to trace. Nothing is uploaded \u2014 the trace runs entirely in this tab." })), source ? (_jsx(Card, { variant: "default", children: _jsx("canvas", { ref: canvasRef, className: "w-full h-auto" }) })) : null, renderCommit?.({
+                    params,
+                    file,
+                    dimensions: natural,
+                })] }) }));
+}

package/dist/features/sticker-trace/constants/help-content.d.ts

@@ -0,0 +1,23 @@
+import type { PrecisionTier } from "../../../_internal/shared/features/sticker-trace/types";
+export interface HelpEntry {
+    title: string;
+    body: string;
+}
+/**
+ * What each tier actually buys, in the terms that decide between them.
+ *
+ * 🛑 A `Record<PrecisionTier, …>`, so a fifth tier cannot be added without
+ * answering "what does it buy" — the thing a tier selector exists to tell you.
+ */
+export declare const TIER_HELP: Record<PrecisionTier, HelpEntry>;
+/**
+ * The parameters an operator actually moves.
+ *
+ * Keyed by the `TraceParams` member name so a field can look its own help up
+ * by `name`, which is what makes the inline `?` and the panel the same text.
+ */
+export declare const PARAM_HELP: Record<string, HelpEntry>;
+/** How to read the result panel's numbers. */
+export declare const DIAGNOSTIC_HELP: Record<string, HelpEntry>;
+/** Things the tool cannot do, stated plainly rather than discovered. */
+export declare const LIMITATION_HELP: readonly HelpEntry[];

package/dist/features/sticker-trace/constants/help-content.js

@@ -0,0 +1,172 @@
+/*
+ * WHY: Every number in this tool has a reason that was measured, and none of
+ *      them is guessable from the label. An operator deciding between tiers, or
+ *      staring at a scan that produced nine parts instead of fifteen, needs the
+ *      reason — not a tooltip restating the field name.
+ * WHAT: One source for that copy, rendered by the help panel AND by each
+ *       field's inline `?`.
+ *
+ * 🛑 ONE source, two renderers. Two copies drift, and the inline hint is the
+ * one people actually read — so it must be the same text as the panel rather
+ * than a shortened paraphrase that loses the number.
+ *
+ * 🛑 Every figure here was MEASURED on the nine reference scans, not estimated.
+ * Where a claim is an expectation rather than a measurement it says so. Do not
+ * add a confident number to this file without one, because this is the copy an
+ * operator will trust over their own eyes.
+ *
+ * EXPORTS: TIER_HELP, PARAM_HELP, DIAGNOSTIC_HELP, LIMITATION_HELP
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:StickerTraceStudio,StickerTracerHelpPanel
+ * @tag sideEffects:none
+ */
+/**
+ * What each tier actually buys, in the terms that decide between them.
+ *
+ * 🛑 A `Record<PrecisionTier, …>`, so a fifth tier cannot be added without
+ * answering "what does it buy" — the thing a tier selector exists to tell you.
+ */
+export const TIER_HELP = {
+    draft: {
+        title: "Draft — interactive",
+        body: "Works at a 1200px long edge, which is what keeps one trace near a second. " +
+            "This is the only tier the live tuner offers: the trace runs in your browser " +
+            "on the main thread, so a heavier tier would freeze the page while you drag a " +
+            "slider. Use it to find parameters that work, then commit a run at a higher " +
+            "tier with those parameters.",
+    },
+    standard: {
+        title: "Standard",
+        body: "3000px long edge, median prefilter, integer contours. The default for a real " +
+            "run, and what the reference corpus was measured at — the part counts you see " +
+            "quoted anywhere in this tool are standard-tier counts.",
+    },
+    precise: {
+        title: "Precise",
+        body: "5000px (or native, whichever is smaller), bilateral prefilter, and SUB-PIXEL " +
+            "contours: the mask is blurred before tracing so an edge lands between pixels " +
+            "rather than on one. Reach for it when a halftone scan merges two stickers at " +
+            "standard, which is the case it exists for.",
+    },
+    max: {
+        title: "Max",
+        body: "Native resolution, with the ridge pass TILED and overlapped so a cut line " +
+            "crossing a tile seam is not broken. Expensive in both time and quota, and the " +
+            "tier most likely to produce a cut file Design Space cannot open — its finer " +
+            "simplify tolerance can push a sheet past the ~50,000-node ceiling. Export " +
+            "simplification is a separate budget for exactly that reason.",
+    },
+};
+/**
+ * The parameters an operator actually moves.
+ *
+ * Keyed by the `TraceParams` member name so a field can look its own help up
+ * by `name`, which is what makes the inline `?` and the panel the same text.
+ */
+export const PARAM_HELP = {
+    ridgeHysteresisLow: {
+        title: "Ridge sensitivity (low)",
+        body: "The threshold a pixel must clear to COUNT as part of a cut line once a " +
+            "neighbour is already certain. Lower finds fainter lines and more noise with " +
+            "them. This is the first thing to try when parts are missing: the detector " +
+            "reads an emboss ridge, which on the reference scans sits 10-20x above noise " +
+            "even where colour shows nothing at all.",
+    },
+    ridgeHysteresisHigh: {
+        title: "Ridge sensitivity (high)",
+        body: "The threshold at which a line is certain enough to start from. Raise it if " +
+            "the trace is finding cut lines inside artwork; lower it if whole stickers are " +
+            "being missed. The two thresholds work as a pair — a line is kept when it " +
+            "clears the low bar AND connects to something that cleared the high one.",
+    },
+    paperTolerance: {
+        title: "Paper tolerance",
+        body: "How far a pixel may differ from the sampled paper colour and still count as " +
+            "background. Only used on sheets that HAVE a background: a full-bleed art sheet " +
+            "is segmented a different way entirely, and this control does nothing there. " +
+            "The result panel tells you which model ran.",
+    },
+    minPartAreaMm2: {
+        title: "Minimum part area",
+        body: "Anything smaller is dropped as speckle. Raise it when the part count is full " +
+            "of fragments. Measured in mm², so it depends on a trustworthy DPI — with no " +
+            "confirmed DPI the tool falls back to a fraction of the image instead, which " +
+            "still removes dust but cannot honour a figure in millimetres.",
+    },
+    bridgeMm: {
+        title: "Bridge gap",
+        body: "Closes small breaks in a cut line before the outline is traced. Useful on a " +
+            "scan where the emboss fades; too high and two adjacent stickers fuse into one " +
+            "part.",
+    },
+    simplifyMm: {
+        title: "Simplify tolerance",
+        body: "How far the final outline may deviate from the traced curve. Tighter means " +
+            "more nodes, and node count is what Design Space runs out of — so the Cricut " +
+            "export re-simplifies to its own budget and reports the resulting deviation " +
+            "rather than inheriting this value.",
+    },
+};
+/** How to read the result panel's numbers. */
+export const DIAGNOSTIC_HELP = {
+    background: {
+        title: "paper vs art",
+        body: "Two completely different segmentation models, chosen automatically. PAPER " +
+            "floods inward from the sheet edge, so a sticker is anything the flood cannot " +
+            "reach — which is why a region inside a sticker stays opaque no matter what " +
+            "colour it is. ART has no background to flood, so it partitions on the cut " +
+            "lines and merges back across the weak ones. If the wrong model is chosen, " +
+            "paper tolerance will appear to do nothing.",
+    },
+    sheetSized: {
+        title: "sheet-sized",
+        body: "Components covering more than 60% of the image. One of these usually means " +
+            "the flood never got in — the cut lines sealed the border, or the scan has no " +
+            "background at all.",
+    },
+    tooSmall: {
+        title: "too small",
+        body: "Components dropped for being under the minimum part area. A large number here " +
+            "with few real parts usually means the detector is reading noise as cut lines; " +
+            "try a prefilter before raising the minimum.",
+    },
+};
+/** Things the tool cannot do, stated plainly rather than discovered. */
+export const LIMITATION_HELP = Object.freeze([
+    {
+        title: "Several sheets in one scan",
+        body: "Unsupported, and measured rather than assumed: a 2x3 montage of six " +
+            "full-bleed sheets returns ZERO parts by both models, because the background " +
+            "estimate samples the outer frame and the gutters and gets one colour that is " +
+            "wrong for five of the six panels. A projection-profile splitter was built for " +
+            "this and removed — it still read the montage as one panel while breaking " +
+            "single sheets that had worked. Scan sheets individually, or crop.",
+    },
+    {
+        title: "No DPI means no millimetres",
+        body: "Five of the nine reference scans declare 72 or 96 DPI, which is a number the " +
+            "encoder wrote rather than anything about the scanner. When DPI cannot be " +
+            "trusted the tool shows sizes in pixels and withholds millimetres entirely — a " +
+            "fabricated millimetre on a cut file is a physical production error, not a " +
+            "cosmetic one. Confirm or measure the DPI to unlock mm output.",
+    },
+    {
+        title: "Halftone scans are the hard case",
+        body: "A screened (dot-pattern) scan carries the weakest cut-line signal of the " +
+            "corpus — roughly 3x noise against 10-20x for the rest. Expect to tune it, and " +
+            "expect the bilateral prefilter at `precise` to matter more than any threshold.",
+    },
+    {
+        title: "Parts wider than the cutter",
+        body: "A Cricut Joy 2's Print-Then-Cut area on A4 is a column about 78mm wide, and " +
+            "several stickers on a typical sheet are wider than that. Those parts are named " +
+            "before export rather than silently scaled — scaling would produce a cut file " +
+            "that looks correct and yields stickers the wrong physical size. Oversized parts " +
+            "can be tiled across sheets, or sent to the print-shop profile, which has no " +
+            "width limit.",
+    },
+]);

package/dist/features/sticker-trace/hooks/useLiveTrace.d.ts

@@ -0,0 +1,27 @@
+import type { DecodedRaster, TraceDiagnostics, TraceParams, PartGeometry } from "../../../_internal/shared/features/sticker-trace/types";
+export interface LiveTraceState {
+    parts: readonly PartGeometry[];
+    diagnostics: TraceDiagnostics | null;
+    /** The raster the trace ran on — what a canvas overlay draws under the paths. */
+    raster: DecodedRaster | null;
+    /** True while a trace is in flight; the previous result stays visible. */
+    tracing: boolean;
+    /** Wall time of the last trace, so a tier change's cost is visible. */
+    lastMs: number | null;
+    error: string | null;
+}
+/**
+ * Re-trace `source` whenever `params` change.
+ *
+ * 🛑 The previous result is kept on screen while a new trace runs. Blanking to
+ * a spinner on every keystroke makes the control feel broken and, worse, hides
+ * the thing the operator is comparing against — the point of live tuning is
+ * seeing what a change did.
+ */
+export declare function useLiveTrace(source: Uint8Array | null, params: TraceParams, opts?: {
+    debounceMs?: number;
+}): LiveTraceState & {
+    retrace: () => void;
+};
+/** Draft-tier defaults, the only tier sized for interactive use. */
+export declare function liveTuningDefaults(): TraceParams;

package/dist/features/sticker-trace/hooks/useLiveTrace.js

@@ -0,0 +1,160 @@
+"use client";
+/*
+ * WHY: Tuning a halftone scan takes several attempts, and a server round trip
+ *      per attempt makes that unaffordable in both time and quota. The whole
+ *      reason the codec is a port is so the identical trace runs in the tab.
+ * WHAT: Decode once, re-trace on every parameter change, report timing.
+ *
+ * 🛑 A PARAMETER TWEAK MUST NOT RE-DECODE. Decoding is the expensive half, and
+ * only decode-stage parameters can change its output — so the raster is cached
+ * and reused, and the decision of when to drop it is DELEGATED to
+ * `earliestChangedStage` from resume.ts rather than hand-written here. That is
+ * the same clamp the retry panel shows, so the browser and the Function agree
+ * on which parameters invalidate what; a second hand-rolled list would be the
+ * drift Root Cause #42 describes.
+ *
+ * 🛑 It runs on the MAIN THREAD, debounced. The `draft` tier caps the working
+ * long edge at 1200 (~1.4 Mpx) specifically so one trace stays near a second;
+ * at `standard` (3000) it would not, which is why the tier selector and this
+ * hook are coupled. If a real session janks, the escalation is a Worker — the
+ * core is pure and already worker-safe, so that is a mechanical change rather
+ * than a redesign. Do not reach for it before measuring.
+ *
+ * EXPORTS: useLiveTrace, LiveTraceState
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:sticker-trace/components
+ * @tag sideEffects:none
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { normalizeError } from "../../../errors/normalize.js";
+import { canvasCodec } from "../../../_internal/client/features/sticker-trace/canvas-codec.js";
+import { paramsForTier } from "../../../_internal/shared/features/sticker-trace/config.js";
+import { traceStickerSheet } from "../../../_internal/shared/features/sticker-trace/index.js";
+import { earliestChangedStage, stageIndex } from "../../../_internal/shared/features/sticker-trace/resume.js";
+const EMPTY = {
+    parts: [],
+    diagnostics: null,
+    raster: null,
+    tracing: false,
+    lastMs: null,
+    error: null,
+};
+/**
+ * Re-trace `source` whenever `params` change.
+ *
+ * 🛑 The previous result is kept on screen while a new trace runs. Blanking to
+ * a spinner on every keystroke makes the control feel broken and, worse, hides
+ * the thing the operator is comparing against — the point of live tuning is
+ * seeing what a change did.
+ */
+export function useLiveTrace(source, params, opts) {
+    const [state, setState] = useState(EMPTY);
+    // The cached decode, plus the params it was produced under.
+    const rasterRef = useRef(null);
+    const decodedWithRef = useRef(null);
+    const sourceRef = useRef(null);
+    /*
+     * Monotonic token. A slow trace that resolves AFTER a newer one must not
+     * overwrite it — without this, dragging a slider lands results out of order
+     * and the canvas settles on whichever request happened to finish last.
+     */
+    const runRef = useRef(0);
+    const run = useCallback(async (src, p) => {
+        const token = ++runRef.current;
+        setState((s) => ({ ...s, tracing: true, error: null }));
+        try {
+            /*
+             * Reuse the cached raster unless a DECODE-stage parameter moved.
+             * `earliestChangedStage` returns the first stage whose params differ;
+             * stage index 0 is decode, so anything else leaves the pixels valid.
+             */
+            const prior = decodedWithRef.current;
+            const sameSource = sourceRef.current === src;
+            const changed = prior ? earliestChangedStage(prior, p) : null;
+            const mustDecode = !rasterRef.current ||
+                !sameSource ||
+                !prior ||
+                (changed !== null && stageIndex(changed) === 0);
+            if (mustDecode) {
+                rasterRef.current = await canvasCodec.decode(src, {
+                    maxLongEdge: p.workingLongEdge,
+                });
+                decodedWithRef.current = p;
+                sourceRef.current = src;
+            }
+            const raster = rasterRef.current;
+            if (token !== runRef.current)
+                return;
+            const t0 = performance.now();
+            /*
+             * `fullWidth` is the raster's own width here, not the original file's.
+             * In the browser there is no confirmed dpi (the canvas codec cannot read
+             * density), so mm-denominated output is withheld anyway — passing a
+             * made-up full width would produce confident millimetre figures from a
+             * number nobody measured.
+             */
+            const result = traceStickerSheet(raster, p, raster.width);
+            const ms = performance.now() - t0;
+            if (token !== runRef.current)
+                return;
+            setState({
+                parts: result.parts,
+                diagnostics: result.diagnostics,
+                raster,
+                tracing: false,
+                lastMs: Math.round(ms),
+                error: null,
+            });
+        }
+        catch (err) {
+            const n = normalizeError(err);
+            /*
+             * normalizeError FIRST, before the body touches the value — the
+             * project-wide rule (Root Cause #31), and audit-catch-normalize caught
+             * this file breaking it twice: once by not calling it at all, then by
+             * putting an eight-line comment between the catch and the call, which
+             * pushed it outside the audit's window. The rule is about the first
+             * STATEMENT, so the explanation belongs after it.
+             *
+             * It also removes the hand-rolled `instanceof Error ? … : String(err)`
+             * narrowing that every catch otherwise reinvents slightly differently.
+             *
+             * The message reaches an admin tuning their own scan, so the browser's
+             * own text is useful rather than dangerous — Root Cause #86 is about
+             * SERVER internals reaching a user, which this is not.
+             */
+            if (token !== runRef.current)
+                return;
+            setState((s) => ({ ...s, tracing: false, error: n.message }));
+        }
+    }, []);
+    const retrace = useCallback(() => {
+        if (sourceRef.current)
+            void run(sourceRef.current, params);
+    }, [run, params]);
+    useEffect(() => {
+        if (!source) {
+            setState(EMPTY);
+            rasterRef.current = null;
+            decodedWithRef.current = null;
+            sourceRef.current = null;
+            return;
+        }
+        const delay = opts?.debounceMs ?? 250;
+        const t = setTimeout(() => void run(source, params), delay);
+        return () => clearTimeout(t);
+        // `params` is a fresh object each render from the caller's form state, so
+        // this intentionally depends on the whole object — the debounce is what
+        // makes that affordable, and `run` compares params by VALUE through
+        // earliestChangedStage rather than by identity.
+    }, [source, params, run, opts?.debounceMs]);
+    return { ...state, retrace };
+}
+/** Draft-tier defaults, the only tier sized for interactive use. */
+export function liveTuningDefaults() {
+    return paramsForTier("draft");
+}

package/dist/features/sticker-trace/hooks/useStickerTraceProgress.d.ts

@@ -0,0 +1,22 @@
+import type { TraceStage } from "../../../_internal/shared/features/sticker-trace/types";
+/** One snapshot of the channel. Every field is optional — see `extract`. */
+export interface StickerTraceProgress {
+    stage: TraceStage | "queued" | "done" | null;
+    pct: number;
+    partsDone: number | null;
+    partsTotal: number | null;
+    shardsDone: number | null;
+    shardsTotal: number | null;
+    message: string | null;
+    level: "info" | "warn" | "error" | null;
+    terminal: boolean;
+}
+export interface UseStickerTraceProgressReturn {
+    progress: StickerTraceProgress;
+    /** Call once with the run id and the token the create route minted. */
+    subscribe: (runId: string, customToken: string) => void;
+    /** A one-line summary for a status row, or null when there is nothing to say. */
+    label: string | null;
+    error: string | null;
+}
+export declare function useStickerTraceProgress(): UseStickerTraceProgressReturn;