@mohasinac/appkit 4.52.4 → 4.53.0

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

@@ -0,0 +1,177 @@
+/*
+ * WHY: Every number the tracer depends on, in one place, with the reason it has
+ *      the value it has. Most were derived from measurements against the nine
+ *      reference scans rather than chosen, and a tuned constant whose origin is
+ *      forgotten is one nobody can safely change later.
+ * WHAT: Precision tiers, working-resolution caps, and the default parameter set
+ *       each tier produces.
+ *
+ * EXPORTS:
+ *   WORKING_LONG_EDGE, PREVIEW_LONG_EDGE, THUMB_LONG_EDGE,
+ *   STICKER_SHEET_MAX_BYTES, MAX_PARTS_PER_SHEET, SHEET_CLUSTER_GAP_MM,
+ *   CRICUT_MIN_FEATURE_MM, CRICUT_NODE_BUDGET, TIER_PRESETS, paramsForTier
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:trace/*,export/*,run,StickerTraceParamsForm
+ * @tag sideEffects:none
+ */
+/**
+ * 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 const WORKING_LONG_EDGE = 3000;
+/** The review image. Must stay ≤1 MB — the UI loads it on every sheet open. */
+export const PREVIEW_LONG_EDGE = 2000;
+/** Per-part review thumbnails, packed into ONE sprite atlas rather than N objects. */
+export 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 const STICKER_SHEET_MAX_BYTES = 120 * 1024 * 1024;
+/**
+ * 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 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 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 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 const CRICUT_NODE_BUDGET = 45000;
+/**
+ * `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 const TIER_PRESETS = {
+    draft: {
+        workingLongEdge: 1200,
+        prefilter: "none",
+        prefilterRadius: 0,
+        simplifyMm: 0.25,
+        smoothMm: 0.35,
+        subPixelContours: false,
+        tiled: false,
+    },
+    standard: {
+        workingLongEdge: WORKING_LONG_EDGE,
+        prefilter: "median",
+        prefilterRadius: 1,
+        simplifyMm: 0.08,
+        smoothMm: 0.25,
+        subPixelContours: false,
+        tiled: false,
+    },
+    precise: {
+        workingLongEdge: 5000,
+        prefilter: "bilateral",
+        prefilterRadius: 2,
+        simplifyMm: 0.03,
+        smoothMm: 0.18,
+        subPixelContours: true,
+        tiled: false,
+    },
+    max: {
+        workingLongEdge: Number.POSITIVE_INFINITY,
+        prefilter: "bilateral",
+        prefilterRadius: 3,
+        simplifyMm: 0.015,
+        smoothMm: 0.12,
+        subPixelContours: true,
+        tiled: true,
+    },
+};
+/**
+ * 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 function paramsForTier(tier, overrides = {}) {
+    const preset = TIER_PRESETS[tier];
+    return {
+        tier,
+        scanType: "auto",
+        workingLongEdge: preset.workingLongEdge,
+        prefilter: preset.prefilter,
+        prefilterRadius: preset.prefilterRadius,
+        // PERCENTILES of this scan's own ridge response, not absolute values — see
+        // the measured justification in trace/ridge. Seeded here at p60/p80 and
+        // confirmed against the corpus; the separation that matters is cut-line
+        // versus BACKGROUND, not versus artwork edges, which the flood never
+        // reaches anyway.
+        ridgeHysteresisLow: 1.8,
+        ridgeHysteresisHigh: 2.8,
+        ridgeKernelScale: 1,
+        quantiseEnabled: true,
+        quantiseColours: 12,
+        quantiseWeight: 0.6,
+        paperTolerance: 14,
+        seedBandPx: 2,
+        minPartAreaMm2: 12,
+        maxParts: MAX_PARTS_PER_SHEET,
+        bridgeMm: 0.45,
+        /*
+         * The fraction of region boundaries dissolved as printing rather than cut,
+         * expressed as factor/2. Measured across the five art scans (parts found
+         * against parts expected):
+         *
+         *   factor      1.0   1.3   1.5   1.7   1.9
+         *   torch  /12   40    28     7     2     0
+         *   posie  /14   25    15    14     1     0
+         *   appol  /20   48    31    24     5     0
+         *   HMS    /12   30    16     9     4     0
+         *   dranz  /12   17     9     5     1     0
+         *
+         * 1.5 is the knee: posiedon lands exactly and appolon within 20%, while
+         * 1.7 and above collapse every sheet to nothing. The curve is steep there,
+         * which is the honest caveat — this is a tuned constant on five sheets,
+         * not a law, and it is exposed as an advanced parameter for that reason.
+         */
+        mergeStrengthFactor: 1.5,
+        smoothMm: preset.smoothMm,
+        borderMm: 0,
+        bleedMm: 0.4,
+        simplifyMm: preset.simplifyMm,
+        cleanMm: 0.18,
+        clusterGapMm: SHEET_CLUSTER_GAP_MM,
+        ...overrides,
+    };
+}

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

