@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/_internal/shared/features/sticker-trace/export/machine-profiles.d.ts

@@ -0,0 +1,92 @@
+import { type PrintPageSize } from "./page-sizes";
+export type MachineProfileId = "print-shop" | "cricut-cut" | "cricut-ptc";
+/**
+ * Where a profile's usable cut width comes from. Modelled as a SOURCE rather
+ * than a stored millimetre value because the Print-Then-Cut width is a property
+ * of the page, not of the machine — a second copy of it on the profile would be
+ * a denormalised mirror, and it would drift the first time a page's PTC area
+ * was corrected (CLAUDE.md Root Cause #42).
+ */
+export type CutWidthSource = 
+/** No machine-imposed limit — the print shop's plotter takes roll media. */
+"unbounded"
+/** The machine's own material width, carried on the profile. */
+ | "material"
+/** The target page's sensor-constrained PTC sub-area. */
+ | "page-ptc-area";
+export interface MachineProfile {
+    readonly id: MachineProfileId;
+    readonly label: string;
+    /** The units this machine's own documentation and UI speak in. */
+    readonly units: "mm" | "in";
+    readonly cutWidthSource: CutWidthSource;
+    /** Set only when `cutWidthSource` is `"material"`. */
+    readonly materialWidthMm: number | null;
+    /**
+     * Longest single continuous shape. `null` is genuinely unbounded (roll media
+     * at a print shop); a number is a documented machine limit.
+     */
+    readonly maxCutLengthMm: number | null;
+    /** Whether the exporter must emit sensor registration marks. */
+    readonly registrationMarks: boolean;
+    /**
+     * Narrowest internal feature the machine cuts reliably. Below this the
+     * material tears rather than cuts. `null` where the process has no such
+     * limit worth modelling.
+     */
+    readonly minFeatureMm: number | null;
+    /**
+     * Node ceiling for the emitted path data, re-simplified to independently of
+     * the TRACE tolerance. Tying the two together would mean a more precise trace
+     * producing a file the software cannot open.
+     */
+    readonly nodeBudget: number | null;
+    readonly emits: "cutcontour-svg" | "cut-only-svg" | "print-then-cut";
+    /** One line, shown in the export picker. */
+    readonly summary: string;
+}
+export declare const MACHINE_PROFILES: Readonly<Record<MachineProfileId, MachineProfile>>;
+export declare const MACHINE_PROFILE_IDS: readonly MachineProfileId[];
+export declare function machineProfileById(id: MachineProfileId): MachineProfile;
+/**
+ * The usable cut width for this profile on this page.
+ *
+ * Returns `null` only for a genuinely unbounded profile. Every caller must
+ * treat `null` as "no limit" and NOT as "unknown" — the two are different, and
+ * conflating them is how an unbounded print-shop export would start reporting
+ * every part as unmeasurable.
+ */
+export declare function maxCutWidthMmForPage(profile: MachineProfile, page: PrintPageSize): number | null;
+export interface PartFitVerdict {
+    readonly fits: boolean;
+    /** Wider than the machine can cut. The part must be tiled, or sent elsewhere. */
+    readonly tooWide: boolean;
+    /** Longer than one continuous cut. */
+    readonly tooLong: boolean;
+    /** Has an internal neck below the machine's reliable minimum; it will tear. */
+    readonly tooFine: boolean;
+    /** The limit that was applied, for the message the UI shows. */
+    readonly limitWidthMm: number | null;
+    readonly limitLengthMm: number | null;
+    readonly reasons: readonly string[];
+}
+/**
+ * Report whether a part can be cut on this profile. **Reports only** — it never
+ * scales, never crops and never rotates to make something fit. The plan is
+ * explicit that scaling here is the worst available failure, because the output
+ * looks right.
+ *
+ * `minFeatureMm` is the part's measured narrowest internal feature (the trace
+ * already computes it from the EDT); pass `null` when it has not been measured,
+ * which suppresses the `tooFine` check rather than guessing it passed.
+ *
+ * Rotation is intentionally not considered. On a 4.5-inch-wide material the
+ * long axis must run along the roll, so "it would fit sideways" is false for
+ * the one profile where width is actually binding — and letting the caller
+ * believe otherwise would hide exactly the parts that need tiling.
+ */
+export declare function partFitsProfile(part: {
+    readonly widthMm: number;
+    readonly heightMm: number;
+    readonly minFeatureMm?: number | null;
+}, profile: MachineProfile, page: PrintPageSize): PartFitVerdict;

