@ai-matrx/print 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.0 — 2026-08-30
+
+Wave 2 — three new entries, all import-inert and RSC-safe:
+
+- **/barcode** — 1-D barcode generation: Code 128, EAN-13, UPC-A via lazy
+  `bwip-js` (`bwip-js/browser`, pure-JS SVG in Node AND browsers).
+  `normalizeBarcodeValue` is the one door: EAN/UPC check digits are appended
+  (12/11 digits) or verified (13/12), Code 128 restricted to printable ASCII.
+  `generateBarcodeSvg` everywhere; `generateBarcodeDataUrl` browser-only with
+  a clear error elsewhere. Heights are millimetres (GS1 nominal defaults).
+- **/booklet** — saddle-stitch imposition: `imposeBooklet` pads to a multiple
+  of 4 and yields the exact fold-order sheet spreads (front `[N−2i+2, 2i−1]`,
+  back `[2i, N−2i+1]`); `requiresShortEdgeDuplex: true` encodes the long-edge
+  flip trap in the type; `bookletSizeWarning` flags bulky (>48pp) booklets;
+  `printBooklet`/`buildBookletDocument` compose a 2-up 11×8.5″ print window
+  with the exact duplex settings banner (flip on SHORT edge, fold the stack,
+  staple the spine).
+- **/qr-styled** — branded QR codes (center logo, dot/corner styles, colors)
+  via lazy `qr-code-styling` (browser-only at CALL time; the module imports
+  fine anywhere and throws a clear browser-required error in Node). Error
+  correction restricted to Q/H (default H; lower levels clamp up — a logo
+  occludes modules). Logos accepted as `data:` URLs ONLY (print windows are
+  unauthenticated and remote logos would taint the canvas); logo size clamped
+  ≤0.3 of the symbol.
+
 ## 0.1.0 — 2026-08-29
 
 First release. Extracted from the AI Matrx frontend's print system with

package/dist/barcode.cjs

@@ -0,0 +1,182 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/barcode.ts
+var barcode_exports = {};
+__export(barcode_exports, {
+  DEFAULT_BARCODE_HEIGHT: () => DEFAULT_BARCODE_HEIGHT,
+  DEFAULT_BARCODE_SCALE: () => DEFAULT_BARCODE_SCALE,
+  generateBarcodeDataUrl: () => generateBarcodeDataUrl,
+  generateBarcodeSvg: () => generateBarcodeSvg,
+  normalizeBarcodeValue: () => normalizeBarcodeValue
+});
+module.exports = __toCommonJS(barcode_exports);
+var DEFAULT_BARCODE_SCALE = 2;
+var DEFAULT_BARCODE_HEIGHT = {
+  code128: 12,
+  ean13: 22.85,
+  upca: 22.85
+};
+var GS1_DIGIT_LENGTHS = {
+  ean13: [12, 13],
+  upca: [11, 12]
+};
+var SYMBOLOGIES = ["code128", "ean13", "upca"];
+function assertSymbology(symbology) {
+  if (!SYMBOLOGIES.includes(symbology)) {
+    throw new Error(
+      `Unknown barcode symbology "${String(symbology)}". Expected one of ${SYMBOLOGIES.map((s) => `"${s}"`).join(", ")}.`
+    );
+  }
+  return symbology;
+}
+function gs1CheckDigit(payloadDigits) {
+  let sum = 0;
+  let weight = 3;
+  for (let i = payloadDigits.length - 1; i >= 0; i -= 1) {
+    sum += (payloadDigits.charCodeAt(i) - 48) * weight;
+    weight = weight === 3 ? 1 : 3;
+  }
+  return (10 - sum % 10) % 10;
+}
+function normalizeCode128(value) {
+  if (value.length === 0) {
+    throw new Error("Code 128 barcode value must be a non-empty string.");
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code > 126) {
+      throw new Error(
+        `Code 128 barcode value contains a non-printable-ASCII character ${JSON.stringify(value.charAt(i))} at index ${i} (char code ${code}). Only ASCII 0x20-0x7E can be printed and read back by a human.`
+      );
+    }
+  }
+  return value;
+}
+function normalizeGs1(value, symbology) {
+  const raw = value.trim();
+  if (raw.length === 0) {
+    throw new Error(`${symbology === "ean13" ? "EAN-13" : "UPC-A"} barcode value must be a non-empty string.`);
+  }
+  if (!/^[0-9]+$/.test(raw)) {
+    throw new Error(
+      `${symbology === "ean13" ? "EAN-13" : "UPC-A"} barcode value "${raw}" must contain digits only (no spaces, dashes, or letters).`
+    );
+  }
+  const lengths = GS1_DIGIT_LENGTHS[symbology];
+  const [withoutCheck, withCheck] = lengths;
+  const label = symbology === "ean13" ? "EAN-13" : "UPC-A";
+  if (raw.length === withoutCheck) {
+    return `${raw}${gs1CheckDigit(raw)}`;
+  }
+  if (raw.length === withCheck) {
+    const expected = gs1CheckDigit(raw.slice(0, -1));
+    const actual = raw.charCodeAt(raw.length - 1) - 48;
+    if (expected !== actual) {
+      throw new Error(
+        `${label} barcode value "${raw}" has an invalid GS1 check digit: expected ${expected}, got ${actual}. Pass the first ${withoutCheck} digits instead and the check digit will be computed for you.`
+      );
+    }
+    return raw;
+  }
+  throw new Error(
+    `${label} barcode value "${raw}" must be ${withoutCheck} digits (check digit appended) or ${withCheck} digits (check digit verified), got ${raw.length}.`
+  );
+}
+function normalizeBarcodeValue(value, symbology) {
+  assertSymbology(symbology);
+  if (typeof value !== "string") {
+    throw new Error(`Barcode value must be a string, got ${String(value)}.`);
+  }
+  if (symbology === "code128") {
+    return normalizeCode128(value);
+  }
+  return normalizeGs1(value, symbology);
+}
+function resolveScale(scale) {
+  if (scale === void 0) return DEFAULT_BARCODE_SCALE;
+  if (typeof scale !== "number" || !Number.isFinite(scale) || scale <= 0) {
+    throw new Error(`Barcode scale must be a positive number, got ${String(scale)}.`);
+  }
+  return scale;
+}
+function resolveHeight(heightModules, symbology) {
+  if (heightModules === void 0) return DEFAULT_BARCODE_HEIGHT[symbology];
+  if (typeof heightModules !== "number" || !Number.isFinite(heightModules) || heightModules <= 0) {
+    throw new Error(`Barcode heightModules must be a positive number, got ${String(heightModules)}.`);
+  }
+  return heightModules;
+}
+function buildRenderOptions(value, symbology, opts) {
+  const normalized = normalizeBarcodeValue(value, symbology);
+  return {
+    bcid: symbology,
+    text: normalized,
+    scale: resolveScale(opts?.scale),
+    height: resolveHeight(opts?.heightModules, symbology),
+    includetext: opts?.includeText === void 0 ? true : opts.includeText === true,
+    textxalign: "center"
+  };
+}
+async function generateBarcodeSvg(value, symbology, opts) {
+  const options = buildRenderOptions(value, symbology, opts);
+  const bwipjs = await import("bwip-js/browser");
+  return bwipjs.toSVG(options);
+}
+var USE_SVG_INSTEAD = "Use generateBarcodeSvg() instead \u2014 SVG renders identically, works in Node and the browser, and prints at the printer's resolution rather than the canvas's.";
+async function generateBarcodeDataUrl(value, symbology, opts) {
+  const options = buildRenderOptions(value, symbology, opts);
+  if (typeof document === "undefined") {
+    throw new Error(`generateBarcodeDataUrl() needs a DOM canvas and cannot run in Node. ${USE_SVG_INSTEAD}`);
+  }
+  const bwipjs = await import("bwip-js/browser");
+  const toCanvas = bwipjs.toCanvas;
+  if (typeof toCanvas !== "function") {
+    throw new Error(
+      `bwip-js resolved to its non-browser build, which has no toCanvas() \u2014 barcode PNG rendering is unavailable in this environment. ${USE_SVG_INSTEAD}`
+    );
+  }
+  let canvas;
+  try {
+    canvas = toCanvas(document.createElement("canvas"), options);
+  } catch (cause) {
+    throw new Error(
+      `This environment's canvas could not render the barcode (${cause instanceof Error ? cause.message : String(cause)}). ${USE_SVG_INSTEAD}`,
+      { cause }
+    );
+  }
+  const dataUrl = canvas.toDataURL("image/png");
+  if (typeof dataUrl !== "string" || !dataUrl.startsWith("data:image/png")) {
+    throw new Error(
+      `This environment's canvas produced no PNG data URL (got ${String(dataUrl)}) \u2014 barcode PNG rendering is unavailable here. ${USE_SVG_INSTEAD}`
+    );
+  }
+  return dataUrl;
+}
+//# sourceMappingURL=barcode.cjs.map