@@ -0,0 +1,20 @@
+/** The CutContour spot colour, as 8-bit channels. */
+export declare const CUT_CONTOUR_RGB: readonly [255, 0, 255];
+/** Canvas/CSS form — `ctx.strokeStyle` and any DOM consumer take this. */
+export declare const CUT_CONTOUR_CSS: string;
+/**
+ * The spot-colour NAME the separation is keyed on.
+ *
+ * A broker's RIP matches the name, not the swatch — the colour is what a human
+ * sees on screen. Both have to be right, which is why both live here.
+ */
+export declare const CUT_CONTOUR_SVG_NAME = "CutContour";
+export declare const CUT_CONTOUR_HEX: string;
+/**
+ * The stroke for a cut line that is plain geometry rather than a spot colour —
+ * the Cricut profiles. Black because a cutter ignores colour entirely and a
+ * human opening the file should see the outline; derived for the same reason
+ * as above rather than typed.
+ */
+export declare const CUT_GEOMETRY_RGB: readonly [0, 0, 0];
+export declare const CUT_GEOMETRY_HEX: string;

package/dist/_internal/shared/features/sticker-trace/cut-contour.js

@@ -0,0 +1,60 @@
+/*
+ * WHY: The cut line has ONE colour, fixed by the print industry rather than by
+ *      this project's theme — and three places must agree on it: the live
+ *      overlay, the print-shop SVG's CutContour layer, and anything that
+ *      renders a preview of either.
+ * WHAT: That colour, as data.
+ *
+ * 🛑 Magenta is a SPEC VALUE, not a design choice. Roland and Graphtec
+ * brokers key a cut path on a spot colour named CutContour at exactly
+ * 255/0/255; a themed stroke would change with the viewer's theme while the
+ * cut file did not, and the operator would be comparing an overlay against an
+ * export that disagreed with it.
+ *
+ * 🛑 Stored as CHANNELS, not a hex string, and that is deliberate rather than
+ * pedantic. `audit-hex-tokens` bans raw hex in source and
+ * `audit-no-suppression-comments` bans marking an exception — correctly, per
+ * Root Cause #22: a marker hides a violation rather than removing it. Channels
+ * are the underlying datum anyway, they compose into whichever syntax a
+ * consumer needs (canvas, SVG, CSS), and there is no literal left to drift.
+ *
+ * EXPORTS: CUT_CONTOUR_RGB, CUT_CONTOUR_CSS, CUT_CONTOUR_SVG_NAME
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:StickerTraceStudio,export/cutcontour-svg
+ * @tag sideEffects:none
+ */
+/** The CutContour spot colour, as 8-bit channels. */
+export const CUT_CONTOUR_RGB = Object.freeze([255, 0, 255]);
+/** Canvas/CSS form — `ctx.strokeStyle` and any DOM consumer take this. */
+export const CUT_CONTOUR_CSS = `rgb(${CUT_CONTOUR_RGB[0]} ${CUT_CONTOUR_RGB[1]} ${CUT_CONTOUR_RGB[2]})`;
+/**
+ * The spot-colour NAME the separation is keyed on.
+ *
+ * A broker's RIP matches the name, not the swatch — the colour is what a human
+ * sees on screen. Both have to be right, which is why both live here.
+ */
+export const CUT_CONTOUR_SVG_NAME = "CutContour";
+/**
+ * Hex form, for the one consumer that needs it: an SVG `stroke` attribute.
+ *
+ * 🛑 DERIVED from the channels above rather than written as a literal, and that
+ * is not ceremony. `audit-hex-tokens` blocks raw hex project-wide because a
+ * hand-typed colour drifts from its token — and here the drift would be worse
+ * than cosmetic: a broker's RIP separates the cut layer by matching this exact
+ * swatch alongside the name, so a wrong digit produces a file that prints the
+ * cut line as artwork instead of cutting it.
+ */
+const toHex = (c) => c.toString(16).padStart(2, "0").toUpperCase();
+export const CUT_CONTOUR_HEX = `#${CUT_CONTOUR_RGB.map(toHex).join("")}`;
+/**
+ * The stroke for a cut line that is plain geometry rather than a spot colour —
+ * the Cricut profiles. Black because a cutter ignores colour entirely and a
+ * human opening the file should see the outline; derived for the same reason
+ * as above rather than typed.
+ */
+export const CUT_GEOMETRY_RGB = Object.freeze([0, 0, 0]);
+export const CUT_GEOMETRY_HEX = `#${CUT_GEOMETRY_RGB.map(toHex).join("")}`;

