@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/_internal/shared/features/sticker-trace/math/rasterize-path.d.ts

@@ -0,0 +1,88 @@
+import type { CutPath, Point, Rect } from "../types";
+/**
+ * Max deviation between the curve and its polyline, in DESTINATION pixels.
+ *
+ * 🛑 MEASURED, and the first value chosen here was wrong. A circle of r=8 has
+ * a known area (pi*r^2 = 201.06), so the fill can be checked against it:
+ *
+ *     tol 0.25   17 pts   area 196.09   -2.47%
+ *     tol 0.10   33 pts   area 200.02   -0.52%
+ *     tol 0.05   57 pts   area 200.74   -0.16%   <- chosen
+ *     tol 0.01  129 pts   area 201.18   +0.06%
+ *     tol 0.002 257 pts   area 201.25   +0.10%
+ *
+ * A polyline inscribed in a convex curve always UNDER-covers — chords cut
+ * corners — so the bias is one-directional and shrinks the sticker rather than
+ * growing it. At 0.25 that is a systematic 2.5% area loss, which is far more
+ * than anti-aliasing can hide. 0.05 costs 57 points against 17 and lands inside
+ * a fifth of a percent; 0.01 buys another 0.1pp for 2.3x the points, which the
+ * cut cannot express.
+ */
+export declare const FLATTEN_TOLERANCE_PX = 0.05;
+/**
+ * Sub-scanlines per pixel row.
+ *
+ * 🛑 This knob does NOT control accuracy, and I assumed it did. Measured on the
+ * same circle, area error barely moves and moves the WRONG way — S=1 -1.96%,
+ * S=4 -2.47%, S=16 -2.54%, S=32 -2.55% — because total coverage is set by the
+ * polyline, not by how finely the rows are sampled. The earlier claim here that
+ * "16 was measurably no better" was written before any of this was measured;
+ * it happened to be true and was not evidence.
+ *
+ * What subsampling actually buys is edge SMOOTHNESS, which an area total cannot
+ * see at all: a stair-stepped edge and a smooth one can sum to the same
+ * coverage. 4 gives five distinguishable levels from vertical coverage while the
+ * horizontal span ends stay exact, so a near-vertical edge is continuous and a
+ * near-horizontal one is quantised to fifths. Raising it is cheap if a printed
+ * part ever shows banding on shallow diagonals — judge that by eye, not by this
+ * area check.
+ */
+export declare const SUBSAMPLES_PER_ROW = 4;
+/**
+ * Flatten a cut path into a closed polyline, transformed into mask space.
+ *
+ * `scale` maps the working raster the path was traced on to full resolution,
+ * and `origin` is the part's bbox corner — so the returned points are already
+ * relative to the mask's own (0,0). Doing the transform HERE rather than per
+ * sample is what keeps the inner scanline loop free of it.
+ */
+export declare function flattenPath(path: CutPath, scale: number, origin: {
+    x: number;
+    y: number;
+}): Point[];
+/**
+ * Rasterise one closed path into an alpha mask of `size`.
+ *
+ * Returns `width * height` bytes, 0..255, row-major — the shape
+ * `encodePngRegion` writes straight into the alpha channel.
+ */
+export declare function rasterizePathAlpha(points: readonly Point[], size: {
+    width: number;
+    height: number;
+}): Uint8Array;
+/**
+ * Rasterise one part's path into an alpha mask covering `bbox`.
+ *
+ * This matches `ShardDeps.rasterise` exactly: `(path, bbox)`, no ordinal and
+ * no scale.
+ *
+ * 🛑 The scale is DERIVED from the path's own extent onto `bbox`, and that is
+ * the only self-consistent option available. The path is in working-raster
+ * coordinates while `bbox` is already full-resolution, so a mapping is
+ * unavoidable — and the two candidates were: take `scale` as a fourth argument,
+ * or derive it. Taking it would mean the shard computes
+ * `sheet.widthPx / workingSize.width` and the binding computes it again from
+ * its own copy of the geometry, which is two derivations of one number and
+ * exactly the drift Root Cause #75 is about. Deriving it here also guarantees
+ * the mask FILLS the region it was given, which is what the caller needs:
+ * `bbox` comes from the component mask while the path comes from marching
+ * squares, so the two can differ by a fraction of a pixel and a mask that
+ * merely scaled by a shared factor could leave an empty row at one edge.
+ *
+ * 🛑 A FIRST DRAFT of this was `makePartRasteriser(geometry)`, keyed on
+ * ordinal. It was written against a stale signature and deleted: the real
+ * contract hands over the path, and its own comment explains why — an ordinal
+ * "could only be implemented by re-reading geometry.json for every part, sixty
+ * extra downloads per shard for data the caller already holds."
+ */
+export declare function rasterisePartToBox(path: CutPath, bbox: Rect): Promise<Uint8Array>;