package/dist/barcode.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/barcode.ts"],"sourcesContent":["/**\n * @ai-matrx/print/barcode — 1-D BARCODE GENERATION for retail and warehouse labels.\n *\n * New code (no port source). Scanning/decoding is NOT here. This module only\n * ever turns a value into a linear symbol, in the three symbologies that\n * actually show up on the commerce lane's labels:\n *\n *  - `code128` — the general-purpose workhorse. The `manufacturer_serial`\n *    identifier kind is usually printed as Code 128: arbitrary printable ASCII,\n *    dense, and every warehouse scanner reads it.\n *  - `ean13` / `upca` — retail GTINs. These are NOT free-form strings: they\n *    carry a GS1 mod-10 check digit, and a label printed with the wrong one is\n *    a label that gets rejected at the point of sale.\n *\n * Two rules that are NOT style choices:\n *  - EVERY generate call routes through `normalizeBarcodeValue` first. A caller\n *    that hands us 12 digits gets the check digit APPENDED; a caller that hands\n *    us 13 gets it VERIFIED and throws on a mismatch. There is no path that\n *    prints an unvalidated retail symbol.\n *  - The human-readable line defaults ON (`includeText`). On a retail or\n *    warehouse label the printed digits are the fallback when the scanner\n *    fails, and a keyer at a register cannot read bars.\n *\n * The module is import-inert: `bwip-js` is only ever pulled in via\n * `await import(\"bwip-js\")` inside a function body, so importing this file from\n * a React Server Component (or any bundle that never draws a barcode) costs\n * nothing. No module-level mutable state, no React, no DOM at import time.\n *\n * SVG works EVERYWHERE — bwip-js `toSVG` is pure JS with no canvas dependency,\n * so it is the lane for Node (server-side PDF/label composition) as much as for\n * the browser. The PNG data-URL lane is browser-only by design: it uses\n * bwip-js's canvas rendering rather than dragging `node-canvas` into a package\n * that mostly runs in a print window. In Node it throws and names the fix.\n */\n\n/**\n * We import the \"bwip-js/browser\" SUBPATH rather than the bare \"bwip-js\"\n * specifier, deliberately and for two reasons:\n *  1. bwip-js's export map has no `default` condition — only `browser`, `node`,\n *    `electron` and `react-native` — so a bundler-style TypeScript resolver\n *    cannot resolve the bare specifier at all. The subpath resolves cleanly.\n *  2. The browser build is the SUPERSET for our purposes: its `toSVG` is pure\n *     JS and imports/runs fine under Node (verified — nothing touches `document`\n *     at module scope), and it is the only build that carries `toCanvas`, which\n *     the PNG lane needs. The node build would give us `toBuffer` instead and\n *     no canvas lane at all.\n */\nimport type { RenderOptions } from \"bwip-js/browser\";\n\n// ─── Contract ────────────────────────────────────────────────────────────────\n\n/** The three 1-D symbologies the platform prints. Values are bwip-js `bcid`s verbatim. */\nexport type BarcodeSymbology = \"code128\" | \"ean13\" | \"upca\";\n\nexport interface BarcodeOptions {\n    /**\n     * Bar height. This is bwip-js's `height`, whose unit is MILLIMETRES (it is\n     * not a module count — the name follows the package's option contract).\n     * Defaults per symbology: 12 for Code 128, 22.85 for EAN-13/UPC-A, the GS1\n     * nominal symbol height at 100% magnification.\n     */\n    heightModules?: number;\n    /** Human-readable line under the bars. Default TRUE — it is the fallback when a scan fails. */\n    includeText?: boolean;\n    /** Module width multiplier (bwip-js `scale`). Default 2. */\n    scale?: number;\n}\n\n/** Default module-width multiplier for every Matrx-printed barcode. */\nexport const DEFAULT_BARCODE_SCALE = 2;\n\n/**\n * Default bar height in millimetres, per symbology.\n * 22.85mm is the GS1 nominal EAN-13/UPC-A symbol height at 100% magnification;\n * Code 128 has no spec height, and 12mm is a comfortable warehouse-label bar.\n */\nexport const DEFAULT_BARCODE_HEIGHT: Readonly<Record<BarcodeSymbology, number>> = {\n    code128: 12,\n    ean13: 22.85,\n    upca: 22.85,\n};\n\n/** Digit counts each GS1 symbology accepts: [without check digit, with check digit]. */\nconst GS1_DIGIT_LENGTHS: Readonly<Record<\"ean13\" | \"upca\", readonly [number, number]>> = {\n    ean13: [12, 13],\n    upca: [11, 12],\n};\n\nconst SYMBOLOGIES: readonly BarcodeSymbology[] = [\"code128\", \"ean13\", \"upca\"];\n\nfunction assertSymbology(symbology: BarcodeSymbology): BarcodeSymbology {\n    if (!SYMBOLOGIES.includes(symbology)) {\n        throw new Error(\n            `Unknown barcode symbology \"${String(symbology)}\". Expected one of ${SYMBOLOGIES.map((s) => `\"${s}\"`).join(\", \")}.`,\n        );\n    }\n    return symbology;\n}\n\n// ─── Validation ──────────────────────────────────────────────────────────────\n\n/**\n * GS1 mod-10 check digit over the payload digits (i.e. WITHOUT the check\n * digit): weights 3 and 1 alternating from the right. Length-independent, so\n * UPC-A's 11-digit payload and EAN-13's 12-digit payload use the same routine.\n */\nfunction gs1CheckDigit(payloadDigits: string): number {\n    let sum = 0;\n    let weight = 3;\n    for (let i = payloadDigits.length - 1; i >= 0; i -= 1) {\n        sum += (payloadDigits.charCodeAt(i) - 48) * weight;\n        weight = weight === 3 ? 1 : 3;\n    }\n    return (10 - (sum % 10)) % 10;\n}\n\n/**\n * Code 128 encodes ASCII 0–127, but a label only prints what a human can read\n * back, so we accept the printable range 0x20 (space) through 0x7E (tilde).\n * Control characters and anything non-ASCII (smart quotes pasted from a\n * spreadsheet are the usual culprit) are rejected loudly rather than silently\n * mangled by the encoder.\n */\nfunction normalizeCode128(value: string): string {\n    if (value.length === 0) {\n        throw new Error(\"Code 128 barcode value must be a non-empty string.\");\n    }\n    for (let i = 0; i < value.length; i += 1) {\n        const code = value.charCodeAt(i);\n        if (code < 0x20 || code > 0x7e) {\n            throw new Error(\n                `Code 128 barcode value contains a non-printable-ASCII character ${JSON.stringify(value.charAt(i))} ` +\n                    `at index ${i} (char code ${code}). Only ASCII 0x20-0x7E can be printed and read back by a human.`,\n            );\n        }\n    }\n    return value;\n}\n\nfunction normalizeGs1(value: string, symbology: \"ean13\" | \"upca\"): string {\n    const raw = value.trim();\n    if (raw.length === 0) {\n        throw new Error(`${symbology === \"ean13\" ? \"EAN-13\" : \"UPC-A\"} barcode value must be a non-empty string.`);\n    }\n    if (!/^[0-9]+$/.test(raw)) {\n        throw new Error(\n            `${symbology === \"ean13\" ? \"EAN-13\" : \"UPC-A\"} barcode value \"${raw}\" must contain digits only ` +\n                `(no spaces, dashes, or letters).`,\n        );\n    }\n\n    const lengths = GS1_DIGIT_LENGTHS[symbology];\n    const [withoutCheck, withCheck] = lengths;\n    const label = symbology === \"ean13\" ? \"EAN-13\" : \"UPC-A\";\n\n    if (raw.length === withoutCheck) {\n        // Caller gave us the payload — APPEND the check digit we compute.\n        return `${raw}${gs1CheckDigit(raw)}`;\n    }\n    if (raw.length === withCheck) {\n        // Caller gave us a full code — VERIFY the check digit they already have.\n        const expected = gs1CheckDigit(raw.slice(0, -1));\n        const actual = raw.charCodeAt(raw.length - 1) - 48;\n        if (expected !== actual) {\n            throw new Error(\n                `${label} barcode value \"${raw}\" has an invalid GS1 check digit: expected ${expected}, got ${actual}. ` +\n                    `Pass the first ${withoutCheck} digits instead and the check digit will be computed for you.`,\n            );\n        }\n        return raw;\n    }\n    throw new Error(\n        `${label} barcode value \"${raw}\" must be ${withoutCheck} digits (check digit appended) or ` +\n            `${withCheck} digits (check digit verified), got ${raw.length}.`,\n    );\n}\n\n/**\n * Validate and normalize a value for a symbology, returning the FULL value that\n * will actually be encoded.\n *\n *  - `ean13` / `upca`: digits only. 12 (EAN-13) or 11 (UPC-A) digits get the\n *    GS1 mod-10 check digit APPENDED; 13 or 12 digits get theirs VERIFIED and\n *    throw on a mismatch. Either way the return value is the complete code.\n *  - `code128`: printable ASCII (0x20-0x7E) passes through untouched —\n *    including leading/trailing spaces, which are legal Code 128 data.\n *\n * Throws an Error with a message naming the exact problem. Every generator in\n * this module routes through here first; call it directly when you need to show\n * the normalized value (e.g. the digits under the bars) before printing.\n */\nexport function normalizeBarcodeValue(value: string, symbology: BarcodeSymbology): string {\n    assertSymbology(symbology);\n    if (typeof value !== \"string\") {\n        throw new Error(`Barcode value must be a string, got ${String(value)}.`);\n    }\n    if (symbology === \"code128\") {\n        return normalizeCode128(value);\n    }\n    return normalizeGs1(value, symbology);\n}\n\n// ─── Option resolution ───────────────────────────────────────────────────────\n\nfunction resolveScale(scale: number | undefined): number {\n    if (scale === undefined) return DEFAULT_BARCODE_SCALE;\n    if (typeof scale !== \"number\" || !Number.isFinite(scale) || scale <= 0) {\n        throw new Error(`Barcode scale must be a positive number, got ${String(scale)}.`);\n    }\n    return scale;\n}\n\nfunction resolveHeight(heightModules: number | undefined, symbology: BarcodeSymbology): number {\n    if (heightModules === undefined) return DEFAULT_BARCODE_HEIGHT[symbology];\n    if (typeof heightModules !== \"number\" || !Number.isFinite(heightModules) || heightModules <= 0) {\n        throw new Error(`Barcode heightModules must be a positive number, got ${String(heightModules)}.`);\n    }\n    return heightModules;\n}\n\n/**\n * Build the bwip-js render options. Note the object is fully populated here —\n * under `exactOptionalPropertyTypes` we never assign `undefined` to an optional\n * key, so every field is either a real value or absent.\n */\nfunction buildRenderOptions(value: string, symbology: BarcodeSymbology, opts: BarcodeOptions | undefined): RenderOptions {\n    const normalized = normalizeBarcodeValue(value, symbology);\n    return {\n        bcid: symbology,\n        text: normalized,\n        scale: resolveScale(opts?.scale),\n        height: resolveHeight(opts?.heightModules, symbology),\n        includetext: opts?.includeText === undefined ? true : opts.includeText === true,\n        textxalign: \"center\",\n    };\n}\n\n// ─── Rendering ───────────────────────────────────────────────────────────────\n\n/**\n * SVG markup string — the lane that works EVERYWHERE (Node and browser), since\n * bwip-js `toSVG` is pure JS with no canvas dependency. Lazy-imports `bwip-js`\n * at call time, so this module stays import-inert.\n *\n * The value is validated and normalized first; a bad GS1 check digit throws\n * here rather than printing a label nobody can sell.\n */\nexport async function generateBarcodeSvg(\n    value: string,\n    symbology: BarcodeSymbology,\n    opts?: BarcodeOptions,\n): Promise<string> {\n    const options = buildRenderOptions(value, symbology, opts);\n    const bwipjs = await import(\"bwip-js/browser\");\n    return bwipjs.toSVG(options);\n}\n\n/**\n * `toCanvas` only exists in bwip-js's browser build (the node build ships\n * `toBuffer` instead), so even on the browser subpath we PROBE for it rather\n * than assume which condition a host bundler ultimately resolved.\n */\ninterface BwipCanvasLane {\n    toCanvas?: (canvas: HTMLCanvasElement, opts: RenderOptions) => HTMLCanvasElement;\n}\n\nconst USE_SVG_INSTEAD =\n    \"Use generateBarcodeSvg() instead — SVG renders identically, works in Node and the browser, \" +\n    \"and prints at the printer's resolution rather than the canvas's.\";\n\n/**\n * PNG data URL, for embedding straight into a print window's `<img src>`.\n *\n * BROWSER ONLY. In Node this throws immediately and names the fix rather than\n * dragging `node-canvas` (a native build) into a package that mostly runs in a\n * print window. The same clear error is thrown in a DOM environment whose\n * canvas is a stub (jsdom without the optional `canvas` package returns `null`\n * from `toDataURL`) — we would rather fail loudly than hand back a broken\n * `src` that silently renders as a missing image.\n */\nexport async function generateBarcodeDataUrl(\n    value: string,\n    symbology: BarcodeSymbology,\n    opts?: BarcodeOptions,\n): Promise<string> {\n    const options = buildRenderOptions(value, symbology, opts);\n\n    if (typeof document === \"undefined\") {\n        throw new Error(`generateBarcodeDataUrl() needs a DOM canvas and cannot run in Node. ${USE_SVG_INSTEAD}`);\n    }\n\n    const bwipjs = (await import(\"bwip-js/browser\")) as unknown as BwipCanvasLane;\n    const toCanvas = bwipjs.toCanvas;\n    if (typeof toCanvas !== \"function\") {\n        throw new Error(\n            `bwip-js resolved to its non-browser build, which has no toCanvas() — barcode PNG rendering is ` +\n                `unavailable in this environment. ${USE_SVG_INSTEAD}`,\n        );\n    }\n\n    let canvas: HTMLCanvasElement;\n    try {\n        canvas = toCanvas(document.createElement(\"canvas\"), options);\n    } catch (cause) {\n        // A DOM without a real 2-D context (jsdom without the optional `canvas`\n        // package is the common one) fails somewhere inside bwip-js's drawing\n        // code. Re-throw with the fix instead of a stray TypeError.\n        throw new Error(\n            `This environment's canvas could not render the barcode (${cause instanceof Error ? cause.message : String(cause)}). ` +\n                `${USE_SVG_INSTEAD}`,\n            { cause },\n        );\n    }\n    const dataUrl: unknown = canvas.toDataURL(\"image/png\");\n    if (typeof dataUrl !== \"string\" || !dataUrl.startsWith(\"data:image/png\")) {\n        throw new Error(\n            `This environment's canvas produced no PNG data URL (got ${String(dataUrl)}) — barcode PNG rendering ` +\n                `is unavailable here. ${USE_SVG_INSTEAD}`,\n        );\n    }\n    return dataUrl;\n}\n"],"mappings":"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","names":[]}

