@svgsketch/core 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -306,6 +306,38 @@ interface SerializedAnimationTimeline {
          * import time.
          */
         transformBaseValue?: string;
+        /**
+         * For `property === 'domAttribute'` tracks: the SVG attribute name
+         * to write on the target element each frame (`cx`, `cy`, `r`, `x`,
+         * `y`, `width`, `height`, `opacity`, `fill-opacity`, `fill`,
+         * `stroke`, `d`, etc.). Generic carrier for `<animate>` / `<set>`
+         * inside `<clipPath>` / `<mask>` defs that the editor doesn't
+         * decompose into per-attribute first-class tracks. Set jointly with
+         * `domAttributeValueType` so the manager knows how to interpolate
+         * the raw keyframe values.
+         * @see SVG Animations §3.5
+         */
+        domAttribute?: string;
+        /**
+         * For `property === 'domAttribute'` tracks: how to interpolate the
+         * keyframe values. `'number'` → numeric tween; `'color'` → RGB
+         * channel tween via the existing color interp; `'string'` →
+         * discrete (no interpolation, holds each keyframe until the next).
+         * Determined at import time from the source `<animate>`'s
+         * `attributeName` (geometry → number, paint → color, others →
+         * string). `<set>` always produces `'string'` regardless of attr.
+         */
+        domAttributeValueType?: 'number' | 'color' | 'string';
+        /**
+         * SMIL `calcMode` (SVG Animations §2.10) — controls interpolation
+         * between keyframes. Persisted because it changes how the SMIL
+         * exporter materializes the track: `'discrete'` round-trips a
+         * single-keyframe track as `<set>` and a multi-keyframe track as one
+         * `<set>` per keyframe, while the absent/`'linear'` form emits a
+         * single `<animate values="…">`. Without this field, set-semantics
+         * tracks degrade to interpolated `<animate>` after save/reload.
+         */
+        calcMode?: 'linear' | 'discrete' | 'paced' | 'spline';
         keyframes: {
             time: number;
             value: number | string;
@@ -437,6 +469,15 @@ interface LinearGradient {
      * element's bbox-normalised [0, 1] space. See `GradientUnits`.
      */
     gradientUnits?: GradientUnits;
+    /**
+     * SVG 2 §13.9 `color-interpolation` — color space for stop
+     * interpolation. Spec applies the property to gradient elements;
+     * `linearRGB` produces physically-linear blends, `sRGB` (the spec
+     * initial value) produces the perceptual blends most authors expect.
+     * Round-trip the attribute when authored so re-export does not
+     * silently shift mid-tone colors.
+     */
+    colorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
     /**
      * Original `id` from the imported source SVG. Runtime `id` is always
      * a fresh GUID (to keep editor uniqueness invariants), but `sourceId`
@@ -472,6 +513,8 @@ interface RadialGradient {
      * `r`/`ry` are in document user space. See `GradientUnits`.
      */
     gradientUnits?: GradientUnits;
+    /** See `LinearGradient.colorInterpolation`. */
+    colorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
     /** See `LinearGradient.sourceId`. */
     sourceId?: string;
 }
@@ -1162,6 +1205,50 @@ interface ShapeMetadata {
     role: AriaRole;
     ariaLabel: string;
     customData: Record<string, string>;
+    /**
+     * Generic ARIA attribute bag — every `aria-*` attribute *except*
+     * `aria-label` (which has its own dedicated field for the metadata
+     * panel's back-compat path). Keys are the full attribute name, e.g.
+     * `'aria-labelledby'`, `'aria-describedby'`, `'aria-hidden'`.
+     *
+     * Spec: SVG 2 §5.12.3 — "All aria- attributes" are valid on every SVG
+     * element. Stored verbatim so the full WAI-ARIA surface round-trips.
+     */
+    aria?: Record<string, string>;
+    /**
+     * Per-element `lang` / `xml:lang` value (SVG 2 §5.11.3). Authored
+     * `xml:lang` is preferred but `lang` is accepted as a fallback. Emit
+     * as `xml:lang` per spec recommendation.
+     */
+    lang?: string;
+    /**
+     * Per-element `tabindex` (SVG 2 §5.11.5). Stored as integer. Negative
+     * values are valid (focusable but not in the default tab order).
+     */
+    tabindex?: number;
+    /** Per-element `autofocus` (SVG 2 §5.11.6). Boolean attribute. */
+    autofocus?: boolean;
+    /**
+     * Per-element `xml:space` value (SVG 2 §5.11.4) for non-text shapes.
+     * Text-bearing shapes (`Text`) own their own `xml:space` lifecycle
+     * via the rich-text serializer.
+     */
+    xmlSpace?: 'default' | 'preserve';
+    /**
+     * Foreign-namespaced or prefixed attributes preserved verbatim for
+     * round-trip (SVG 2 §5.10 — "elements and attributes from foreign
+     * namespaces ... must be ignored for rendering ... [but] preserved
+     * when the SVG document is loaded and saved"). Covers `inkscape:`,
+     * `sodipodi:`, `serif:`, `figma:`, and any other authoring-tool
+     * markers, plus arbitrary user-defined namespaces. Stored as a list
+     * (rather than a record) to preserve ordering and to permit multiple
+     * attributes with the same local name across different namespaces.
+     */
+    foreignAttrs?: Array<{
+        name: string;
+        namespaceURI: string | null;
+        value: string;
+    }>;
     /**
      * Hyperlink target — when set, the shape is rendered inside an SVG `<a>`
      * element with `href="${linkUrl}"`. Round-trips through SVG import/export.
@@ -1254,6 +1341,19 @@ interface DocumentMetadata {
      * `ShapeMetadata.rawDescription`; see there for the emit rule.
      */
     rawDescription?: string;
+    /**
+     * Lossless carrier for HTML metadata elements (`<link>`, `<meta>`)
+     * that appeared as direct children of the root `<svg>`. Stored as a
+     * serialized string of one or more elements in document order.
+     *
+     * Spec: SVG 2 §5.9 — "The HTML elements `meta`, `link` and `style`
+     * may appear inside the `svg` element". `<style>` is consumed by
+     * the CSS parser; `<link>` (often used for external stylesheets)
+     * and `<meta>` (charset, viewport hints, OpenGraph) round-trip
+     * verbatim through this field so downstream tooling that produced
+     * them sees its data preserved.
+     */
+    rawHtmlMetadata?: string;
     /**
      * Decimal precision for coordinate values when the document is
      * serialized — file save, cloud sync, undo capture, and SVG export.
@@ -1354,17 +1454,13 @@ type TemplateVariableType = 'string' | 'color' | 'number';
  */
 type TemplateVariableMode = 'live' | 'stamped';
 /**
- * Where a TemplateVariable came from. `user` is hand-authored in the
- * Variables panel; `palette` is auto-generated by the palette-token
- * integration and is read-mostly (the source of truth lives in user
- * settings, not the document).
+ * Where a TemplateVariable came from. Currently only `user` (hand-authored
+ * in the Document Tokens panel or harvested from imported `:root { --foo
+ * }` blocks). Retained as a tagged union so additional sources (e.g.
+ * external design-token imports) can be added without breaking callers.
  */
 type TemplateVariableSource = {
     kind: 'user';
-} | {
-    kind: 'palette';
-    paletteId: string;
-    index: number;
 };
 /**
  * A template variable definition stored in the document.
@@ -1796,7 +1892,40 @@ interface SerializedShape {
         opacity?: number;
         blendMode?: string;
         shapeRendering?: 'auto' | 'optimizeSpeed' | 'crispEdges' | 'geometricPrecision';
+        textRendering?: 'auto' | 'optimizeSpeed' | 'optimizeLegibility' | 'geometricPrecision';
+        imageRendering?: 'auto' | 'optimizeSpeed' | 'optimizeQuality' | 'crisp-edges' | 'pixelated' | 'smooth' | 'high-quality';
+        colorRendering?: 'auto' | 'optimizeSpeed' | 'optimizeQuality';
+        /**
+         * SVG `color-interpolation` (SVG 2 §13.9). Selects the color space —
+         * sRGB or linearized RGB — used for *non-filter* color operations:
+         * gradient-stop interpolation, SMIL color animation interpolation,
+         * and the compositing/blending of graphics elements. The
+         * filter-pipeline analogue is `color-interpolation-filters`
+         * (carried separately on filter chains as `filterColorInterpolation`).
+         * Spec initial value: `sRGB`. Authors who pick `linearRGB` get
+         * physically-linear stop interpolation; missing this attribute on
+         * round-trip silently shifts mid-tone gradient colors.
+         */
+        colorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
+        /**
+         * SVG `display` presentation attribute as authored on the source
+         * element. Distinct from `visible` (editor's layer-hide boolean,
+         * which writes inline `style="display:none"`): `display: 'none'`
+         * here carries the author's intent through round-trip as an XML
+         * attribute (`<rect display="none"/>`), preserving SVG 2 §3.2.2
+         * semantics that `display:none` removes the element from the
+         * rendering tree.
+         */
+        display?: 'none';
         metadata?: Partial<ShapeMetadata>;
+        /**
+         * Shape-scoped `<script>` elements (SVG 2 §15.9 allows scripts as
+         * descendants of any container). Emitted as children of the shape's
+         * exported element on save; preserved verbatim through .svgs round-trip,
+         * undo/redo, copy/paste. Distinct from `HistorySnapshot.documentScripts`
+         * which sits at the SVG root and runs in document order.
+         */
+        scripts?: DocumentScript[];
         groupId?: string;
         cssClipPath?: string;
         cssMaskProperties?: Record<string, string>;
@@ -1842,6 +1971,26 @@ interface SerializedShape {
          * Only meaningful on `symbol-instance` shapes.
          */
         instancePresentation?: Record<string, string>;
+        /**
+         * Inline children for container shape types (`hyperlink`, `switch`,
+         * `container`, embedded `svg`). Each child is a self-contained
+         * `SerializedShape` rendered nested inside the parent's element.
+         *
+         * Groups (`type === 'group'`) do NOT use this field — they store
+         * children flat in `HistorySnapshot.shapes[]` and back-reference the
+         * parent group via `state.groupId`. The two pickup paths exist
+         * because groups predate the inline-children container model.
+         */
+        children?: SerializedShape[];
+        /** Legacy `xlink:href`, preserved alongside `href` for round-trip. */
+        hrefXlink?: string;
+        linkTarget?: '_self' | '_blank' | '_parent' | '_top' | string;
+        linkRel?: string;
+        linkDownload?: string;
+        linkPing?: string;
+        linkHreflang?: string;
+        linkType?: string;
+        linkReferrerPolicy?: string;
         /**
          * Id of the canvas shape this `shape-reference` (Linked Copy) targets.
          * A Linked Copy renders as a live clone of another top-level shape and
@@ -2023,6 +2172,55 @@ interface HistorySnapshot {
     symbols?: SerializedSymbolDef[];
     /** @deprecated v2 — use `library`. Read-only: v1 docs migrate into `library`. */
     markers?: SerializedMarkerDef[];
+    /**
+     * Color glyph library — Phase 3 of the OT-SVG / COLR foundry.  Authored
+     * color glyphs (each a small SVG document plus codepoint mapping) ride
+     * with the document so they survive local save/load and cloud sync.
+     * The base font that the foundry overlays onto is intentionally NOT
+     * stored here — it's a per-browser tool choice (kept in IndexedDB),
+     * not document state.  Only the colour-glyph artwork itself rides.
+     *
+     * Optional: documents that never opened the foundry have no entry,
+     * and the field is omitted on serialisation when the library is empty.
+     */
+    colorGlyphLibrary?: SerializedColorGlyphLibrary;
+}
+/**
+ * Wire format for the color glyph library.  Mirrors the in-editor
+ * `GlyphLibrary` exactly, but typed in core so plugins / CLI tooling /
+ * any future export pipeline can consume it without depending on the
+ * editor app.
+ *
+ * Versioned because the entry shape may evolve (e.g. when variable-axis
+ * glyph deltas land in Phase 4).  Readers honour `version: 1` only;
+ * future versions will get explicit migration code in `migrateSnapshot`.
+ */
+interface SerializedColorGlyphLibrary {
+    version: 1;
+    entries: SerializedColorGlyph[];
+}
+/**
+ * One color glyph in the library.  All fields are JSON-serialisable;
+ * the SVG document is stored as a string, not parsed, so round-tripping
+ * preserves whatever DOM the user authored byte-for-byte.
+ */
+interface SerializedColorGlyph {
+    /** Internal glyph ID assigned by the library; resolved against the base font's cmap on export. */
+    glyphId: number;
+    /** PostScript glyph name (e.g. `"uni1F3A8"`).  Optional — emitter generates one if absent. */
+    glyphName?: string;
+    /** Unicode codepoints this glyph maps from in `cmap`.  Empty = unmapped (referenced only by GSUB). */
+    codepoints: number[];
+    /** Advance width in font units.  Defaults to `unitsPerEm` if unset. */
+    advanceWidth?: number;
+    /** SVG document for the glyph.  Root `<svg>` should carry `id="glyph${glyphId}"`. */
+    svgDocument: string;
+    /** Source font this glyph came from (when extracted via the Phase 2 break-apart). */
+    sourceFamily?: string;
+    /** Source glyph ID in the originating font. */
+    sourceGlyphId?: number;
+    /** Display label shown in the library panel. */
+    label?: string;
 }
 /**
  * A variant axis on a component symbol. Each axis has a name (e.g.
@@ -2094,6 +2292,13 @@ interface SerializedGroup {
     filter?: string;
     cssFilter?: string;
     mixBlendMode?: string;
+    /**
+     * CSS `isolation` (Compositing & Blending §6.1). CSS-only property —
+     * no SVG presentation-attribute form, so it lives in inline style on
+     * the group element. Round-tripped here so authored
+     * `<g style="isolation:isolate">` survives serialize/restore.
+     */
+    isolation?: string;
     clipPath?: string;
     mask?: string;
     /**
@@ -2388,6 +2593,7 @@ interface CommonNodeProps {
     gapLength: number;
     dashOffset: number;
     strokeDasharray: string | null;
+    colorInterpolation: 'auto' | 'sRGB' | 'linearRGB' | null;
     filters: unknown[];
     filterColorInterpolation: 'auto' | 'sRGB' | 'linearRGB' | null;
     filterUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
@@ -3988,6 +4194,68 @@ declare abstract class ShapeBuilder<T extends ShapeBuilder<T>> {
     cssClipPath(value: string): T;
     /** Set CSS mask sub-properties (`mask-image`, `mask-mode`, etc.). */
     cssMaskProperties(props: Record<string, string>): T;
+    /**
+     * SVG 2 §13.4 `vector-effect`. `non-scaling-stroke` keeps stroke width
+     * constant under zoom and transforms (heavily used in CAD/diagram SVGs).
+     */
+    vectorEffect(value: 'none' | 'non-scaling-stroke' | 'non-scaling-size' | 'non-rotation' | 'fixed-position'): T;
+    /** CSS Transforms 2 `transform-box`. */
+    transformBox(value: 'view-box' | 'fill-box' | 'stroke-box' | 'content-box' | 'border-box'): T;
+    /** SVG 2 §13.10 `paint-order` (e.g. `'stroke fill'`, `'fill stroke markers'`). */
+    paintOrder(value: string): T;
+    /** Compositing & Blending 2 `mix-blend-mode` (e.g. `'multiply'`, `'screen'`). */
+    blendMode(value: string): T;
+    /**
+     * SVG `visibility` attribute — paint-only hiding that preserves layout.
+     * Distinct from `.visible(false)` which sets `display:none`.
+     */
+    visibility(value: 'visible' | 'hidden' | 'collapse'): T;
+    /** SVG 2 §13.6 `shape-rendering`. */
+    shapeRendering(value: 'auto' | 'optimizeSpeed' | 'crispEdges' | 'geometricPrecision'): T;
+    /** Color-interpolation hint for filter chains attached to this shape. */
+    filterColorInterpolation(value: 'auto' | 'sRGB' | 'linearRGB'): T;
+    /**
+     * Suppress the shape-level `fill` so the `<use>` cascade can drive it
+     * (used by symbol instances with `instancePresentation`).
+     */
+    inheritFill(value?: boolean): T;
+    /** Suppress the shape-level `stroke` so the `<use>` cascade can drive it. */
+    inheritStroke(value?: boolean): T;
+    /** SVG 2 §5.8.5 `systemLanguage` conditional-processing attribute (BCP 47 tag). */
+    systemLanguage(tag: string): T;
+    /** SVG 2 §5.8 `requiredExtensions` conditional-processing attribute. */
+    requiredExtensions(value: string): T;
+    /**
+     * Reference a library-registered fill (gradient or pattern) by id.
+     * The `kind` parameter tells the renderer which `<defs>` shape to expect;
+     * it's the discriminator on the matching `LibraryDef` entry.
+     * Mutually exclusive with `.fill()`/`.fillGradient()`/`.fillPattern()`.
+     */
+    fillLibrary(id: string, kind?: 'linear-gradient' | 'radial-gradient' | 'pattern'): T;
+    /** Reference a library-registered stroke (gradient or pattern) by id. */
+    strokeLibrary(id: string, kind?: 'linear-gradient' | 'radial-gradient' | 'pattern'): T;
+    /**
+     * Reference one or more library-registered filters by id. The chain is
+     * composed in order, then merged with any inline `.filter()`/`.dropShadow()`/etc.
+     */
+    filterLibrary(...ids: string[]): T;
+    /**
+     * Reference a library-registered marker for the start vertex.
+     * Distinct from the `Line`/`Path` `.markerStart()` preset accessors —
+     * those set the `startEndpoint` preset, this points at a library def id.
+     */
+    markerStartRef(id: string): T;
+    /** Reference a library-registered marker for intermediate vertices. */
+    markerMidRef(id: string): T;
+    /** Reference a library-registered marker for the end vertex. */
+    markerEndRef(id: string): T;
+    /**
+     * Bind a shape property to a template variable name. The variable must be
+     * registered on the document via `Document.defineVariable(...)`. At export
+     * time the property's serialized value is replaced by `{{varName}}`, which
+     * `Document.toSVG({ variables })` then substitutes.
+     */
+    bind(propertyName: string, variableName: string): T;
     /** Set shape metadata (name, title, description, etc). */
     metadata(meta: Partial<ShapeMetadata>): T;
     /** Assign this shape to a group. */
@@ -4111,6 +4379,26 @@ declare class Text extends ShapeBuilder<Text> {
     shapePadding(value: number): Text;
     /** Set rich text data for per-segment styling. */
     richTextData(data: RichTextData): Text;
+    /**
+     * Toggle rich-text rendering. When `true`, `richTextData` drives output and
+     * the plain `text` field is treated as a fallback. When `false` (default),
+     * the plain `text` field is rendered.
+     */
+    useRichText(flag?: boolean): Text;
+    /**
+     * Set per-line position overrides. Used when imported `<tspan>` runs
+     * carried explicit `x`/`y`/`dx`/`dy` lists that the editor must round-trip.
+     */
+    linePositions(positions: {
+        x?: number | null;
+        y?: number | null;
+        dx?: number;
+        dy?: number;
+    }[]): Text;
+    /** SVG `textLength` attribute (target advance width). */
+    textLength(value: number): Text;
+    /** SVG `lengthAdjust` attribute (`spacing` or `spacingAndGlyphs`). */
+    lengthAdjust(value: 'spacing' | 'spacingAndGlyphs'): Text;
 }
 declare abstract class PolygonShapeBuilder<T extends PolygonShapeBuilder<T>> extends ShapeBuilder<T> {
     constructor(type: SerializedShape['type'], cx: number, cy: number, radius: number);
@@ -4173,6 +4461,166 @@ declare class Arrow extends PolygonShapeBuilder<Arrow> {
     /** Set the arrow shaft width as a percent (0–100). */
     shaftWidth(percent: number): Arrow;
 }
+declare class Heart extends PolygonShapeBuilder<Heart> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the lobe radius as a percent of the bounding circle (30–70). */
+    lobeRadius(percent: number): Heart;
+    /** Set the cleft (top notch) depth as a percent (10–50). */
+    cleftDepth(percent: number): Heart;
+}
+declare class Lightning extends PolygonShapeBuilder<Lightning> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the number of zigzag bend segments. */
+    segments(n: number): Lightning;
+    /** Set the horizontal sway as a percent (10–80). */
+    jaggedness(percent: number): Lightning;
+    /** Set the bolt ribbon thickness as a percent (10–60). */
+    thickness(percent: number): Lightning;
+}
+declare class Cloud extends PolygonShapeBuilder<Cloud> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the number of bumps around the cloud silhouette. */
+    bumps(n: number): Cloud;
+    /** Set the puffiness (bump radius) as a percent. */
+    puffiness(percent: number): Cloud;
+}
+declare class SpeechBubble extends PolygonShapeBuilder<SpeechBubble> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the tail angle in degrees (0 = right, 90 = down, etc.). */
+    tailAngle(degrees: number): SpeechBubble;
+    /** Set the tail length as a percent of the bounding radius. */
+    tailLength(percent: number): SpeechBubble;
+    /** Set the tail base width as a percent of the bounding radius. */
+    tailWidth(percent: number): SpeechBubble;
+}
+/**
+ * Mixin base for shape builders whose `state.children` is an inline array
+ * of `SerializedShape`. Hyperlink, Switch, Container, NestedSvg all extend
+ * this. The `.add()` method accepts another `ShapeBuilder` (its `.build()`
+ * is called immediately) or a raw `SerializedShape`.
+ */
+declare abstract class ContainerShapeBuilder<T extends ContainerShapeBuilder<T>> extends ShapeBuilder<T> {
+    /** Append a shape (builder or pre-built SerializedShape) as a child. */
+    add(shape: ShapeBuilder<any> | SerializedShape): T;
+    /** Append multiple children in a single call. */
+    addAll(...shapes: (ShapeBuilder<any> | SerializedShape)[]): T;
+    /** Replace the children array wholesale. */
+    children(shapes: (ShapeBuilder<any> | SerializedShape)[]): T;
+}
+declare class Hyperlink extends ContainerShapeBuilder<Hyperlink> {
+    constructor(href?: string);
+    /** Set the link target URL (`href` attribute). */
+    href(value: string): Hyperlink;
+    /** Set the legacy `xlink:href` (kept for round-trip with SVG 1.1 sources). */
+    hrefXlink(value: string): Hyperlink;
+    /** Set the link target window — `'_self'`, `'_blank'`, etc. */
+    target(value: '_self' | '_blank' | '_parent' | '_top' | string): Hyperlink;
+    /** Set the `download` attribute (file name hint for download links). */
+    download(value: string): Hyperlink;
+    /** Set the `rel` attribute (e.g. `'noopener noreferrer'`). */
+    rel(value: string): Hyperlink;
+    /** Set the `ping` attribute (space-separated URLs notified on click). */
+    ping(value: string): Hyperlink;
+    /** Set the `hreflang` attribute. */
+    hreflang(value: string): Hyperlink;
+    /** Set the `type` attribute (MIME type hint for the destination). */
+    type(value: string): Hyperlink;
+    /** Set the `referrerpolicy` attribute. */
+    referrerPolicy(value: string): Hyperlink;
+}
+declare class Switch extends ContainerShapeBuilder<Switch> {
+    constructor();
+}
+/**
+ * Generic container shape: emits `<g>` wrapping inline children. Distinct
+ * from the editor's `Group` system, which uses flat-with-`groupId` storage —
+ * use this when programmatically composing a document where you want the
+ * children persisted under their parent rather than in the flat shapes array.
+ */
+declare class Container extends ContainerShapeBuilder<Container> {
+    constructor();
+}
+declare class View extends ShapeBuilder<View> {
+    constructor(viewBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    });
+    /** Set the viewBox (x, y, width, height) the view exposes. */
+    viewBox(x: number, y: number, width: number, height: number): View;
+    /** Human-readable name (round-tripped as `data-view-name`). */
+    name(value: string): View;
+    /** SVG 2 `preserveAspectRatio` (e.g. `'xMidYMid meet'`). */
+    preserveAspectRatio(value: string): View;
+    /** Legacy `zoomAndPan` attribute (`'disable' | 'magnify'`). */
+    zoomAndPan(value: 'disable' | 'magnify'): View;
+    /** SVG `viewTarget` attribute. */
+    viewTarget(value: string): View;
+    /** Mark this view as the canonical "home" view of the document. */
+    asHome(value?: boolean): View;
+}
+declare class NestedSvg extends ContainerShapeBuilder<NestedSvg> {
+    constructor(x?: number, y?: number, width?: number, height?: number);
+    /** Set the position on the parent canvas. */
+    position(x: number, y: number): NestedSvg;
+    /** Set width and height on the parent canvas. */
+    size(width: number, height: number): NestedSvg;
+    /** Set the `viewBox` (the inner coordinate system). */
+    viewBox(x: number, y: number, width: number, height: number): NestedSvg;
+    /** SVG 2 `preserveAspectRatio` for the nested viewport. */
+    preserveAspectRatio(value: string): NestedSvg;
+    /** Mark this as the root SVG element (rare; typically only one per document). */
+    asRoot(value?: boolean): NestedSvg;
+}
+declare class ShapeReference extends ShapeBuilder<ShapeReference> {
+    constructor(targetShapeId?: string);
+    /** ID of the shape this reference clones. */
+    target(shapeId: string): ShapeReference;
+    /** Offset from the source's reference point (mapped to `<use x>`/`<use y>`). */
+    offset(x: number, y: number): ShapeReference;
+    /** Override the rendered width/height (mapped to `<use width>`/`<use height>`). */
+    size(width: number, height: number): ShapeReference;
+}
+declare abstract class MediaShapeBuilder<T extends MediaShapeBuilder<T>> extends ShapeBuilder<T> {
+    /** Position on the canvas. */
+    position(x: number, y: number): T;
+    /** Bounding-box width/height of the foreignObject wrapper. */
+    size(width: number, height: number): T;
+    /** Source URL or data URI. */
+    src(href: string): T;
+    /** MIME type hint (e.g. `'video/mp4'`, `'audio/mpeg'`). */
+    mimeType(value: string): T;
+    /** Source duration in seconds (set by the editor on `loadedmetadata`). */
+    naturalDuration(seconds: number): T;
+    /** Timeline offset where playback starts. */
+    begin(seconds: number): T;
+    /** Source-relative in/out trim (seconds). */
+    trim(start: number, end: number): T;
+    volume(value: number): T;
+    muted(value?: boolean): T;
+    loop(value?: boolean): T;
+    playbackRate(value: number): T;
+    /** Convenience volume ramps applied live by the sync controller. */
+    fade(inDuration: number, outDuration: number): T;
+    /** SVG conditional-processing `systemLanguage` (BCP 47 tag). */
+    language(tag: string): T;
+}
+declare class Video extends MediaShapeBuilder<Video> {
+    constructor(href?: string);
+    /** First-frame thumbnail URL or data URI. */
+    poster(href: string): Video;
+    /** Crop window in source-pixel space. */
+    sourceRect(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Video;
+}
+declare class Audio extends MediaShapeBuilder<Audio> {
+    constructor(href?: string);
+}
 declare class Path extends ShapeBuilder<Path> {
     constructor(points?: (Point | PathPoint)[]);
     /** Set the spline points. */
@@ -4193,6 +4641,15 @@ declare class Path extends ShapeBuilder<Path> {
     markerEnd(style: EndpointStyle): Path;
     /** Convenience: set both markers. */
     markers(start: EndpointStyle, end: EndpointStyle): Path;
+    /**
+     * Resolve this path to its SVG `d` attribute string. Useful for path-morph
+     * animations: the `d` track property accepts a `d` string per keyframe, and
+     * SMIL interpolates between matching command sequences character-by-character.
+     *
+     * The output uses the same geometry pipeline as `Document.toSVG()`, so the
+     * animated values match the static render of the same path exactly.
+     */
+    toD(): string;
 }
 declare class Polyline extends ShapeBuilder<Polyline> {
     constructor(points?: Point[]);
@@ -4518,6 +4975,16 @@ declare class Document {
         viewBox?: string;
         thumbnail?: string;
         groups?: SerializedGroup[];
+        /** SVG-element form: `'symbol'` (the default) or `'group'` (`<defs><g>`). */
+        defKind?: 'symbol' | 'group';
+        /** Wrapper attributes from a source `<g id>` def root, when `defKind === 'group'`. */
+        wrapperAttrs?: Record<string, string>;
+        /** Named variant axes, e.g. `[{ name: 'color', values: ['red', 'blue'] }]`. */
+        variantAxes?: SerializedVariantAxis[];
+        /** Variant shape arrays keyed by canonical `axis=val,…` string. */
+        variants?: Record<string, SerializedShape[]>;
+        /** Per-variant thumbnails keyed by canonical variant string. */
+        variantThumbnails?: Record<string, string>;
     }): string;
     /**
      * Place a symbol instance on the canvas.
@@ -4525,14 +4992,88 @@ declare class Document {
      * @param symbolId - The ID of the symbol definition.
      * @param x - X position.
      * @param y - Y position.
-     * @param width - Instance width (optional).
-     * @param height - Instance height (optional).
+     * @param widthOrOptions - Instance width, or an options bag.
+     * @param height - Instance height (only when `widthOrOptions` is a number).
      */
-    placeSymbolInstance(symbolId: string, x: number, y: number, width?: number, height?: number): Document;
+    placeSymbolInstance(symbolId: string, x: number, y: number, widthOrOptions?: number | {
+        width?: number;
+        height?: number;
+        /** Selected variant key, e.g. `'color=red,size=large'`. */
+        variantKey?: string;
+        /** Per-inner-shape state patches applied to this instance only. */
+        symbolOverrides?: Record<string, Partial<SerializedShape['state']>>;
+        /** Per-instance attribute cascade applied to the `<use>` element (SVG 2 §5.5.4). */
+        instancePresentation?: Record<string, string>;
+    }, height?: number): Document;
     /** Remove a symbol definition by ID. */
     removeSymbol(id: string): boolean;
     /** Get all symbol definitions. */
     get symbols(): readonly SerializedSymbolDef[];
+    /**
+     * Register a marker definition. Shapes can then reference the marker by
+     * id via `.markerStartRef(id)` / `.markerMidRef(id)` / `.markerEndRef(id)`.
+     *
+     * @returns The marker library def id.
+     */
+    defineMarker(name: string, shapes: (ShapeBuilder<any> | SerializedShape)[], options?: {
+        viewBox?: string;
+        refX?: number;
+        refY?: number;
+        markerWidth?: number;
+        markerHeight?: number;
+        markerUnits?: 'strokeWidth' | 'userSpaceOnUse';
+        orient?: 'auto' | 'auto-start-reverse' | number;
+        thumbnail?: string;
+        groups?: SerializedGroup[];
+    }): string;
+    /**
+     * Register a reusable filter chain. Shapes reference it via `.filterLibrary(id)`.
+     *
+     * @returns The filter library def id.
+     */
+    defineFilter(name: string, filters: ShapeFilter[], options?: {
+        colorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
+        filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        x?: string;
+        y?: string;
+        width?: string;
+        height?: string;
+        thumbnail?: string;
+    }): string;
+    /**
+     * Register a reusable linear gradient. Shapes reference it via `.fillLibrary(id)`.
+     *
+     * @returns The library def id.
+     */
+    defineLinearGradientLibrary(name: string, gradient: LinearGradientBuilder | LinearGradient, options?: {
+        thumbnail?: string;
+    }): string;
+    /**
+     * Register a reusable radial gradient. Shapes reference it via `.fillLibrary(id, 'radial-gradient')`.
+     *
+     * @returns The library def id.
+     */
+    defineRadialGradientLibrary(name: string, gradient: RadialGradientBuilder | RadialGradient, options?: {
+        thumbnail?: string;
+    }): string;
+    /**
+     * Register a reusable pattern. Shapes reference it via `.fillLibrary(id, 'pattern')`.
+     *
+     * @returns The library def id.
+     */
+    definePatternLibrary(name: string, pattern: PatternBuilder | PatternFill, options?: {
+        thumbnail?: string;
+    }): string;
+    /** Remove a library def (marker / filter / gradient / pattern) by id. */
+    removeLibraryDef(id: string): boolean;
+    /** Read-only view of every registered library def. */
+    get library(): readonly LibraryDef[];
+    /**
+     * Push a library def, lazily initializing `_snapshot.library` and
+     * deduplicating by id (last write wins).
+     */
+    private _pushLibraryDef;
     /**
      * Add a clip group.
      *
@@ -4751,4 +5292,4 @@ declare class Document {
     private _ensureMetadata;
 }
 
-export { type AnimatablePropertyDescriptor, type AnimationKeyframe, type AnimationTimeline, type AnimationTrack, type AnimationTrigger, type AnimationTriggerType, type AnyNodeProps, type ArcParams$1 as ArcParams, type AriaRole, Arrow, type ArrowNodeProps, BUILTIN_MARKER_ID_MAP, type BaseFilter, type BaseFilterPrimitive, type BlackAndWhiteFilter, type BlurQuality, type BrightnessFilter, CURRENT_SCHEMA_VERSION, type ChannelPainterFilter, Circle, type CircleNodeProps, type CodeFormat, type CodegenOptions, type CommonNodeProps, type ConnectionDirection, type ConnectionPoint, type ContouringDiscreteFilter, type ContouringTableFilter, type ContrastFilter, type CornerShapeValue, type CreateDocumentOptions, type CreateShapeOptions, Cross, type CrossNodeProps, type CrumpledPlasticFilter, type CustomPatternDef, type CycleBehavior, DEFAULT_COORDINATE_PRECISION, type DiffuseLightingFilter, Document, type DocumentMetadata, type DocumentNodeProps, type DocumentOptions, type DocumentScript, type DocumentStyle, type DropShadowFilter, type DuotoneFilter, EASING_CURVES, EVENT_TRIGGER_OPTIONS, EasingType, Ellipse, type EllipseNodeProps, type EmbossFilter, type ExtractedVariables, type FeBlendPrimitive, type FeColorMatrixPrimitive, type FeComponentTransferPrimitive, type FeCompositePrimitive, type FeConvolveMatrixPrimitive, type FeDiffuseLightingPrimitive, type FeDisplacementMapPrimitive, type FeDropShadowPrimitive, type FeFloodPrimitive, type FeGaussianBlurPrimitive, type FeImagePrimitive, type FeMergePrimitive, type FeMorphologyPrimitive, type FeOffsetPrimitive, type FeSpecularLightingPrimitive, type FeTilePrimitive, type FeTurbulencePrimitive, type FillType, type FilmGrainFilter, type FilterBlendMode, type FilterLibraryDef, type FilterLightSource, type FilterPrimitive, type FilterPrimitiveType, type FilterType, type GaussianBlurFilter, Gear, type GearNodeProps, type GlowFilter, type GouacheFilter, type GradientDefinition, type GradientSpreadMethod, type GradientStop, type GradientUnits, type GrayscaleFilter, type GroupNodeProps, type Guide, type HistorySnapshot, type HueRotateFilter, type ImageAttribution, type ImageNodeProps, ImageShape, type InkBlotFilter, type InnerGlowFilter, type InnerShadowFilter, type InvertFilter, LIBRARY_EMIT_ORDER, type LibraryDef, type LibraryDefBase, type LibraryDefOfKind, type LibraryKind, type LicenseType, type LightSource, Line, type LineEndpointValue, type LineNodeProps, type LinearEasingPoint, type LinearGradient, LinearGradientBuilder, type LinearGradientLibraryDef, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, MAX_COORDINATE_PRECISION, MIGRATIONS, type MarkerDescriptor, type MarkerLibraryDef, type Measurement, type Migration, type MorphologyFilter, type MorphologyOperator, type MotionBlurFilter, NGon, type NGonNodeProps, type NodeTypePropsMap, type NoiseFilter, type OpacityFilter, type OutlineFilter, type OutlinePosition, type ParseOptions, Path, PathCurveType, type PathNodeProps, type PathPoint, PathPointType, PatternBuilder, type PatternElement, type PatternFill, type PatternLibraryDef, type PatternParams, type PatternSvgContentResult, type PatternType, type PixelateFilter, type Point, type PointLightFilter, type PolygonBaseNodeProps, Polyline, type PolylineNodeProps, type RadialGradient, RadialGradientBuilder, type RadialGradientLibraryDef, type RawSvgFilter, Rectangle, type RectangleNodeProps, type RenderOptions, type RichTextData, type RichTextLine, type RichTextSegment, type RichTextSegmentStyle, type RiddledFilter, Ring, type RingNodeProps, type RoundEdgesFilter, type SaturateFilter, type SegmentCurveType, type SepiaFilter, type SerializedAnimationTimeline, type SerializedClipMaskGroup, type SerializedGroup, type SerializedMarkerDef, type SerializedShape, type SerializedSymbolDef, type SerializedVariantAxis, type SerializedViewbox, ShapeBuilder, type ShapeFilter, type ShapeMetadata, type SharpenFilter, type SpecularLightingFilter, Spiral, type SpiralNodeProps, type SpotLightFilter, Square, type SquareNodeProps, Star, type StarNodeProps, type StepPosition, type StepsParams, type StringifyOptions, type StrokeType, type SvgPrimitiveChainFilter, type SymbolInstanceNodeProps, type SymbolLibraryDef, type TemplateVariable, type TemplateVariableMode, type TemplateVariableSource, type TemplateVariableType, Text, type TextNodeProps, Timeline, Track, type TransferFunc, Triangle, type TriangleNodeProps, type ValidationError, type ValidationResult, type VariableMap, type Viewbox, type WarpFilter, type WarpType, type WatercolorFilter, type XrayFilter, collectReferencedLibraryIds, computeArrowVertices, computeCloudPath, computeCrossVertices, computeDashArray, computeGearPath, computeGearVertices, computeHeartPath, computeLightningVertices, computePolygonVertices, computeRectanglePath, computeRingPath, computeSpeechBubbleVertices, computeSpiralPath, computeSplinePath, computeStarVertices, createDocument, createShape, createViewbox, defaultVariableMode, escXml, extractVariables, filterAttr, generateCode, generateCssCode, generateD3Code, generateId, generatePatternSvgContent, generateReactCode, generateSvgCode, generateVueCode, getBuiltInMarkerDefs, getEasingCubicBezier, getEffectivePrecision, getMarkerDescriptors, getPatternElements, linearGradient, migrateSnapshot, parseDocument, parseVariableArgs, pattern, radialGradient, renderAnimationElements, renderBuiltinMarkerDefs, renderCircle, renderEllipse, renderFilterDefs, renderFilterLibraryDef, renderFilterPrimitive, renderFilterPrimitivesForType, renderImage, renderLibraryDef, renderLibraryDefs, renderLine, renderLinearGradientLibraryDef, renderMarkerLibraryDef, renderPatternLibraryDef, renderPolygonShape, renderPolyline, renderRadialGradientLibraryDef, renderRectangle, renderReferencedLibraryDefs, renderShape, renderSpline, renderSvgPrimitiveChainFilter, renderSymbolLibraryDef, renderText, renderToSvg, roundCoord, roundNumberString, roundSerializedShape, roundSnapshot, stringifyDocument, substituteString, substituteVariables, validateSnapshot, verticesToPath };
+export { type AnimatablePropertyDescriptor, type AnimationKeyframe, type AnimationTimeline, type AnimationTrack, type AnimationTrigger, type AnimationTriggerType, type AnyNodeProps, type ArcParams$1 as ArcParams, type AriaRole, Arrow, type ArrowNodeProps, Audio, BUILTIN_MARKER_ID_MAP, type BaseFilter, type BaseFilterPrimitive, type BlackAndWhiteFilter, type BlurQuality, type BrightnessFilter, CURRENT_SCHEMA_VERSION, type ChannelPainterFilter, Circle, type CircleNodeProps, Cloud, type CodeFormat, type CodegenOptions, type CommonNodeProps, type ConnectionDirection, type ConnectionPoint, Container, ContainerShapeBuilder, type ContouringDiscreteFilter, type ContouringTableFilter, type ContrastFilter, type CornerShapeValue, type CreateDocumentOptions, type CreateShapeOptions, Cross, type CrossNodeProps, type CrumpledPlasticFilter, type CustomPatternDef, type CycleBehavior, DEFAULT_COORDINATE_PRECISION, type DiffuseLightingFilter, Document, type DocumentMetadata, type DocumentNodeProps, type DocumentOptions, type DocumentScript, type DocumentStyle, type DropShadowFilter, type DuotoneFilter, EASING_CURVES, EVENT_TRIGGER_OPTIONS, EasingType, Ellipse, type EllipseNodeProps, type EmbossFilter, type ExtractedVariables, type FeBlendPrimitive, type FeColorMatrixPrimitive, type FeComponentTransferPrimitive, type FeCompositePrimitive, type FeConvolveMatrixPrimitive, type FeDiffuseLightingPrimitive, type FeDisplacementMapPrimitive, type FeDropShadowPrimitive, type FeFloodPrimitive, type FeGaussianBlurPrimitive, type FeImagePrimitive, type FeMergePrimitive, type FeMorphologyPrimitive, type FeOffsetPrimitive, type FeSpecularLightingPrimitive, type FeTilePrimitive, type FeTurbulencePrimitive, type FillType, type FilmGrainFilter, type FilterBlendMode, type FilterLibraryDef, type FilterLightSource, type FilterPrimitive, type FilterPrimitiveType, type FilterType, type GaussianBlurFilter, Gear, type GearNodeProps, type GlowFilter, type GouacheFilter, type GradientDefinition, type GradientSpreadMethod, type GradientStop, type GradientUnits, type GrayscaleFilter, type GroupNodeProps, type Guide, Heart, type HistorySnapshot, type HueRotateFilter, Hyperlink, type ImageAttribution, type ImageNodeProps, ImageShape, type InkBlotFilter, type InnerGlowFilter, type InnerShadowFilter, type InvertFilter, LIBRARY_EMIT_ORDER, type LibraryDef, type LibraryDefBase, type LibraryDefOfKind, type LibraryKind, type LicenseType, type LightSource, Lightning, Line, type LineEndpointValue, type LineNodeProps, type LinearEasingPoint, type LinearGradient, LinearGradientBuilder, type LinearGradientLibraryDef, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, MAX_COORDINATE_PRECISION, MIGRATIONS, type MarkerDescriptor, type MarkerLibraryDef, type Measurement, type Migration, type MorphologyFilter, type MorphologyOperator, type MotionBlurFilter, NGon, type NGonNodeProps, NestedSvg, type NodeTypePropsMap, type NoiseFilter, type OpacityFilter, type OutlineFilter, type OutlinePosition, type ParseOptions, Path, PathCurveType, type PathNodeProps, type PathPoint, PathPointType, PatternBuilder, type PatternElement, type PatternFill, type PatternLibraryDef, type PatternParams, type PatternSvgContentResult, type PatternType, type PixelateFilter, type Point, type PointLightFilter, type PolygonBaseNodeProps, Polyline, type PolylineNodeProps, type RadialGradient, RadialGradientBuilder, type RadialGradientLibraryDef, type RawSvgFilter, Rectangle, type RectangleNodeProps, type RenderOptions, type RichTextData, type RichTextLine, type RichTextSegment, type RichTextSegmentStyle, type RiddledFilter, Ring, type RingNodeProps, type RoundEdgesFilter, type SaturateFilter, type SegmentCurveType, type SepiaFilter, type SerializedAnimationTimeline, type SerializedClipMaskGroup, type SerializedColorGlyph, type SerializedColorGlyphLibrary, type SerializedGroup, type SerializedMarkerDef, type SerializedShape, type SerializedSymbolDef, type SerializedVariantAxis, type SerializedViewbox, ShapeBuilder, type ShapeFilter, type ShapeMetadata, ShapeReference, type SharpenFilter, type SpecularLightingFilter, SpeechBubble, Spiral, type SpiralNodeProps, type SpotLightFilter, Square, type SquareNodeProps, Star, type StarNodeProps, type StepPosition, type StepsParams, type StringifyOptions, type StrokeType, type SvgPrimitiveChainFilter, Switch, type SymbolInstanceNodeProps, type SymbolLibraryDef, type TemplateVariable, type TemplateVariableMode, type TemplateVariableSource, type TemplateVariableType, Text, type TextNodeProps, Timeline, Track, type TransferFunc, Triangle, type TriangleNodeProps, type ValidationError, type ValidationResult, type VariableMap, Video, View, type Viewbox, type WarpFilter, type WarpType, type WatercolorFilter, type XrayFilter, collectReferencedLibraryIds, computeArrowVertices, computeCloudPath, computeCrossVertices, computeDashArray, computeGearPath, computeGearVertices, computeHeartPath, computeLightningVertices, computePolygonVertices, computeRectanglePath, computeRingPath, computeSpeechBubbleVertices, computeSpiralPath, computeSplinePath, computeStarVertices, createDocument, createShape, createViewbox, defaultVariableMode, escXml, extractVariables, filterAttr, generateCode, generateCssCode, generateD3Code, generateId, generatePatternSvgContent, generateReactCode, generateSvgCode, generateVueCode, getBuiltInMarkerDefs, getEasingCubicBezier, getEffectivePrecision, getMarkerDescriptors, getPatternElements, linearGradient, migrateSnapshot, parseDocument, parseVariableArgs, pattern, radialGradient, renderAnimationElements, renderBuiltinMarkerDefs, renderCircle, renderEllipse, renderFilterDefs, renderFilterLibraryDef, renderFilterPrimitive, renderFilterPrimitivesForType, renderImage, renderLibraryDef, renderLibraryDefs, renderLine, renderLinearGradientLibraryDef, renderMarkerLibraryDef, renderPatternLibraryDef, renderPolygonShape, renderPolyline, renderRadialGradientLibraryDef, renderRectangle, renderReferencedLibraryDefs, renderShape, renderSpline, renderSvgPrimitiveChainFilter, renderSymbolLibraryDef, renderText, renderToSvg, roundCoord, roundNumberString, roundSerializedShape, roundSnapshot, stringifyDocument, substituteString, substituteVariables, validateSnapshot, verticesToPath };