@mohasinac/appkit 4.52.4 → 4.53.0

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

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: The studio tunes a scan entirely in the tab — no upload, no Storage
+ *      object, no Function invocation. That is the whole reason the codec is a
+ *      port. This is the deliberate moment the operator decides those
+ *      parameters are worth spending quota on.
+ * WHAT: Name the attempt, pick a real tier, upload the scan, start the run.
+ *
+ * 🛑 THE NAME IS MANDATORY AND THE BUTTON STAYS DISABLED WITHOUT ONE. The
+ * server rejects an empty name and so does this; the requirement is that every
+ * attempt is something you can tell apart from the other seven later, and
+ * "Untitled (3)" defeats it exactly when it matters.
+ *
+ * 🛑 The tier here is NOT the studio's. The studio is draft-only because it
+ * runs on the main thread and draft's 1200px cap is what keeps a trace near a
+ * second. A committed run is a server run, so the heavy tiers become available
+ * for the first time — which is the point of committing at all.
+ *
+ * 🛑 The upload is three hops and the ROW IS CREATED FIRST. The object path
+ * contains the sheet id, so a signed upload before the row exists has nowhere
+ * to go — and an object with no document pointing at it is unreachable AND
+ * unmeterable. See `createStickerSheet` for the full argument.
+ *
+ * EXPORTS: StickerCommitPanel, StickerCommitResult
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:tools/sticker-tracer
+ * @tag sideEffects:none
+ */
+import { useCallback, useMemo, useState } from "react";
+import { normalizeError } from "../../../errors/normalize.js";
+import { Alert, Button, Card, Form, Heading, Stack, Text } from "../../../ui/index.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FieldSelect } from "../../../ui/forms/FieldSelect.js";
+import { TIER_HELP } from "../constants/help-content.js";
+/** Every tier, unlike the studio — see the header. */
+const TIERS = ["draft", "standard", "precise", "max"];
+export function StickerCommitPanel({ file, dimensions, onCommit, onCommitted, }) {
+    const [title, setTitle] = useState("");
+    const [tier, setTier] = useState("standard");
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    /*
+     * The file's size in MB, shown rather than hidden. A scan is stored AS
+     * UPLOADED — no re-encode, because compression artefacts measured the same
+     * magnitude as the cut-line signal on the halftone sample — so what an
+     * operator picks here is what the storage meter will report forever.
+     */
+    const sizeMb = useMemo(() => (file ? Math.round((file.size / (1024 * 1024)) * 10) / 10 : 0), [file]);
+    const ready = Boolean(file && dimensions && title.trim().length > 0 && !pending);
+    const submit = useCallback(async () => {
+        if (!file || !dimensions)
+            return;
+        setPending(true);
+        setError(null);
+        try {
+            const result = await onCommit({
+                file,
+                title: title.trim(),
+                tier,
+                widthPx: dimensions.widthPx,
+                heightPx: dimensions.heightPx,
+            });
+            onCommitted?.(result);
+        }
+        catch (err) {
+            const n = normalizeError(err);
+            /*
+             * normalizeError FIRST — the project-wide rule, and the explanation goes
+             * after the call rather than between it and the catch, because
+             * audit-catch-normalize checks the first STATEMENT and a long comment in
+             * between pushes the call outside its window.
+             *
+             * The message reaches an admin uploading their own scan, so the real text
+             * is useful here. Root Cause #86 is about SERVER internals reaching a
+             * buyer, which this is not — and the routes already map their own
+             * failures to user-safe text.
+             */
+            setError(n.message);
+        }
+        finally {
+            setPending(false);
+        }
+    }, [file, dimensions, title, tier, onCommit, onCommitted]);
+    if (!file) {
+        return (_jsx(Card, { variant: "default", children: _jsx(Text, { color: "muted", children: "Pick a scan and tune it above. Nothing is uploaded until you commit a run \u2014 the trace you are watching runs entirely in this tab." }) }));
+    }
+    return (_jsx(Card, { variant: "default", children: _jsx(Form, { onSubmit: (e) => e.preventDefault(), children: _jsxs(Stack, { gap: "comfortable", children: [_jsx(Heading, { level: 3, children: "Commit this as a run" }), _jsxs(Text, { size: "sm", color: "muted", children: ["Uploads ", _jsx(Text, { as: "span", weight: "semibold", children: file.name }), " (", sizeMb, " MB) and traces it at full resolution on the server. The parameters you tuned above are the starting point; a run keeps its own copy, so later edits here never change what an earlier run recorded."] }), error ? _jsx(Alert, { variant: "error", children: error }) : null, _jsx(FieldInput, { name: "title", label: "Name this sheet", required: true, value: title, onChange: setTitle }), _jsx(Text, { size: "xs", color: "muted", children: "Required \u2014 nothing processes without one. Name it so you recognise it next to the others: \u201CDriger G, matte scan 600dpi\u201D." }), _jsx(FieldSelect, { name: "tier", label: "Tier", value: tier, options: TIERS.map((t) => ({ value: t, label: TIER_HELP[t].title })), onChange: (v) => setTier(v) }), _jsx(Text, { size: "xs", color: "muted", children: TIER_HELP[tier].body }), tier === "max" ? (_jsx(Alert, { variant: "warning", children: "Max is expensive in both time and quota, and its finer simplify can push a busy sheet past Design Space's node ceiling. Try precise first unless a halftone scan is merging two stickers." })) : null, !dimensions ? (_jsx(Text, { size: "xs", color: "muted", children: "Waiting for the scan to finish decoding\u2026" })) : null, _jsx(Button, { type: "submit", variant: "primary", isLoading: pending, disabled: !ready, onClick: submit, children: pending ? "Uploading and starting…" : "Upload and run" })] }) }) }));
+}

