@svgsketch/core 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -27,9 +27,31 @@ declare enum EasingType {
     EASE_IN_SINE = "ease-in-sine",
     EASE_OUT_SINE = "ease-out-sine",
     EASE_IN_OUT_SINE = "ease-in-out-sine",
+    EASE_IN_QUINT = "ease-in-quint",
+    EASE_OUT_QUINT = "ease-out-quint",
+    EASE_IN_OUT_QUINT = "ease-in-out-quint",
+    EASE_IN_EXPO = "ease-in-expo",
+    EASE_OUT_EXPO = "ease-out-expo",
+    EASE_IN_OUT_EXPO = "ease-in-out-expo",
+    EASE_IN_CIRC = "ease-in-circ",
+    EASE_OUT_CIRC = "ease-out-circ",
+    EASE_IN_OUT_CIRC = "ease-in-out-circ",
     EASE_IN_BACK = "ease-in-back",
     EASE_OUT_BACK = "ease-out-back",
-    EASE_IN_OUT_BACK = "ease-in-out-back"
+    EASE_IN_OUT_BACK = "ease-in-out-back",
+    CUSTOM_BEZIER = "custom-bezier",
+    LINEAR_FUNCTION = "linear-function",
+    STEPS = "steps"
+}
+/**
+ * Step position for CSS `steps()` easing. Follows CSS Easing 1 §3.2.
+ * `start`/`end` are legacy aliases for `jump-start`/`jump-end`.
+ */
+type StepPosition = 'jump-start' | 'jump-end' | 'jump-none' | 'jump-both';
+/** Parameters for a `steps(count, position)` easing function. */
+interface StepsParams {
+    count: number;
+    position: StepPosition;
 }
 /**
  * Map from EasingType → cubic-bezier control points [x1, y1, x2, y2].
@@ -82,6 +104,19 @@ interface AnimationKeyframe {
     time: number;
     value: number | string;
     easing: EasingType;
+    /** Custom cubic-bezier control points [x1, y1, x2, y2] when easing is CUSTOM_BEZIER. */
+    customBezier?: [number, number, number, number];
+    /** Control points for CSS linear() easing when easing is LINEAR_FUNCTION. */
+    linearPoints?: LinearEasingPoint[];
+    /** Step count and jump position when easing is STEPS. */
+    stepsParams?: StepsParams;
+}
+/** A control point for a CSS linear() easing function. */
+interface LinearEasingPoint {
+    /** Output value (y-axis). Can exceed 0-1 for overshoot/elastic effects. */
+    value: number;
+    /** Position on the x-axis (0-1). */
+    position: number;
 }
 /**
  * An animation track binds a single property of a single shape
@@ -174,10 +209,33 @@ interface SerializedAnimationTimeline {
         };
         motionRotate?: 'auto' | 'auto-reverse' | number;
         additive?: 'sum' | 'replace';
+        /**
+         * 6-element CSS matrix of the track's ancestor transform context, captured
+         * at the time the animation was authored. Preserves visual fidelity when
+         * a shape is animated inside a transformed group and later copied, pasted,
+         * or imported into a different transform context.
+         */
+        ancestorMatrix?: number[];
+        /**
+         * Translation offset applied to transform-property keyframe values when
+         * the animated shape was pasted or imported into a new document, so that
+         * absolute transforms (rotation origins, translate values) remain correct
+         * relative to the shape's new location.
+         */
+        pasteOffset?: {
+            x: number;
+            y: number;
+        };
         keyframes: {
             time: number;
             value: number | string;
             easing: string;
+            customBezier?: [number, number, number, number];
+            linearPoints?: {
+                value: number;
+                position: number;
+            }[];
+            stepsParams?: StepsParams;
         }[];
     }[];
 }