package/dist/barcode.d.cts

@@ -0,0 +1,94 @@
+/**
+ * @ai-matrx/print/barcode — 1-D BARCODE GENERATION for retail and warehouse labels.
+ *
+ * New code (no port source). Scanning/decoding is NOT here. This module only
+ * ever turns a value into a linear symbol, in the three symbologies that
+ * actually show up on the commerce lane's labels:
+ *
+ *  - `code128` — the general-purpose workhorse. The `manufacturer_serial`
+ *    identifier kind is usually printed as Code 128: arbitrary printable ASCII,
+ *    dense, and every warehouse scanner reads it.
+ *  - `ean13` / `upca` — retail GTINs. These are NOT free-form strings: they
+ *    carry a GS1 mod-10 check digit, and a label printed with the wrong one is
+ *    a label that gets rejected at the point of sale.
+ *
+ * Two rules that are NOT style choices:
+ *  - EVERY generate call routes through `normalizeBarcodeValue` first. A caller
+ *    that hands us 12 digits gets the check digit APPENDED; a caller that hands
+ *    us 13 gets it VERIFIED and throws on a mismatch. There is no path that
+ *    prints an unvalidated retail symbol.
+ *  - The human-readable line defaults ON (`includeText`). On a retail or
+ *    warehouse label the printed digits are the fallback when the scanner
+ *    fails, and a keyer at a register cannot read bars.
+ *
+ * The module is import-inert: `bwip-js` is only ever pulled in via
+ * `await import("bwip-js")` inside a function body, so importing this file from
+ * a React Server Component (or any bundle that never draws a barcode) costs
+ * nothing. No module-level mutable state, no React, no DOM at import time.
+ *
+ * SVG works EVERYWHERE — bwip-js `toSVG` is pure JS with no canvas dependency,
+ * so it is the lane for Node (server-side PDF/label composition) as much as for
+ * the browser. The PNG data-URL lane is browser-only by design: it uses
+ * bwip-js's canvas rendering rather than dragging `node-canvas` into a package
+ * that mostly runs in a print window. In Node it throws and names the fix.
+ */
+/** The three 1-D symbologies the platform prints. Values are bwip-js `bcid`s verbatim. */
+type BarcodeSymbology = "code128" | "ean13" | "upca";
+interface BarcodeOptions {
+    /**
+     * Bar height. This is bwip-js's `height`, whose unit is MILLIMETRES (it is
+     * not a module count — the name follows the package's option contract).
+     * Defaults per symbology: 12 for Code 128, 22.85 for EAN-13/UPC-A, the GS1
+     * nominal symbol height at 100% magnification.
+     */
+    heightModules?: number;
+    /** Human-readable line under the bars. Default TRUE — it is the fallback when a scan fails. */
+    includeText?: boolean;
+    /** Module width multiplier (bwip-js `scale`). Default 2. */
+    scale?: number;
+}
+/** Default module-width multiplier for every Matrx-printed barcode. */
+declare const DEFAULT_BARCODE_SCALE = 2;
+/**
+ * Default bar height in millimetres, per symbology.
+ * 22.85mm is the GS1 nominal EAN-13/UPC-A symbol height at 100% magnification;
+ * Code 128 has no spec height, and 12mm is a comfortable warehouse-label bar.
+ */
+declare const DEFAULT_BARCODE_HEIGHT: Readonly<Record<BarcodeSymbology, number>>;
+/**
+ * Validate and normalize a value for a symbology, returning the FULL value that
+ * will actually be encoded.
+ *
+ *  - `ean13` / `upca`: digits only. 12 (EAN-13) or 11 (UPC-A) digits get the
+ *    GS1 mod-10 check digit APPENDED; 13 or 12 digits get theirs VERIFIED and
+ *    throw on a mismatch. Either way the return value is the complete code.
+ *  - `code128`: printable ASCII (0x20-0x7E) passes through untouched —
+ *    including leading/trailing spaces, which are legal Code 128 data.
+ *
+ * Throws an Error with a message naming the exact problem. Every generator in
+ * this module routes through here first; call it directly when you need to show
+ * the normalized value (e.g. the digits under the bars) before printing.
+ */
+declare function normalizeBarcodeValue(value: string, symbology: BarcodeSymbology): string;
+/**
+ * SVG markup string — the lane that works EVERYWHERE (Node and browser), since
+ * bwip-js `toSVG` is pure JS with no canvas dependency. Lazy-imports `bwip-js`
+ * at call time, so this module stays import-inert.
+ *
+ * The value is validated and normalized first; a bad GS1 check digit throws
+ * here rather than printing a label nobody can sell.
+ */
+declare function generateBarcodeSvg(value: string, symbology: BarcodeSymbology, opts?: BarcodeOptions): Promise<string>;
+/**
+ * PNG data URL, for embedding straight into a print window's `<img src>`.
+ *
+ * BROWSER ONLY. In Node this throws immediately and names the fix rather than
+ * dragging `node-canvas` (a native build) into a package that mostly runs in a
+ * print window. The same clear error is thrown in a DOM environment whose
+ * canvas is a stub (jsdom without the optional `canvas` package returns `null`
+ * from `toDataURL`) — we would rather fail loudly than hand back a broken
+ * `src` that silently renders as a missing image.
+ */
+declare function generateBarcodeDataUrl(value: string, symbology: BarcodeSymbology, opts?: BarcodeOptions): Promise<string>;
+
+export { type BarcodeOptions, type BarcodeSymbology, DEFAULT_BARCODE_HEIGHT, DEFAULT_BARCODE_SCALE, generateBarcodeDataUrl, generateBarcodeSvg, normalizeBarcodeValue };

