# Internal build contract — snapdom vector v0

This document describes the internal migrated engine, SVD format and optional Figma consumer in `src/`, `svd/` and `figma-plugin/`. Historical examples below use the engine's internal API; they are not the public npm API.

The public MIT-licensed plugin is `@zumer/snapdom-plugins/vector`: `vector({ exclude })` adds `toVector()` (SVG string) and `toFigma()` (clipboard write, returning `Promise<void>`). Only `exclude` is a public Vector option. See [usage](README.md), [public types](../vector.d.ts) and [the public adapter](src/public.js). Plugins 4.x are available on npm and require core 3.x.

**And the reverse duty, which is what this paragraph is for: a contract that
lies is worse than no contract.** When this file described a shape the code no
longer had, three consumers each invented their own probe list for the gradient
`unit` keys (`from || start || p0`); two were right by accident and the Figma
plugin was wrong, which flattened every linear gradient to top-to-bottom. The
same failure repeated with `decoration`, read as an object when it had become an
array — every underline in the document came out as NONE. Change the code and
this file in the same pass, or the next reader builds on the older of the two.
Last reconciled against the source: 2026-08-05 (text emitters, effect vocabulary,
`emit/*` signatures).

## Scope: the engine walks snapdom's CLONE, not the live DOM

This is the founding decision and it is not an implementation detail.

The engine is a **snapdom plugin**. The caller writes the `snapdom()` call and
registers us on it; our `beforeRender` hook takes the clone off the hook state, and
the `toVector()` / `toVectorSvg()` exports we publish through `defineExports()` mount
that clone offscreen and walk **that**.

```js
import { snapdom } from '@zumer/snapdom'          // v3, local repo
import { vector, svdToSvg } from '@zumer/snapdom-vector'

const result = await snapdom(el, { plugins: [vector({ mode: 'design' })] })
const doc = await result.toVector()               // SVD document
const svg = await result.toVectorSvg()            // ...or straight to markup
```

There is no `toVector(element)`, and there must not be one again — see
[Why a plugin, and not a hook in the core](#why-a-plugin-and-not-a-hook-in-the-core)
below. `svdToSvg` / `svdToFigma` stay module-level functions because they are
document→format, not capture APIs: give them a document and they need no DOM.

The clone is where snapdom has already done the ugly
half of the job: pseudo-elements materialised into real `<span>`s, shadow DOM
flattened with its CSS rewritten, icon fonts resolved to `<img>`, backgrounds and
images inlined past CORS, `backdrop-filter` pre-composed, scroll applied as a
translate. Membership in the tree is *solved*; only geometry and paint are ours.

**Measured, not assumed** (`test/_clonemetrics.mjs`, nine fixtures across two demo
pages plus `test/fixtures/scrolldrift.html`): the mount reproduces the live layout
with a delta of **0.00px** — median, p95 and max, across every mapped node. There is
no accuracy argument for preferring the live DOM, and the clone additionally carries
boxes for nodes the live DOM does not have at all.

That number is the *output* of four repairs, not a property of mounting. Borrowing
the page's cascade is what makes the clone faithful, and every way it fails comes
from the same place — the page's selectors were not written for a tree that sits
somewhere else, gained nodes, and connects custom elements on arrival. Each repair
lives in `adapters/snapdom.js` with the drift it removed:

| what breaks | repair | was |
|---|---|---|
| host has no width; a `width:auto` root shrink-wraps | `sizeHost` | 628px |
| nothing styles a node snapdom invented (`::before` at 0×0) | `synthRulesFrom` | 18px |
| a scroll wrapper breaks every `>` chain crossing it, whole subtree | `synthRulesFrom` | 268px |
| connecting the clone upgrades custom elements, re-attaching shadow roots | `defuseUpgradedShadowRoots` | 37.72px |

The snapshot rules go **only** to nodes the page cannot reach. Applying snapdom's
whole `classCSS` on top of the page's cascade is worse than applying none of it:
measured, fx-table's pixel diff went 1.83 → 10.25 and a paragraph re-wrapped.

Mount in the LIGHT dom, never a shadow root: Chromium ignores `@font-face` inside
one, and a clone laid out with substituted fonts measures nothing useful.

`nodeMap` (clone → source) stays available and is what a harness uses to assert the
clone has not drifted. It is a check, not the data path.

## Why a plugin, and not a hook in the core

This section exists so nobody re-derives the hook. It has been invented twice.

The history: an early revision had the engine walking the **live DOM**, because
snapdom's internal hand-off (`__retain`, which burst's differential recapture uses to
keep a clone alive) was not reachable from outside — `createContext` is an allowlist
and silently drops any callback a caller passes. The fix at the time was to widen the
allowlist: a public `retain` option, committed to snapdom v3 as `2c9d22c`.

**That commit is reverted.** The access it added already existed. `snapdom(el, {
plugins: [...] })` runs render hooks, and a render hook is handed the clone — the same
clone, one line earlier in the same function. `retain` bought nothing a plugin could
not already do, and it charged for it in public surface: once `retain` is in the
allowlist it is a documented capability the core owes every caller forever, and the
private `__retain` channel it shadowed is an implementation detail of burst that
should stay private. So the core is untouched, and the engine is a plugin.

Four things that decision fixes on the way past, each of which the loose API had to
work around by hand:

- **`burst` no longer has to be forced off.** The old API passed `burst: false` on
  every call, because burst's memo and differential paths answer with a URL without
  re-entering `captureDOM`, so there would be no clone. A plugin with render hooks
  that does not declare `pure: true` suspends auto-burst by construction
  (`snapdom/src/core/plugins.js`, `hasImpureRenderPlugins`). Measured: five
  back-to-back captures of one element all ran the pipeline; the loose API broke at
  the third. **Omitting `pure` is therefore load-bearing, not an oversight.**
- **One capture, not two.** The loose API made its own `snapdom()` call, so a caller
  who wanted a PNG *and* an SVD paid for two full captures. Now both come off one.
- **`toVector`, not `toSvg`.** `buildResult` derives the helper name from the export
  key, and plugin exports override core exports by name (`{...coreExports,
  ...provided}`). Publishing `svg` would have silently replaced `result.toSvg()` for
  every caller of that capture. Hence `vector` / `vectorSvg` → `result.toVector()` /
  `result.toVectorSvg()`.