package/dist/_internal/shared/features/sticker-trace/export/machine-profiles.js

@@ -0,0 +1,153 @@
+/*
+ * WHY: Machine capability is DATA, not hardcode. The exporters, the nester and
+ *      the pre-export report all need the same answer to "can this machine cut
+ *      a part this wide", and the one failure this file exists to prevent is a
+ *      part being silently scaled or cropped to fit. That produces a cut file
+ *      which looks correct and yields stickers the wrong size — discovered only
+ *      after printing, cutting and measuring.
+ * WHAT: The three machine profiles, and the fit check that reports per-part by
+ *       name instead of adjusting anything.
+ *
+ * 🛑 PDF mosaic is deliberately NOT a machine profile. It targets paper, has no
+ * cut head and no width limit, and giving it a profile would mean inventing
+ * capability numbers for a machine that does not exist. It is an exporter that
+ * takes a page size; see export/pdf-mosaic.
+ *
+ * EXPORTS:
+ *   MachineProfileId, CutWidthSource, MachineProfile, MACHINE_PROFILES,
+ *   MACHINE_PROFILE_IDS, machineProfileById, maxCutWidthMmForPage,
+ *   PartFitVerdict, partFitsProfile
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:export/nesting,export/cricut-svg,export/print-then-cut,export/part-tiling,StickerExportPanel
+ * @tag sideEffects:none
+ */
+import { CRICUT_MIN_FEATURE_MM, CRICUT_NODE_BUDGET } from "../config.js";
+import { inchesToMm, printableAreaMm } from "./page-sizes.js";
+/** Cricut Joy 2 material width: 4.5 in, from Cricut's published documentation. */
+const JOY_MATERIAL_WIDTH_MM = inchesToMm(4.5);
+/**
+ * Joy 2 Smart Materials cut one continuous shape up to 4 ft. Repeated cuts can
+ * reach 20 ft, but a single PART is what this bounds, so 4 ft is the honest
+ * number — quoting 20 would admit a shape the machine cannot cut in one pass.
+ */
+const JOY_MAX_CONTINUOUS_MM = inchesToMm(48);
+export const MACHINE_PROFILES = {
+    "print-shop": {
+        id: "print-shop",
+        label: "Print shop (Roland / Graphtec)",
+        units: "mm",
+        cutWidthSource: "unbounded",
+        materialWidthMm: null,
+        maxCutLengthMm: null,
+        registrationMarks: false,
+        minFeatureMm: null,
+        nodeBudget: null,
+        emits: "cutcontour-svg",
+        summary: "Artwork PNG plus a magenta CutContour layer — the format contour-cutting brokers accept. No width limit.",
+    },
+    "cricut-cut": {
+        id: "cricut-cut",
+        label: "Cricut Joy 2 — cut only",
+        units: "in",
+        cutWidthSource: "material",
+        materialWidthMm: JOY_MATERIAL_WIDTH_MM,
+        maxCutLengthMm: JOY_MAX_CONTINUOUS_MM,
+        registrationMarks: false,
+        minFeatureMm: CRICUT_MIN_FEATURE_MM,
+        nodeBudget: CRICUT_NODE_BUDGET,
+        emits: "cut-only-svg",
+        summary: "Outlines only, true millimetre scale, nested into strips within the 4.5 inch material width.",
+    },
+    "cricut-ptc": {
+        id: "cricut-ptc",
+        label: "Cricut Joy 2 — Print Then Cut",
+        units: "in",
+        cutWidthSource: "page-ptc-area",
+        materialWidthMm: null,
+        maxCutLengthMm: JOY_MAX_CONTINUOUS_MM,
+        registrationMarks: true,
+        minFeatureMm: CRICUT_MIN_FEATURE_MM,
+        nodeBudget: CRICUT_NODE_BUDGET,
+        emits: "print-then-cut",
+        summary: "Printable sheet plus cut lines, laid out inside the machine's real sensor-constrained area — on A4 that is a 78 mm column, not the page.",
+    },
+};
+export const MACHINE_PROFILE_IDS = [
+    "print-shop",
+    "cricut-cut",
+    "cricut-ptc",
+];
+export function machineProfileById(id) {
+    return MACHINE_PROFILES[id];
+}
+/**
+ * The usable cut width for this profile on this page.
+ *
+ * Returns `null` only for a genuinely unbounded profile. Every caller must
+ * treat `null` as "no limit" and NOT as "unknown" — the two are different, and
+ * conflating them is how an unbounded print-shop export would start reporting
+ * every part as unmeasurable.
+ */
+export function maxCutWidthMmForPage(profile, page) {
+    switch (profile.cutWidthSource) {
+        case "unbounded":
+            return null;
+        case "material":
+            return profile.materialWidthMm;
+        case "page-ptc-area": {
+            // printableAreaMm throws on a page with no PTC area, which is correct:
+            // choosing a PTC profile against a page the machine cannot register is a
+            // configuration error, not a part that happens not to fit.
+            const area = printableAreaMm(page, true);
+            return Math.min(area.widthMm, JOY_MATERIAL_WIDTH_MM);
+        }
+    }
+}
+/**
+ * Report whether a part can be cut on this profile. **Reports only** — it never
+ * scales, never crops and never rotates to make something fit. The plan is
+ * explicit that scaling here is the worst available failure, because the output
+ * looks right.
+ *
+ * `minFeatureMm` is the part's measured narrowest internal feature (the trace
+ * already computes it from the EDT); pass `null` when it has not been measured,
+ * which suppresses the `tooFine` check rather than guessing it passed.
+ *
+ * Rotation is intentionally not considered. On a 4.5-inch-wide material the
+ * long axis must run along the roll, so "it would fit sideways" is false for
+ * the one profile where width is actually binding — and letting the caller
+ * believe otherwise would hide exactly the parts that need tiling.
+ */
+export function partFitsProfile(part, profile, page) {
+    const limitWidthMm = maxCutWidthMmForPage(profile, page);
+    const limitLengthMm = profile.maxCutLengthMm;
+    const tooWide = limitWidthMm !== null && part.widthMm > limitWidthMm;
+    const tooLong = limitLengthMm !== null && part.heightMm > limitLengthMm;
+    const measuredFeature = part.minFeatureMm ?? null;
+    const tooFine = profile.minFeatureMm !== null &&
+        measuredFeature !== null &&
+        measuredFeature < profile.minFeatureMm;
+    const reasons = [];
+    if (tooWide) {
+        reasons.push(`${part.widthMm.toFixed(1)} mm wide exceeds the ${limitWidthMm?.toFixed(1)} mm cut width — tile it, or use the print-shop profile where no width limit applies.`);
+    }
+    if (tooLong) {
+        reasons.push(`${part.heightMm.toFixed(1)} mm long exceeds the ${limitLengthMm?.toFixed(1)} mm single continuous cut.`);
+    }
+    if (tooFine) {
+        reasons.push(`narrowest feature ${measuredFeature?.toFixed(2)} mm is below the ${profile.minFeatureMm?.toFixed(2)} mm reliable minimum — it will tear rather than cut.`);
+    }
+    return {
+        fits: !tooWide && !tooLong && !tooFine,
+        tooWide,
+        tooLong,
+        tooFine,
+        limitWidthMm,
+        limitLengthMm,
+        reasons,
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { PrintPageSize } from "./page-sizes";
+export interface NestablePart {
+    ordinal: number;
+    name: string;
+    widthMm: number;
+    heightMm: number;
+}
+export interface PlacedPart extends NestablePart {
+    /** Page index, 0-based. */
+    page: number;
+    /** Top-left corner, in page coordinates including the margin. */
+    xMm: number;
+    yMm: number;
+    /** True when the part was turned 90° to fit. */
+    rotated: boolean;
+}
+export interface NestResult {
+    placed: PlacedPart[];
+    pageCount: number;
+    /**
+     * Parts that fit on NO page at any rotation.
+     *
+     * 🛑 Returned rather than thrown, and rather than silently dropped. A part
+     * that cannot be placed is a real operator decision — tile it, or send it to
+     * a profile with no width limit — and both a crash and a silent omission
+     * take that decision away. A silently dropped part is the worse of the two:
+     * the export looks complete and is missing a sticker.
+     */
+    unplaceable: NestablePart[];
+}
+export interface NestOptions {
+    /** Gap between neighbouring parts. Default 2mm — enough for a blade to turn. */
+    gapMm?: number;
+    /**
+     * Nest into the Print-Then-Cut sub-area rather than the printable page.
+     *
+     * 🛑 Must be passed through from the caller's machine profile, never guessed.
+     * `printableAreaMm` defaults it false on purpose so a forgotten flag yields a
+     * layout the machine REJECTS rather than one that silently wastes two thirds
+     * of the page — a rejected file is noticed, a wasteful one is not.
+     */
+    forPrintThenCut?: boolean;
+}
+/**
+ * Lay parts out across as many pages as they need.
+ *
+ * Tall-first because a shelf's height is set by its tallest member: feeding
+ * short parts first leaves tall ones to open a new shelf each, which is the
+ * pathological case for this algorithm and costs real paper.
+ */
+export declare function nestParts(parts: readonly NestablePart[], page: PrintPageSize, opts?: NestOptions): NestResult;

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

@@ -0,0 +1,110 @@
+/*
+ * WHY: Parts have to be placed on a page before anything can be printed, and
+ *      the placement decides how much paper a sheet costs. A naive grid on the
+ *      widest part wastes most of an A4 when one sticker is large and twenty
+ *      are small.
+ * WHAT: Shelf packing — parts sorted tall-first, laid in rows, each row only as
+ *       tall as its own tallest member.
+ *
+ * 🛑 SHELF PACKING, NOT A BIN-PACKING OPTIMUM, and that is a deliberate
+ * ceiling. Optimal 2D packing is NP-hard; a shelf pack is O(n log n), gives a
+ * layout a human can predict by eye, and the residual waste is paper rather
+ * than correctness. An operator who can see why a part landed where it did can
+ * drag it; one looking at a solver's output cannot.
+ *
+ * 🛑 Everything here is MILLIMETRES. The one unit that survives from the trace
+ * to the paper — see page-sizes.ts.
+ *
+ * EXPORTS: NestablePart, PlacedPart, NestResult, nestParts
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/export
+ * @tag sideEffects:none
+ */
+import { printableAreaMm } from "./page-sizes.js";
+const DEFAULT_GAP_MM = 2;
+/**
+ * Lay parts out across as many pages as they need.
+ *
+ * Tall-first because a shelf's height is set by its tallest member: feeding
+ * short parts first leaves tall ones to open a new shelf each, which is the
+ * pathological case for this algorithm and costs real paper.
+ */
+export function nestParts(parts, page, opts = {}) {
+    const gap = opts.gapMm ?? DEFAULT_GAP_MM;
+    const area = printableAreaMm(page, opts.forPrintThenCut ?? false);
+    const originX = page.marginMm;
+    const originY = page.marginMm;
+    const placed = [];
+    const unplaceable = [];
+    /*
+     * Decide orientation ONCE, up front: the orientation that makes the part
+     * shortest is the one that packs best into shelves, and re-deciding per shelf
+     * would make placement depend on arrival order in a way nobody can predict.
+     */
+    const oriented = parts
+        .map((p) => {
+        const fitsUnrotated = p.widthMm <= area.widthMm && p.heightMm <= area.heightMm;
+        const fitsRotated = p.heightMm <= area.widthMm && p.widthMm <= area.heightMm;
+        if (!fitsUnrotated && !fitsRotated)
+            return { part: p, placeable: false };
+        /*
+         * Prefer NOT rotating when both fit. A rotated sticker is harder to
+         * check against the original sheet by eye, and the packing gain from
+         * turning a part that already fits is marginal.
+         */
+        const rotated = fitsUnrotated ? false : true;
+        return {
+            part: p,
+            placeable: true,
+            rotated,
+            w: rotated ? p.heightMm : p.widthMm,
+            h: rotated ? p.widthMm : p.heightMm,
+        };
+    })
+        .filter((o) => {
+        if (!o.placeable) {
+            unplaceable.push(o.part);
+            return false;
+        }
+        return true;
+    });
+    oriented.sort((a, b) => b.h - a.h || b.w - a.w);
+    let pageIndex = 0;
+    let shelfY = 0;
+    let shelfHeight = 0;
+    let cursorX = 0;
+    for (const item of oriented) {
+        // New shelf when this one is full across.
+        if (cursorX > 0 && cursorX + item.w > area.widthMm) {
+            shelfY += shelfHeight + gap;
+            shelfHeight = 0;
+            cursorX = 0;
+        }
+        // New page when the shelf would run off the bottom.
+        if (shelfY + item.h > area.heightMm) {
+            pageIndex += 1;
+            shelfY = 0;
+            shelfHeight = 0;
+            cursorX = 0;
+        }
+        placed.push({
+            ...item.part,
+            page: pageIndex,
+            xMm: Math.round((originX + cursorX) * 100) / 100,
+            yMm: Math.round((originY + shelfY) * 100) / 100,
+            rotated: item.rotated,
+        });
+        cursorX += item.w + gap;
+        shelfHeight = Math.max(shelfHeight, item.h);
+    }
+    return {
+        placed,
+        // 0 placed parts is 0 pages, not 1 — an empty page in a PDF is a wasted sheet.
+        pageCount: placed.length === 0 ? 0 : pageIndex + 1,
+        unplaceable,
+    };
+}

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

@@ -0,0 +1,68 @@
+/** The definition of the inch, exact by international agreement since 1959. */
+export declare 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 declare function inchesToMm(inches: number): number;
+/**
+ * The Print-Then-Cut cuttable sub-region of a page.
+ *
+ * 🛑 This is NOT the page minus a uniform margin. Cricut reserves area for the
+ * sensor registration marks, and the Joy's 4.5" material width caps the result
+ * further — on A4 the cuttable region is a ~78 mm column, roughly a THIRD of
+ * the page width. Treating it as "page minus margin" produces a layout the
+ * machine silently refuses to register.
+ */
+export interface PtcArea {
+    readonly widthMm: number;
+    readonly heightMm: number;
+}
+export type PrintPageSizeId = "a3" | "a4" | "a5" | "letter" | "legal" | "tabloid" | "joy-mat-standard" | "joy-mat-long" | "joy-mat-card" | "joy-smart-material" | "custom";
+export interface PrintPageSize {
+    readonly id: PrintPageSizeId;
+    readonly label: string;
+    readonly widthMm: number;
+    readonly heightMm: number;
+    /**
+     * Unprintable border. For paper this is the printer's mechanical margin; for
+     * a Cricut mat it is 0, because the mat's stated size IS its usable area —
+     * the gridded border sits outside it.
+     */
+    readonly marginMm: number;
+    /** Present only where the page is a Print-Then-Cut target. */
+    readonly ptcArea?: PtcArea;
+    /**
+     * True for a Cricut mat / Smart Material roll rather than a sheet of paper.
+     * The nester uses this to decide whether a page may be rotated: paper may,
+     * a 4.5"-wide mat may not — rotating it would claim a width the machine
+     * does not have.
+     */
+    readonly isMat: boolean;
+}
+export declare const PRINT_PAGE_SIZES: Readonly<Record<PrintPageSizeId, PrintPageSize>>;
+/** Stable display order for pickers: papers first, then mats, then custom. */
+export declare const PRINT_PAGE_SIZE_IDS: readonly PrintPageSizeId[];
+export declare function pageSizeById(id: PrintPageSizeId): PrintPageSize;
+/**
+ * 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 declare function customPageSize(widthMm: number, heightMm: number, marginMm?: number): PrintPageSize;
+/**
+ * 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 declare function printableAreaMm(page: PrintPageSize, forPrintThenCut?: boolean): {
+    widthMm: number;
+    heightMm: number;
+};