@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/_internal/server/features/seo/robots.js

@@ -1,3 +1,6 @@
+// The defining module, not the `/client` entry — this is reached from
+// server-only metadata paths (Root Cause #76).
+import { ROUTES } from "../../../../next/routing/route-map.js";
 export function buildRobots({ siteUrl }) {
     return {
         rules: [
@@ -12,7 +15,24 @@ export function buildRobots({ siteUrl }) {
                     "/auth/",
                     "/checkout/",
                     "/cart/",
-                    "/wishlist",
+                    /*
+                     * The one entry here that is a PAGE rather than a subtree prefix —
+                     * its twelve siblings end in "/" because they disallow a whole tree,
+                     * and `/wishlist` is a single route. So it genuinely is a route
+                     * reference and takes the constant; the earlier
+                     * eslint-disable here was treating a real finding as noise.
+                     */
+                    ROUTES.USER.WISHLIST,
+                    /*
+                     * Admin-only tool under a public prefix. Belongs here for the same
+                     * reason /admin/ does, and takes the CONSTANT rather than a literal
+                     * so a route rename cannot leave this entry pointing at nothing.
+                     *
+                     * 🛑 A Disallow stops the crawl, which means the page's own
+                     * `noindex` is never read — the layout's server-side redirect is
+                     * what actually guarantees there is no indexable content here.
+                     */
+                    ROUTES.PUBLIC.TOOL_STICKER_TRACER,
                     "/preview/",
                     "/track/",
                     "/unauthorized/",

package/dist/_internal/server/features/seo/sitemap.js

@@ -117,7 +117,7 @@ function staticPages(baseUrl) {
         page(String(ROUTES.PUBLIC.AUCTIONS), "daily", 0.9),
         page(String(ROUTES.PUBLIC.CATEGORIES), "weekly", 0.8),
         page(String(ROUTES.PUBLIC.BRANDS), "weekly", 0.7),
-        page(String(ROUTES.PUBLIC.BLOG), "daily", 0.7),
+        page(String(ROUTES.BLOG.LIST), "daily", 0.7),
         page(String(ROUTES.PUBLIC.EVENTS), "daily", 0.7),
         page(String(ROUTES.PUBLIC.SELLERS), "weekly", 0.6),
         page(String(ROUTES.PUBLIC.ABOUT), "monthly", 0.5),

package/dist/_internal/server/features/shared/listing-data-factory.js

@@ -55,14 +55,26 @@ export const getProductFeaturesForStore = cache(async (storeId) => safeRead(() =
 // Export names in stores/data.ts stay identical so consumers need no changes.
 export function makeGetStoreListingsInitial(type, pageSize) {
     return cache(async (storeId, page = 1) => {
-        const result = await productRepository
-            .list({
+        /*
+         * 🛑 `safeRead`, not `.catch(() => null)`. This factory backs every
+         * per-type store listing tab, so a swallowed failure renders a seller's
+         * page as "no listings" — which is Root Cause #59's exact shape, where a
+         * `FAILED_PRECONDITION` from a missing composite index was indistinguishable
+         * from an empty catalogue and stayed invisible for weeks.
+         *
+         * Same `null` fallback and same empty render; the difference is that the
+         * failure now lands in `serverErrors` as a `DEGRADED_READ`.
+         */
+        const result = await safeRead(() => productRepository.list({
             filters: `storeId==${storeId},status==published,listingType==${type}`,
             sorts: "-createdAt",
             page,
             pageSize,
-        })
-            .catch(() => null);
+        }), {
+            route: `store-listing:${type}`,
+            key: "products.listByStoreAndType",
+            fallback: null,
+        });
         return { items: result?.items ?? [], total: result?.total ?? 0 };
     });
 }

package/dist/_internal/server/features/site-settings/adapters.d.ts

@@ -37,7 +37,7 @@ import type { PublicSiteSettings } from "../../../shared/features/site-settings/
  * was traced to a call site; anything without one belongs in the private list,
  * because an unused public field is pure attack surface.
  */
-export declare const PUBLIC_SITE_SETTINGS_FIELDS: readonly ["contact", "payment", "listings", "notificationChannels", "announcementBar", "navConfig", "actionConfig", "background", "watermark", "disabledRoutes", "chat"];
+export declare const PUBLIC_SITE_SETTINGS_FIELDS: readonly ["contact", "payment", "listings", "notificationChannels", "announcementBar", "navConfig", "actionConfig", "background", "watermark", "disabledRoutes", "chat", "search"];
 /** Everything else, with the reason it stays server-side. */
 export declare const PRIVATE_SITE_SETTINGS_FIELDS: readonly ["id", "createdAt", "updatedAt", "credentials", "emailSettings", "legalPages", "commissions", "emi", "gst", "laborRate", "adSettings", "integrations", "platformLimits", "auctionConfig", "siteName", "tagline", "motto", "logo", "favicon", "seo", "socialLinks", "features", "shipping", "returns", "faq", "aboutContent", "navbarConfig", "footerConfig", "theme", "featuredResults", "messaging"];
 export interface ToPublicSiteSettingsOptions {

package/dist/_internal/server/features/site-settings/adapters.js

@@ -37,6 +37,20 @@ export const PUBLIC_SITE_SETTINGS_FIELDS = [
     // render a "Message seller" CTA at all. Narrowed to `enabled` only; there is
     // nothing else in the group.
     "chat",
+    /*
+     * useSearchIndex — the kill switch for the browser-side search artifact.
+     *
+     * Public because the reader is a GUEST's search box: search is the one
+     * surface that must work before anyone signs in, so a server-only flag
+     * could not reach the visitor it governs. Publishing it discloses one
+     * boolean meaning "site search currently falls back to the server path",
+     * which is observable from the outside anyway by watching which request
+     * the page makes.
+     *
+     * 🛑 It fails OPEN on absence (`!== false`), so a settings fetch that fails
+     * leaves search working rather than dark — see the schema note.
+     */
+    "search",
 ];
 /** Everything else, with the reason it stays server-side. */
 export const PRIVATE_SITE_SETTINGS_FIELDS = [
@@ -112,5 +126,17 @@ export function toPublicSiteSettings(doc, opts) {
         effectiveWatermark: opts?.effectiveWatermark,
         // D9 — undefined reads as OFF, never a default-true `??`.
         chat: { enabled: doc.chat?.enabled === true },
+        /*
+         * 🛑 `!== false`, the opposite of the line above it, and the two sit
+         * together deliberately so the difference is visible rather than looking
+         * like one of them is a mistake.
+         *
+         * `chat` is a feature nobody has turned on yet; absent means off. This is
+         * a kill switch on a path that is already the primary one; absent means
+         * ON, and only an explicit `false` disables it. Normalised here rather
+         * than at the reader so there is one place that decides, and a client
+         * cannot accidentally re-derive it with `??`.
+         */
+        search: { indexEnabled: doc.search?.indexEnabled !== false },
     };
 }

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,80 @@
+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;
+    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,174 @@
+/*
+ * 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.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,
+    };
+}