- **The caller owns the capture options.** `dpr`, `outerTransforms` and `burst` are
  all read before the first hook runs and **cannot** be forced from a plugin. That is
  not a loss of control — it is where the control belongs now. `outerTransforms:false`
  shows up as measured drift and gets filed, rather than being silently prevented.

Two prices, both paid deliberately:

- `report.timings.snapdomMs` is gone. It was only ever measurable while the engine
  made the `snapdom()` call itself. The caller makes it now, so the caller is what can
  hold a stopwatch — `demo/vector.html` times both halves and still shows the split.
- `classPrefixCSS` is the one capture value no hook sees. It is recovered inside the
  plugin by `classPrefixFrom` (`adapters/snapdom.js`), which cuts it out of `classCSS`
  anchored on the exact suppressor literal plus the `[data-sd-pN]::marker` grammar —
  verified byte-identical to snapdom's own on 14/14 fixtures. If the anchor ever moves
  it falls back to the literal and files `capture.clone-css-partial` rather than
  guessing.

## Module signatures

All modules are ESM, `.js`, no TypeScript, no build step. JSDoc for types.
Files under `src/css/` MUST be importable from Node with no DOM access.

### `packages/svd/src/schema.js`

```js
/** @returns {{ok: boolean, errors: string[]}} */
export function validate (doc)
/** @returns {string[]} errors, empty if valid */
export function validateNode (node, id)
```

Strict: reject, never repair. Checks structural invariants (every `children` id
exists in `nodes`, `root` resolves, every node has `frame` and `abs` and
`fidelity.grade`, every non-`E` grade has a matching `diagnostics` entry, colors
are 4-float arrays in 0..1, `paint.z` is an integer).

**The effect vocabulary is closed and lives here**, because "what can an effect
be" is the question every backend answers differently:

```
dropShadow | innerShadow   {color, offset:[x,y], blur, spread, behind}
layerBlur  | backgroundBlur {blur}
colorMatrix                {values: 20 floats, srcCss: string, backdrop: boolean}
```

`colorMatrix` is the one that is not a blur and does not carry one: it is the
4x5 of `feColorMatrix type="matrix"`, row-major, composing the run of colour
functions (`saturate`, `hue-rotate`, `grayscale`, `sepia`, `invert`, `contrast`,
`brightness`) that `collect/box.js` (`colorMatrixOf`) folded together. `srcCss`
is REQUIRED and is that CSS chain verbatim — a backend that cannot paint the
matrix can still name what it dropped, and a diagnostic that cannot name the
function is not much of a diagnostic. `backdrop` distinguishes `filter` from
`backdrop-filter`: the two recolour different pixels.

### `packages/vector/src/css/color.js`

```js
/** Any CSS color string -> [r,g,b,a] floats 0..1 sRGB. Null if unparseable. */
export function parseColor (css)            // => {rgba: [r,g,b,a], srcCss: string} | null
/** [r,g,b,a] -> "#rrggbb" / "rgba(...)" for SVG output. */
export function toCssString (rgba)
export function isTransparent (rgba)        // => boolean (a === 0)
```
Must handle: hex 3/4/6/8, `rgb()`/`rgba()` legacy and space-separated, `hsl()`/`hsla()`,
named colors, `transparent`, `currentColor` (caller passes resolved value),
and `oklch()`/`lab()`/`color()` by round-tripping through a canvas 2D context when a
DOM is present, falling back to a documented approximation when not. Gamut-map by
chroma reduction, never per-channel clipping.

### `packages/vector/src/css/gradient.js`

```js
/**
 * @param {string} css   one background-image layer, e.g. "linear-gradient(...)"
 * @param {{w:number,h:number}} box  the painting box in px
 * @returns {Paint|null}  null when the layer is not a gradient
 */
export function parseGradient (css, box)
```
Emits `{type:'linear'|'radial'|'angular', unit:{...}, transform:[a,b,c,d,e,f], stops:[...], notes:[]}`.

**`unit` keys are normative — do not guess them downstream.** Leaving them
undefined already cost us: three consumers each invented their own probe list
(`from||start||p0`), two were right by accident and the Figma plugin was wrong,
which silently flattened every linear gradient to top-to-bottom.

```js
linear:  { p0: [x, y], p1: [x, y] }          // unit square, gradient line endpoints
radial:  { center: [x, y], radius: [rx, ry] | r, shape: 'circle'|'ellipse' }
angular: { center: [x, y], startAngle: deg } // CW from 12 o'clock
```

`radius` is a PAIR or a single number. `css/gradient.js` normalizes anisotropy
into `transform` and so writes the scalar; `svd/src/schema.js` accepts both and
every emitter reads a bare `r` as `[r, r]`, which is what it means. This is the
contract, not a divergence from it — do not "fix" one side without the other.

A stop is `{ t, color: [r,g,b,a], srcCss }` with `t` in 0..1, monotonic.
`transform` is the SVG-order 2x3 `[a,b,c,d,e,f]` taking unit space to painted px.

`angular` is the one asymmetry: a conic's angles are real screen angles, so its
matrix must stay a uniform similarity and the rotation lives in `unit.startAngle`.
The emitter composes it; the matrix never carries it.
Geometry normalized to the unit square; anisotropic ellipses absorbed into the matrix.
Color-stop hints resampled to 8–16 stops. `transparent` replaced by `rgba(R,G,B,0)`
of the neighbouring stop (this fixes premultiplication artifacts). `repeating-*`
unrolled up to K=64. Record every approximation in `notes`.

### `packages/vector/src/css/shadow.js`

```js
/**
 * @param {string} css
 * @param {{inset?: boolean, currentColor?: string}} [options]
 * @returns {{shadows: Effect[], warnings: string[]}}
 */
export function parseShadows (css, { inset = true, currentColor } = {})
```
`{type:'dropShadow'|'innerShadow', color:[r,g,b,a], offset:[x,y], blur, spread, behind:false}`.
Multiple comma-separated shadows, in CSS order. `blur` is the CSS radius verbatim.
`warnings` is a RETURNED array, never a property hung off the list: a caller that
destructures the shadows must not be able to drop the reasons by accident. A
shadow that names no color *is* `currentColor`, and only the caller knows it —
pass `cs.color` or the shadow comes out declared-black.