package/dist/barcode.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @ai-matrx/print/barcode — 1-D BARCODE GENERATION for retail and warehouse labels.
+ *
+ * New code (no port source). Scanning/decoding is NOT here. This module only
+ * ever turns a value into a linear symbol, in the three symbologies that
+ * actually show up on the commerce lane's labels:
+ *
+ *  - `code128` — the general-purpose workhorse. The `manufacturer_serial`
+ *    identifier kind is usually printed as Code 128: arbitrary printable ASCII,
+ *    dense, and every warehouse scanner reads it.
+ *  - `ean13` / `upca` — retail GTINs. These are NOT free-form strings: they
+ *    carry a GS1 mod-10 check digit, and a label printed with the wrong one is
+ *    a label that gets rejected at the point of sale.
+ *
+ * Two rules that are NOT style choices:
+ *  - EVERY generate call routes through `normalizeBarcodeValue` first. A caller
+ *    that hands us 12 digits gets the check digit APPENDED; a caller that hands
+ *    us 13 gets it VERIFIED and throws on a mismatch. There is no path that
+ *    prints an unvalidated retail symbol.
+ *  - The human-readable line defaults ON (`includeText`). On a retail or
+ *    warehouse label the printed digits are the fallback when the scanner
+ *    fails, and a keyer at a register cannot read bars.
+ *
+ * The module is import-inert: `bwip-js` is only ever pulled in via
+ * `await import("bwip-js")` inside a function body, so importing this file from
+ * a React Server Component (or any bundle that never draws a barcode) costs
+ * nothing. No module-level mutable state, no React, no DOM at import time.
+ *
+ * SVG works EVERYWHERE — bwip-js `toSVG` is pure JS with no canvas dependency,
+ * so it is the lane for Node (server-side PDF/label composition) as much as for
+ * the browser. The PNG data-URL lane is browser-only by design: it uses
+ * bwip-js's canvas rendering rather than dragging `node-canvas` into a package
+ * that mostly runs in a print window. In Node it throws and names the fix.
+ */
+/** The three 1-D symbologies the platform prints. Values are bwip-js `bcid`s verbatim. */
+type BarcodeSymbology = "code128" | "ean13" | "upca";
+interface BarcodeOptions {
+    /**
+     * Bar height. This is bwip-js's `height`, whose unit is MILLIMETRES (it is
+     * not a module count — the name follows the package's option contract).
+     * Defaults per symbology: 12 for Code 128, 22.85 for EAN-13/UPC-A, the GS1
+     * nominal symbol height at 100% magnification.
+     */
+    heightModules?: number;
+    /** Human-readable line under the bars. Default TRUE — it is the fallback when a scan fails. */
+    includeText?: boolean;
+    /** Module width multiplier (bwip-js `scale`). Default 2. */
+    scale?: number;
+}
+/** Default module-width multiplier for every Matrx-printed barcode. */
+declare const DEFAULT_BARCODE_SCALE = 2;
+/**
+ * Default bar height in millimetres, per symbology.
+ * 22.85mm is the GS1 nominal EAN-13/UPC-A symbol height at 100% magnification;
+ * Code 128 has no spec height, and 12mm is a comfortable warehouse-label bar.
+ */
+declare const DEFAULT_BARCODE_HEIGHT: Readonly<Record<BarcodeSymbology, number>>;
+/**
+ * Validate and normalize a value for a symbology, returning the FULL value that
+ * will actually be encoded.
+ *
+ *  - `ean13` / `upca`: digits only. 12 (EAN-13) or 11 (UPC-A) digits get the
+ *    GS1 mod-10 check digit APPENDED; 13 or 12 digits get theirs VERIFIED and
+ *    throw on a mismatch. Either way the return value is the complete code.
+ *  - `code128`: printable ASCII (0x20-0x7E) passes through untouched —
+ *    including leading/trailing spaces, which are legal Code 128 data.
+ *
+ * Throws an Error with a message naming the exact problem. Every generator in
+ * this module routes through here first; call it directly when you need to show
+ * the normalized value (e.g. the digits under the bars) before printing.
+ */
+declare function normalizeBarcodeValue(value: string, symbology: BarcodeSymbology): string;
+/**
+ * SVG markup string — the lane that works EVERYWHERE (Node and browser), since
+ * bwip-js `toSVG` is pure JS with no canvas dependency. Lazy-imports `bwip-js`
+ * at call time, so this module stays import-inert.
+ *
+ * The value is validated and normalized first; a bad GS1 check digit throws
+ * here rather than printing a label nobody can sell.
+ */
+declare function generateBarcodeSvg(value: string, symbology: BarcodeSymbology, opts?: BarcodeOptions): Promise<string>;
+/**
+ * PNG data URL, for embedding straight into a print window's `<img src>`.
+ *
+ * BROWSER ONLY. In Node this throws immediately and names the fix rather than
+ * dragging `node-canvas` (a native build) into a package that mostly runs in a
+ * print window. The same clear error is thrown in a DOM environment whose
+ * canvas is a stub (jsdom without the optional `canvas` package returns `null`
+ * from `toDataURL`) — we would rather fail loudly than hand back a broken
+ * `src` that silently renders as a missing image.
+ */
+declare function generateBarcodeDataUrl(value: string, symbology: BarcodeSymbology, opts?: BarcodeOptions): Promise<string>;
+
+export { type BarcodeOptions, type BarcodeSymbology, DEFAULT_BARCODE_HEIGHT, DEFAULT_BARCODE_SCALE, generateBarcodeDataUrl, generateBarcodeSvg, normalizeBarcodeValue };