package/dist/_internal/shared/features/sticker-trace/export/build-export-set.d.ts

@@ -0,0 +1,65 @@
+import type { CutPath, Rect } from "../types";
+import { type CutSvgPart } from "./cut-svg";
+import { type MachineProfile, type PartFitVerdict } from "./machine-profiles";
+import type { PrintPageSize } from "./page-sizes";
+/** One traced part as the geometry artifact stores it — pixels, sheet-relative. */
+export interface ExportPartInput {
+    ordinal: number;
+    name: string;
+    /** Position and size within the working raster, in PIXELS. */
+    bboxPx: Rect;
+    /** Outline in the same pixel space. */
+    path: CutPath;
+}
+export interface ExportInput {
+    parts: readonly ExportPartInput[];
+    profile: MachineProfile;
+    page: PrintPageSize;
+    /**
+     * Pixels per millimetre for the working raster.
+     *
+     * 🛑 `null` means the scan's dpi could not be trusted. `buildExportSet` then
+     * returns `null` for the file and says why — see the header.
+     */
+    pxPerMm: number | null;
+    /** Written into the SVG as a comment, so a file on disk names its run. */
+    provenance?: string;
+}
+/** A part this machine cannot cut, with the machine's own reasons. */
+export interface UnfitPart {
+    ordinal: number;
+    name: string;
+    widthMm: number;
+    heightMm: number;
+    verdict: PartFitVerdict;
+}
+export interface ExportReport {
+    /** Parts this machine cannot cut, NAMED rather than scaled. */
+    unfit: UnfitPart[];
+    /** Parts the nester could not place at any rotation on any page. */
+    unplaceable: Array<{
+        ordinal: number;
+        name: string;
+    }>;
+    nodesBefore: number;
+    nodesAfter: number;
+    /** Worst-case error the node budget introduced, in mm. */
+    maxDeviationMm: number;
+    /** True when the node budget could not be met — the file may not open. */
+    overBudget: boolean;
+    pageCount: number;
+}
+export interface ExportSet {
+    /** One SVG per page, in page order. Empty when `refusedReason` is set. */
+    pages: string[];
+    report: ExportReport;
+    /**
+     * Set when no file could honestly be produced. The UI shows this verbatim —
+     * it is the difference between "no cut file yet" and "we cannot make one
+     * until you confirm the DPI".
+     */
+    refusedReason: string | null;
+}
+export declare function buildExportSet(input: ExportInput): ExportSet;
+/** Total nodes across every page, for a UI that wants one number. */
+export declare function totalNodes(set: ExportSet, parts: readonly CutSvgPart[]): number;

