@svgsketch/core 0.6.0 → 1.0.0

package/dist/index.d.mts

@@ -136,6 +136,32 @@ interface AnimationTrack {
     locked: boolean;
     /** SVG path data for motion-path animation (property should be 'pathMotion'). */
     motionPath?: string;
+    /**
+     * When set, the motion path was authored as a reference to another shape
+     * (SVG `<mpath href="#shapeId"/>`). `motionPath` still holds the resolved
+     * path data string (kept in sync with the referenced shape's geometry) so
+     * the runtime renderer doesn't need to dereference; the `mode` field
+     * controls how that data is interpreted and whether export can round-trip
+     * the reference as `<mpath>`.
+     *
+     * - `'trackShape'` — motionPath is displacement-relative to the animated
+     *   element's center, so the overlay and playback render on top of the
+     *   referenced shape's absolute canvas position ("follow this shape").
+     *   Exports as inline `path=` because `<mpath>` would double-offset.
+     * - `'curveTemplate'` — motionPath is normalized so `M 0,0` is the
+     *   animation's starting displacement ("trace this curve from wherever
+     *   the element is"). Exports spec-correctly as `<mpath href>` since
+     *   the referenced shape's `d` (normalized to origin) matches the stored
+     *   motionPath byte-for-byte, enabling reuse across animations.
+     *
+     * Missing `mode` (legacy data) defaults to `'trackShape'` for back-compat.
+     *
+     * @see https://svgwg.org/specs/animations/#MPathElement
+     */
+    motionPathRef?: {
+        shapeId: string;
+        mode?: 'trackShape' | 'curveTemplate';
+    };
     /** Trigger to begin the animation (defaults to '0s'). */
     beginTrigger?: AnimationTrigger;
     /** Trigger to end the animation. */
@@ -206,6 +232,12 @@ interface SerializedAnimationTimeline {
         locked?: boolean;
         motionPath?: string;
         motionPathMatrix?: number[];
+        /** See `AnimationTrack.motionPathRef`. Persists the authoring reference to
+         *  another shape's geometry so a round-trip re-emits `<mpath href>`. */
+        motionPathRef?: {
+            shapeId: string;
+            mode?: 'trackShape' | 'curveTemplate';
+        };
         beginTrigger?: AnimationTrigger;
         endTrigger?: AnimationTrigger;
         cycleDuration?: number;
@@ -237,6 +269,43 @@ interface SerializedAnimationTimeline {
             x: number;
             y: number;
         };
+        /**
+         * CSS selector for a DOM element to animate directly, used when the
+         * animation target is not an editor Shape — e.g. an `<animateTransform
+         * xlink:href="#rect1"/>` whose target lives inside a `<clipPath>`
+         * definition. The track's `shapeId` is a synthetic `__dom__<id>` in
+         * this case (no editor Shape exists to bind to). Without this field,
+         * the SMIL exporter has no way to re-locate the target after a
+         * save/reload round-trip and silently drops every clip/mask-internal
+         * animation.
+         */
+        domTargetSelector?: string;
+        /**
+         * For `property === 'domTransformStack'` tracks: the original
+         * `<animateTransform>` `type` function (`translate` / `scale` /
+         * `rotate` / `skewX` / `skewY` / `matrix`). The SMIL exporter
+         * (`addDomTransformStackEntry`) early-returns when this is missing,
+         * silently dropping every stacked DOM-transform animation across
+         * save/reload. Per SVG Animation §19.4.2 the export must re-emit
+         * the same `type` — and per SMIL §4.2 the document-order index
+         * (`transformStackIndex`) controls additive composition of the
+         * stack. Both are essential for clip/mask internal animations.
+         */
+        transformFunction?: 'translate' | 'scale' | 'rotate' | 'skewX' | 'skewY' | 'matrix';
+        /**
+         * For `property === 'domTransformStack'` tracks: document-order
+         * index within the target element's `<animateTransform>` stack.
+         * The renderer sorts tracks by this index before applying the
+         * SMIL animation sandwich (SVG 2 §19.2.7).
+         */
+        transformStackIndex?: number;
+        /**
+         * For `property === 'domTransformStack'` tracks: the target
+         * element's pre-animation `transform` attribute value (the
+         * underlying value in the SMIL animation sandwich). Captured at
+         * import time.
+         */
+        transformBaseValue?: string;
         keyframes: {
             time: number;
             value: number | string;
@@ -280,7 +349,7 @@ interface AnimatablePropertyDescriptor {
  * Only enums referenced by SerializedShape or HistorySnapshot live here.
  * Editor-only enums (Mode, ControlPointPosition, etc.) stay in the editor.
  */
-declare enum SplineCurveType {
+declare enum PathCurveType {
     LINEAR = "linear",
     QUADRATIC = "quadratic",
     CUBIC = "cubic",
@@ -289,7 +358,7 @@ declare enum SplineCurveType {
     BASIS = "basis",
     MIXED = "mixed"
 }
-declare enum SplinePointType {
+declare enum PathPointType {
     SMOOTH = "smooth",
     CORNER = "corner",
     SYMMETRIC = "symmetric"
@@ -387,6 +456,14 @@ interface RadialGradient {
     r: number;
     ry: number;
     rotation: number;
+    /**
+     * Focal-circle radius (SVG 2 §14.2.3.1 `fr`). When present and > 0, the
+     * gradient's first stop is rendered along this circle (not at a single
+     * focal point) — produces a "donut" radial gradient. Same coordinate
+     * space as `r` (i.e. governed by `gradientUnits`). Defaults to 0
+     * when omitted, matching the spec's initial value and pre-SVG-2 behaviour.
+     */
+    fr?: number;
     stops: GradientStop[];
     spreadMethod: GradientSpreadMethod;
     opacity: number;
@@ -531,7 +608,7 @@ interface CustomPatternDef {
     /** Tile height in userSpaceOnUse coordinates. */
     height: number;
 }
-type FilterType = 'drop-shadow' | 'inner-shadow' | 'gaussian-blur' | 'motion-blur' | 'point-light' | 'spot-light' | 'diffuse-lighting' | 'specular-lighting' | 'outline' | 'sharpen' | 'pixelate' | 'warp' | 'morphology' | 'contouring-discrete' | 'contouring-table' | 'round-edges' | 'grayscale' | 'channel-painter' | 'brightness' | 'contrast' | 'opacity' | 'invert' | 'hue-rotate' | 'saturate' | 'black-and-white' | 'sepia' | 'duotone' | 'xray' | 'noise' | 'emboss' | 'film-grain' | 'watercolor' | 'gouache' | 'ink-blot' | 'crumpled-plastic' | 'riddled' | 'glow' | 'inner-glow' | 'raw-svg';
+type FilterType = 'drop-shadow' | 'inner-shadow' | 'gaussian-blur' | 'motion-blur' | 'point-light' | 'spot-light' | 'diffuse-lighting' | 'specular-lighting' | 'outline' | 'sharpen' | 'pixelate' | 'warp' | 'morphology' | 'contouring-discrete' | 'contouring-table' | 'round-edges' | 'grayscale' | 'channel-painter' | 'brightness' | 'contrast' | 'opacity' | 'invert' | 'hue-rotate' | 'saturate' | 'black-and-white' | 'sepia' | 'duotone' | 'xray' | 'noise' | 'emboss' | 'film-grain' | 'watercolor' | 'gouache' | 'ink-blot' | 'crumpled-plastic' | 'riddled' | 'glow' | 'inner-glow' | 'raw-svg' | 'svg-primitive-chain';
 type BlurQuality = 'normal' | 'high';
 interface BaseFilter {
     id: string;
@@ -799,14 +876,265 @@ interface RawSvgFilter extends BaseFilter {
     floodOpacity?: string;
     lightingColor?: string;
 }
-type ShapeFilter = DropShadowFilter | InnerShadowFilter | GaussianBlurFilter | MotionBlurFilter | PointLightFilter | SpotLightFilter | DiffuseLightingFilter | SpecularLightingFilter | OutlineFilter | SharpenFilter | PixelateFilter | WarpFilter | MorphologyFilter | ContouringDiscreteFilter | ContouringTableFilter | RoundEdgesFilter | GrayscaleFilter | ChannelPainterFilter | BrightnessFilter | ContrastFilter | OpacityFilter | InvertFilter | HueRotateFilter | SaturateFilter | BlackAndWhiteFilter | SepiaFilter | DuotoneFilter | XrayFilter | NoiseFilter | EmbossFilter | FilmGrainFilter | WatercolorFilter | GouacheFilter | InkBlotFilter | CrumpledPlasticFilter | RiddledFilter | GlowFilter | InnerGlowFilter | RawSvgFilter;
-type SegmentCurveType = 'LINEAR' | 'CUBIC' | 'QUADRATIC' | 'ARC';
-interface SplinePoint {
+type ShapeFilter = DropShadowFilter | InnerShadowFilter | GaussianBlurFilter | MotionBlurFilter | PointLightFilter | SpotLightFilter | DiffuseLightingFilter | SpecularLightingFilter | OutlineFilter | SharpenFilter | PixelateFilter | WarpFilter | MorphologyFilter | ContouringDiscreteFilter | ContouringTableFilter | RoundEdgesFilter | GrayscaleFilter | ChannelPainterFilter | BrightnessFilter | ContrastFilter | OpacityFilter | InvertFilter | HueRotateFilter | SaturateFilter | BlackAndWhiteFilter | SepiaFilter | DuotoneFilter | XrayFilter | NoiseFilter | EmbossFilter | FilmGrainFilter | WatercolorFilter | GouacheFilter | InkBlotFilter | CrumpledPlasticFilter | RiddledFilter | GlowFilter | InnerGlowFilter | RawSvgFilter | SvgPrimitiveChainFilter;
+/** Common attributes on every filter primitive (FE1 §7.2). */
+interface BaseFilterPrimitive {
+    /** Editor-only stable id; not serialized to SVG. */
+    id: string;
+    /** SourceGraphic | SourceAlpha | BackgroundImage | BackgroundAlpha |
+     *  FillPaint | StrokePaint | <filter-primitive-reference>. Omitted ⇒
+     *  defaults to previous primitive's result (or SourceGraphic if first). */
+    in?: string;
+    /** Custom result name for forward references. Omitted ⇒ implicit. */
+    result?: string;
+    /** Filter primitive subregion (FE1 §7.3). */
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+    /** Per-primitive override of color-interpolation-filters. */
+    colorInterpolationFilters?: 'auto' | 'sRGB' | 'linearRGB';
+    /** Carry of attributes the editor doesn't model (style, class, data-*,
+     *  unknown spec attrs). Re-emitted verbatim. Keys exclude attrs already
+     *  modeled on this primitive. */
+    unknownAttrs?: Record<string, string>;
+    /** SMIL animation children attached to this primitive — preserved
+     *  verbatim. Each entry is the outerHTML of an <animate>, <set>,
+     *  <animateTransform>, or <animateMotion> element. */
+    animations?: string[];
+}
+/** Blend modes per Compositing 1 §3 + the FE1-specific extensions. */
+type FilterBlendMode = 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'plus-darker' | 'plus-lighter';
+interface FeBlendPrimitive extends BaseFilterPrimitive {
+    type: 'feBlend';
+    in2?: string;
+    mode?: FilterBlendMode;
+    /** FE1 extension — boolean attribute, presence-based. */
+    noComposite?: boolean;
+}
+interface FeColorMatrixPrimitive extends BaseFilterPrimitive {
+    type: 'feColorMatrix';
+    matrixType?: 'matrix' | 'saturate' | 'hueRotate' | 'luminanceToAlpha';
+    /** Verbatim attribute string so we preserve the exact author spelling
+     *  (matrix arg counts, whitespace inside). Omitted ⇒ spec defaults
+     *  apply (matrix=identity, saturate=1, hueRotate=0). */
+    values?: string;
+}
+type TransferFunc = {
+    type: 'identity';
+} | {
+    type: 'table' | 'discrete';
+    tableValues: number[];
+} | {
+    type: 'linear';
+    slope?: number;
+    intercept?: number;
+} | {
+    type: 'gamma';
+    amplitude?: number;
+    exponent?: number;
+    offset?: number;
+};
+interface FeComponentTransferPrimitive extends BaseFilterPrimitive {
+    type: 'feComponentTransfer';
+    funcR?: TransferFunc;
+    funcG?: TransferFunc;
+    funcB?: TransferFunc;
+    funcA?: TransferFunc;
+}
+interface FeCompositePrimitive extends BaseFilterPrimitive {
+    type: 'feComposite';
+    in2?: string;
+    operator?: 'over' | 'in' | 'out' | 'atop' | 'xor' | 'lighter' | 'arithmetic';
+    k1?: number;
+    k2?: number;
+    k3?: number;
+    k4?: number;
+}
+interface FeConvolveMatrixPrimitive extends BaseFilterPrimitive {
+    type: 'feConvolveMatrix';
+    /** <number-optional-number>; preserved as authored (e.g. "3" or "3 3"). */
+    order?: string;
+    /** Space-separated kernel values, preserved as authored. */
+    kernelMatrix?: string;
+    divisor?: number;
+    bias?: number;
+    targetX?: number;
+    targetY?: number;
+    edgeMode?: 'duplicate' | 'wrap' | 'none';
+    /** <number-optional-number>; preserved as authored. */
+    kernelUnitLength?: string;
+    preserveAlpha?: boolean;
+}
+/** Light source elements (FE1 §16) — never appear at <filter> top level,
+ *  only as children of feDiffuseLighting/feSpecularLighting. */
+type FilterLightSource = {
+    kind: 'feDistantLight';
+    azimuth?: number;
+    elevation?: number;
+} | {
+    kind: 'fePointLight';
+    x?: number;
+    y?: number;
+    z?: number;
+} | {
+    kind: 'feSpotLight';
+    x?: number;
+    y?: number;
+    z?: number;
+    pointsAtX?: number;
+    pointsAtY?: number;
+    pointsAtZ?: number;
+    specularExponent?: number;
+    limitingConeAngle?: number;
+};
+interface FeDiffuseLightingPrimitive extends BaseFilterPrimitive {
+    type: 'feDiffuseLighting';
+    surfaceScale?: number;
+    diffuseConstant?: number;
+    /** <number-optional-number>; preserved as authored. */
+    kernelUnitLength?: string;
+    lightingColor?: string;
+    lightSource?: FilterLightSource;
+}
+interface FeSpecularLightingPrimitive extends BaseFilterPrimitive {
+    type: 'feSpecularLighting';
+    surfaceScale?: number;
+    specularConstant?: number;
+    specularExponent?: number;
+    kernelUnitLength?: string;
+    lightingColor?: string;
+    lightSource?: FilterLightSource;
+}
+interface FeDisplacementMapPrimitive extends BaseFilterPrimitive {
+    type: 'feDisplacementMap';
+    in2?: string;
+    scale?: number;
+    xChannelSelector?: 'R' | 'G' | 'B' | 'A';
+    yChannelSelector?: 'R' | 'G' | 'B' | 'A';
+}
+interface FeDropShadowPrimitive extends BaseFilterPrimitive {
+    type: 'feDropShadow';
+    dx?: number;
+    dy?: number;
+    /** <number-optional-number>; preserved as authored. */
+    stdDeviation?: string;
+    floodColor?: string;
+    /** Numeric value or the literal 'inherit'. */
+    floodOpacity?: string;
+}
+interface FeFloodPrimitive extends BaseFilterPrimitive {
+    type: 'feFlood';
+    floodColor?: string;
+    floodOpacity?: string;
+}
+interface FeGaussianBlurPrimitive extends BaseFilterPrimitive {
+    type: 'feGaussianBlur';
+    /** <number-optional-number>; preserved as authored (e.g. "3" or "3 1"). */
+    stdDeviation?: string;
+    edgeMode?: 'duplicate' | 'wrap' | 'none';
+}
+interface FeImagePrimitive extends BaseFilterPrimitive {
+    type: 'feImage';
+    /** Canonical (SVG 2). */
+    href?: string;
+    /** Back-compat alias re-emitted only when the original used xlink:href
+     *  and no href was authored. */
+    xlinkHref?: string;
+    preserveAspectRatio?: string;
+    crossorigin?: 'anonymous' | 'use-credentials';
+}
+interface FeMergePrimitive extends BaseFilterPrimitive {
+    type: 'feMerge';
+    /** <feMergeNode> children inlined. */
+    nodes: {
+        in?: string;
+    }[];
+}
+interface FeMorphologyPrimitive extends BaseFilterPrimitive {
+    type: 'feMorphology';
+    operator?: 'erode' | 'dilate';
+    /** <number-optional-number>; preserved as authored. */
+    radius?: string;
+}
+interface FeOffsetPrimitive extends BaseFilterPrimitive {
+    type: 'feOffset';
+    dx?: number;
+    dy?: number;
+}
+interface FeTilePrimitive extends BaseFilterPrimitive {
+    type: 'feTile';
+}
+interface FeTurbulencePrimitive extends BaseFilterPrimitive {
+    type: 'feTurbulence';
+    /** <number-optional-number>; preserved as authored. */
+    baseFrequency?: string;
+    numOctaves?: number;
+    seed?: number;
+    stitchTiles?: 'stitch' | 'noStitch';
+    turbulenceType?: 'fractalNoise' | 'turbulence';
+}
+type FilterPrimitive = FeBlendPrimitive | FeColorMatrixPrimitive | FeComponentTransferPrimitive | FeCompositePrimitive | FeConvolveMatrixPrimitive | FeDiffuseLightingPrimitive | FeSpecularLightingPrimitive | FeDisplacementMapPrimitive | FeDropShadowPrimitive | FeFloodPrimitive | FeGaussianBlurPrimitive | FeImagePrimitive | FeMergePrimitive | FeMorphologyPrimitive | FeOffsetPrimitive | FeTilePrimitive | FeTurbulencePrimitive;
+type FilterPrimitiveType = FilterPrimitive['type'];
+/**
+ * A `<filter>` element modeled as an ordered list of editable primitives.
+ *
+ * This variant is the parser's default when no curated stylized preset
+ * matches — it preserves every spec primitive 1:1 so imported third-party
+ * SVG round-trips with semantic equivalence and remains editable in the
+ * filters panel. Distinct from `RawSvgFilter` (which is opaque XML
+ * passthrough); this one walks the primitives.
+ */
+interface SvgPrimitiveChainFilter extends BaseFilter {
+    type: 'svg-primitive-chain';
+    /** <filter> wrapper attributes — all optional; omitted ⇒ UA spec default. */
+    filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+    filterColorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
+    /** Inheritable presentation attrs author placed on <filter> so child
+     *  primitives can resolve them via the CSS `inherit` keyword. */
+    floodColor?: string;
+    floodOpacity?: string;
+    lightingColor?: string;
+    /** <title> child text, captured for a11y/round-trip. */
+    filterTitle?: string;
+    filterDescription?: string;
+    /** SMIL animation children directly on <filter> (rare). */
+    filterAnimations?: string[];
+    /** The primitive chain. Order is significant — implicit input chains
+     *  match document order. */
+    primitives: FilterPrimitive[];
+}
+/**
+ * Per-segment command hint, recording the SVG path command the segment
+ * was authored with. Lets the serializer emit the original command form
+ * (H, V, S, T, A) when the current geometry still satisfies its
+ * constraints — and auto-demote to L/C/Q when a user edit invalidates
+ * the shorthand condition. Replaces the old `originalD` round-trip
+ * cache with a property of the geometry itself.
+ *
+ *  - LINEAR            → `L` (default for handle-less segments)
+ *  - HORIZONTAL        → `H`; valid when `from.y === to.y`
+ *  - VERTICAL          → `V`; valid when `from.x === to.x`
+ *  - CUBIC             → `C`
+ *  - SMOOTH_CUBIC      → `S`; valid when `to.handleIn` reflects the previous
+ *                        segment's exit-tangent about the previous endpoint
+ *  - QUADRATIC         → `Q`
+ *  - SMOOTH_QUADRATIC  → `T`; valid when the implicit control reflects the
+ *                        previous quadratic's control about the current point
+ *  - ARC               → `A`
+ */
+type SegmentCurveType = 'LINEAR' | 'HORIZONTAL' | 'VERTICAL' | 'CUBIC' | 'SMOOTH_CUBIC' | 'QUADRATIC' | 'SMOOTH_QUADRATIC' | 'ARC';
+interface PathPoint {
     x: number;
     y: number;
     handleIn?: Point;
     handleOut?: Point;
-    pointType: SplinePointType;
+    pointType: PathPointType;
     isSubpathStart?: boolean;
     segmentType?: SegmentCurveType;
     arcParams?: ArcParams$1;
@@ -818,6 +1146,12 @@ interface ArcParams$1 {
     largeArc: boolean;
     sweep: boolean;
 }
+/**
+ * Hyperlink target per SVG 2 §16.2. Kept for UI convenience — the four
+ * well-known keywords plus any authored `<XML-Name>` (custom named
+ * browsing context). Hyperlink shapes themselves store target as a plain
+ * string so arbitrary names round-trip.
+ */
 type LinkTarget = '_self' | '_blank' | '_parent' | '_top';
 type AriaRole = '' | 'img' | 'button' | 'link' | 'presentation' | 'none' | 'graphics-document' | 'graphics-object' | 'graphics-symbol';
 interface ShapeMetadata {
@@ -827,9 +1161,38 @@ interface ShapeMetadata {
     description: string;
     role: AriaRole;
     ariaLabel: string;
-    linkUrl: string;
-    linkTarget: LinkTarget;
     customData: Record<string, string>;
+    /**
+     * Hyperlink target — when set, the shape is rendered inside an SVG `<a>`
+     * element with `href="${linkUrl}"`. Round-trips through SVG import/export.
+     */
+    linkUrl?: string;
+    /** Hyperlink target window — maps to `<a target="...">`. */
+    linkTarget?: LinkTarget;
+    /**
+     * Lossless carrier for any `<metadata>` elements that appeared as children
+     * of this shape's SVG element. Stored as a serialized string containing
+     * one or more complete `<metadata ...>...</metadata>` blocks in document
+     * order. Preserves element-level attributes (id, lang, class, style,
+     * xml:space), arbitrary child elements from any namespace, character data,
+     * mixed content, and multiple sibling blocks.
+     *
+     * Spec: SVG 2 §5.8 — content model is "Any elements or character data",
+     * and the element may appear on any container or graphical element.
+     */
+    rawMetadata?: string;
+    /**
+     * Lossless carrier for the inner XML of the `<desc>` element when it
+     * contains foreign XML (per SVG 2 §5.7 — the spec example shows
+     * `<myfoo:…>` elements inside `<desc>`). Populated only when `<desc>`
+     * has non-text children; plain-prose desc uses `description` alone.
+     *
+     * Emit rule: if the textContent of `rawDescription` still equals the
+     * current `description` value, emit the raw (foreign XML round-trips).
+     * If `description` has been edited and the textual views diverge, emit
+     * plain text from `description` (user intent takes precedence).
+     */
+    rawDescription?: string;
 }
 /**
  * Provider attribution metadata for an image shape sourced from a third-party
@@ -868,6 +1231,29 @@ interface DocumentMetadata {
     licenseUrl: string;
     language: string;
     customMetadata: Record<string, string>;
+    /**
+     * Lossless carrier for any `<metadata>` elements that appeared as direct
+     * children of the root `<svg>`. Stored as a serialized string containing
+     * one or more complete `<metadata ...>...</metadata>` blocks in document
+     * order. Preserves element-level attributes, arbitrary child elements
+     * from any namespace (RDF, XMP, Inkscape, custom), character data and
+     * mixed content, and multiple sibling blocks.
+     *
+     * Typed fields above (`author`, `keywords`, `license`, `licenseUrl`,
+     * `customMetadata`) are a structured view over a designated managed
+     * `<rdf:Description>` inside this carrier. On export the managed
+     * description is spliced into the preserved raw; foreign siblings and
+     * non-RDF content survive untouched.
+     *
+     * Spec: SVG 2 §5.8.
+     */
+    rawMetadata?: string;
+    /**
+     * Lossless carrier for the inner XML of the document-level `<desc>`
+     * element when it contains foreign XML (SVG 2 §5.7). Mirrors
+     * `ShapeMetadata.rawDescription`; see there for the emit rule.
+     */
+    rawDescription?: string;
     /**
      * Decimal precision for coordinate values when the document is
      * serialized — file save, cloud sync, undo capture, and SVG export.
@@ -949,6 +1335,24 @@ interface DocumentStyle {
 }
 /** Type of a template variable's value. */
 type TemplateVariableType = 'string' | 'color' | 'number';
+/**
+ * How the variable participates in export. Two genuinely different
+ * substitution mechanisms — declaring intent up-front lets the export
+ * pipeline pick the right one.
+ *
+ *   - `live`     → emitted as `var(--name, fallback)` references; the
+ *                  variable definition rides along in a `<style>` block,
+ *                  so consumers can re-theme the SVG at runtime via the
+ *                  CSS cascade.
+ *   - `stamped`  → resolved to its literal value at export time. Used
+ *                  for `{{name}}` template-style stamping, and for
+ *                  attributes (`width`, `x`, geometry) where `var()`
+ *                  in attribute values has uneven interop.
+ *
+ * Defaults to `live` for `color` (well-supported in browsers), `stamped`
+ * for `number`/`string` (where attribute-level var() is unreliable).
+ */
+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
@@ -995,7 +1399,19 @@ interface TemplateVariable {
      * settings palette.
      */
     source?: TemplateVariableSource;
+    /**
+     * Substitution mode at export time. When omitted, callers should
+     * apply the type-based default in `defaultVariableMode()`:
+     * `color` → `live`, `number`/`string` → `stamped`.
+     */
+    mode?: TemplateVariableMode;
 }
+/**
+ * Type-based default substitution mode. Color variables work reliably as
+ * runtime `var()` references in browsers; numbers and strings are far
+ * better baked into literal attribute values at export time.
+ */
+declare function defaultVariableMode(type: TemplateVariableType): TemplateVariableMode;
 interface Guide {
     id: string;
     orientation: 'horizontal' | 'vertical';
@@ -1015,261 +1431,11 @@ interface Measurement {
 }
 
 /**
- * Typed property interfaces for every node type in the scene graph.
- *
- * This is the **single source of truth** for shape property types across
- * the entire SVGSketch stack (editor, API worker, server renderer, etc.).
+ * @svgsketch/core — Serialized document types.
  *
- * Each shape type declares the exact set of properties it owns.
- * These interfaces drive:
- * - Compile-time type safety on `SceneNode.get()` / `.set()` calls
- * - The `NodeTypePropsMap` lookup used by `SceneNode.create()`
- * - Schema defaults and validators in the editor's `node-schema.ts`
- * - Serialization format for the `.svgs` document format
- */
-
-interface CommonNodeProps {
-    fillColor: string;
-    borderColor: string;
-    borderWidth: number;
-    opacity: number;
-    fillOpacity: number;
-    strokeOpacity: number;
-    rotation: number;
-    skewX: number;
-    skewY: number;
-    customPivot: Point | null;
-    locked: boolean;
-    visible: boolean;
-    fillType: string;
-    fillGradient: unknown | null;
-    strokeType: string;
-    strokeGradient: unknown | null;
-    fillRule: 'nonzero' | 'evenodd';
-    strokeLinejoin: 'miter' | 'round' | 'bevel';
-    strokeLinecap: 'butt' | 'round' | 'square';
-    strokeMiterlimit: number;
-    lineStyle: string;
-    dashLength: number;
-    gapLength: number;
-    dashOffset: number;
-    strokeDasharray: string | null;
-    filters: unknown[];
-    filterColorInterpolation: 'auto' | 'sRGB' | 'linearRGB' | null;
-    filterUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
-    primitiveUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
-    filterX: string | null;
-    filterY: string | null;
-    filterWidth: string | null;
-    filterHeight: string | null;
-    rawTransform: string | null;
-    metadata: unknown | null;
-    cssClipPath: string | null;
-    cssMaskProperties: Record<string, string> | null;
-    groupId: string | null;
-}
-type CornerShapeValue = 'round' | 'notch' | 'bevel' | 'scoop';
-interface RectangleNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    cornerRadius: number;
-    cornerShape: CornerShapeValue;
-    cornerMode: 'uniform' | 'non-uniform';
-    cornerRadiusTL: number;
-    cornerRadiusTR: number;
-    cornerRadiusBL: number;
-    cornerRadiusBR: number;
-    cornerShapeTL: CornerShapeValue;
-    cornerShapeTR: CornerShapeValue;
-    cornerShapeBL: CornerShapeValue;
-    cornerShapeBR: CornerShapeValue;
-}
-type SquareNodeProps = RectangleNodeProps;
-interface CircleNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    radius: number;
-}
-interface EllipseNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    rx: number;
-    ry: number;
-}
-type LineEndpointValue = 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
-interface LineNodeProps extends CommonNodeProps {
-    x1: number;
-    y1: number;
-    x2: number;
-    y2: number;
-    startEndpoint: LineEndpointValue;
-    endEndpoint: LineEndpointValue;
-}
-interface TextNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    textX: number;
-    textY: number;
-    fontSize: number;
-    text: string;
-    fontFamily: string;
-    fontWeight: string;
-    fontStyle: string;
-    textDecoration: Record<string, boolean>;
-    textTransform: string;
-    baselineShift: string;
-    dominantBaseline: string;
-    writingMode: string;
-    textAnchor: string;
-    letterSpacing: number;
-    wordSpacing: number;
-    lineHeight: number;
-    inlineSize: number;
-    overflowWrap: string;
-    whiteSpace: string;
-    textDirection: string;
-    unicodeBidi: string;
-    scaleX: number;
-    scaleY: number;
-    scaleAnchor: Point | null;
-    useRichText: boolean;
-    richTextData: unknown | null;
-    charOffsets: {
-        x: number;
-        y: number;
-        rotate: number;
-    }[] | null;
-    fontVariationSettings: Record<string, number>;
-    isTextPath: boolean;
-    textPathPoints: unknown[] | null;
-    textPathStartOffset: number;
-    textPathSide: 'left' | 'right';
-    shapeInsideRef: string | null;
-    shapePadding: number;
-}
-interface ImageNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    href: string;
-    originalWidth: number;
-    originalHeight: number;
-    preserveAspectRatio: boolean;
-    imageOpacity: number;
-}
-interface SplineNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    splinePoints: unknown[];
-    splineArcParams: unknown[];
-    splineControlBounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    } | null;
-    startEndpoint: LineEndpointValue;
-    endEndpoint: LineEndpointValue;
-}
-interface PolylineNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    polylinePoints: Point[];
-    polylineClosed: boolean;
-}
-interface PolygonBaseNodeProps extends CommonNodeProps {
-    cx: number;
-    cy: number;
-    radius: number;
-    cornerRadius: number;
-    shiftAngle: number;
-}
-interface TriangleNodeProps extends PolygonBaseNodeProps {
-    sides: 3;
-}
-interface NGonNodeProps extends PolygonBaseNodeProps {
-    sides: number;
-}
-interface StarNodeProps extends PolygonBaseNodeProps {
-    arms: number;
-    innerRadiusPercent: number;
-}
-interface CrossNodeProps extends PolygonBaseNodeProps {
-    armWidthPercent: number;
-}
-interface RingNodeProps extends PolygonBaseNodeProps {
-    innerRadiusPercent: number;
-}
-interface SpiralNodeProps extends PolygonBaseNodeProps {
-    turns: number;
-    thicknessPercent: number;
-    spiralDirection: number;
-}
-interface GearNodeProps extends PolygonBaseNodeProps {
-    teeth: number;
-    toothDepthPercent: number;
-    holeRadiusPercent: number;
-}
-interface ArrowNodeProps extends PolygonBaseNodeProps {
-    headWidthPercent: number;
-    headLengthPercent: number;
-    shaftWidthPercent: number;
-}
-interface SymbolInstanceNodeProps extends CommonNodeProps {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    symbolId: string;
-}
-interface GroupNodeProps {
-    groupId: string | null;
-}
-type DocumentNodeProps = Record<string, never>;
-/**
- * Maps each node type string to its typed property interface.
- * Used by `SceneNode.create()` for compile-time type safety.
- */
-interface NodeTypePropsMap {
-    rectangle: RectangleNodeProps;
-    square: SquareNodeProps;
-    circle: CircleNodeProps;
-    ellipse: EllipseNodeProps;
-    line: LineNodeProps;
-    text: TextNodeProps;
-    image: ImageNodeProps;
-    spline: SplineNodeProps;
-    polyline: PolylineNodeProps;
-    triangle: TriangleNodeProps;
-    ngon: NGonNodeProps;
-    star: StarNodeProps;
-    cross: CrossNodeProps;
-    ring: RingNodeProps;
-    spiral: SpiralNodeProps;
-    gear: GearNodeProps;
-    arrow: ArrowNodeProps;
-    'symbol-instance': SymbolInstanceNodeProps;
-    group: GroupNodeProps;
-    document: DocumentNodeProps;
-}
-/** Union of all node prop types. */
-type AnyNodeProps = RectangleNodeProps | SquareNodeProps | CircleNodeProps | EllipseNodeProps | LineNodeProps | TextNodeProps | ImageNodeProps | SplineNodeProps | PolylineNodeProps | TriangleNodeProps | NGonNodeProps | StarNodeProps | CrossNodeProps | RingNodeProps | SpiralNodeProps | GearNodeProps | ArrowNodeProps | SymbolInstanceNodeProps | GroupNodeProps | DocumentNodeProps;
-
-/**
- * @svgsketch/core — Serialized document types.
- *
- * These types define the .svgs document format. SerializedShape and
- * HistorySnapshot are the canonical data structures for persisting
- * SVGSketch documents.
+ * These types define the .svgs document format. SerializedShape and
+ * HistorySnapshot are the canonical data structures for persisting
+ * SVGSketch documents.
  */
 
 interface SerializedShape {
@@ -1319,11 +1485,31 @@ interface SerializedShape {
         textDirection?: 'ltr' | 'rtl';
         unicodeBidi?: 'normal' | 'embed' | 'bidi-override' | 'isolate' | 'isolate-override' | 'plaintext';
         fontVariationSettings?: Record<string, number>;
-        charOffsets?: {
+        /**
+         * Per-glyph positioning data, mirroring SVG 2 §11.2's five attribute
+         * lists (`x`, `y`, `dx`, `dy`, `rotate`).
+         *
+         *  - `x`/`y` are absolute user coordinates; `null` means "no
+         *    override at this glyph — the cursor advances naturally".
+         *  - `dx`/`dy` are additive shifts on top of natural advance.
+         *  - `rotate` is per-glyph rotation in degrees.
+         *
+         * For backward compatibility, the legacy three-field shape
+         * `{x, y, rotate}` (produced before the spec-aligned model shipped)
+         * is still accepted on read; its `x`/`y` are interpreted as the
+         * additive shifts (`dx`/`dy`).
+         */
+        charOffsets?: ({
+            x: number | null;
+            y: number | null;
+            dx: number;
+            dy: number;
+            rotate: number;
+        } | {
             x: number;
             y: number;
             rotate: number;
-        }[];
+        })[];
         linePositions?: {
             x: number;
             dy: number;
@@ -1352,9 +1538,29 @@ interface SerializedShape {
         borderColor?: string;
         borderWidth?: number | string;
         strokeOpacity?: number;
+        /**
+         * Inherit `fill` from the ancestor cascade rather than emit an explicit
+         * attribute. Set at import for shapes inside `<defs>`/`<symbol>` that
+         * have no own `fill` — they're reachable only via `<use>`, whose shadow
+         * tree inherits paint from the `<use>` element itself (SVG 2 §5.5.4).
+         * Baking the SVG-default black onto the inner shape would block the
+         * `<use fill="…">` cascade and render the instance override dead.
+         */
+        inheritFill?: boolean;
+        /** See {@link inheritFill}. */
+        inheritStroke?: boolean;
         /** CSS `paint-order` (SVG 2). Canonical SVG token string, e.g.
          *  'stroke fill markers'. Omitted when equivalent to default 'normal'. */
         paintOrder?: string;
+        /**
+         * CSS Transforms 2 §6.2 — `transform-box` reference box. SVG
+         * default is `view-box`; persisted on the shape so authored values
+         * (`fill-box`, `stroke-box`) survive round-trip. The editor bakes
+         * `transform-origin` into a numeric pivot at import using the
+         * resolved box, so this field exists for export fidelity rather
+         * than rendering.
+         */
+        transformBox?: 'view-box' | 'fill-box' | 'stroke-box' | 'content-box' | 'border-box';
         /** Marker id applied as `marker-start` (rendered `url(#id)` in SVG). */
         markerStart?: string;
         /** Marker id applied as `marker-mid`. */
@@ -1412,30 +1618,112 @@ interface SerializedShape {
          * overrides the SVG visibility attribute.
          */
         visibility?: 'visible' | 'hidden' | 'collapse';
+        /**
+         * Structural role of the shape in the exported SVG.
+         * - `'normal'` / absent — rendered inline in document order (default).
+         * - `'motionOnly'` — emitted inside `<defs>` as an `<mpath>` reference
+         *   target; not rendered.  Used for `<path>` elements imported from
+         *   `<defs>` that serve only as animateMotion paths.
+         *   @see https://svgwg.org/specs/animations/#MPathElement
+         */
+        displayMode?: 'normal' | 'motionOnly';
         fillType?: FillType;
+        /**
+         * @deprecated from v2 for linear/radial kinds — canonical storage is a
+         * `LinearGradientLibraryDef` / `RadialGradientLibraryDef` keyed by
+         * `fillLibraryId`. Still used for `PatternFill` until Phase 3 promotes
+         * patterns, and retained as a runtime shadow copy of the library def so
+         * legacy readers keep working through the transition.
+         */
         fillGradient?: LinearGradient | RadialGradient | PatternFill;
+        /**
+         * Reference into the unified library (v2+). When `fillType` is
+         * `'linear-gradient'` or `'radial-gradient'`, `fillLibraryId` points at
+         * the canonical `LinearGradientLibraryDef` / `RadialGradientLibraryDef`.
+         * For `'pattern'` this field is unused in v2 (patterns still live on
+         * `fillGradient`) and will be populated in Phase 3. For `'solid'` /
+         * `'none'` this field is ignored.
+         */
+        fillLibraryId?: string;
         strokeType?: StrokeType;
+        /** @deprecated see `fillGradient`. */
         strokeGradient?: LinearGradient | RadialGradient | PatternFill;
+        /** See `fillLibraryId`. */
+        strokeLibraryId?: string;
+        /**
+         * @deprecated from v2 — canonical storage is a `FilterLibraryDef` keyed
+         * by entries in `filterLibraryIds`. Retained as a runtime shadow copy of
+         * the library def so legacy readers and the editor's filter-manager keep
+         * working through the transition.
+         */
         filters?: ShapeFilter[];
+        /**
+         * Ordered list of library filter-def ids applied to this shape. On
+         * export each id emits `url(#id)`; the `filter` CSS property chains the
+         * list serially (CSS Filter Effects §Filter Property). Today the list
+         * always has length 0 or 1 — the editor wraps a shape's primitive chain
+         * in a single compound `FilterLibraryDef`. Future phases may split
+         * independent filter chains into multiple library entries.
+         */
+        filterLibraryIds?: string[];
+        /** @deprecated v2 — scope fields live on `FilterLibraryDef` from Phase 4 on. */
         filterColorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
+        /** @deprecated v2 — see `filterColorInterpolation`. */
         filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        /** @deprecated v2 — see `filterColorInterpolation`. */
         primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        /** @deprecated v2 — lives on `FilterLibraryDef` from Phase 4 on. */
         filterX?: string;
+        /** @deprecated v2 — see `filterX`. */
         filterY?: string;
+        /** @deprecated v2 — see `filterX`. */
         filterWidth?: string;
+        /** @deprecated v2 — see `filterX`. */
         filterHeight?: string;
         rawTransform?: string;
-        splinePoints?: SplinePoint[];
-        splineCurveType?: SplineCurveType;
-        splineClosed?: boolean;
-        splineTension?: number;
-        splineArcParams?: ArcParams$1[];
+        ancestorTransform?: number[];
+        pathPoints?: PathPoint[];
+        pathCurveType?: PathCurveType;
+        pathClosed?: boolean;
+        pathTension?: number;
+        pathArcParams?: ArcParams$1[];
+        /**
+         * SVG 2 §6 `pathLength` — author's stated total length of the path.
+         * Used to scale distance-along-a-path computations (text-on-path,
+         * `<animateMotion>`, `stroke-dasharray`) by `pathLength / actualLength`.
+         * A non-negative number; negative values are an error per spec.
+         */
+        pathLength?: number;
+        /**
+         * CSS Vector Effects — `vector-effect` property. `non-scaling-stroke`
+         * keeps stroke width constant under zoom/transforms (heavily used in
+         * CAD/diagram SVGs). Applies to any graphic element, not just paths;
+         * persists at the SerializedShape state level so all shape types can
+         * round-trip it.
+         */
+        vectorEffect?: 'none' | 'non-scaling-stroke' | 'non-scaling-size' | 'non-rotation' | 'fixed-position';
         polylinePoints?: Point[];
         polylineClosed?: boolean;
         href?: string;
         originalWidth?: number;
         originalHeight?: number;
+        /**
+         * Editor-internal flag controlling whether interactive resize keeps
+         * the image's natural aspect ratio. NOT the SVG `preserveAspectRatio`
+         * attribute — this is purely a UX behavior switch on the resize
+         * handles. Persisted so the user's setting survives reload.
+         */
         preserveAspectRatio?: boolean;
+        /**
+         * SVG 2 §8.7 — verbatim `preserveAspectRatio` attribute value
+         * (e.g. `'xMidYMid slice'`, `'defer xMidYMid meet'`, `'none'`). When
+         * unset, the spec default applies. The editor canvas always renders
+         * `<image>` with `preserveAspectRatio="none"` so the visible box
+         * matches the resize handles; this field carries the author's
+         * intent through round-trip and is restored on export by
+         * `SvgExportFinalizer`.
+         */
+        specPreserveAspectRatio?: string;
         imageOpacity?: number;
         mediaKind?: 'audio' | 'video';
         mediaMimeType?: string;
@@ -1471,12 +1759,36 @@ interface SerializedShape {
          * soundtracks / captioned video versions.
          */
         systemLanguage?: string;
+        /**
+         * Space-separated list of required IRI references that the user agent
+         * must support for this shape to be rendered. SVG 2 §15.4 conditional
+         * processing — typically `http://www.w3.org/TR/SVG11/feature#…` strings.
+         * Persisted alongside `systemLanguage` so `<switch>` content round-trips.
+         */
+        requiredExtensions?: string;
         shapeInsideRef?: string;
         shapePadding?: number;
         isTextPath?: boolean;
-        textPathPoints?: SplinePoint[];
+        textPathPoints?: PathPoint[];
+        /**
+         * Curve type used to interpolate `textPathPoints` into a renderable
+         * path. Mirrors `pathCurveType` for plain path shapes; persisted
+         * separately so author-set text-path curves don't have to share the
+         * shape's geometry curve type.
+         */
+        textPathCurveType?: PathCurveType;
         textPathStartOffset?: number;
+        textPathStartOffsetUnit?: '%' | 'user';
         textPathSide?: 'left' | 'right';
+        textPathMethod?: 'align' | 'stretch';
+        textPathSpacing?: 'auto' | 'exact';
+        textPathLengthAdjust?: 'spacing' | 'spacingAndGlyphs';
+        textPathLength?: number;
+        textPathLengthUnit?: '%' | 'user';
+        textPathInlineFormat?: 'defs-path' | 'path-attr';
+        textPathRefShapeId?: string;
+        /** Transient: import-time href target id, resolved away by ImportExportManager. */
+        textPathImportRefId?: string;
         fillRule?: 'nonzero' | 'evenodd';
         strokeLinejoin?: 'miter' | 'round' | 'bevel';
         strokeLinecap?: 'butt' | 'round' | 'square';
@@ -1503,6 +1815,48 @@ interface SerializedShape {
          * variant (`def.shapes`). Only meaningful on `symbol-instance` shapes.
          */
         variantKey?: string;
+        /**
+         * Per-instance presentation cascade (SVG 2 §5.5.4): attributes set on
+         * the source `<use>` element that are inherited into the symbol shadow
+         * tree on render and re-emitted on export. Keyed by the SVG attribute
+         * name in its canonical kebab-case form (`fill`, `stroke-width`,
+         * `color-interpolation-filters`, `paint-order`, etc.). Values are the
+         * verbatim attribute string — numeric parsing happens at the edit /
+         * render boundary, not at storage time.
+         *
+         * The map is the single source of truth: importing a `<use>` stores
+         * every presentation-class attribute the author wrote, applying it
+         * mirrors every entry onto the wrapper `<g>`, and exporting emits
+         * every entry back onto the `<use>`. No whitelist — any attribute the
+         * SVG cascade honors round-trips.
+         *
+         * Special case: `transform` is composed with the editor's geometry
+         * (position / rotation / skew / scale) rather than applied raw to the
+         * wrapper. See `SymbolInstance.buildTransformString`.
+         *
+         * Legacy (pre-refactor) documents may carry camelCase keys
+         * (`fillOpacity`, `strokeWidth`, …). `SymbolInstance.createFromSerialized`
+         * normalises them to kebab-case on load; no runtime readers of this
+         * field should assume either form.
+         *
+         * Only meaningful on `symbol-instance` shapes.
+         */
+        instancePresentation?: Record<string, 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
+         * exports to `<use href="#targetShapeId">` per SVG 2 §5.5. Only
+         * meaningful on shapes of type `shape-reference`.
+         */
+        targetShapeId?: string;
+        /**
+         * For `shape-reference` shapes: x/y offset from the source's reference
+         * point. Maps to the `x`/`y` on the exported `<use>` per SVG 2 §5.5.2
+         * (an additional translate applied to the use element), so the instance
+         * tracks the source's position natively.
+         */
+        offsetX?: number;
+        offsetY?: number;
         /**
          * Map of geometry-property name → CSS custom-property name (without
          * the leading `--`) the property is bound to.
@@ -1552,6 +1906,44 @@ interface SerializedShape {
         topWidthPercent?: number;
         /** Document shape: wave amplitude as a % of height. */
         waveAmplitudePercent?: number;
+        /** View shape: viewBox X component (animatable axis of the 4-tuple). */
+        viewBoxX?: number;
+        /** View shape: viewBox Y component (animatable axis of the 4-tuple). */
+        viewBoxY?: number;
+        /** View shape: viewBox width component (animatable axis of the 4-tuple). */
+        viewBoxWidth?: number;
+        /** View shape: viewBox height component (animatable axis of the 4-tuple). */
+        viewBoxHeight?: number;
+        /** View shape: name used as `<view id="...">` and fragment URL target. */
+        viewName?: string;
+        /** View shape: optional preserveAspectRatio (SVG 2 §7.8 — animatable). */
+        viewPreserveAspectRatio?: string;
+        /** View shape: SVG 1.1 §16.5 zoomAndPan. */
+        viewZoomAndPan?: 'disable' | 'magnify';
+        /** View shape: deprecated SVG 1.1 viewTarget — preserved verbatim. */
+        viewTarget?: string;
+        /** View shape: when true, this View's viewBox becomes the root SVG viewBox. */
+        isHomeView?: boolean;
+        /** SvgShape: viewBox X component (animatable). */
+        svgViewBoxX?: number;
+        /** SvgShape: viewBox Y component (animatable). */
+        svgViewBoxY?: number;
+        /** SvgShape: viewBox width component (animatable). */
+        svgViewBoxWidth?: number;
+        /** SvgShape: viewBox height component (animatable). */
+        svgViewBoxHeight?: number;
+        /** SvgShape: preserveAspectRatio (SVG 2 §7.8 — animatable, discrete). */
+        svgPreserveAspectRatio?: string;
+        /** SvgShape: outermost = intrinsic doc size, embedded = viewport rect width. */
+        svgWidth?: number;
+        /** SvgShape: outermost = intrinsic doc size, embedded = viewport rect height. */
+        svgHeight?: number;
+        /** SvgShape: x position (no effect on outermost per §5.1.4 ¶3, embedded only). */
+        svgX?: number;
+        /** SvgShape: y position (no effect on outermost per §5.1.4 ¶3, embedded only). */
+        svgY?: number;
+        /** SvgShape: marks the singleton root <svg> shape (one per document). */
+        isRootSvg?: boolean;
     };
 }
 type SerializedViewbox = Viewbox;
@@ -1576,7 +1968,7 @@ type SerializedViewbox = Viewbox;
  *      (version - 1) snapshots into the new format.
  *   c. Register it in the migrateSnapshot() chain.
  */
-declare const CURRENT_SCHEMA_VERSION = 1;
+declare const CURRENT_SCHEMA_VERSION = 2;
 interface HistorySnapshot {
     /**
      * Schema version — written on save, read on load to trigger migrations.
@@ -1606,15 +1998,30 @@ interface HistorySnapshot {
     templateVariables?: TemplateVariable[];
     /** Animation timeline (tracks, keyframes, easing). */
     animationTimeline?: SerializedAnimationTimeline;
-    /** User-defined custom patterns stored in the document. */
-    customPatterns?: CustomPatternDef[];
-    /** Symbol definitions (reusable component templates). */
-    symbols?: SerializedSymbolDef[];
     /**
-     * Marker definitions (reusable vertex-attached graphics: arrowheads, dots,
-     * etc.). Built-in markers are reconstituted at load time by MarkerManager
-     * and are NOT persisted here — only user-authored defs are stored.
+     * Unified library of reusable `<defs>` content. Authoritative from v2 onward
+     * for symbols and markers (and, as later phases land, gradients, patterns,
+     * and filters too). Built-in markers are reconstituted at load time by
+     * MarkerManager and are NOT persisted here — only user-authored defs are.
+     */
+    library?: LibraryDef[];
+    /**
+     * Raw XML fragments for `<mask>` / `<clipPath>` defs that live in editor
+     * defs but have no typed entry in `library`. Populated by paste pipelines
+     * that clone source paint-server defs verbatim (preserving original ids so
+     * `url(#id)` refs resolve). Without this field, the save/reload cycle
+     * drops the masks entirely because `library` has no kind for them; shapes
+     * that reference those ids render without their mask.
+     *
+     * Each entry is a serialised fragment (`<mask id="…">…</mask>`) ready to
+     * `innerHTML`-append into editor defs on restore.
      */
+    rawPaintServerDefs?: string[];
+    /** @deprecated v2 — use `library`. Read-only: v1 docs migrate into `library`. */
+    customPatterns?: CustomPatternDef[];
+    /** @deprecated v2 — use `library`. Read-only: v1 docs migrate into `library`. */
+    symbols?: SerializedSymbolDef[];
+    /** @deprecated v2 — use `library`. Read-only: v1 docs migrate into `library`. */
     markers?: SerializedMarkerDef[];
 }
 /**
@@ -1627,213 +2034,581 @@ interface SerializedVariantAxis {
     name: string;
     values: string[];
 }
-/**
- * A reusable symbol definition. Contains the shapes that make up the
- * symbol template, plus metadata for the symbols panel.
- *
- * **Variants:** when `variantAxes` is present, the symbol carries
- * multiple alternative shape arrays keyed by variant combination
- * (e.g. `state=hover,size=md`). The base `shapes` field is always
- * the **default variant** — the combination where every axis is at
- * its first value. Other variants live in `variants[variantKey]`.
- * Variant resolution falls back to `shapes` whenever `variantKey`
- * is missing or empty.
- */
-interface SerializedSymbolDef {
-    /** Unique identifier for this symbol definition. */
-    id: string;
-    /** Human-readable name shown in the symbols panel. */
-    name: string;
-    /** SVG viewBox string ("minX minY width height"). */
-    viewBox: string;
-    /**
-     * Default variant shapes. When `variantAxes` is present, this represents
-     * the variant where every axis is at its first value.
-     */
-    shapes: SerializedShape[];
-    /** Groups within the symbol. */
-    groups?: SerializedGroup[];
-    /** Base64 data-URI thumbnail for the symbols panel. */
-    thumbnail?: string;
-    /**
-     * Ordered list of variant axes available on this symbol. The order is
-     * stable so that variant keys can be canonicalized as
-     * `axis1=val1,axis2=val2`.
-     */
-    variantAxes?: SerializedVariantAxis[];
-    /**
-     * Non-default variant shape arrays keyed by canonical axis combination
-     * string (e.g. `state=hover,size=md`). Missing keys fall back to the
-     * base `shapes` array.
-     */
-    variants?: Record<string, SerializedShape[]>;
-    /**
-     * Per-variant thumbnails as base64 data URIs, keyed by canonical
-     * variant combination string. The empty string `""` keys the default
-     * variant (which also lives in `thumbnail` for backwards compatibility).
-     * Used by the variant matrix view to show real previews of each cell.
-     */
-    variantThumbnails?: Record<string, string>;
+/**
+ * A reusable symbol definition. Contains the shapes that make up the
+ * symbol template, plus metadata for the symbols panel.
+ *
+ * **Variants:** when `variantAxes` is present, the symbol carries
+ * multiple alternative shape arrays keyed by variant combination
+ * (e.g. `state=hover,size=md`). The base `shapes` field is always
+ * the **default variant** — the combination where every axis is at
+ * its first value. Other variants live in `variants[variantKey]`.
+ * Variant resolution falls back to `shapes` whenever `variantKey`
+ * is missing or empty.
+ */
+type SerializedSymbolDef = SymbolLibraryDef;
+/**
+ * A reusable `<marker>` definition (SVG 2 §11.6). Markers are vertex-attached
+ * graphics — arrowheads, vertex dots, decorations — referenced via
+ * `marker-start` / `marker-mid` / `marker-end` attributes on stroked shapes.
+ *
+ * The browser handles per-vertex positioning, scaling (via `markerUnits`),
+ * and orientation (via `orient`, including tangent-aware `auto` mode on
+ * curved paths). MarkerManager only maintains the DOM `<defs>` entries in
+ * sync with this serialized state.
+ *
+ * Simpler than `SerializedSymbolDef` — markers have no variants, no instance
+ * overrides, and no placed instances (they attach via attribute references).
+ */
+type SerializedMarkerDef = MarkerLibraryDef;
+interface SerializedGroup {
+    id: string;
+    parentId: string | null;
+    /** CSS transform-origin value (e.g. "50px 50px") for group animations */
+    transformOrigin?: string;
+    /**
+     * SVG `<g>` transform attribute (e.g. "matrix(...)" or "scale(2,1)").
+     * Preserved verbatim from import so the group carries its ancestor/own
+     * transform through serialization (clipboard, undo/redo, collab).
+     * Shapes inside stay in the group's local frame — the browser composes
+     * `groupTransform × child` natively at render.
+     */
+    transform?: string;
+    /**
+     * Zero-based position of this group among its parent container's
+     * children (including both sibling groups and sibling shape nodes).
+     * Used during restoration to correctly interleave groups and shapes
+     * so that SVG document order (painting order) is preserved.
+     */
+    siblingIndex?: number;
+    /** Plugin that owns this group (e.g. 'svgsketch-charts') */
+    pluginId?: string;
+    /** Serialized plugin-specific state (JSON string) */
+    pluginData?: string;
+    /** Additional custom data-* attributes set by plugins */
+    attributes?: Record<string, string>;
+    fill?: string;
+    fillOpacity?: string;
+    strokeOpacity?: string;
+    opacity?: string;
+    filter?: string;
+    cssFilter?: string;
+    mixBlendMode?: string;
+    clipPath?: string;
+    mask?: string;
+    /**
+     * Lossless carrier for any `<metadata>` elements that appeared as
+     * children of this group's source `<g>` element. Same semantics as
+     * `ShapeMetadata.rawMetadata` / `DocumentMetadata.rawMetadata` — see
+     * SVG 2 §5.8 (`<metadata>` can appear on any container).
+     */
+    rawMetadata?: string;
+}
+/** Serialized clip or mask group */
+interface SerializedClipMaskGroup {
+    id: string;
+    type: 'clip' | 'mask';
+    /**
+     * @deprecated Use `clipShapeIds` instead. Kept for backward compatibility
+     * when reading older documents that used a single clip/mask shape.
+     */
+    clipShapeId?: string;
+    /** IDs of shape(s) that form the clip/mask definition. */
+    clipShapeIds: string[];
+    /** IDs of the content shapes being clipped/masked. */
+    contentShapeIds: string[];
+    parentId: string | null;
+    /**
+     * Position of the clip/mask group among its parent container's children,
+     * so that SVG document order (painting order) is preserved across
+     * save / restore.
+     */
+    siblingIndex?: number;
+    /**
+     * Coordinate system for the `<mask>` bounds (`x`, `y`, `width`, `height`).
+     * @see CSS Masking Module §9.1 — `maskUnits`
+     * @default 'objectBoundingBox'
+     */
+    maskUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    /**
+     * Coordinate system for the **contents** of a `<mask>`.
+     * @see CSS Masking Module §9.1 — `maskContentUnits`
+     * @default 'userSpaceOnUse'
+     */
+    maskContentUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    /**
+     * Coordinate system for the contents of a `<clipPath>`.
+     * @see CSS Masking Module §6.1 — `clipPathUnits`
+     * @default 'userSpaceOnUse'
+     */
+    clipPathUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    /**
+     * Explicit mask bounds (`x`, `y`, `width`, `height`).
+     * When omitted the browser defaults apply (−10% / 120%).
+     */
+    maskBounds?: {
+        x: string;
+        y: string;
+        width: string;
+        height: string;
+    };
+    /**
+     * Whether the mask uses luminance or alpha channel.
+     * @see CSS Masking Module §9.2 — `mask-type`
+     * @default 'luminance'
+     */
+    maskType?: 'luminance' | 'alpha';
+    /**
+     * Raw SVG markup for imported mask/clip definitions that cannot be
+     * decomposed into editor `Shape` objects (e.g. multi-element masks
+     * with gradients, patterns, or nested groups). When present the
+     * editor preserves the original `<mask>` / `<clipPath>` verbatim
+     * and `clipShapeIds` may be empty.
+     */
+    rawDefinition?: string;
+}
+
+/**
+ * @svgsketch/core — Library (defs) types.
+ *
+ * A `LibraryDef` is any reusable element that lives in an SVG `<defs>` and is
+ * referenced from shapes via `url(#id)`. The library is the authoritative store
+ * for these definitions; shapes carry only ID references.
+ *
+ * Kinds covered here:
+ *   - symbol  (SVG 2 §5.5, referenced by `<use href="#id">`)
+ *   - marker  (SVG 2 §13.7, referenced by `marker-start/-mid/-end`)
+ *   - linear-gradient / radial-gradient (SVG 2 §14, referenced by fill/stroke)
+ *   - pattern (SVG 2 §14.3, referenced by fill/stroke)
+ *   - filter  (CSS Filter Effects §Filter Property, referenced by `filter`)
+ *
+ * ClipPath, mask, and <style> are deliberately out of scope for this pass.
+ */
+
+/** Discriminator for the `LibraryDef` union. */
+type LibraryKind = 'symbol' | 'marker' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'filter';
+/**
+ * Common fields shared by every kind of library def. ID prefix convention:
+ *   sym- / mkr- / grd- / pat- / flt-
+ */
+interface LibraryDefBase {
+    /** Unique identifier, prefixed by kind (see convention above). */
+    id: string;
+    /** Kind discriminator — required on every def. */
+    kind: LibraryKind;
+    /** Human-readable name shown in the library panel. */
+    name: string;
+    /** Base64 data-URI thumbnail, rendered by the kind's thumbnail generator. */
+    thumbnail?: string;
+    /**
+     * Editor-shipped seed that isn't deletable, renamable, or user-editable
+     * (today: built-in markers). Only set when the kind actually has built-ins.
+     */
+    builtIn?: boolean;
+    /**
+     * Original id from the imported source SVG. Runtime `id` is always a fresh
+     * GUID; `sourceId` lets export restore human-friendly ids when uncontested.
+     */
+    sourceId?: string;
+}
+/**
+ * Reusable component template. Shapes inside are edited via symbol isolation
+ * mode and placed onto the canvas as `SymbolInstance` shapes (which emit as
+ * `<use href="#id">` on export — SVG 2 §5.5).
+ */
+interface SymbolLibraryDef extends LibraryDefBase {
+    kind: 'symbol';
+    /**
+     * Source SVG element form for round-trip fidelity. Most symbols are
+     * authored as `<symbol>` (SVG 2 §5.5.1); `<defs><g id="X"/>` referenced
+     * by `<use href="#X"/>` is a legally distinct pattern that the editor
+     * also models as a SymbolLibraryDef but must export as `<g>` to remain
+     * spec-faithful — `<symbol>` would silently introduce viewport-
+     * establishment (SVG 2 §5.5.2) and `overflow: hidden` defaulting that
+     * the source `<g>` does not have. Default `'symbol'` for backward
+     * compatibility with documents authored before this field existed.
+     */
+    defKind?: 'symbol' | 'group';
+    viewBox: string;
+    /**
+     * Wrapper attributes from the source `<g id="X">` def root that apply to
+     * the def's contents (transform, opacity, fill cascade, mask, filter,
+     * clip-path). Re-emitted on the exported `<g id="X">` when `defKind === 'group'`
+     * — `<symbol>` doesn't legally accept these attributes per SVG 2 §5.5.1.
+     * Without this, `<use href="#X"/>` would silently render the children at
+     * their unwrapped local coords / paint, losing every non-id attribute on
+     * the source `<g>` def root.
+     */
+    wrapperAttrs?: Record<string, string>;
+    /**
+     * Default variant shapes. When `variantAxes` is present this represents the
+     * variant where every axis is at its first value.
+     */
+    shapes: SerializedShape[];
+    groups?: SerializedGroup[];
+    /**
+     * Ordered list of variant axes. The order is stable so variant keys can be
+     * canonicalized as `axis1=val1,axis2=val2`.
+     */
+    variantAxes?: SerializedVariantAxis[];
+    /** Non-default variant shape arrays keyed by canonical axis combination. */
+    variants?: Record<string, SerializedShape[]>;
+    /** Per-variant thumbnails keyed by canonical variant string. */
+    variantThumbnails?: Record<string, string>;
+}
+/**
+ * Vertex-attached graphic (arrowheads, dots, decorations). Referenced via
+ * `marker-start` / `marker-mid` / `marker-end` on stroked shapes — SVG 2
+ * §13.7.2 specifies each attribute accepts a single `<marker-ref>`.
+ */
+interface MarkerLibraryDef extends LibraryDefBase {
+    kind: 'marker';
+    viewBox: string;
+    /** X reference point — where the marker's tip aligns with the host vertex. */
+    refX: number;
+    refY: number;
+    markerWidth: number;
+    markerHeight: number;
+    /**
+     * `strokeWidth` scales with the host's stroke; `userSpaceOnUse` renders at
+     * fixed size regardless of stroke.
+     */
+    markerUnits: 'strokeWidth' | 'userSpaceOnUse';
+    /**
+     * `auto` rotates to match path tangent; `auto-start-reverse` reverses the
+     * start marker; a number is a fixed rotation in degrees.
+     */
+    orient: 'auto' | 'auto-start-reverse' | number;
+    /**
+     * Inner geometry (authoritative for user markers). Built-ins render from
+     * the descriptor registry and carry `shapes: []`.
+     */
+    shapes: SerializedShape[];
+    groups?: SerializedGroup[];
+    /**
+     * Animation tracks scoped to the marker's inner shapes. Emitted as SMIL
+     * `<animate>` children of the exported `<marker>`.
+     */
+    animations?: SerializedAnimationTimeline['tracks'];
+}
+/**
+ * Linear gradient def (SVG 2 §14.6). Referenced via `fill="url(#id)"` or
+ * `stroke="url(#id)"`. Inner geometry is the existing `LinearGradient` shape,
+ * minus the fields that live on `LibraryDefBase` (`id`, `sourceId`).
+ */
+interface LinearGradientLibraryDef extends LibraryDefBase {
+    kind: 'linear-gradient';
+    gradient: Omit<LinearGradient, 'id' | 'sourceId'>;
+}
+/** Radial gradient def (SVG 2 §14.7). See `LinearGradientLibraryDef`. */
+interface RadialGradientLibraryDef extends LibraryDefBase {
+    kind: 'radial-gradient';
+    gradient: Omit<RadialGradient, 'id' | 'sourceId'>;
+}
+/**
+ * Pattern def (SVG 2 §14.3). Subsumes today's `CustomPatternDef` (user-created
+ * reusable tiles) and the per-shape `PatternFill` — both collapse into one
+ * persisted representation keyed by `LibraryDefBase.id`.
+ *
+ * `customPatternId` is stripped because once the pattern IS the library entry,
+ * the back-reference is redundant.
+ */
+interface PatternLibraryDef extends LibraryDefBase {
+    kind: 'pattern';
+    pattern: Omit<PatternFill, 'id' | 'sourceId' | 'customPatternId'>;
+}
+/**
+ * Filter def (CSS Filter Effects). Referenced via `filter="url(#id)"`. When a
+ * shape chains multiple filters, the CSS `filter` property accepts a
+ * space-separated list (`<filter-value-list>`) and composes them serially —
+ * each url()'s input is the previous url()'s output.
+ *
+ * Filter region and unit attributes live on `<filter>` itself (per the spec),
+ * so they move here from the per-shape state.
+ */
+interface FilterLibraryDef extends LibraryDefBase {
+    kind: 'filter';
+    /** Ordered primitive chain (same editable model used per-shape today). */
+    filters: ShapeFilter[];
+    colorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
+    filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+}
+/** Discriminated union over `kind`. */
+type LibraryDef = SymbolLibraryDef | MarkerLibraryDef | LinearGradientLibraryDef | RadialGradientLibraryDef | PatternLibraryDef | FilterLibraryDef;
+/**
+ * Narrow helper — picks the library-def type for a given kind. Useful for
+ * `getByKind('symbol')` return types.
+ */
+type LibraryDefOfKind<K extends LibraryKind> = Extract<LibraryDef, {
+    kind: K;
+}>;
+
+/**
+ * Typed property interfaces for every node type in the scene graph.
+ *
+ * This is the **single source of truth** for shape property types across
+ * the entire SVGSketch stack (editor, API worker, server renderer, etc.).
+ *
+ * Each shape type declares the exact set of properties it owns.
+ * These interfaces drive:
+ * - Compile-time type safety on `SceneNode.get()` / `.set()` calls
+ * - The `NodeTypePropsMap` lookup used by `SceneNode.create()`
+ * - Schema defaults and validators in the editor's `node-schema.ts`
+ * - Serialization format for the `.svgs` document format
+ */
+
+interface CommonNodeProps {
+    fillColor: string;
+    borderColor: string;
+    borderWidth: number;
+    opacity: number;
+    fillOpacity: number;
+    strokeOpacity: number;
+    rotation: number;
+    skewX: number;
+    skewY: number;
+    customPivot: Point | null;
+    locked: boolean;
+    visible: boolean;
+    fillType: string;
+    fillGradient: unknown | null;
+    strokeType: string;
+    strokeGradient: unknown | null;
+    fillRule: 'nonzero' | 'evenodd';
+    strokeLinejoin: 'miter' | 'round' | 'bevel';
+    strokeLinecap: 'butt' | 'round' | 'square';
+    strokeMiterlimit: number;
+    lineStyle: string;
+    dashLength: number;
+    gapLength: number;
+    dashOffset: number;
+    strokeDasharray: string | null;
+    filters: unknown[];
+    filterColorInterpolation: 'auto' | 'sRGB' | 'linearRGB' | null;
+    filterUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
+    primitiveUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
+    filterX: string | null;
+    filterY: string | null;
+    filterWidth: string | null;
+    filterHeight: string | null;
+    rawTransform: string | null;
+    ancestorTransform: number[] | null;
+    metadata: unknown | null;
+    cssClipPath: string | null;
+    cssMaskProperties: Record<string, string> | null;
+    groupId: string | null;
+}
+type CornerShapeValue = 'round' | 'notch' | 'bevel' | 'scoop';
+interface RectangleNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    cornerRadius: number;
+    cornerShape: CornerShapeValue;
+    cornerMode: 'uniform' | 'non-uniform';
+    cornerRadiusTL: number;
+    cornerRadiusTR: number;
+    cornerRadiusBL: number;
+    cornerRadiusBR: number;
+    cornerShapeTL: CornerShapeValue;
+    cornerShapeTR: CornerShapeValue;
+    cornerShapeBL: CornerShapeValue;
+    cornerShapeBR: CornerShapeValue;
+}
+type SquareNodeProps = RectangleNodeProps;
+interface CircleNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    radius: number;
+}
+interface EllipseNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    rx: number;
+    ry: number;
+}
+type LineEndpointValue = 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
+interface LineNodeProps extends CommonNodeProps {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    startEndpoint: LineEndpointValue;
+    endEndpoint: LineEndpointValue;
+}
+interface TextNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    textX: number;
+    textY: number;
+    fontSize: number;
+    text: string;
+    fontFamily: string;
+    fontWeight: string;
+    fontStyle: string;
+    textDecoration: Record<string, boolean>;
+    textTransform: string;
+    baselineShift: string;
+    dominantBaseline: string;
+    writingMode: string;
+    textAnchor: string;
+    letterSpacing: number;
+    wordSpacing: number;
+    lineHeight: number;
+    inlineSize: number;
+    overflowWrap: string;
+    whiteSpace: string;
+    textDirection: string;
+    unicodeBidi: string;
+    scaleX: number;
+    scaleY: number;
+    scaleAnchor: Point | null;
+    useRichText: boolean;
+    richTextData: unknown | null;
+    /**
+     * Per-glyph positioning data — see `SerializedShape['state'].charOffsets`
+     * in `serialized.ts` for full semantics.  Legacy `{x, y, rotate}` form
+     * accepted on read for back-compat with pre-spec-aligned saves.
+     */
+    charOffsets: ({
+        x: number | null;
+        y: number | null;
+        dx: number;
+        dy: number;
+        rotate: number;
+    } | {
+        x: number;
+        y: number;
+        rotate: number;
+    })[] | null;
+    fontVariationSettings: Record<string, number>;
+    isTextPath: boolean;
+    textPathPoints: unknown[] | null;
+    textPathStartOffset: number;
+    textPathSide: 'left' | 'right';
+    shapeInsideRef: string | null;
+    shapePadding: number;
+}
+interface ImageNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    href: string;
+    originalWidth: number;
+    originalHeight: number;
+    preserveAspectRatio: boolean;
+    imageOpacity: number;
+}
+interface PathNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    pathPoints: unknown[];
+    pathArcParams: unknown[];
+    pathControlBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    startEndpoint: LineEndpointValue;
+    endEndpoint: LineEndpointValue;
+}
+interface PolylineNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    polylinePoints: Point[];
+    polylineClosed: boolean;
+}
+interface PolygonBaseNodeProps extends CommonNodeProps {
+    cx: number;
+    cy: number;
+    radius: number;
+    cornerRadius: number;
+    shiftAngle: number;
+}
+interface TriangleNodeProps extends PolygonBaseNodeProps {
+    sides: 3;
+}
+interface NGonNodeProps extends PolygonBaseNodeProps {
+    sides: number;
+}
+interface StarNodeProps extends PolygonBaseNodeProps {
+    arms: number;
+    innerRadiusPercent: number;
+}
+interface CrossNodeProps extends PolygonBaseNodeProps {
+    armWidthPercent: number;
+}
+interface RingNodeProps extends PolygonBaseNodeProps {
+    innerRadiusPercent: number;
+}
+interface SpiralNodeProps extends PolygonBaseNodeProps {
+    turns: number;
+    thicknessPercent: number;
+    spiralDirection: number;
+}
+interface GearNodeProps extends PolygonBaseNodeProps {
+    teeth: number;
+    toothDepthPercent: number;
+    holeRadiusPercent: number;
+}
+interface ArrowNodeProps extends PolygonBaseNodeProps {
+    headWidthPercent: number;
+    headLengthPercent: number;
+    shaftWidthPercent: number;
 }
-/**
- * A reusable `<marker>` definition (SVG 2 §11.6). Markers are vertex-attached
- * graphics — arrowheads, vertex dots, decorations — referenced via
- * `marker-start` / `marker-mid` / `marker-end` attributes on stroked shapes.
- *
- * The browser handles per-vertex positioning, scaling (via `markerUnits`),
- * and orientation (via `orient`, including tangent-aware `auto` mode on
- * curved paths). MarkerManager only maintains the DOM `<defs>` entries in
- * sync with this serialized state.
- *
- * Simpler than `SerializedSymbolDef` — markers have no variants, no instance
- * overrides, and no placed instances (they attach via attribute references).
- */
-interface SerializedMarkerDef {
-    /**
-     * Unique identifier.
-     * - Built-in markers use stable ids: `mkr-builtin-arrow`, `mkr-builtin-open-arrow`,
-     *   `mkr-builtin-circle`, `mkr-builtin-diamond`, `mkr-builtin-square`.
-     * - User-created markers use `mkr-<guid>`.
-     */
-    id: string;
-    /** Human-readable name shown in the markers panel. */
-    name: string;
-    /** SVG viewBox string ("minX minY width height"). */
-    viewBox: string;
-    /** X reference point — where the marker's "tip" aligns with the host vertex. */
-    refX: number;
-    refY: number;
-    markerWidth: number;
-    markerHeight: number;
-    /**
-     * `strokeWidth` scales the marker with the host's stroke-width (default,
-     * typical for arrows). `userSpaceOnUse` renders at fixed size regardless
-     * of stroke.
-     */
-    markerUnits: 'strokeWidth' | 'userSpaceOnUse';
-    /**
-     * `auto` rotates to match the path tangent at each vertex.
-     * `auto-start-reverse` reverses the start marker (so arrowheads don't
-     * point inward at path starts). A number is a fixed rotation in degrees.
-     */
-    orient: 'auto' | 'auto-start-reverse' | number;
-    /**
-     * Inner geometry. For user markers this is the authoritative source —
-     * edited via isolation mode and re-rendered into the DOM `<marker>` child.
-     * For built-ins this is `[]` in v1; built-ins render from the descriptor
-     * registry (`getMarkerDescriptors()`) and are not editable.
-     */
-    shapes: SerializedShape[];
-    /** Groups within the marker (mirrors `SerializedSymbolDef.groups`). */
-    groups?: SerializedGroup[];
-    /** Base64 data-URI thumbnail for the markers panel. */
-    thumbnail?: string;
-    /**
-     * Animation tracks scoped to the marker's inner shapes. Each track's
-     * `shapeId` references an id in `shapes`. During isolation editing these
-     * tracks are merged into the document timeline (tagged `scope:
-     * 'marker:<id>'`) so the user can edit them; on save they're extracted
-     * back here. On SVG export the tracks render as SMIL `<animate>` elements
-     * inside the `<marker>` DOM so they play at every attached vertex.
-     */
-    animations?: SerializedAnimationTimeline['tracks'];
-    /**
-     * True for editor-shipped built-ins (arrow, open-arrow, circle, diamond,
-     * square). Built-ins are non-deletable, non-renamable, and non-editable.
-     */
-    builtIn?: boolean;
+interface SymbolInstanceNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    symbolId: string;
 }
-interface SerializedGroup {
-    id: string;
-    parentId: string | null;
-    /** CSS transform-origin value (e.g. "50px 50px") for group animations */
-    transformOrigin?: string;
-    /**
-     * Zero-based position of this group among its parent container's
-     * children (including both sibling groups and sibling shape nodes).
-     * Used during restoration to correctly interleave groups and shapes
-     * so that SVG document order (painting order) is preserved.
-     */
-    siblingIndex?: number;
-    /** Plugin that owns this group (e.g. 'svgsketch-charts') */
-    pluginId?: string;
-    /** Serialized plugin-specific state (JSON string) */
-    pluginData?: string;
-    /** Additional custom data-* attributes set by plugins */
-    attributes?: Record<string, string>;
-    fill?: string;
-    fillOpacity?: string;
-    strokeOpacity?: string;
-    opacity?: string;
-    filter?: string;
-    cssFilter?: string;
-    mixBlendMode?: string;
-    clipPath?: string;
-    mask?: string;
+interface GroupNodeProps {
+    groupId: string | null;
 }
-/** Serialized clip or mask group */
-interface SerializedClipMaskGroup {
-    id: string;
-    type: 'clip' | 'mask';
-    /**
-     * @deprecated Use `clipShapeIds` instead. Kept for backward compatibility
-     * when reading older documents that used a single clip/mask shape.
-     */
-    clipShapeId?: string;
-    /** IDs of shape(s) that form the clip/mask definition. */
-    clipShapeIds: string[];
-    /** IDs of the content shapes being clipped/masked. */
-    contentShapeIds: string[];
-    parentId: string | null;
-    /**
-     * Position of the clip/mask group among its parent container's children,
-     * so that SVG document order (painting order) is preserved across
-     * save / restore.
-     */
-    siblingIndex?: number;
-    /**
-     * Coordinate system for the `<mask>` bounds (`x`, `y`, `width`, `height`).
-     * @see CSS Masking Module §9.1 — `maskUnits`
-     * @default 'objectBoundingBox'
-     */
-    maskUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
-    /**
-     * Coordinate system for the **contents** of a `<mask>`.
-     * @see CSS Masking Module §9.1 — `maskContentUnits`
-     * @default 'userSpaceOnUse'
-     */
-    maskContentUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
-    /**
-     * Coordinate system for the contents of a `<clipPath>`.
-     * @see CSS Masking Module §6.1 — `clipPathUnits`
-     * @default 'userSpaceOnUse'
-     */
-    clipPathUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
-    /**
-     * Explicit mask bounds (`x`, `y`, `width`, `height`).
-     * When omitted the browser defaults apply (−10% / 120%).
-     */
-    maskBounds?: {
-        x: string;
-        y: string;
-        width: string;
-        height: string;
-    };
-    /**
-     * Whether the mask uses luminance or alpha channel.
-     * @see CSS Masking Module §9.2 — `mask-type`
-     * @default 'luminance'
-     */
-    maskType?: 'luminance' | 'alpha';
-    /**
-     * Raw SVG markup for imported mask/clip definitions that cannot be
-     * decomposed into editor `Shape` objects (e.g. multi-element masks
-     * with gradients, patterns, or nested groups). When present the
-     * editor preserves the original `<mask>` / `<clipPath>` verbatim
-     * and `clipShapeIds` may be empty.
-     */
-    rawDefinition?: string;
+type DocumentNodeProps = Record<string, never>;
+/**
+ * Maps each node type string to its typed property interface.
+ * Used by `SceneNode.create()` for compile-time type safety.
+ */
+interface NodeTypePropsMap {
+    rectangle: RectangleNodeProps;
+    square: SquareNodeProps;
+    circle: CircleNodeProps;
+    ellipse: EllipseNodeProps;
+    line: LineNodeProps;
+    text: TextNodeProps;
+    image: ImageNodeProps;
+    path: PathNodeProps;
+    polyline: PolylineNodeProps;
+    triangle: TriangleNodeProps;
+    ngon: NGonNodeProps;
+    star: StarNodeProps;
+    cross: CrossNodeProps;
+    ring: RingNodeProps;
+    spiral: SpiralNodeProps;
+    gear: GearNodeProps;
+    arrow: ArrowNodeProps;
+    'symbol-instance': SymbolInstanceNodeProps;
+    group: GroupNodeProps;
+    document: DocumentNodeProps;
 }
+/** Union of all node prop types. */
+type AnyNodeProps = RectangleNodeProps | SquareNodeProps | CircleNodeProps | EllipseNodeProps | LineNodeProps | TextNodeProps | ImageNodeProps | PathNodeProps | PolylineNodeProps | TriangleNodeProps | NGonNodeProps | StarNodeProps | CrossNodeProps | RingNodeProps | SpiralNodeProps | GearNodeProps | ArrowNodeProps | SymbolInstanceNodeProps | GroupNodeProps | DocumentNodeProps;
 
 /**
  * @svgsketch/core — Schema migrations.
@@ -1870,17 +2645,6 @@ interface SerializedClipMaskGroup {
  * It must return the transformed snapshot (typically the same object).
  */
 type Migration = (snapshot: HistorySnapshot) => HistorySnapshot;
-/**
- * Registry of schema migrations, keyed by **source** version.
- *
- * Entry `N: fn` means "`fn` transforms a version-N snapshot into a
- * version-(N+1) snapshot." The dispatcher in {@link migrateSnapshot}
- * walks this registry from the snapshot's current version up to
- * {@link CURRENT_SCHEMA_VERSION}.
- *
- * This object is exported so tests (and diagnostic tooling) can read
- * the registered migrations, but it should not be mutated at runtime.
- */
 declare const MIGRATIONS: Readonly<Record<number, Migration>>;
 /**
  * Migrate a snapshot from any older schema version to the current version.
@@ -2239,6 +3003,28 @@ declare function renderToSvg(snapshot: HistorySnapshot, options?: RenderOptions)
  * @packageDocumentation
  */
 
+/**
+ * Render a single `FilterPrimitive` to its SVG element string.
+ *
+ * Walks every modeled spec attribute and re-emits it. Author-preserved
+ * attributes (e.g. <number-optional-number> spellings, kernelMatrix
+ * whitespace) are stored as strings on the primitive and emitted verbatim,
+ * so import → render produces semantically equivalent output.
+ *
+ * `unknownAttrs` are emitted last (alphabetised) so re-export is stable.
+ * `animations` children are appended inside the element.
+ */
+declare function renderFilterPrimitive(p: FilterPrimitive): string;
+/**
+ * Render an `SvgPrimitiveChainFilter` as a complete `<filter>` element.
+ *
+ * Wrapper attributes are author-faithful: omitted ⇒ unset on the element ⇒
+ * UA spec defaults apply (filterUnits=objectBoundingBox, primitiveUnits=
+ * userSpaceOnUse, region -10%/-10%/120%/120%, color-interpolation-filters=
+ * linearRGB). The chain is emitted in document order with no synthetic
+ * `in`/`result` rewriting.
+ */
+declare function renderSvgPrimitiveChainFilter(filterId: string, f: SvgPrimitiveChainFilter): string;
 /**
  * Render SVG filter primitive string(s) for a single filter.
  *
@@ -2260,14 +3046,25 @@ declare function renderFilterPrimitivesForType(filter: ShapeFilter, input: strin
 /**
  * Generate `<filter>` definition strings for all shapes that have filters.
  *
+ * Phase 4: filters are library-first. Each distinct `filterLibraryIds`
+ * entry emits exactly one `<filter>` in the output — two shapes sharing
+ * the same library filter id produce one `<filter>`, not two. Falls back
+ * to the legacy `filter-${shape.id}` id when a shape has inline filters
+ * but no library ids set (shapes that haven't re-serialized since the
+ * migration, or callers working against an in-memory object).
+ *
  * @returns Concatenated `<filter>` elements to include in `<defs>`.
  */
 declare function renderFilterDefs(shapes: SerializedShape[]): string;
 /**
  * Get the `filter="url(#...)"` attribute value for a shape, or empty string
  * if the shape has no enabled filters.
+ *
+ * Phase 4: reads from `filterLibraryIds` when set, joining multiple ids as
+ * a space-separated `<filter-value-list>` (CSS Filter Effects §Filter
+ * Property). Falls back to the legacy shape-derived id for unmigrated input.
  */
-declare function filterAttr(shapeId: string, filters: ShapeFilter[] | undefined): string;
+declare function filterAttr(shapeId: string, filters: ShapeFilter[] | undefined, filterLibraryIds?: string[]): string;
 
 /**
  * Shape renderers — convert SerializedShape → SVG element string.
@@ -2287,6 +3084,31 @@ declare function renderImage(shape: SerializedShape): string;
 declare function renderPolygonShape(shape: SerializedShape): string;
 /** Render any SerializedShape to an SVG element string. */
 declare function renderShape(shape: SerializedShape): string;
+/**
+ * Walk shapes to find referenced marker ids. Returns two sets:
+ *   - `ids`: raw marker ids from `state.markerStart` / `markerMid` /
+ *     `markerEnd` — can be built-in ids (`mkr-builtin-arrow`,
+ *     `line-marker-arrow`) or user marker ids.
+ *   - `legacyEndpoints`: endpoint names from `state.startEndpoint` /
+ *     `endEndpoint` (e.g. `'arrow'`, `'circle'`). Lines emit these as a
+ *     shortcut to built-in markers without explicit `marker-*` attrs.
+ */
+interface MarkerReferenceSets {
+    ids: Set<string>;
+    legacyEndpoints: Set<string>;
+}
+/**
+ * Emit only built-in marker `<marker>` definitions referenced by a shape
+ * collection. Split out of `renderMarkerDefs` so the library-first
+ * pipeline can compose built-in handling with
+ * `renderReferencedLibraryDefs` (which covers user-authored markers via
+ * `snapshot.library`).
+ *
+ * Takes a pre-collected `MarkerReferenceSets` so callers can avoid walking
+ * shapes twice when they need both the reference sets and the built-in
+ * defs.
+ */
+declare function renderBuiltinMarkerDefs(referenced: MarkerReferenceSets | SerializedShape[]): string;
 
 /**
  * Pure geometry functions for computing shape vertices and paths.
@@ -2535,6 +3357,95 @@ declare function getBuiltInMarkerDefs(): SerializedMarkerDef[];
  */
 declare function renderAnimationElements(timeline: SerializedAnimationTimeline): Map<string, string[]>;
 
+/**
+ * Library renderers — convert `LibraryDef` entries into SVG `<defs>` strings.
+ *
+ * This is the headless/string-based renderer for library defs. The editor's
+ * live `<defs>` rendering is handled by the kind-specific managers
+ * (SymbolManager, MarkerManager, GradientManager, FilterManager) writing D3
+ * DOM nodes; this module is the equivalent path for the CLI/SDK export pipe.
+ *
+ * Implementations delegate to the existing per-shape renderers where
+ * possible — library defs carry the same render-affecting data as the
+ * inline payloads those renderers were built for, with `LibraryDefBase`
+ * metadata (id, name, thumbnail) peeled off at the outer call.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Deterministic emission order for `<defs>` contents. Put paint servers
+ * (gradients, patterns) and filters **before** symbols/markers so that when a
+ * symbol or marker's inner shapes reference a library paint or filter by
+ * `url(#id)`, the forward reference resolves in parsers that do a single
+ * forward pass.
+ *
+ * This matches the plan's export ordering rule: symbols and markers can
+ * reference any other library kind, but not vice versa.
+ */
+declare const LIBRARY_EMIT_ORDER: readonly LibraryKind[];
+/** Top-level dispatch. Picks the right kind-renderer for a library def. */
+declare function renderLibraryDef(def: LibraryDef): string;
+declare function renderSymbolLibraryDef(def: SymbolLibraryDef): string;
+declare function renderMarkerLibraryDef(def: MarkerLibraryDef): string;
+declare function renderLinearGradientLibraryDef(def: LinearGradientLibraryDef): string;
+declare function renderRadialGradientLibraryDef(def: RadialGradientLibraryDef): string;
+declare function renderPatternLibraryDef(def: PatternLibraryDef): string;
+declare function renderFilterLibraryDef(def: FilterLibraryDef): string;
+/**
+ * Render every library def as a single `<defs>`-body string, in the
+ * canonical order defined by `LIBRARY_EMIT_ORDER`. Useful for callers that
+ * want to emit the entire library regardless of which defs are actually
+ * referenced — the editor's export finalizer uses a reference-walker
+ * instead, but standalone SVG producers (e.g. CLI fixture generation) may
+ * prefer this unconditional emission.
+ */
+declare function renderLibraryDefs(defs: readonly LibraryDef[]): string;
+/**
+ * Collect every library-def id referenced by a shape collection. Covers
+ * all the ways a shape points at a library entry:
+ *
+ *   - `fillLibraryId` / `strokeLibraryId` (gradient / pattern paint servers)
+ *   - `filterLibraryIds[]` (filter chain)
+ *   - `markerStart` / `markerMid` / `markerEnd` (vertex markers)
+ *   - `symbolId` (symbol instances)
+ *
+ * Ids for built-in markers (e.g. `mkr-builtin-arrow`, `line-marker-arrow`)
+ * are included in the result — callers that emit built-ins from the
+ * descriptor registry should still look here for the reference signal.
+ *
+ * Does NOT include `url(#...)` strings parsed out of inline fill/stroke
+ * CSS text — the library-first pipeline assumes shapes set `fillLibraryId`
+ * explicitly when they reference a library def.
+ */
+declare function collectReferencedLibraryIds(shapes: readonly SerializedShape[]): Set<string>;
+/**
+ * Library-first `<defs>` emission: walks shapes and emits one `<defs>`
+ * entry per unique paint-server / filter / user-marker referenced by the
+ * scene. Built-in markers (which live in the descriptor registry, not
+ * `snapshot.library`) are NOT emitted by this function — callers should
+ * compose with `renderBuiltinMarkerDefs` or similar.
+ *
+ * Two input sources are merged, with library-first precedence:
+ *
+ *   1. **Library refs**: shapes set `fillLibraryId`, `strokeLibraryId`,
+ *      `filterLibraryIds`, `markerStart/Mid/End`, or `symbolId` pointing
+ *      into `library`. The library entry is authoritative for the def.
+ *   2. **Legacy inline payloads**: shapes with `fillGradient` /
+ *      `strokeGradient` / `filters[]` but NO matching library ref. A
+ *      transient library def is synthesized from the inline data on the
+ *      fly so renders remain correct for snapshots that bypass the
+ *      migrator (e.g. older tests, hand-built snapshots via the SDK).
+ *
+ * Dedup is by emitted id. A shape that has both a library ref AND an
+ * inline payload with the same id emits the library entry once.
+ *
+ * Defs are emitted in `LIBRARY_EMIT_ORDER` so cross-kind references
+ * (e.g. a `<symbol>` whose inner shapes reference a gradient) resolve
+ * during single-pass parsing.
+ */
+declare function renderReferencedLibraryDefs(shapes: readonly SerializedShape[], library: readonly LibraryDef[]): string;
+
 /**
  * Code generation dispatcher — routes to format-specific generators.
  */
@@ -2836,6 +3747,26 @@ declare abstract class ShapeBuilder<T extends ShapeBuilder<T>> {
     locked(value?: boolean): T;
     /** Set visibility. */
     visible(value?: boolean): T;
+    /**
+     * Set the shape's structural role in the exported SVG.
+     *
+     * - `'normal'` (default) — rendered inline in document order.
+     * - `'motionOnly'` — emitted inside `<defs>` as an `<mpath>` reference
+     *   target and NOT rendered.  Pair with `Track.motionPathRef(shapeId,
+     *   'curveTemplate')` so the animation's `<mpath>` resolves to this
+     *   shape's origin-normalized `d`.  The exporter automatically
+     *   translates the shape's `d` so its first moveto is at `M 0,0`,
+     *   the canonical "curve template" form that lets multiple animations
+     *   share one motion-path `<defs>` entry.
+     *
+     * @see https://svgwg.org/specs/animations/#MPathElement
+     */
+    displayMode(mode: 'normal' | 'motionOnly'): T;
+    /**
+     * Convenience alias for `.displayMode('motionOnly')` — marks this shape
+     * as an `<mpath>` reference target (not rendered; placed in `<defs>`).
+     */
+    motionOnly(): T;
     /** Set a solid fill color. */
     fill(color: string, opacity?: number): T;
     /** Set fill to none (transparent). */
@@ -3242,26 +4173,26 @@ declare class Arrow extends PolygonShapeBuilder<Arrow> {
     /** Set the arrow shaft width as a percent (0–100). */
     shaftWidth(percent: number): Arrow;
 }
-declare class Spline extends ShapeBuilder<Spline> {
-    constructor(points?: (Point | SplinePoint)[]);
+declare class Path extends ShapeBuilder<Path> {
+    constructor(points?: (Point | PathPoint)[]);
     /** Set the spline points. */
-    points(pts: (Point | SplinePoint)[]): Spline;
+    points(pts: (Point | PathPoint)[]): Path;
     /** Add a point to the spline. */
-    addPoint(x: number, y: number): Spline;
+    addPoint(x: number, y: number): Path;
     /** Set the curve type. */
-    curveType(type: SplineCurveType): Spline;
+    curveType(type: PathCurveType): Path;
     /** Set whether the spline is closed. */
-    closed(value?: boolean): Spline;
+    closed(value?: boolean): Path;
     /** Set the tension for Catmull-Rom curves (0–1). */
-    tension(value: number): Spline;
+    tension(value: number): Path;
     /** Set arc params for ARC curve type. */
-    arcParams(params: ArcParams$1[]): Spline;
+    arcParams(params: ArcParams$1[]): Path;
     /** Set the start endpoint marker. */
-    markerStart(style: EndpointStyle): Spline;
+    markerStart(style: EndpointStyle): Path;
     /** Set the end endpoint marker. */
-    markerEnd(style: EndpointStyle): Spline;
+    markerEnd(style: EndpointStyle): Path;
     /** Convenience: set both markers. */
-    markers(start: EndpointStyle, end: EndpointStyle): Spline;
+    markers(start: EndpointStyle, end: EndpointStyle): Path;
 }
 declare class Polyline extends ShapeBuilder<Polyline> {
     constructor(points?: Point[]);
@@ -3365,6 +4296,42 @@ declare class Track {
     locked(): Track;
     /** Set an SVG path for motion-path animation. */
     motionPath(path: string): Track;
+    /**
+     * Link this motion-path track to another shape's geometry as an
+     * `<mpath href="#shapeId"/>` reference.  The track's `motionPath` is
+     * expected to have been set (or will be) to the referenced shape's
+     * path data — the two fields together model SVG Animations §19.2
+     * semantics where `<mpath>` supersedes inline `path=` on export.
+     *
+     * The `mode` controls how the reference is interpreted:
+     *   - `'trackShape'` (default) — the motion path is displacement-
+     *     relative to the animated element's center, so playback and
+     *     editor overlay render on top of the referenced shape's absolute
+     *     position.  Exports as inline `path=` (spec-correct).
+     *   - `'curveTemplate'` — the motion path's first point is `M 0,0`,
+     *     matching how `<mpath>` semantics want a reusable curve-template.
+     *     Exports as `<mpath href="#shapeId"/>` pointing at a `<defs>` path
+     *     with the same origin-normalized `d` — reusable across animations.
+     *
+     * Pair with `.motionPath(d)` where `d` is in the form the mode expects:
+     * absolute-minus-element-center for trackShape, origin-normalized for
+     * curveTemplate.
+     *
+     * @example
+     * ```ts
+     * const curve = new Path(...).id('curve');
+     * doc.add(curve);
+     *
+     * const track = new Track('rect-1', 'pathMotion')
+     *   .motionPath('M0,0 C 50,-100 150,-100 200,0')   // origin-normalized
+     *   .motionPathRef('curve', 'curveTemplate')        // emits <mpath href="#curve"/>
+     *   .keyframe(0, 0)
+     *   .keyframe(3, 1);
+     * ```
+     *
+     * @see https://svgwg.org/specs/animations/#MPathElement
+     */
+    motionPathRef(shapeId: string, mode?: 'trackShape' | 'curveTemplate'): Track;
     /**
      * Set the begin trigger for this track.
      *
@@ -3784,4 +4751,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 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 FillType, type FilmGrainFilter, 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, type LicenseType, type LightSource, Line, type LineEndpointValue, type LineNodeProps, type LinearEasingPoint, type LinearGradient, LinearGradientBuilder, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, MAX_COORDINATE_PRECISION, MIGRATIONS, type MarkerDescriptor, 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, PatternBuilder, type PatternElement, type PatternFill, type PatternParams, type PatternSvgContentResult, type PatternType, type PixelateFilter, type Point, type PointLightFilter, type PolygonBaseNodeProps, Polyline, type PolylineNodeProps, type RadialGradient, RadialGradientBuilder, 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, Spline, SplineCurveType, type SplineNodeProps, type SplinePoint, SplinePointType, type SpotLightFilter, Square, type SquareNodeProps, Star, type StarNodeProps, type StepPosition, type StepsParams, type StringifyOptions, type StrokeType, type SymbolInstanceNodeProps, type TemplateVariable, type TemplateVariableSource, type TemplateVariableType, Text, type TextNodeProps, Timeline, Track, Triangle, type TriangleNodeProps, type ValidationError, type ValidationResult, type VariableMap, type Viewbox, type WarpFilter, type WarpType, type WatercolorFilter, type XrayFilter, computeArrowVertices, computeCloudPath, computeCrossVertices, computeDashArray, computeGearPath, computeGearVertices, computeHeartPath, computeLightningVertices, computePolygonVertices, computeRectanglePath, computeRingPath, computeSpeechBubbleVertices, computeSpiralPath, computeSplinePath, computeStarVertices, createDocument, createShape, createViewbox, escXml, extractVariables, filterAttr, generateCode, generateCssCode, generateD3Code, generateId, generatePatternSvgContent, generateReactCode, generateSvgCode, generateVueCode, getBuiltInMarkerDefs, getEasingCubicBezier, getEffectivePrecision, getMarkerDescriptors, getPatternElements, linearGradient, migrateSnapshot, parseDocument, parseVariableArgs, pattern, radialGradient, renderAnimationElements, renderCircle, renderEllipse, renderFilterDefs, renderFilterPrimitivesForType, renderImage, renderLine, renderPolygonShape, renderPolyline, renderRectangle, renderShape, renderSpline, 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, 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 };