@ai-matrx/print 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.1.0 — 2026-08-29
+
+First release. Extracted from the AI Matrx frontend's print system with
+behavior-verbatim ports; only coupling seams were inverted (structural types,
+injected markdown converter, bundled dialog primitives).
+
+- **/core** — the `BlockPrinter` contract (boolean/range/number/select
+  settings), `buildPrintDocument` / `openPrintWindow` (popup-blocked → .html
+  download fallback) / `printHtmlContent` / `escapeHtml`, and
+  `buildFitTextScript` (the shared in-window auto-shrink loop).
+- **/qr** — QR generation: PNG data URL + SVG lanes (lazy `qrcode`), ECC
+  default **M**, quiet zone clamped to the ISO minimum of 4 modules, symbol
+  math (`minQrVersion`, `qrModuleCount`, `qrByteCapacity` — byte-mode
+  capacity table verified against the reference encoder), and payload
+  builders: `buildShortResolverUrl` (opaque server-minted codes) and
+  `buildGs1DigitalLink` (GTIN check-digit validation; AI 17 as a query
+  attribute).
+- **/labels** — the label engine: template registry (Avery 5160/8160,
+  5163/8163, 5164/8164, 22806, 22807 + custom), NEW roll formats
+  (Brother DK-1202/DK-11201, DYMO 30252, 4×6″ thermal), `startAtLabel` /
+  `copiesPerCode` / ranges / EC select, 300 dpi inlined data-URI QRs with
+  spec quiet zones, `print-color-adjust: exact`, calibration sheets, jsPDF
+  download lane, NEW `LabelFormat` custom-format model (`qr`/`text` with
+  title/detail/badge roles/`image` elements; presets `qr-only`, `qr-caption`,
+  `garment`, `asset-spec`; `badge` renders large in all lanes), and NEW
+  `assertScannable` (module-density validator wired into the print/PDF lanes
+  as a non-blocking warning).
+- **/flashcards** — the deck printer, all 10 variants (portrait 6-up +
+  landscape 4-up duplex-mirrored/stacked, Avery 5388, cut-cards, both-sides,
+  study-sheet, front-only, back-only) with card ranges, cut guides, and
+  show-through countermeasures. Face images print from durable URLs only.
+- **/pdf** — DOM-capture → PDF (html2canvas + jsPDF, lazy), the oklch/lab
+  `getComputedStyle` compatibility patch, paginated and continuous lanes,
+  Blob variants, `markdownToPdfBlob(markdown, { convertToHtml, loadCss })`
+  with the converter injected.
+- **/react** — `PrintOptionsDialog` (+ `usePrintOptions`) over bundled Radix
+  dialog / vaul drawer with inlined icons, and `LabelSheetPreview`.
+
+Deliberate divergences from the originals (defects fixed in the port — the
+originals die at the adoption swap):
+
+- flashcards: the "all fronts, then all backs" stacked variants actually
+  interleaved front/back pages per batch on decks larger than one page;
+  they now match their documented behavior.
+- pdf: `patchGetComputedStyle` permanently stacked a `.bind` wrapper per
+  capture instead of restoring the original function; `captureToPDF` ignored
+  `imageFormat`/`imageQuality`; `captureToClipboardImage` resolved before its
+  clipboard/download work finished.
+- labels: the Avery 22806/22807 rows did not tile the sheet (labels drifted
+  0.375″ per column off the die-cut) — corrected to Avery's published 2.75″
+  pitch; `customLabelTemplate` let an explicit `undefined` clobber its
+  defaults; the template registry is now immutable; the dev-time geometry
+  check no longer reads `process.env` bare (which would throw in browser
+  consumers).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @ai-matrx/print
+
+The AI Matrx print system — everything a browser app needs to turn structured
+content into paper: a tiny print contract, print-window composition, QR
+generation with e-commerce payload builders, label-sheet printing on Avery and
+roll stock with custom label formats, a full flashcard deck printer, and
+DOM-capture/markdown → PDF.
+
+Every entry is import-inert and safe to import during SSR — browser APIs are
+touched only when you call something. `/react` is the only React entry (a
+client component entry); everything else is framework-free.
+
+## Install
+
+```bash
+npm install @ai-matrx/print
+```
+
+React ≥18 is an optional peer, needed only for `@ai-matrx/print/react`.
+
+## Entries
+
+### `@ai-matrx/print` — types only
+
+`BlockPrinter`, `PrintVariant`, `PrintSetting`, `PrintSettings`,
+`LabelTemplate`, `LabelFormat`, `QrEcLevel`, `Flashcard`, … — the shared
+vocabulary, no runtime.
+
+### `@ai-matrx/print/core` — the print contract & window composition
+
+```ts
+import { buildPrintDocument, openPrintWindow, printHtmlContent, escapeHtml, buildFitTextScript } from "@ai-matrx/print/core";
+
+printHtmlContent("<h1>Report</h1><table>…</table>", "Q3 Report");
+```
+
+`BlockPrinter` is the one interface a host needs: `label`, `variants`,
+optional `settings` (boolean / range / number / select), and
+`print(data, variantId, settings)`. `openPrintWindow` opens a styled window
+with Print / Close actions and falls back to an `.html` download when the
+popup is blocked. `buildFitTextScript(selectors)` returns the in-window
+auto-shrink script (0.5pt steps, 6pt floor) used by the flashcards engine.
+
+### `@ai-matrx/print/qr` — QR generation (not decoding)
+
+```ts
+import { generateQrDataUrl, generateQrSvg, minQrVersion, buildShortResolverUrl, buildGs1DigitalLink } from "@ai-matrx/print/qr";
+
+const url = buildShortResolverUrl({ origin: "https://yourbrand.com", code: "a1B2c3" }); // https://yourbrand.com/l/a1B2c3
+const png = await generateQrDataUrl(url);              // ECC "M", ≥4-module quiet zone — both enforced defaults
+const gs1 = buildGs1DigitalLink({ origin: "https://id.yourbrand.com", gtin: "4006381333931", lot: "L42", serial: "S1001", expiry: "271231" });
+```
+
+Error correction defaults to **M** (never L — scuffed labels need margin) and
+the quiet zone is clamped to the ISO minimum of 4 modules. The code value in
+`buildShortResolverUrl` is an opaque input — mint identities server-side.
+`minQrVersion(byteLen, ecc)` / `qrModuleCount(version)` /
+`qrByteCapacity(version, ecc)` expose the symbol math (byte-mode capacities
+verified against the reference encoder).
+
+### `@ai-matrx/print/labels` — label sheets, roll stock, custom formats
+
+```ts
+import { qrLabelsPrinter, printQrLabelSheet, downloadLabelsPdf, printCalibrationSheet, applyLabelFormat, LABEL_FORMAT_PRESETS, assertScannable, getLabelTemplate } from "@ai-matrx/print/labels";
+
+// One data shape, three lanes: print window, PDF download, calibration page.
+const data = applyLabelFormat(
+  LABEL_FORMAT_PRESETS.find((f) => f.id === "garment")!,
+  [{ qrValue: "https://yourbrand.com/l/a1B2c3", size: "XL", sku: "TS-001", color: "Black", price: "$29" }],
+);
+await printQrLabelSheet({ ...data, templateId: "avery-5160" });
+```
+
+Built-in templates: Avery 5160/8160, 5163/8163, 5164/8164, 22806 (2″ square),
+22807 (2″ round), plus roll stock — Brother DK-1202 / DK-11201, DYMO 30252,
+and generic 4×6″ thermal (`kind: "roll"`). Custom stock is just data via
+`customLabelTemplate(geometry)`; a dev-time assertion proves every template
+tiles its sheet. Settings include `startAtLabel` (reuse a partially-used
+sheet), `copiesPerCode`, label ranges, and EC level (default M).
+
+`LabelFormat` describes a label as ordered elements — `qr`, `text` with a
+`title` / `detail` / `badge` role, `image` (durable http(s) URLs only) — so
+clients can define their own layouts as data. Presets: `qr-only`,
+`qr-caption`, `garment`, `asset-spec`.
+
+`assertScannable(template, payloadByteLen, ecc)` warns before anyone prints a
+payload too dense for the stock (module size below the ~0.4 mm thermal floor);
+the print lane surfaces it as an on-screen banner automatically.
+
+Print fidelity: QRs are inlined data URIs rasterized at 300 dpi (a print
+window is a fresh, unauthenticated document — nothing is fetched),
+`print-color-adjust: exact`, inch-exact `@page` geometry, and a
+print-on-plain-paper calibration sheet per template. Print at 100% scale with
+no margins.
+
+### `@ai-matrx/print/flashcards` — the deck printer
+
+```ts
+import { flashcardsPrinter } from "@ai-matrx/print/flashcards";
+
+flashcardsPrinter.print({ title: "Biology 101", cards }, "portrait-6up-duplex", { showCutLines: true });
+```
+
+Ten variants: portrait 6-up and landscape 4-up (each duplex-mirrored — backs
+column-swapped so long-edge duplex aligns perfectly — or stacked
+all-fronts-then-all-backs), Avery 5388 index cards, cut-out cards, both-sides,
+study-sheet table, questions-only self-test, answers-only. Settings: card
+ranges, cut tick marks / full cut lines, side labels, card numbers, and
+show-through countermeasures (gray back text, mirrored back text). Face
+images print from durable URLs only.
+
+### `@ai-matrx/print/pdf` — DOM capture & markdown → PDF
+
+```ts
+import { captureToPDF, captureElementsToPDF, markdownToPdfBlob } from "@ai-matrx/print/pdf";
+
+await captureToPDF(document.getElementById("report")!, { filename: "report", orientation: "landscape" });
+const blob = await markdownToPdfBlob(markdown, { convertToHtml, loadCss }); // bring your own converter + stylesheet
+```
+
+html2canvas + jsPDF, lazy-loaded on use. Handles the Tailwind v4 problem
+(oklch/lab colors html2canvas can't parse) via a scoped `getComputedStyle`
+patch that is always restored. `captureElementsToPDF` renders deliberately
+paginated report pages one-per-PDF-page; the single-element lane slices one
+tall canvas across pages.
+
+### `@ai-matrx/print/react` — the options dialog & sheet preview
+
+```ts
+import { PrintOptionsDialog, usePrintOptions, LabelSheetPreview } from "@ai-matrx/print/react";
+```
+
+`PrintOptionsDialog` renders any `BlockPrinter`'s variants + settings
+(desktop dialog, mobile bottom drawer) and runs the print.
+`LabelSheetPreview` shows a scaled, exact-proportion preview of a label sheet,
+with a calibration outline mode. Tailwind CSS classes; Radix dialog + vaul
+drawer are bundled dependencies.
+
+## License
+
+MIT

package/dist/core.cjs

@@ -0,0 +1,184 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core.ts
+var core_exports = {};
+__export(core_exports, {
+  buildFitTextScript: () => buildFitTextScript,
+  buildPrintDocument: () => buildPrintDocument,
+  escapeHtml: () => escapeHtml,
+  openPrintWindow: () => openPrintWindow,
+  printHtmlContent: () => printHtmlContent
+});
+module.exports = __toCommonJS(core_exports);
+var PRINT_STYLES = `
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Helvetica Neue', Arial, sans-serif;
+    font-size: 11pt;
+    line-height: 1.6;
+    color: #1a1a1a;
+    background: #fff;
+    max-width: 860px;
+    margin: 0 auto;
+    padding: 28px 36px;
+  }
+
+  .print-actions {
+    display: flex;
+    gap: 10px;
+    margin-bottom: 24px;
+    padding-bottom: 18px;
+    border-bottom: 2px solid #e5e7eb;
+  }
+
+  .print-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 8px 20px;
+    border-radius: 8px;
+    font-size: 13px;
+    font-family: inherit;
+    cursor: pointer;
+    border: none;
+    font-weight: 600;
+  }
+
+  .print-btn-primary { background: #2563eb; color: #fff; }
+  .print-btn-secondary { background: #f3f4f6; color: #374151; border: 1px solid #d1d5db; }
+
+  h1 { font-size: 22pt; font-weight: 700; margin-bottom: 0.5em; }
+  h2 { font-size: 16pt; font-weight: 700; margin: 1.2em 0 0.4em; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.2em; }
+  h3 { font-size: 13pt; font-weight: 600; margin: 1em 0 0.3em; }
+  p  { margin-bottom: 0.7em; }
+
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 1em 0;
+    font-size: 10pt;
+  }
+  th {
+    background: #1e293b;
+    color: #f8fafc;
+    font-weight: 600;
+    text-align: left;
+    padding: 7px 12px;
+    border: 1px solid #334155;
+  }
+  td {
+    padding: 6px 12px;
+    border: 1px solid #e2e8f0;
+    vertical-align: top;
+  }
+  tr:nth-child(even) td { background: #f8fafc; }
+
+  @media print {
+    body { max-width: 100%; padding: 0; }
+    .print-actions { display: none !important; }
+    th { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+  }
+`;
+function escapeHtml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function buildPrintDocument(bodyHtml, title = "AI Response", extraStyles = "") {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+  <style>
+${PRINT_STYLES}
+${extraStyles}
+  </style>
+</head>
+<body>
+  <div class="print-actions">
+    <button class="print-btn print-btn-primary" onclick="window.print()">Print / Save as PDF</button>
+    <button class="print-btn print-btn-secondary" onclick="window.close()">Close</button>
+  </div>
+  <div class="content">
+${bodyHtml}
+  </div>
+</body>
+</html>`;
+}
+function openPrintWindow(htmlDocument, filename = "print") {
+  const win = window.open("", "_blank", "width=920,height=720,scrollbars=yes");
+  if (!win) {
+    const blob = new Blob([htmlDocument], { type: "text/html;charset=utf-8" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${filename.replace(/\s+/g, "-").toLowerCase()}.html`;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+    return;
+  }
+  win.document.open();
+  win.document.write(htmlDocument);
+  win.document.close();
+}
+function printHtmlContent(bodyHtml, title = "AI Response", extraStyles = "") {
+  const doc = buildPrintDocument(bodyHtml, title, extraStyles);
+  openPrintWindow(doc, title);
+}
+function buildFitTextScript(selectors) {
+  const selectorsJson = JSON.stringify([...selectors]);
+  return `
+<script>
+(function() {
+  function fitText(el, container) {
+    // container is the bounding box we must fit inside
+    var maxW = container.clientWidth;
+    var maxH = container.clientHeight;
+    var size = parseFloat(window.getComputedStyle(el).fontSize);
+    var minSize = 6;
+    // Give the element a chance to reflow at current size before measuring
+    el.style.fontSize = size + "pt";
+    while (size > minSize && (el.scrollWidth > maxW + 1 || el.scrollHeight > maxH + 1)) {
+      size -= 0.5;
+      el.style.fontSize = size + "pt";
+    }
+  }
+  function runAll() {
+    var selectors = ${selectorsJson};
+    for (var s = 0; s < selectors.length; s++) {
+      var els = document.querySelectorAll(selectors[s]);
+      for (var i = 0; i < els.length; i++) {
+        fitText(els[i], els[i].parentElement);
+      }
+    }
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", runAll);
+  } else {
+    // document.write pages may already be loaded
+    setTimeout(runAll, 0);
+  }
+})();
+<\/script>`;
+}
+//# sourceMappingURL=core.cjs.map