@@ -191,8 +249,8 @@ interface AnimatablePropertyDescriptor {
     key: string;
     /** Human-readable label. */
     label: string;
-    /** Value type: number, color (hex string), or path (SVG path data). */
-    type: 'number' | 'color' | 'path';
+    /** Value type: number, color (hex string), path (SVG path data), or points (polyline/polygon). */
+    type: 'number' | 'color' | 'path' | 'points';
     /** The SVG attribute name this maps to (e.g. 'cx', 'fill'). */
     attr?: string;
     /** Minimum value for numeric properties. */
@@ -253,6 +311,23 @@ interface GradientStop {
     color: string;
     opacity: number;
 }
+/**
+ * How gradient coordinates are interpreted.
+ *
+ * - `'objectBoundingBox'` (default): coordinates are fractions of the
+ *   painted element's bounding box, where `1` equals the full width or
+ *   height. The gradient rescales to each shape.
+ * - `'userSpaceOnUse'`: coordinates are absolute user-space values, so
+ *   the gradient is a fixed color field in the document. Multiple
+ *   shapes referencing the same gradient see a consistent field, and
+ *   clipped shapes reveal a specific slice of it. Required for
+ *   round-tripping source SVGs that author gradients this way.
+ *
+ * When omitted, the renderer treats the gradient as `objectBoundingBox`
+ * for backward compatibility with documents authored before this field
+ * was added.
+ */
+type GradientUnits = 'objectBoundingBox' | 'userSpaceOnUse';
 interface LinearGradient {
     type: 'linear-gradient';
     id: string;
@@ -263,6 +338,12 @@ interface LinearGradient {
     stops: GradientStop[];
     spreadMethod: GradientSpreadMethod;
     opacity: number;
+    /**
+     * When present and equal to `'userSpaceOnUse'`, `x1`/`y1`/`x2`/`y2`
+     * are in document user space (post any ancestor bake), not in the
+     * element's bbox-normalised [0, 1] space. See `GradientUnits`.
+     */
+    gradientUnits?: GradientUnits;
 }
 interface RadialGradient {
     type: 'radial-gradient';
@@ -277,6 +358,11 @@ interface RadialGradient {
     stops: GradientStop[];
     spreadMethod: GradientSpreadMethod;
     opacity: number;
+    /**
+     * When present and equal to `'userSpaceOnUse'`, `cx`/`cy`/`fx`/`fy`/
+     * `r`/`ry` are in document user space. See `GradientUnits`.
+     */
+    gradientUnits?: GradientUnits;
 }
 /**
  * Per-pattern-type tuneable parameters.
@@ -652,6 +738,33 @@ interface ShapeMetadata {
     linkTarget: LinkTarget;
     customData: Record<string, string>;
 }
+/**
+ * Provider attribution metadata for an image shape sourced from a third-party
+ * stock photo service. Stored on the shape so the editor can render the
+ * required photographer + provider credit links wherever the image is shown,
+ * and so the data round-trips through document save/load. Required by stock
+ * photo provider API guidelines (e.g. Unsplash).
+ */
+interface ImageAttribution {
+    /** Slug for the provider, e.g. 'unsplash', 'openverse'. */
+    source: string;
+    /** Display name for the provider, e.g. 'Unsplash', 'OpenVerse'. */
+    sourceName: string;
+    /** URL to the photo's HTML page on the provider site. */
+    sourceUrl: string;
+    /** Photographer's display name. */
+    photographer: string;
+    /** Photographer's profile URL on the provider site. */
+    photographerUrl: string;
+    /**
+     * Optional SPDX-style license display label, e.g. 'CC BY 4.0', 'CC0 1.0',
+     * 'Public Domain'. Set by aggregators (OpenVerse) that surface per-asset
+     * license info; absent for providers with a single global license model.
+     */
+    license?: string;
+    /** Optional URL to the full license text. */
+    licenseUrl?: string;
+}
 type LicenseType = '' | 'cc0' | 'cc-by' | 'cc-by-sa' | 'cc-by-nc' | 'cc-by-nc-sa' | 'cc-by-nd' | 'cc-by-nc-nd' | 'mit' | 'apache-2.0' | 'custom';
 interface DocumentMetadata {
     title: string;
@@ -665,9 +778,36 @@ interface DocumentMetadata {
 }
 /** Type of a template variable's value. */
 type TemplateVariableType = 'string' | 'color' | 'number';
-/** A template variable definition stored in the document. */
+/**
+ * Where a TemplateVariable came from. `user` is hand-authored in the
+ * Variables panel; `palette` is auto-generated by the palette-token
+ * integration and is read-mostly (the source of truth lives in user
+ * settings, not the document).
+ */
+type TemplateVariableSource = {
+    kind: 'user';
+} | {
+    kind: 'palette';
+    paletteId: string;
+    index: number;
+};
+/**
+ * A template variable definition stored in the document.
+ *
+ * Two complementary roles:
+ *
+ *   1. **Build-time substitution** — `{{name}}` placeholders in shape
+ *      properties are replaced via `substituteVariables()` (CLI / SDK
+ *      template builds).
+ *
+ *   2. **Runtime CSS custom property** — when the editor is open, each
+ *      variable is mirrored as `--name: defaultValue` inside a single
+ *      `:root, svg { ... }` style block in the canvas SVG. Shapes can
+ *      bind a geometry property to a variable via `var(--name)` and
+ *      get live updates whenever the value changes.
+ */
 interface TemplateVariable {
-    /** Variable name (used in `{{name}}` placeholders). */
+    /** Variable name (used in `{{name}}` placeholders and as CSS custom property `--name`). */
     name: string;
     /** The type of value this variable holds. */
     type: TemplateVariableType;
@@ -677,6 +817,13 @@ interface TemplateVariable {
     label?: string;
     /** Description / help text. */
     description?: string;
+    /**
+     * Provenance tag. Defaults to `{ kind: 'user' }` when omitted.
+     * Palette-sourced variables are surfaced in the panel as a read-only
+     * group — editing them in place would break the round-trip with the
+     * settings palette.
+     */
+    source?: TemplateVariableSource;
 }
 interface Guide {
     id: string;
@@ -696,6 +843,248 @@ interface Measurement {
     opacity?: number;
 }
 
+/**
+ * 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[];
+    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.
  *
@@ -746,6 +1135,17 @@ interface SerializedShape {
             y: number;
             rotate: number;
         }[];
+        linePositions?: {
+            x: number;
+            dy: number;
+        }[];
+        /**
+         * Whether this text element uses the rich-text model (styled runs with
+         * per-character formatting) versus the plain-text model. When true,
+         * `richTextData` is the authoritative source for text content and
+         * formatting; when false/absent, `text` is authoritative.
+         */
+        useRichText?: boolean;
         richTextData?: RichTextData;
         scaleX?: number;
         scaleY?: number;
@@ -773,10 +1173,21 @@ interface SerializedShape {
         holeRadiusPercent?: number;
         turns?: number;
         thicknessPercent?: number;
-        direction?: number;
+        /** Spiral winding direction: 1 = counterclockwise, -1 = clockwise. */
+        spiralDirection?: number;
         headWidthPercent?: number;
         headLengthPercent?: number;
         shaftWidthPercent?: number;
+        tailAngleDeg?: number;
+        tailLengthPercent?: number;
+        tailWidthPercent?: number;
+        lobeRadiusPercent?: number;
+        cleftDepthPercent?: number;
+        boltSegments?: number;
+        boltJaggednessPercent?: number;
+        boltWidthPercent?: number;
+        cloudBumps?: number;
+        cloudPuffinessPercent?: number;
         x1?: number;
         y1?: number;
         x2?: number;
@@ -791,6 +1202,16 @@ interface SerializedShape {
         endEndpoint?: 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
         locked?: boolean;
         visible?: boolean;
+        /**
+         * SVG `visibility` presentation attribute. Distinct from `visible`:
+         * `visible` (boolean) is the editor's user-toggled layer hide
+         * (display:none semantics); `visibility` is the SVG attribute
+         * (preserves layout, can be flipped by SMIL
+         * `<animate attributeName="visibility">`). Conflating the two breaks
+         * SMIL visibility animations on imported SVGs because display:none
+         * overrides the SVG visibility attribute.
+         */
+        visibility?: 'visible' | 'hidden' | 'collapse';
         fillType?: FillType;
         fillGradient?: LinearGradient | RadialGradient | PatternFill;
         strokeType?: StrokeType;
@@ -819,11 +1240,42 @@ interface SerializedShape {
         strokeLinecap?: 'butt' | 'round' | 'square';
         strokeMiterlimit?: number;
         opacity?: number;
+        blendMode?: string;
+        shapeRendering?: 'auto' | 'optimizeSpeed' | 'crispEdges' | 'geometricPrecision';
         metadata?: Partial<ShapeMetadata>;
         groupId?: string;
         cssClipPath?: string;
         cssMaskProperties?: Record<string, string>;
         symbolId?: string;
+        /**
+         * Per-shape property overrides applied to inner shapes of a symbol instance.
+         * Keyed by the inner shape's ID inside the symbol definition. Each value is
+         * a partial state object whose fields override the corresponding fields on
+         * the resolved variant shape at render time. Only meaningful on shapes of
+         * type `symbol-instance`.
+         */
+        symbolOverrides?: Record<string, Partial<SerializedShape['state']>>;
+        /**
+         * Canonical variant axis selection for a symbol instance, encoded as
+         * `axis1=val1,axis2=val2`. Empty / missing → use the symbol's default
+         * variant (`def.shapes`). Only meaningful on `symbol-instance` shapes.
+         */
+        variantKey?: string;
+        /**
+         * Map of geometry-property name → CSS custom-property name (without
+         * the leading `--`) the property is bound to.
+         *
+         * When a property is bound, the literal value in `state[property]`
+         * is the **resolved** value (last seen value of the variable). The
+         * binding is what survives editing — typing into a bound field in
+         * the panel updates the variable, not the literal — and on document
+         * load the literal is re-resolved from the current variable value.
+         *
+         * Example: `{ width: 'card-width', cornerRadius: 'unit' }` means
+         * `state.width = var(--card-width)` and `state.cornerRadius = var(--unit)`
+         * when serialized to standalone SVG.
+         */
+        bindings?: Record<string, string>;
     };
 }
 type SerializedViewbox = Viewbox;
@@ -874,9 +1326,27 @@ interface HistorySnapshot {
     /** Symbol definitions (reusable component templates). */
     symbols?: SerializedSymbolDef[];
 }
+/**
+ * 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.
  */
 interface SerializedSymbolDef {
     /** Unique identifier for this symbol definition. */
@@ -885,12 +1355,34 @@ interface SerializedSymbolDef {
     name: string;
     /** SVG viewBox string ("minX minY width height"). */
     viewBox: string;
-    /** The shapes that make up this symbol's content. */
+    /**
+     * 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 SerializedGroup {
     id: string;
@@ -910,6 +1402,15 @@ interface SerializedGroup {
     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 {
@@ -979,25 +1480,62 @@ interface SerializedClipMaskGroup {
  * @svgsketch/core — Schema migrations.
  *
  * Migrates a HistorySnapshot from any previous schema version to
- * CURRENT_SCHEMA_VERSION. Each migration step is a pure function
- * that transforms version N to N+1.
- *
- * To add a new migration:
- *   1. Bump CURRENT_SCHEMA_VERSION in types/serialized.ts
- *   2. Add a function migrateVNtoVN+1(snapshot) below
- *   3. Add a case in the switch inside migrateSnapshot()
+ * CURRENT_SCHEMA_VERSION. Each migration step is a pure function that
+ * transforms version N to N+1 and lives in the `MIGRATIONS` registry
+ * below.
+ *
+ * **Rules for adding a migration (e.g. v1 → v2):**
+ *   1. Bump `CURRENT_SCHEMA_VERSION` in `types/serialized.ts`.
+ *   2. Write a pure function `migrateV1toV2(snapshot) => snapshot` that
+ *      returns the transformed document (it may mutate — the dispatcher
+ *      clones input first).
+ *   3. Register it in `MIGRATIONS` below with the *source* version as the
+ *      key: `1: migrateV1toV2`.
+ *   4. Add a dedicated test in `migrations.test.ts` that exercises the
+ *      before-and-after shape.
+ *
+ * **Behavior contract:**
+ *   - Unknown older version (gap with no registered migration) → throws.
+ *     Silently stamping would risk corrupting data.
+ *   - Unknown newer version (snapshot from the future) → returned unchanged.
+ *     Loaders that can't understand a newer document should refuse it at a
+ *     higher layer, not here.
+ *   - Missing/malformed `schemaVersion` → treated as version 1 (the oldest
+ *     known format).
  */
 
+/**
+ * A migration function: transforms a snapshot from version N to N+1.
+ *
+ * The function receives a deep-cloned snapshot and may mutate it freely.
+ * 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.
  *
  * The function is idempotent — if the snapshot is already at the current
- * version (or newer), it is returned unchanged.
+ * version (or newer), it is returned as a deep clone with no migrations
+ * applied.
  *
- * @param snapshot - The snapshot to migrate (not mutated; a new object is returned)
- * @returns The migrated snapshot at CURRENT_SCHEMA_VERSION
+ * @param snapshot - The snapshot to migrate. Not mutated — a new object is returned.
+ * @param registry - Override the migration registry (for tests). Defaults to {@link MIGRATIONS}.
+ * @returns The migrated snapshot, stamped with {@link CURRENT_SCHEMA_VERSION}.
+ * @throws If the snapshot is at an older version for which no migration is registered.
  */
-declare function migrateSnapshot(snapshot: HistorySnapshot): HistorySnapshot;
+declare function migrateSnapshot(snapshot: HistorySnapshot, registry?: Record<number, Migration>): HistorySnapshot;
 
 /**
  * @svgsketch/core — Document validation.
@@ -1116,11 +1654,15 @@ declare function createViewbox(x: number, y: number, width: number, height: numb
  *
  *   - Sorts top-level sections in a fixed order (schemaVersion, documentMetadata,
  *     viewboxes, guides, measurements, groups, clipMaskGroups, shapes)
- *   - Sorts shapes, viewboxes, groups, guides by `id`
+ *   - Preserves `shapes` array order because shape-array position IS the
+ *     SVG painter's-model z-order (no separate z-index field exists).
+ *     Sorting would silently reorder rendering and destroy user intent.
+ *   - Sorts other id-keyed collections (groups, viewboxes, guides, etc.)
+ *     by `id` for stable diffs — their order has no semantic meaning
+ *     (groups use siblingIndex + parentId to record position).
  *   - Sorts object keys alphabetically within each shape/state
  *   - Uses 2-space indentation, one property per line
  *   - Strips `undefined` values (but keeps explicit `null`)
- *   - Produces consistent output regardless of insertion order
  *
  * The result can be saved as a `.svgs` file and tracked in Git with
  * meaningful line-by-line diffs.
@@ -1352,6 +1894,41 @@ declare function computeCrossVertices(radius: number, armWidthPercent: number, s
  * Compute arrow vertices (7 points forming an arrow).
  */
 declare function computeArrowVertices(radius: number, headWidthPercent: number, headLengthPercent: number, shaftWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute speech-bubble vertices — square body with a tail protruding at a
+ * chosen angle. The base endpoints lie on the chosen body edge (keeping the
+ * body outline continuous); the tip extends in the direction of `tailAngleDeg`
+ * at length `tailLengthPercent * radius`.
+ *
+ * The `shiftAngleDeg` rotates the entire shape (body + tail).
+ */
+declare function computeSpeechBubbleVertices(radius: number, tailAngleDeg: number, tailLengthPercent: number, tailWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute lightning-bolt vertices — a zigzag ribbon from top tip to bottom tip.
+ * `boltSegments` line segments make the zigzag (alternating x offsets of
+ * `boltJaggednessPercent * radius`); the ribbon is `boltWidthPercent * radius`
+ * wide, perpendicular to each segment's bisector normal.
+ */
+declare function computeLightningVertices(radius: number, boltSegments: number, boltJaggednessPercent: number, boltWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute heart path — two cubic Béziers meeting at the bottom tip and the
+ * upper cleft. `lobeRadiusPercent` controls the horizontal extent of the two
+ * top lobes; `cleftDepthPercent` controls how deep the central dip sits.
+ */
+declare function computeHeartPath(radius: number, lobeRadiusPercent: number, cleftDepthPercent: number, shiftAngleDeg?: number): string;
+/**
+ * Compute cloud path — a classic cartoon-cloud silhouette built as the outer
+ * boundary of N overlapping circles placed around an elongated ellipse.
+ * Circles go all the way around (top, sides, bottom), and the silhouette is
+ * closed by walking each circle's outer arc via the intersection with its
+ * next neighbor. Every transition between bumps is tangent-smooth — no flat
+ * edges, no corners.
+ *
+ * `cloudBumps` (3..8) — number of bump circles forming the silhouette.
+ * `cloudPuffinessPercent` (40..80) — drives bump overlap; higher values
+ * smooth the underside; lower values leave the bumps more pronounced.
+ */
+declare function computeCloudPath(radius: number, cloudBumps: number, cloudPuffinessPercent: number, shiftAngleDeg?: number): string;
 /**
  * Convert an array of vertices to an SVG path string.
  * Supports optional rounded corners via quadratic Bézier.
@@ -1365,9 +1942,6 @@ declare function computeRingPath(radius: number, innerRadiusPercent: number, fil
  * Generate SVG path for an Archimedean spiral.
  */
 declare function computeSpiralPath(radius: number, turns: number, thicknessPercent: number, spiralDirection?: number, shiftAngleDeg?: number): string;
-/**
- * Compute gear vertices (4 vertices per tooth).
- */
 declare function computeGearVertices(teeth: number, radius: number, toothDepthPercent: number, shiftAngleDeg?: number): Point[];
 /**
  * Generate full gear path including optional center hole.
@@ -2212,7 +2786,7 @@ declare class Spiral extends PolygonShapeBuilder<Spiral> {
     turns(n: number): Spiral;
     /** Set the stroke thickness as a percent (0–100). */
     thickness(percent: number): Spiral;
-    /** Set the spiral direction: 1 = clockwise, -1 = counter-clockwise. */
+    /** Set the spiral winding direction: 1 = counterclockwise, -1 = clockwise. */
     direction(d: 1 | -1): Spiral;
 }
 declare class Gear extends PolygonShapeBuilder<Gear> {
@@ -2332,6 +2906,22 @@ declare class Track {
      *                 Defaults to LINEAR.
      */
     keyframe(time: number, value: number | string, easing?: EasingType): Track;
+    /**
+     * Add a keyframe with a custom cubic-bezier easing.
+     *
+     * @param time   - Time in seconds.
+     * @param value  - The property value.
+     * @param points - Cubic-bezier control points [x1, y1, x2, y2].
+     */
+    keyframeBezier(time: number, value: number | string, points: [number, number, number, number]): Track;
+    /**
+     * Add a keyframe with a CSS linear() easing function.
+     *
+     * @param time         - Time in seconds.
+     * @param value        - The property value.
+     * @param linearPoints - Control points for the piecewise linear function.
+     */
+    keyframeLinear(time: number, value: number | string, linearPoints: LinearEasingPoint[]): Track;
     /** Add multiple keyframes at once. */
     keyframes(...kfs: AnimationKeyframe[]): Track;
     /** Disable this track (excluded from playback/export). */
@@ -2759,4 +3349,4 @@ declare class Document {
     private _ensureMetadata;
 }
 
-export { type AnimatablePropertyDescriptor, type AnimationKeyframe, type AnimationTimeline, type AnimationTrack, type AnimationTrigger, type AnimationTriggerType, type ArcParams$1 as ArcParams, type AriaRole, Arrow, type BaseFilter, type BlackAndWhiteFilter, type BlurQuality, type BrightnessFilter, CURRENT_SCHEMA_VERSION, type ChannelPainterFilter, Circle, type CodeFormat, type CodegenOptions, type ContouringDiscreteFilter, type ContouringTableFilter, type ContrastFilter, type CreateDocumentOptions, type CreateShapeOptions, Cross, type CrumpledPlasticFilter, type CustomPatternDef, type CycleBehavior, Document, type DocumentMetadata, type DocumentOptions, type DropShadowFilter, type DuotoneFilter, EASING_CURVES, EVENT_TRIGGER_OPTIONS, EasingType, Ellipse, type EmbossFilter, type ExtractedVariables, type FillType, type FilmGrainFilter, type FilterType, type GaussianBlurFilter, Gear, type GlowFilter, type GouacheFilter, type GradientDefinition, type GradientSpreadMethod, type GradientStop, type GrayscaleFilter, type Guide, type HistorySnapshot, type HueRotateFilter, ImageShape, type InkBlotFilter, type InnerGlowFilter, type InnerShadowFilter, type InvertFilter, type LicenseType, Line, type LinearGradient, LinearGradientBuilder, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, type MarkerDescriptor, type Measurement, type MorphologyFilter, type MorphologyOperator, type MotionBlurFilter, NGon, 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, Polyline, type RadialGradient, RadialGradientBuilder, Rectangle, type RenderOptions, type RichTextData, type RichTextLine, type RichTextSegment, type RichTextSegmentStyle, type RiddledFilter, Ring, type RoundEdgesFilter, type SaturateFilter, type SegmentCurveType, type SepiaFilter, type SerializedAnimationTimeline, type SerializedClipMaskGroup, type SerializedGroup, type SerializedShape, type SerializedSymbolDef, type SerializedViewbox, ShapeBuilder, type ShapeFilter, type ShapeMetadata, type SharpenFilter, Spiral, Spline, SplineCurveType, type SplinePoint, SplinePointType, type SpotLightFilter, Square, Star, type StringifyOptions, type StrokeType, type TemplateVariable, type TemplateVariableType, Text, Timeline, Track, Triangle, type ValidationError, type ValidationResult, type VariableMap, type Viewbox, type WarpFilter, type WarpType, type WatercolorFilter, type XrayFilter, computeArrowVertices, computeCrossVertices, computeDashArray, computeGearPath, computeGearVertices, computePolygonVertices, computeRectanglePath, computeRingPath, 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, 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 };