### `packages/vector/src/css/radius.js`

```js
/** @returns {[[number,number],[number,number],[number,number],[number,number]]} tl,tr,br,bl as [rx,ry] */
export function parseRadii (cs, w, h)
```
Percentages resolved against the box. **Apply the CSS overlap scale factor `f`**
(CSS Backgrounds §5.5) when adjacent radii exceed a side.

### `packages/vector/src/css/matrix.js`

```js
/** @returns {{m:[a,b,c,d,e,f], decomposed:{tx,ty,rot,sx,sy,skewX}}|null} */
export function parseTransform (cssTransform, cssOrigin, w, h)
export function multiply (m1, m2)
export function applyToPoint (m, x, y)
```
`rot` in degrees clamped to -180..180. `null` for `none`. 3D transforms return the
flattened 2D projection and the caller emits a diagnostic.

### `packages/vector/src/collect/box.js`

```js
/**
 * @param {Element} el
 * @param {CSSStyleDeclaration} cs   already-computed style for `el`
 * @param {CollectCtx} [ctx]
 * @returns {{fills:Paint[], strokes:Stroke[], effects:Effect[], textEffects:Effect[],
 *            clip:Clip|null, mask:object|null, radii, opacity:number, blend:string,
 *            warnings:Array<string|{code,grade,severity,message}>}}
 */
export function collectBox (el, cs, ctx = {})
/** A background layer's painted rect, given its placement and the asset's intrinsic size. */
export function resolveLayerRect (placement, intrinsic = null)
```
`textEffects` is `text-shadow`: it paints the GLYPHS, so it cannot ride in
`effects` (which filters the box) and the caller hands it to the block's text
node. `mask` is the collected `mask-image` layers — a paint, not a node, and the
schema's `mask` is a reference to a node, so `wireMasks` in `index.js` builds
that node and writes `node.mask = {node, type}`. Both are inert until such a
caller exists and both say so in `warnings`.

Background layers -> `fills` in **reverse CSS order** (CSS paints last layer first).
Coalesce: N background layers sharing a `clipBox` become N entries in one node's
`fills` array, not N nodes. Uniform borders -> one stroke with per-side weights.
Per-side differing colors -> `warnings` + caller composes.

### `packages/vector/src/collect/text.js`

```js
/**
 * @param {Element} blockEl  an element with a text-carrying inline formatting context
 * @param {CollectCtx} ctx
 * @returns {{characters:string, lines:Line[], runs:Run[], pitch:number,
 *            align:string, direction:string, styles:Record<string,TextStyle>,
 *            sourceText:string,
 *            warnings:Array<string|{code,grade,severity,message}>}|null}
 */
export function collectText (blockEl, ctx)
```

**This is the hard one. The rules are not negotiable:**

- `TreeWalker(SHOW_TEXT)` per block. **Never** `selectNodeContents` on a container
  with inline children — it returns duplicate rects (12 for 7 runs). **Never**
  per-character: measured 95ms/35k chars vs 4.1ms for 5600 nodes.
- `Range.getClientRects()` returns the font's ascent+descent box, **not** the CSS
  line box. Baseline is `rect.top + ctx.measureText('Hxg').fontBoundingBoxAscent`.
- **Group rects into lines by baseline** (0.5px tolerance), **never by `top`** — a
  larger-`font-size` span shares a baseline but not a top.
- `pitch` is **measured** between consecutive baselines. Never read from CSS
  `line-height`.
- Never scale metrics between sizes: Chromium rounds `fontBoundingBox*` to integers
  per size.
- Whitespace collapsing means DOM offsets != rendered offsets. Build the run map on
  the **rendered** string. NBSP does not collapse.
- `characters` joins visual lines with `
` (LSEP). **Never `\n`** — that creates
  a paragraph and triggers `paragraphSpacing` in Figma.
- `sourceText` holds the pre-`text-transform` original, the SAME LENGTH as
  `characters` and indexed identically — a transform that changed the length is
  refused and reported instead.
- **Every number in `lines` is in the block's OWN units**: an axis-aligned scale
  between the block and the capture root is divided out, because the node these
  lines land on carries that transform and would apply it again. The known gap:
  under a ROTATION the lines are measured on the block's AABB, which is the
  bounding box of a quad and cannot be undone from here. `emit/svg-flat.js`
  inverts it exactly (`unbbox`, `emit.svg.text-unbboxed`); a backend that does not
  must not compensate twice.
- `Line = {i, start, end, x, w, baseline, asc, desc, frags?, spans?, words?, hyphen?}`.
  `w` is the sum of the painted glyph advances, **not** the bbox:
  - `frags:[{x,w,start,end}]` — present only when something that is not a
    character (an inline image, a float) splits the line into two or more painted
    stretches. They tessellate `[start, end)` left to right and are the only place
    the hole is visible. A consumer that ignores `frags` and stretches the line to
    `w` squeezes the glyphs.
  - `words:[{x,w,start,end}]` (2026-08-13) — measured anchor per word, written
    only for `text-align: justify` blocks (every line of one, last included) and
    only where trustworthy: axis-aligned chain, no RTL, two or more words. Unlike
    `frags` they do NOT tessellate — the gaps between them are the space
    characters, which belong to no word — and justification is the reason they
    exist: the slack goes into the word gaps, so no advance arithmetic can place
    a word. One Range measurement per word, paid only on justified blocks. A
    consumer that anchors each word at its `x` reproduces the justification
    exactly; one that ignores `words` falls back to the `textLength` tier below.
  - `spans:[{start,end,x,w}]` — the painted extent of each STYLE stretch on the
    line, one entry per contiguous piece, in logical order. A `Run` is character
    offsets and nothing else, so this is the ONLY place a backend can find where
    the run that carries a wavy underline starts and stops. Without it a
    decoration over `characters 23..41` had no extent and fell back to a straight
    line.
  - `hyphen: string` — the glyph the browser painted at a hyphenation break
    (`hyphens: auto`) and the document does not contain. **It is deliberately not
    in `characters`**: every offset in `lines`, `runs`, `frags` and `spans` indexes
    that string and `sourceText` matches it character for character, so inserting
    it would move all four at once. Its advance is ALREADY inside `w`, `spans` and
    `frags` — the browser reports it as ink of this line — so a backend paints the
    line as `characters.slice(start, end) + hyphen` and nothing else moves.
    Which character it is, is MEASURED (U+2010 vs U+002D vs a declared
    `hyphenate-character`), never assumed.
- `Run = {start, end, style, href, dy}`. `dy` is the MEASURED offset of a raised
  or lowered run (superscript, subscript, `vertical-align`) from its line's
  baseline, positive downwards. The fold that put the run on this line already took
  the offset out of the baseline, so a consumer that drops `dy` renders H₂O as H2O.
- A warning may be prose or `{code, grade, severity, message}`. A collector that
  knows what it lost states the grade; the orchestrator's regex is the last resort.

**TextStyle**, as the collector returns it and as `index.js` (`registerTextStyle`)
rewrites it into `doc.styles.text[ts_N]`. The rewrite is the one place the
orchestrator translates rather than forwards, and both spellings are normative
for the side that sees them:

| collector | SVD | notes |
|---|---|---|
| `fontSize` | `size` | the only renamed key |
| `fontFamily` / `family` | `stack` / `family` | `family` is the first entry of the stack, unquoted |
| `fontWeight`, `fontStyle`, `fontStretch` | `weight`, `fontStyle`, `stretch` | plus `italic: boolean` |
| `fontVariant` (+ `fontVariantCaps` merged in) | `variant` | see below |
| `fontFeatureSettings`, `fontVariationSettings` | `features`, `variations` | computed CSS strings |
| `letterSpacing`, `wordSpacing`, `lineHeight` | same | resolved to px numbers, never `'normal'` |
| `textTransform` | `case` | `characters` is ALREADY transformed; this says what was applied |
| `color`/`colorCss` | `fills:[{type:'solid', color, srcCss}]` | |
| `decorations` (array) | `decoration` (array \| **null**) | |
| `strokeWidth`, `strokeColor` | same | |
| `ascent`, `descent`, `fontCss` | same | measured metrics for the face that actually painted |

- **`decoration` is an ARRAY, or null — never a single object.** `text-decoration`
  does not inherit, it PROPAGATES: an `<a>` and a `<span>` inside it can each
  contribute one, and `underline line-through` is one declaration and two lines.
  Order is innermost first (`[0]` is the decoration nearest the glyphs). An entry
  is `{line, style, color, colorCss, thickness, offset, offsetCss}`; `thickness`
  and `offset` are `null` for `auto`, which is the honest answer — the value is
  then the font's, and the font's underline position is not in this document.
  Reading `decoration.line` off the array returns `undefined`, which is how a
  consumer silently emitted NONE for every underline in the document.
- **`variant` is the whole `font-variant` shorthand with `font-variant-caps`
  merged in.** Chromium drops `small-caps` from the shorthand's serialization as
  soon as another longhand is set, so both are read and joined. It therefore
  carries two unrelated things at once — the caps half (`small-caps`,
  `all-small-caps`, …), which repaints letters, and the OpenType half
  (`tabular-nums`, `lining-nums`, `slashed-zero`, …), which selects figures and
  ligatures. Backends split it themselves (`emit/pdf.js` `splitSmallCaps`,
  `emit/figma-json.js` `variantOf`); there is no second field, so nobody has two
  places to look.
- **`strokeWidth` / `strokeColor` are `-webkit-text-stroke`**, resolved
  (`strokeColor` falls back to `color`, and is `null` when the width is 0). It is
  centred on the glyph outline and painted over the fill — in CSS, in SVG and in
  Figma alike — so a backend that has a stroke primitive can carry the number
  across unchanged.

### `packages/vector/src/collect/image.js`

```js
/** @returns {Promise<{asset:Asset, fill:Paint, warnings:string[]}|null>} */
export async function collectImage (el, cs, ctx = {})
```
Read `currentSrc` (not `src`) and `naturalWidth/Height`. **If `currentSrc` is an SVG,
inline and vectorize it — do not rasterize.** Honour `object-fit`/`object-position`
as a crop plus matrix: the returned `fill` carries `crop` (the visible region in
the asset's OWN source pixels) and `transform` (a 2x3 mapping the unit square of
that crop onto the node's border box in px), and between them those express all
five `object-fit` values. `null` only when the element carries no replaced content
at all — the one case with nothing to report, because nothing was lost.

**Passthrough markup carries no active content.** `<script>` elements and `on*`
attributes are removed before serialization (`stripActiveContent`) and reported as
`collect.image.active-content-stripped`, grade `E` — nothing visual is lost. This is
not hygiene theatre: on 2026-08-08 a dev server injecting a live-reload snippet into
every `.svg` it served put three of them inside one capture, and the exported file
stopped parsing at the first `// <![CDATA[`. The engine copies what the page gave it;
it does not have to copy that.

`asset.kind === 'vector'` means the caller must emit a `vector` node and put the
markup on **`node.svg`**, with the placement on `node.svgPlacement`. Both emitters
read `node.svg`; while nobody wrote it, every inline `<svg>` exported as an empty
group with an `emit.svg.image-no-data` per icon.

### `packages/vector/src/collect/mathml.js`

```js
/** @returns {Promise<{asset:Asset, fill:Paint, warnings:Array, fontStyles:Array}|null>} */
export async function collectMathML (el, cs, ctx = {})
```

Native MathML stays opaque to the HTML paint walk and is kept as a `vector`
node. The collector reads the mounted clone's mathematical layout and produces
native SVG text and geometry for presentation math. Its asset and placement use
the same interface as `collectImage`; it adds neither raster content nor
`foreignObject`. Root CSS paint and transforms remain the orchestrator/emitter's
responsibility. Excluded, phantom and annotation content must not become visible
text. Unsupported paint and approximated glyph geometry carry diagnostics.

`fontStyles` contains collector `TextStyle` objects plus `characters`, the actual
code points emitted in that style (including MathML `math-auto` substitutions).
The orchestrator registers them in `doc.styles.text` and keeps transient
`st.markupTextUses = [{nodeId, style, characters}]`. These uses join font coverage,
embedding and missing-font diagnostics; they do not create phantom SVD text
nodes. MathML behavior follows [MathML Core](https://www.w3.org/TR/mathml-core/).

### `packages/vector/src/collect/font.js`

```js
/** Mutates doc.assets and styles.text[*].font; every non-embed is a diagnostic. */
export async function collectFonts (st, report)
```

The asynchronous other half of `collect/text.js`'s family resolution (2026-08-13),
run by `assemble` inside the mount, after every text style exists and before
`declareFonts`. For each style the resolution marked `webfont: true` it finds the
`@font-face` rule the browser matched — same ordering as `pickFace`/`nameTableFor`,
whose helpers (`weightRange`, `parseUnicodeRange`, `parseFontNames`, `dataUriBytes`)
it imports rather than re-deriving — fetches the first loadable `src` with
`force-cache`, and writes an asset `{kind: 'font', data, mime, cssFamily,
weight | weightRange, italic, nameTable?, subset: false}` with `style.font`
pointing at it. That is the key `fontFaceRules` and `measuredFontTravels` (emit)
and `fontOf` (figma-json, reads `nameTable`) have always looked for.

What it refuses, each with its own `assets.*` code: a family whose rule no
readable stylesheet declares (`font-rule-missing`; cross-origin CSS is re-read
over HTTP first, `font-css-unreadable` when that fails too), a family served in
unicode-range subsets none of which alone covers every painted code point
(`font-uncovered` — embedding one subset would pin `textLength` to a file
missing characters), and a failed fetch (`font-fetch-failed`). It does not
subset (the file travels whole; size stated per face in `font-embedded`), and
`embedFonts: false` skips it entirely. System and locally-installed faces have
no bytes a page can hand over and stay `declareFonts`' story. The fixture is
`demo/vector.html` -> `fx-font`, whose family name exists nowhere installed and
whose baseline was measured on a render page with no stylesheets at all.

### `packages/vector/src/paint.js`

```js
/**
 * Pure given a snapshot: builds the containment tree, assigns paint order, prunes.
 * @returns {{nodes:Record<string,SVDNode>, rootId:string, diagnostics:Diagnostic[]}}
 */
export function buildPaintTree (rootEl, ctx = {})
export function isStackingContext (el, cs, parentCs)  // pure, testable from Node with a fake cs
export function paintOrder (siblings)        // CSS 2.1 Appendix E -> integer z per sibling
```

`parentCs` is optional and is what decides the flex/grid-item rule (`z-index` on
a flex item creates a stacking context whatever its `position`); without it that
one rule falls back to `getComputedStyle`, and with no DOM it is skipped.
`buildPaintTree` **refuses a detached root**: the engine walks snapdom's mounted
clone, and an unmounted clone computes to nothing and would prune to one empty
node that looks like a page with nothing on it.

**The tree is DOM containment. Paint order is an index, not a hierarchy.** A node is
promoted out of its DOM parent only when *both* hold: (a) the correct paint order is
not expressible by reordering siblings within the parent (negative `z-index` behind
the parent background, `position:fixed`, top layer), **and** (b) the divergence is
geometrically observable — the node's box overlaps some box whose relative order
would change. Every promotion emits a `diagnostics` entry with `from`, `to`, `reason`.

Pruning: an element emits a node only if it has a fill, stroke, effect, clip, mask,
transform, `opacity < 1`, is text, or is replaced. Everything else is pass-through and
is flattened when it has <= 1 child. **`opacity < 1` always forces a `group`**, even
with a single child.

### `packages/vector/src/emit/svg-flat.js`

```js
/**
 * @param {SVDDocument} doc
 * @param {object} [options]
 * @param {boolean} [options.debugPaint=false]
 * @param {'auto'|'always'|'never'} [options.textPerLine='auto']
 * @param {boolean} [options.exactShadows=false]
 * @returns {{svg: string, diagnostics: Diagnostic[]}} standalone SVG markup plus
 *   what the SVG backend itself could not represent. The result also behaves as
 *   the markup string (`toString`, `length`, `valueOf`) for callers written
 *   against the older signature.
 */
export function svdToSvg (doc, { debugPaint = false, textPerLine = 'auto', exactShadows = false } = {})
```
Pure. No DOM. **No `foreignObject` anywhere** — that is the entire point. SVG blur
sigma is `blur / 2`. `debugPaint` tints nodes by stacking-context depth and gives
each a `<title>` naming its id, grade and paint order.
The returned `diagnostics` carry `{code, grade, severity, message, node?}` and are
meant to be concatenated onto `doc.diagnostics` — an approximation the emitter made
is a loss like any other, and `toSvg` merges them and degrades the nodes they name.
The same notes also go into an XML comment under the `<svg>` tag, so the file is
self-describing on its own.

**The text shape is NOT one `<text>` with a `<tspan>` per line, and has not been
since the Figma findings.** An earlier revision of this file said it was; three
consumers built on that sentence. What the emitter does:

- **One `<text>` per positioned piece** — per visual line, and per `frag` within a
  line — each at its own measured baseline, whenever the block occupies more than
  one piece. A block that fits on ONE line stays a single `<text>`, which is the
  more editable object and has nothing to reflow. `textPerLine` moves that line:
  `'auto'` (the default, as described), `'always'` (split even a single line),
  `'never'` (the SVG-native shape, one element per block — and the lines stack on
  top of each other in Figma). **Why**: Figma discards the `x`/`y` of an interior
  `<tspan>` and reflows with its own leading.
- **`textLength` + `lengthAdjust="spacingAndGlyphs"` ONLY when the font binary
  travels in the file** (`fontFaceRules` / `measuredFontTravels`). Pinning a line
  to a width measured with the page's font, in a viewer that substituted the
  family, does not degrade gracefully: it squeezes the glyphs into a width they
  were never going to produce. Without a binary the width is the viewer's to
  decide and `emit.svg.text-length-viewer-width` says so. **Justified lines are
  the exception (2026-08-13), in two tiers.** Where the collector measured
  per-word anchors (`line.words`), every anchored word becomes a `<tspan x="…">`
  at the x the browser painted and `textLength` is OMITTED — absolute anchors
  and a whole-piece length would fight over the same glyphs
  (`emit.svg.text-justified-words`, grade E: exact, whatever font renders;
  measured on `challenges/fx-type` -> `.ty-just`, diffMean 6.25 -> 3.61, and on
  `vector/fx-font`, 8.62 -> 4.43). Where it could not (skewed chain, RTL,
  one-word lines), a justified non-last line is pinned even without a binary,
  with `lengthAdjust="spacing"` (glyphs unstretched) and
  `emit.svg.text-justified-length`, grade A — unpinned, the justification is
  simply gone and every word lands left of where the page painted it.
- **The `<text>` carries the typography of its dominant run**
  (`inheritedTextAttrs` / `dominantStyle`) and the `<tspan>`s carry only what
  differs, with explicit resets (`stroke="none"`, `font-variant="normal"`) where a
  run does not inherit. Figma builds its TextNode from the `<text>` element and
  does not look inside it for the real values.
- **A run raised or lowered off the baseline becomes its own positioned piece**
  (`pushRange`), never a relative `dy` inside its line: `dy` is cumulative, and an
  importer that carries part of the chain drifts everything after it.
- **`line.hyphen` is painted**, appended INSIDE the last `<tspan>` of the piece
  that ends the line (`emitText`) — not after it, where a bare text node between
  tspans is a separate character an importer can misplace. Its advance was already
  inside the measured width, so nothing moves. `emit/figma-json.js` deliberately
  does not paint it — see below.
- **`-webkit-text-stroke` is `stroke` + `stroke-width`** on the text (exact: both
  are centred on the outline and SVG's paint order is WebKit's).
  `background-clip: text` becomes the `<text>`'s own fill, never a glyph mask.
  `text-decoration-style: wavy` becomes a `<path>` at Chromium's measured
  wavelength and amplitude, ending where the run does, with no `<clipPath>`.
- **A `<pattern>` wrapper is emitted only when the layer genuinely tiles inside
  the painted box.** Figma does not resolve `fill="url(#pattern)"` — the node does
  not degrade, it disappears — and a single tile covering its own box never needed
  the wrapper.
- **`box-shadow` is `feDropShadow` by default**, not the exact
  `feMorphology → feGaussianBlur → feOffset → feFlood → feComposite → feMerge`
  chain: Figma runs part of that chain and paints a black rectangle. `spread` has
  no `feDropShadow` parameter and is folded into the blur, loudly
  (`emit.svg.shadow-spread-in-blur`). `{exactShadows: true}` asks for the exact
  chain back — exact in a browser, unimportable. **This is a measured pixel
  regression accepted as a product decision**, recorded in
  `test/vector-baselines.json` under `_acceptedRegressions`.

### `packages/vector/src/emit/figma-json.js`

```js
/** @param {SVDDocument} doc @returns {FigmaPayload} */
export function svdToFigma (doc)
```

**`svdToFigma` is the single canonical translator and `figma-plugin/code.js`
consumes its output verbatim.** There must not be a second SVD-reading path
inside the plugin. The plugin validates `payload.version`, then builds; if it
finds itself deriving Figma properties from raw SVD fields, that logic belongs
in `svdToFigma` where it can be tested in Node without the Figma sandbox.

```js
FigmaPayload = {
  version: 1,
  fonts: [{ key, family, style, weight, italic, stack,
            nodes, chars, nodeIds, canOutline, canRaster }],  // for the preflight UI
  root: 'n_0',
  nodes: { [id]: FigmaNodeSpec },
  diagnostics: [...],                 // ONLY what the translation itself lost
  document: {                         // everything the plugin cannot re-derive
    assets,                           // asset bytes, addressed by id from image fills
    capture,                          // the capture header
    report,
    diagnostics,                      // what the ENGINE lost, kept apart so the
  },                                  //   two lists never double-count
}
```
The plugin is handed this object and nothing else — it never sees the SVD — so
`document` is not optional decoration: without it there are no image bytes and no
provenance. Every node also carries `provenance` (for `setPluginData`), and text
nodes carry `outlineAsset`/`rasterAsset`.
`FigmaNodeSpec` uses Figma's own vocabulary: `type` in caps, `x`/`y`/`width`/`height`
(never `frame`), `fills`/`strokes`/`effects` in Figma paint shape, and text ranges
as serialized `setRange*` instructions. Gradient geometry arrives as a finished
`gradientTransform` — the plugin never sees `unit`.
Pure. Produces the payload the Figma plugin consumes — **plain data, no Figma API
calls** (those live in the plugin sandbox). Gradient geometry converted to
`gradientTransform`. Per-side stroke weights only on rect-like nodes. Colors stay
0..1 floats (Figma's native form).

A composed shape (a per-side border, an outline, an image that does not fill its
box) becomes a node of its own with `composed: <kind>` and an id `<owner>__cN`;
`root.siblings` holds the ones the capture root could not adopt, which the plugin
must append NEXT to the root. `degrade: {action:'OUTLINE'|'RASTER', reason, asset}`
marks a node the Figma model cannot hold at all (a skew, `text.emit.mode`).

**A TEXT node's own vocabulary**, since it is the one place the payload is richer
than a naive read of the SVD suggests:

```js
{ characters, fontName:{family,style}, fontSize, fills, lineHeight:{unit,value},
  letterSpacing:{unit,value}, paragraphSpacing, textCase:'ORIGINAL',
  textAutoResize:'NONE', textAlignHorizontal, textAlignVertical,
  strokes, strokeWeight, strokeAlign:'CENTER',    // -webkit-text-stroke, node-level
  setRange: [{ start, end, fontName, fontSize, fills, hyperlink,
               textDecoration, textDecorationStyle?, textDecorationColor?,
               textDecorationThickness?,
               letterSpacing?,      // per run — the Plugin API HAS setRangeLetterSpacing
               textCase?,           // SMALL_CAPS / SMALL_CAPS_FORCED, from `variant`
               baselineShift? }],   // measured `run.dy`; no Figma setter, carried anyway
  textLayout: { pitch, lineCount, baselines, lineWidths, lineX,
                firstBaselineFromTop, trailingSpacingComp, widthSlackPx,
                hyphenLines, svgPasteWidthDelta } }
```

`textLayout` is consumed by no setter: it is the measured browser layout, kept so
the plugin can check its result against it and so the export carries a record of
what the browser saw.

**The two routes into Figma do not lose the same things.** This is
counter-intuitive and it is the source of repeated rediscovery, so it is
normative here: `letter-spacing`, `-webkit-text-stroke` and small caps ARE in the
Plugin API (`setRangeLetterSpacing`, `TextNode.strokes`, `setRangeTextCase`) and
this payload carries all three; **Figma's SVG importer discards all three**, which
is measured in FIGMA_FINDINGS.md §5 (a 22px/700 line arriving 19% wide, +50px of
it ignored letter-spacing). The hyphen goes the other way: `emit/svg-flat.js`
paints `line.hyphen` and this file deliberately does not — a Figma TextNode
reflows to its own box with its own substituted font, so the break moves and a
hyphen written into `characters` would land inside a word
(`figma.text-hyphen-dropped`; the lines it happened on are in
`textLayout.hyphenLines`).

**What has no Figma equivalent at all, and is therefore declared, never dropped
quietly:** the `colorMatrix` effect (Figma's effect list is DROP_SHADOW,
INNER_SHADOW, LAYER_BLUR, BACKGROUND_BLUR — there is no colour-matrix effect, no
colour-matrix paint and no blend mode that stands in for one, so
`figma.effect-colormatrix-dropped` names the CSS function from `srcCss` and says
whether it was `filter` or `backdrop-filter`); the OpenType half of `variant`
(`tabular-nums` and friends — the Plugin API exposes no feature control, same wall
as `font-feature-settings`); `-webkit-text-stroke` when the runs of a block
disagree, because a Figma stroke is per-NODE and applying it would contour glyphs
the page does not contour; and per-range baseline shift.

### `packages/vector/src/emit/pdf.js`

```js
/**
 * @param {SVDDocument} doc
 * @param {object} [options]  {compress, background, shadowLayers, quality,
 *                             onDiagnostic, onWarn, pages, links}
 * @returns {Promise<Uint8Array>}  the bytes, with a non-enumerable `diagnostics`
 */
export async function svdToPdf (doc, options = {})
```
The third backend, and the one with the smallest primitive set: PDF has no blur,
so every blurred shadow is `shadowLayers` concentric copies, and it has no
colour-matrix either. `pages` is finished page geometry from a caller that owns
the pagination — this emitter paginates nothing on its own. The diagnostics ride
on the returned array AND are written into the file as an uncompressed object off
the catalog, so `strings out.pdf` finds them: an approximation that only reaches a
stream nobody opens is a silent degradation.

### `packages/vector/src/index.js`

```js
/**
 * @param {object} [options]  {mode, maxNodes, maxDepth, exclude, fetchTimeout,
 *                             maxAssetBytes, silent, debugPaint}
 * @returns {object} snapdom plugin — {name, beforeRender, defineExports}
 */
export function vector (options = {})
export { svdToSvg, svdToFigma }
export default vector
```

`beforeRender(state)` does one thing: `state.options.__vectorHandoff = handoffFrom(state)`.
Everything else is in the exports it declares —

```js
defineExports () {
  return {
    vector:    (ctx, opts) => buildDocument(ctx, {...options, ...opts}),   // result.toVector()
    vectorSvg: (ctx, opts) => svgFrom(await buildDocument(ctx, ...), ...), // result.toVectorSvg()
  }
}
```

— which mount the clone, walk it, validate the document and `unmount()` in a
`finally`. Per-capture options may be passed to the factory or to the export; the
export's win.

There is **no** `toVector(element)` and **no** `options.snapdom`: the caller writes
the `snapdom()` call, so every capture option is already theirs to set. `dpr`,
`outerTransforms` and `burst` are read before the first hook and cannot be forced
from here in any case.

Orchestrator only: builds ctx, calls `buildPaintTree`, collects per node, assembles
the document, fills `report`, runs `validate` and **throws on invalid output**.
Every collector returns `{...data, warnings: []}`; the orchestrator prints them with
the `[snapdom-vector]` prefix and folds them into `diagnostics`.

It also owns the two wiring steps a collector cannot do from where it stands, and
both were silent holes until they existed: `wireMasks` turns `collectBox`'s mask
layers into the node `node.mask` references, and `applyImage` writes `node.svg` +
`node.svgPlacement` for a vector asset.

## Shared node shape

```js
{
  type: 'frame',                                  // NodeType
  name: '#plan-card',                             // human-readable, from tag/id/class/text
  frame: { x, y, w, h },                          // relative to emitted parent
  abs:   { x, y, w, h },                          // relative to capture root
  paint: { z: 0, stackingContext: false },
  transform: null,                                // {m, decomposed} | null
  opacity: 1,
  blend: 'normal',
  clip: null,                                     // {mode:'rect'|'path', box:'padding', radii, d?} | null
  fills: [], strokes: [], effects: [],
  text: null,                                     // only on type:'text'
  fidelity: { grade: 'E', notes: [] },
  source: { tag, path, css: {} },
  children: [],
}
```

Optional, and read by both emitters when present:

```js
  radii: [[rx,ry] × 4],       // tl, tr, br, bl — CSS §5.5 overlap factor already applied
  isolate: true,              // the node isolates its children's blending
  mask: { node: 'n_7', type: 'alpha'|'luminance' },   // a REFERENCE, never a paint
  svg: '<svg …>',             // passthrough markup for an inline/vector asset
  svgPlacement: { crop, transform, clipBox },         // where that markup lands
  control: { kind, … },       // a native form widget, described — see below
```

### `node.control` — the one thing on a node that is not paint

```js
  control: {
    kind: 'checkbox'|'radio'|'range'|'select'|'text'|'email'|…,  // what the UA draws
    checked: false, indeterminate: false,   // checkbox/radio
    fraction: 0.62, value: '62', min: 0, max: 100,   // range/progress/meter
    accent: [r,g,b,a], accentSource: 'accent-color'|'ua-default',
    ink: [r,g,b,a],                          // tick/thumb colour, by luminance over accent
    border: [r,g,b,a], track: [r,g,b,a], surface: [r,g,b,a],
    direction: 'ltr'|'rtl', disabled: false,
  }
```

**Why it exists and why it is not fills.** A native control is the one thing on a page
that `getComputedStyle` cannot describe: Chromium paints the tick, the thumb, the track
and the chevron itself, from the element's TYPE and STATE, and no CSS property in the
cascade mentions any of them (`collect/box.js` files `collect.box.form-control` saying
so). So the collector records the semantics — what kind of control, in what state, with
which accent — and a backend reconstructs the picture from it at Chromium's measured
proportions, or declines to and says nothing was drawn. It is deliberately NOT a fill
list: fills would freeze one platform's drawing into the document, and a consumer that
knows better (Figma, which has real components) could never recognise the widget again.

`describeWidget` (`paint.js`) returns `null` — and the field is absent — when
`appearance: none` says the author replaced the widget with their own CSS, which the
ordinary collectors already read. Two checkboxes in one box is worse than none.

**Who reads it.** `emit/svg-flat.js` draws it (`emit.svg.control-reconstructed`, grade
A, one per control: a reconstruction is not a capture). `emit/figma-json.js` and
`emit/pdf.js` ignore it, so the widget is missing there and `B4.form-control` remains
the whole story on those two paths.

## What the Figma importer does — read `FIGMA_FINDINGS.md` before changing an emitter

**The default flow into Figma is the universal SVG (product call, Martin,
2026-08-13):** in practice it pastes better into today's Figma than the h2d
clipboard channel lands, so recommend `toVectorSvg()` → paste first, with the
importer's losses below as the accepted cost. h2d stays as the channel for when
the editable text layer outweighs paste fidelity. Do not bend the universal
emitter toward this importer — that is what `target: 'figma'` and h2d are for.

Five behaviours of Figma's SVG importer are the reason the emitters look the way
they do. Every one was **isolated by changing a single thing in the SVG and
pasting into Figma again** — none is deduced from documentation, and each has its
artefact in `out/vector/_clone-*.svg`. They are summarised here only so nobody
rediscovers them the hard way; the measurements, the controls and the ideas
already tried and rejected are in `FIGMA_FINDINGS.md`, which is normative for
this subject.

1. **The `<text>` element must carry its own typography** (§1). Figma builds its
   TextNode from `<text>` and does not look inside for a `<tspan>` with the real
   values: a bare `<text>` lands at the importer's default size and weight.
2. **Interior `<tspan>` `x`/`y` are discarded and the block is reflowed with
   Figma's own leading** (§2). Hence one `<text>` per visual line.
3. **`fill="url(#pattern)"` is not resolved and the whole node disappears** (§3)
   — it does not degrade, it vanishes. Hence: no `<pattern>` wrapper for a layer
   that does not actually tile.
4. **A filter chain is only partly executed** (§4). Figma keeps the `feFlood` and
   the blur and loses the `feComposite` that cuts the colour to the silhouette, so
   the exact shadow chain arrives as a black rectangle. Hence `feDropShadow`, at
   the cost of `spread`.
5. **`letter-spacing` is ignored on paste, and font STACKS are not resolved**
   (§5, the one with no workaround). Measured: 376.8px of text arriving at 449px,
   +50px from the ignored spacing and +23px from falling back to Inter. Four ways
   of forcing the width through the SVG were tried and all four failed — do not
   retry them. Consequence: anything anchored to the end of a line drifts, which
   is one cause behind three symptoms (the floating wavy underline, the short
   justified line, the misplaced hyphen).

The corollary that keeps being got backwards: **the SVG-paste route is not the
lossless one.** For text metrics the Plugin API payload is strictly richer —
`letter-spacing`, per-range small caps and a text stroke all survive it and none
of them survives a paste. See the TEXT block under `emit/figma-json.js`.

## PDF and Vector stay independent

Both exporters are MIT licensed and ship together in `@zumer/snapdom-plugins` 4.x
(`packages/plugins/pdf` and `packages/plugins/vector`), and **neither may import the
other.** The rule started as a licence boundary, when `@zumer/snapdom-pdf` and
`@zumer/snapdom-vector` were sold separately, and it stays because each exporter can
then be shipped and fixed on its own.

The history is worth keeping because it is the reason for the shape. Until 2026-08-08
`emit/pdf.js` imported the byte-level writer through `../../../pdf/src/pdf-writer.js`
— a relative path into the other product, undeclared in `package.json`, and visible to
users as `[snapdom-pdf]` warnings coming out of a vector capture. It was then lifted
into a shared private package, `@zumer/pdf-writer`, that both plugins depended on by
name and each build inlined. On 2026-08-28 the PDF product moved to a repository of
its own, and the shared package went with the split: **each product now owns its copy
of the writer as source** — `packages/vector/src/writer/` here, `src/writer/` there.

That trade is deliberate and it is not free. Nothing can leak between the two any
more, and nothing can be fixed in both at once either: a correction here does not
reach the PDF product, and the two will drift. That is the cost of the boundary being
a repository rather than a rule.

Two rules follow:

- **Nothing in `src/writer/` may name a product or know what it is drawing.** The
  warning prefix is injected by whoever loaded it (`setWarnPrefix`).
- **A module only this product needs belongs to this product.** There is no shared
  package left to put it in, and reaching into the other repository is not available.

## House rules

- Match the surrounding code: ESM, 2-space indent, no semicolon-free style changes,
  JSDoc on exported functions, comments only where the *why* is not obvious.
- Every approximation produces a `warnings` entry. **Nothing degrades silently** —
  this is the product's differentiator, not a nicety.
- Pure modules (`css/*`, `emit/*`, `paint.js` predicates) must run in Node without a
  DOM so the harness can fuzz them.
- No `new Function`, no `eval` — they detonate under a page's CSP. snapStudio already
  has this bug at `content/index.js:236`; do not repeat it.