package/dist/core.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts"],"sourcesContent":["/**\n * @ai-matrx/print/core — the Block Print contract & print-window composition.\n *\n * Ported VERBATIM from matrx-frontend `lib/block-print/block-print-utils.ts`\n * (2026-08-29 state, including the `number` and `select` PrintSetting types the\n * commerce label lane added). Zero dependencies; touches `window` only at call\n * time, so the module stays import-inert and RSC-safe.\n *\n * BlockPrinter is the only interface a host system needs to know about.\n * Each printable unit exports its own BlockPrinter alongside its render\n * component; host code only ever calls print(data, variantId, settings).\n *\n * `buildFitTextScript` is the ONE auto-shrink script (the flashcards\n * FIT_TEXT pattern, parameterized by selector so the label lane shares it).\n */\n\n// ─── Contract ────────────────────────────────────────────────────────────────\n\nexport interface PrintVariant {\n  id: string;\n  label: string;\n  description?: string;\n}\n\n/**\n * A single user-configurable setting shown in the print dialog.\n * Extend the discriminated union for new control types\n * without breaking existing printers.\n */\nexport type PrintSetting =\n  | {\n      type: \"boolean\";\n      id: string;\n      label: string;\n      description?: string;\n      /** Default value shown when the dialog first opens */\n      defaultValue: boolean;\n      /** Which variant IDs this setting applies to. Omit = applies to all. */\n      appliesTo?: string[];\n    }\n  | {\n      /**\n       * A numeric \"from → to\" range control, rendered as two small number inputs.\n       * Writes two entries into the resolved PrintSettings map — one under fromId,\n       * one under toId. Printers interpret 0 (or missing) as \"no bound\" by convention.\n       */\n      type: \"range\";\n      /** Stable id used as React key — not written to the settings map */\n      id: string;\n      label: string;\n      description?: string;\n      /** Settings map key for the lower bound value */\n      fromId: string;\n      /** Settings map key for the upper bound value */\n      toId: string;\n      defaultFrom: number;\n      defaultTo: number;\n      /** Minimum accepted value for each input (inclusive). Default 0. */\n      min?: number;\n      /** Placeholder shown when the input is empty (0). Default \"start\" / \"end\". */\n      fromPlaceholder?: string;\n      toPlaceholder?: string;\n      /** Which variant IDs this setting applies to. Omit = applies to all. */\n      appliesTo?: string[];\n    }\n  | {\n      /** A single numeric input (e.g. \"start at label #\", \"copies\"). */\n      type: \"number\";\n      id: string;\n      label: string;\n      description?: string;\n      defaultValue: number;\n      /** Minimum accepted value (inclusive). Default 0. */\n      min?: number;\n      /** Maximum accepted value (inclusive). Omit = unbounded. */\n      max?: number;\n      /** Which variant IDs this setting applies to. Omit = applies to all. */\n      appliesTo?: string[];\n    }\n  | {\n      /** A one-of-N choice rendered as a compact segmented row. */\n      type: \"select\";\n      id: string;\n      label: string;\n      description?: string;\n      options: { value: string; label: string }[];\n      defaultValue: string;\n      /** Which variant IDs this setting applies to. Omit = applies to all. */\n      appliesTo?: string[];\n    };\n\n/** A resolved map of setting id → current value, passed to print(). */\nexport type PrintSettings = Record<string, boolean | string | number>;\n\n/**\n * The self-contained print capability that each block can export.\n * Host code only ever calls print(data, variantId, settings) — it never inspects internals.\n */\nexport interface BlockPrinter {\n  /** Tooltip / aria-label for the print button in the block header */\n  label: string;\n\n  /**\n   * Variants offered to the user before printing.\n   * Empty array = no options dialog shown; prints immediately with defaults.\n   */\n  variants: PrintVariant[];\n\n  /**\n   * Optional user-configurable settings shown below the variant picker.\n   * Omit entirely if the block has no configurable settings.\n   */\n  settings?: PrintSetting[];\n\n  /**\n   * Execute the print.\n   * data      — the block's structured data (serverData or parsed content)\n   * variantId — which variant was chosen (undefined = default / no variants)\n   * settings  — resolved setting values chosen by the user\n   */\n  print: (\n    data: unknown,\n    variantId?: string,\n    settings?: PrintSettings,\n  ) => void | Promise<void>;\n}\n\n// ─── Shared Utilities ─────────────────────────────────────────────────────────\n\nconst PRINT_STYLES = `\n  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }\n\n  body {\n    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Helvetica Neue', Arial, sans-serif;\n    font-size: 11pt;\n    line-height: 1.6;\n    color: #1a1a1a;\n    background: #fff;\n    max-width: 860px;\n    margin: 0 auto;\n    padding: 28px 36px;\n  }\n\n  .print-actions {\n    display: flex;\n    gap: 10px;\n    margin-bottom: 24px;\n    padding-bottom: 18px;\n    border-bottom: 2px solid #e5e7eb;\n  }\n\n  .print-btn {\n    display: inline-flex;\n    align-items: center;\n    gap: 6px;\n    padding: 8px 20px;\n    border-radius: 8px;\n    font-size: 13px;\n    font-family: inherit;\n    cursor: pointer;\n    border: none;\n    font-weight: 600;\n  }\n\n  .print-btn-primary { background: #2563eb; color: #fff; }\n  .print-btn-secondary { background: #f3f4f6; color: #374151; border: 1px solid #d1d5db; }\n\n  h1 { font-size: 22pt; font-weight: 700; margin-bottom: 0.5em; }\n  h2 { font-size: 16pt; font-weight: 700; margin: 1.2em 0 0.4em; border-bottom: 1px solid #e5e7eb; padding-bottom: 0.2em; }\n  h3 { font-size: 13pt; font-weight: 600; margin: 1em 0 0.3em; }\n  p  { margin-bottom: 0.7em; }\n\n  table {\n    width: 100%;\n    border-collapse: collapse;\n    margin: 1em 0;\n    font-size: 10pt;\n  }\n  th {\n    background: #1e293b;\n    color: #f8fafc;\n    font-weight: 600;\n    text-align: left;\n    padding: 7px 12px;\n    border: 1px solid #334155;\n  }\n  td {\n    padding: 6px 12px;\n    border: 1px solid #e2e8f0;\n    vertical-align: top;\n  }\n  tr:nth-child(even) td { background: #f8fafc; }\n\n  @media print {\n    body { max-width: 100%; padding: 0; }\n    .print-actions { display: none !important; }\n    th { -webkit-print-color-adjust: exact; print-color-adjust: exact; }\n  }\n`;\n\nfunction escapeHtml(str: string): string {\n  return str\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\")\n    .replace(/'/g, \"&#39;\");\n}\n\n/**\n * Wrap body HTML in a complete, styled print document.\n */\nexport function buildPrintDocument(\n  bodyHtml: string,\n  title = \"AI Response\",\n  extraStyles = \"\",\n): string {\n  return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <title>${escapeHtml(title)}</title>\n  <style>\n${PRINT_STYLES}\n${extraStyles}\n  </style>\n</head>\n<body>\n  <div class=\"print-actions\">\n    <button class=\"print-btn print-btn-primary\" onclick=\"window.print()\">Print / Save as PDF</button>\n    <button class=\"print-btn print-btn-secondary\" onclick=\"window.close()\">Close</button>\n  </div>\n  <div class=\"content\">\n${bodyHtml}\n  </div>\n</body>\n</html>`;\n}\n\n/**\n * Open a new browser window and write a complete HTML document into it.\n * Falls back to downloading an .html file if the popup is blocked.\n */\nexport function openPrintWindow(\n  htmlDocument: string,\n  filename = \"print\",\n): void {\n  const win = window.open(\"\", \"_blank\", \"width=920,height=720,scrollbars=yes\");\n  if (!win) {\n    // Popup blocked — fall back to file download\n    const blob = new Blob([htmlDocument], { type: \"text/html;charset=utf-8\" });\n    const url = URL.createObjectURL(blob);\n    const a = document.createElement(\"a\");\n    a.href = url;\n    a.download = `${filename.replace(/\\s+/g, \"-\").toLowerCase()}.html`;\n    document.body.appendChild(a);\n    a.click();\n    document.body.removeChild(a);\n    URL.revokeObjectURL(url);\n    return;\n  }\n  win.document.open();\n  win.document.write(htmlDocument);\n  win.document.close();\n}\n\n/**\n * Shorthand: build the document and open it in one call.\n */\nexport function printHtmlContent(\n  bodyHtml: string,\n  title = \"AI Response\",\n  extraStyles = \"\",\n): void {\n  const doc = buildPrintDocument(bodyHtml, title, extraStyles);\n  openPrintWindow(doc, title);\n}\n\n/**\n * Build the auto-shrink script that runs INSIDE a printed window: for every\n * element matching each selector, its font-size is reduced (0.5pt steps, 6pt\n * floor) until it fits its parent element's box. This is the flashcards\n * FIT_TEXT behavior verbatim, parameterized by selector so every lane\n * (flashcards card text, Avery text, label captions) shares the ONE loop.\n *\n * Pass the same selectors the original used to get byte-identical behavior:\n * flashcards passes `[\".card-text .card-text-inner\", \".avery-text-wrap .avery-text\"]`.\n */\nexport function buildFitTextScript(selectors: readonly string[]): string {\n  const selectorsJson = JSON.stringify([...selectors]);\n  return `\n<script>\n(function() {\n  function fitText(el, container) {\n    // container is the bounding box we must fit inside\n    var maxW = container.clientWidth;\n    var maxH = container.clientHeight;\n    var size = parseFloat(window.getComputedStyle(el).fontSize);\n    var minSize = 6;\n    // Give the element a chance to reflow at current size before measuring\n    el.style.fontSize = size + \"pt\";\n    while (size > minSize && (el.scrollWidth > maxW + 1 || el.scrollHeight > maxH + 1)) {\n      size -= 0.5;\n      el.style.fontSize = size + \"pt\";\n    }\n  }\n  function runAll() {\n    var selectors = ${selectorsJson};\n    for (var s = 0; s < selectors.length; s++) {\n      var els = document.querySelectorAll(selectors[s]);\n      for (var i = 0; i < els.length; i++) {\n        fitText(els[i], els[i].parentElement);\n      }\n    }\n  }\n  if (document.readyState === \"loading\") {\n    document.addEventListener(\"DOMContentLoaded\", runAll);\n  } else {\n    // document.write pages may already be loaded\n    setTimeout(runAll, 0);\n  }\n})();\n</script>`;\n}\n\nexport { escapeHtml };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiIA,IAAM,eAAe;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuErB,SAAS,WAAW,KAAqB;AACvC,SAAO,IACJ,QAAQ,MAAM,OAAO,EACrB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,QAAQ,EACtB,QAAQ,MAAM,OAAO;AAC1B;AAKO,SAAS,mBACd,UACA,QAAQ,eACR,cAAc,IACN;AACR,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA,WAKE,WAAW,KAAK,CAAC;AAAA;AAAA,EAE1B,YAAY;AAAA,EACZ,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASX,QAAQ;AAAA;AAAA;AAAA;AAIV;AAMO,SAAS,gBACd,cACA,WAAW,SACL;AACN,QAAM,MAAM,OAAO,KAAK,IAAI,UAAU,qCAAqC;AAC3E,MAAI,CAAC,KAAK;AAER,UAAM,OAAO,IAAI,KAAK,CAAC,YAAY,GAAG,EAAE,MAAM,0BAA0B,CAAC;AACzE,UAAM,MAAM,IAAI,gBAAgB,IAAI;AACpC,UAAM,IAAI,SAAS,cAAc,GAAG;AACpC,MAAE,OAAO;AACT,MAAE,WAAW,GAAG,SAAS,QAAQ,QAAQ,GAAG,EAAE,YAAY,CAAC;AAC3D,aAAS,KAAK,YAAY,CAAC;AAC3B,MAAE,MAAM;AACR,aAAS,KAAK,YAAY,CAAC;AAC3B,QAAI,gBAAgB,GAAG;AACvB;AAAA,EACF;AACA,MAAI,SAAS,KAAK;AAClB,MAAI,SAAS,MAAM,YAAY;AAC/B,MAAI,SAAS,MAAM;AACrB;AAKO,SAAS,iBACd,UACA,QAAQ,eACR,cAAc,IACR;AACN,QAAM,MAAM,mBAAmB,UAAU,OAAO,WAAW;AAC3D,kBAAgB,KAAK,KAAK;AAC5B;AAYO,SAAS,mBAAmB,WAAsC;AACvE,QAAM,gBAAgB,KAAK,UAAU,CAAC,GAAG,SAAS,CAAC;AACnD,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAiBa,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBnC;","names":[]}

