@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/_internal/server/jobs/handlers/index.d.ts

@@ -29,6 +29,7 @@ export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove";
 export { productStatsSyncHandler } from "./productStatsSync";
 export { revenueRollupHandler } from "./revenueRollup";
 export { priceIndexRollupHandler } from "./priceIndexRollup";
+export { searchIndexBuildHandler } from "./searchIndexBuild";
 export { analyticsAlertEvaluateHandler } from "./analyticsAlertEvaluate";
 export { pageViewRollupHandler } from "./pageViewRollup";
 export { pageViewPruneHandler } from "./pageViewPrune";

package/dist/_internal/server/jobs/handlers/index.js

@@ -29,6 +29,7 @@ export { paymentReviewAutoApproveHandler } from "./paymentReviewAutoApprove.js";
 export { productStatsSyncHandler } from "./productStatsSync.js";
 export { revenueRollupHandler } from "./revenueRollup.js";
 export { priceIndexRollupHandler } from "./priceIndexRollup.js";
+export { searchIndexBuildHandler } from "./searchIndexBuild.js";
 export { analyticsAlertEvaluateHandler } from "./analyticsAlertEvaluate.js";
 export { pageViewRollupHandler } from "./pageViewRollup.js";
 export { pageViewPruneHandler } from "./pageViewPrune.js";

package/dist/_internal/server/jobs/handlers/onCategoryWrite.js

@@ -1,8 +1,26 @@
+import { markSearchIndexDirty } from "../../features/search/index-build/artifact-store.js";
 import { handleCategoryWrite } from "../core/onCategoryWrite.js";
+/*
+ * 🛑 Also marks the public search index stale.
+ *
+ * Added here rather than in the core so all five content triggers share one
+ * shape, and so each core keeps doing exactly the one thing it is named for.
+ *
+ * Safe under Root Cause #92 — which cost 12 MILLION invocations a day —
+ * because it writes a DIFFERENT collection (`searchIndex/manifest`) from the
+ * one this trigger watches, the same argument `priceIndexRollup` makes for
+ * writing `priceIndex/{leafId}` and never `categories`. #92's other half is
+ * handled inside `markSearchIndexDirty`: its no-op guard is a BOOLEAN read,
+ * never a deep compare, so a burst of 50 writes costs 50 reads and one write.
+ *
+ * It never throws: a missed mark delays the index by one 15-minute cadence,
+ * and failing the content write that triggered it would be far worse.
+ */
 export const onCategoryWriteHandler = async (event, ctx) => {
     await handleCategoryWrite({
         categoryId: event.params.categoryId,
         before: event.before,
         after: event.after,
     }, ctx);
+    await markSearchIndexDirty(ctx.db, "onCategoryWrite");
 };

package/dist/_internal/server/jobs/handlers/onProductWrite.js

@@ -1,8 +1,26 @@
+import { markSearchIndexDirty } from "../../features/search/index-build/artifact-store.js";
 import { handleProductWrite } from "../core/onProductWrite.js";
+/*
+ * 🛑 Also marks the public search index stale.
+ *
+ * Added here rather than in the core so all five content triggers share one
+ * shape, and so each core keeps doing exactly the one thing it is named for.
+ *
+ * Safe under Root Cause #92 — which cost 12 MILLION invocations a day —
+ * because it writes a DIFFERENT collection (`searchIndex/manifest`) from the
+ * one this trigger watches, the same argument `priceIndexRollup` makes for
+ * writing `priceIndex/{leafId}` and never `categories`. #92's other half is
+ * handled inside `markSearchIndexDirty`: its no-op guard is a BOOLEAN read,
+ * never a deep compare, so a burst of 50 writes costs 50 reads and one write.
+ *
+ * It never throws: a missed mark delays the index by one 15-minute cadence,
+ * and failing the content write that triggered it would be far worse.
+ */
 export const onProductWriteHandler = async (event, ctx) => {
     await handleProductWrite({
         productId: event.params.productId,
         before: event.before,
         after: event.after,
     }, ctx);
+    await markSearchIndexDirty(ctx.db, "onProductWrite");
 };

package/dist/_internal/server/jobs/handlers/onReviewWrite.js

