@weasel-js/svg 1.9.3 → 1.10.0

package/README.md

@@ -20,16 +20,13 @@ import { /* … */ } from '@weasel-js/svg';
 
 ## Text fidelity
 
-Two things worth knowing before you rely on a text round-trip.
-
 **The format is exactly as expressive as the runs model.** A run can turn
 `underline` on but not off, so `<g text-decoration="underline"><text
 text-decoration="none">` has no representation on the way in — and neither
 does "this word is not underlined inside an underlined node" on the way out.
-That is not loss in the serializer; it is the model, faithfully reproduced. A
-future "un-underline this word" feature needs a model change, not a
-serializer change. (Contrast `letterSpacing`, where the model *was* more
-expressive than the serializer — that was a real data-loss bug, since fixed.)
+That is not loss in the serializer; it is the model. An
+"un-underline this word" feature needs a model change, not a
+serializer change.
 
 **Decoration is treated as inherited.** Real CSS says `text-decoration` is
 not inherited and cannot be cancelled by a descendant; a browser shown
@@ -151,8 +148,13 @@ query against the same environment.
 `@supports` asks whether this parser honors a declaration, not whether a browser
 parses it: `(fill: red)` holds, `(display: grid)` and `(clip-path: url(#c))` do
 not, because nothing reads them from a stylesheet. `@import` is not fetched, and