package/dist/_internal/shared/features/sticker-trace/math/rasterize-path.js

@@ -0,0 +1,286 @@
+/*
+ * WHY: A cut path is Bézier geometry, but a part's PNG needs an alpha mask —
+ *      and the mask has to agree with the cut file exactly, or the printed
+ *      sticker and the blade disagree about where its edge is.
+ * WHAT: Flatten cubics to a polyline, then scanline-fill with coverage alpha.
+ *
+ * TWO DECISIONS THE CUT QUALITY DEPENDS ON, both made here and stated:
+ *
+ * 🛑 1. FILL RULE: NONZERO.
+ *
+ * A kiss cut is one closed outer boundary with no interior holes — cutting a
+ * hole would make the sticker fall apart on the backing — so on today's data
+ * nonzero and even-odd are IDENTICAL. Nonzero is chosen anyway because it is
+ * SVG's default, and the cut SVG exporter will emit these same paths: if the
+ * two rules ever disagreed (a self-intersecting trace, or a future part that
+ * genuinely has a hole), the mask and the cut file must still describe the same
+ * region. Picking the renderer's rule means they cannot drift.
+ *
+ * 🛑 2. EDGES ARE ANTI-ALIASED, by coverage.
+ *
+ * A hard 0/255 mask leaves visible stair-stepping along every diagonal and
+ * curve — on a printed sticker that reads as a jagged edge, and it is exactly
+ * the artifact a Bézier trace exists to avoid. So each pixel's alpha is the
+ * FRACTION of it inside the path: vertical supersampling across sub-scanlines
+ * plus exact horizontal span ends. Costs ~4x the scanline work for an edge
+ * that survives printing.
+ *
+ * Pure: no codec, no node, no DOM. Enforced by audit-sticker-trace-purity.
+ *
+ * EXPORTS: flattenPath, rasterizePathAlpha, rasterisePartToBox,
+ *   FLATTEN_TOLERANCE_PX, SUBSAMPLES_PER_ROW
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:shard,canvas-codec
+ * @tag sideEffects:none
+ */
+/**
+ * Max deviation between the curve and its polyline, in DESTINATION pixels.
+ *
+ * 🛑 MEASURED, and the first value chosen here was wrong. A circle of r=8 has
+ * a known area (pi*r^2 = 201.06), so the fill can be checked against it:
+ *
+ *     tol 0.25   17 pts   area 196.09   -2.47%
+ *     tol 0.10   33 pts   area 200.02   -0.52%
+ *     tol 0.05   57 pts   area 200.74   -0.16%   <- chosen
+ *     tol 0.01  129 pts   area 201.18   +0.06%
+ *     tol 0.002 257 pts   area 201.25   +0.10%
+ *
+ * A polyline inscribed in a convex curve always UNDER-covers — chords cut
+ * corners — so the bias is one-directional and shrinks the sticker rather than
+ * growing it. At 0.25 that is a systematic 2.5% area loss, which is far more
+ * than anti-aliasing can hide. 0.05 costs 57 points against 17 and lands inside
+ * a fifth of a percent; 0.01 buys another 0.1pp for 2.3x the points, which the
+ * cut cannot express.
+ */
+export const FLATTEN_TOLERANCE_PX = 0.05;
+/**
+ * Sub-scanlines per pixel row.
+ *
+ * 🛑 This knob does NOT control accuracy, and I assumed it did. Measured on the
+ * same circle, area error barely moves and moves the WRONG way — S=1 -1.96%,
+ * S=4 -2.47%, S=16 -2.54%, S=32 -2.55% — because total coverage is set by the
+ * polyline, not by how finely the rows are sampled. The earlier claim here that
+ * "16 was measurably no better" was written before any of this was measured;
+ * it happened to be true and was not evidence.
+ *
+ * What subsampling actually buys is edge SMOOTHNESS, which an area total cannot
+ * see at all: a stair-stepped edge and a smooth one can sum to the same
+ * coverage. 4 gives five distinguishable levels from vertical coverage while the
+ * horizontal span ends stay exact, so a near-vertical edge is continuous and a
+ * near-horizontal one is quantised to fifths. Raising it is cheap if a printed
+ * part ever shows banding on shallow diagonals — judge that by eye, not by this
+ * area check.
+ */
+export const SUBSAMPLES_PER_ROW = 4;
+/** Flat-enough test: the control points' distance from the chord. */
+function isFlatEnough(p0, c1, c2, p1, tol) {
+    const dx = p1.x - p0.x;
+    const dy = p1.y - p0.y;
+    const len = Math.hypot(dx, dy);
+    if (len < 1e-9) {
+        // Degenerate chord: fall back to control-point spread, or a cusp would
+        // recurse to the depth cap and emit a needlessly dense polyline.
+        return Math.hypot(c1.x - p0.x, c1.y - p0.y) + Math.hypot(c2.x - p1.x, c2.y - p1.y) < tol;
+    }
+    const d1 = Math.abs((c1.x - p0.x) * dy - (c1.y - p0.y) * dx) / len;
+    const d2 = Math.abs((c2.x - p0.x) * dy - (c2.y - p0.y) * dx) / len;
+    return Math.max(d1, d2) <= tol;
+}
+function subdivide(p0, c1, c2, p1, tol, depth, out) {
+    /*
+     * Depth 16 is a guard, not a tuning knob. Adaptive subdivision terminates on
+     * real curves; the cap exists so a NaN or an infinity in the geometry cannot
+     * spin forever — which would hang a shard rather than fail it.
+     */
+    if (depth >= 16 || isFlatEnough(p0, c1, c2, p1, tol)) {
+        out.push(p1);
+        return;
+    }
+    const mid = (a, b) => ({ x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 });
+    const p01 = mid(p0, c1);
+    const p12 = mid(c1, c2);
+    const p23 = mid(c2, p1);
+    const p012 = mid(p01, p12);
+    const p123 = mid(p12, p23);
+    const m = mid(p012, p123);
+    subdivide(p0, p01, p012, m, tol, depth + 1, out);
+    subdivide(m, p123, p23, p1, tol, depth + 1, out);
+}
+/**
+ * Flatten a cut path into a closed polyline, transformed into mask space.
+ *
+ * `scale` maps the working raster the path was traced on to full resolution,
+ * and `origin` is the part's bbox corner — so the returned points are already
+ * relative to the mask's own (0,0). Doing the transform HERE rather than per
+ * sample is what keeps the inner scanline loop free of it.
+ */
+export function flattenPath(path, scale, origin) {
+    const tx = (p) => ({ x: p.x * scale - origin.x, y: p.y * scale - origin.y });
+    const pts = [tx(path.start)];
+    let current = path.start;
+    for (const seg of path.segments) {
+        subdivide(tx(current), tx(seg.c1), tx(seg.c2), tx(seg.to), FLATTEN_TOLERANCE_PX, 0, pts);
+        current = seg.to;
+    }
+    return pts;
+}
+function buildEdges(points) {
+    const edges = [];
+    for (let i = 0; i < points.length; i++) {
+        const a = points[i];
+        const b = points[(i + 1) % points.length];
+        // Horizontal edges contribute no crossings and would divide by zero.
+        if (a.y === b.y)
+            continue;
+        edges.push(a.y < b.y
+            ? { x0: a.x, y0: a.y, x1: b.x, y1: b.y, dir: 1 }
+            : { x0: b.x, y0: b.y, x1: a.x, y1: a.y, dir: -1 });
+    }
+    return edges;
+}
+/**
+ * Rasterise one closed path into an alpha mask of `size`.
+ *
+ * Returns `width * height` bytes, 0..255, row-major — the shape
+ * `encodePngRegion` writes straight into the alpha channel.
+ */
+export function rasterizePathAlpha(points, size) {
+    const { width, height } = size;
+    const alpha = new Uint8Array(width * height);
+    const edges = buildEdges(points);
+    if (edges.length === 0)
+        return alpha;
+    // Float accumulator per row: coverage sums across sub-scanlines before the
+    // single rounding at the end. Rounding per sub-scanline would quantise four
+    // times and lose most of the anti-aliasing.
+    const cov = new Float32Array(width);
+    const xs = [];
+    for (let y = 0; y < height; y++) {
+        cov.fill(0);
+        for (let s = 0; s < SUBSAMPLES_PER_ROW; s++) {
+            const sy = y + (s + 0.5) / SUBSAMPLES_PER_ROW;
+            xs.length = 0;
+            for (const e of edges) {
+                // Half-open [y0, y1): a vertex shared by two edges is counted once, so
+                // a crossing exactly on a sub-scanline cannot double-count and punch a
+                // hole in the fill.
+                if (sy < e.y0 || sy >= e.y1)
+                    continue;
+                const t = (sy - e.y0) / (e.y1 - e.y0);
+                xs.push({ x: e.x0 + t * (e.x1 - e.x0), dir: e.dir });
+            }
+            if (xs.length < 2)
+                continue;
+            xs.sort((a, b) => a.x - b.x);
+            // NONZERO: accumulate winding, and a span is inside wherever it is != 0.
+            let winding = 0;
+            for (let i = 0; i < xs.length - 1; i++) {
+                winding += xs[i].dir;
+                if (winding === 0)
+                    continue;
+                addSpan(cov, xs[i].x, xs[i + 1].x, width);
+            }
+        }
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            const v = cov[x] / SUBSAMPLES_PER_ROW;
+            alpha[row + x] = v <= 0 ? 0 : v >= 1 ? 255 : Math.round(v * 255);
+        }
+    }
+    return alpha;
+}
+/**
+ * Add one horizontal span's coverage, with EXACT fractional ends.
+ *
+ * This is what makes a near-vertical edge smooth: the partial pixels at each
+ * end get their real fraction rather than being rounded in or out, so the
+ * horizontal resolution is continuous even though the vertical is sampled.
+ */
+function addSpan(cov, xStart, xEnd, width) {
+    let a = xStart;
+    let b = xEnd;
+    if (b <= a)
+        return;
+    if (b <= 0 || a >= width)
+        return;
+    if (a < 0)
+        a = 0;
+    if (b > width)
+        b = width;
+    const first = Math.floor(a);
+    const last = Math.ceil(b) - 1;
+    if (first === last) {
+        cov[first] = cov[first] + (b - a);
+        return;
+    }
+    cov[first] = cov[first] + (first + 1 - a);
+    for (let x = first + 1; x < last; x++)
+        cov[x] = cov[x] + 1;
+    cov[last] = cov[last] + (b - last);
+}
+/**
+ * Rasterise one part's path into an alpha mask covering `bbox`.
+ *
+ * This matches `ShardDeps.rasterise` exactly: `(path, bbox)`, no ordinal and
+ * no scale.
+ *
+ * 🛑 The scale is DERIVED from the path's own extent onto `bbox`, and that is
+ * the only self-consistent option available. The path is in working-raster
+ * coordinates while `bbox` is already full-resolution, so a mapping is
+ * unavoidable — and the two candidates were: take `scale` as a fourth argument,
+ * or derive it. Taking it would mean the shard computes
+ * `sheet.widthPx / workingSize.width` and the binding computes it again from
+ * its own copy of the geometry, which is two derivations of one number and
+ * exactly the drift Root Cause #75 is about. Deriving it here also guarantees
+ * the mask FILLS the region it was given, which is what the caller needs:
+ * `bbox` comes from the component mask while the path comes from marching
+ * squares, so the two can differ by a fraction of a pixel and a mask that
+ * merely scaled by a shared factor could leave an empty row at one edge.
+ *
+ * 🛑 A FIRST DRAFT of this was `makePartRasteriser(geometry)`, keyed on
+ * ordinal. It was written against a stale signature and deleted: the real
+ * contract hands over the path, and its own comment explains why — an ordinal
+ * "could only be implemented by re-reading geometry.json for every part, sixty
+ * extra downloads per shard for data the caller already holds."
+ */
+export async function rasterisePartToBox(path, bbox) {
+    if (bbox.width <= 0 || bbox.height <= 0)
+        return new Uint8Array(0);
+    // The path's extent in its own (working) coordinates.
+    const raw = flattenPath(path, 1, { x: 0, y: 0 });
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const p of raw) {
+        if (p.x < minX)
+            minX = p.x;
+        if (p.y < minY)
+            minY = p.y;
+        if (p.x > maxX)
+            maxX = p.x;
+        if (p.y > maxY)
+            maxY = p.y;
+    }
+    const spanX = maxX - minX;
+    const spanY = maxY - minY;
+    if (!(spanX > 0) || !(spanY > 0))
+        return new Uint8Array(bbox.width * bbox.height);
+    /*
+     * ONE uniform factor, from the larger span. A per-axis fit would stretch the
+     * sticker to fill its own bounding box, which is wrong by up to a pixel on a
+     * part whose bbox was rounded outward — and a stretched cut outline no longer
+     * matches the artwork it was traced from.
+     */
+    const scale = Math.max(bbox.width / spanX, bbox.height / spanY);
+    // Centre the scaled path inside the box, so any rounding slack is split
+    // between the two edges rather than all landing on one.
+    const originX = minX * scale - (bbox.width - spanX * scale) / 2;
+    const originY = minY * scale - (bbox.height - spanY * scale) / 2;
+    const points = flattenPath(path, scale, { x: originX, y: originY });
+    return rasterizePathAlpha(points, { width: bbox.width, height: bbox.height });
+}

package/dist/_internal/shared/features/sticker-trace/math/rdp.d.ts

@@ -0,0 +1,10 @@
+import type { Point } from "../types";
+/**
+ * Drop points that lie within `epsilon` of the chord they sit on.
+ *
+ * `epsilon` is in the same units as the points — callers pass a millimetre
+ * tolerance converted to pixels, so the tolerance means the same physical thing
+ * at every scan resolution. That is why the Cricut exporter can re-simplify to
+ * a node budget independently: both speak the same units.
+ */
+export declare function simplifyRdp(points: readonly Point[], epsilon: number): Point[];

package/dist/_internal/shared/features/sticker-trace/math/rdp.js

@@ -0,0 +1,74 @@
+/*
+ * WHY: A traced ring from a 3000px raster carries ten thousand points, one per
+ *      pixel crack. Emitting that as a cut path makes the blade chatter, bloats
+ *      the SVG past what Design Space will open, and encodes scanner noise as
+ *      geometry. Simplifying first is what makes the curve fit meaningful.
+ * WHAT: Ramer-Douglas-Peucker, iterative.
+ *
+ * Iterative rather than recursive on purpose: a ten-thousand-point contour
+ * recurses deep enough to blow the stack, and it does so only on the largest
+ * stickers — i.e. in production, on the sheets that matter, having passed every
+ * smaller test.
+ *
+ * EXPORTS: simplifyRdp
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:geometry,export/cricut-svg
+ * @tag sideEffects:none
+ */
+/**
+ * Drop points that lie within `epsilon` of the chord they sit on.
+ *
+ * `epsilon` is in the same units as the points — callers pass a millimetre
+ * tolerance converted to pixels, so the tolerance means the same physical thing
+ * at every scan resolution. That is why the Cricut exporter can re-simplify to
+ * a node budget independently: both speak the same units.
+ */
+export function simplifyRdp(points, epsilon) {
+    const n = points.length;
+    if (n < 3 || epsilon <= 0)
+        return points.slice();
+    const keep = new Uint8Array(n);
+    keep[0] = 1;
+    keep[n - 1] = 1;
+    const stack = [[0, n - 1]];
+    while (stack.length > 0) {
+        const [i, j] = stack.pop();
+        if (j <= i + 1)
+            continue;
+        const a = points[i];
+        const b = points[j];
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const len = Math.hypot(dx, dy);
+        let worst = -1;
+        let worstIndex = -1;
+        for (let k = i + 1; k < j; k++) {
+            const p = points[k];
+            // Perpendicular distance to the chord, written out rather than via a
+            // cross-product helper: numpy's `cross` dropped 2-vector support and the
+            // Python original had to be rewritten this way, which is a reminder that
+            // the explicit form is the portable one.
+            const d = len === 0
+                ? Math.hypot(p.x - a.x, p.y - a.y)
+                : Math.abs(dx * (p.y - a.y) - dy * (p.x - a.x)) / len;
+            if (d > worst) {
+                worst = d;
+                worstIndex = k;
+            }
+        }
+        if (worst > epsilon && worstIndex >= 0) {
+            keep[worstIndex] = 1;
+            stack.push([i, worstIndex], [worstIndex, j]);
+        }
+    }
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        if (keep[i])
+            out.push(points[i]);
+    }
+    return out;
+}

package/dist/_internal/shared/features/sticker-trace/resume.d.ts

@@ -0,0 +1,50 @@
+import { type TraceParams, type TraceStage } from "./types";
+/**
+ * Which stage each parameter first affects.
+ *
+ * 🛑 A `Record<keyof TraceParams, TraceStage>` on purpose. Adding a parameter
+ * without classifying it is then a COMPILE error rather than a parameter that
+ * silently never invalidates anything — which would let a changed value resume
+ * past the stage it governs, i.e. exactly the defect this file exists to
+ * prevent. If `tsc` sends you here, the question to answer is "what is the
+ * earliest stage this value changes the output of".
+ */
+export declare const PARAM_STAGE: Record<keyof TraceParams, TraceStage>;
+/** The pipeline order, straight from the union so it cannot drift from it. */
+export declare const STAGE_ORDER: readonly TraceStage[];
+export declare function stageIndex(stage: TraceStage): number;
+/**
+ * The earliest stage whose parameters differ between two runs.
+ *
+ * `null` means nothing relevant changed, so the requested resume point stands.
+ *
+ * Compared with `!==` after a JSON round-trip is deliberately NOT what happens
+ * here — every `TraceParams` member is a number, boolean or short string
+ * union, so a direct comparison is exact. A nested object would need the
+ * key-order-independent treatment Root Cause #92 is about; there isn't one, and
+ * the `Record` above is what stops one being added unnoticed.
+ */
+export declare function earliestChangedStage(previous: TraceParams, next: TraceParams): TraceStage | null;
+export interface ResumeDecision {
+    /** Where the new run actually starts. */
+    stage: TraceStage;
+    /** True when the clamp moved it earlier than asked. */
+    clamped: boolean;
+    requested: TraceStage;
+    /** The parameter stage that forced the clamp, when one did. */
+    forcedBy: TraceStage | null;
+}
+/**
+ * `resumeStage = max(requested, earliestChangedParamStage)` — where "max" means
+ * EARLIER in the pipeline, because a changed parameter invalidates its own
+ * stage and everything after it.
+ */
+export declare function resolveResumeStage(requested: TraceStage, previous: TraceParams, next: TraceParams): ResumeDecision;
+/**
+ * The sentence the retry panel shows. Empty when nothing was clamped.
+ *
+ * Returns plain text rather than a translation key because this is the one
+ * place the two stage names have to appear together, and a key would hide the
+ * fact that the message is load-bearing rather than decorative.
+ */
+export declare function explainResume(decision: ResumeDecision): string;

