@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/shared/features/sticker-trace/export/page-sizes.js

@@ -0,0 +1,223 @@
+/*
+ * WHY: The print modal, the nester and the PDF writer each need to know how big
+ *      a page is and how much of it may be printed on. Three copies of that
+ *      table would disagree the first time one of them was corrected, and the
+ *      symptom would be a cut file that is subtly the wrong size — which is only
+ *      discoverable after it has been printed and cut.
+ * WHAT: Every page the tool can target, as data, in millimetres. Includes the
+ *       Cricut mat sizes, because a mat IS a page as far as nesting is concerned.
+ *
+ * 🛑 Names are deliberately `PrintPageSize*`, not `PageSize*`. appkit already
+ * exports `PageSizeKey` from constants/pagination-presets, where it means ROWS
+ * PER PAGE. Two things called a page size, one of them paper and one of them
+ * pagination, is a confusion worth spending six characters to avoid.
+ *
+ * EXPORTS:
+ *   MM_PER_INCH, inchesToMm, PrintPageSizeId, PrintPageSize, PtcArea,
+ *   PRINT_PAGE_SIZES, PRINT_PAGE_SIZE_IDS, pageSizeById, customPageSize,
+ *   printableAreaMm
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:export/machine-profiles,export/nesting,export/pdf-mosaic,StickerPrintModal
+ * @tag sideEffects:none
+ */
+/** The definition of the inch, exact by international agreement since 1959. */
+export const MM_PER_INCH = 25.4;
+/**
+ * Cricut publishes every dimension in inches, so the constants below are
+ * written in inches and converted here rather than being pre-multiplied. A
+ * pre-multiplied `114.3` loses the fact that it is 4.5", which is what you need
+ * when checking a number against Cricut's own documentation.
+ */
+export function inchesToMm(inches) {
+    return inches * MM_PER_INCH;
+}
+/**
+ * 5 mm is a conservative margin that every consumer inkjet and laser printer
+ * clears, chosen rather than measured. It is a DEFAULT, not a constraint: the
+ * print modal lets it be overridden per job, and borderless printers can take
+ * it to 0. Erring large costs a few mm of nesting area; erring small puts a cut
+ * line in the unprintable zone, where it simply does not appear.
+ */
+const PAPER_MARGIN_MM = 5;
+/*
+ * Cricut Joy 2 figures below come from Cricut's own published documentation, as
+ * researched during planning — not from inference:
+ *
+ *   cut width          4.5 in
+ *   Smart Materials    4.5 x 48 in (one continuous shape to 4 ft)
+ *   mats               StandardGrip 4.5 x 6.5 · LightGrip 4.5 x 12 · Card 4.5 x 6.25
+ *   PTC area, Letter   9.94 x 3.19 in
+ *   PTC area, A4       10.62 x 3.07 in
+ *
+ * 🛑 Read the PTC pair carefully: the LONG number runs along the page's long
+ * edge and the SHORT one across it. On portrait A4 that is a 269.7 x 78.0 mm
+ * column. Transposing them yields an area wider than A4 itself, which is the
+ * obvious tell that they have been swapped.
+ */
+const JOY_MAT_WIDTH_IN = 4.5;
+export const PRINT_PAGE_SIZES = {
+    a3: {
+        id: "a3",
+        label: "A3",
+        widthMm: 297,
+        heightMm: 420,
+        marginMm: PAPER_MARGIN_MM,
+        isMat: false,
+    },
+    a4: {
+        id: "a4",
+        label: "A4",
+        widthMm: 210,
+        heightMm: 297,
+        marginMm: PAPER_MARGIN_MM,
+        ptcArea: {
+            widthMm: inchesToMm(3.07),
+            heightMm: inchesToMm(10.62),
+        },
+        isMat: false,
+    },
+    a5: {
+        id: "a5",
+        label: "A5",
+        widthMm: 148,
+        heightMm: 210,
+        marginMm: PAPER_MARGIN_MM,
+        isMat: false,
+    },
+    letter: {
+        id: "letter",
+        label: "Letter",
+        widthMm: inchesToMm(8.5),
+        heightMm: inchesToMm(11),
+        marginMm: PAPER_MARGIN_MM,
+        ptcArea: {
+            widthMm: inchesToMm(3.19),
+            heightMm: inchesToMm(9.94),
+        },
+        isMat: false,
+    },
+    legal: {
+        id: "legal",
+        label: "Legal",
+        widthMm: inchesToMm(8.5),
+        heightMm: inchesToMm(14),
+        marginMm: PAPER_MARGIN_MM,
+        isMat: false,
+    },
+    tabloid: {
+        id: "tabloid",
+        label: "Tabloid",
+        widthMm: inchesToMm(11),
+        heightMm: inchesToMm(17),
+        marginMm: PAPER_MARGIN_MM,
+        isMat: false,
+    },
+    "joy-mat-standard": {
+        id: "joy-mat-standard",
+        label: 'Cricut Joy StandardGrip mat (4.5 x 6.5")',
+        widthMm: inchesToMm(JOY_MAT_WIDTH_IN),
+        heightMm: inchesToMm(6.5),
+        marginMm: 0,
+        isMat: true,
+    },
+    "joy-mat-long": {
+        id: "joy-mat-long",
+        label: 'Cricut Joy LightGrip mat (4.5 x 12")',
+        widthMm: inchesToMm(JOY_MAT_WIDTH_IN),
+        heightMm: inchesToMm(12),
+        marginMm: 0,
+        isMat: true,
+    },
+    "joy-mat-card": {
+        id: "joy-mat-card",
+        label: 'Cricut Joy Card mat (4.5 x 6.25")',
+        widthMm: inchesToMm(JOY_MAT_WIDTH_IN),
+        heightMm: inchesToMm(6.25),
+        marginMm: 0,
+        isMat: true,
+    },
+    "joy-smart-material": {
+        id: "joy-smart-material",
+        label: 'Cricut Joy Smart Material (4.5 x 48")',
+        widthMm: inchesToMm(JOY_MAT_WIDTH_IN),
+        heightMm: inchesToMm(48),
+        marginMm: 0,
+        isMat: true,
+    },
+    /**
+     * A placeholder row so the id union is total and the picker has something to
+     * select. Its dimensions are meaningless — always build the real one with
+     * `customPageSize()`, which is why both are 0 rather than a plausible-looking
+     * A4 that would silently stand in for a forgotten override.
+     */
+    custom: {
+        id: "custom",
+        label: "Custom size",
+        widthMm: 0,
+        heightMm: 0,
+        marginMm: PAPER_MARGIN_MM,
+        isMat: false,
+    },
+};
+/** Stable display order for pickers: papers first, then mats, then custom. */
+export const PRINT_PAGE_SIZE_IDS = [
+    "a4",
+    "a3",
+    "a5",
+    "letter",
+    "legal",
+    "tabloid",
+    "joy-mat-standard",
+    "joy-mat-long",
+    "joy-mat-card",
+    "joy-smart-material",
+    "custom",
+];
+export function pageSizeById(id) {
+    return PRINT_PAGE_SIZES[id];
+}
+/**
+ * Build a custom page. Dimensions are caller-supplied and validated here rather
+ * than at each call site: a zero or negative page silently produces an empty
+ * nest, which reads as "nothing fitted" instead of "the page was never set".
+ */
+export function customPageSize(widthMm, heightMm, marginMm = PAPER_MARGIN_MM) {
+    if (!(widthMm > 0) || !(heightMm > 0)) {
+        throw new Error(`customPageSize: width and height must both be > 0 (got ${widthMm}x${heightMm})`);
+    }
+    if (marginMm < 0 || marginMm * 2 >= Math.min(widthMm, heightMm)) {
+        throw new Error(`customPageSize: margin ${marginMm}mm leaves no printable area on ${widthMm}x${heightMm}mm`);
+    }
+    return {
+        ...PRINT_PAGE_SIZES.custom,
+        widthMm,
+        heightMm,
+        marginMm,
+    };
+}
+/**
+ * The area parts may actually be nested into.
+ *
+ * `forPrintThenCut` is not a styling choice — on a PTC target the usable region
+ * is the sensor-constrained sub-area, which is dramatically smaller than the
+ * page minus its margin. Defaulting it to `false` means a caller who forgets it
+ * gets the LARGER area, so the failure is a layout the machine rejects rather
+ * than one that silently wastes two thirds of the page. That direction is
+ * chosen deliberately: a rejected file is noticed, a wasteful one is not.
+ */
+export function printableAreaMm(page, forPrintThenCut = false) {
+    if (forPrintThenCut) {
+        if (!page.ptcArea) {
+            throw new Error(`printableAreaMm: ${page.id} has no Print-Then-Cut area; only ${PRINT_PAGE_SIZE_IDS.filter((id) => PRINT_PAGE_SIZES[id].ptcArea).join(", ")} do`);
+        }
+        return { widthMm: page.ptcArea.widthMm, heightMm: page.ptcArea.heightMm };
+    }
+    return {
+        widthMm: page.widthMm - page.marginMm * 2,
+        heightMm: page.heightMm - page.marginMm * 2,
+    };
+}