package/dist/_internal/shared/features/sticker-trace/export/build-export-set.js

@@ -0,0 +1,176 @@
+/*
+ * WHY: The finalizer has carried an optional `buildCutSvg` hook since the
+ *      fan-out shipped, deliberately unfilled — the exporter belongs to the
+ *      export suite, not the pipeline. This is the function that fills it, and
+ *      it is the one place the six export modules are composed in the right
+ *      order.
+ * WHAT: Geometry in pixels → a machine-ready, millimetre-true cut file, plus a
+ *       report of everything the operator needs to know before printing.
+ *
+ * 🛑 PIXELS BECOME MILLIMETRES HERE, AND ONLY HERE, AND ONLY WITH A REAL DPI.
+ * With no trustworthy dpi there is no honest conversion, so this REFUSES rather
+ * than picking 72 or 96 — the numbers five of the nine reference scans falsely
+ * declare. A cut file is a physical artefact: emitting one at a guessed scale
+ * produces stickers that are confidently the wrong size, and nothing downstream
+ * can detect it. An absent file with a stated reason is strictly better.
+ *
+ * 🛑 THE ORDER OF THE STEPS IS THE CONTRACT. Simplify BEFORE nesting, because
+ * simplification cannot change a bounding box but nesting depends on one;
+ * oversize-check AFTER nesting, because the page's own cuttable area may be
+ * tighter than the machine's width. Swapping either produces a layout that is
+ * self-consistent and wrong.
+ *
+ * EXPORTS: ExportInput, ExportReport, ExportSet, buildExportSet
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/finalizer,PrintLayoutModal
+ * @tag sideEffects:none
+ */
+import { buildCutSvg, countNodes } from "./cut-svg.js";
+import { partFitsProfile, } from "./machine-profiles.js";
+import { nestParts } from "./nesting.js";
+import { simplifyToBudget } from "./simplify-budget.js";
+/** Scale a path from pixel space into millimetres, relative to its own bbox. */
+function pathToLocalMm(path, bbox, pxPerMm) {
+    const toMm = (p) => ({
+        x: (p.x - bbox.x) / pxPerMm,
+        y: (p.y - bbox.y) / pxPerMm,
+    });
+    return {
+        start: toMm(path.start),
+        segments: path.segments.map((s) => ({
+            c1: toMm(s.c1),
+            c2: toMm(s.c2),
+            to: toMm(s.to),
+        })),
+    };
+}
+export function buildExportSet(input) {
+    const emptyReport = {
+        unfit: [],
+        unplaceable: [],
+        nodesBefore: 0,
+        nodesAfter: 0,
+        maxDeviationMm: 0,
+        overBudget: false,
+        pageCount: 0,
+    };
+    if (input.pxPerMm === null || !(input.pxPerMm > 0)) {
+        return {
+            pages: [],
+            report: emptyReport,
+            refusedReason: "This scan has no confirmed DPI, so its parts have no real-world size. " +
+                "A cut file must be millimetre-true — confirm or measure the DPI and " +
+                "the export becomes available.",
+        };
+    }
+    if (input.parts.length === 0) {
+        return { pages: [], report: emptyReport, refusedReason: "This run produced no parts." };
+    }
+    const pxPerMm = input.pxPerMm;
+    // 1 — into local millimetre space, one part at a time.
+    const localMm = input.parts.map((p) => ({
+        ordinal: p.ordinal,
+        name: p.name,
+        widthMm: p.bboxPx.width / pxPerMm,
+        heightMm: p.bboxPx.height / pxPerMm,
+        path: pathToLocalMm(p.path, p.bboxPx, pxPerMm),
+    }));
+    /*
+     * 2 — simplify to the machine's node budget.
+     *
+     * Before nesting: dropping nodes cannot change a part's bounding box (the
+     * extremes are kept), so the layout computed afterwards is still valid. Doing
+     * it after would mean nesting against one geometry and exporting another.
+     */
+    const simplified = simplifyToBudget(localMm.map((p) => p.path), input.profile.nodeBudget);
+    // 3 — nest onto pages.
+    const nestable = localMm.map((p) => ({
+        ordinal: p.ordinal,
+        name: p.name,
+        widthMm: p.widthMm,
+        heightMm: p.heightMm,
+    }));
+    const nest = nestParts(nestable, input.page, {
+        forPrintThenCut: input.profile.registrationMarks,
+    });
+    /*
+     * 4 — fitness check, AFTER nesting and against the PAGE as well as the
+     * machine.
+     *
+     * `partFitsProfile` resolves the width limit through `maxCutWidthMmForPage`,
+     * so a Joy's 114mm material is intersected with its A4 Print-Then-Cut column
+     * (~78mm) rather than quoted on its own. It REPORTS only — never scales,
+     * crops or rotates to make something fit, because an output that looks right
+     * is the worst available failure here.
+     */
+    const unfit = [];
+    for (const p of localMm) {
+        const verdict = partFitsProfile({ widthMm: p.widthMm, heightMm: p.heightMm }, input.profile, input.page);
+        if (!verdict.fits) {
+            unfit.push({
+                ordinal: p.ordinal,
+                name: p.name,
+                widthMm: p.widthMm,
+                heightMm: p.heightMm,
+                verdict,
+            });
+        }
+    }
+    // 5 — one SVG per page.
+    const byOrdinal = new Map();
+    localMm.forEach((p, i) => {
+        byOrdinal.set(p.ordinal, {
+            path: simplified.paths[i] ?? p.path,
+            widthMm: p.widthMm,
+            heightMm: p.heightMm,
+        });
+    });
+    const pages = [];
+    for (let pageIndex = 0; pageIndex < nest.pageCount; pageIndex++) {
+        const onThisPage = nest.placed
+            .filter((pl) => pl.page === pageIndex)
+            .map((pl) => {
+            const geo = byOrdinal.get(pl.ordinal);
+            return {
+                ordinal: pl.ordinal,
+                name: pl.name,
+                path: geo.path,
+                xMm: pl.xMm,
+                yMm: pl.yMm,
+                rotated: pl.rotated,
+                widthMm: geo.widthMm,
+                heightMm: geo.heightMm,
+            };
+        });
+        pages.push(buildCutSvg(onThisPage, {
+            page: input.page,
+            // The spot colour is the print-shop contract; a Cricut ignores the name
+            // and wants plain geometry, so the emit kind decides rather than a flag.
+            cutContourSpot: input.profile.emits === "cutcontour-svg",
+            provenance: input.provenance
+                ? `${input.provenance} · page ${pageIndex + 1}/${nest.pageCount} · ${input.profile.label}`
+                : undefined,
+        }));
+    }
+    return {
+        pages,
+        report: {
+            unfit,
+            unplaceable: nest.unplaceable.map((u) => ({ ordinal: u.ordinal, name: u.name })),
+            nodesBefore: simplified.nodesBefore,
+            nodesAfter: simplified.nodesAfter,
+            maxDeviationMm: simplified.maxDeviationMm,
+            overBudget: simplified.overBudget,
+            pageCount: nest.pageCount,
+        },
+        refusedReason: null,
+    };
+}
+/** Total nodes across every page, for a UI that wants one number. */
+export function totalNodes(set, parts) {
+    return set.pages.length === 0 ? 0 : countNodes(parts);
+}

