@ai-matrx/print 0.2.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.3.1 — 2026-08-30
+
+Release-only successor to 0.3.0. The 0.3.0 tagged workflow was rejected before
+package verification because its monorepo lockfile did not match a concurrently
+landed sibling manifest. No 0.3.0 artifact reached npm. This version carries the
+same `/markdown` capability from a source graph whose frozen workspace install
+passes, preserving the immutable-tag release boundary.
+
+## 0.3.0 — 2026-08-30
+
+**The BYO-converter seam is gone.** `markdownToPdfBlob` used to declare its
+markdown→HTML converter and its stylesheet as REQUIRED injected ports —
+"bring your own converter + stylesheet". That is exactly the failure THE
+ALL-INCLUSIVE LAW names: the package shipped the easy half and left the hard
+half to every host. Both ports now ship a complete working default; the
+injection seam survives as the OVERRIDE path.
+
+- **NEW `/markdown` entry** — the shipped defaults:
+  - `markdownToHtml` — the full `.matrx-*` converter (headings, emphasis,
+    nested lists at any depth, markdown tables, images, links with underscores,
+    code fences, blockquotes, intro-paragraph and FAQ promotion,
+    `<flashcards>` blocks).
+  - `markdownToArticleHtml` — bare semantic tags for the print-window look;
+    code fences are HTML-escaped (a print window does not re-escape).
+  - `removeThinkingContent` / `hasThinkingContent` — strips `<thinking>`,
+    `<think>` AND `<reasoning>`.
+  - `MARKDOWN_DOCUMENT_CSS` / `MARKDOWN_ARTICLE_CSS` + their token sheets, and
+    `getMarkdownStylesheet({ skin, tokens, extraCss })`.
+  - `renderMarkdownDocument` — markdown → a complete standalone HTML page.
+  - `printMarkdown` — markdown → print window in one call, returning the
+    `PrintOutcome` so a popup-blocked download is still announced.
+- **`markdownToPdfBlob(markdown)` now works with no second argument.**
+  `MarkdownPdfDeps` is all-optional and gains `skin`, `tokens`, `onNotice`,
+  `imageTimeoutMs`. Overriding one port leaves the other on its default.
+- **C26 styling** — every colour in both shipped sheets is
+  `var(--matrx-print-<role>, <default>)` over one role vocabulary; the inline
+  fallbacks make the drop-in test pass unthemed and `tokens` is appended last
+  so a host's brand wins. A test proves zero hardcoded colours survive and that
+  the token sheet defines exactly the roles the CSS consumes.
+- **Defect found in the ported original, fixed here** — the document
+  stylesheet had NO print rules at all: it was authored as a WordPress *screen*
+  sheet and then reused for PDF/print, so tables and code blocks split across
+  page boundaries, headings stranded at page bottoms, and coloured chrome
+  dropped out. It now carries `@media print` with page-break avoidance,
+  orphans/widows and `print-color-adjust: exact`.
+- **Nothing fails silently (C22)** — a flashcard missing `Front:`/`Back:` was
+  dropped without a word; markdown that converts to an empty document produced
+  a blank PDF; an image that 404s or never loads is painted as a blank
+  rectangle by html2canvas with no error anywhere; a rasterization failure
+  surfaced as a raw html2canvas message. All four now report with a remedy —
+  through `onNotice`, or `console.warn` when no sink is supplied. Images are
+  awaited before capture (`imageTimeoutMs`, default 8000).
+- **Bundle** — the defaults sit behind a lazy
+  `import("@ai-matrx/print/markdown")`, and tsup now treats the package's own
+  subpaths as `external` (with `splitting: false` a relative dynamic import is
+  inlined and the lazy edge silently disappears — measured: `dist/pdf.js` fell
+  from 54.7KB to 12.7KB once the edge was real). A DOM-capture-only consumer
+  pays nothing for the stylesheets.
+- **tests** — new `markdown.test.ts` (converter fidelity, the C26 token
+  contract, skins/overrides, the announce-what-you-drop cases, the
+  popup-blocked print fallback) plus new `markdownToPdfBlob` cases for the
+  default path, partial overrides, image notices and capture-failure wording.
+  The tarball canary exercises `/markdown` through both `import` and
+  `require`, including the no-hardcoded-colour assertion.
+
+### Consumer action (C28)
+
+- `markdownToPdfBlob(markdown, deps)` is **source-compatible** — existing
+  injecting call sites keep working unchanged.
+- **Delete your markdown converter and print stylesheet.** If a host module
+  exists only to fill the old required ports, it is now redundant: call
+  `markdownToPdfBlob(markdown)` directly. matrx-frontend removed
+  `lib/print/markdown-pdf.ts`, `features/html-pages/css/wordpress-styles.ts`,
+  `features/html-pages/utils/markdown-wordpress-utils.ts`'s converter, the
+  `removeThinkingContent`/`hasThinkingContent` bodies in
+  `components/matrx/buttons/markdown-copy-utils.ts`, and the private converter
+  + print sheet inside `features/conversation/utils/markdown-print.ts` in the
+  0.3.0 adoption.
+- **Behaviour delta:** printed/exported document-skin output now obeys print
+  page-break rules it previously ignored. Pages break in better places; a
+  pixel-diff against a pre-0.3.0 PDF will differ.
+- **Brand tokens:** a host that wants its own colours passes
+  `tokens: ":root{ --matrx-print-accent: …; }"` instead of forking the sheet.
+
 ## 0.2.1 — 2026-08-30
 
 QA pass F5/F6/F8 hardening — the popup-blocked lane is now observable and has