package/dist/_internal/shared/features/sticker-trace/export/part-tiling.d.ts

@@ -0,0 +1,51 @@
+import type { Rect } from "../types";
+/** Default join allowance. Enough to butt or lap without a white line. */
+export declare const DEFAULT_BLEED_MM = 2;
+export interface TileSpec {
+    /** `#03a`, `#03b`, … — the suffix an operator reads off the printed sheet. */
+    label: string;
+    /** This tile's slice of the part, in the part's own mm space. */
+    regionMm: Rect;
+    /** Where the seam sits, as a fraction of the part's split axis. */
+    seamFraction: number;
+}
+export interface TilePlan {
+    ordinal: number;
+    name: string;
+    /** Which axis was cut. */
+    axis: "x" | "y";
+    tiles: TileSpec[];
+    bleedMm: number;
+    /** True when even the tiles exceed the limit — the part cannot be tiled to fit. */
+    stillOversized: boolean;
+}
+/**
+ * Per-column "detail" cost, for choosing where to cut.
+ *
+ * Cost is the count of alpha EDGES in a column — pixels whose opacity differs
+ * from their neighbour. A column through flat colour or empty space scores
+ * near zero; a column through lettering or a face scores high.
+ *
+ * 🛑 Edges, not opacity. Summing opacity finds the EMPTIEST column, which on a
+ * sticker is usually just outside the artwork — i.e. a seam that misses the
+ * part entirely and splits nothing. Counting transitions finds the quietest
+ * column that is still inside it.
+ */
+export declare function seamCostProfile(alpha: Uint8Array, width: number, height: number, axis: "x" | "y"): Float32Array;
+/**
+ * Plan the tiles for one oversized part.
+ *
+ * `alpha` is the part's own mask at `maskWidth × maskHeight`; `bboxMm` is its
+ * real size. Splitting runs along the part's NARROWEST axis, because that is
+ * the one the width limit applies to and splitting the long axis would not help.
+ */
+export declare function planPartTiles(input: {
+    ordinal: number;
+    name: string;
+    bboxMm: Rect;
+    alpha: Uint8Array;
+    maskWidth: number;
+    maskHeight: number;
+    limitMm: number;
+    bleedMm?: number;
+}): TilePlan;

