@svgsketch/core 0.5.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. */
@@ -165,6 +191,15 @@ interface AnimationTrack {
      * @default 'replace' (except transforms, which default to 'sum')
      */
     additive?: 'sum' | 'replace';
+    /**
+     * Scoping for this track.
+     * - Absent / 'document' — plays on the main document timeline (default).
+     * - `'marker:<markerId>'` — scoped to a marker definition's inner shapes.
+     *   Only evaluated when the editor is isolation-editing that marker;
+     *   exported as SMIL inside the `<marker>` element so it animates at
+     *   every attached vertex.
+     */
+    scope?: string;
 }
 /**
  * The top-level animation timeline for a document.
@@ -197,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;
@@ -209,6 +250,8 @@ interface SerializedAnimationTimeline {
         };
         motionRotate?: 'auto' | 'auto-reverse' | number;
         additive?: 'sum' | 'replace';
+        /** Scoping — see `AnimationTrack.scope`. */
+        scope?: string;
         /**
          * 6-element CSS matrix of the track's ancestor transform context, captured
          * at the time the animation was authored. Preserves visual fidelity when
@@ -302,6 +345,19 @@ interface Viewbox {
     width: number;
     height: number;
 }
+/** Direction hint for connector routing tangents. */
+type ConnectionDirection = 'n' | 's' | 'e' | 'w' | 'any';
+/** A named anchor point on a shape where connectors can attach. */
+interface ConnectionPoint {
+    /** Stable id — 'n','s','e','w','center' for derived; 'custom-<uuid>' for user-placed. */
+    id: string;
+    /** Location in canvas/workspace coordinates (post-transform). */
+    point: Point;
+    /** Tangent hint used by connector routing. */
+    direction: ConnectionDirection;
+    /** 'derived' anchors are computed from shape geometry; 'custom' are persisted overrides. */
+    kind: 'derived' | 'custom';
+}
 type FillType = 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'none';
 type StrokeType = 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'none';
 type GradientSpreadMethod = 'pad' | 'repeat' | 'reflect';
@@ -344,6 +400,14 @@ interface LinearGradient {
      * element's bbox-normalised [0, 1] space. See `GradientUnits`.
      */
     gradientUnits?: GradientUnits;
+    /**
+     * Original `id` from the imported source SVG. Runtime `id` is always
+     * a fresh GUID (to keep editor uniqueness invariants), but `sourceId`
+     * is retained so export can restore human-friendly ids when there is
+     * no collision. Cleared whenever the gradient is mutated through the
+     * editor — at that point the source id no longer describes the data.
+     */
+    sourceId?: string;
 }
 interface RadialGradient {
     type: 'radial-gradient';
@@ -363,6 +427,8 @@ interface RadialGradient {
      * `r`/`ry` are in document user space. See `GradientUnits`.
      */
     gradientUnits?: GradientUnits;
+    /** See `LinearGradient.sourceId`. */
+    sourceId?: string;
 }
 /**
  * Per-pattern-type tuneable parameters.
@@ -444,6 +510,8 @@ interface PatternFill {
     y?: number;
     /** ID of the `CustomPatternDef` this fill was built from (if any). */
     customPatternId?: string;
+    /** See `LinearGradient.sourceId`. */
+    sourceId?: string;
 }
 type GradientDefinition = LinearGradient | RadialGradient | PatternFill;
 /** Style overrides for a single rich-text segment. */
@@ -495,7 +563,7 @@ interface CustomPatternDef {
     /** Tile height in userSpaceOnUse coordinates. */
     height: number;
 }