package/README.md

@@ -3,7 +3,8 @@
 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
+roll stock with custom label formats, a full flashcard deck printer, a shipped
+markdown converter with two default print stylesheets, and
 DOM-capture/markdown → PDF.
 
 Every entry is import-inert and safe to import during SSR — browser APIs are
@@ -109,15 +110,56 @@ 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/markdown` — the shipped converter & print stylesheets
+
+```ts
+import { markdownToHtml, getMarkdownStylesheet, renderMarkdownDocument, printMarkdown, removeThinkingContent } from "@ai-matrx/print/markdown";
+
+printMarkdown(markdown, { title: "Report" });                       // markdown → print window, one call
+const html = markdownToHtml(markdown);                              // → .matrx-* classed body HTML
+const css  = getMarkdownStylesheet({ skin: "article" });             // → the matching stylesheet
+const page = renderMarkdownDocument(markdown, { title: "Report" });  // → a complete <!DOCTYPE html> page
+```
+
+Two skins off one vocabulary. **`"document"`** (default) emits `.matrx-*`
+classed HTML — headings, nested lists, markdown tables, images, links, code,
+FAQ promotion, `<flashcards>` blocks — inside `.matrx-content-container`, and
+its stylesheet is what pastes into a WordPress theme. **`"article"`** emits
+bare semantic tags with the serif AI-response look for print windows (code
+fences are HTML-escaped there, because a print window does not re-escape).
+`removeThinkingContent` strips `<thinking>` / `<think>` / `<reasoning>` — all
+three, which is why a model switching tag names cannot leak reasoning into a
+printed page.
+
+Colours are `var(--matrx-print-<role>, <default>)` throughout (C26): the inline
+fallbacks make a fresh app render correctly with zero setup, and a host brands
+it by passing `tokens: ":root{--matrx-print-accent:#0f766e}"` — appended last,
+so the host wins. Both sheets carry the print hard parts (`@media print`,
+page-break avoidance, orphans/widows, `print-color-adjust`).
+
 ### `@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