@@ -1,4 +1,22 @@
+import { markSearchIndexDirty } from "../../features/search/index-build/artifact-store.js";
 import { handleReviewWrite } from "../core/onReviewWrite.js";
+/*
+ * 🛑 Also marks the public search index stale.
+ *
+ * Added here rather than in the core so all five content triggers share one
+ * shape, and so each core keeps doing exactly the one thing it is named for.
+ *
+ * Safe under Root Cause #92 — which cost 12 MILLION invocations a day —
+ * because it writes a DIFFERENT collection (`searchIndex/manifest`) from the
+ * one this trigger watches, the same argument `priceIndexRollup` makes for
+ * writing `priceIndex/{leafId}` and never `categories`. #92's other half is
+ * handled inside `markSearchIndexDirty`: its no-op guard is a BOOLEAN read,
+ * never a deep compare, so a burst of 50 writes costs 50 reads and one write.
+ *
+ * It never throws: a missed mark delays the index by one 15-minute cadence,
+ * and failing the content write that triggered it would be far worse.
+ */
 export const onReviewWriteHandler = async (event, ctx) => {
     await handleReviewWrite({ reviewId: event.params.reviewId, before: event.before, after: event.after }, ctx);
+    await markSearchIndexDirty(ctx.db, "onReviewWrite");
 };

package/dist/_internal/server/jobs/handlers/onScamReportUpdate.js

@@ -1,5 +1,22 @@
+import { markSearchIndexDirty } from "../../features/search/index-build/artifact-store.js";
 import { handleScamReportVerified } from "../core/onScamReportVerified.js";
 import { handleScamReportRejected } from "../core/onScamReportRejected.js";