-type FilterType = 'drop-shadow' | 'inner-shadow' | 'gaussian-blur' | 'motion-blur' | 'point-light' | 'spot-light' | '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';
+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 BlurQuality = 'normal' | 'high';
 interface BaseFilter {
     id: string;
@@ -558,6 +626,41 @@ interface SpotLightFilter extends BaseFilter {
     specularConstant: number;
     specularExponent: number;
 }
+type LightSource = {
+    kind: 'point';
+    x: number;
+    y: number;
+    z: number;
+} | {
+    kind: 'spot';
+    x: number;
+    y: number;
+    z: number;
+    pointsAtX: number;
+    pointsAtY: number;
+    pointsAtZ: number;
+    limitingConeAngle?: number;
+    specularExponent?: number;
+} | {
+    kind: 'distant';
+    azimuth: number;
+    elevation: number;
+};
+interface DiffuseLightingFilter extends BaseFilter {
+    type: 'diffuse-lighting';
+    surfaceScale: number;
+    diffuseConstant: number;
+    color: string;
+    lightSource: LightSource;
+}
+interface SpecularLightingFilter extends BaseFilter {
+    type: 'specular-lighting';
+    surfaceScale: number;
+    specularConstant: number;
+    specularExponent: number;
+    color: string;
+    lightSource: LightSource;
+}
 type OutlinePosition = 'outside' | 'center' | 'inside';
 interface OutlineFilter extends BaseFilter {
     type: 'outline';
@@ -706,7 +809,29 @@ interface InnerGlowFilter extends BaseFilter {
     radius: number;
     intensity: number;
 }
-type ShapeFilter = DropShadowFilter | InnerShadowFilter | GaussianBlurFilter | MotionBlurFilter | PointLightFilter | SpotLightFilter | 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;
+/**
+ * Passthrough for `<filter>` definitions the editor doesn't model as a preset.
+ * The parser serialises the element's inner markup and authored region
+ * attributes verbatim; the filter manager re-emits them on render. Absent
+ * attributes stay `undefined` so the UA applies the SVG spec initial values
+ * (filterUnits=objectBoundingBox, primitiveUnits=userSpaceOnUse, filter region
+ * -10% -10% 120% 120%, color-interpolation-filters=linearRGB).
+ */
+interface RawSvgFilter extends BaseFilter {
+    type: 'raw-svg';
+    svgContent: string;
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+    filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    colorInterpolationFilters?: 'auto' | 'sRGB' | 'linearRGB';
+    floodColor?: string;
+    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 {
     x: number;
@@ -737,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
@@ -775,6 +924,107 @@ 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.
+     * Stored on the document so collaborators stay consistent and
+     * round-trips are deterministic.
+     *
+     * Range 0-12. Defaults to 3 (sub-pixel precision adequate for screen
+     * rendering; matches SVGO's `floatPrecision` and Adobe Illustrator's
+     * SVG export defaults). Set higher (6-8) when authoring assets for
+     * high-fidelity interchange. Values above 8 carry no practical benefit
+     * at the coordinate ranges typical of SVG documents.
+     *
+     * Imported SVGs are NOT rounded on the way in; the first edit or save
+     * conforms them to this precision.
+     */
+    coordinatePrecision?: number;
+}
+/**
+ * A document-level `<script>` element. Scripts are stored as inert data
+ * alongside document metadata — never executed inside the editor — and
+ * re-emitted on export.
+ *
+ * Spec reference: SVG 2 §15.9 (The `<script>` element).
+ */
+interface DocumentScript {
+    /** Internal id (guid) used for list keying inside the editor. */
+    id: string;
+    /** Preserved `id` attribute from the source SVG, if any. */
+    svgId?: string;
+    /** Whether this script has inline body text or an external href. */
+    source: 'inline' | 'external';
+    /** Script body for inline scripts. Empty for external. */
+    content: string;
+    /** URL for external scripts. */
+    href?: string;
+    /** MIME type. Defaults to 'application/ecmascript' per SVG 2. */
+    type: string;
+    /** CORS setting. */
+    crossorigin?: 'anonymous' | 'use-credentials';
+    /** async attribute (SVG 2 aligns with HTML). */
+    async?: boolean;
+    /** defer attribute (SVG 2 aligns with HTML). */
+    defer?: boolean;
+    /** Unknown/extra attributes preserved for round-trip fidelity. */
+    customAttrs?: Record<string, string>;
+}
+/**
+ * A document-level `<style>` block captured from the imported SVG and
+ * re-emitted verbatim on export.
+ *
+ * Styles with `preserved: true` are opaque CSS blobs the editor refuses
+ * to reinterpret because their matched elements live inside `<defs>`
+ * subtrees (mask / clipPath / symbol / pattern) that never become canvas
+ * shapes. Keeping them intact is the only way to round-trip author CSS
+ * that drives mask-interior animations (e.g. `stroke-dashoffset` flow on
+ * `<use>` elements inside a `<mask>`).
+ *
+ * Spec reference: SVG 2 §16 (The `<style>` element).
+ */
+interface DocumentStyle {
+    /** Internal id (guid) used for list keying inside the editor. */
+    id: string;
+    /** Preserved `id` attribute from the source SVG, if any. */
+    svgId?: string;
+    /** Raw CSS source — `@keyframes`, rules, `@media`, etc. */
+    css: string;
+    /** `type` attribute. Defaults to `text/css`. */
+    type?: string;
+    /** `media` attribute, if specified. */
+    media?: string;
+    /**
+     * When true, this block was captured verbatim during import because
+     * the editor cannot safely reinterpret its effect. Must be emitted
+     * as-is on export.
+     */
+    preserved: boolean;
+    /** Unknown/extra attributes preserved for round-trip fidelity. */
+    customAttrs?: Record<string, string>;
 }
 /** Type of a template variable's value. */
 type TemplateVariableType = 'string' | 'color' | 'number';
@@ -844,253 +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[];
-    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 {
@@ -1106,6 +1114,16 @@ interface SerializedShape {
         rx?: number;
         ry?: number;
         cornerRadius?: number;
+        cornerShape?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerMode?: 'uniform' | 'non-uniform';
+        cornerRadiusTL?: number;
+        cornerRadiusTR?: number;
+        cornerRadiusBL?: number;
+        cornerRadiusBR?: number;
+        cornerShapeTL?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerShapeTR?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerShapeBL?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerShapeBR?: 'round' | 'notch' | 'bevel' | 'scoop';
         fontSize?: number;
         text?: string;
         fontFamily?: string;
@@ -1139,6 +1157,8 @@ interface SerializedShape {
             x: number;
             dy: number;
         }[];
+        textLength?: number;
+        lengthAdjust?: 'spacing' | 'spacingAndGlyphs';
         /**
          * Whether this text element uses the rich-text model (styled runs with
          * per-character formatting) versus the plain-text model. When true,
@@ -1161,6 +1181,15 @@ interface SerializedShape {
         borderColor?: string;
         borderWidth?: number | string;
         strokeOpacity?: number;
+        /** CSS `paint-order` (SVG 2). Canonical SVG token string, e.g.
+         *  'stroke fill markers'. Omitted when equivalent to default 'normal'. */
+        paintOrder?: string;
+        /** Marker id applied as `marker-start` (rendered `url(#id)` in SVG). */
+        markerStart?: string;
+        /** Marker id applied as `marker-mid`. */
+        markerMid?: string;
+        /** Marker id applied as `marker-end`. */
+        markerEnd?: string;
         cx?: number;
         cy?: number;
         sides?: number;
@@ -1212,11 +1241,69 @@ 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;
@@ -1229,6 +1316,40 @@ interface SerializedShape {
         originalHeight?: number;
         preserveAspectRatio?: boolean;
         imageOpacity?: number;
+        mediaKind?: 'audio' | 'video';
+        mediaMimeType?: string;
+        naturalDuration?: number;
+        begin?: number;
+        trimStart?: number;
+        trimEnd?: number;
+        volume?: number;
+        muted?: boolean;
+        loop?: boolean;
+        playbackRate?: number;
+        mediaOpacity?: number;
+        /** Auto-generated volume ramp length at clip start (seconds). */
+        fadeInDuration?: number;
+        /** Auto-generated volume ramp length at clip end (seconds). */
+        fadeOutDuration?: number;
+        /** First-frame thumbnail (data URI or /api/image-assets URL). Video only. */
+        posterHref?: string;
+        /** Crop rectangle in source pixels. Video only. */
+        sourceRect?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /**
+         * BCP 47 language tag matched against the user agent's language
+         * preferences via SVG's `systemLanguage` conditional-processing
+         * attribute. Meaningful when a `<switch>` wraps multiple
+         * localized media alternatives — the UA picks the foreignObject
+         * whose language matches. No editor UI yet; preserved on
+         * import/export for forward compatibility with translated
+         * soundtracks / captioned video versions.
+         */
+        systemLanguage?: string;
         shapeInsideRef?: string;
         shapePadding?: number;
         isTextPath?: boolean;
@@ -1261,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.
@@ -1276,6 +1412,40 @@ interface SerializedShape {
          * when serialized to standalone SVG.
          */
         bindings?: Record<string, string>;
+        /** User-placed custom connection anchors. Derived anchors are not persisted. */
+        connectionPoints?: ConnectionPoint[];
+        /** Connector shape: reference to the source shape + anchor it attaches to. */
+        sourceRef?: {
+            shapeId: string;
+            anchorId: string;
+        } | null;
+        /** Connector shape: reference to the target shape + anchor it attaches to. */
+        targetRef?: {
+            shapeId: string;
+            anchorId: string;
+        } | null;
+        /** Connector shape: cached absolute source point (recomputed when source moves). */
+        sourcePoint?: Point;
+        /** Connector shape: cached absolute target point. */
+        targetPoint?: Point;
+        /** Connector shape: interior waypoints for orthogonal routing. */
+        waypoints?: Point[];
+        /** Connector shape: path routing algorithm. */
+        routingMode?: 'straight' | 'orthogonal' | 'rounded-ortho' | 'curved';
+        /** Connector shape: in-path label (double-click to edit). */
+        label?: string;
+        /** Connector shape: label position along the path (0–1). */
+        labelPosition?: number;
+        /** Connector shape: perpendicular offset of the label. */
+        labelOffset?: number;
+        /** Connector shape: stroke style to Mermaid edge mapping. */
+        mermaidEdgeStyle?: 'solid' | 'thick' | 'dotted';
+        /** Parallelogram/trapezoid slant amount as a % of width. */
+        slantPercent?: number;
+        /** Trapezoid top width as a % of the bottom width (0–100). */
+        topWidthPercent?: number;
+        /** Document shape: wave amplitude as a % of height. */
+        waveAmplitudePercent?: number;
     };
 }
 type SerializedViewbox = Viewbox;
@@ -1300,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.
@@ -1317,164 +1487,577 @@ interface HistorySnapshot {
     clipMaskGroups?: SerializedClipMaskGroup[];
     /** Document-level metadata (title, description, author, etc.) */
     documentMetadata?: DocumentMetadata;
+    /** Document-level `<script>` elements (SVG 2 §15.9). */
+    documentScripts?: DocumentScript[];
+    /**
+     * Document-level `<style>` blocks captured from the source SVG and
+     * re-emitted verbatim on export. Used for CSS whose effect targets
+     * def-scoped content (mask / clipPath / symbol interiors) that the
+     * editor cannot translate into AnimationTracks.
+     */
+    documentStyles?: DocumentStyle[];
     /** Template variable definitions with defaults. */
     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;
+    /**
+     * 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';
+    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;
 }
-/**
- * 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 SpiralNodeProps extends PolygonBaseNodeProps {
+    turns: number;
+    thicknessPercent: number;
+    spiralDirection: number;
 }
-/**
- * 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 GearNodeProps extends PolygonBaseNodeProps {
+    teeth: number;
+    toothDepthPercent: number;
+    holeRadiusPercent: number;
 }
-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 ArrowNodeProps extends PolygonBaseNodeProps {
+    headWidthPercent: number;
+    headLengthPercent: number;
+    shaftWidthPercent: number;
 }
-/** 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 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 — Schema migrations.
@@ -1511,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.
@@ -1777,6 +2349,65 @@ declare function extractVariables(snapshot: HistorySnapshot): ExtractedVariables
  */
 declare function parseVariableArgs(args: string[]): VariableMap;
 
+/**
+ * @svgsketch/core — Coordinate precision utilities.
+ *
+ * Pure rounding utilities used at every state-capture boundary in the
+ * editor (per-shape command capture, full snapshot capture, SVG export)
+ * to enforce a configurable decimal precision on persisted/exported
+ * coordinate values.
+ *
+ * Rounding fires only on the way OUT of the document model (save, export,
+ * undo capture). Imports are never rounded — see DocumentMetadata's
+ * `coordinatePrecision` field for the policy.
+ *
+ * Industry context: Adobe Illustrator, Inkscape, Affinity Designer, and
+ * SVGO all expose a precision control. Default 3 decimals matches SVGO
+ * and Illustrator.
+ */
+
+/** Default precision when DocumentMetadata.coordinatePrecision is unset. */
+declare const DEFAULT_COORDINATE_PRECISION = 3;
+/**
+ * Maximum precision we accept. Above 12 the rounding becomes a no-op for
+ * practical SVG coordinate ranges (float64 has ~15-17 significant digits).
+ */
+declare const MAX_COORDINATE_PRECISION = 12;
+/**
+ * Resolve an optional precision value to a concrete one. Clamps to the
+ * supported range and substitutes the default for `undefined` / `null` /
+ * non-finite inputs.
+ */
+declare function getEffectivePrecision(p: number | undefined | null): number;
+/**
+ * Round a single number to N decimal places. Non-finite inputs (NaN,
+ * Infinity) pass through unchanged so we never poison data with NaN.
+ */
+declare function roundCoord(value: number, precision: number): number;
+/**
+ * Round every numeric token in a string in place. Does not touch any
+ * non-numeric content (operators, commands, whitespace).
+ */
+declare function roundNumberString(s: string, precision: number): string;
+/**
+ * Round all coordinate-bearing numeric fields in a SerializedShape's
+ * state. Returns a new object — input is not mutated.
+ *
+ * `id` and `type` are passed through unchanged.
+ */
+declare function roundSerializedShape(shape: SerializedShape, precision: number): SerializedShape;
+/**
+ * Round all coordinate-bearing fields in a complete HistorySnapshot.
+ * Used at the snapshot-level capture boundary (file save, cloud sync).
+ *
+ * Returns a new snapshot with shapes, viewboxes, guides, measurements,
+ * and the animation timeline rounded. Document metadata (titles, IDs,
+ * etc.) and structural fields (groups, clipMaskGroups, scripts, symbols)
+ * pass through with their numeric leaves rounded but their structure
+ * preserved.
+ */
+declare function roundSnapshot(snapshot: HistorySnapshot, precision: number): HistorySnapshot;
+
 /**
  * Document-level SVG renderer.
  *
@@ -1842,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.
@@ -1869,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.
@@ -2051,6 +2718,7 @@ declare function generatePatternSvgContent(patternType: string, scale: number, c
  *
  * @packageDocumentation
  */
+
 interface MarkerDescriptor {
     /** Marker element id (e.g., 'line-marker-arrow'). */
     id: string;
@@ -2075,6 +2743,22 @@ declare const MARKER_HEIGHT = 6;
  * `markerUnits="strokeWidth"`, and `orient="auto-start-reverse"`.
  */
 declare function getMarkerDescriptors(): MarkerDescriptor[];
+/**
+ * Maps the legacy marker ids (used by line endpoint shape state) to the new
+ * first-class MarkerManager ids. The legacy ids remain valid references in
+ * the DOM — built-ins are emitted under BOTH ids to preserve backwards
+ * compat with saved docs that reference `url(#line-marker-arrow)`.
+ */
+declare const BUILTIN_MARKER_ID_MAP: Record<string, string>;
+/**
+ * Return `SerializedMarkerDef`s for the built-in line endpoint markers.
+ *
+ * Built-ins carry `shapes: []` — their geometry is rendered by the editor
+ * directly from the descriptor registry rather than from `SerializedShape`s.
+ * This keeps descriptor → shape conversion out of v1 scope. Consequence:
+ * built-ins are non-editable (the markers panel disables Edit on them).
+ */
+declare function getBuiltInMarkerDefs(): SerializedMarkerDef[];
 
 /**
  * SMIL animation renderer — converts SerializedAnimationTimeline
@@ -2100,6 +2784,95 @@ declare function getMarkerDescriptors(): MarkerDescriptor[];
  */
 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.
  */
@@ -2401,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). */
@@ -2930,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.
      *
@@ -3349,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, type BaseFilter, type BlackAndWhiteFilter, type BlurQuality, type BrightnessFilter, CURRENT_SCHEMA_VERSION, type ChannelPainterFilter, Circle, type CircleNodeProps, type CodeFormat, type CodegenOptions, type CommonNodeProps, type ContouringDiscreteFilter, type ContouringTableFilter, type ContrastFilter, type CornerShapeValue, type CreateDocumentOptions, type CreateShapeOptions, Cross, type CrossNodeProps, type CrumpledPlasticFilter, type CustomPatternDef, type CycleBehavior, Document, type DocumentMetadata, type DocumentNodeProps, type DocumentOptions, 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, Line, type LineEndpointValue, type LineNodeProps, type LinearEasingPoint, type LinearGradient, LinearGradientBuilder, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, 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, 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 SerializedShape, type SerializedSymbolDef, type SerializedVariantAxis, type SerializedViewbox, ShapeBuilder, type ShapeFilter, type ShapeMetadata, type SharpenFilter, 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, getEasingCubicBezier, getMarkerDescriptors, getPatternElements, linearGradient, migrateSnapshot, parseDocument, parseVariableArgs, pattern, radialGradient, renderAnimationElements, renderCircle, renderEllipse, renderFilterDefs, renderFilterPrimitivesForType, renderImage, renderLine, renderPolygonShape, renderPolyline, renderRectangle, renderShape, renderSpline, renderText, renderToSvg, 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 };