+const blob = await markdownToPdfBlob(markdown);                                    // converter + stylesheet included
+const branded = await markdownToPdfBlob(markdown, { skin: "article", tokens });    // tune without replacing
+const custom = await markdownToPdfBlob(markdown, { convertToHtml, loadCss });      // override either port
 ```
 
+`markdownToPdfBlob` needs nothing from you. Both ports ship a working default
+(they were REQUIRED injections until 0.3.0); supplying one replaces that
+default and leaves the other alone. The defaults load through a lazy
+`import("@ai-matrx/print/markdown")`, so a consumer that only does DOM capture
+never pulls in the stylesheets.
+
+Nothing degrades silently: a flashcard missing its `Front:`/`Back:`, markdown
+that converts to an empty document, an image that 404s or never finishes
+loading (html2canvas would paint a blank rectangle and say nothing), and a
+failed rasterization all report through `onNotice` — or `console.warn` with the
+remedy when no sink is given. `imageTimeoutMs` (default 8000) bounds the wait.
+
 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

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @ai-matrx/print — root entry: TYPES ONLY.\n *\n * The runtime lives in the subpaths (each import-inert, RSC-safe except\n * /react which is a client entry):\n *   @ai-matrx/print/core        BlockPrinter contract + print-window composition\n *   @ai-matrx/print/qr          QR generation + e-commerce payload builders\n *   @ai-matrx/print/labels      label-sheet engine (templates, formats, print/PDF)\n *   @ai-matrx/print/flashcards  the deck printer (10 variants)\n *   @ai-matrx/print/pdf         DOM-capture / markdown → PDF\n *   @ai-matrx/print/barcode     1-D barcodes (Code128 / EAN-13 / UPC-A)\n *   @ai-matrx/print/booklet     saddle-stitch imposition + 2-up print lane\n *   @ai-matrx/print/qr-styled   branded/logo QR (browser-only at call time)\n *   @ai-matrx/print/react       PrintOptionsDialog + LabelSheetPreview\n */\n\nexport type {\n  BlockPrinter,\n  PrintVariant,\n  PrintSetting,\n  PrintSettings,\n  PrintOutcome,\n} from \"./core\";\n\nexport type { QrEcLevel, QrOptions } from \"./qr\";\n\nexport type {\n  LabelTemplate,\n  QrLabel,\n  QrLabelPrintData,\n  QrLabelSettings,\n  ScannabilityReport,\n  LabelField,\n  LabelElement,\n  LabelFormat,\n} from \"./labels\";\n\nexport type { Flashcard, FlashcardsVariant } from \"./flashcards\";\n\nexport type { DomCaptureOptions, MarkdownPdfDeps } from \"./pdf\";\n\nexport type { BarcodeSymbology, BarcodeOptions } from \"./barcode\";\n\nexport type {\n  BookletSheet,\n  BookletImposition,\n  BookletPrintOptions,\n} from \"./booklet\";\n\nexport type {\n  StyledQrOptions,\n  StyledQrEcLevel,\n  StyledQrDotStyle,\n  StyledQrCornerStyle,\n} from \"./qr-styled\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @ai-matrx/print — root entry: TYPES ONLY.\n *\n * The runtime lives in the subpaths (each import-inert, RSC-safe except\n * /react which is a client entry):\n *   @ai-matrx/print/core        BlockPrinter contract + print-window composition\n *   @ai-matrx/print/qr          QR generation + e-commerce payload builders\n *   @ai-matrx/print/labels      label-sheet engine (templates, formats, print/PDF)\n *   @ai-matrx/print/flashcards  the deck printer (10 variants)\n *   @ai-matrx/print/pdf         DOM-capture / markdown → PDF\n *   @ai-matrx/print/markdown    the shipped markdown converter + print stylesheets\n *   @ai-matrx/print/barcode     1-D barcodes (Code128 / EAN-13 / UPC-A)\n *   @ai-matrx/print/booklet     saddle-stitch imposition + 2-up print lane\n *   @ai-matrx/print/qr-styled   branded/logo QR (browser-only at call time)\n *   @ai-matrx/print/react       PrintOptionsDialog + LabelSheetPreview\n */\n\nexport type {\n  BlockPrinter,\n  PrintVariant,\n  PrintSetting,\n  PrintSettings,\n  PrintOutcome,\n} from \"./core\";\n\nexport type { QrEcLevel, QrOptions } from \"./qr\";\n\nexport type {\n  LabelTemplate,\n  QrLabel,\n  QrLabelPrintData,\n  QrLabelSettings,\n  ScannabilityReport,\n  LabelField,\n  LabelElement,\n  LabelFormat,\n} from \"./labels\";\n\nexport type { Flashcard, FlashcardsVariant } from \"./flashcards\";\n\nexport type {\n  DomCaptureOptions,\n  MarkdownPdfDeps,\n  MarkdownPdfNotice,\n} from \"./pdf\";\n\nexport type {\n  MarkdownSkin,\n  MarkdownNotice,\n  MarkdownToHtmlOptions,\n  MarkdownStylesheetOptions,\n  RenderMarkdownDocumentOptions,\n  PrintMarkdownOptions,\n} from \"./markdown\";\n\nexport type { BarcodeSymbology, BarcodeOptions } from \"./barcode\";\n\nexport type {\n  BookletSheet,\n  BookletImposition,\n  BookletPrintOptions,\n} from \"./booklet\";\n\nexport type {\n  StyledQrOptions,\n  StyledQrEcLevel,\n  StyledQrDotStyle,\n  StyledQrCornerStyle,\n} from \"./qr-styled\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/index.d.cts

@@ -2,7 +2,8 @@ export { BlockPrinter, PrintOutcome, PrintSetting, PrintSettings, PrintVariant }
 export { QrEcLevel, QrOptions } from './qr.cjs';
 export { LabelElement, LabelField, LabelFormat, LabelTemplate, QrLabel, QrLabelPrintData, QrLabelSettings, ScannabilityReport } from './labels.cjs';
 export { Flashcard, FlashcardsVariant } from './flashcards.cjs';
-export { DomCaptureOptions, MarkdownPdfDeps } from './pdf.cjs';
+export { DomCaptureOptions, MarkdownPdfDeps, MarkdownPdfNotice } from './pdf.cjs';
+export { MarkdownNotice, MarkdownSkin, MarkdownStylesheetOptions, MarkdownToHtmlOptions, PrintMarkdownOptions, RenderMarkdownDocumentOptions } from './markdown.cjs';
 export { BarcodeOptions, BarcodeSymbology } from './barcode.cjs';
 export { BookletImposition, BookletPrintOptions, BookletSheet } from './booklet.cjs';
 export { StyledQrCornerStyle, StyledQrDotStyle, StyledQrEcLevel, StyledQrOptions } from './qr-styled.cjs';

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export { BlockPrinter, PrintOutcome, PrintSetting, PrintSettings, PrintVariant }
 export { QrEcLevel, QrOptions } from './qr.js';
 export { LabelElement, LabelField, LabelFormat, LabelTemplate, QrLabel, QrLabelPrintData, QrLabelSettings, ScannabilityReport } from './labels.js';
 export { Flashcard, FlashcardsVariant } from './flashcards.js';
-export { DomCaptureOptions, MarkdownPdfDeps } from './pdf.js';
+export { DomCaptureOptions, MarkdownPdfDeps, MarkdownPdfNotice } from './pdf.js';
+export { MarkdownNotice, MarkdownSkin, MarkdownStylesheetOptions, MarkdownToHtmlOptions, PrintMarkdownOptions, RenderMarkdownDocumentOptions } from './markdown.js';
 export { BarcodeOptions, BarcodeSymbology } from './barcode.js';
 export { BookletImposition, BookletPrintOptions, BookletSheet } from './booklet.js';
 export { StyledQrCornerStyle, StyledQrDotStyle, StyledQrEcLevel, StyledQrOptions } from './qr-styled.js';