package/dist/barcode.js

@@ -0,0 +1,151 @@
+// src/barcode.ts
+var DEFAULT_BARCODE_SCALE = 2;
+var DEFAULT_BARCODE_HEIGHT = {
+  code128: 12,
+  ean13: 22.85,
+  upca: 22.85
+};
+var GS1_DIGIT_LENGTHS = {
+  ean13: [12, 13],
+  upca: [11, 12]
+};
+var SYMBOLOGIES = ["code128", "ean13", "upca"];
+function assertSymbology(symbology) {
+  if (!SYMBOLOGIES.includes(symbology)) {
+    throw new Error(
+      `Unknown barcode symbology "${String(symbology)}". Expected one of ${SYMBOLOGIES.map((s) => `"${s}"`).join(", ")}.`
+    );
+  }
+  return symbology;
+}
+function gs1CheckDigit(payloadDigits) {
+  let sum = 0;
+  let weight = 3;
+  for (let i = payloadDigits.length - 1; i >= 0; i -= 1) {
+    sum += (payloadDigits.charCodeAt(i) - 48) * weight;
+    weight = weight === 3 ? 1 : 3;
+  }
+  return (10 - sum % 10) % 10;
+}
+function normalizeCode128(value) {
+  if (value.length === 0) {
+    throw new Error("Code 128 barcode value must be a non-empty string.");
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code > 126) {
+      throw new Error(
+        `Code 128 barcode value contains a non-printable-ASCII character ${JSON.stringify(value.charAt(i))} at index ${i} (char code ${code}). Only ASCII 0x20-0x7E can be printed and read back by a human.`
+      );
+    }
+  }
+  return value;
+}
+function normalizeGs1(value, symbology) {
+  const raw = value.trim();
+  if (raw.length === 0) {
+    throw new Error(`${symbology === "ean13" ? "EAN-13" : "UPC-A"} barcode value must be a non-empty string.`);
+  }
+  if (!/^[0-9]+$/.test(raw)) {
+    throw new Error(
+      `${symbology === "ean13" ? "EAN-13" : "UPC-A"} barcode value "${raw}" must contain digits only (no spaces, dashes, or letters).`
+    );
+  }
+  const lengths = GS1_DIGIT_LENGTHS[symbology];
+  const [withoutCheck, withCheck] = lengths;
+  const label = symbology === "ean13" ? "EAN-13" : "UPC-A";
+  if (raw.length === withoutCheck) {
+    return `${raw}${gs1CheckDigit(raw)}`;
+  }
+  if (raw.length === withCheck) {
+    const expected = gs1CheckDigit(raw.slice(0, -1));
+    const actual = raw.charCodeAt(raw.length - 1) - 48;
+    if (expected !== actual) {
+      throw new Error(
+        `${label} barcode value "${raw}" has an invalid GS1 check digit: expected ${expected}, got ${actual}. Pass the first ${withoutCheck} digits instead and the check digit will be computed for you.`
+      );
+    }
+    return raw;
+  }
+  throw new Error(
+    `${label} barcode value "${raw}" must be ${withoutCheck} digits (check digit appended) or ${withCheck} digits (check digit verified), got ${raw.length}.`
+  );
+}
+function normalizeBarcodeValue(value, symbology) {
+  assertSymbology(symbology);
+  if (typeof value !== "string") {
+    throw new Error(`Barcode value must be a string, got ${String(value)}.`);
+  }
+  if (symbology === "code128") {
+    return normalizeCode128(value);
+  }
+  return normalizeGs1(value, symbology);
+}
+function resolveScale(scale) {
+  if (scale === void 0) return DEFAULT_BARCODE_SCALE;
+  if (typeof scale !== "number" || !Number.isFinite(scale) || scale <= 0) {
+    throw new Error(`Barcode scale must be a positive number, got ${String(scale)}.`);
+  }
+  return scale;
+}
+function resolveHeight(heightModules, symbology) {
+  if (heightModules === void 0) return DEFAULT_BARCODE_HEIGHT[symbology];
+  if (typeof heightModules !== "number" || !Number.isFinite(heightModules) || heightModules <= 0) {
+    throw new Error(`Barcode heightModules must be a positive number, got ${String(heightModules)}.`);
+  }
+  return heightModules;
+}
+function buildRenderOptions(value, symbology, opts) {
+  const normalized = normalizeBarcodeValue(value, symbology);
+  return {
+    bcid: symbology,
+    text: normalized,
+    scale: resolveScale(opts?.scale),
+    height: resolveHeight(opts?.heightModules, symbology),
+    includetext: opts?.includeText === void 0 ? true : opts.includeText === true,
+    textxalign: "center"
+  };
+}
+async function generateBarcodeSvg(value, symbology, opts) {
+  const options = buildRenderOptions(value, symbology, opts);
+  const bwipjs = await import("bwip-js/browser");
+  return bwipjs.toSVG(options);
+}
+var USE_SVG_INSTEAD = "Use generateBarcodeSvg() instead \u2014 SVG renders identically, works in Node and the browser, and prints at the printer's resolution rather than the canvas's.";
+async function generateBarcodeDataUrl(value, symbology, opts) {
+  const options = buildRenderOptions(value, symbology, opts);
+  if (typeof document === "undefined") {
+    throw new Error(`generateBarcodeDataUrl() needs a DOM canvas and cannot run in Node. ${USE_SVG_INSTEAD}`);
+  }
+  const bwipjs = await import("bwip-js/browser");
+  const toCanvas = bwipjs.toCanvas;
+  if (typeof toCanvas !== "function") {
+    throw new Error(
+      `bwip-js resolved to its non-browser build, which has no toCanvas() \u2014 barcode PNG rendering is unavailable in this environment. ${USE_SVG_INSTEAD}`
+    );
+  }
+  let canvas;
+  try {
+    canvas = toCanvas(document.createElement("canvas"), options);
+  } catch (cause) {
+    throw new Error(
+      `This environment's canvas could not render the barcode (${cause instanceof Error ? cause.message : String(cause)}). ${USE_SVG_INSTEAD}`,
+      { cause }
+    );
+  }
+  const dataUrl = canvas.toDataURL("image/png");
+  if (typeof dataUrl !== "string" || !dataUrl.startsWith("data:image/png")) {
+    throw new Error(
+      `This environment's canvas produced no PNG data URL (got ${String(dataUrl)}) \u2014 barcode PNG rendering is unavailable here. ${USE_SVG_INSTEAD}`
+    );
+  }
+  return dataUrl;
+}
+export {
+  DEFAULT_BARCODE_HEIGHT,
+  DEFAULT_BARCODE_SCALE,
+  generateBarcodeDataUrl,
+  generateBarcodeSvg,
+  normalizeBarcodeValue
+};
+//# sourceMappingURL=barcode.js.map