package/dist/_internal/shared/features/sticker-trace/export/part-tiling.js

@@ -0,0 +1,178 @@
+/*
+ * WHY: A Cricut Joy 2's Print-Then-Cut area on A4 is a ~78mm column, and
+ *      several stickers on a typical Beyblade sheet are wider than that. The
+ *      alternatives are refusing to export them, silently scaling them — which
+ *      yields stickers the wrong physical size — or splitting them.
+ * WHAT: Split an oversized part into tiles with a bleed overlap, choosing the
+ *       seam through the least-detailed column rather than the midpoint.
+ *
+ * 🛑 THIS IS A COMPROMISE AND THE UI MUST SAY SO. A seam through sticker
+ * artwork is visible on the finished article. That is unavoidable, not a
+ * tuning failure — and the honest alternative, which the tool also offers, is
+ * to send the part to the print-shop profile where no width limit applies.
+ *
+ * 🛑 The seam is MEASURED from the artwork, never assumed. Splitting at the
+ * midpoint lands the join wherever the midpoint happens to be — through a face,
+ * through lettering — and those are exactly the places a human objects to.
+ *
+ * EXPORTS: TileSpec, TilePlan, planPartTiles, seamCostProfile
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/export,PrintLayoutModal
+ * @tag sideEffects:none
+ */
+/** Default join allowance. Enough to butt or lap without a white line. */
+export const DEFAULT_BLEED_MM = 2;
+/**
+ * Per-column "detail" cost, for choosing where to cut.
+ *
+ * Cost is the count of alpha EDGES in a column — pixels whose opacity differs
+ * from their neighbour. A column through flat colour or empty space scores
+ * near zero; a column through lettering or a face scores high.
+ *
+ * 🛑 Edges, not opacity. Summing opacity finds the EMPTIEST column, which on a
+ * sticker is usually just outside the artwork — i.e. a seam that misses the
+ * part entirely and splits nothing. Counting transitions finds the quietest
+ * column that is still inside it.
+ */
+export function seamCostProfile(alpha, width, height, axis) {
+    const n = axis === "x" ? width : height;
+    const cost = new Float32Array(n);
+    if (axis === "x") {
+        for (let x = 0; x < width; x++) {
+            let edges = 0;
+            for (let y = 1; y < height; y++) {
+                const a = alpha[y * width + x] ?? 0;
+                const b = alpha[(y - 1) * width + x] ?? 0;
+                if (Math.abs(a - b) > 8)
+                    edges++;
+            }
+            cost[x] = edges;
+        }
+    }
+    else {
+        for (let y = 0; y < height; y++) {
+            let edges = 0;
+            for (let x = 1; x < width; x++) {
+                const a = alpha[y * width + x] ?? 0;
+                const b = alpha[y * width + (x - 1)] ?? 0;
+                if (Math.abs(a - b) > 8)
+                    edges++;
+            }
+            cost[y] = edges;
+        }
+    }
+    return cost;
+}
+/**
+ * Pick the cheapest seam within the window the width limit allows.
+ *
+ * 🛑 The search window is CONSTRAINED, not the whole part. A seam must leave
+ * both halves under the limit, so it can only sit between `size - limit` and
+ * `limit`. Searching the whole part and then clamping is how you get a seam
+ * reported at the quietest column and applied somewhere else.
+ */
+function cheapestSeam(cost, limitPx) {
+    const n = cost.length;
+    const lo = Math.max(1, n - limitPx);
+    const hi = Math.min(n - 1, limitPx);
+    if (lo >= hi)
+        return Math.floor(n / 2);
+    let bestIndex = Math.floor((lo + hi) / 2);
+    let bestCost = Number.POSITIVE_INFINITY;
+    for (let i = lo; i <= hi; i++) {
+        const c = cost[i] ?? 0;
+        /*
+         * Strictly-less-than keeps the FIRST cheapest column rather than the last.
+         * With a flat run of equally quiet columns that puts the seam at the start
+         * of the quiet region, which is stable: re-running on the same part gives
+         * the same seam, so a preview an operator approved does not move.
+         */
+        if (c < bestCost) {
+            bestCost = c;
+            bestIndex = i;
+        }
+    }
+    return bestIndex;
+}
+/**
+ * Plan the tiles for one oversized part.
+ *
+ * `alpha` is the part's own mask at `maskWidth × maskHeight`; `bboxMm` is its
+ * real size. Splitting runs along the part's NARROWEST axis, because that is
+ * the one the width limit applies to and splitting the long axis would not help.
+ */
+export function planPartTiles(input) {
+    const bleed = input.bleedMm ?? DEFAULT_BLEED_MM;
+    const { width: wMm, height: hMm } = input.bboxMm;
+    // Split across the axis the limit actually binds.
+    const axis = wMm >= hMm ? "x" : "y";
+    const sizeMm = axis === "x" ? wMm : hMm;
+    const maskN = axis === "x" ? input.maskWidth : input.maskHeight;
+    const cost = seamCostProfile(input.alpha, input.maskWidth, input.maskHeight, axis);
+    const limitPx = Math.floor((input.limitMm / sizeMm) * maskN);
+    const seamPx = cheapestSeam(cost, limitPx);
+    const seamFraction = seamPx / maskN;
+    const seamMm = seamFraction * sizeMm;
+    /*
+     * Each tile carries the bleed INTO its neighbour, so the two overlap rather
+     * than abut. Without it the two printed pieces meet at a hairline the paper
+     * shows through — the join is then visible as a white line rather than as a
+     * slight doubling, and white is far more obvious.
+     */
+    const firstEnd = Math.min(sizeMm, seamMm + bleed);
+    const secondStart = Math.max(0, seamMm - bleed);
+    const tiles = axis === "x"
+        ? [
+            {
+                label: `#${String(input.ordinal).padStart(2, "0")}a`,
+                regionMm: { x: 0, y: 0, width: firstEnd, height: hMm },
+                seamFraction,
+            },
+            {
+                label: `#${String(input.ordinal).padStart(2, "0")}b`,
+                regionMm: {
+                    x: secondStart,
+                    y: 0,
+                    width: sizeMm - secondStart,
+                    height: hMm,
+                },
+                seamFraction,
+            },
+        ]
+        : [
+            {
+                label: `#${String(input.ordinal).padStart(2, "0")}a`,
+                regionMm: { x: 0, y: 0, width: wMm, height: firstEnd },
+                seamFraction,
+            },
+            {
+                label: `#${String(input.ordinal).padStart(2, "0")}b`,
+                regionMm: {
+                    x: 0,
+                    y: secondStart,
+                    width: wMm,
+                    height: sizeMm - secondStart,
+                },
+                seamFraction,
+            },
+        ];
+    /*
+     * 🛑 Reported, not silently re-split. A part more than twice the limit needs
+     * three or more tiles, and this plans TWO — saying so is what lets the UI
+     * offer the print-shop profile instead of handing over a plan that still does
+     * not fit. Pretending otherwise is the scaling mistake in another costume.
+     */
+    const widest = Math.max(...tiles.map((t) => (axis === "x" ? t.regionMm.width : t.regionMm.height)));
+    return {
+        ordinal: input.ordinal,
+        name: input.name,
+        axis,
+        tiles,
+        bleedMm: bleed,
+        stillOversized: widest > input.limitMm,
+    };
+}