package/dist/_internal/shared/features/sticker-trace/resume.js

@@ -0,0 +1,160 @@
+/*
+ * WHY: A retry is a NEW named run, but it may resume rather than restart,
+ *      because the expensive stage is usually not the one that failed. Resuming
+ *      is only safe if the parameters the earlier stages ran under have not
+ *      changed.
+ * WHAT: The clamp, and the param-to-stage grouping it reads.
+ *
+ * 🛑 THE CLAMP IS WHAT MAKES RESUME HONEST.
+ *
+ * Without it, "resume from `parts` but with a different ridge threshold"
+ * produces a run whose stored artifacts were generated under DIFFERENT
+ * parameters than the run records — and nothing anywhere contradicts it. The
+ * parts look plausible, the run says `hysteresisLow 0.3`, and the two have
+ * nothing to do with each other. That is the same class of silent lie as a
+ * mirror field drifting from its source (Root Cause #42), which is why the
+ * grouping below is structural rather than a convention someone remembers.
+ *
+ * 🛑 The clamp is SHOWN, never applied silently. `explainResume` returns the
+ * sentence the retry panel displays — "you changed a ridge threshold, so this
+ * run restarts from ridge rather than resuming from parts". An adjustment the
+ * user did not ask for and cannot see is indistinguishable from the tool
+ * ignoring them.
+ *
+ * Pure: no codec, no node, no providers. Enforced by
+ * scripts/audit-sticker-trace-purity.mjs.
+ *
+ * EXPORTS: PARAM_STAGE, STAGE_ORDER, stageIndex, earliestChangedStage,
+ *   resolveResumeStage, explainResume
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/actions,functions/sticker-trace
+ * @tag sideEffects:none
+ */
+import { TRACE_STAGES } from "./types.js";
+/**
+ * Which stage each parameter first affects.
+ *
+ * 🛑 A `Record<keyof TraceParams, TraceStage>` on purpose. Adding a parameter
+ * without classifying it is then a COMPILE error rather than a parameter that
+ * silently never invalidates anything — which would let a changed value resume
+ * past the stage it governs, i.e. exactly the defect this file exists to
+ * prevent. If `tsc` sends you here, the question to answer is "what is the
+ * earliest stage this value changes the output of".
+ */
+export const PARAM_STAGE = {
+    // decode
+    workingLongEdge: "decode",
+    scanType: "decode",
+    /*
+     * Both map to the FIRST stage, i.e. changing either forces a full restart.
+     *
+     * `tier` carries workingLongEdge and subPixelContours, so it reaches decode
+     * and geometry at once — there is no partial resume that honours a new tier.
+     * `dpi` is the px-per-mm scale, and every mm-denominated parameter after it
+     * (minPartAreaMm2, bridgeMm, smoothMm, simplifyMm, clusterGapMm) converts
+     * through it — so a changed dpi silently re-means all five. That is the
+     * subtle one: nothing about those values changed, but what they MEAN did.
+     */
+    tier: "decode",
+    dpi: "decode",
+    // prefilter
+    prefilter: "prefilter",
+    prefilterRadius: "prefilter",
+    // ridge
+    ridgeHysteresisLow: "ridge",
+    ridgeHysteresisHigh: "ridge",
+    ridgeKernelScale: "ridge",
+    // quantise + fuse — the second detector channel and its union into the barrier
+    quantiseEnabled: "quantise",
+    quantiseColours: "quantise",
+    quantiseWeight: "fuse",
+    // flood
+    paperTolerance: "flood",
+    seedBandPx: "flood",
+    // segment
+    minPartAreaMm2: "segment",
+    maxParts: "segment",
+    bridgeMm: "segment",
+    mergeStrengthFactor: "segment",
+    // geometry
+    smoothMm: "geometry",
+    borderMm: "geometry",
+    bleedMm: "geometry",
+    simplifyMm: "geometry",
+    cleanMm: "geometry",
+    /*
+     * 🛑 `subPixelContours` is NOT here, and that is not an omission. It lives on
+     * the TIER config, not on TraceParams — so it cannot change without the tier
+     * changing, and a tier change is a new run rather than a resume. The
+     * `Record<keyof TraceParams, …>` above rejected it on the first compile,
+     * which is the whole reason the map is typed that way.
+     */
+    // cluster
+    clusterGapMm: "cluster",
+};
+/** The pipeline order, straight from the union so it cannot drift from it. */
+export const STAGE_ORDER = TRACE_STAGES;
+export function stageIndex(stage) {
+    const i = STAGE_ORDER.indexOf(stage);
+    /*
+     * 🛑 Fails LOUD. An unknown stage reaching here means the union moved and
+     * this file did not; returning -1 or 0 would make the clamp silently resume
+     * from the beginning (merely wasteful) or from wherever was asked (actively
+     * wrong), and both read as working.
+     */
+    if (i === -1)
+        throw new Error(`Unknown trace stage: ${stage}`);
+    return i;
+}
+/**
+ * The earliest stage whose parameters differ between two runs.
+ *
+ * `null` means nothing relevant changed, so the requested resume point stands.
+ *
+ * Compared with `!==` after a JSON round-trip is deliberately NOT what happens
+ * here — every `TraceParams` member is a number, boolean or short string
+ * union, so a direct comparison is exact. A nested object would need the
+ * key-order-independent treatment Root Cause #92 is about; there isn't one, and
+ * the `Record` above is what stops one being added unnoticed.
+ */
+export function earliestChangedStage(previous, next) {
+    let earliest = null;
+    for (const key of Object.keys(PARAM_STAGE)) {
+        if (previous[key] === next[key])
+            continue;
+        const stage = PARAM_STAGE[key];
+        if (earliest === null || stageIndex(stage) < stageIndex(earliest)) {
+            earliest = stage;
+        }
+    }
+    return earliest;
+}
+/**
+ * `resumeStage = max(requested, earliestChangedParamStage)` — where "max" means
+ * EARLIER in the pipeline, because a changed parameter invalidates its own
+ * stage and everything after it.
+ */
+export function resolveResumeStage(requested, previous, next) {
+    const changed = earliestChangedStage(previous, next);
+    if (changed === null || stageIndex(changed) >= stageIndex(requested)) {
+        return { stage: requested, clamped: false, requested, forcedBy: changed };
+    }
+    return { stage: changed, clamped: true, requested, forcedBy: changed };
+}
+/**
+ * The sentence the retry panel shows. Empty when nothing was clamped.
+ *
+ * Returns plain text rather than a translation key because this is the one
+ * place the two stage names have to appear together, and a key would hide the
+ * fact that the message is load-bearing rather than decorative.
+ */
+export function explainResume(decision) {
+    if (!decision.clamped)
+        return "";
+    return (`You changed a ${decision.forcedBy} parameter, so this run restarts from ` +
+        `${decision.stage} rather than resuming from ${decision.requested}.`);
+}