package/dist/features/sticker-trace/components/StickerPrintPanel.d.ts

@@ -0,0 +1,33 @@
+/** Mirrors the export route's response. Kept structural — no appkit internals. */
+export interface ExportReport {
+    unfit: Array<{
+        ordinal: number;
+        name: string;
+        widthMm: number;
+        heightMm: number;
+        verdict: {
+            reasons: readonly string[];
+        };
+    }>;
+    unplaceable: Array<{
+        ordinal: number;
+        name: string;
+    }>;
+    nodesBefore: number;
+    nodesAfter: number;
+    maxDeviationMm: number;
+    overBudget: boolean;
+    pageCount: number;
+}
+export interface StickerPrintPanelProps {
+    /** Fetches the report for a profile/page pair. Injected — appkit owns no transport. */
+    loadReport: (profile: string, page: string) => Promise<{
+        report: ExportReport;
+        refusedReason: string | null;
+    }>;
+    /** Resolve and open the cut file's signed URL. */
+    onDownloadCutFile?: () => void;
+    /** Resolve and open the PDF mosaic. */
+    onDownloadMosaic?: () => void;
+}
+export declare function StickerPrintPanel({ loadReport, onDownloadCutFile, onDownloadMosaic, }: StickerPrintPanelProps): import("react").JSX.Element;

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

