@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/server/features/sticker-trace/actions.d.ts

@@ -0,0 +1,109 @@
+import { type StickerTraceRunDocument } from "../../../../features/sticker-trace/schemas/firestore";
+import { type ResumeDecision } from "../../../shared/features/sticker-trace/resume";
+import type { PrecisionTier, TraceParams, TraceStage } from "../../../shared/features/sticker-trace/types";
+/** What a caller needs to watch a run it just started. */
+export interface TraceRunHandle {
+    runId: string;
+    /** Carries the single `stickerTraceRunId` claim for this run's channel. */
+    customToken: string;
+}
+export interface StartTraceRunInput {
+    sheetId: string;
+    /** 🛑 Mandatory, and validated here rather than trusted. */
+    name: string;
+    tier: PrecisionTier;
+    requestedBy: string;
+    /** Advanced-panel overrides on top of the tier's defaults. */
+    paramOverrides?: Partial<TraceParams>;
+}
+/**
+ * Start the first trace of a sheet.
+ *
+ * The sheet is read to confirm it exists before a run is written against it —
+ * a run whose `sheetId` points at nothing is an orphan that every list query
+ * returns and no page can open.
+ */
+export declare function startStickerTraceRun(input: StartTraceRunInput): Promise<TraceRunHandle>;
+export interface RetryTraceRunInput {
+    sheetId: string;
+    /** The run being retried. Read for its params; never modified. */
+    sourceRunId: string;
+    name: string;
+    tier: PrecisionTier;
+    requestedBy: string;
+    paramOverrides?: Partial<TraceParams>;
+    /** Where the operator asked to resume from. Clamped, never silently. */
+    requestedResumeStage?: TraceStage;
+}
+export interface RetryTraceRunResult extends TraceRunHandle {
+    resume: ResumeDecision;
+    /** The sentence the retry panel shows. Empty when nothing was clamped. */
+    notice: string;
+}
+/**
+ * Retry a run.
+ *
+ * 🛑 A retry is a NEW named run. Editing the old one would destroy the only
+ * thing attempt history is for — being able to compare "standard vs precise on
+ * the same sheet" weeks later, and to see that run 2 died at `ridge`.
+ *
+ * 🛑 Resuming requires the source run's artifacts to still EXIST. Retention
+ * may have stripped them, and a resume from `parts` against a run whose
+ * geometry is gone would read every missing artifact as an empty result — a
+ * successful-looking run with no parts. `artifactsPruned` is checked and the
+ * resume point is forced back to the start rather than failing, because
+ * restarting is what the operator wants and being told why is what they need.
+ */
+export declare function retryStickerTraceRun(input: RetryTraceRunInput): Promise<RetryTraceRunResult>;
+/**
+ * One row of a sheet's attempt history.
+ *
+ * 🛑 A PROJECTION, not the run document. Every `*Path` on a run is a raw
+ * Storage path under `private/sticker-sheets/…` and must never reach a client
+ * — the bucket's own rule is `allow read: if true`, so containment is the
+ * application's job. The panel needs to know an artifact EXISTS so it can
+ * offer a link; the path itself is resolved to a short-lived signed URL by an
+ * authenticated route when the link is actually clicked.
+ *
+ * `events` is omitted too: up to 100 entries per run times N runs is a large
+ * payload for a list nobody expands, and the detail view fetches one run.
+ */
+export interface TraceRunListRow {
+    id: string;
+    name: string;
+    tier: StickerTraceRunDocument["tier"];
+    status: StickerTraceRunDocument["status"];
+    stage: StickerTraceRunDocument["stage"];
+    partCount: number;
+    groupCount: number;
+    durationMs: number | null;
+    createdAt: Date;
+    finishedAt: Date | null;
+    /** Whether this run is the sheet's currently accepted result. */
+    isActive: boolean;
+    /** True once promoted — i.e. full-resolution parts exist. */
+    isPromoted: boolean;
+    /** Which artifacts exist, WITHOUT their paths. */
+    has: {
+        preview: boolean;
+        overlay: boolean;
+        geometry: boolean;
+        cutSvg: boolean;
+        thumbAtlas: boolean;
+    };
+    /** Present only on a failure, already user-safe. */
+    error: StickerTraceRunDocument["error"] | null;
+}
+/**
+ * A sheet's attempt history, newest first.
+ *
+ * Served by the `(sheetId, createdAt desc)` composite index deployed in P4, so
+ * this is one query regardless of how many runs a sheet has accumulated.
+ *
+ * 🛑 `activeRunId` comes from the SHEET, not from a flag on each run. A
+ * per-run `isActive` boolean would be a mirror that needs clearing on every
+ * other run whenever one is promoted — and the first write path that forgot
+ * would show two active runs with nothing contradicting it (Root Cause #42).
+ * One read of the sheet decides it for the whole list.
+ */
+export declare function listStickerTraceRuns(sheetId: string, limit?: number): Promise<TraceRunListRow[]>;