package/dist/core.d.cts

@@ -0,0 +1,139 @@
+/**
+ * @ai-matrx/print/core — the Block Print contract & print-window composition.
+ *
+ * Ported VERBATIM from matrx-frontend `lib/block-print/block-print-utils.ts`
+ * (2026-08-29 state, including the `number` and `select` PrintSetting types the
+ * commerce label lane added). Zero dependencies; touches `window` only at call
+ * time, so the module stays import-inert and RSC-safe.
+ *
+ * BlockPrinter is the only interface a host system needs to know about.
+ * Each printable unit exports its own BlockPrinter alongside its render
+ * component; host code only ever calls print(data, variantId, settings).
+ *
+ * `buildFitTextScript` is the ONE auto-shrink script (the flashcards
+ * FIT_TEXT pattern, parameterized by selector so the label lane shares it).
+ */
+interface PrintVariant {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * A single user-configurable setting shown in the print dialog.
+ * Extend the discriminated union for new control types
+ * without breaking existing printers.
+ */
+type PrintSetting = {
+    type: "boolean";
+    id: string;
+    label: string;
+    description?: string;
+    /** Default value shown when the dialog first opens */
+    defaultValue: boolean;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /**
+     * A numeric "from → to" range control, rendered as two small number inputs.
+     * Writes two entries into the resolved PrintSettings map — one under fromId,
+     * one under toId. Printers interpret 0 (or missing) as "no bound" by convention.
+     */
+    type: "range";
+    /** Stable id used as React key — not written to the settings map */
+    id: string;
+    label: string;
+    description?: string;
+    /** Settings map key for the lower bound value */
+    fromId: string;
+    /** Settings map key for the upper bound value */
+    toId: string;
+    defaultFrom: number;
+    defaultTo: number;
+    /** Minimum accepted value for each input (inclusive). Default 0. */
+    min?: number;
+    /** Placeholder shown when the input is empty (0). Default "start" / "end". */
+    fromPlaceholder?: string;
+    toPlaceholder?: string;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /** A single numeric input (e.g. "start at label #", "copies"). */
+    type: "number";
+    id: string;
+    label: string;
+    description?: string;
+    defaultValue: number;
+    /** Minimum accepted value (inclusive). Default 0. */
+    min?: number;
+    /** Maximum accepted value (inclusive). Omit = unbounded. */
+    max?: number;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /** A one-of-N choice rendered as a compact segmented row. */
+    type: "select";
+    id: string;
+    label: string;
+    description?: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    defaultValue: string;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+};
+/** A resolved map of setting id → current value, passed to print(). */
+type PrintSettings = Record<string, boolean | string | number>;
+/**
+ * The self-contained print capability that each block can export.
+ * Host code only ever calls print(data, variantId, settings) — it never inspects internals.
+ */
+interface BlockPrinter {
+    /** Tooltip / aria-label for the print button in the block header */
+    label: string;
+    /**
+     * Variants offered to the user before printing.
+     * Empty array = no options dialog shown; prints immediately with defaults.
+     */
+    variants: PrintVariant[];
+    /**
+     * Optional user-configurable settings shown below the variant picker.
+     * Omit entirely if the block has no configurable settings.
+     */
+    settings?: PrintSetting[];
+    /**
+     * Execute the print.
+     * data      — the block's structured data (serverData or parsed content)
+     * variantId — which variant was chosen (undefined = default / no variants)
+     * settings  — resolved setting values chosen by the user
+     */
+    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | Promise<void>;
+}
+declare function escapeHtml(str: string): string;
+/**
+ * Wrap body HTML in a complete, styled print document.
+ */
+declare function buildPrintDocument(bodyHtml: string, title?: string, extraStyles?: string): string;
+/**
+ * Open a new browser window and write a complete HTML document into it.
+ * Falls back to downloading an .html file if the popup is blocked.
+ */
+declare function openPrintWindow(htmlDocument: string, filename?: string): void;
+/**
+ * Shorthand: build the document and open it in one call.
+ */
+declare function printHtmlContent(bodyHtml: string, title?: string, extraStyles?: string): void;
+/**
+ * Build the auto-shrink script that runs INSIDE a printed window: for every
+ * element matching each selector, its font-size is reduced (0.5pt steps, 6pt
+ * floor) until it fits its parent element's box. This is the flashcards
+ * FIT_TEXT behavior verbatim, parameterized by selector so every lane
+ * (flashcards card text, Avery text, label captions) shares the ONE loop.
+ *
+ * Pass the same selectors the original used to get byte-identical behavior:
+ * flashcards passes `[".card-text .card-text-inner", ".avery-text-wrap .avery-text"]`.
+ */
+declare function buildFitTextScript(selectors: readonly string[]): string;
+
+export { type BlockPrinter, type PrintSetting, type PrintSettings, type PrintVariant, buildFitTextScript, buildPrintDocument, escapeHtml, openPrintWindow, printHtmlContent };