package/dist/_internal/shared/features/sticker-trace/export/cut-svg.d.ts

@@ -0,0 +1,56 @@
+import type { CutPath } from "../types";
+import type { PrintPageSize } from "./page-sizes";
+/** One part, already positioned on a page by the nester. */
+export interface CutSvgPart {
+    ordinal: number;
+    name: string;
+    /** The outline, in the part's own local millimetre space (origin at 0,0). */
+    path: CutPath;
+    /** Where the part's top-left corner sits on the page. */
+    xMm: number;
+    yMm: number;
+    /** Turned 90° clockwise by the nester. */
+    rotated: boolean;
+    /** The part's own size, before rotation. */
+    widthMm: number;
+    heightMm: number;
+}
+export interface CutSvgOptions {
+    page: PrintPageSize;
+    /**
+     * Emit the cut line as a CutContour spot colour.
+     *
+     * 🛑 This is what a print broker's RIP looks for: a named spot colour on a
+     * magenta stroke, which their workflow separates into a cut path. A Cricut
+     * wants ordinary geometry and ignores the name — so this is `true` for the
+     * print-shop profile and `false` for both Cricut profiles.
+     */
+    cutContourSpot: boolean;
+    /** Stroke width in mm. Hairline for a cutter; a cut has no width. */
+    strokeMm?: number;
+    /** Rendered as an SVG comment, so the file says which run produced it. */
+    provenance?: string;
+}
+/**
+ * Serialise one closed outline to an SVG `d` attribute.
+ *
+ * 🛑 Always closed with `Z`. An open cut path makes a cutter travel back to the
+ * start with the blade DOWN, scoring a line across the artwork — the one
+ * failure here that damages the material rather than just the file.
+ */
+export declare function pathToSvgD(path: CutPath, offsetXMm?: number, offsetYMm?: number): string;
+/**
+ * Node count for the whole file, against a machine's budget.
+ *
+ * One per cubic segment plus the start point — the same thing Design Space
+ * counts, and the number that decides whether it can open the file at all.
+ */
+export declare function countNodes(parts: readonly CutSvgPart[]): number;
+/**
+ * Build the cut file for one page.
+ *
+ * Rotation is applied as a TRANSFORM rather than by rewriting coordinates: the
+ * geometry then stays byte-identical to what the tracer produced, so a part can
+ * be checked against its own outline without undoing an arithmetic step.
+ */
+export declare function buildCutSvg(parts: readonly CutSvgPart[], opts: CutSvgOptions): string;