+/*
+ * 🛑 Also marks the public search index stale.
+ *
+ * Added here rather than in the core so all five content triggers share one
+ * shape, and so each core keeps doing exactly the one thing it is named for.
+ *
+ * Safe under Root Cause #92 — which cost 12 MILLION invocations a day —
+ * because it writes a DIFFERENT collection (`searchIndex/manifest`) from the
+ * one this trigger watches, the same argument `priceIndexRollup` makes for
+ * writing `priceIndex/{leafId}` and never `categories`. #92's other half is
+ * handled inside `markSearchIndexDirty`: its no-op guard is a BOOLEAN read,
+ * never a deep compare, so a burst of 50 writes costs 50 reads and one write.
+ *
+ * It never throws: a missed mark delays the index by one 15-minute cadence,
+ * and failing the content write that triggered it would be far worse.
+ */
 export const onScamReportUpdateHandler = async (event, ctx) => {
     const before = event.before;
     const after = event.after;
@@ -22,4 +39,5 @@ export const onScamReportUpdateHandler = async (event, ctx) => {
     else if (nextStatus === "rejected") {
         await handleScamReportRejected(baseInput, ctx);
     }
+    await markSearchIndexDirty(ctx.db, "onScamReportUpdate");
 };

package/dist/_internal/server/jobs/handlers/onStoreWrite.js

@@ -1,8 +1,26 @@
+import { markSearchIndexDirty } from "../../features/search/index-build/artifact-store.js";
 import { handleStoreWrite } from "../core/onStoreWrite.js";
+/*
+ * 🛑 Also marks the public search index stale.
+ *
+ * Added here rather than in the core so all five content triggers share one
+ * shape, and so each core keeps doing exactly the one thing it is named for.
+ *
+ * Safe under Root Cause #92 — which cost 12 MILLION invocations a day —
+ * because it writes a DIFFERENT collection (`searchIndex/manifest`) from the
+ * one this trigger watches, the same argument `priceIndexRollup` makes for
+ * writing `priceIndex/{leafId}` and never `categories`. #92's other half is
+ * handled inside `markSearchIndexDirty`: its no-op guard is a BOOLEAN read,
+ * never a deep compare, so a burst of 50 writes costs 50 reads and one write.
+ *
+ * It never throws: a missed mark delays the index by one 15-minute cadence,
+ * and failing the content write that triggered it would be far worse.
+ */
 export const onStoreWriteHandler = async (event, ctx) => {
     await handleStoreWrite({
         storeId: event.params.storeId,
         before: event.before,
         after: event.after,
     }, ctx);
+    await markSearchIndexDirty(ctx.db, "onStoreWrite");
 };

package/dist/_internal/server/jobs/handlers/searchIndexBuild.d.ts

@@ -0,0 +1,2 @@
+import type { ScheduleHandler } from "../runtime/types";
+export declare const searchIndexBuildHandler: ScheduleHandler;

package/dist/_internal/server/jobs/handlers/searchIndexBuild.js

@@ -0,0 +1,2 @@
+import { runSearchIndexBuild } from "../core/searchIndexBuild.js";
+export const searchIndexBuildHandler = runSearchIndexBuild;

package/dist/_internal/server/jobs/handlers/triggerEventRaffle.d.ts

@@ -1,3 +1,11 @@
 import type { CallableHandler } from "../runtime/types";
 import { type TriggerEventRaffleInput, type TriggerEventRaffleResult } from "../core/triggerEventRaffle";
+/**
+ * Statuses come from `reasonToHttp`, shared with
+ * `POST /api/admin/events/[id]/trigger-raffle`.
+ *
+ * The hand-written chain this replaces knew two reasons (404 / 422) while the
+ * route mapped everything to 409 — so the same refusal had two different
+ * statuses depending on which door it came through (Root Cause #85).
+ */
 export declare const triggerEventRaffleHandler: CallableHandler<TriggerEventRaffleInput, TriggerEventRaffleResult>;

package/dist/_internal/server/jobs/handlers/triggerEventRaffle.js

@@ -1,16 +1,25 @@
 import { runTriggerEventRaffle, } from "../core/triggerEventRaffle.js";
-function httpError(message, status) {
+import { reasonToHttp } from "../core/event-draw-reasons.js";
+function httpError(message, status, code) {
     const err = new Error(message);
     err.httpStatus = status;
+    err.code = code;
     return err;
 }
+/**
+ * Statuses come from `reasonToHttp`, shared with
+ * `POST /api/admin/events/[id]/trigger-raffle`.
+ *
+ * The hand-written chain this replaces knew two reasons (404 / 422) while the
+ * route mapped everything to 409 — so the same refusal had two different
+ * statuses depending on which door it came through (Root Cause #85).
+ */
 export const triggerEventRaffleHandler = async (input, ctx) => {
     const result = await runTriggerEventRaffle(input, ctx);
-    if (result.reason === "event_not_found") {
-        throw httpError("Event not found", 404);
-    }
-    if (result.reason === "no_eligible_entries") {
-        throw httpError("No eligible entries for raffle", 422);
+    // Mirrors the route's own success test: a reason with no winner is a refusal.
+    if (result.reason && !result.raffleWinnerUserId) {
+        const { status, code, message } = reasonToHttp(result.reason);
+        throw httpError(message, status, code);
     }
     return result;
 };

package/dist/_internal/shared/actions/action-registry.js

@@ -1063,6 +1063,35 @@ export const ACTIONS = {
                 confirmKind: "danger",
             },
         },
+        /*
+         * The raffle draw. Added 2026-10-19 — before this there was NO control to
+         * draw a raffle anywhere in the product: the endpoint and its
+         * `ADMIN_ENDPOINTS.EVENT_TRIGGER_RAFFLE` constant existed with zero
+         * callers, and the tester case whose step 3 reads "trigger the raffle
+         * draw" was literally unexecutable.
+         *
+         * `kind: "danger"` with a REQUIRED confirmation, because a draw is
+         * genuinely irreversible: it writes the winner onto the event, and the
+         * winner's notification cannot be recalled. The server enforces the
+         * one-draw invariant transactionally and answers 409
+         * `RAFFLE_ALREADY_DRAWN` on a second attempt, so this dialog is the
+         * courtesy and that 409 is the guarantee.
+         */
+        "draw-raffle-winner": {
+            iconKey: "verify",
+            id: "event.draw-raffle-winner",
+            label: "Draw raffle winner",
+            ariaLabel: "Pick a random winner from the approved entries",
+            description: "Picks one winner at random from this event's approved entries, records them on the event, and notifies them.",
+            kind: "danger",
+            permissions: ["admin"],
+            confirmation: {
+                title: "Draw the raffle winner?",
+                body: "One winner will be picked at random from the approved entries, announced on the event page, and notified. A raffle can only be drawn once — this action cannot be undone.",
+                confirmLabel: "Yes, draw the winner",
+                confirmKind: "danger",
+            },
+        },
     },
     USER: {
         "cancel-order": {

package/dist/_internal/shared/cache/revalidate-targets.d.ts

@@ -31,7 +31,6 @@
  * render). Under-revalidating is the failure that shows a buyer a sold-out
  * listing as in stock, so when in doubt this returns MORE paths, not fewer.
  */
-/** What the caller knows about the written document, when it knows anything. */
 export interface RevalidateHints {
     /** `standard` | `auction` | `pre-order` | … — picks the right detail route. */
     listingType?: string;

package/dist/_internal/shared/cache/revalidate-targets.js

@@ -31,6 +31,8 @@
  * render). Under-revalidating is the failure that shows a buyer a sold-out
  * listing as in stock, so when in doubt this returns MORE paths, not fewer.
  */
+/** What the caller knows about the written document, when it knows anything. */
+import { ROUTES } from "../../../next/routing/route-map.js";
 /** Detail route per listing type. Mirrors `ListingTypePlugin.detailRoute`. */
 const PRODUCT_DETAIL_BY_TYPE = {
     standard: (id) => `/products/${id}`,
@@ -73,7 +75,7 @@ function listingTypeFromId(id) {
     return undefined;
 }
 function productTargets(id, hints) {
-    const out = ["/", "/products"];
+    const out = [ROUTES.HOME, ROUTES.PUBLIC.PRODUCTS];
     if (!id)
         return out;
     const type = hints?.listingType ?? listingTypeFromId(id);
@@ -81,7 +83,7 @@ function productTargets(id, hints) {
         out.push(PRODUCT_DETAIL_BY_TYPE[type](id));
         // The type's own browse page, when it has one distinct from /products.
         const browse = PRODUCT_DETAIL_BY_TYPE[type](id).replace(/\/[^/]+$/, "");
-        if (browse && browse !== "/products")
+        if (browse && browse !== ROUTES.PUBLIC.PRODUCTS)
             out.push(browse);
     }
     else {
@@ -119,26 +121,26 @@ export function revalidateTargetsFor(collection, id, hints) {
         case "categories":
             // Brands and pricing bundles are `categories` rows discriminated by
             // `categoryType`, so all three detail shapes are marked.
-            paths = ["/", "/categories"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.CATEGORIES];
             if (id)
                 paths.push(`/categories/${id}`, `/brands/${id}`, `/bundles/${id}`);
             break;
         case "blogPosts":
-            paths = ["/", "/blog"];
+            paths = [ROUTES.HOME, ROUTES.BLOG.LIST];
             if (id)
                 paths.push(`/blog/${id}`);
             break;
         case "events":
-            paths = ["/", "/events"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.EVENTS];
             if (id)
                 paths.push(`/events/${id}`);
             break;
         case "reviews":
             // A new review changes the product's rating and the homepage stat.
-            paths = ["/", "/reviews"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.REVIEWS];
             break;
         case "stores":
-            paths = ["/", "/stores"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.STORES];
             if (id)
                 paths.push(`/stores/${id}`);
             break;
@@ -148,7 +150,7 @@ export function revalidateTargetsFor(collection, id, hints) {
             paths = ["/"];
             break;
         case "faqs":
-            paths = ["/", "/faqs"];
+            paths = [ROUTES.HOME, ROUTES.PUBLIC.FAQS];
             break;
         default:
             paths = [];

package/dist/_internal/shared/features/events/config.d.ts

@@ -3,3 +3,17 @@ export declare const EVENTS_UPCOMING_LIMIT = 10;
 export declare const EVENT_MAX_ENTRIES_DEFAULT = 500;
 export declare const EVENT_TITLE_MAX_LENGTH = 200;
 export declare const EVENT_DESCRIPTION_MAX_LENGTH = 5000;
+/**
+ * Entries one person may put into a raffle.
+ *
+ * One, because a raffle is one ticket per person and there is nothing to
+ * configure: `maxEntriesPerUser` exists on `SurveyConfig` only, and
+ * `EventDocument` has no `raffleConfig` at all.
+ *
+ * 🛑 Shared deliberately, by BOTH `enterEvent`'s server-side dedupe and the
+ * `EventRaffleEntryForm` prop that renders "you've used all N entry slots".
+ * Two mirrored literals is the shape that made this bug survive: the form
+ * already defaulted to 1 and displayed that sentence, while the server
+ * enforced nothing, so the UI claimed a limit that did not exist.
+ */
+export declare const RAFFLE_MAX_ENTRIES_PER_USER = 1;

package/dist/_internal/shared/features/events/config.js

@@ -3,3 +3,17 @@ export const EVENTS_UPCOMING_LIMIT = 10;
 export const EVENT_MAX_ENTRIES_DEFAULT = 500;
 export const EVENT_TITLE_MAX_LENGTH = 200;
 export const EVENT_DESCRIPTION_MAX_LENGTH = 5000;
+/**
+ * Entries one person may put into a raffle.
+ *
+ * One, because a raffle is one ticket per person and there is nothing to
+ * configure: `maxEntriesPerUser` exists on `SurveyConfig` only, and
+ * `EventDocument` has no `raffleConfig` at all.
+ *
+ * 🛑 Shared deliberately, by BOTH `enterEvent`'s server-side dedupe and the
+ * `EventRaffleEntryForm` prop that renders "you've used all N entry slots".
+ * Two mirrored literals is the shape that made this bug survive: the form
+ * already defaulted to 1 and displayed that sentence, while the server
+ * enforced nothing, so the UI claimed a limit that did not exist.
+ */
+export const RAFFLE_MAX_ENTRIES_PER_USER = 1;

package/dist/_internal/shared/features/notifications/action-url.js

@@ -97,6 +97,14 @@ export function resolveNotificationActionUrl(relatedType, relatedId, audience) {
             return audience === "admin"
                 ? String(ROUTES.ADMIN.STORE_DETAIL(relatedId))
                 : String(ROUTES.STORE.DASHBOARD);
+        case "event":
+            /*
+             * The public winner page — the same destination for everyone, like
+             * `product` and `review`. An admin who drew the raffle and the buyer who
+             * won it both want to see the announcement, and that announcement IS the
+             * public page; there is no admin-side winner view to send them to.
+             */
+            return String(ROUTES.PUBLIC.EVENT_WINNER(relatedId));
         case "conversation":
             // D9 — one universal inbox, reachable from any portal; there is no
             // admin-specific thread view (admins moderate via reports, not a

package/dist/_internal/shared/features/site-settings/types.d.ts

@@ -42,6 +42,17 @@ export interface PublicSiteSettings {
     chat?: {
         enabled: boolean;
     };
+    /**
+     * The browser-side search index kill switch. **ON by default** — the
+     * projection emits `indexEnabled: doc.search?.indexEnabled !== false`, so
+     * an unseeded settings document and an absent group both mean "search
+     * works". The property itself is optional only because an OLD cached
+     * `/api/site-settings` response predates the field; `useSearchIndex`
+     * therefore reads it as `!== false` a second time rather than `=== true`.
+     */
+    search?: {
+        indexEnabled: boolean;
+    };
     notificationChannels?: NotificationChannelConfig;
     announcementBar?: SiteSettingsDocument["announcementBar"];
     navConfig?: SiteSettingsDocument["navConfig"];

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

@@ -0,0 +1,81 @@
+import type { DecodedRaster, EncodedImage, Rect } from "./types";
+export interface ProbeResult {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * The density the FILE declares, unvalidated. Five of the nine reference
+     * scans say 72 or 96 — an encoder default, not a measurement — so a caller
+     * must treat this as a suggestion to confirm, never as truth.
+     */
+    readonly dpi?: number;
+}
+export interface DecodeOptions {
+    /**
+     * The memory cap, enforced INSIDE the codec.
+     *
+     * This is the single most important line in the seam. sharp downscales in
+     * native code during decode and canvas does it in `drawImage`, so a 34 MP
+     * source never materialises as a JS buffer. If a codec implementation ignores
+     * this and returns full-resolution pixels, every Float32Array downstream
+     * scales with it and the Function runs out of memory — with no error that
+     * points here.
+     */
+    readonly maxLongEdge: number;
+}
+export interface PreviewOptions {
+    readonly maxLongEdge: number;
+    readonly format: "png" | "webp";
+}
+export interface ImageCodec {
+    /** Header-only. Must not decode pixels — it runs on the full upload. */
+    probe(source: Uint8Array): Promise<ProbeResult>;
+    /**
+     * Decode, downscale to `maxLongEdge`, apply EXIF orientation, drop ICC.
+     *
+     * The last two matter for correctness, not tidiness: both codecs must hand
+     * back the SAME pixels for the same file, or a path tuned in the browser
+     * lands somewhere else when the Function re-renders it.
+     */
+    decode(source: Uint8Array, opts: DecodeOptions): Promise<DecodedRaster>;
+    /**
+     * Decode one tile at native resolution, for the `max` tier's tiled ridge pass.
+     *
+     * 🛑 Tiles must overlap by at least the ridge kernel radius. A cut line
+     * crossing a seam with insufficient overlap is detected on neither side and
+     * breaks silently — producing worse output than the cheaper `precise` tier,
+     * which is the one way that tier can quietly be a downgrade.
+     */
+    decodeTile(source: Uint8Array, tile: Rect): Promise<DecodedRaster>;
+    encodePng(raster: DecodedRaster): Promise<EncodedImage>;
+    /**
+     * Crop to `region` and apply `alpha` (length === region.width * region.height),
+     * in one call.
+     *
+     * One call rather than crop-then-composite so that neither codec needs its own
+     * pixel loop, and — the real reason — so a full-resolution part render never
+     * materialises a full-resolution RGBA buffer. The caller rasterises that one
+     * part's Bézier path into `alpha` over its own bounding box, and the codec
+     * reads only that box out of the source file. Sixty parts therefore cost
+     * sixty small allocations rather than one enormous one.
+     */
+    encodePngRegion(source: Uint8Array, region: Rect, alpha: Uint8Array): Promise<EncodedImage>;
+    /** The ≤1 MB review image the UI loads instead of the scan. */
+    encodePreview(source: Uint8Array, opts: PreviewOptions): Promise<EncodedImage>;
+    /**
+     * Pack already-encoded tiles into one sprite atlas.
+     *
+     * Exists because object COUNT is metered separately from bytes: sixty
+     * thumbnail objects per run spend the Class A/B allowance sixty times faster
+     * than one atlas of the same pixels, and the part list loads in one request
+     * rather than sixty.
+     */
+    encodeAtlas(tiles: readonly {
+        readonly raster: DecodedRaster;
+        readonly ordinal: number;
+    }[], opts: {
+        readonly maxLongEdge: number;
+    }): Promise<{
+        readonly image: EncodedImage;
+        readonly frames: Readonly<Record<number, Rect>>;
+    }>;
+}

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

@@ -0,0 +1,30 @@
+/*
+ * WHY: The tracing algorithm must be ONE implementation, but it has to run in a
+ *      browser (live threshold tuning, ~1s per tweak) and in a Firebase Function
+ *      (full-resolution render on save). Two implementations drift, and the one
+ *      that drifts is always the one you are not currently looking at
+ *      (CLAUDE.md Root Cause #59/#73). So the algorithm is shared and only the
+ *      pixel I/O differs — this file is that seam, and it is the whole of it.
+ * WHAT: The codec interface. Declaration only: no implementation, no imports, no
+ *       dependency on sharp, canvas, node:* or providers/*. Keeping this tree
+ *       import-free is what lets the browser bundle it at all (Root Cause #24),
+ *       and `audit-sticker-trace-purity` enforces it.
+ *
+ * The division of labour is deliberate and worth stating, because getting it
+ * wrong reintroduces the memory problem the design exists to avoid:
+ *
+ *   codec  — owns BYTES. Decodes, downscales, crops, encodes.
+ *   core   — owns MATHS. Takes a DecodedRaster, returns geometry. Never resizes
+ *            anything, never allocates at source resolution, never sees a file.
+ *
+ * EXPORTS:
+ *   ImageCodec, DecodeOptions, PreviewOptions, ProbeResult
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:port
+ * @tag access:isomorphic
+ * @tag consumers:canvas-codec,sharp-codec,run,coordinator,shard
+ * @tag sideEffects:none
+ */
+export {};

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

@@ -0,0 +1,81 @@
+import type { PrecisionTier, TraceParams } from "./types";
+/**
+ * The memory cap, and the reason the core never sees a 34 MP buffer.
+ *
+ * The downscale happens inside the CODEC, not here — sharp does it in native
+ * code, canvas in `drawImage` — so no Float32Array is ever allocated at source
+ * resolution. At 3000px long edge a mask is ~9 MB as Uint8 and a distance
+ * transform ~36 MB as Float32, with several live at once; that fits a 2 GiB
+ * Function with room. The `max` tier deliberately exceeds it and pays for that
+ * by tiling the ridge pass instead (see trace/tiling).
+ */
+export declare const WORKING_LONG_EDGE = 3000;
+/** The review image. Must stay ≤1 MB — the UI loads it on every sheet open. */
+export declare const PREVIEW_LONG_EDGE = 2000;
+/** Per-part review thumbnails, packed into ONE sprite atlas rather than N objects. */
+export declare const THUMB_LONG_EDGE = 220;
+/**
+ * Upload ceiling. Deliberately its own constant rather than the shared
+ * MAX_IMAGE_BYTES (10 MB), which is sized for product photography and must not
+ * be raised — a 4948x6955 scan is legitimately 80 MB.
+ */
+export declare const STICKER_SHEET_MAX_BYTES: number;
+/**
+ * A hard bound, not a tuning knob. A noise-dominated scan whose ridges survive
+ * hysteresis produces thousands of components, and without this the failure
+ * mode is thousands of Storage writes rather than an error message.
+ */
+export declare const MAX_PARTS_PER_SHEET = 400;
+/**
+ * Gap between physical sheets in one scan. Stickers on a sheet sit a few mm
+ * apart; separate sheets land centimetres apart, so the threshold has a wide
+ * safe margin either side.
+ */
+export declare const SHEET_CLUSTER_GAP_MM = 12;
+/**
+ * Cricut's documented minimum reliable detail / line spacing: 0.25 in. A part
+ * with an internal neck below this tears instead of cutting.
+ */
+export declare const CRICUT_MIN_FEATURE_MM = 6.35;
+/**
+ * Design Space degrades past roughly 50,000 nodes. The exporter re-simplifies
+ * to this budget INDEPENDENTLY of the trace tolerance — tying the two together
+ * would mean a more precise trace producing a file Design Space cannot open.
+ */
+export declare const CRICUT_NODE_BUDGET = 45000;
+interface TierPreset {
+    readonly workingLongEdge: number;
+    readonly prefilter: TraceParams["prefilter"];
+    readonly prefilterRadius: number;
+    readonly simplifyMm: number;
+    readonly smoothMm: number;
+    readonly subPixelContours: boolean;
+    readonly tiled: boolean;
+}
+/**
+ * `draft` exists for the browser's live loop and nothing else — 1200px traces
+ * in about a second, which is what makes threshold tuning feel like a slider
+ * rather than a job submission.
+ *
+ * `max` is the only tier that tiles. Its simplify tolerance is fine enough that
+ * the Cricut exporter will almost certainly have to re-simplify; that is
+ * expected and reported, not a misconfiguration.
+ */
+export declare const TIER_PRESETS: Readonly<Record<PrecisionTier, TierPreset>>;
+/**
+ * Defaults measured against the reference corpus, not guessed:
+ *
+ * - `ridgeHysteresisLow/High` — the cut line reads as a dark-trough/light-ridge
+ *   doublet at 10-20x scan noise on four sampled scanlines (−40/+27 against ±2
+ *   on yellow-on-yellow, +22 against ±1 on red-on-red). The low threshold sits
+ *   just above the worst measured noise floor (±7, a JPEG scan) so a faint but
+ *   continuous line links, while isolated speckle does not seed.
+ * - `quantiseWeight` below 1 on purpose: the colour channel REINFORCES a weak
+ *   ridge but must not invent a cut where only a colour change exists, or every
+ *   gradient band inside a sticker becomes an outline.
+ * - `bridgeMm` closes white channels narrower than 2x itself. It must sit
+ *   between the widest intra-sticker band and the narrowest real gap between
+ *   neighbours; 0.45 was measured on the Driger G sheet.
+ */
+export declare function paramsForTier(tier: PrecisionTier, overrides?: Partial<TraceParams>): TraceParams;
+export {};