@@ -0,0 +1,104 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/*
+ * WHY: Every irreversible thing about an export is decided before the file is
+ *      produced — which machine, which page, and which parts that machine
+ *      simply cannot cut. Those answers exist in the export report and had
+ *      nowhere to be shown, so the only way to discover a part was too wide
+ *      was to cut it and watch it run off the material.
+ * WHAT: Pick a profile and a page, see what will actually happen, then export.
+ *
+ * 🛑 IT SHOWS THE REFUSALS BEFORE THE DOWNLOAD, and that ordering is the whole
+ * design. An oversized part is NAMED here — never scaled to fit, because a
+ * scaled part produces a cut file that looks correct and yields stickers the
+ * wrong physical size, which is only discoverable against the real object.
+ *
+ * 🛑 The preview fetches a REPORT, never the file. The whole point is trying
+ * three machines and two pages before committing, and each of those would
+ * otherwise be a few hundred KB of SVG through a Vercel function — the egress
+ * shape `audit-sticker-trace-egress` exists to refuse. The bytes come from a
+ * signed GCS URL only once, when the operator actually exports.
+ *
+ * EXPORTS: StickerPrintPanel
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:tools/sticker-tracer
+ * @tag sideEffects:none
+ */
+import { useCallback, useEffect, useState } from "react";
+import { normalizeError } from "../../../errors/normalize.js";
+import { Alert, Badge, Button, Card, Heading, Row, Span, Stack, Text, } from "../../../ui/index.js";
+import { FieldSelect } from "../../../ui/forms/FieldSelect.js";
+const PROFILES = [
+    { value: "print-shop", label: "Print shop (Roland / Graphtec)" },
+    { value: "cricut-cut", label: "Cricut Joy 2 — cut only" },
+    { value: "cricut-ptc", label: "Cricut Joy 2 — Print Then Cut" },
+];
+const PAGES = [
+    { value: "a4", label: "A4" },
+    { value: "a3", label: "A3" },
+    { value: "a5", label: "A5" },
+    { value: "letter", label: "Letter" },
+    { value: "legal", label: "Legal" },
+    { value: "tabloid", label: "Tabloid" },
+    { value: "joy-mat-standard", label: 'Joy mat 4.5 × 6.5"' },
+    { value: "joy-mat-long", label: 'Joy mat 4.5 × 12"' },
+    { value: "joy-mat-card", label: 'Joy card mat 4.5 × 6.25"' },
+    { value: "joy-smart-material", label: 'Joy Smart Material 4.5 × 48"' },
+];
+/*
+ * The report, rendered.
+ *
+ * 🛑 NOT exported. It was, "so the retry and review surfaces can reuse it" —
+ * which is a consumer that does not exist, and audit-orphan-view-component
+ * caught it as reachable only through a barrel. Split out for readability
+ * inside this file; export it the day something actually imports it.
+ */
+function ExportReportView({ report }) {
+    return (_jsxs(Stack, { gap: "dense", children: [_jsxs(Row, { gap: "sm", wrap: true, align: "center", children: [_jsxs(Badge, { variant: "info", children: [report.pageCount, " page", report.pageCount === 1 ? "" : "s"] }), _jsxs(Badge, { variant: report.overBudget ? "danger" : "success", children: [report.nodesAfter.toLocaleString(), " nodes"] }), report.maxDeviationMm > 0 ? (_jsxs(Badge, { variant: "warning", children: ["\u00B1", report.maxDeviationMm, "mm"] })) : null] }), report.nodesAfter < report.nodesBefore ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Simplified from ", report.nodesBefore.toLocaleString(), " nodes to fit this machine's budget. Worst-case deviation from the traced outline:", " ", _jsxs(Span, { weight: "semibold", children: [report.maxDeviationMm, "mm"] }), "."] })) : null, report.overBudget ? (_jsx(Alert, { variant: "error", children: "Still over this machine's node budget after simplification. Design Space may refuse to open the file \u2014 try the print-shop profile, which has no ceiling, or split the sheet." })) : null, report.unfit.length > 0 ? (_jsx(Alert, { variant: "warning", children: _jsxs(Stack, { gap: "dense", children: [_jsxs(Text, { weight: "semibold", children: [report.unfit.length, " part", report.unfit.length === 1 ? "" : "s", " this machine cannot cut:"] }), report.unfit.map((u) => (_jsxs(Text, { size: "sm", children: [_jsx(Span, { weight: "semibold", children: u.name }), " (", u.widthMm.toFixed(1), " \u00D7 ", u.heightMm.toFixed(1), "mm) \u2014", " ", u.verdict.reasons.join(" ")] }, u.ordinal)))] }) })) : null, report.unplaceable.length > 0 ? (_jsxs(Alert, { variant: "warning", children: [report.unplaceable.length, " part", report.unplaceable.length === 1 ? "" : "s", " would not fit on this page at any rotation:", " ", report.unplaceable.map((u) => u.name).join(", "), ". A larger page, or the print-shop profile, will take them."] })) : null] }));
+}
+export function StickerPrintPanel({ loadReport, onDownloadCutFile, onDownloadMosaic, }) {
+    const [profile, setProfile] = useState("print-shop");
+    const [page, setPage] = useState("a4");
+    const [report, setReport] = useState(null);
+    const [refusedReason, setRefusedReason] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const refresh = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const res = await loadReport(profile, page);
+            setReport(res.report);
+            setRefusedReason(res.refusedReason);
+        }
+        catch (err) {
+            const n = normalizeError(err);
+            /*
+             * Kept distinct from `refusedReason`. A refusal is a true answer about
+             * this sheet — "no confirmed DPI" — while this is the request failing.
+             * Rendering both the same way would have an operator confirming a DPI to
+             * fix a lapsed session.
+             */
+            setError(n.message);
+            setReport(null);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [loadReport, profile, page]);
+    // Re-report on every change: the point of the panel is comparing options.
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    /*
+     * 🛑 Downloads stay enabled while a REFUSAL is showing only when there is
+     * something to download. A refusal means no file exists, so offering the
+     * button would hand the operator a 404 for a reason the panel just explained.
+     */
+    const canDownload = report !== null && refusedReason === null && report.pageCount > 0;
+    return (_jsx(Card, { variant: "default", children: _jsxs(Stack, { gap: "comfortable", children: [_jsx(Heading, { level: 3, children: "Print & export" }), _jsx(FieldSelect, { name: "profile", label: "Machine", value: profile, options: PROFILES, onChange: setProfile }), _jsx(FieldSelect, { name: "page", label: "Page / material", value: page, options: PAGES, onChange: setPage }), error ? _jsx(Alert, { variant: "error", children: error }) : null, refusedReason ? _jsx(Alert, { variant: "warning", children: refusedReason }) : null, loading ? (_jsx(Text, { color: "muted", children: "Checking what this machine can do\u2026" })) : report && !refusedReason ? (_jsx(ExportReportView, { report: report })) : null, _jsxs(Row, { gap: "sm", wrap: true, children: [_jsx(Button, { variant: "primary", disabled: !canDownload, onClick: () => onDownloadCutFile?.(), children: "Download cut file" }), _jsx(Button, { variant: "secondary", disabled: !canDownload, onClick: () => onDownloadMosaic?.(), children: "Download PDF mosaic" })] }), _jsx(Text, { size: "xs", color: "muted", children: "Print the mosaic at 100% \u2014 never \u201Cfit to page\u201D, or the stickers come out the wrong size." })] }) }));
+}

package/dist/features/sticker-trace/components/StickerRetryPanel.d.ts

@@ -0,0 +1,20 @@
+import type { PrecisionTier, TraceParams, TraceStage } from "../../../_internal/shared/features/sticker-trace/types";
+export interface StickerRetryPanelProps {
+    /** The run being retried — its name and params seed the form. */
+    source: {
+        id: string;
+        name: string;
+        tier: PrecisionTier;
+        params?: TraceParams;
+    };
+    /** True once the source run's light artifacts have been pruned. */
+    artifactsPruned?: boolean;
+    onSubmit: (input: {
+        name: string;
+        tier: PrecisionTier;
+        requestedResumeStage: TraceStage;
+        paramOverrides?: Record<string, number>;
+    }) => Promise<void>;
+    onCancel?: () => void;
+}
+export declare function StickerRetryPanel({ source, artifactsPruned, onSubmit, onCancel, }: StickerRetryPanelProps): import("react").JSX.Element;

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

@@ -0,0 +1,128 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: A retry is where the resume clamp becomes visible or invisible, and
+ *      invisible is the dangerous one. The server may move the resume point
+ *      EARLIER than asked; an operator who requested a fast resume and silently
+ *      got a full re-trace concludes the tool is broken.
+ * WHAT: Name the new attempt, pick a tier and a resume point, see what the
+ *       server will actually do before committing to it.
+ *
+ * 🛑 THE CLAMP IS SHOWN, NEVER SWALLOWED. `explainResume()` already returns the
+ * sentence; this panel's entire reason for existing is that something renders
+ * it. Without the clamp a run resumed from `parts` with a changed ridge
+ * threshold would carry artifacts generated under DIFFERENT parameters than the
+ * run records — and nothing anywhere would contradict it. That is Root Cause
+ * #42's shape, which is why the parameter-to-stage grouping is structural
+ * rather than a convention.
+ *
+ * 🛑 The panel PREDICTS the clamp client-side so the operator sees it before
+ * submitting, and the server computes it again independently. Those are not
+ * redundant: the prediction is an affordance, the server's is the decision.
+ * Both call `resolveResumeStage`, so they cannot disagree about which parameter
+ * belongs to which stage.
+ *
+ * 🛑 Built on `<SectionForm>`, not a hand-rolled `<Form>`. Three controls is
+ * where a form stops being trivial, and sectionising is what buys the error
+ * summary, the jump-to-field link and the pinned mobile action bar for free —
+ * audit-form-sectionised is strict-zero on exactly this, and its grandfather
+ * list is empty and closed.
+ *
+ * EXPORTS: StickerRetryPanel
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:tools/sticker-tracer
+ * @tag sideEffects:none
+ */
+import { useCallback, useMemo, useState } from "react";
+import { z } from "zod";
+import { normalizeError } from "../../../errors/normalize.js";
+import { Alert, Card, Stack, Text } from "../../../ui/index.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FieldSelect } from "../../../ui/forms/FieldSelect.js";
+import { SectionForm } from "../../shell/SectionForm.js";
+import { TRACE_STAGES } from "../../../_internal/shared/features/sticker-trace/types.js";
+import { resolveResumeStage, explainResume, } from "../../../_internal/shared/features/sticker-trace/resume.js";
+import { paramsForTier } from "../../../_internal/shared/features/sticker-trace/config.js";
+import { TIER_HELP } from "../constants/help-content.js";
+const TIERS = ["draft", "standard", "precise", "max"];
+/**
+ * 🛑 `.min(1)` on the name, mirroring `requireName` on the server.
+ *
+ * Validated in both places deliberately rather than redundantly: the schema
+ * guards THIS form, `requireName` guards every caller including a future server
+ * action. A rule enforced only at the edge is the one the next caller bypasses.
+ */
+const retrySchema = z.object({
+    name: z.string().min(1, "Name this attempt so you can tell it apart later."),
+    tier: z.enum(["draft", "standard", "precise", "max"]),
+    requested: z.string().min(1),
+});
+export function StickerRetryPanel({ source, artifactsPruned = false, onSubmit, onCancel, }) {
+    /*
+     * Seeded with the source's name plus a marker rather than left blank. A name
+     * is MANDATORY and the server rejects an empty one, so an empty field is a
+     * guaranteed round-trip failure on the most common action in the tool.
+     */
+    const [values, setValues] = useState({
+        name: `${source.name} — retry`,
+        tier: source.tier,
+        requested: "decode",
+    });
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    const onChange = useCallback((partial) => setValues((v) => ({ ...v, ...partial })), []);
+    /*
+     * The next run's parameters, resolved exactly as the server will resolve
+     * them: tier defaults first, overrides second. Comparing anything else would
+     * predict a clamp the server does not apply, or miss one it does.
+     */
+    const nextParams = useMemo(() => paramsForTier(values.tier), [values.tier]);
+    const notice = useMemo(() => {
+        if (!source.params)
+            return "";
+        return explainResume(resolveResumeStage(values.requested, source.params, nextParams));
+    }, [source.params, nextParams, values.requested]);
+    const submit = useCallback(async () => {
+        setPending(true);
+        setError(null);
+        try {
+            await onSubmit({
+                name: values.name.trim(),
+                tier: values.tier,
+                requestedResumeStage: values.requested,
+            });
+        }
+        catch (err) {
+            const n = normalizeError(err);
+            /*
+             * Shown rather than thrown away. A retry that fails silently leaves the
+             * operator looking at a form that did nothing — and the likeliest causes,
+             * a lapsed session or a rejected name, are both named by the message.
+             */
+            setError(n.message);
+        }
+        finally {
+            setPending(false);
+        }
+    }, [values, onSubmit]);
+    const sections = useMemo(() => [
+        {
+            id: "attempt",
+            label: "This attempt",
+            required: true,
+            fields: ["name", "tier"],
+            render: ({ values: v, onChange: set, errors }) => (_jsxs(Stack, { gap: "comfortable", children: [_jsxs(Text, { size: "sm", color: "muted", children: ["This never edits", " ", _jsx(Text, { as: "span", weight: "semibold", children: source.name }), " ", "\u2014 it creates a new attempt beside it, so both stay comparable."] }), _jsx(FieldInput, { name: "name", label: "Name this attempt", required: true, value: v.name, error: errors.name, onChange: (next) => set({ name: next }) }), _jsx(FieldSelect, { name: "tier", label: "Tier", value: v.tier, options: TIERS.map((t) => ({ value: t, label: TIER_HELP[t].title })), onChange: (next) => set({ tier: next }) }), _jsx(Text, { size: "xs", color: "muted", children: TIER_HELP[v.tier].body })] })),
+        },
+        {
+            id: "resume",
+            label: "Where it restarts",
+            fields: ["requested"],
+            render: ({ values: v, onChange: set }) => (_jsxs(Stack, { gap: "comfortable", children: [_jsx(FieldSelect, { name: "requested", label: "Resume from", value: v.requested, options: TRACE_STAGES.map((s) => ({ value: s, label: s })), onChange: (next) => set({ requested: next }) }), notice ? _jsx(Alert, { variant: "warning", children: notice }) : null, artifactsPruned ? (_jsx(Alert, { variant: "warning", children: "This run's artifacts have been cleared, so the retry starts from the beginning whatever you pick here." })) : null, !source.params ? (_jsx(Text, { size: "xs", color: "muted", children: "This run predates parameter recording, so the resume point cannot be checked ahead of time \u2014 the server will decide and tell you." })) : null] })),
+        },
+    ], [source.name, source.params, notice, artifactsPruned]);
+    return (_jsx(Card, { variant: "default", children: _jsxs(Stack, { gap: "comfortable", children: [error ? _jsx(Alert, { variant: "error", children: error }) : null, _jsx(SectionForm, { sections: sections, values: values, onChange: onChange, onSubmit: submit, schema: retrySchema, submitLabel: "Start retry", isLoading: pending, onCancel: onCancel, cancelLabel: "Cancel" })] }) }));
+}

package/dist/features/sticker-trace/components/StickerRunHistoryPanel.d.ts

@@ -0,0 +1,45 @@
+/** One attempt. Mirrors the route's projection — booleans, never paths. */
+export interface StickerRunRow {
+    id: string;
+    name: string;
+    tier: string;
+    status: string;
+    stage: string | null;
+    partCount: number;
+    groupCount: number;
+    durationMs: number | null;
+    createdAt: string;
+    finishedAt: string | null;
+    isActive: boolean;
+    isPromoted: boolean;
+    has: {
+        preview: boolean;
+        overlay: boolean;
+        geometry: boolean;
+        cutSvg: boolean;
+        thumbAtlas: boolean;
+    };
+    error?: {
+        stage: string;
+        code: string;
+        message: string;
+        partOrdinal?: number;
+    } | null;
+}
+export interface StickerRunHistoryPanelProps {
+    runs: readonly StickerRunRow[];
+    loading?: boolean;
+    /** Open a run's overlay or preview. Resolves a signed URL; the panel never holds one. */
+    onOpenAsset?: (runId: string, kind: "preview" | "overlay" | "cutSvg") => void;
+    /** Start a retry from this run — the retry panel takes it from here. */
+    onRetry?: (run: StickerRunRow) => void;
+    /**
+     * Accept this run as the sheet's result and render its parts full-size.
+     *
+     * 🛑 Offered only on a SUCCEEDED run that is not already active. Promoting a
+     * failed run would copy a partial result onto the sheet, and re-promoting the
+     * active one spends the whole render budget to reach the state it is in.
+     */
+    onPromote?: (run: StickerRunRow) => void;
+}
+export declare function StickerRunHistoryPanel({ runs, loading, onOpenAsset, onRetry, onPromote, }: StickerRunHistoryPanelProps): import("react").JSX.Element;

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

@@ -0,0 +1,84 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Tuning a halftone scan takes several attempts, and the attempts ARE the
+ *      deliverable — "run 2 died at ridge, run 1's parts are still the accepted
+ *      set" is the question this feature exists to answer. Until now the runs
+ *      existed in Firestore with nothing able to list them.
+ * WHAT: Every attempt on one sheet, newest first, with what each produced.
+ *
+ * 🛑 A run is NEVER overwritten. A retry is a new named run, so this list only
+ * grows — which is why each row leads with the NAME the operator typed rather
+ * than an id. "Untitled (3)" would defeat the whole point at the moment it
+ * matters most.
+ *
+ * 🛑 It renders `has.*` BOOLEANS, never paths. The list action returns a
+ * projection with no `*Path` fields at all: an artifact's existence is all a
+ * list needs in order to offer "open overlay", and the path would be a private
+ * Storage location that must not reach a client
+ * (PRIVATE_TRACE_RUN_FIELDS, audit-public-projection-parity).
+ *
+ * EXPORTS: StickerRunHistoryPanel, StickerRunRow
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:tools/sticker-tracer
+ * @tag sideEffects:none
+ */
+import { useCallback, useMemo } from "react";
+import { Badge, Button, Card, Heading, Row, Span, Stack, Text, } from "../../../ui/index.js";
+import { TIER_HELP } from "../constants/help-content.js";
+/**
+ * 🛑 `succeeded` is NOT the same as `isActive`, and the badges keep them apart.
+ *
+ * A run can succeed and still not be the sheet's accepted result — that is the
+ * normal case once you have tried three tiers. Collapsing the two would make
+ * "which parts does this sheet actually show" unanswerable from the list, which
+ * is most of what the list is for.
+ */
+function statusTone(status) {
+    if (status === "succeeded")
+        return "success";
+    if (status === "failed")
+        return "danger";
+    if (status === "cancelled")
+        return "warning";
+    return "info";
+}
+function formatDuration(ms) {
+    if (ms === null)
+        return "—";
+    if (ms < 1000)
+        return `${ms} ms`;
+    const s = Math.round(ms / 100) / 10;
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${Math.round(s % 60)}s`;
+}
+/**
+ * Dates are formatted with an EXPLICIT locale and options.
+ *
+ * A bare `toLocaleString()` renders differently on the server and in the
+ * browser, which React reports as a hydration mismatch on a component whose
+ * only job is to be read.
+ */
+const STAMP = {
+    day: "2-digit",
+    month: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+};
+export function StickerRunHistoryPanel({ runs, loading = false, onOpenAsset, onRetry, onPromote, }) {
+    const open = useCallback((runId, kind) => () => onOpenAsset?.(runId, kind), [onOpenAsset]);
+    const sorted = useMemo(() => [...runs].sort((a, b) => b.createdAt.localeCompare(a.createdAt)), [runs]);
+    if (loading) {
+        return (_jsx(Card, { variant: "default", children: _jsx(Text, { color: "muted", children: "Loading attempts\u2026" }) }));
+    }
+    if (sorted.length === 0) {
+        return (_jsx(Card, { variant: "default", children: _jsxs(Stack, { gap: "dense", children: [_jsx(Heading, { level: 3, children: "Attempts" }), _jsx(Text, { color: "muted", children: "No runs yet. Tune the parameters above, give the attempt a name, and commit it \u2014 every attempt is kept so you can compare them later." })] }) }));
+    }
+    return (_jsxs(Stack, { gap: "comfortable", children: [_jsxs(Heading, { level: 3, children: ["Attempts (", sorted.length, ")"] }), sorted.map((run) => (_jsx(Card, { variant: "default", children: _jsxs(Stack, { gap: "dense", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Row, { align: "center", gap: "sm", wrap: true, children: [_jsx(Text, { weight: "bold", children: run.name }), _jsx(Badge, { variant: statusTone(run.status), children: run.status }), run.isActive ? _jsx(Badge, { variant: "info", children: "accepted" }) : null, run.isPromoted ? _jsx(Badge, { variant: "success", children: "promoted" }) : null] }), _jsx(Text, { size: "xs", color: "muted", children: new Date(run.createdAt).toLocaleString("en-GB", STAMP) })] }), _jsxs(Text, { size: "sm", color: "muted", children: [TIER_HELP[run.tier]?.title ?? run.tier, " · ", run.partCount, " part", run.partCount === 1 ? "" : "s", run.groupCount > 1 ? ` in ${run.groupCount} sheets` : "", " · ", formatDuration(run.durationMs)] }), run.status === "failed" && run.error ? (_jsxs(Text, { size: "sm", color: "error", role: "alert", children: ["Failed at ", _jsx(Span, { weight: "semibold", children: run.error.stage }), typeof run.error.partOrdinal === "number"
+                                    ? ` on part ${run.error.partOrdinal}`
+                                    : "", ": ", run.error.message] })) : null, run.status === "running" && run.stage ? (_jsxs(Text, { size: "sm", color: "muted", children: ["Currently in ", _jsx(Span, { weight: "semibold", children: run.stage }), "."] })) : null, _jsxs(Row, { gap: "sm", wrap: true, children: [run.has.preview ? (_jsx(Button, { size: "sm", variant: "secondary", onClick: open(run.id, "preview"), children: "Preview" })) : null, run.has.overlay ? (_jsx(Button, { size: "sm", variant: "secondary", onClick: open(run.id, "overlay"), children: "Overlay" })) : null, run.has.cutSvg ? (_jsx(Button, { size: "sm", variant: "secondary", onClick: open(run.id, "cutSvg"), children: "Cut file" })) : null, onRetry ? (_jsx(Button, { size: "sm", variant: "ghost", onClick: () => onRetry(run), children: "Retry from this" })) : null, onPromote && run.status === "succeeded" && !run.isActive ? (_jsx(Button, { size: "sm", variant: "primary", onClick: () => onPromote(run), children: "Accept & render" })) : null] })] }) }, run.id)))] }));
+}

package/dist/features/sticker-trace/components/StickerTraceStudio.d.ts

@@ -0,0 +1,27 @@
+import type { TraceParams } from "../../../_internal/shared/features/sticker-trace/types";
+export interface StickerTraceStudioProps {
+    /**
+     * Rendered under the canvas — where a parent puts "commit this as a run".
+     *
+     * 🛑 `dimensions` are the scan's NATURAL size, from `codec.probe` — NOT the
+     * raster's. The working raster is capped at the tier's `workingLongEdge`
+     * (1200 at draft), so handing over `raster.width` would record the draft
+     * size as the scan's true size on the sheet document, and every millimetre
+     * derived from it afterwards would be wrong by the downscale factor.
+     *
+     * The browser is the only party that can measure this at all: appkit cannot
+     * probe an image (the codec is injected, Root Cause #24) and reading the
+     * header server-side would mean pulling up to 100 MB into a function, which
+     * is the egress mistake this feature exists to avoid. Null until the probe
+     * lands.
+     */
+    renderCommit?: (ctx: {
+        params: TraceParams;
+        file: File | null;
+        dimensions: {
+            widthPx: number;
+            heightPx: number;
+        } | null;
+    }) => React.ReactNode;
+}
+export declare function StickerTraceStudio({ renderCommit }: StickerTraceStudioProps): import("react").JSX.Element;