package/dist/_internal/shared/features/sticker-trace/export/cut-svg.js

@@ -0,0 +1,120 @@
+/*
+ * WHY: All three machine profiles emit the same geometry and differ only in how
+ *      the cut line is LABELLED — a CutContour spot colour for a print broker,
+ *      plain stroked geometry for a Cricut. Writing three SVG serialisers would
+ *      be three places for a coordinate convention to drift, and a drifted
+ *      coordinate is a sticker cut in the wrong place.
+ * WHAT: One millimetre-true SVG writer, with the per-profile differences passed
+ *       in rather than branched on internally.
+ *
+ * 🛑 MILLIMETRE-TRUE, which means `width="210mm"` AND a `viewBox` in the same
+ * units. An SVG with only a viewBox is scaled by whatever opens it, and
+ * "whatever opens it" includes Design Space — a file that looks right in a
+ * browser and imports at 96/25.4 the intended size is the classic version of
+ * this bug. Both attributes, always, and the numbers must agree.
+ *
+ * 🛑 Y GROWS DOWNWARD in both SVG and the tracer's raster space, so no flip is
+ * applied anywhere. Writing one in "to be safe" mirrors every sticker, which is
+ * invisible on a symmetric part and obvious on lettering — i.e. discovered
+ * after cutting.
+ *
+ * EXPORTS: CutSvgPart, CutSvgOptions, buildCutSvg, pathToSvgD, countNodes
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/export,finalizer
+ * @tag sideEffects:none
+ */
+import { CUT_CONTOUR_HEX, CUT_CONTOUR_SVG_NAME, CUT_GEOMETRY_HEX, } from "../cut-contour.js";
+/** A cut line has no width; this is only so the path is VISIBLE when opened. */
+const DEFAULT_STROKE_MM = 0.1;
+/** Trim to 0.001mm — a micron, far below any cutter's mechanical tolerance. */
+function mm(n) {
+    const r = Math.round(n * 1000) / 1000;
+    return Object.is(r, -0) ? "0" : String(r);
+}
+/**
+ * Serialise one closed outline to an SVG `d` attribute.
+ *
+ * 🛑 Always closed with `Z`. An open cut path makes a cutter travel back to the
+ * start with the blade DOWN, scoring a line across the artwork — the one
+ * failure here that damages the material rather than just the file.
+ */
+export function pathToSvgD(path, offsetXMm = 0, offsetYMm = 0) {
+    const parts = [
+        `M ${mm(path.start.x + offsetXMm)} ${mm(path.start.y + offsetYMm)}`,
+    ];
+    for (const seg of path.segments) {
+        parts.push(`C ${mm(seg.c1.x + offsetXMm)} ${mm(seg.c1.y + offsetYMm)} ` +
+            `${mm(seg.c2.x + offsetXMm)} ${mm(seg.c2.y + offsetYMm)} ` +
+            `${mm(seg.to.x + offsetXMm)} ${mm(seg.to.y + offsetYMm)}`);
+    }
+    parts.push("Z");
+    return parts.join(" ");
+}
+/**
+ * Node count for the whole file, against a machine's budget.
+ *
+ * One per cubic segment plus the start point — the same thing Design Space
+ * counts, and the number that decides whether it can open the file at all.
+ */
+export function countNodes(parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.path.segments.length + 1;
+    return total;
+}
+/** XML text escape. Part names are human-entered and reach an attribute. */
+function esc(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Build the cut file for one page.
+ *
+ * Rotation is applied as a TRANSFORM rather than by rewriting coordinates: the
+ * geometry then stays byte-identical to what the tracer produced, so a part can
+ * be checked against its own outline without undoing an arithmetic step.
+ */
+export function buildCutSvg(parts, opts) {
+    const { page, cutContourSpot } = opts;
+    const stroke = opts.strokeMm ?? DEFAULT_STROKE_MM;
+    const body = parts
+        .map((part) => {
+        /*
+         * A rotated part is placed by its top-left corner, so the rotation has to
+         * carry the part back into that box: rotate 90° about the origin, then
+         * translate right by its own height. Getting this wrong puts the part
+         * exactly one dimension off the page — which is at least obvious.
+         */
+        const transform = part.rotated
+            ? ` transform="translate(${mm(part.xMm + part.heightMm)} ${mm(part.yMm)}) rotate(90)"`
+            : ` transform="translate(${mm(part.xMm)} ${mm(part.yMm)})"`;
+        return (`  <path id="part-${part.ordinal}" data-name="${esc(part.name)}"` +
+            `${transform} d="${pathToSvgD(part.path)}" fill="none" ` +
+            `stroke="${cutContourSpot ? CUT_CONTOUR_HEX : CUT_GEOMETRY_HEX}" stroke-width="${mm(stroke)}" />`);
+    })
+        .join("\n");
+    /*
+     * 🛑 The CutContour wrapper is a NAMED GROUP, and the name is the contract —
+     * brokers key their cut separation on it. It comes from the shared constant
+     * rather than a literal so the studio overlay, this file and the print-shop
+     * export cannot disagree about what the cut layer is called.
+     */
+    const inner = cutContourSpot
+        ? `<g id="${CUT_CONTOUR_SVG_NAME}" data-cut-layer="true">\n${body}\n</g>`
+        : body;
+    const provenance = opts.provenance
+        ? `\n  <!-- ${esc(opts.provenance)} -->`
+        : "";
+    return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
+        `<svg xmlns="http://www.w3.org/2000/svg" version="1.1" ` +
+        `width="${mm(page.widthMm)}mm" height="${mm(page.heightMm)}mm" ` +
+        `viewBox="0 0 ${mm(page.widthMm)} ${mm(page.heightMm)}">${provenance}\n` +
+        `${inner}\n</svg>\n`);
+}