@zumer/snapdom-plugins 3.0.0-beta.0 → 4.0.0

package/pdf/REFERENCE.md

@@ -0,0 +1,520 @@
+# SnapDOM PDF reference
+
+Version 1.0.0 reference. This is the canonical option and behaviour reference
+for the build beside it.
+
+SnapDOM PDF is a SnapDOM plugin. It does not expose a standalone `toPdf(element)`
+function. Register the `pdf()` factory before capture; the resulting capture
+then gains `toPdf()` and the generic `to('pdf')` export.
+
+```js
+import { snapdom } from '@zumer/snapdom'
+import pdf from './snapdom-pdf.mjs'
+
+snapdom.plugins(pdf())
+
+const shot = await snapdom(document.querySelector('#report'), {
+  scale: 2,
+  dpr: 1,
+})
+
+const blob = await shot.toPdf({ page: 'a4' })
+```
+
+See [README.md](./README.md) for the bundler and import-map installation
+recipes. Both builds export the same factory as the default export and as the
+named export `pdf`. The supported peer range is `@zumer/snapdom >=3.0.0 <4`.
+The plugin uses v3's immutable capture metadata, requested export options and
+pre-decode canvas crops. PDF declares `needs: 'render'` and uses the SVG path so
+the text layer and raster share one immutable artifact.
+
+## The two option moments
+
+The plugin derives its geometry and document semantics lazily from SnapDOM's
+final serialized clone when the first PDF export runs, rather than reading the
+original live DOM. Five options control that capture model and therefore have
+to be fixed on `pdf()` before the capture is created:
+
+| Capture-time option | Default | Meaning |
+|---|---:|---|
+| `formValues` | `true` | Put `input`, `textarea` and selected `select` values in the text layer. Password values are replaced with bullets. |
+| `shadow` | `true` | Walk open shadow roots as a flattened tree. Closed roots are unreachable. |
+| `breakAvoid` | `true` | Measure rows, list items, figures and other atomic blocks so pagination can avoid splitting them. |
+| `outline` | `true` | Build bookmarks from `h1`–`h6` and `role="heading"`. A string is a custom CSS selector; `false` disables the outline. |
+| `forms` | `true` | Measure form controls (kind, name, value, options, geometry, painted style) so the export can write fillable fields. `false` skips the measurement entirely. |
+
+```js
+snapdom.plugins(pdf({
+  shadow: true,
+  outline: 'h1, h2, [role="heading"]',
+  page: 'a4',       // an export default may also live here
+  margin: 36,
+}))
+
+const shot = await snapdom(report)
+await shot.toPdf({ margin: 48 }) // overrides only this export
+```
+
+Passing a capture-time option to `toPdf()` warns and ignores it. Every export
+option below may also be supplied to `pdf()` as a default; `toPdf()` wins.
+
+## `toPdf()`
+
+```ts
+shot.toPdf(options?: PdfExportOptions): Promise<Blob>
+shot.to('pdf', options?: PdfExportOptions): Promise<Blob>
+```
+
+`download` is an optional side effect. A `Blob` with type `application/pdf` is
+returned in every case.
+
+### Page and pagination
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `page` | `'fit'` | `'fit'`; `a3`, `a4`, `a5`, `a6`, `b4`, `b5`, `letter`, `legal`, `tabloid`, `executive`; or `[width, height]` in PDF points. |
+| `orientation` | `'portrait'` | `'portrait'` or `'landscape'`. It has no effect on `'fit'`. |
+| `margin` | `24` | Points on all sides. It has no effect on `'fit'`. |
+| `repeatHeaders` | `true` | On paginated output, repeat a table's `<thead>` wherever that table continues. |
+
+`page: 'fit'` creates one page at the captured element's size. Other sizes scale
+the capture to the printable width and paginate vertically. Declared
+`break-before`/`break-after` values `always`, `page`, `left`, `right`, `recto`
+and `verso` create plain breaks when they do not create an empty page.
+
+Atomic blocks include table rows, list items, `dt`/`dd`, figures, blockquotes,
+replaced content, `break-inside: avoid` content and short leaf blocks. A block
+taller than a page still has to be split.
+
+Repeated `<thead>` pixels and text are re-stamped from the body capture. Links
+inside the repeated copy are not repeated. A header taller than half a page is
+left where it originally occurs and produces a warning.
+
+### Raster
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `image` | `true` | Draw the visible page raster. `false` skips rasterization and produces an image-free PDF while the enabled text, links and structure remain. Element headers, footers and watermarks are omitted because they are images. |
+| `codec` | `'auto'` | `'auto'` encodes JPEG and lossless Flate and keeps the smaller image. `'jpeg'` and `'flate'` pin the choice. |
+| `quality` | capture quality or `0.92` | Quality of the JPEG candidate, taken from the capture when the export does not set one. It reaches nothing when Flate wins, and on ordinary page artwork Flate wins until roughly 0.5. Measured on a 37-page report: `0.92`, `0.8` and `0.6` all produce a byte-identical 16.1 MB, `0.4` gives 13.7 MB and `0.2` gives 10.1 MB. An export whose lowered quality changed nothing says so. |
+| `backgroundColor` | capture background or `null` | Flatten this PDF export onto a colour. May be set on the capture, the plugin defaults or this export. |
+
+Resolution belongs to `snapdom(...)`: use `scale`, `dpr`, `width` and `height`
+there, not in `toPdf()`. On v3, an explicit width or height overrides `scale`;
+`dpr` still multiplies the raster resolution. Keep the capture aspect ratio when
+setting both dimensions. The exporter rasterizes page regions lazily and caches
+them on the capture for later exports. A different codec, quality or flattening
+choice may still require encoding work.
+
+**`dpr` is the same knob as `scale` here, and it defaults to the machine.**
+A PDF has no device to match, so neither option moves a point of geometry: the
+MediaBox, the text layer and every annotation are identical whatever they are
+set to. What they multiply is the page image's pixel count, and they multiply it
+together. Measured on an 8-page A4 report, `scale: 1, dpr: 2` and
+`scale: 2, dpr: 1` produce the same 1748px-wide raster and the same 3.18 MB
+file, against 1.63 MB at 1×1 and 6.93 MB at 2×2.
+
+The catch is the default. SnapDOM reads `dpr` from `window.devicePixelRatio`,
+which is right for a screenshot and surprising for a document: the same code
+exports 3.18 MB from a 2× laptop and 1.63 MB from a 1× monitor or a CI
+container, with no visible difference in the page and no warning. Set `dpr`
+explicitly on the capture (`1` for a light, screen-read file, `2` for one meant
+to be printed) and the export stops depending on who ran it.
+
+`codec: 'auto'` costs an extra encode. Pin a codec when latency matters more than
+choosing the smallest file. If `CompressionStream` is unavailable, `auto` uses
+JPEG and a requested `flate` warns before falling back to JPEG.
+
+Transparency uses a soft mask. `backgroundColor` removes that mask and usually
+produces a smaller file. Geometry comes from the same final serialized clone as
+the raster. Real removals/replacements made by `exclude`, `resolveNode`,
+`afterClone`, `clip`, or a geometry-preserving `afterRender` replacement of the
+final serialized tree/URL stay synchronized with the PDF layer. An `afterRender`
+replacement that changes the artifact's viewBox, root paint/layout attributes or
+intrinsic aspect/geometry incompatibly is rejected rather than exported with a
+misaligned layer. Uniform width/height scaling that preserves aspect is allowed.
+
+### Text, links, navigation and accessibility
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `text` | `true` | Emit selectable/searchable invisible text. |
+| `links` | `true` | Emit external URI and in-document link annotations. |
+| `tagged` | `true` | Emit a structure tree for headings, paragraphs, lists, tables, sections and figures. |
+| `lang` | DOM language or `null` | Set the PDF document language, such as `'en'` or `'es-MX'`. |
+| `embedFonts` | `true` | Embed the capture's `@font-face` binaries and point the text at them. |
+| `vectorText` | `false` | Paint eligible text as real vector glyphs instead of leaving it invisible over the raster. |
+| `debugText` | `false` | Paint the normally invisible layer in red and leave streams readable. |
+
+#### Embedded fonts
+
+The capture must CARRY its fonts for the export to embed them: pass
+`embedFonts: true` to `snapdom(…)` (the engine option that inlines `@font-face`
+into the capture), and the PDF side reads those rules, fetches each face the
+text actually painted with, and embeds a SUBSET of it: only the glyphs the
+document drew, renumbered into a dense space. On a Latin page a ~320 kB face
+travels as a few kB; the subset renders pixel-identical to the whole font
+(asserted by rendering both through pdf.js). A face travels once however many
+styles and pages use it, and the saving is declared per face (`font-embedded`).
+
+`embedFonts` on the PDF export controls this: `true` (default) subsets;
+`'full'` embeds the whole file unsubsetted (glyph ids stay the font's own);
+`false` embeds nothing. CFF/OpenType (`OTTO`) faces are always embedded whole
+(their charstrings are a different compiler), so `'full'` only differs for
+TrueType. The subsetter is fail-safe: a TrueType face it cannot subset falls
+back to a whole embed with an explicit `CIDToGIDMap`, never a corrupt glyph.
+
+#### Vector text
+
+By default the visible text is the raster: pixel-exact, but pixels. With
+`vectorText: true` the exporter PAINTS eligible runs as real vector glyphs from
+the embedded fonts, so the type is crisp at any zoom and the file is a fraction
+of the size. This is a different fidelity model from the pixel-exact capture,
+and it is opt-in for that reason.
+
+A run is painted only where no shaping stands between code points and glyphs: a
+left-to-right run, in a covering embedded face, with a resolved colour. RTL,
+complex scripts, uncovered characters and unresolved colours are NOT painted,
+because one CID per code point would place their glyphs wrong. Those runs stay
+on the raster; in an image-free export they are invisible and `vector-missed`
+says so.
+
+The two useful pairings:
+
+- `image: false, vectorText: true`: a small, fully-vector text PDF. Only the
+  text and vector furniture travel; borders, checkboxes, background images and
+  any un-paintable run are absent. Measured: the mega fixture is ~22 kB this way
+  against ~420 kB with the raster.
+- `image: true, vectorText: true`: the raster plus crisp vector glyphs painted
+  over it. Larger, but sharp under magnification.
+
+Interior glyph positions follow the embedded font's own advances scaled to the
+run's measured width (`Tz`), not the browser's kerned positions, so a heavily
+kerned pair can drift sub-pixel from the raster. Extraction is unchanged: the
+painted glyphs carry the same `/ToUnicode` as the invisible layer.
+
+Per run, the embedded face is used only when its real cmap covers every
+character of the run; a run it cannot carry falls back to the unembedded layer
+and is counted (`font-coverage`). System fonts have no bytes a page can hand
+over and travel by name as before. WOFF unpacks; WOFF2, TrueType collections
+and faces whose `OS/2 fsType` forbids embedding are refused with their reason
+(`font-fallback`). No shaping is performed, which is correct for the invisible
+layer, whose widths are pinned to the DOM measurement by `Tz`.
+
+Text extraction is byte-for-byte identical with and without embedding (asserted
+in the harness), because extraction runs off `/ToUnicode` either way.
+
+#### The earned PDF/UA-1 claim
+
+The exporter never takes a conformance claim as an option; it COMPUTES
+eligibility per export: every text-showing operation on an embedded face,
+`tagged` structure present, a document language, a `meta.title` to display, and
+no painted image without alternative text. When all of it holds, the XMP carries
+`pdfuaid:part 1` and the report says so (`ua-claimed`, `report.pdfua === true`).
+When fonts are clean but a blocker remains, the blockers are named
+(`ua-withheld`).
+
+Two blockers are worth knowing in advance. Fillable fields block the claim,
+because their editor-facing `/DA` types in unembedded Helvetica, so a
+UA-claiming export pairs with `fields: false`. A painted `<img>` or
+`role="img"` element with no accessible name blocks it too, because its pixels
+live in the page raster, which is an artifact, and there is no `/Alt` to
+announce: give it `alt`, `aria-label` or `title`, or `alt=""` when it is
+decorative.
+
+Text is measured from the final serialized clone, one run per word. Text
+transforms are applied; open shadow roots, visible form values and bidi logical
+order are included. Text hidden by layout, ancestor opacity or rectangular
+overflow clipping is excluded.
+
+Base-14 fonts carry WinAnsi text. Other scripts use an invisible Type0 font with
+a `/ToUnicode` map. Without `vectorText`, the visible type remains the SnapDOM
+raster.
+
+Headings become bookmarks and named destinations. A same-document `#fragment`
+link becomes a PDF destination; an unresolved or out-of-capture fragment gets no
+annotation and produces a warning. External annotations are restricted to
+`http:`, `https:`, `mailto:` and `tel:`. Malformed URLs and other schemes such
+as `javascript:`, `data:`, `blob:` and `file:` are ignored and reported. A
+custom `outline` selector is evaluated against the final flattened artifact, so
+matching open-shadow and slotted headings participate too.
+
+#### Redaction and semantic visibility
+
+Visual occlusion is not redaction. A rectangle above a secret, blur, or arbitrary
+overlap can hide pixels without removing the underlying text from the serialized
+document. Remove or replace confidential nodes/text with `exclude`,
+`resolveNode` or a clone/render hook. Do not use overlays or blur as a redaction
+mechanism.
+
+For known clipping, masking and filter geometry, the collector omits text and
+links when it cannot prove they are visible. This is fail-safe: difficult visual
+effects may lose selectable semantics instead of leaking content. An
+`afterRender` hook is synchronized only when it replaces the final serialized
+tree/URL while preserving its geometry. A purely visual overlay is not evidence
+that semantic content vanished, and an incompatible viewBox, root paint/layout
+or intrinsic-aspect change fails instead of guessing new coordinates.
+
+Tagged output improves reading order and structure. It becomes a **PDF/UA-1
+claim only when the export earns it** (see "The earned PDF/UA-1 claim" above);
+short of that, no `pdfuaid` identifier is written. Either way the tree is
+real: link annotations are tied in by
+`/Link` structure elements carrying `/OBJR` references, fillable fields by
+`/Form` elements, header cells carry `/Scope` (and spans), table row groups map
+to `THead`/`TBody`/`TFoot`, pages declare `/Tabs /S` so tab order follows the
+structure, and the parent tree resolves both marked content and annotations.
+Inline formatting elements are deliberately not expanded into a structure node
+each.
+
+### Fillable form fields
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `fields` | `true` | Emit measured form controls as real AcroForm fields: fillable, tabbable, extractable. `false` keeps their values in the invisible text layer instead. |
+
+A captured form should still BE a form. Text inputs, textareas, checkboxes,
+radio groups, and selects become widget annotations with their DOM name, value,
+options and checked state; `readonly`/`disabled` map to the read-only flag,
+`required` and `maxlength` travel too, and the accessible label (`aria-label`,
+`<label for>`, placeholder, title, in that order) becomes the field's tooltip,
+which is what a screen reader speaks. Radios group by their HTML `name`;
+duplicate non-radio names are uniquified with a suffix and reported.
+
+The page image yields each fielded control's area to its widget, and the
+widget's appearance follows one rule, dictated by macOS Preview: a field
+HOLDING A VALUE paints it as real text, laid out from the control's own
+measured runs so a textarea's wrap and an input's alignment are the page's
+rather than a guess, while an EMPTY field wears the control's own crop of the
+capture: border, corner radius and placeholder, pixel-exact. (Preview redraws a
+text field's value over any appearance carrying an image, so a valued field's
+crop would show the value twice there; text appearances render once everywhere:
+Preview, Quick Look, Chrome, pdf.js, Acrobat, and every print/flatten path.)
+
+What deliberately does not happen: a **password** field is written empty with
+the password flag set, because a field value is plain text in the file; the
+raster keeps its painted bullets. **Buttons, sliders, colour wells and file
+pickers** stay pixels; a control that only means something to a running page is
+not a field. **No JavaScript actions and no submit URLs** are ever written. A
+rotated or clip-cut control is reported and left as invisible text, and a
+control crossing a page break is clamped to one page and reported. With
+`image: false` the appearance is synthesized (background, border and a base-14
+value line), and a value outside WinAnsi sets `/NeedAppearances` so the viewer
+draws it.
+
+### Document metadata, identity and page labels
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `meta` | `null` | `{ title, author, subject, keywords, creator, created, modified }`: /Info plus a mirrored XMP packet. |
+
+`title` also sets `/ViewerPreferences << /DisplayDocTitle true >>`, so viewers
+show the document's name rather than its filename. `keywords` may be a string or
+an array. `created`/`modified` accept a `Date` or ISO-8601 string and are
+written ONLY when given: an invented "now" would break the byte-determinism
+promise, so pass `new Date()` yourself when you mean it. `/Producer` is always
+`snapdom-pdf` and is not an option.
+
+Every file carries a trailer `/ID` derived from its own content: identical
+unencrypted exports share an ID, different documents differ, and no clock is
+involved. Paginated documents with front matter get `/PageLabels` (cover and
+contents in lowercase roman, body decimal from 1), so the viewer's page field
+agrees with the printed folio and with the generated contents.
+
+### Encryption
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `encrypt` | `null` | `{ userPassword, ownerPassword, permissions }`: encrypt the file with AES-256 (standard security handler, revision 6). |
+
+The exported file is the delivery: it gets downloaded, attached, and forwarded.
+`encrypt` is what makes that file unreadable once it has left, and it is the
+only protection here that is not advisory.
+
+```js
+await shot.toPdf({
+  page: 'a4',
+  encrypt: { userPassword: 'ada-1815', ownerPassword: 'owner-key' },
+})
+```
+
+`userPassword` is **required and must be non-empty**, and an export that omits
+it throws rather than producing a file. A PDF whose user password is `''` is
+genuinely encrypted (the bytes are unreadable to a text editor), and every
+viewer in the world still opens it without asking. That is the exact shape of a
+document somebody believes is protected and is not. `ownerPassword` defaults to
+the user password; it exists to lift the permission flags for whoever holds it.
+
+**AES-256 and nothing older.** RC4 and revisions 2–4 are not offered at any
+setting. A 40-bit key falls in seconds, 128-bit RC4 is not far behind, and both
+need MD5, which the platform does not provide. Writing one by hand to ship a
+weaker product is not a trade this exporter makes. Everything used here comes
+from the browser's own `crypto.subtle`, so the plugin carries no cipher code and
+no dependency. Encryption therefore needs a **secure context**: https, or
+localhost. Encrypting a 14 MB document costs about 34 ms.
+
+| | |
+|---|---|
+| `/Filter /Standard /V 5 /R 6`, `/CFM /AESV3`, 256-bit key | ISO 32000-2 §7.6.4 |
+| Header stays `%PDF-1.7`; the catalog declares `/ADBE /ExtensionLevel 3` | the shape readers learned before ISO 32000-2 |
+| Every stream and every string is encrypted, `/Metadata` included | strings inside content streams ride the stream |
+
+#### Permissions are a request, not a protection
+
+`permissions` accepts `print`, `modify`, `copy`, `annotate`, `fillForms`,
+`assemble` and `printHighRes`; each defaults to `true`, and setting one to
+`false` clears its `/P` bit. Understand what that buys: a flag is something a
+viewer *may* honour and any other tool can ignore. The password is what protects
+the document; the flags only express intent to software that has already been
+given the key. The export says so in the report when any of them is set.
+
+Extraction for accessibility is deliberately not exposed. PDF 2.0 deprecates
+that bit (a conforming reader must always allow it), and PDF/UA requires an
+encrypted file to keep permitting it, so an exporter whose selling point is an
+extractable text layer has no business offering to switch it off. A UA-claiming
+export and an encrypted one are compatible for exactly that reason.
+
+#### Encrypted exports are not deterministic
+
+The file key, the salts and every IV are random, drawn from
+`crypto.getRandomValues` for each export. Encrypting the same document twice with
+the same password gives two different files that open to the same content, so
+two encrypted files never reveal that their contents match. Unencrypted exports
+stay byte-deterministic.
+
+### Progress, cancellation and the report
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `onProgress` | `null` | `({ phase, done, total })` per step: `measure`, `page` (with counts), `matter`, `assemble`. |
+| `signal` | `null` | An `AbortSignal`; aborting rejects with `AbortError` between pages. |
+| `onReport` | `null` | Receives the structured diagnostics report once the Blob is finished. |
+
+The report is `{ warnings, counts, pages, bytes, fields, annotations,
+fontsEmbedded, pdfua, vectorText }`, where each warning is `{ code, message }`,
+`counts` tallies by code and `vectorText` counts the runs painted as glyphs.
+Codes are a stable contract (`text-clipped`, `link-unresolved`, `field-skipped`,
+`layout-split`, …) so a CI step can gate on "no annotations lost" without
+parsing prose. Identical unencrypted exports produce identical reports; the
+console keeps warning regardless, so nothing changes for callers who ignore all
+of this.
+
+### Header, footer and page numbers
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `header` | `null` | A string/function, a text-band object, or an Element. |
+| `footer` | `null` | The same along the bottom. |
+| `pageNumbers` | `false` | `true` or `{ format, align, size, font, color }`. |
+
+Text bands accept `{ left, center, right, size, font, color, rule, gap }`.
+Segments may be strings or `(page, pages) => value`. `font` is `document`,
+`sans`, `serif` or `mono`; colours are three- or six-digit hex values.
+`document`, the default, is the body's own embedded face when the export has
+one, so a running head is set in the same type as the report it runs over, in
+real embedded glyphs; per string it falls back to base-14 sans when nothing is
+embedded or the face lacks a character. An explicit `sans`/`serif`/`mono` keeps
+meaning base-14. Base-14 furniture remains limited to WinAnsi scripts.
+
+Text-band defaults are `size: 9`, `font: 'document'`, `rule: true` and
+`gap: 10`. Page numbers default to `(page, pages) => page + ' / ' + pages`,
+centred at size 9 in the document face. `colour` is accepted as an alias for
+`color`; prefer `color` in new code.
+
+An Element band captures its capturable content and styles, but it is a picture
+without its own selectable layer; scripts are not executed by the measurement
+sandbox. Header, footer and numbers reserve space and only apply to paginated
+page sizes. With `image: false`, Element bands are omitted with a warning; text
+bands and page numbers still work.
+
+### Cover, generated contents, closing page and watermark
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `cover` | `null` | An Element captured as the first page. |
+| `toc` | `null` | `true`, a title string, or `{ title, levels, size, font, indent, dots, label, color, leaderColor }`. |
+| `back` | `null` | An Element captured as the last page. |
+| `watermark` | `null` | A string, Element, text-watermark object or element-watermark object. |
+
+Cover and back are scaled to fit a whole page without cropping and receive a
+selectable text layer. The generated contents comes from the same outline as
+the bookmarks; each row links to the body destination. Its page numbers refer
+to body pages, excluding cover and contents pages. When a custom
+`pageNumbers.format` changes numbering, use `toc.label` to keep both in step.
+
+Text watermarks accept `{ text, opacity, angle, size, font, color }`; omitting
+`size` auto-fits the rotated text. Element watermarks accept
+`{ element, opacity, angle, fit }`. Watermarks draw over every page and also work
+with `page: 'fit'`. With `image: false`, an Element watermark is omitted, while
+text watermarks still work. Cover, contents and back require a paginated page
+size; image-free cover/back pages retain their measured text, links and structure
+but not their visible raster.
+
+Contents default to title `Contents`, three outline depths, size 10, the
+document face, 14-point indentation and leaders enabled. Text watermarks default
+to 12% opacity and 45 degrees; Element watermarks default to 12% opacity, no
+rotation and a 0.6 fit. `colour`/`leaderColour` are accepted aliases for
+`color`/`leaderColor`.
+
+### Output
+
+| Option | Default | Meaning |
+|---|---:|---|
+| `deflate` | `true` | Compress PDF content streams. `debugText` leaves them readable. |
+| `download` | `false` | A filename, or `true` for `snapdom.pdf`. `.pdf` is appended when absent. |
+
+Use `deflate`, not SnapDOM's `compress`; use `download`, not SnapDOM's
+`filename`. `compress`, `filename`, PDF-side `scale`, legacy `background`,
+`mode` and `vector` are not PDF options and are reported when passed.
+
+## Errors and warnings
+
+Register the plugin before capture. A capture made without it has no `toPdf()`
+helper, and its generic `to('pdf')` has no PDF exporter to run. An available PDF
+export rejects an incompatible SnapDOM contract, invalid or empty capture
+geometry, an incompatible final-artifact viewBox/root paint-layout/intrinsic
+aspect, invalid orientation/margins/custom page geometry, and invalid active
+image codec/quality.
+An unknown string paper name warns and falls back to A4 for untyped JavaScript
+callers. Other fidelity losses are reported under `[snapdom-pdf]`, including:
+
+- page breaks that split atomic blocks or declared breaks that cannot be used;
+- text or links clipped, invisible, outside the page, or under unsupported 3D geometry;
+- unresolved internal links and invalid custom outline selectors;
+- missing language on tagged output;
+- a repeated table header too tall to repeat;
+- a requested contents page with no headings;
+- Base-14 page furniture that cannot represent its script;
+- invalid or translucent flattening colours and unavailable Flate compression;
+- malformed links or URI schemes outside the safe allowlist.
+
+Every one of these is also a structured diagnostic with a stable code in the
+report handed to `onReport`, so a build can gate on them instead of reading the
+console.
+
+## Known limits
+
+- Visible text is raster by default, so zooming beyond capture resolution exposes pixels. `vectorText` paints eligible runs as glyphs, never RTL or complex scripts.
+- `textarea` wrapping is greedy and can drift for hyphenation, CJK, unbreakable strings and `line-height: normal`.
+- Date-like controls contribute their ISO value rather than the locale-painted value. Multi-row selects contribute no value.
+- Closed shadow roots are unreachable.
+- Upright glyphs in vertical writing modes are placed square; sideways runs are supported.
+- Ambiguous clipping, masking and filter geometry is omitted fail-safe, so some visibly painted text may not be selectable.
+- Native `<select>` insets were measured on Chromium and can differ in other engines.
+- Rotated links use an axis-aligned PDF rectangle.
+- Captured header/footer Elements have no selectable text layer.
+- `image: false` omits Element headers, footers and watermarks; cover/back pages
+  keep semantics but lose their visible raster.
+- Only `<thead>` repeats, and its repeated copy has no repeated link annotations.
+
+## Browser status
+
+The exporter is a browser ESM module. The complete PDF fixture suite runs in
+Chromium through `npm run test:pdf`. The monorepo also tests registration,
+searchable text, frozen capture state and redaction in Chromium and WebKit.
+Firefox is not yet verified in this branch: its runner failed to connect.
+The complete complex-layout matrix is not verified in every engine; known
+engine-sensitive limits remain listed above.
+
+The exporter runs locally in the page and returns a Blob. It does not upload the
+PDF. SnapDOM may still fetch the page resources or use a proxy if the application
+configured one.