package/dist/barcode.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/barcode.ts"],"sourcesContent":["/**\n * @ai-matrx/print/barcode — 1-D BARCODE GENERATION for retail and warehouse labels.\n *\n * New code (no port source). Scanning/decoding is NOT here. This module only\n * ever turns a value into a linear symbol, in the three symbologies that\n * actually show up on the commerce lane's labels:\n *\n *  - `code128` — the general-purpose workhorse. The `manufacturer_serial`\n *    identifier kind is usually printed as Code 128: arbitrary printable ASCII,\n *    dense, and every warehouse scanner reads it.\n *  - `ean13` / `upca` — retail GTINs. These are NOT free-form strings: they\n *    carry a GS1 mod-10 check digit, and a label printed with the wrong one is\n *    a label that gets rejected at the point of sale.\n *\n * Two rules that are NOT style choices:\n *  - EVERY generate call routes through `normalizeBarcodeValue` first. A caller\n *    that hands us 12 digits gets the check digit APPENDED; a caller that hands\n *    us 13 gets it VERIFIED and throws on a mismatch. There is no path that\n *    prints an unvalidated retail symbol.\n *  - The human-readable line defaults ON (`includeText`). On a retail or\n *    warehouse label the printed digits are the fallback when the scanner\n *    fails, and a keyer at a register cannot read bars.\n *\n * The module is import-inert: `bwip-js` is only ever pulled in via\n * `await import(\"bwip-js\")` inside a function body, so importing this file from\n * a React Server Component (or any bundle that never draws a barcode) costs\n * nothing. No module-level mutable state, no React, no DOM at import time.\n *\n * SVG works EVERYWHERE — bwip-js `toSVG` is pure JS with no canvas dependency,\n * so it is the lane for Node (server-side PDF/label composition) as much as for\n * the browser. The PNG data-URL lane is browser-only by design: it uses\n * bwip-js's canvas rendering rather than dragging `node-canvas` into a package\n * that mostly runs in a print window. In Node it throws and names the fix.\n */\n\n/**\n * We import the \"bwip-js/browser\" SUBPATH rather than the bare \"bwip-js\"\n * specifier, deliberately and for two reasons:\n *  1. bwip-js's export map has no `default` condition — only `browser`, `node`,\n *    `electron` and `react-native` — so a bundler-style TypeScript resolver\n *    cannot resolve the bare specifier at all. The subpath resolves cleanly.\n *  2. The browser build is the SUPERSET for our purposes: its `toSVG` is pure\n *     JS and imports/runs fine under Node (verified — nothing touches `document`\n *     at module scope), and it is the only build that carries `toCanvas`, which\n *     the PNG lane needs. The node build would give us `toBuffer` instead and\n *     no canvas lane at all.\n */\nimport type { RenderOptions } from \"bwip-js/browser\";\n\n// ─── Contract ────────────────────────────────────────────────────────────────\n\n/** The three 1-D symbologies the platform prints. Values are bwip-js `bcid`s verbatim. */\nexport type BarcodeSymbology = \"code128\" | \"ean13\" | \"upca\";\n\nexport interface BarcodeOptions {\n    /**\n     * Bar height. This is bwip-js's `height`, whose unit is MILLIMETRES (it is\n     * not a module count — the name follows the package's option contract).\n     * Defaults per symbology: 12 for Code 128, 22.85 for EAN-13/UPC-A, the GS1\n     * nominal symbol height at 100% magnification.\n     */\n    heightModules?: number;\n    /** Human-readable line under the bars. Default TRUE — it is the fallback when a scan fails. */\n    includeText?: boolean;\n    /** Module width multiplier (bwip-js `scale`). Default 2. */\n    scale?: number;\n}\n\n/** Default module-width multiplier for every Matrx-printed barcode. */\nexport const DEFAULT_BARCODE_SCALE = 2;\n\n/**\n * Default bar height in millimetres, per symbology.\n * 22.85mm is the GS1 nominal EAN-13/UPC-A symbol height at 100% magnification;\n * Code 128 has no spec height, and 12mm is a comfortable warehouse-label bar.\n */\nexport const DEFAULT_BARCODE_HEIGHT: Readonly<Record<BarcodeSymbology, number>> = {\n    code128: 12,\n    ean13: 22.85,\n    upca: 22.85,\n};\n\n/** Digit counts each GS1 symbology accepts: [without check digit, with check digit]. */\nconst GS1_DIGIT_LENGTHS: Readonly<Record<\"ean13\" | \"upca\", readonly [number, number]>> = {\n    ean13: [12, 13],\n    upca: [11, 12],\n};\n\nconst SYMBOLOGIES: readonly BarcodeSymbology[] = [\"code128\", \"ean13\", \"upca\"];\n\nfunction assertSymbology(symbology: BarcodeSymbology): BarcodeSymbology {\n    if (!SYMBOLOGIES.includes(symbology)) {\n        throw new Error(\n            `Unknown barcode symbology \"${String(symbology)}\". Expected one of ${SYMBOLOGIES.map((s) => `\"${s}\"`).join(\", \")}.`,\n        );\n    }\n    return symbology;\n}\n\n// ─── Validation ──────────────────────────────────────────────────────────────\n\n/**\n * GS1 mod-10 check digit over the payload digits (i.e. WITHOUT the check\n * digit): weights 3 and 1 alternating from the right. Length-independent, so\n * UPC-A's 11-digit payload and EAN-13's 12-digit payload use the same routine.\n */\nfunction gs1CheckDigit(payloadDigits: string): number {\n    let sum = 0;\n    let weight = 3;\n    for (let i = payloadDigits.length - 1; i >= 0; i -= 1) {\n        sum += (payloadDigits.charCodeAt(i) - 48) * weight;\n        weight = weight === 3 ? 1 : 3;\n    }\n    return (10 - (sum % 10)) % 10;\n}\n\n/**\n * Code 128 encodes ASCII 0–127, but a label only prints what a human can read\n * back, so we accept the printable range 0x20 (space) through 0x7E (tilde).\n * Control characters and anything non-ASCII (smart quotes pasted from a\n * spreadsheet are the usual culprit) are rejected loudly rather than silently\n * mangled by the encoder.\n */\nfunction normalizeCode128(value: string): string {\n    if (value.length === 0) {\n        throw new Error(\"Code 128 barcode value must be a non-empty string.\");\n    }\n    for (let i = 0; i < value.length; i += 1) {\n        const code = value.charCodeAt(i);\n        if (code < 0x20 || code > 0x7e) {\n            throw new Error(\n                `Code 128 barcode value contains a non-printable-ASCII character ${JSON.stringify(value.charAt(i))} ` +\n                    `at index ${i} (char code ${code}). Only ASCII 0x20-0x7E can be printed and read back by a human.`,\n            );\n        }\n    }\n    return value;\n}\n\nfunction normalizeGs1(value: string, symbology: \"ean13\" | \"upca\"): string {\n    const raw = value.trim();\n    if (raw.length === 0) {\n        throw new Error(`${symbology === \"ean13\" ? \"EAN-13\" : \"UPC-A\"} barcode value must be a non-empty string.`);\n    }\n    if (!/^[0-9]+$/.test(raw)) {\n        throw new Error(\n            `${symbology === \"ean13\" ? \"EAN-13\" : \"UPC-A\"} barcode value \"${raw}\" must contain digits only ` +\n                `(no spaces, dashes, or letters).`,\n        );\n    }\n\n    const lengths = GS1_DIGIT_LENGTHS[symbology];\n    const [withoutCheck, withCheck] = lengths;\n    const label = symbology === \"ean13\" ? \"EAN-13\" : \"UPC-A\";\n\n    if (raw.length === withoutCheck) {\n        // Caller gave us the payload — APPEND the check digit we compute.\n        return `${raw}${gs1CheckDigit(raw)}`;\n    }\n    if (raw.length === withCheck) {\n        // Caller gave us a full code — VERIFY the check digit they already have.\n        const expected = gs1CheckDigit(raw.slice(0, -1));\n        const actual = raw.charCodeAt(raw.length - 1) - 48;\n        if (expected !== actual) {\n            throw new Error(\n                `${label} barcode value \"${raw}\" has an invalid GS1 check digit: expected ${expected}, got ${actual}. ` +\n                    `Pass the first ${withoutCheck} digits instead and the check digit will be computed for you.`,\n            );\n        }\n        return raw;\n    }\n    throw new Error(\n        `${label} barcode value \"${raw}\" must be ${withoutCheck} digits (check digit appended) or ` +\n            `${withCheck} digits (check digit verified), got ${raw.length}.`,\n    );\n}\n\n/**\n * Validate and normalize a value for a symbology, returning the FULL value that\n * will actually be encoded.\n *\n *  - `ean13` / `upca`: digits only. 12 (EAN-13) or 11 (UPC-A) digits get the\n *    GS1 mod-10 check digit APPENDED; 13 or 12 digits get theirs VERIFIED and\n *    throw on a mismatch. Either way the return value is the complete code.\n *  - `code128`: printable ASCII (0x20-0x7E) passes through untouched —\n *    including leading/trailing spaces, which are legal Code 128 data.\n *\n * Throws an Error with a message naming the exact problem. Every generator in\n * this module routes through here first; call it directly when you need to show\n * the normalized value (e.g. the digits under the bars) before printing.\n */\nexport function normalizeBarcodeValue(value: string, symbology: BarcodeSymbology): string {\n    assertSymbology(symbology);\n    if (typeof value !== \"string\") {\n        throw new Error(`Barcode value must be a string, got ${String(value)}.`);\n    }\n    if (symbology === \"code128\") {\n        return normalizeCode128(value);\n    }\n    return normalizeGs1(value, symbology);\n}\n\n// ─── Option resolution ───────────────────────────────────────────────────────\n\nfunction resolveScale(scale: number | undefined): number {\n    if (scale === undefined) return DEFAULT_BARCODE_SCALE;\n    if (typeof scale !== \"number\" || !Number.isFinite(scale) || scale <= 0) {\n        throw new Error(`Barcode scale must be a positive number, got ${String(scale)}.`);\n    }\n    return scale;\n}\n\nfunction resolveHeight(heightModules: number | undefined, symbology: BarcodeSymbology): number {\n    if (heightModules === undefined) return DEFAULT_BARCODE_HEIGHT[symbology];\n    if (typeof heightModules !== \"number\" || !Number.isFinite(heightModules) || heightModules <= 0) {\n        throw new Error(`Barcode heightModules must be a positive number, got ${String(heightModules)}.`);\n    }\n    return heightModules;\n}\n\n/**\n * Build the bwip-js render options. Note the object is fully populated here —\n * under `exactOptionalPropertyTypes` we never assign `undefined` to an optional\n * key, so every field is either a real value or absent.\n */\nfunction buildRenderOptions(value: string, symbology: BarcodeSymbology, opts: BarcodeOptions | undefined): RenderOptions {\n    const normalized = normalizeBarcodeValue(value, symbology);\n    return {\n        bcid: symbology,\n        text: normalized,\n        scale: resolveScale(opts?.scale),\n        height: resolveHeight(opts?.heightModules, symbology),\n        includetext: opts?.includeText === undefined ? true : opts.includeText === true,\n        textxalign: \"center\",\n    };\n}\n\n// ─── Rendering ───────────────────────────────────────────────────────────────\n\n/**\n * SVG markup string — the lane that works EVERYWHERE (Node and browser), since\n * bwip-js `toSVG` is pure JS with no canvas dependency. Lazy-imports `bwip-js`\n * at call time, so this module stays import-inert.\n *\n * The value is validated and normalized first; a bad GS1 check digit throws\n * here rather than printing a label nobody can sell.\n */\nexport async function generateBarcodeSvg(\n    value: string,\n    symbology: BarcodeSymbology,\n    opts?: BarcodeOptions,\n): Promise<string> {\n    const options = buildRenderOptions(value, symbology, opts);\n    const bwipjs = await import(\"bwip-js/browser\");\n    return bwipjs.toSVG(options);\n}\n\n/**\n * `toCanvas` only exists in bwip-js's browser build (the node build ships\n * `toBuffer` instead), so even on the browser subpath we PROBE for it rather\n * than assume which condition a host bundler ultimately resolved.\n */\ninterface BwipCanvasLane {\n    toCanvas?: (canvas: HTMLCanvasElement, opts: RenderOptions) => HTMLCanvasElement;\n}\n\nconst USE_SVG_INSTEAD =\n    \"Use generateBarcodeSvg() instead — SVG renders identically, works in Node and the browser, \" +\n    \"and prints at the printer's resolution rather than the canvas's.\";\n\n/**\n * PNG data URL, for embedding straight into a print window's `<img src>`.\n *\n * BROWSER ONLY. In Node this throws immediately and names the fix rather than\n * dragging `node-canvas` (a native build) into a package that mostly runs in a\n * print window. The same clear error is thrown in a DOM environment whose\n * canvas is a stub (jsdom without the optional `canvas` package returns `null`\n * from `toDataURL`) — we would rather fail loudly than hand back a broken\n * `src` that silently renders as a missing image.\n */\nexport async function generateBarcodeDataUrl(\n    value: string,\n    symbology: BarcodeSymbology,\n    opts?: BarcodeOptions,\n): Promise<string> {\n    const options = buildRenderOptions(value, symbology, opts);\n\n    if (typeof document === \"undefined\") {\n        throw new Error(`generateBarcodeDataUrl() needs a DOM canvas and cannot run in Node. ${USE_SVG_INSTEAD}`);\n    }\n\n    const bwipjs = (await import(\"bwip-js/browser\")) as unknown as BwipCanvasLane;\n    const toCanvas = bwipjs.toCanvas;\n    if (typeof toCanvas !== \"function\") {\n        throw new Error(\n            `bwip-js resolved to its non-browser build, which has no toCanvas() — barcode PNG rendering is ` +\n                `unavailable in this environment. ${USE_SVG_INSTEAD}`,\n        );\n    }\n\n    let canvas: HTMLCanvasElement;\n    try {\n        canvas = toCanvas(document.createElement(\"canvas\"), options);\n    } catch (cause) {\n        // A DOM without a real 2-D context (jsdom without the optional `canvas`\n        // package is the common one) fails somewhere inside bwip-js's drawing\n        // code. Re-throw with the fix instead of a stray TypeError.\n        throw new Error(\n            `This environment's canvas could not render the barcode (${cause instanceof Error ? cause.message : String(cause)}). ` +\n                `${USE_SVG_INSTEAD}`,\n            { cause },\n        );\n    }\n    const dataUrl: unknown = canvas.toDataURL(\"image/png\");\n    if (typeof dataUrl !== \"string\" || !dataUrl.startsWith(\"data:image/png\")) {\n        throw new Error(\n            `This environment's canvas produced no PNG data URL (got ${String(dataUrl)}) — barcode PNG rendering ` +\n                `is unavailable here. ${USE_SVG_INSTEAD}`,\n        );\n    }\n    return dataUrl;\n}\n"],"mappings":"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","names":[]}