package/dist/_internal/shared/features/sticker-trace/export/simplify-budget.d.ts

@@ -0,0 +1,26 @@
+import type { CutPath } from "../types";
+export interface SimplifyResult {
+    paths: CutPath[];
+    nodesBefore: number;
+    nodesAfter: number;
+    /**
+     * Greatest distance any dropped control point sat from the curve that
+     * replaced it, in millimetres. 0 when nothing was dropped.
+     *
+     * 🛑 A MEASURED worst case, not an average. An average hides the one place a
+     * corner was rounded off, which is exactly the place a human would object to.
+     */
+    maxDeviationMm: number;
+    /** True when the budget could not be met even at the coarsest pass. */
+    overBudget: boolean;
+}
+/**
+ * Simplify until the whole file fits `nodeBudget`.
+ *
+ * `null` budget means no ceiling — the print-shop profile — and returns the
+ * input untouched with a deviation of 0, which is the truthful answer rather
+ * than a no-op that still claims to have simplified.
+ */
+export declare function simplifyToBudget(paths: readonly CutPath[], nodeBudget: number | null, opts?: {
+    maxPasses?: number;
+}): SimplifyResult;

package/dist/_internal/shared/features/sticker-trace/export/simplify-budget.js

@@ -0,0 +1,134 @@
+/*
+ * WHY: Design Space gives up past roughly 50,000 nodes. A `max`-tier trace at
+ *      0.015mm across sixty parts can plausibly exceed that — so without a
+ *      separate budget here, the most precise tier would produce a file the
+ *      machine cannot open, making it strictly worse than `precise` at higher
+ *      cost.
+ * WHAT: Re-simplify an already-traced outline to a node budget, and REPORT the
+ *       deviation that bought.
+ *
+ * 🛑 THIS IS A SECOND, INDEPENDENT BUDGET. The trace simplifies to whatever the
+ * scan deserves; this simplifies to whatever the machine can open. Tying them
+ * together is the mistake — and the reporting is half the point: an operator
+ * told "simplified to 48,900 nodes, max deviation 0.08mm" can decide whether
+ * that matters, where one told nothing cannot.
+ *
+ * 🛑 It only ever REMOVES nodes. A budget pass that moved a point would be
+ * editing the traced geometry, and the deviation figure would then be a lie
+ * about a shape nobody chose.
+ *
+ * EXPORTS: SimplifyResult, simplifyToBudget
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/export
+ * @tag sideEffects:none
+ */
+function dist(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+function nodeCount(paths) {
+    let n = 0;
+    for (const p of paths)
+        n += p.segments.length + 1;
+    return n;
+}
+/**
+ * Drop every Nth segment, splicing its neighbours together.
+ *
+ * Deliberately a uniform stride rather than a curvature-weighted pass: a
+ * curvature pass keeps corners and eats smooth runs, which on a kiss-cut
+ * outline means it removes exactly the long gentle arcs that make a sticker
+ * look right, and keeps the scanner noise it mistook for detail. A uniform
+ * stride degrades the whole outline evenly and predictably.
+ */
+function thinOnce(path) {
+    if (path.segments.length < 4)
+        return { path, deviation: 0 };
+    const kept = [];
+    let deviation = 0;
+    let cursor = path.start;
+    for (let i = 0; i < path.segments.length; i++) {
+        const seg = path.segments[i];
+        const isLast = i === path.segments.length - 1;
+        /*
+         * Keep every other segment, and ALWAYS the last one so the outline still
+         * returns to its start. Dropping the closing segment leaves a gap the SVG
+         * writer's `Z` would bridge with a straight line — a visible flat edge on a
+         * curved sticker.
+         */
+        if (i % 2 === 0 || isLast) {
+            kept.push(seg);
+            cursor = seg.to;
+            continue;
+        }
+        // Merged away: the dropped endpoint's distance from the surviving one is
+        // the error this pass introduced at that location.
+        deviation = Math.max(deviation, dist(seg.to, cursor));
+    }
+    return { path: { start: path.start, segments: kept }, deviation };
+}
+/**
+ * Simplify until the whole file fits `nodeBudget`.
+ *
+ * `null` budget means no ceiling — the print-shop profile — and returns the
+ * input untouched with a deviation of 0, which is the truthful answer rather
+ * than a no-op that still claims to have simplified.
+ */
+export function simplifyToBudget(paths, nodeBudget, opts = {}) {
+    const nodesBefore = nodeCount(paths);
+    if (nodeBudget === null || nodesBefore <= nodeBudget) {
+        return {
+            paths: [...paths],
+            nodesBefore,
+            nodesAfter: nodesBefore,
+            maxDeviationMm: 0,
+            overBudget: false,
+        };
+    }
+    /*
+     * Bounded. Each pass roughly halves the node count, so 12 passes can reduce
+     * a 50,000-node file to single digits — far past any real budget. An
+     * unbounded loop on a degenerate path is how a Function burns its 300s.
+     */
+    const maxPasses = opts.maxPasses ?? 12;
+    let current = [...paths];
+    let maxDeviation = 0;
+    for (let pass = 0; pass < maxPasses; pass++) {
+        if (nodeCount(current) <= nodeBudget)
+            break;
+        const next = [];
+        for (const p of current) {
+            const { path, deviation } = thinOnce(p);
+            next.push(path);
+            maxDeviation = Math.max(maxDeviation, deviation);
+        }
+        /*
+         * Stop if a pass achieved nothing — every path is already at its floor of
+         * three segments. Continuing would spin for the remaining passes and still
+         * report over-budget, just later.
+         */
+        if (nodeCount(next) === nodeCount(current)) {
+            current = next;
+            break;
+        }
+        current = next;
+    }
+    const nodesAfter = nodeCount(current);
+    return {
+        paths: current,
+        nodesBefore,
+        nodesAfter,
+        maxDeviationMm: Math.round(maxDeviation * 1000) / 1000,
+        /*
+         * Reported rather than thrown. The operator may still want the file — to
+         * split it across two exports, or to open it in something that is not
+         * Design Space — and refusing to produce it takes that choice away.
+         */
+        overBudget: nodesAfter > nodeBudget,
+    };
+}

package/dist/_internal/shared/features/sticker-trace/export/vectorise-art.d.ts

@@ -0,0 +1,40 @@
+import type { DecodedRaster, Point } from "../types";
+/** One filled region: a colour and the rings that bound it. */
+export interface VectorRegion {
+    /** 8-bit channels, as sampled from the region's own pixels. */
+    rgb: readonly [number, number, number];
+    /** Closed rings in part-local pixel space. */
+    rings: Point[][];
+    /** Share of the part's opaque pixels this region covers. */
+    coverage: number;
+}
+export interface VectoriseResult {
+    regions: VectorRegion[];
+    nodeCount: number;
+    /**
+     * Fraction of opaque pixels whose colour the vector version gets wrong,
+     * 0..1, measured by refilling rather than estimated.
+     */
+    deviation: number;
+    /**
+     * 🛑 TRUE when vectorising made this part WORSE. The caller must surface it:
+     * the whole reason this export is opt-in is that a gradient-heavy part bands
+     * visibly and costs tens of thousands of nodes to do it.
+     */
+    notRecommended: boolean;
+    /** Why, in words, when `notRecommended`. Empty otherwise. */
+    reason: string;
+}
+export interface VectoriseOptions {
+    /** Palette size. More colours means finer bands and far more nodes. */
+    colours?: number;
+    /** RDP tolerance in pixels. */
+    simplifyPx?: number;
+}
+/**
+ * @param raster the part's own RGBA crop
+ * @param alpha  its cut mask — which pixels belong to the sticker at all
+ */
+export declare function vectoriseArtwork(raster: DecodedRaster, alpha: Uint8Array, opts?: VectoriseOptions): VectoriseResult;
+/** Serialise the regions to SVG paths, for an artwork layer. */
+export declare function regionsToSvgPaths(regions: readonly VectorRegion[]): string;