package/dist/_internal/server/features/sticker-trace/actions.js

@@ -0,0 +1,172 @@
+/*
+ * WHY: A trace is started once and retried several times, and the retries are
+ *      the point — tuning a halftone scan takes a few goes. Every attempt has
+ *      to be a record you can come back to, which means a retry creates a new
+ *      run and never edits the old one.
+ * WHAT: Start, and retry-with-resume.
+ *
+ * 🛑 Returns a PLAIN object, not an `ActionResult` envelope — mirroring
+ * `enqueueJob`, which these are modelled on. That is deliberate rather than
+ * casual: an envelope spread as if it were the payload is Root Cause #98,
+ * where `{ ok, data }` reached nine edit pages as `initialValues`, every field
+ * resolved `undefined`, and pressing Save wrote `draft` over live listings.
+ * These throw on failure; the route's `createRouteHandler` maps that.
+ *
+ * EXPORTS: StartTraceRunInput, RetryTraceRunInput, TraceRunHandle,
+ *   startStickerTraceRun, retryStickerTraceRun
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets
+ * @tag sideEffects:firestore,rtdb
+ */
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+import { stickerTraceRunsRepository } from "../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js";
+import { TraceRunStatusValues, } from "../../../../features/sticker-trace/schemas/firestore.js";
+import { paramsForTier } from "../../../shared/features/sticker-trace/config.js";
+import { explainResume, resolveResumeStage, } from "../../../shared/features/sticker-trace/resume.js";
+import { emitProgress, mintStickerTraceToken } from "./progress.js";
+/**
+ * A name is required to process, and this is where that is enforced.
+ *
+ * Trimmed before the length check, so "   " is rejected rather than stored as
+ * a run nobody can tell apart from the next one — which is the whole reason
+ * the field is mandatory.
+ */
+function requireName(raw) {
+    const name = (raw ?? "").trim();
+    if (name.length === 0) {
+        throw new ValidationError("Give this run a name so you can tell it apart later.", {
+            name: "A name is required.",
+        });
+    }
+    return name;
+}
+async function createRun(input) {
+    const run = await stickerTraceRunsRepository.create(input);
+    /*
+     * Seed the channel BEFORE returning the token, so a client that subscribes
+     * immediately finds a node rather than an absence it cannot distinguish from
+     * a run that never started. `emitProgress` never throws, so a failure here
+     * costs the live bar and not the run.
+     */
+    await emitProgress({ runId: run.id, stage: "queued", pct: 0, prior: run });
+    return { runId: run.id, customToken: await mintStickerTraceToken(run.id) };
+}
+/**
+ * Start the first trace of a sheet.
+ *
+ * The sheet is read to confirm it exists before a run is written against it —
+ * a run whose `sheetId` points at nothing is an orphan that every list query
+ * returns and no page can open.
+ */
+export async function startStickerTraceRun(input) {
+    const name = requireName(input.name);
+    await stickerSheetsRepository.findByIdOrFail(input.sheetId);
+    /*
+     * Tier defaults FIRST, overrides second. The run records the parameters it
+     * actually used, which is what makes the resume clamp meaningful — a run
+     * storing a tier name and resolving defaults later could not tell whether
+     * its artifacts predated a default changing.
+     */
+    const params = {
+        ...paramsForTier(input.tier),
+        ...(input.paramOverrides ?? {}),
+    };
+    const handle = await createRun({
+        sheetId: input.sheetId,
+        name,
+        tier: input.tier,
+        params,
+        requestedBy: input.requestedBy,
+    });
+    await stickerSheetsRepository.update(input.sheetId, {
+        traceStatus: TraceRunStatusValues.QUEUED,
+    });
+    return handle;
+}
+/**
+ * Retry a run.
+ *
+ * 🛑 A retry is a NEW named run. Editing the old one would destroy the only
+ * thing attempt history is for — being able to compare "standard vs precise on
+ * the same sheet" weeks later, and to see that run 2 died at `ridge`.
+ *
+ * 🛑 Resuming requires the source run's artifacts to still EXIST. Retention
+ * may have stripped them, and a resume from `parts` against a run whose
+ * geometry is gone would read every missing artifact as an empty result — a
+ * successful-looking run with no parts. `artifactsPruned` is checked and the
+ * resume point is forced back to the start rather than failing, because
+ * restarting is what the operator wants and being told why is what they need.
+ */
+export async function retryStickerTraceRun(input) {
+    const name = requireName(input.name);
+    const source = await stickerTraceRunsRepository.findByIdOrFail(input.sourceRunId);
+    if (source.sheetId !== input.sheetId) {
+        throw new ValidationError("That run belongs to a different sheet.", {
+            sourceRunId: "Run and sheet do not match.",
+        });
+    }
+    const params = {
+        ...paramsForTier(input.tier),
+        ...(input.paramOverrides ?? {}),
+    };
+    const requested = input.requestedResumeStage ?? "decode";
+    let resume = resolveResumeStage(requested, source.params, params);
+    let notice = explainResume(resume);
+    if (source.artifactsPruned && resume.stage !== "decode") {
+        resume = { stage: "decode", clamped: true, requested, forcedBy: resume.forcedBy };
+        notice =
+            "This run's intermediate files were cleared, so there is nothing to resume " +
+                "from — the retry starts from the beginning.";
+    }
+    const handle = await createRun({
+        sheetId: input.sheetId,
+        name,
+        tier: input.tier,
+        params,
+        requestedBy: input.requestedBy,
+    });
+    return { ...handle, resume, notice };
+}
+/**
+ * A sheet's attempt history, newest first.
+ *
+ * Served by the `(sheetId, createdAt desc)` composite index deployed in P4, so
+ * this is one query regardless of how many runs a sheet has accumulated.
+ *
+ * 🛑 `activeRunId` comes from the SHEET, not from a flag on each run. A
+ * per-run `isActive` boolean would be a mirror that needs clearing on every
+ * other run whenever one is promoted — and the first write path that forgot
+ * would show two active runs with nothing contradicting it (Root Cause #42).
+ * One read of the sheet decides it for the whole list.
+ */
+export async function listStickerTraceRuns(sheetId, limit = 50) {
+    const sheet = await stickerSheetsRepository.findByIdOrFail(sheetId);
+    const runs = await stickerTraceRunsRepository.listBySheet(sheetId, limit);
+    return runs.map((run) => ({
+        id: run.id,
+        name: run.name,
+        tier: run.tier,
+        status: run.status,
+        stage: run.stage,
+        partCount: run.partCount,
+        groupCount: run.groupCount,
+        durationMs: run.durationMs ?? null,
+        createdAt: run.createdAt,
+        finishedAt: run.finishedAt ?? null,
+        isActive: sheet.activeRunId === run.id,
+        isPromoted: Boolean(run.promoted),
+        has: {
+            preview: Boolean(run.artifacts?.previewPath),
+            overlay: Boolean(run.artifacts?.overlayPath),
+            geometry: Boolean(run.artifacts?.geometryPath),
+            cutSvg: Boolean(run.artifacts?.cutSvgPath),
+            thumbAtlas: Boolean(run.artifacts?.thumbAtlasPath),
+        },
+        error: run.error ?? null,
+    }));
+}

package/dist/_internal/server/features/sticker-trace/adapters.d.ts

@@ -0,0 +1,91 @@
+import type { DpiSource, StickerSheetDocument, StickerTraceRunDocument, TraceRunError, TraceRunEvent, TraceRunStatus } from "../../../../features/sticker-trace/schemas/firestore";
+import type { PrecisionTier, Rect, ScanType, TraceParams, TraceStage } from "../../../shared/features/sticker-trace/types";
+export declare const PUBLIC_STICKER_SHEET_FIELDS: readonly ["id", "title", "scanType", "dpi", "dpiSource", "widthPx", "heightPx", "activeRunId", "traceStatus", "partCount", "groupCount", "parts", "createdAt", "updatedAt"];
+export declare const PRIVATE_STICKER_SHEET_FIELDS: readonly ["sourceScan", "artifacts"];
+export declare const PUBLIC_TRACE_RUN_FIELDS: readonly ["id", "sheetId", "name", "tier", "params", "requestedBy", "startedAt", "finishedAt", "durationMs", "status", "stage", "events", "eventsTruncated", "partCount", "groupCount", "shardCount", "error", "artifactsPruned", "createdAt", "updatedAt"];
+export declare const PRIVATE_TRACE_RUN_FIELDS: readonly ["artifacts", "promoted"];
+/** A part as the review UI sees it: geometry and identity, never a path. */
+export interface ClientSheetPart {
+    ordinal: number;
+    name: string;
+    groupIndex: number;
+    bboxPx: Rect;
+    /** Null whenever dpi is untrustworthy — never a fabricated millimetre. */
+    bboxMm: Rect | null;
+    areaMm2: number | null;
+    /** Whether a full-resolution render exists, NOT where it is. */
+    hasAsset: boolean;
+    /**
+     * The PUBLIC `/media/{shortId}` slug, when the part has been promoted.
+     *
+     * 🛑 Public on purpose and NOT a path. A `mediaShortId` is already a public
+     * URL by construction — a `mediaAssets` row IS what mints `/media/{id}`, and
+     * `/api/media/[...slug]` serves it to anyone, watermarked. So the thing it
+     * names is public whether or not this field is projected, and the admin
+     * review UI genuinely needs it to show the marketplace copy beside the clean
+     * one. `assetPath` stays private: that is the unwatermarked original.
+     */
+    mediaShortId?: string;
+    duplicateOf?: number;
+}
+export interface ClientStickerSheet {
+    id: string;
+    title: string;
+    scanType: ScanType;
+    dpi?: number;
+    dpiSource?: DpiSource;
+    widthPx: number;
+    heightPx: number;
+    /** Size only. The path and hash never leave the server. */
+    sourceScanBytes: number;
+    activeRunId?: string;
+    traceStatus: TraceRunStatus;
+    partCount: number;
+    groupCount: number;
+    parts: ClientSheetPart[];
+    hasPreview: boolean;
+    hasOverlay: boolean;
+    hasGeometry: boolean;
+    hasCutSvg: boolean;
+    hasCricutSvg: boolean;
+    hasPrintThenCutSvg: boolean;
+    hasPdfMosaic: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ClientTraceRun {
+    id: string;
+    sheetId: string;
+    name: string;
+    tier: PrecisionTier;
+    params: TraceParams;
+    requestedBy: string;
+    startedAt?: Date;
+    finishedAt?: Date;
+    durationMs?: number;
+    status: TraceRunStatus;
+    stage?: TraceStage | "queued" | "done";
+    events: TraceRunEvent[];
+    eventsTruncated?: number;
+    partCount: number;
+    groupCount: number;
+    shardCount?: number;
+    error?: TraceRunError;
+    artifactsPruned?: boolean;
+    hasPreview: boolean;
+    hasOverlay: boolean;
+    hasGeometry: boolean;
+    hasCutSvg: boolean;
+    hasThumbAtlas: boolean;
+    /** Promotion is a fact about the run; its paths are not. */
+    promotedAt?: Date;
+    promotedBy?: string;
+    promotedPartCount: number;
+    hasCricutSvg: boolean;
+    hasPrintThenCutSvg: boolean;
+    hasPdfMosaic: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export declare function toClientStickerSheet(doc: StickerSheetDocument): ClientStickerSheet;
+export declare function toClientTraceRun(doc: StickerTraceRunDocument): ClientTraceRun;

package/dist/_internal/server/features/sticker-trace/adapters.js

@@ -0,0 +1,175 @@
+/*
+ * WHY: Every `*Path` on these documents is a raw private Storage path. A
+ *      document field is private until someone names it public, and the only
+ *      thing that actually removes a field at runtime is a function that builds
+ *      a NEW object.
+ * WHAT: The sheet and run projections, with every schema field triaged.
+ *
+ * 🛑 ALLOW-LIST, never spread-and-delete. A denial keyed on a TypeScript
+ * interface is structurally blind to fields the interface does not declare —
+ * which is exactly how `adSettings.providerCredentials` went out unmasked from
+ * `GET /api/site-settings` (Root Cause #70). These build literals.
+ *
+ * 🛑 A NARROW PROP TYPE STRIPS NOTHING. TypeScript's structural typing accepts
+ * a wider object without complaint and Next serialises whatever the value
+ * actually is, so typing a client prop `ClientStickerSheet` while passing a
+ * `StickerSheetDocument` publishes every path in it. Only these functions
+ * remove anything.
+ *
+ * 🛑 PATHS ARE REPLACED BY BOOLEANS, not omitted silently. The review UI needs
+ * to know an overlay EXISTS so it can offer the button; it must never learn
+ * WHERE. It then asks an authenticated route for a 5-minute signed URL. A bare
+ * omission would have left the UI unable to tell "no overlay" from "overlay I
+ * cannot see", and the obvious fix for that is to leak the path.
+ *
+ * EXPORTS: ClientStickerSheet, ClientSheetPart, ClientTraceRun,
+ *   toClientStickerSheet, toClientTraceRun,
+ *   PUBLIC_STICKER_SHEET_FIELDS, PRIVATE_STICKER_SHEET_FIELDS,
+ *   PUBLIC_TRACE_RUN_FIELDS, PRIVATE_TRACE_RUN_FIELDS
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:adapter
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets,sticker-trace/components
+ * @tag sideEffects:none
+ */
+/*
+ * ---------------------------------------------------------------------------
+ * The triage. Every schema field appears in exactly ONE of these lists, with a
+ * reason on each private entry. audit-public-projection-parity fails on an
+ * untriaged field, so adding one to the schema forces a decision here.
+ * ---------------------------------------------------------------------------
+ */
+export const PUBLIC_STICKER_SHEET_FIELDS = [
+    "id",
+    "title",
+    "scanType",
+    "dpi",
+    "dpiSource", // always shown and always confirmable — see the schema's 🛑
+    "widthPx",
+    "heightPx",
+    "activeRunId",
+    "traceStatus",
+    "partCount",
+    "groupCount",
+    "parts", // projected per-part; `assetPath` stripped inside
+    "createdAt",
+    "updatedAt",
+];
+export const PRIVATE_STICKER_SHEET_FIELDS = [
+    // Carries assetPath (a raw private Storage path) and sha256. Only `bytes` is
+    // surfaced, as sourceScanBytes, for the usage meter.
+    "sourceScan",
+    // Every member is a raw private Storage path. The client gets booleans here
+    // and a 5-minute signed URL from an authenticated route.
+    "artifacts",
+];
+export const PUBLIC_TRACE_RUN_FIELDS = [
+    "id",
+    "sheetId",
+    "name",
+    "tier",
+    "params", // the retry panel shows and edits these
+    "requestedBy", // an Auth UID, never a name or an email — the actorUid rule
+    "startedAt",
+    "finishedAt",
+    "durationMs",
+    "status",
+    "stage",
+    "events", // the progress history the panel renders; messages are user-safe by contract
+    "eventsTruncated",
+    "partCount",
+    "groupCount",
+    "shardCount",
+    "error", // stage/code/message/partOrdinal — message resolved through toUserMessage
+    "artifactsPruned", // the retry panel MUST know artifacts are gone before offering resume
+    "createdAt",
+    "updatedAt",
+];
+export const PRIVATE_TRACE_RUN_FIELDS = [
+    // Raw private Storage paths (preview/overlay/geometry/cutSvg/thumbAtlas).
+    // Surfaced as hasPreview/hasOverlay/hasGeometry/hasCutSvg/hasThumbAtlas.
+    "artifacts",
+    // partAssetPaths plus the three export paths are all raw Storage paths.
+    // `at`/`by` are surfaced as promotedAt/promotedBy, the count as
+    // promotedPartCount.
+    "promoted",
+];
+function toClientPart(part) {
+    return {
+        ordinal: part.ordinal,
+        name: part.name,
+        groupIndex: part.groupIndex,
+        bboxPx: part.bboxPx,
+        bboxMm: part.bboxMm,
+        areaMm2: part.areaMm2,
+        hasAsset: Boolean(part.assetPath),
+        ...(part.mediaShortId !== undefined ? { mediaShortId: part.mediaShortId } : {}),
+        ...(part.duplicateOf !== undefined ? { duplicateOf: part.duplicateOf } : {}),
+    };
+}
+export function toClientStickerSheet(doc) {
+    const a = doc.artifacts ?? {};
+    return {
+        id: doc.id,
+        title: doc.title,
+        scanType: doc.scanType,
+        dpi: doc.dpi,
+        dpiSource: doc.dpiSource,
+        widthPx: doc.widthPx,
+        heightPx: doc.heightPx,
+        sourceScanBytes: doc.sourceScan?.bytes ?? 0,
+        activeRunId: doc.activeRunId,
+        traceStatus: doc.traceStatus,
+        partCount: doc.partCount,
+        groupCount: doc.groupCount,
+        parts: (doc.parts ?? []).map(toClientPart),
+        hasPreview: Boolean(a.previewPath),
+        hasOverlay: Boolean(a.overlayPath),
+        hasGeometry: Boolean(a.geometryPath),
+        hasCutSvg: Boolean(a.cutSvgPath),
+        hasCricutSvg: Boolean(a.cricutSvgPath),
+        hasPrintThenCutSvg: Boolean(a.printThenCutSvgPath),
+        hasPdfMosaic: Boolean(a.pdfMosaicPath),
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt,
+    };
+}
+export function toClientTraceRun(doc) {
+    const a = doc.artifacts ?? {};
+    const p = doc.promoted ?? null;
+    return {
+        id: doc.id,
+        sheetId: doc.sheetId,
+        name: doc.name,
+        tier: doc.tier,
+        params: doc.params,
+        requestedBy: doc.requestedBy,
+        startedAt: doc.startedAt,
+        finishedAt: doc.finishedAt,
+        durationMs: doc.durationMs,
+        status: doc.status,
+        stage: doc.stage,
+        events: doc.events ?? [],
+        eventsTruncated: doc.eventsTruncated,
+        partCount: doc.partCount,
+        groupCount: doc.groupCount,
+        shardCount: doc.shardCount,
+        error: doc.error,
+        artifactsPruned: doc.artifactsPruned,
+        hasPreview: Boolean(a.previewPath),
+        hasOverlay: Boolean(a.overlayPath),
+        hasGeometry: Boolean(a.geometryPath),
+        hasCutSvg: Boolean(a.cutSvgPath),
+        hasThumbAtlas: Boolean(a.thumbAtlasPath),
+        ...(p?.at ? { promotedAt: p.at } : {}),
+        ...(p?.by ? { promotedBy: p.by } : {}),
+        promotedPartCount: p?.partAssetPaths?.length ?? 0,
+        hasCricutSvg: Boolean(p?.cricutSvgPath),
+        hasPrintThenCutSvg: Boolean(p?.printThenCutSvgPath),
+        hasPdfMosaic: Boolean(p?.pdfMosaicPath),
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt,
+    };
+}

package/dist/_internal/server/features/sticker-trace/build-cut-file.d.ts

@@ -0,0 +1,26 @@
+import { type ExportSet } from "../../../shared/features/sticker-trace/export/build-export-set";
+import { MACHINE_PROFILES } from "../../../shared/features/sticker-trace/export/machine-profiles";
+import { type PrintPageSizeId } from "../../../shared/features/sticker-trace/export/page-sizes";
+export interface BuildCutFileOptions {
+    profileId?: keyof typeof MACHINE_PROFILES;
+    pageSizeId?: PrintPageSizeId;
+}
+/**
+ * Build the export set for one run.
+ *
+ * Returns the full `ExportSet` — including `refusedReason` — because the print
+ * modal needs the report (unfit parts, node deviation, page count) and not just
+ * the bytes. `buildCutFileBytes` is the narrow wrapper the finalizer uses.
+ */
+export declare function buildCutFileForRun(runId: string, sheetId: string, opts?: BuildCutFileOptions): Promise<ExportSet>;
+/**
+ * The finalizer's hook: bytes, or null.
+ *
+ * 🛑 Only the FIRST page is written as `cut.svg`. A multi-page export is a
+ * print-modal concern — the run's own artifact is one file, and silently
+ * concatenating pages into it would produce a document that overlays every
+ * page on top of the first. Multi-page sheets are rare at print-shop sizes and
+ * the count is reported, so this is a bounded simplification rather than a
+ * hidden one.
+ */
+export declare function buildCutFileBytes(runId: string, sheetId: string): Promise<Uint8Array | null>;