@svgsketch/core 0.6.0 → 0.7.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;
@@ -830,6 +862,30 @@ interface ShapeMetadata {
     linkUrl: string;
     linkTarget: LinkTarget;
     customData: Record<string, string>;
+    /**
+     * 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 +924,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.
@@ -1015,261 +1094,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 {
@@ -1412,17 +1241,67 @@ 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[];
@@ -1503,6 +1382,21 @@ interface SerializedShape {
          * variant (`def.shapes`). Only meaningful on `symbol-instance` shapes.
          */
         variantKey?: 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.
@@ -1576,7 +1470,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,234 +1500,564 @@ interface HistorySnapshot {
     templateVariables?: TemplateVariable[];
     /** Animation timeline (tracks, keyframes, easing). */
     animationTimeline?: SerializedAnimationTimeline;
-    /** User-defined custom patterns stored in the document. */
+    /**
+     * 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[];
+    /** @deprecated v2 — use `library`. Read-only: v1 docs migrate into `library`. */
     customPatterns?: CustomPatternDef[];
-    /** Symbol definitions (reusable component templates). */
+    /** @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[];
+}
+/**
+ * A variant axis on a component symbol. Each axis has a name (e.g.
+ * `state`, `size`, `theme`) and an ordered list of allowed values
+ * (e.g. `[default, hover, pressed]`). The default value is always
+ * the first entry in `values`.
+ */
+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.
+ */
+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;
+    /**
+     * 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;
     /**
-     * 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.
+     * 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).
      */
-    markers?: SerializedMarkerDef[];
+    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';
+    viewBox: 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;
+    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;
 }
-/**
- * A variant axis on a component symbol. Each axis has a name (e.g.
- * `state`, `size`, `theme`) and an ordered list of allowed values
- * (e.g. `[default, hover, pressed]`). The default value is always
- * the first entry in `values`.
- */
-interface SerializedVariantAxis {
-    name: string;
-    values: string[];
+interface SymbolInstanceNodeProps extends CommonNodeProps {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    symbolId: 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>;
+interface GroupNodeProps {
+    groupId: string | null;
 }
+type DocumentNodeProps = Record<string, never>;
 /**
- * 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).
+ * Maps each node type string to its typed property interface.
+ * Used by `SceneNode.create()` for compile-time type safety.
  */
-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 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;
-}
-/** 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;
+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 — Schema migrations.
@@ -1870,17 +2094,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.
@@ -2260,14 +2473,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 +2511,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 +2784,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 +3174,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). */
@@ -3365,6 +3723,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 Spline(...).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 +4178,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 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 FilterLibraryDef, 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, 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, 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 SymbolLibraryDef, 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, collectReferencedLibraryIds, 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, renderBuiltinMarkerDefs, renderCircle, renderEllipse, renderFilterDefs, renderFilterLibraryDef, renderFilterPrimitivesForType, renderImage, renderLibraryDef, renderLibraryDefs, renderLine, renderLinearGradientLibraryDef, renderMarkerLibraryDef, renderPatternLibraryDef, renderPolygonShape, renderPolyline, renderRadialGradientLibraryDef, renderRectangle, renderReferencedLibraryDefs, renderShape, renderSpline, renderSymbolLibraryDef, renderText, renderToSvg, roundCoord, roundNumberString, roundSerializedShape, roundSnapshot, stringifyDocument, substituteString, substituteVariables, validateSnapshot, verticesToPath };