-each one is reported in `warnings`. Rules inside `@layer`, `@container` and
-other at-rules are skipped.
+each one is reported in `warnings`. Rules inside other at-rules are skipped.
+
+`@container` size queries are answered against the root `<svg>`, the one box a
+parse knows the size of: the same viewport `@media` sees. They apply to its
+descendants when the root declares `container-type: size` or `inline-size`
+(or the `container` shorthand), by name when the query gives one. A style
+query never holds.
 
 ## Raster images
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Mat3 } from '@weasel-js/geom';
-import { Path, FillStyle, ScreenLength, StrokeAlign, MarkerRef, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, RenderNeeds, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
+import { Path, Paint, ScreenLength, StrokeAlign, MarkerRef, StyledRun, TextStyle, TextVerticalAlign, Fill, Stroke, PoseLinear, MarkerEntry, RenderNeeds, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
 
 /**
  * Media Queries 4 evaluation against a fixed environment.
@@ -41,39 +41,25 @@ declare const DEFAULT_MEDIA_ENVIRONMENT: SvgMediaEnvironment;
 declare function evaluateMediaQuery(list: string, env: SvgMediaEnvironment): boolean;
 
 /**
- * Public types for `@weasel-js/svg`. The package exposes a flat,
- * discriminated-union node model (`SvgNode`) that mirrors the SVG element
- * tree but uses weasel-native leaf data (`Path`, `FillStyle`) for geometry and
- * paint.
- *
- * Parsing collapses every `transform="..."` onto its descendants' geometry,
- * so the `SvgNode` tree returned from `parseSvg` never has a non-identity
- * group transform. Consumers may still construct groups with explicit
- * transforms before serializing, in which case the serializer emits a
- * single `matrix(a b c d e f)` on the `<g>`.
+ * Public types for `@weasel-js/svg`: a node model (`SvgNode`) that mirrors
+ * the SVG element tree but uses weasel-native leaf data (`Path`, `Paint`)
+ * for geometry and paint.
  */
 
 /**
- * Opaque pass-through bag for namespaced XML content.
- *
- * weasel-svg does not interpret the contents — it only ensures that any
- * attributes or child elements in a *declared* XML namespace round-trip
- * losslessly through parse → serialize. Consumers (e.g. an app-specific
- * bridge layer) hang their domain semantics off this structure.
+ * Opaque pass-through bag for namespaced XML content. The package does not
+ * interpret it; attributes and child elements in a *declared* XML namespace
+ * round-trip losslessly through parse → serialize.
  *
- * Keyed by namespace prefix (the prefix is a write-time choice; the URI
- * is the canonical identifier and is supplied via `ParseOptions.namespaces`
- * / `SerializeOptions.namespaces`).
+ * Keyed by namespace prefix. The URI is the canonical identifier and is
+ * supplied via `ParseOptions.namespaces` / `SerializeOptions.namespaces`.
  */
 interface NamespaceMeta {
     [prefix: string]: {
         /** Local-name → string-value map for attributes in this namespace. */
         attrs?: Record<string, string>;
-        /**
-         * Child elements in this namespace, keyed by local name. Each entry
-         * is an array because a namespace can host multiple sibling elements
-         * with the same tag (e.g. `<wd:layer/><wd:layer/>`).
-         */
+        /** Child elements in this namespace, keyed by local name. An array
+         *  because siblings can share a tag. */
         elements?: Record<string, NamespacedElement[]>;
     };
 }
@@ -88,21 +74,17 @@ interface NamespacedElement {
 }
 /**
  * 2x3 affine matrix in SVG's `matrix(a b c d e f)` order, mapping
- * `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`.
- *
- * The same order the kernel's affine tier uses, so this is that type under
- * the name the SVG spec gives it — not a parallel one. An `SvgGroupNode`'s
- * transform and a geom `Mat3` are interchangeable without a conversion.
+ * `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`. It is geom's `Mat3`, so the
+ * two are interchangeable without a conversion.
  */
 type Matrix = Mat3;
 
-/** Identity matrix — useful as a default in tests / constructors. */
+/** The identity matrix. */
 declare const IDENTITY_MATRIX: Matrix;
 /**
- * FillStyle description in the SVG sense — either explicit `none`, a solid
- * color, or a reference to a weasel-native gradient `FillStyle`. Solid colors
- * are normalized to `#rrggbb` strings; opacity is carried separately so
- * `fill-opacity` and `stroke-opacity` round-trip cleanly.
+ * A paint in the SVG sense: explicit `none`, a solid color, or a weasel-native
+ * gradient `Paint`. Solid colors are normalized to `#rrggbb` strings, with
+ * opacity carried separately.
  */
 type SvgPaint = {
     kind: 'none';
@@ -112,14 +94,13 @@ type SvgPaint = {
     opacity?: number;
 } | {
     kind: 'gradient';
-    paint: FillStyle;
+    paint: Paint;
 };
 /** Stroke description: a paint plus structural line parameters. */
 interface SvgStroke {
     paint: SvgPaint;
     /** World units, or `{ px }` for a width that holds its rendered thickness
-     *  however the document is scaled — SVG's `vector-effect="non-scaling-stroke"`.
-     *  Literally the kit's own unit, not a second spelling of it. */
+     *  however the document is scaled — SVG's `vector-effect="non-scaling-stroke"`. */
     width: ScreenLength;
     opacity?: number;
     /** `stroke-linecap`. Default per SVG spec is `'butt'`. */
@@ -146,10 +127,8 @@ interface SvgStroke {
     markerEnd?: MarkerRef;
 }
 /**
- * Leaf node: a path geometry plus fill/stroke. All other v1 shapes
- * (`<rect>`, `<ellipse>`, etc.) are lowered to this representation on
- * parse — `<rect>` uses weasel's `RectPath` fast-path subtype when
- * possible, everything else becomes a `PolygonPath`.
+ * Leaf node: a path geometry plus fill/stroke. Other shapes (`<rect>`,
+ * `<ellipse>`, etc.) are lowered to this on parse.
  */
 interface SvgPathNode {
     kind: 'path';
@@ -162,14 +141,17 @@ interface SvgPathNode {
      *  center of the underlying `path` geometry. Emitted as SVG
      *  `transform="rotate(angleDegrees cx cy)"`. */
     rotation?: number;
+    /** Kept by `ParseOptions.keepHidden` from content SVG does not render:
+     *  `display="none"` here, or a leaf under `visibility="hidden"`. Written
+     *  back as `display="none"`. */
+    hidden?: boolean;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
 }
 /**
- * Group node: an SVG `<g>`. On parse, `transform` is always omitted (any
- * `transform` attribute is collapsed onto descendants' geometry). On
- * serialize, a non-identity `transform` is emitted as
- * `matrix(a b c d e f)`.
+ * Group node: an SVG `<g>`. Parsing collapses any `transform` attribute onto
+ * the descendants' geometry, so a parsed group never has one. On serialize, a
+ * non-identity `transform` is emitted as `matrix(a b c d e f)`.
  */
 interface SvgGroupNode {
     kind: 'group';
@@ -182,21 +164,21 @@ interface SvgGroupNode {
      *  unions them and a `Path` holds one outline. */
     clip?: Path;
     opacity?: number;
+    /** Kept by `ParseOptions.keepHidden` from content SVG does not render:
+     *  `display="none"` here, or a leaf under `visibility="hidden"`. Written
+     *  back as `display="none"`. */
+    hidden?: boolean;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
 }
 /**
- * Text leaf node. Mirrors the kit's `TextPose` shape — a bounding box plus
- * text content, optional rich-text `runs` (per-range styling), and an
- * optional `TextStyle` for the node-wide defaults.
+ * Text leaf node: a bounding box plus text content, optional per-range
+ * `runs`, and an optional `TextStyle` for the node-wide defaults.
  *
- * Note on SVG text geometry: native `<text>` flows from a baseline; it
- * doesn't have width/height attributes. The serializer emits
- * `dominant-baseline="text-before-edge"` so `y` is the top of the text
- * box, plus `data-weasel-width` / `data-weasel-height` so weasel's
- * explicit box dimensions round-trip losslessly. External SVG text
- * (lacking the data-* attrs) imports with the width the kit's text layout
- * measures — an em-based estimate when no registered font can — and
+ * Native `<text>` has no width or height, so the serializer writes the box
+ * as `data-weasel-width` / `data-weasel-height`. External SVG text, lacking
+ * them, imports with the width the kit's text layout measures — an em-based
+ * estimate when no registered font can — and
  * `height = fontSize * lineHeight * (lineCount || 1)`.
  *
  * `x` here is always the box's left edge. In the SVG it is the
@@ -210,24 +192,23 @@ interface SvgTextNode {
     height: number;
     /** Plain text. When `runs` is set, `runsToPlainText(runs)` must equal `text`. */
     text: string;
-    /** Optional per-range styling — same shape as `TextPose.runs`. */
+    /** Per-range styling. */
     runs?: StyledRun[];
-    /** Node-wide typography. Defaults applied at render time via `resolveTextStyle`. */
+    /** Node-wide typography. */
     style?: TextStyle;
     /** Where the laid-out text sits inside the box — `kit:text`'s
      *  `data.verticalAlign`. SVG text has no box to align in, so this rides in
      *  `data-weasel-vertical-align` and other readers draw the text top-aligned. */
     verticalAlign?: TextVerticalAlign;
     /**
-     * Node-wide glyph paint, the `FillStyle` / `Stroke` a kit text node holds
-     * in `data.fill` / `data.stroke`. Not `SvgPaint`, which is the path
-     * nodes' shape — a text paint reaches the renderer through the runs, and
-     * `StyledRun.fill` / `.stroke` override these per range.
+     * Node-wide glyph paint, as the kit's `Fill` / `Stroke` rather than
+     * the path nodes' `SvgPaint`. `StyledRun.fill` / `.stroke` override these
+     * per range.
      *
      * `null` is SVG's `fill="none"`: outline-only text, painted by its stroke
      * alone. Absent takes the default black.
      */
-    fill?: FillStyle | null;
+    fill?: Fill | null;
     stroke?: Stroke;
     /** Element-level opacity (`opacity="..."`), 0..1. */
     opacity?: number;
@@ -235,22 +216,29 @@ interface SvgTextNode {
      *  AABB center `(x + width/2, y + height/2)`. Emitted as SVG
      *  `transform="rotate(angleDegrees cx cy)"`. */
     rotation?: number;
+    /** The skew or per-axis scale the box, `rotation`, and flips cannot hold,
+     *  applied about the box center inside the rotation; see `PoseLinear`.
+     *  With one, the element is written with its whole frame as a
+     *  `transform="matrix(...)"`. */
+    transform?: PoseLinear;
+    /** Kept by `ParseOptions.keepHidden` from content SVG does not render:
+     *  `display="none"` here, or a leaf under `visibility="hidden"`. Written
+     *  back as `display="none"`. */
+    hidden?: boolean;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
 }
 /**
  * Raster-image leaf — an SVG `<image>`. `href` is the element's `href` (or
  * legacy `xlink:href`) verbatim: an external URL or a `data:` URI. The
- * package neither fetches nor decodes it, so an external URL round-trips as
- * a reference and only resolves when something downstream loads it.
+ * package neither fetches nor decodes it.
  *
  * SVG's `preserveAspectRatio` is not modeled; the box is taken literally.
  *
  * With a `source` rect or a flip, the element is written as a `<g
  * data-weasel-image>` holding a nested `<svg>` viewport at the box, whose
  * `viewBox` is the source window over a unit-square `<image>` — plain SVG 1.1,
- * which any reader crops and mirrors the same way, and which `parseSvg` reads
- * back as one image node.
+ * which `parseSvg` reads back as one image node.
  */
 interface SvgImageNode {
     kind: 'image';
@@ -279,19 +267,27 @@ interface SvgImageNode {
      *  AABB center `(x + width/2, y + height/2)`. Emitted as SVG
      *  `transform="rotate(angleDegrees cx cy)"`. */
     rotation?: number;
+    /** The skew or per-axis scale the box, `rotation`, and flips cannot hold,
+     *  applied about the box center inside the rotation; see `PoseLinear`.
+     *  With one, the element is written with its whole frame as a
+     *  `transform="matrix(...)"`. */
+    transform?: PoseLinear;
+    /** Kept by `ParseOptions.keepHidden` from content SVG does not render:
+     *  `display="none"` here, or a leaf under `visibility="hidden"`. Written
+     *  back as `display="none"`. */
+    hidden?: boolean;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
 }
-/** Discriminated-union node — the leaf of the public tree. */
+/** Any node of a parsed SVG tree. */
 type SvgNode = SvgPathNode | SvgGroupNode | SvgTextNode | SvgImageNode;
 /** Options for {@link parseSvg}. */
 interface ParseOptions {
     /**
      * Map of prefix → URI for XML namespaces the caller wants surfaced.
-     * Attributes / child elements in any declared namespace are collected
+     * Attributes and child elements in a declared namespace are collected
      * into `SvgNode.meta` (per element) or `ParseResult.documentMeta` (root).
-     * Undeclared namespaces are preserved in the DOM but not promoted into
-     * the structured `meta` bag; they are silently dropped at serialize time.
+     * Content in an undeclared namespace is dropped.
      */
     namespaces?: Record<string, string>;
     /**
@@ -302,17 +298,19 @@ interface ParseOptions {
      * those defaults.
      */
     media?: Partial<SvgMediaEnvironment>;
+    /**
+     * Keep `display="none"` and `visibility="hidden"` content, each node marked
+     * `hidden`, so a file's hidden layers survive the import. By default it is
+     * left out, as a renderer leaves it out.
+     */
+    keepHidden?: boolean;
 }
 /** Output of {@link parseSvg}. */
 interface ParseResult {
     nodes: SvgNode[];
     /** Non-fatal notices (unsupported elements, unrecognized attributes). */
     warnings: string[];
-    /**
-     * Opaque per-document bag for declared namespaces. Holds root-level
-     * namespaced attributes (`documentMeta.<prefix>.attrs`) and namespaced
-     * root children (`documentMeta.<prefix>.elements`).
-     */
+    /** The root's namespaced attributes and children, for declared namespaces. */
     documentMeta?: NamespaceMeta;
     /** Root `viewBox` attribute, parsed from `"x y width height"`. */
     viewBox?: {
@@ -321,9 +319,9 @@ interface ParseResult {
         width: number;
         height: number;
     };
-    /** Root `width` attribute, parsed as a unitless number when present. */
+    /** Root `width` attribute in user units when present, an absolute CSS unit converted at 96 per inch. */
     width?: number;
-    /** Root `height` attribute, parsed as a unitless number when present. */
+    /** Root `height` attribute in user units when present, converted as `width` is. */
     height?: number;
     /** Text content of the first `<title>` child of `<svg>`, when present. */
     title?: string;
@@ -337,10 +335,7 @@ interface ParseResult {
 }
 /** Options for {@link serializeSvg}. */
 interface SerializeOptions {
-    /**
-     * Override the root `viewBox`. When omitted, the serializer computes
-     * a tight bounding box from the supplied nodes.
-     */
+    /** The root `viewBox`. Default: a tight bounding box around the nodes. */
     viewBox?: {
         x: number;
         y: number;
@@ -359,25 +354,23 @@ interface SerializeOptions {
     width?: number;
     /** Emit `height="..."` on the root `<svg>`. */
     height?: number;
-    /**
-     * Emit `<title>...</title>` as the first child of the root `<svg>`. The
-     * value is XML-escaped on output. Empty strings are skipped.
-     */
+    /** Emit `<title>` as the first child of the root `<svg>`. Empty strings are skipped. */
     title?: string;
     /**
-     * Map of prefix → URI for XML namespaces to declare on the root
-     * `<svg>`. The serializer reads `documentMeta[prefix]` and
-     * `node.meta[prefix]` to write the actual attributes and elements.
+     * Map of prefix → URI for XML namespaces to declare on the root `<svg>`.
+     * Only `documentMeta` and `node.meta` entries under a declared prefix are written.
      */
     namespaces?: Record<string, string>;
     /**
-     * Opaque per-document namespaced extras. Each `<prefix>.attrs` becomes
-     * `<prefix>:<name>="..."` attributes on the root `<svg>`. Each
-     * `<prefix>.elements[localName]` becomes `<prefix>:<localName>...>`
-     * children placed immediately before any geometry.
+     * Per-document namespaced extras: `attrs` go on the root `<svg>`, and
+     * `elements` become children placed immediately before any geometry.
      */
     documentMeta?: NamespaceMeta;
-    /** Pretty-print with newlines + indentation. Default `false`. */
+    /**
+     * Put each element on its own line, indented two spaces per level. A
+     * `<text>` element, and any element holding character data, stays on one
+     * line, since whitespace inside it is content.
+     */
     pretty?: boolean;
 }
 
@@ -400,7 +393,7 @@ declare function parseSvg(svg: string, opts?: ParseOptions): ParseResult;
 
 /**
  * Map between SVG `<linearGradient>` / `<radialGradient>` elements and
- * weasel's `FillStyle` gradient variants. Definitions are indexed by id
+ * weasel's `Paint` gradient variants. Definitions are indexed by id
  * wherever in the document they appear, and looked up when a `fill` /
  * `stroke` attribute references one as `url(#id)`. On serialize, we
  * emit a fresh `<defs>` block with stable generated ids.
@@ -418,9 +411,8 @@ declare function nativeSvgKind(kind: string): boolean;
 declare function nativeSvgSpace(space: string | null | undefined): boolean;
 
 /**
- * Walk the tree and produce an SVG document string. The root `<svg>`'s
- * `viewBox` is taken from `opts.viewBox` if supplied, otherwise computed
- * as a tight bounding box around every leaf.
+ * Produce an SVG document string. The root `viewBox` is `opts.viewBox` if
+ * supplied, otherwise a tight bounding box around every leaf.
  */
 declare function serializeSvg(nodes: SvgNode[], opts?: SerializeOptions): string;
 
@@ -442,27 +434,17 @@ declare function svgNeeds(nodes: readonly SvgNode[]): RenderNeeds;
 declare function warmSvg(nodes: readonly SvgNode[]): Promise<void>;
 
 /**
- * Map between SVG `<pattern>` elements and weasel's `pattern` `FillStyle`.
- * The counterpart to `gradients.ts` for the other paint-server kind.
- *
- * The tile's shapes come from `tileGeometry` in core, so the vector form a
- * viewer sees is generated from the same description that rasterizes the GL
- * texture. Alongside them we write the spec itself onto a `data-weasel-tile`
- * attribute: any SVG consumer renders the shapes, and weasel reads the
- * attribute back to recover the exact spec rather than reverse-engineering
- * it from geometry.
+ * Map between SVG `<pattern>` elements and weasel's pattern paints.
  *
- * A pattern whose payload is a `TextureHandle` has no vector form — the
- * handle is a session-scoped registry key with no tile description behind
- * it — and exports as nothing, with a warning. Same treatment conic
- * gradients get.
+ * The tile's shapes are written for any SVG consumer to render, and the spec
+ * itself goes on a `data-weasel-tile` attribute, which weasel reads back
+ * rather than reverse-engineering it from geometry. A `texture` paint has no
+ * vector form and exports as nothing, with a warning.
  */
 
 /**
- * A single tile as a standalone `<svg>` document, sized to its own extent.
- * For UI that needs to show a tile outside a document — a picker swatch,
- * set as a repeating CSS `background-image` via a data URI. Shares the shape
- * mapper with `patternXml`, so a preview can't drift from what paints.
+ * A single tile as a standalone `<svg>` document, sized to its own extent,
+ * for UI that shows a tile outside a document, such as a picker swatch.
  */
 declare function tilePreviewSvg(spec: TilePatternSpec, background?: string): string;
 /** `tilePreviewSvg` packed as a `url(...)` value for CSS `background-image`. */
@@ -473,6 +455,7 @@ declare function tilePreviewCssUrl(spec: TilePatternSpec, background?: string):
  * honor the declaration ({@link isDeclarationHonored}), not whether a browser
  * could parse it — the answer decides whether the guarded rules apply here.
  */
+/** Options for evaluating a `@supports` condition. */
 interface SupportsOptions {
     /** Answers `selector(…)`; without it every selector test is false. */
     readonly selector?: (selector: string) => boolean;
@@ -500,12 +483,15 @@ interface SvgKitPose {
     width: number;
     height: number;
     rotation?: number;
+    /** Carried onto a text or image node. A path node has nowhere to hold it,
+     *  so a path leaf's is baked into its geometry with its rotation. */
+    transform?: PoseLinear;
 }
 /** The leaf data the kit's path, text and image painters read — what
  *  `svgNodesToKitDrafts` writes. */
 interface SvgKitLeafData {
     path?: Path;
-    fill?: FillStyle | null;
+    fill?: Fill | null;
     stroke?: Stroke | null;
     text?: string;
     style?: TextStyle;
@@ -516,7 +502,7 @@ interface SvgKitLeafData {
 /** A kit paint as an `SvgPaint`. `null` is `fill="none"`; a box-relative
  *  gradient or pattern is resolved into `box`, since the geometry it paints
  *  is written already placed there. */
-declare function svgPaintFromKit(fill: FillStyle | null, box: SvgKitPose): SvgPaint;
+declare function svgPaintFromKit(fill: Paint | null, box: SvgKitPose): SvgPaint;
 /** A kit `Stroke` as an `SvgStroke` — the inverse of `strokeDataFromSvg`.
  *  One with no paint or no width draws nothing and is written as no stroke. */
 declare function svgStrokeFromKit(stroke: Stroke | null | undefined, box: SvgKitPose): SvgStroke | undefined;
@@ -529,7 +515,9 @@ declare function svgImageFromKit(image: ImageNodeData['image'], pose: SvgKitPose
  * draws.
  *
  * A path with no `fill` takes `kit:path`'s fallback: the default shape fill
- * when it has no stroke, and no fill when it has one.
+ * when it has no stroke, and no fill when it has one. Under a pose `transform`
+ * its stroke width takes the uniform part of the stretch, as `parseSvg` reads
+ * a stroke under a skewed element.
  */
 declare function svgLeafFromKit(data: SvgKitLeafData, pose: SvgKitPose): SvgPathNode | SvgTextNode | SvgImageNode | null;
 /** One node as {@link svgNodesFromKit} reads it. */
@@ -572,25 +560,37 @@ interface SvgDraftBounds {
     width: number;
     height: number;
 }
-type DraftPose = SvgDraftBounds & {
+/** Where a draft node sits: its box, and the rotation or linear part its SVG transform left it with. */
+type SvgDraftPose = SvgDraftBounds & {
     rotation?: number;
+    transform?: PoseLinear;
 };
+
 /**
  * One node the unpack wants the scene to materialize, in parent-before-child
  * order (a draft's `parentId` always names an earlier draft, or `null` for
- * roots). Leaf `data` is kit-painter-native (see module doc).
+ * roots). `hidden` is the source node's, for the caller to map onto whatever
+ * it hides a node with.
+ *
+ * A container's `data` is empty unless its `<g>` is clipped. A scene container
+ * clips to what its painter draws, so a clipped one holds the clip as an
+ * unpainted path, `{ path, fill: null }`, and its `pose` is the clip's box
+ * rather than its children's.
  */
 type SvgSceneDraft<TData = Record<string, unknown>> = {
     kind: 'container';
     id: string;
     parentId: string | null;
-    pose: DraftPose;
+    pose: SvgDraftPose;
+    data: SvgKitLeafData;
+    hidden?: true;
 } | {
     kind: 'leaf';
     id: string;
     parentId: string | null;
-    pose: DraftPose;
+    pose: SvgDraftPose;
     data: TData;
+    hidden?: true;
 };
 /** A leaf `SvgNode`: everything but a group. */
 type SvgLeafNode = Exclude<SvgNode, SvgGroupNode>;
@@ -600,33 +600,27 @@ interface SvgNodesToKitDraftsOptions<TData> {
      *  the node it came from — for data shaped other than the kit painters', or
      *  metadata the document carries. `null` leaves it out. */
     leaf?(id: string, draft: {
-        pose: DraftPose;
+        pose: SvgDraftPose;
         data: SvgKitLeafData;
     }, source: SvgLeafNode): TData | null;
 }
-/** Lower an `SvgPaint` onto the `kit:path` painter's `data.fill` — a
- *  `FillStyle`, or `null` for SVG's `fill="none"` (the painter skips the
- *  fill rather than falling back to its default). A solid paint keeps its
- *  `fill-opacity`.
+/** Lower an `SvgPaint` onto the paint of the `kit:path` painter's
+ *  `data.fill` — a `Paint`, or `null` for SVG's `fill="none"` (the painter
+ *  skips the fill rather than falling back to its default).
  *
- *  A gradient rides through as the `FillStyle` it already is, normalized to
- *  the leaf's own box: `objectBoundingBox` gradients already are, and a
- *  `userSpaceOnUse` one is rebased so it survives the fit-clamp and the
- *  drop-point placement that move the geometry out from under it. */
-declare function fillDataFromSvg(paint: SvgPaint | undefined, box: SvgDraftBounds): FillStyle | null | undefined;
-/** Lower an `SvgStroke` onto the leaf's `data.stroke`.
- *
- *  Everything the SVG carried — paint, width, cap, join, dash, miter limit,
- *  opacity — lands on the one `Stroke` `data.stroke` takes. The paint is
- *  normalized to the leaf's own box the same way a fill is, so a
- *  `userSpaceOnUse` gradient survives the fit-clamp and the drop-point
- *  placement. */
+ *  A `userSpaceOnUse` gradient is rebased onto the leaf's own box, so it
+ *  survives the fit-clamp and the drop-point placement that move the
+ *  geometry out from under it. */
+declare function fillDataFromSvg(paint: SvgPaint | undefined, box: SvgDraftBounds): Paint | null | undefined;
+/** Lower an `SvgStroke` onto the leaf's `data.stroke`, or `undefined` for an
+ *  unpainted one. The paint is rebased onto the leaf's own box the same way
+ *  a fill is. */
 declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftBounds): Stroke | undefined;
 /**
  * Walk an `SvgNode[]` tree and emit a flat, parent-before-child list of
  * {@link SvgSceneDraft}s. Each `<g>` becomes a container whose pose is the
- * union AABB of its descendants (the kit `group` action's convention);
- * path/text leaves carry kit-painter-native data. Empty groups are dropped.
+ * union AABB of its descendants, or its clip's box when it has one; leaves
+ * carry kit-painter-native data. Empty groups are dropped.
  *
  * Handed a whole `ParseResult`, it also registers the document's markers
  * (`parsed.markers`), without which the strokes naming them draw bare.
@@ -638,11 +632,15 @@ declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftB
  */
 declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: ParseResult | readonly SvgNode[], nextId: (source: SvgNode) => string, options?: SvgNodesToKitDraftsOptions<TData>): SvgSceneDraft<TData>[];
 /**
- * Parse each file and insert its node tree — one undoable `applyOps` batch
- * per file. See the module doc for placement and wrapping policy. A file
- * that fails to parse (or parses to nothing) is skipped with a
- * `console.warn`; the rest proceed.
+ * Parse each file and insert its node tree, one undo step per file. Pass it
+ * as `<SceneCanvas ingestion={{ svg: { unpack: unpackSvgFiles } }}>`.
+ *
+ * Each file is fit-clamped to 90% of the visible viewport and centered on the
+ * drop point (or the viewport center), with later files cascading by a fixed
+ * offset. A multi-root file is wrapped in one container so it arrives as a
+ * single selectable unit. A file that fails to parse, or parses to nothing,
+ * is skipped with a `console.warn`.
  */
 declare function unpackSvgFiles(files: File[], ctx: IngestCtx): Promise<void>;
 
-export { DEFAULT_MEDIA_ENVIRONMENT, IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SupportsOptions, type SvgDraftBounds, type SvgGroupNode, type SvgImageNode, type SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgMediaEnvironment, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };
+export { DEFAULT_MEDIA_ENVIRONMENT, IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SupportsOptions, type SvgDraftBounds, type SvgDraftPose, type SvgGroupNode, type SvgImageNode, type SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgMediaEnvironment, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };