@svgsketch/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2756 @@
+/**
+ * @svgsketch/core — Animation types.
+ *
+ * These types define the animation timeline model used by the
+ * SDK, CLI, and editor. They mirror the editor's runtime animation
+ * engine but live in core so every consumer shares the same schema.
+ */
+/**
+ * Easing functions available for keyframe interpolation.
+ * Each value maps to a CSS cubic-bezier curve.
+ */
+declare enum EasingType {
+    LINEAR = "linear",
+    EASE = "ease",
+    EASE_IN = "ease-in",
+    EASE_OUT = "ease-out",
+    EASE_IN_OUT = "ease-in-out",
+    EASE_IN_QUAD = "ease-in-quad",
+    EASE_OUT_QUAD = "ease-out-quad",
+    EASE_IN_OUT_QUAD = "ease-in-out-quad",
+    EASE_IN_CUBIC = "ease-in-cubic",
+    EASE_OUT_CUBIC = "ease-out-cubic",
+    EASE_IN_OUT_CUBIC = "ease-in-out-cubic",
+    EASE_IN_QUART = "ease-in-quart",
+    EASE_OUT_QUART = "ease-out-quart",
+    EASE_IN_OUT_QUART = "ease-in-out-quart",
+    EASE_IN_SINE = "ease-in-sine",
+    EASE_OUT_SINE = "ease-out-sine",
+    EASE_IN_OUT_SINE = "ease-in-out-sine",
+    EASE_IN_BACK = "ease-in-back",
+    EASE_OUT_BACK = "ease-out-back",
+    EASE_IN_OUT_BACK = "ease-in-out-back"
+}
+/**
+ * Map from EasingType → cubic-bezier control points [x1, y1, x2, y2].
+ * LINEAR maps to `null` (no curve needed).
+ */
+declare const EASING_CURVES: Record<EasingType, [number, number, number, number] | null>;
+/**
+ * Get the CSS cubic-bezier string for an easing type.
+ * Returns `'linear'` for LINEAR.
+ */
+declare function getEasingCubicBezier(easing: EasingType): string;
+/** How an animation track is triggered. */
+type AnimationTriggerType = 'time' | 'event' | 'expression';
+/** A trigger that begins or ends an animation track. */
+interface AnimationTrigger {
+    type: AnimationTriggerType;
+    /** For 'time': seconds offset (e.g. '0.5'). For 'event': DOM event name (e.g. 'click'). */
+    value: string;
+}
+/** Common event names available for event-based triggers. */
+declare const EVENT_TRIGGER_OPTIONS: readonly [{
+    readonly value: "click";
+    readonly label: "Click";
+}, {
+    readonly value: "mouseenter";
+    readonly label: "Mouse Enter";
+}, {
+    readonly value: "mouseleave";
+    readonly label: "Mouse Leave";
+}, {
+    readonly value: "focus";
+    readonly label: "Focus";
+}, {
+    readonly value: "blur";
+    readonly label: "Blur";
+}, {
+    readonly value: "load";
+    readonly label: "Page Load";
+}];
+/** How a repeating animation behaves after completing a cycle. */
+type CycleBehavior = 'restart' | 'alternate';
+/**
+ * A single keyframe in an animation track.
+ *
+ * - `time`   — Absolute time in seconds within the track.
+ * - `value`  — The property value at this point (number for numeric, string for colors/paths).
+ * - `easing` — The easing curve *leading into* this keyframe (from the previous keyframe).
+ */
+interface AnimationKeyframe {
+    time: number;
+    value: number | string;
+    easing: EasingType;
+}
+/**
+ * An animation track binds a single property of a single shape
+ * to a sequence of keyframes.
+ */
+interface AnimationTrack {
+    id: string;
+    /** The shape ID this track animates. */
+    shapeId: string;
+    /** The property to animate (e.g. 'cx', 'opacity', 'rotation', 'fillColor'). */
+    property: string;
+    /** Ordered keyframes for this property. */
+    keyframes: AnimationKeyframe[];
+    /** Whether this track is active during playback/export. */
+    enabled: boolean;
+    /** Whether the track is locked from editing. */
+    locked: boolean;
+    /** SVG path data for motion-path animation (property should be 'pathMotion'). */
+    motionPath?: string;
+    /** Trigger to begin the animation (defaults to '0s'). */
+    beginTrigger?: AnimationTrigger;
+    /** Trigger to end the animation. */
+    endTrigger?: AnimationTrigger;
+    /** Override the track's cycle duration (seconds). */
+    cycleDuration?: number;
+    /** Number of times to repeat the cycle. */
+    cycleRepeats?: number;
+    /** Repeat indefinitely. */
+    cycleInfinite?: boolean;
+    /** Behavior on repeat: restart from beginning or alternate direction. */
+    cycleBehavior?: CycleBehavior;
+    /** Center point for transform animations (rotation, skew). */
+    transformOrigin?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Rotation behavior for motion-path animation.
+     * - `'auto'` — rotate to match path direction
+     * - `'auto-reverse'` — rotate to match path direction + 180°
+     * - `number` — fixed rotation angle in degrees
+     */
+    motionRotate?: 'auto' | 'auto-reverse' | number;
+    /**
+     * Whether this track's values add to or replace the base value.
+     * @default 'replace' (except transforms, which default to 'sum')
+     */
+    additive?: 'sum' | 'replace';
+}
+/**
+ * The top-level animation timeline for a document.
+ * Contains all animation tracks and playback configuration.
+ */
+interface AnimationTimeline {
+    /** Total timeline duration in seconds. */
+    duration: number;
+    /** Whether the timeline loops after completing. */
+    loop: boolean;
+    /** Playback speed multiplier (1 = normal). */
+    playbackSpeed: number;
+    /** All animation tracks in this timeline. */
+    tracks: AnimationTrack[];
+}
+/**
+ * Serialized animation timeline for persistence in .svgs files.
+ * Identical to AnimationTimeline but uses plain string for easing
+ * to keep the format forward-compatible.
+ */
+interface SerializedAnimationTimeline {
+    duration: number;
+    loop: boolean;
+    playbackSpeed: number;
+    tracks: {
+        id: string;
+        shapeId: string;
+        property: string;
+        enabled: boolean;
+        locked?: boolean;
+        motionPath?: string;
+        motionPathMatrix?: number[];
+        beginTrigger?: AnimationTrigger;
+        endTrigger?: AnimationTrigger;
+        cycleDuration?: number;
+        cycleRepeats?: number;
+        cycleInfinite?: boolean;
+        cycleBehavior?: CycleBehavior;
+        transformOrigin?: {
+            x: number;
+            y: number;
+        };
+        motionRotate?: 'auto' | 'auto-reverse' | number;
+        additive?: 'sum' | 'replace';
+        keyframes: {
+            time: number;
+            value: number | string;
+            easing: string;
+        }[];
+    }[];
+}
+/**
+ * Describes a shape property that can be animated.
+ * Used by the editor UI to build the property picker, but also
+ * available for programmatic introspection.
+ */
+interface AnimatablePropertyDescriptor {
+    /** Internal property key (e.g. 'cx', 'opacity'). */
+    key: string;
+    /** Human-readable label. */
+    label: string;
+    /** Value type: number, color (hex string), or path (SVG path data). */
+    type: 'number' | 'color' | 'path';
+    /** The SVG attribute name this maps to (e.g. 'cx', 'fill'). */
+    attr?: string;
+    /** Minimum value for numeric properties. */
+    min?: number;
+    /** Maximum value for numeric properties. */
+    max?: number;
+    /** Step increment for numeric properties. */
+    step?: number;
+    /** Logical category for UI grouping. */
+    category?: 'position' | 'size' | 'transform' | 'style' | 'path';
+}
+
+/**
+ * @svgsketch/core — Enums used by the document format.
+ *
+ * Only enums referenced by SerializedShape or HistorySnapshot live here.
+ * Editor-only enums (Mode, ControlPointPosition, etc.) stay in the editor.
+ */
+declare enum SplineCurveType {
+    LINEAR = "linear",
+    QUADRATIC = "quadratic",
+    CUBIC = "cubic",
+    CATMULL_ROM = "catmull-rom",
+    ARC = "arc",
+    BASIS = "basis",
+    MIXED = "mixed"
+}
+declare enum SplinePointType {
+    SMOOTH = "smooth",
+    CORNER = "corner",
+    SYMMETRIC = "symmetric"
+}
+
+/**
+ * @svgsketch/core — Interfaces used by the document format.
+ *
+ * Only types referenced by SerializedShape or HistorySnapshot live here.
+ * Editor-only types (ShapeState, ControlPoint, ChartConfig, etc.) stay in the editor.
+ */
+
+interface Point {
+    x: number;
+    y: number;
+}
+interface Viewbox {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type FillType = 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'none';
+type StrokeType = 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'none';
+type GradientSpreadMethod = 'pad' | 'repeat' | 'reflect';
+type PatternType = 'stripes' | 'dots' | 'grid' | 'checkerboard' | 'diagonal' | 'crosshatch' | 'zigzag' | 'waves' | 'triangles' | 'hexagons' | 'diamonds' | 'circles' | 'bricks' | 'herringbone' | 'custom';
+interface GradientStop {
+    offset: number;
+    color: string;
+    opacity: number;
+}
+interface LinearGradient {
+    type: 'linear-gradient';
+    id: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    stops: GradientStop[];
+    spreadMethod: GradientSpreadMethod;
+    opacity: number;
+}
+interface RadialGradient {
+    type: 'radial-gradient';
+    id: string;
+    cx: number;
+    cy: number;
+    fx: number;
+    fy: number;
+    r: number;
+    ry: number;
+    rotation: number;
+    stops: GradientStop[];
+    spreadMethod: GradientSpreadMethod;
+    opacity: number;
+}
+/**
+ * Per-pattern-type tuneable parameters.
+ *
+ * All values are **ratios relative to the tile size** so they scale cleanly
+ * when the user drags the Scale slider.  Each preset pattern type uses only
+ * the subset of params that make sense for its geometry — the rest are
+ * ignored.  Omitted fields fall back to the built-in defaults inside
+ * `getPatternElements()`.
+ */
+interface PatternParams {
+    /** Line / stroke thickness ratio (0.02–0.5, default varies per type). */
+    strokeWidth?: number;
+    /** Dot / circle radius ratio (0.05–0.45, default 0.25). */
+    dotRadius?: number;
+    /** Wave / zigzag amplitude ratio (0.05–0.5, default 0.25). */
+    amplitude?: number;
+}
+/**
+ * Pattern fill definition.
+ *
+ * SVG 2 §14.3 — a pre-defined graphic object replicated at fixed intervals
+ * to tile an area.  When `svgContent` is present it is the single source of
+ * truth for rendering and is emitted directly inside the `<pattern>` element.
+ *
+ * Legacy fields (`patternType`, `color`, `backgroundColor`, `scale`,
+ * `rotation`) are kept for backward compatibility with existing documents
+ * and provide preset metadata for the UI.  For imported (custom) patterns
+ * they carry fallback values only.
+ */
+interface PatternFill {
+    type: 'pattern';
+    id: string;
+    /** Preset identifier, or `'custom'` for imported / user-provided patterns. */
+    patternType: PatternType;
+    /** Preset foreground colour, or dominant-colour fallback for custom. */
+    color: string;
+    /** Preset background colour. */
+    backgroundColor: string;
+    /** Preset scale multiplier (base tile size = 10 × scale). */
+    scale: number;
+    /** Preset rotation in degrees (written into `patternTransform`). */
+    rotation: number;
+    /** Fill-opacity applied to the painted area (0–1). */
+    opacity: number;
+    /** Per-preset tuneable geometry parameters (stroke width, dot radius …). */
+    patternParams?: PatternParams;
+    /**
+     * Serialised inner markup of the `<pattern>` tile.
+     * When present this is used **instead of** generating content from the
+     * preset helpers — it can contain arbitrary SVG (rects, paths, images …).
+     */
+    svgContent?: string;
+    /** Tile width in the coordinate system defined by `patternUnits`. */
+    width?: number;
+    /** Tile height in the coordinate system defined by `patternUnits`. */
+    height?: number;
+    /**
+     * Coordinate system for `x`, `y`, `width`, `height`.
+     * SVG 2 initial value: `objectBoundingBox`.
+     * SVGSketch presets default to `userSpaceOnUse` for simplicity.
+     */
+    patternUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    /**
+     * Coordinate system for the pattern tile contents.
+     * SVG 2 initial value: `userSpaceOnUse`.
+     * Has no effect when `viewBox` is specified.
+     */
+    patternContentUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    /** Full SVG `patternTransform` string (e.g. `"rotate(45) scale(2)"`). */
+    patternTransform?: string;
+    /** Optional `viewBox` attribute for the tile coordinate system. */
+    viewBox?: string;
+    /** Optional `preserveAspectRatio` attribute. */
+    preserveAspectRatio?: string;
+    /** Tile origin X offset (default 0). */
+    x?: number;
+    /** Tile origin Y offset (default 0). */
+    y?: number;
+    /** ID of the `CustomPatternDef` this fill was built from (if any). */
+    customPatternId?: string;
+}
+type GradientDefinition = LinearGradient | RadialGradient | PatternFill;
+/** Style overrides for a single rich-text segment. */
+interface RichTextSegmentStyle {
+    fontFamily?: string;
+    fontWeight?: string;
+    fontStyle?: string;
+    textDecoration?: {
+        underline?: boolean;
+        strikethrough?: boolean;
+        overline?: boolean;
+    };
+    textTransform?: string;
+    baselineShift?: string;
+    fontSize?: number;
+    fillColor?: string;
+}
+/** A single styled text segment within a rich-text line. */
+interface RichTextSegment {
+    text: string;
+    style: RichTextSegmentStyle;
+}
+/** A line of rich text containing styled segments. */
+interface RichTextLine {
+    segments: RichTextSegment[];
+}
+/**
+ * Rich text data for per-segment styling within a text shape.
+ * Each line contains independently styled segments.
+ */
+interface RichTextData {
+    lines: RichTextLine[];
+    baseStyle: RichTextSegmentStyle;
+    lineHeight: number;
+}
+/**
+ * A user-defined custom pattern stored in the document.
+ * Created by serialising selected shapes into a reusable pattern tile.
+ */
+interface CustomPatternDef {
+    /** Unique identifier for this pattern definition. */
+    id: string;
+    /** User-assigned name shown in the pattern picker. */
+    name: string;
+    /** Serialised inner SVG markup of the pattern tile. */
+    svgContent: string;
+    /** Tile width in userSpaceOnUse coordinates. */
+    width: number;
+    /** 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 BlurQuality = 'normal' | 'high';
+interface BaseFilter {
+    id: string;
+    type: FilterType;
+    enabled: boolean;
+}
+interface DropShadowFilter extends BaseFilter {
+    type: 'drop-shadow';
+    offsetX: number;
+    offsetY: number;
+    blurRadius: number;
+    spread: number;
+    color: string;
+    opacity: number;
+}
+interface InnerShadowFilter extends BaseFilter {
+    type: 'inner-shadow';
+    offsetX: number;
+    offsetY: number;
+    blurRadius: number;
+    choke: number;
+    color: string;
+    opacity: number;
+}
+interface GaussianBlurFilter extends BaseFilter {
+    type: 'gaussian-blur';
+    blurX: number;
+    blurY: number;
+    linked: boolean;
+    quality: BlurQuality;
+}
+interface MotionBlurFilter extends BaseFilter {
+    type: 'motion-blur';
+    distance: number;
+    angle: number;
+    quality: BlurQuality;
+}
+interface PointLightFilter extends BaseFilter {
+    type: 'point-light';
+    x: number;
+    y: number;
+    z: number;
+    color: string;
+    surfaceScale: number;
+    diffuseConstant: number;
+    specularConstant: number;
+    specularExponent: number;
+}
+interface SpotLightFilter extends BaseFilter {
+    type: 'spot-light';
+    x: number;
+    y: number;
+    z: number;
+    pointsAtX: number;
+    pointsAtY: number;
+    pointsAtZ: number;
+    coneAngle: number;
+    color: string;
+    surfaceScale: number;
+    specularConstant: number;
+    specularExponent: number;
+}
+type OutlinePosition = 'outside' | 'center' | 'inside';
+interface OutlineFilter extends BaseFilter {
+    type: 'outline';
+    width: number;
+    color: string;
+    opacity: number;
+    position: OutlinePosition;
+}
+interface SharpenFilter extends BaseFilter {
+    type: 'sharpen';
+    amount: number;
+}
+interface PixelateFilter extends BaseFilter {
+    type: 'pixelate';
+    blockSize: number;
+}
+type WarpType = 'turbulence' | 'fractalNoise';
+interface WarpFilter extends BaseFilter {
+    type: 'warp';
+    scale: number;
+    frequency: number;
+    octaves: number;
+    warpType: WarpType;
+}
+type MorphologyOperator = 'erode' | 'dilate';
+interface MorphologyFilter extends BaseFilter {
+    type: 'morphology';
+    operator: MorphologyOperator;
+    radiusX: number;
+    radiusY: number;
+    linked: boolean;
+}
+interface ContouringDiscreteFilter extends BaseFilter {
+    type: 'contouring-discrete';
+    levels: number;
+}
+interface ContouringTableFilter extends BaseFilter {
+    type: 'contouring-table';
+    levels: number;
+    contrast: number;
+}
+interface RoundEdgesFilter extends BaseFilter {
+    type: 'round-edges';
+    radius: number;
+}
+interface GrayscaleFilter extends BaseFilter {
+    type: 'grayscale';
+    amount: number;
+}
+interface ChannelPainterFilter extends BaseFilter {
+    type: 'channel-painter';
+    red: number;
+    green: number;
+    blue: number;
+}
+interface BrightnessFilter extends BaseFilter {
+    type: 'brightness';
+    amount: number;
+}
+interface ContrastFilter extends BaseFilter {
+    type: 'contrast';
+    amount: number;
+}
+interface OpacityFilter extends BaseFilter {
+    type: 'opacity';
+    amount: number;
+}
+interface InvertFilter extends BaseFilter {
+    type: 'invert';
+    amount: number;
+}
+interface HueRotateFilter extends BaseFilter {
+    type: 'hue-rotate';
+    angle: number;
+}
+interface SaturateFilter extends BaseFilter {
+    type: 'saturate';
+    amount: number;
+}
+interface BlackAndWhiteFilter extends BaseFilter {
+    type: 'black-and-white';
+    threshold: number;
+}
+interface SepiaFilter extends BaseFilter {
+    type: 'sepia';
+    amount: number;
+}
+interface DuotoneFilter extends BaseFilter {
+    type: 'duotone';
+    shadowColor: string;
+    highlightColor: string;
+}
+interface XrayFilter extends BaseFilter {
+    type: 'xray';
+    intensity: number;
+}
+interface NoiseFilter extends BaseFilter {
+    type: 'noise';
+    amount: number;
+    scale: number;
+}
+interface EmbossFilter extends BaseFilter {
+    type: 'emboss';
+    strength: number;
+    angle: number;
+}
+interface FilmGrainFilter extends BaseFilter {
+    type: 'film-grain';
+    amount: number;
+    size: number;
+}
+interface WatercolorFilter extends BaseFilter {
+    type: 'watercolor';
+    wetness: number;
+    turbulence: number;
+}
+interface GouacheFilter extends BaseFilter {
+    type: 'gouache';
+    thickness: number;
+    texture: number;
+}
+interface InkBlotFilter extends BaseFilter {
+    type: 'ink-blot';
+    spread: number;
+    edges: number;
+}
+interface CrumpledPlasticFilter extends BaseFilter {
+    type: 'crumpled-plastic';
+    wrinkles: number;
+    shine: number;
+}
+interface RiddledFilter extends BaseFilter {
+    type: 'riddled';
+    density: number;
+    size: number;
+}
+interface GlowFilter extends BaseFilter {
+    type: 'glow';
+    color: string;
+    radius: number;
+    intensity: number;
+}
+interface InnerGlowFilter extends BaseFilter {
+    type: 'inner-glow';
+    color: string;
+    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;
+type SegmentCurveType = 'LINEAR' | 'CUBIC' | 'QUADRATIC' | 'ARC';
+interface SplinePoint {
+    x: number;
+    y: number;
+    handleIn?: Point;
+    handleOut?: Point;
+    pointType: SplinePointType;
+    isSubpathStart?: boolean;
+    segmentType?: SegmentCurveType;
+    arcParams?: ArcParams$1;
+}
+interface ArcParams$1 {
+    rx: number;
+    ry: number;
+    rotation: number;
+    largeArc: boolean;
+    sweep: boolean;
+}
+type LinkTarget = '_self' | '_blank' | '_parent' | '_top';
+type AriaRole = '' | 'img' | 'button' | 'link' | 'presentation' | 'none' | 'graphics-document' | 'graphics-object' | 'graphics-symbol';
+interface ShapeMetadata {
+    name: string;
+    classes: string[];
+    title: string;
+    description: string;
+    role: AriaRole;
+    ariaLabel: string;
+    linkUrl: string;
+    linkTarget: LinkTarget;
+    customData: Record<string, 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;
+    description: string;
+    author: string;
+    keywords: string[];
+    license: LicenseType;
+    licenseUrl: string;
+    language: string;
+    customMetadata: Record<string, string>;
+}
+/** Type of a template variable's value. */
+type TemplateVariableType = 'string' | 'color' | 'number';
+/** A template variable definition stored in the document. */
+interface TemplateVariable {
+    /** Variable name (used in `{{name}}` placeholders). */
+    name: string;
+    /** The type of value this variable holds. */
+    type: TemplateVariableType;
+    /** Default value (used when no override is provided). */
+    defaultValue: string;
+    /** Human-readable label for UI display. */
+    label?: string;
+    /** Description / help text. */
+    description?: string;
+}
+interface Guide {
+    id: string;
+    orientation: 'horizontal' | 'vertical';
+    position: number;
+    controlPointOffset: number;
+    color?: string;
+    opacity?: number;
+}
+interface Measurement {
+    id: string;
+    type: 'distance' | 'angle';
+    points: Point[];
+    visible: boolean;
+    snapDivisions: number;
+    color?: string;
+    opacity?: number;
+}
+
+/**
+ * @svgsketch/core — Serialized document types.
+ *
+ * These types define the .svgs document format. SerializedShape and
+ * HistorySnapshot are the canonical data structures for persisting
+ * SVGSketch documents.
+ */
+
+interface SerializedShape {
+    id: string;
+    /** Shape type identifier. Built-in types: 'circle', 'rectangle', etc. Plugin shapes use custom ids. */
+    type: string;
+    state: {
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        radius?: number;
+        rx?: number;
+        ry?: number;
+        cornerRadius?: number;
+        fontSize?: number;
+        text?: string;
+        fontFamily?: string;
+        fontWeight?: string;
+        fontStyle?: string;
+        textDecoration?: {
+            underline?: boolean;
+            strikethrough?: boolean;
+            overline?: boolean;
+        };
+        textTransform?: string;
+        baselineShift?: string;
+        dominantBaseline?: string;
+        writingMode?: 'horizontal-tb' | 'vertical-rl' | 'vertical-lr';
+        textAnchor?: string;
+        letterSpacing?: number;
+        wordSpacing?: number;
+        lineHeight?: number;
+        inlineSize?: number;
+        overflowWrap?: 'normal' | 'break-word' | 'anywhere';
+        whiteSpace?: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces';
+        textDirection?: 'ltr' | 'rtl';
+        unicodeBidi?: 'normal' | 'embed' | 'bidi-override' | 'isolate' | 'isolate-override' | 'plaintext';
+        fontVariationSettings?: Record<string, number>;
+        charOffsets?: {
+            x: number;
+            y: number;
+            rotate: number;
+        }[];
+        richTextData?: RichTextData;
+        scaleX?: number;
+        scaleY?: number;
+        textX?: number;
+        textY?: number;
+        scaleAnchor?: Point | null;
+        rotation?: number;
+        skewX?: number;
+        skewY?: number;
+        customPivot?: Point | null;
+        fillColor?: string;
+        fillOpacity?: number;
+        borderColor?: string;
+        borderWidth?: number | string;
+        strokeOpacity?: number;
+        cx?: number;
+        cy?: number;
+        sides?: number;
+        arms?: number;
+        innerRadiusPercent?: number;
+        shiftAngle?: number;
+        armWidthPercent?: number;
+        teeth?: number;
+        toothDepthPercent?: number;
+        holeRadiusPercent?: number;
+        turns?: number;
+        thicknessPercent?: number;
+        direction?: number;
+        headWidthPercent?: number;
+        headLengthPercent?: number;
+        shaftWidthPercent?: number;
+        x1?: number;
+        y1?: number;
+        x2?: number;
+        y2?: number;
+        lineStyle?: 'solid' | 'dashed' | 'dotted' | 'custom';
+        dashLength?: number;
+        gapLength?: number;
+        dashOffset?: number;
+        /** Raw SVG stroke-dasharray for multi-value patterns. */
+        strokeDasharray?: string;
+        startEndpoint?: 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
+        endEndpoint?: 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
+        locked?: boolean;
+        visible?: boolean;
+        fillType?: FillType;
+        fillGradient?: LinearGradient | RadialGradient | PatternFill;
+        strokeType?: StrokeType;
+        strokeGradient?: LinearGradient | RadialGradient | PatternFill;
+        filters?: ShapeFilter[];
+        splinePoints?: SplinePoint[];
+        splineCurveType?: SplineCurveType;
+        splineClosed?: boolean;
+        splineTension?: number;
+        splineArcParams?: ArcParams$1[];
+        polylinePoints?: Point[];
+        polylineClosed?: boolean;
+        href?: string;
+        originalWidth?: number;
+        originalHeight?: number;
+        preserveAspectRatio?: boolean;
+        imageOpacity?: number;
+        shapeInsideRef?: string;
+        shapePadding?: number;
+        isTextPath?: boolean;
+        textPathPoints?: SplinePoint[];
+        textPathStartOffset?: number;
+        textPathSide?: 'left' | 'right';
+        fillRule?: 'nonzero' | 'evenodd';
+        strokeLinejoin?: 'miter' | 'round' | 'bevel';
+        strokeLinecap?: 'butt' | 'round' | 'square';
+        strokeMiterlimit?: number;
+        opacity?: number;
+        metadata?: Partial<ShapeMetadata>;
+        groupId?: string;
+        cssClipPath?: string;
+        cssMaskProperties?: Record<string, string>;
+        symbolId?: string;
+    };
+}
+type SerializedViewbox = Viewbox;
+/**
+ * Schema version for the HistorySnapshot format.
+ *
+ * IMPORTANT — Serialization compatibility rules:
+ *
+ * 1. NEVER rename an existing serialized property — add a new one alongside
+ *    the old and read both with a fallback (e.g. state.newName ?? state.oldName).
+ * 2. NEVER change a property's type — add a new property instead.
+ * 3. NEVER make a previously optional field required without providing a
+ *    default in the migration path.
+ * 4. NEVER remove a shape type — old documents referencing it would silently
+ *    lose those shapes.
+ * 5. When adding new optional properties, always handle their absence in
+ *    restoreFromSerialized with ?? or if-guards.
+ *
+ * When you need a breaking change:
+ *   a. Bump CURRENT_SCHEMA_VERSION below.
+ *   b. Add a migration function in the migrations module that transforms
+ *      (version - 1) snapshots into the new format.
+ *   c. Register it in the migrateSnapshot() chain.
+ */
+declare const CURRENT_SCHEMA_VERSION = 1;
+interface HistorySnapshot {
+    /**
+     * Schema version — written on save, read on load to trigger migrations.
+     * If absent, the snapshot predates versioning and is treated as version 1.
+     */
+    schemaVersion?: number;
+    shapes: SerializedShape[];
+    viewboxes: SerializedViewbox[];
+    guides?: Guide[];
+    measurements?: Measurement[];
+    /** Group structure: array of group IDs with their parent group ID (null for top-level) */
+    groups?: SerializedGroup[];
+    /** Clip/mask group structure for undo/redo support */
+    clipMaskGroups?: SerializedClipMaskGroup[];
+    /** Document-level metadata (title, description, author, etc.) */
+    documentMetadata?: DocumentMetadata;
+    /** Template variable definitions with defaults. */
+    templateVariables?: TemplateVariable[];
+    /** Animation timeline (tracks, keyframes, easing). */
+    animationTimeline?: SerializedAnimationTimeline;
+    /** User-defined custom patterns stored in the document. */
+    customPatterns?: CustomPatternDef[];
+    /** Symbol definitions (reusable component templates). */
+    symbols?: SerializedSymbolDef[];
+}
+/**
+ * A reusable symbol definition. Contains the shapes that make up the
+ * symbol template, plus metadata for the symbols panel.
+ */
+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;
+    /** The shapes that make up this symbol's content. */
+    shapes: SerializedShape[];
+    /** Groups within the symbol. */
+    groups?: SerializedGroup[];
+    /** Base64 data-URI thumbnail for the symbols panel. */
+    thumbnail?: string;
+}
+interface SerializedGroup {
+    id: string;
+    parentId: string | null;
+    /** CSS transform-origin value (e.g. "50px 50px") for group animations */
+    transformOrigin?: string;
+    /**
+     * Zero-based position of this group among its parent container's
+     * children (including both sibling groups and sibling shape nodes).
+     * Used during restoration to correctly interleave groups and shapes
+     * so that SVG document order (painting order) is preserved.
+     */
+    siblingIndex?: number;
+}
+/** 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 — 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()
+ */
+
+/**
+ * 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.
+ *
+ * @param snapshot - The snapshot to migrate (not mutated; a new object is returned)
+ * @returns The migrated snapshot at CURRENT_SCHEMA_VERSION
+ */
+declare function migrateSnapshot(snapshot: HistorySnapshot): HistorySnapshot;
+
+/**
+ * @svgsketch/core — Document validation.
+ *
+ * Validates the structural correctness of a HistorySnapshot (the .svgs
+ * document format). This is NOT JSON Schema — it performs semantic
+ * validation that static types cannot express:
+ *   - required fields present & correct types
+ *   - shape IDs are unique
+ *   - group references point to existing shapes
+ *   - viewbox dimensions are positive
+ *   - enum values are valid
+ */
+/** A single validation problem. */
+interface ValidationError {
+    /** Dot-path to the problematic value, e.g. "shapes[2].state.width" */
+    path: string;
+    /** Human-readable description */
+    message: string;
+    /** 'error' = invalid document, 'warning' = loadable but suspicious */
+    severity: 'error' | 'warning';
+}
+/** Result returned by validateSnapshot(). */
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+/**
+ * Validate a HistorySnapshot for structural and semantic correctness.
+ *
+ * @param snapshot - The document to validate
+ * @returns ValidationResult with `valid` flag plus error/warning lists
+ */
+declare function validateSnapshot(snapshot: unknown): ValidationResult;
+
+/**
+ * @svgsketch/core — Document factory helpers.
+ *
+ * Pure functions for creating HistorySnapshot documents and adding
+ * shapes programmatically. These are the building blocks for the SDK.
+ */
+
+/**
+ * Generate a unique ID suitable for shapes, viewboxes, and guides.
+ * Uses crypto.randomUUID when available, falls back to a timestamp-based ID.
+ */
+declare function generateId(): string;
+/** Options for createDocument(). All fields are optional. */
+interface CreateDocumentOptions {
+    /** Shapes to include. Default: [] */
+    shapes?: SerializedShape[];
+    /** Viewboxes to include. Default: [] */
+    viewboxes?: SerializedViewbox[];
+    /** Document metadata (title, author, etc.) */
+    metadata?: Partial<DocumentMetadata>;
+}
+/**
+ * Create a new, valid HistorySnapshot.
+ *
+ * @param options - Optional shapes, viewboxes, and metadata
+ * @returns A well-formed HistorySnapshot at the current schema version
+ */
+declare function createDocument(options?: CreateDocumentOptions): HistorySnapshot;
+/** Minimal options for creating a shape. */
+interface CreateShapeOptions {
+    /** Shape type (required) */
+    type: SerializedShape['type'];
+    /** Optional ID. Auto-generated if omitted. */
+    id?: string;
+    /** Position and dimensions */
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    radius?: number;
+    /** Fill */
+    fillColor?: string;
+    fillOpacity?: number;
+    /** Stroke */
+    borderColor?: string;
+    borderWidth?: number;
+    strokeOpacity?: number;
+    /** Transform */
+    rotation?: number;
+    /** Text (for text shapes) */
+    text?: string;
+    fontSize?: number;
+    /** Any additional state properties */
+    [key: string]: unknown;
+}
+/**
+ * Create a SerializedShape with sensible defaults.
+ *
+ * @param options - Shape type plus optional position/style/text
+ * @returns A valid SerializedShape ready to add to a document
+ */
+declare function createShape(options: CreateShapeOptions): SerializedShape;
+/**
+ * Create a viewbox (artboard).
+ *
+ * @param x - X position
+ * @param y - Y position
+ * @param width - Width (must be positive)
+ * @param height - Height (must be positive)
+ * @param id - Optional ID. Auto-generated if omitted.
+ * @returns A valid SerializedViewbox
+ */
+declare function createViewbox(x: number, y: number, width: number, height: number, id?: string): SerializedViewbox;
+
+/**
+ * @svgsketch/core — Git-friendly .svgs serializer.
+ *
+ * Converts a HistorySnapshot to a deterministic, human-readable JSON
+ * string optimized for version-control diffs. The output:
+ *
+ *   - Sorts top-level sections in a fixed order (schemaVersion, documentMetadata,
+ *     viewboxes, guides, measurements, groups, clipMaskGroups, shapes)
+ *   - Sorts shapes, viewboxes, groups, guides by `id`
+ *   - 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.
+ */
+
+/** Options for stringifyDocument(). */
+interface StringifyOptions {
+    /** Number of spaces per indentation level. Default: 2 */
+    indent?: number;
+    /** Include a trailing newline. Default: true */
+    trailingNewline?: boolean;
+    /** Validate before serializing; throws on invalid docs. Default: false */
+    validate?: boolean;
+}
+/**
+ * Serialize a HistorySnapshot to a deterministic, git-friendly JSON string.
+ *
+ * @param snapshot - The document to serialize
+ * @param options - Formatting options
+ * @returns A formatted JSON string suitable for `.svgs` files
+ * @throws If `options.validate` is true and the snapshot is invalid
+ */
+declare function stringifyDocument(snapshot: HistorySnapshot, options?: StringifyOptions): string;
+/** Options for parseDocument(). */
+interface ParseOptions {
+    /** Validate after parsing; throws on invalid docs. Default: true */
+    validate?: boolean;
+    /** Run migrations to bring old docs to current schema. Default: true */
+    migrate?: boolean;
+}
+/**
+ * Parse a `.svgs` JSON string into a HistorySnapshot.
+ *
+ * @param input - The JSON string to parse
+ * @param options - Parsing options
+ * @returns The parsed (and optionally migrated/validated) HistorySnapshot
+ * @throws On invalid JSON or failed validation
+ */
+declare function parseDocument(input: string, options?: ParseOptions): HistorySnapshot;
+
+/**
+ * @svgsketch/core — Template variable engine.
+ *
+ * Substitutes `{{variableName}}` placeholders in a HistorySnapshot.
+ * Variables can appear in:
+ *   - Text content (`state.text`)
+ *   - Color values (`state.fillColor`, `state.borderColor`)
+ *   - Numeric values (font size, dimensions, etc.)
+ *   - Any string property in `state`
+ *
+ * The engine deep-clones the snapshot before substitution so the
+ * original is never mutated.
+ *
+ * @example
+ * ```ts
+ * const result = substituteVariables(snapshot, {
+ *   primaryColor: '#e74c3c',
+ *   title: 'Hello World',
+ *   radius: '50',
+ * });
+ * ```
+ */
+
+/** A map of variable name → value for substitution. */
+type VariableMap = Record<string, string | number>;
+/**
+ * The result of extracting variable definitions from a document.
+ */
+interface ExtractedVariables {
+    /** Defined variables with their defaults and types. */
+    defined: TemplateVariable[];
+    /**
+     * Variable names found in templates (`{{name}}`) that have
+     * no matching definition.
+     */
+    undeclared: string[];
+}
+/**
+ * Substitute `{{var}}` placeholders in a string.
+ * Returns the original string if it contains no placeholders.
+ */
+declare function substituteString(template: string, vars: VariableMap): string;
+/**
+ * Substitute template variables throughout a HistorySnapshot.
+ *
+ * Creates a deep clone, then walks every shape's `state` and replaces
+ * `{{varName}}` in string properties. If a variable resolves to a
+ * number and the target property is numeric, it's coerced.
+ *
+ * Variable values are resolved in this order:
+ *   1. Explicit `vars` argument (highest priority)
+ *   2. Default values from `snapshot.templateVariables`
+ *
+ * @param snapshot - The source snapshot (not mutated)
+ * @param vars     - Variable values to substitute
+ * @returns A new HistorySnapshot with substitutions applied
+ */
+declare function substituteVariables(snapshot: HistorySnapshot, vars?: VariableMap): HistorySnapshot;
+/**
+ * Extract variable references from a snapshot.
+ * Returns defined variables and any undeclared references found in templates.
+ */
+declare function extractVariables(snapshot: HistorySnapshot): ExtractedVariables;
+/**
+ * Parse a `key=value` string (from CLI `--var` flags) into a VariableMap.
+ *
+ * @example
+ * ```ts
+ * parseVariableArgs(['primaryColor=#e74c3c', 'title=Hello World', 'radius=50'])
+ * // → { primaryColor: '#e74c3c', title: 'Hello World', radius: '50' }
+ * ```
+ */
+declare function parseVariableArgs(args: string[]): VariableMap;
+
+/**
+ * Document-level SVG renderer.
+ *
+ * Takes a {@link HistorySnapshot} (from a .svgs file) and produces a
+ * standalone SVG string that can be written to disk or piped to a
+ * rasterizer.
+ */
+
+interface RenderOptions {
+    /** Explicit width; defaults to first viewbox width or 800. */
+    width?: number;
+    /** Explicit height; defaults to first viewbox height or 600. */
+    height?: number;
+    /** Custom viewBox string, e.g. "0 0 800 600". */
+    viewBox?: string;
+    /** Whether to include the XML declaration. Default true. */
+    xmlDeclaration?: boolean;
+    /** Background color. If set, a <rect> is drawn behind all shapes. */
+    backgroundColor?: string;
+    /** Pretty-print with indentation. Default true. */
+    indent?: boolean;
+    /** CSS class to add to the root <svg>. */
+    className?: string;
+}
+/**
+ * Render a snapshot to a standalone SVG string.
+ *
+ * @param snapshot - The deserialized document snapshot
+ * @param options  - Optional rendering overrides
+ * @returns A complete SVG document as a string
+ */
+declare function renderToSvg(snapshot: HistorySnapshot, options?: RenderOptions): string;
+
+/**
+ * Filter renderers — convert ShapeFilter[] → SVG `<filter>` definition strings.
+ *
+ * Each filter type maps to one or more SVG filter primitives (feGaussianBlur,
+ * feDropShadow, feColorMatrix, etc.). The logic mirrors the editor's
+ * FilterManager (apps/editor/src/canvas/filter-manager.ts) but produces
+ * strings instead of D3 DOM nodes.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Render SVG filter primitive string(s) for a single filter.
+ *
+ * This is the canonical implementation used by both the core string renderer
+ * and the editor's DOM-based filter manager (via insertAdjacentHTML).
+ *
+ * @param filter - The filter definition
+ * @param input - Input result name (e.g., 'SourceGraphic' or previous result)
+ * @param output - Output result name for this filter
+ * @param shapeCenter - Optional shape center for light positioning
+ *   (point-light, spot-light). When provided, light coordinates are offset
+ *   relative to the shape center. When omitted, coordinates are absolute.
+ * @returns SVG string of filter primitives
+ */
+declare function renderFilterPrimitivesForType(filter: ShapeFilter, input: string, output: string, shapeCenter?: {
+    x: number;
+    y: number;
+}): string;
+/**
+ * Generate `<filter>` definition strings for all shapes that have filters.
+ *
+ * @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.
+ */
+declare function filterAttr(shapeId: string, filters: ShapeFilter[] | undefined): string;
+
+/**
+ * Shape renderers — convert SerializedShape → SVG element string.
+ *
+ * Each renderer produces one SVG element (circle, rect, path, text, etc.)
+ * as a string. The caller wraps them in <svg> with <defs>.
+ */
+
+declare function renderCircle(shape: SerializedShape): string;
+declare function renderEllipse(shape: SerializedShape): string;
+declare function renderRectangle(shape: SerializedShape): string;
+declare function renderLine(shape: SerializedShape): string;
+declare function renderText(shape: SerializedShape): string;
+declare function renderSpline(shape: SerializedShape): string;
+declare function renderPolyline(shape: SerializedShape): string;
+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;
+
+/**
+ * Pure geometry functions for computing shape vertices and paths.
+ *
+ * These are headless — no DOM required. They take numeric parameters
+ * and return vertex arrays or SVG path-data strings.
+ */
+
+/**
+ * Compute equally-spaced vertices around a circle (for triangle, ngon).
+ * Path is centered at origin; caller applies translate(cx, cy).
+ */
+declare function computePolygonVertices(sides: number, radius: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute star vertices with alternating outer/inner radii.
+ */
+declare function computeStarVertices(arms: number, radius: number, innerRadiusPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute cross vertices (12 points forming a plus shape).
+ */
+declare function computeCrossVertices(radius: number, armWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute arrow vertices (7 points forming an arrow).
+ */
+declare function computeArrowVertices(radius: number, headWidthPercent: number, headLengthPercent: number, shaftWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Convert an array of vertices to an SVG path string.
+ * Supports optional rounded corners via quadratic Bézier.
+ */
+declare function verticesToPath(vertices: Point[], cornerRadius?: number, radius?: number): string;
+/**
+ * Generate SVG path for a ring (two concentric circles).
+ */
+declare function computeRingPath(radius: number, innerRadiusPercent: number, fillRule?: 'nonzero' | 'evenodd'): string;
+/**
+ * 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.
+ */
+declare function computeGearPath(teeth: number, radius: number, toothDepthPercent: number, cornerRadius?: number, holeRadiusPercent?: number, fillRule?: 'nonzero' | 'evenodd', shiftAngleDeg?: number): string;
+type CornerShape = 'round' | 'bevel' | 'notch' | 'scoop';
+/**
+ * Generate SVG path for a rectangle with per-corner radius and shape.
+ * Returns null if all corners are simple (use <rect> instead).
+ */
+declare function computeRectanglePath(x: number, y: number, width: number, height: number, cornerRadius: number, cornerShape?: CornerShape, cornerMode?: 'uniform' | 'non-uniform', perCorner?: {
+    radiusTL?: number;
+    radiusTR?: number;
+    radiusBR?: number;
+    radiusBL?: number;
+    shapeTL?: CornerShape;
+    shapeTR?: CornerShape;
+    shapeBR?: CornerShape;
+    shapeBL?: CornerShape;
+}): string | null;
+interface SplinePointInput {
+    x: number;
+    y: number;
+    handleIn?: Point;
+    handleOut?: Point;
+    pointType?: string;
+    isSubpathStart?: boolean;
+    segmentType?: string;
+    arcParams?: ArcParams;
+}
+interface ArcParams {
+    rx: number;
+    ry: number;
+    rotation: number;
+    largeArc: boolean;
+    sweep: boolean;
+}
+/**
+ * Compute SVG path data from spline points.
+ */
+declare function computeSplinePath(points: SplinePointInput[], curveType: string, closed?: boolean, tension?: number, arcParams?: ArcParams[]): string;
+/**
+ * Compute a dash-array string for a given line style.
+ *
+ * @returns A `stroke-dasharray` value like `"8 4"`, or `null` for solid lines.
+ */
+declare function computeDashArray(style: string, dashLength: number, gapLength: number): string | null;
+
+/**
+ * Shared pattern geometry descriptors.
+ *
+ * Both the editor (D3 DOM) and the headless renderer (string concatenation)
+ * consume these declarative element descriptions, eliminating code duplication.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A declarative description of an SVG element within a pattern tile.
+ */
+interface PatternElement {
+    tag: 'rect' | 'circle' | 'path';
+    attrs: Record<string, string | number>;
+}
+/**
+ * Return the foreground geometry elements for a given pattern type.
+ *
+ * @param type   - One of the 14 built-in pattern type names.
+ * @param size   - Tile size in user-space units.
+ * @param color  - Foreground CSS colour string.
+ * @param params - Optional per-pattern tuneable parameters (ratios relative to size).
+ * @returns An array of element descriptors (empty for unknown types).
+ */
+declare function getPatternElements(type: string, size: number, color: string, params?: PatternParams): PatternElement[];
+/**
+ * Result of generating pattern SVG content from a preset.
+ */
+interface PatternSvgContentResult {
+    /** Serialised SVG markup for the pattern tile (goes inside `<pattern>`). */
+    svgContent: string;
+    /** Tile width in user-space units. */
+    width: number;
+    /** Tile height in user-space units. */
+    height: number;
+}
+/**
+ * Generate the full inner SVG markup for a preset pattern tile.
+ *
+ * This produces the exact content that goes inside a `<pattern>` element:
+ * a background rect followed by the foreground geometry from
+ * {@link getPatternElements}.
+ *
+ * @param patternType      - One of the 14 built-in pattern type names.
+ * @param scale            - Scale multiplier (base tile = 10 × scale).
+ * @param color            - Foreground CSS colour string.
+ * @param backgroundColor  - Background CSS colour string.
+ * @param params           - Optional per-pattern tuneable parameters.
+ * @returns Object with `svgContent`, `width`, and `height`.
+ */
+declare function generatePatternSvgContent(patternType: string, scale: number, color: string, backgroundColor: string, params?: PatternParams): PatternSvgContentResult;
+
+/**
+ * Shared marker descriptors for line endpoints.
+ *
+ * Returns declarative descriptions of SVG `<marker>` definitions.
+ * Consumed by both the core string renderer and the editor's D3 DOM builder.
+ *
+ * @packageDocumentation
+ */
+interface MarkerDescriptor {
+    /** Marker element id (e.g., 'line-marker-arrow'). */
+    id: string;
+    /** Reference point X for the marker tip. */
+    refX: number;
+    /** Reference point Y for the marker center. */
+    refY: number;
+    /** The child shape element inside the marker. */
+    element: {
+        tag: string;
+        attrs: Record<string, string | number>;
+    };
+}
+/** All markers share this viewBox. */
+declare const MARKER_VIEWBOX = "0 0 10 10";
+declare const MARKER_WIDTH = 6;
+declare const MARKER_HEIGHT = 6;
+/**
+ * Return the canonical marker descriptors for all line endpoint types.
+ *
+ * All markers use `viewBox="0 0 10 10"`, `markerWidth=6`, `markerHeight=6`,
+ * `markerUnits="strokeWidth"`, and `orient="auto-start-reverse"`.
+ */
+declare function getMarkerDescriptors(): MarkerDescriptor[];
+
+/**
+ * SMIL animation renderer — converts SerializedAnimationTimeline
+ * data into inline SVG animation elements.
+ *
+ * Produces:
+ *   - `<animate>` for numeric and color properties
+ *   - `<animateTransform>` for rotation, skewX, skewY
+ *   - `<animateMotion>` for path-based motion
+ *
+ * The output is a map from shape ID → array of SVG element strings
+ * so the main renderer can inject them as children of each shape element.
+ */
+
+/**
+ * Render animation tracks to a map of shape ID → SMIL element strings.
+ *
+ * The caller injects these strings as children of the corresponding
+ * SVG shape elements.
+ *
+ * @param timeline - The serialized animation timeline
+ * @returns Map from shape ID to an array of SVG animation element strings
+ */
+declare function renderAnimationElements(timeline: SerializedAnimationTimeline): Map<string, string[]>;
+
+/**
+ * Code generation dispatcher — routes to format-specific generators.
+ */
+
+/** Supported code output formats. */
+type CodeFormat = 'svg' | 'react' | 'vue' | 'd3' | 'css';
+/** Options for code generation. */
+interface CodegenOptions {
+    /** Target code format. */
+    format: CodeFormat;
+    /** Component/function name (used by React, Vue, D3). Defaults to 'SvgComponent'. */
+    componentName?: string;
+    /** Whether to include the XML declaration for SVG format. Default false. */
+    xmlDeclaration?: boolean;
+    /** Canvas width. Defaults to first viewbox width or 800. */
+    width?: number;
+    /** Canvas height. Defaults to first viewbox height or 600. */
+    height?: number;
+    /** Whether to use TypeScript syntax (React/D3). Default false. */
+    typescript?: boolean;
+    /** Indent string. Default '  ' (2 spaces). */
+    indent?: string;
+}
+/**
+ * Generate code from a snapshot or array of shapes.
+ *
+ * @param input  - A HistorySnapshot or an array of SerializedShape
+ * @param options - Code generation options
+ * @returns Generated code as a string
+ */
+declare function generateCode(input: HistorySnapshot | SerializedShape[], options: CodegenOptions): string;
+
+/**
+ * Shared helpers for code generators.
+ */
+
+/** Escape special XML characters. */
+declare function escXml(value: string): string;
+
+/**
+ * Raw SVG code generator.
+ *
+ * Produces a standalone SVG string using the headless renderer.
+ * This is the simplest format — it re-uses renderToSvg directly.
+ */
+
+/**
+ * Generate raw SVG markup from a snapshot.
+ */
+declare function generateSvgCode(snapshot: HistorySnapshot, options: CodegenOptions): string;
+
+/**
+ * React/JSX code generator.
+ *
+ * Produces a functional React component that renders the shapes as JSX.
+ * Converts SVG attributes to JSX-compatible camelCase (stroke-width → strokeWidth).
+ */
+
+/**
+ * Generate a React functional component from a snapshot.
+ */
+declare function generateReactCode(snapshot: HistorySnapshot, options: CodegenOptions): string;
+
+/**
+ * Vue SFC code generator.
+ *
+ * Produces a Vue Single File Component (SFC) with a <template> containing
+ * the SVG and a <script setup> block.
+ */
+
+/**
+ * Generate a Vue SFC from a snapshot.
+ */
+declare function generateVueCode(snapshot: HistorySnapshot, options: CodegenOptions): string;
+
+/**
+ * D3.js code generator.
+ *
+ * Produces a JavaScript/TypeScript function that uses D3 selections to
+ * programmatically build the SVG DOM.
+ */
+
+/**
+ * Generate D3.js code from a snapshot.
+ */
+declare function generateD3Code(snapshot: HistorySnapshot, options: CodegenOptions): string;
+
+/**
+ * CSS code generator.
+ *
+ * Produces SVG with inline classes plus a companion CSS block.
+ * Extracts fill, stroke, opacity, and transform styles into CSS classes.
+ */
+
+/**
+ * Generate CSS + SVG markup from a snapshot.
+ *
+ * Output format:
+ * ```
+ * <style>
+ *   .circle-1 { fill: #ff0000; stroke: #000; }
+ * </style>
+ * <svg ...>
+ *   <circle class="circle-1" cx="100" cy="100" r="50"/>
+ * </svg>
+ * ```
+ */
+declare function generateCssCode(snapshot: HistorySnapshot, options: CodegenOptions): string;
+
+/**
+ * Style builder helpers — fluent constructors for gradients and patterns.
+ *
+ * @example
+ * ```ts
+ * import { linearGradient, radialGradient, pattern } from '@svgsketch/core';
+ *
+ * const sunset = linearGradient(0, 0, 0, 1)
+ *   .stop(0, '#ff6b6b')
+ *   .stop(0.5, '#ffa726')
+ *   .stop(1, '#ffee58');
+ *
+ * const glow = radialGradient()
+ *   .center(0.5, 0.5)
+ *   .radius(0.5)
+ *   .stop(0, '#ffffff')
+ *   .stop(1, '#000000');
+ *
+ * const stripes = pattern('stripes', '#333', '#fff');
+ * ```
+ */
+
+declare class LinearGradientBuilder {
+    private _x1;
+    private _y1;
+    private _x2;
+    private _y2;
+    private _stops;
+    private _spreadMethod;
+    private _opacity;
+    private _id;
+    constructor(x1?: number, y1?: number, x2?: number, y2?: number);
+    /** Add a color stop. Offset is 0–1. */
+    stop(offset: number, color: string, opacity?: number): this;
+    /** Set the gradient direction. Values are 0–1 fractions. */
+    direction(x1: number, y1: number, x2: number, y2: number): this;
+    /** Set the spread method. */
+    spread(method: GradientSpreadMethod): this;
+    /** Set the overall gradient opacity. */
+    opacity(value: number): this;
+    /** Build the gradient definition object. */
+    build(): LinearGradient;
+}
+declare class RadialGradientBuilder {
+    private _cx;
+    private _cy;
+    private _fx;
+    private _fy;
+    private _r;
+    private _ry;
+    private _rotation;
+    private _stops;
+    private _spreadMethod;
+    private _opacity;
+    private _id;
+    constructor();
+    /** Set the center point (0–1). */
+    center(cx: number, cy: number): this;
+    /** Set the focal point (0–1). */
+    focus(fx: number, fy: number): this;
+    /** Set the radius (0–1). */
+    radius(r: number, ry?: number): this;
+    /** Set the rotation in degrees. */
+    rotation(degrees: number): this;
+    /** Add a color stop. Offset is 0–1. */
+    stop(offset: number, color: string, opacity?: number): this;
+    /** Set the spread method. */
+    spread(method: GradientSpreadMethod): this;
+    /** Set the overall gradient opacity. */
+    opacity(value: number): this;
+    /** Build the gradient definition object. */
+    build(): RadialGradient;
+}
+declare class PatternBuilder {
+    private _patternType;
+    private _color;
+    private _backgroundColor;
+    private _scale;
+    private _rotation;
+    private _opacity;
+    private _patternParams?;
+    private _id;
+    private _svgContent?;
+    private _width?;
+    private _height?;
+    private _patternUnits?;
+    private _patternContentUnits?;
+    private _patternTransform?;
+    private _viewBox?;
+    private _preserveAspectRatio?;
+    private _x?;
+    private _y?;
+    private _customPatternId?;
+    constructor(patternType?: PatternType, color?: string, backgroundColor?: string);
+    /** Set the pattern scale. */
+    scale(value: number): this;
+    /** Set the pattern rotation in degrees. */
+    rotation(degrees: number): this;
+    /** Set the overall pattern opacity. */
+    opacity(value: number): this;
+    /** Set per-pattern tuneable parameters (strokeWidth, dotRadius, amplitude). */
+    params(value: PatternParams): this;
+    /** Set custom SVG content for the pattern tile (bypasses preset generation). */
+    svgContent(content: string): this;
+    /** Set the pattern tile size. */
+    size(width: number, height: number): this;
+    /** Set the coordinate system for pattern bounds. */
+    patternUnits(value: 'userSpaceOnUse' | 'objectBoundingBox'): this;
+    /** Set the coordinate system for pattern tile contents. */
+    patternContentUnits(value: 'userSpaceOnUse' | 'objectBoundingBox'): this;
+    /** Set the pattern transform string (e.g. `"rotate(45) scale(2)"`). */
+    patternTransform(value: string): this;
+    /** Set the viewBox for the pattern tile coordinate system. */
+    viewBox(value: string): this;
+    /** Set the preserveAspectRatio attribute. */
+    preserveAspectRatio(value: string): this;
+    /** Set the tile origin offset. */
+    position(x: number, y: number): this;
+    /** Link this fill to a document-level custom pattern definition. */
+    customPatternId(id: string): this;
+    /** Build the pattern fill object. */
+    build(): PatternFill;
+}
+/**
+ * Create a linear gradient builder.
+ *
+ * @param x1 - Start X (0–1). Default 0.
+ * @param y1 - Start Y (0–1). Default 0.
+ * @param x2 - End X (0–1). Default 1.
+ * @param y2 - End Y (0–1). Default 0.
+ */
+declare function linearGradient(x1?: number, y1?: number, x2?: number, y2?: number): LinearGradientBuilder;
+/**
+ * Create a radial gradient builder.
+ */
+declare function radialGradient(): RadialGradientBuilder;
+/**
+ * Create a pattern fill builder.
+ *
+ * @param patternType - Pattern type (e.g. 'stripes', 'dots', 'grid').
+ * @param color - Foreground color. Default '#000000'.
+ * @param backgroundColor - Background color. Default '#ffffff'.
+ */
+declare function pattern(patternType?: PatternType, color?: string, backgroundColor?: string): PatternBuilder;
+
+/**
+ * Shape builder classes — fluent API for constructing shapes.
+ *
+ * Each class corresponds to one of the 17 supported shape types.
+ * All builders extend `ShapeBuilder` which provides common styling
+ * and transform methods that return `this` for chaining.
+ *
+ * @example
+ * ```ts
+ * import { Circle, Rectangle, Star } from '@svgsketch/core';
+ *
+ * const c = new Circle(100, 200, 50)
+ *   .fill('#3498db')
+ *   .stroke('#2980b9', 3)
+ *   .opacity(0.9);
+ *
+ * const r = new Rectangle(10, 20, 200, 100)
+ *   .fill('#e74c3c')
+ *   .cornerRadius(12);
+ *
+ * const s = new Star(300, 300, 80)
+ *   .arms(6)
+ *   .innerRadius(40)
+ *   .fill('#f1c40f');
+ * ```
+ */
+
+type LineStyle = 'solid' | 'dashed' | 'dotted' | 'custom';
+type EndpointStyle = 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
+type FontWeight = 'normal' | 'bold' | 'lighter' | 'bolder' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
+type FontStyle = 'normal' | 'italic' | 'oblique';
+type TextTransform = 'none' | 'uppercase' | 'lowercase' | 'capitalize';
+/**
+ * Abstract shape builder with shared styling, transform, and metadata methods.
+ * All methods return `this` for chaining.
+ */
+declare abstract class ShapeBuilder<T extends ShapeBuilder<T>> {
+    protected _id: string;
+    protected _type: SerializedShape['type'];
+    protected _state: Record<string, unknown>;
+    constructor(type: SerializedShape['type'], id?: string);
+    /** Set the shape ID. */
+    id(value: string): T;
+    /** Lock the shape (prevent editing). */
+    locked(value?: boolean): T;
+    /** Set visibility. */
+    visible(value?: boolean): T;
+    /** Set a solid fill color. */
+    fill(color: string, opacity?: number): T;
+    /** Set fill to none (transparent). */
+    noFill(): T;
+    /** Set a gradient fill (linear or radial). */
+    fillGradient(gradient: LinearGradientBuilder | RadialGradientBuilder | LinearGradient | RadialGradient): T;
+    /** Set a pattern fill. */
+    fillPattern(patternOrBuilder: PatternBuilder | PatternFill): T;
+    /** Set the fill opacity (0–1). */
+    fillOpacity(value: number): T;
+    /** Set the fill rule. */
+    fillRule(rule: 'nonzero' | 'evenodd'): T;
+    /** Set the stroke color and optional width. */
+    stroke(color: string, width?: number): T;
+    /** Set stroke to none. */
+    noStroke(): T;
+    /** Set the stroke width. */
+    strokeWidth(value: number): T;
+    /** Set the stroke opacity (0–1). */
+    strokeOpacity(value: number): T;
+    /** Set a gradient stroke. */
+    strokeGradient(gradient: LinearGradientBuilder | RadialGradientBuilder | LinearGradient | RadialGradient): T;
+    /** Set a pattern stroke. */
+    strokePattern(patternOrBuilder: PatternBuilder | PatternFill): T;
+    /** Set the stroke line join style. */
+    strokeLinejoin(value: 'miter' | 'round' | 'bevel'): T;
+    /** Set the stroke line cap style. */
+    strokeLinecap(value: 'butt' | 'round' | 'square'): T;
+    /** Set the stroke miter limit. */
+    strokeMiterlimit(value: number): T;
+    /** Set the stroke dash offset. */
+    dashOffset(value: number): T;
+    /** Set a raw SVG stroke-dasharray string for complex dash patterns. */
+    strokeDasharray(value: string): T;
+    /** Set the line/dash style. */
+    dash(style: LineStyle, dashLength?: number, gapLength?: number): T;
+    /** Set the overall opacity (0–1). */
+    opacity(value: number): T;
+    /** Set the rotation in degrees. */
+    rotate(degrees: number): T;
+    /** Set the skew. */
+    skew(x: number, y: number): T;
+    /** Set the scale. */
+    scale(x: number, y?: number): T;
+    /** Set a custom pivot point for transforms. */
+    pivot(x: number, y: number): T;
+    /** Add one or more filters to the shape. */
+    filter(...filters: ShapeFilter[]): T;
+    /** Add a drop shadow filter. */
+    dropShadow(options?: {
+        offsetX?: number;
+        offsetY?: number;
+        blurRadius?: number;
+        spread?: number;
+        color?: string;
+        opacity?: number;
+    }): T;
+    /** Add an inner shadow filter. */
+    innerShadow(options?: {
+        offsetX?: number;
+        offsetY?: number;
+        blurRadius?: number;
+        choke?: number;
+        color?: string;
+        opacity?: number;
+    }): T;
+    /** Add a Gaussian blur filter. */
+    blur(radiusOrX?: number, radiusY?: number, options?: {
+        quality?: BlurQuality;
+    }): T;
+    /** Add an outer glow filter. */
+    glow(options?: {
+        color?: string;
+        radius?: number;
+        intensity?: number;
+    }): T;
+    /** Add an inner glow filter. */
+    innerGlow(options?: {
+        color?: string;
+        radius?: number;
+        intensity?: number;
+    }): T;
+    /** Add a grayscale filter. */
+    grayscale(amount?: number): T;
+    /** Add a sepia filter. */
+    sepia(amount?: number): T;
+    /** Add an outline filter. */
+    outline(options?: {
+        width?: number;
+        color?: string;
+        opacity?: number;
+        position?: OutlinePosition;
+    }): T;
+    /** Add a motion blur filter. */
+    motionBlur(options?: {
+        distance?: number;
+        angle?: number;
+        quality?: BlurQuality;
+    }): T;
+    /** Add a point light filter. */
+    pointLight(options?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        color?: string;
+        surfaceScale?: number;
+        diffuseConstant?: number;
+        specularConstant?: number;
+        specularExponent?: number;
+    }): T;
+    /** Add a spot light filter. */
+    spotLight(options?: {
+        x?: number;
+        y?: number;
+        z?: number;
+        pointsAtX?: number;
+        pointsAtY?: number;
+        pointsAtZ?: number;
+        coneAngle?: number;
+        color?: string;
+        surfaceScale?: number;
+        specularConstant?: number;
+        specularExponent?: number;
+    }): T;
+    /** Add a sharpen filter. */
+    sharpen(amount?: number): T;
+    /** Add a pixelate filter. */
+    pixelate(blockSize?: number): T;
+    /** Add a warp filter. */
+    warp(options?: {
+        scale?: number;
+        frequency?: number;
+        octaves?: number;
+        warpType?: WarpType;
+    }): T;
+    /** Add a morphology filter (dilate or erode). */
+    morphology(options?: {
+        operator?: MorphologyOperator;
+        radiusX?: number;
+        radiusY?: number;
+        linked?: boolean;
+    }): T;
+    /** Add a contouring filter (discrete or table mode). */
+    contouring(options?: {
+        mode?: 'discrete' | 'table';
+        levels?: number;
+        contrast?: number;
+    }): T;
+    /** Add a round edges filter. */
+    roundEdges(radius?: number): T;
+    /** Add a channel painter filter. */
+    channelPainter(options?: {
+        red?: number;
+        green?: number;
+        blue?: number;
+    }): T;
+    /** Add a brightness filter. */
+    brightness(amount?: number): T;
+    /** Add a contrast filter. */
+    contrast(amount?: number): T;
+    /** Add an opacity filter. */
+    filterOpacity(amount?: number): T;
+    /** Add an invert filter. */
+    invert(amount?: number): T;
+    /** Add a hue-rotate filter. */
+    hueRotate(angle?: number): T;
+    /** Add a saturate filter. */
+    saturate(amount?: number): T;
+    /** Add a black-and-white filter. */
+    blackAndWhite(threshold?: number): T;
+    /** Add a duotone filter. */
+    duotone(options?: {
+        shadowColor?: string;
+        highlightColor?: string;
+    }): T;
+    /** Add an x-ray filter. */
+    xray(intensity?: number): T;
+    /** Add a noise filter. */
+    noise(options?: {
+        amount?: number;
+        scale?: number;
+    }): T;
+    /** Add an emboss filter. */
+    emboss(options?: {
+        strength?: number;
+        angle?: number;
+    }): T;
+    /** Add a film grain filter. */
+    filmGrain(options?: {
+        amount?: number;
+        size?: number;
+    }): T;
+    /** Add a watercolor filter. */
+    watercolor(options?: {
+        wetness?: number;
+        turbulence?: number;
+    }): T;
+    /** Add a gouache filter. */
+    gouache(options?: {
+        thickness?: number;
+        texture?: number;
+    }): T;
+    /** Add an ink blot filter. */
+    inkBlot(options?: {
+        spread?: number;
+        edges?: number;
+    }): T;
+    /** Add a crumpled plastic filter. */
+    crumpledPlastic(options?: {
+        wrinkles?: number;
+        shine?: number;
+    }): T;
+    /** Add a riddled filter. */
+    riddled(options?: {
+        density?: number;
+        size?: number;
+    }): T;
+    /** Set a CSS basic-shape clip-path value (e.g. `circle(50%)`, `inset(10px)`, `polygon(…)`). */
+    cssClipPath(value: string): T;
+    /** Set CSS mask sub-properties (`mask-image`, `mask-mode`, etc.). */
+    cssMaskProperties(props: Record<string, string>): T;
+    /** Set shape metadata (name, title, description, etc). */
+    metadata(meta: Partial<ShapeMetadata>): T;
+    /** Assign this shape to a group. */
+    group(groupId: string): T;
+    /** Build the SerializedShape object. */
+    build(): SerializedShape;
+}
+declare class Circle extends ShapeBuilder<Circle> {
+    constructor(x: number, y: number, radius: number);
+    /** Set the center position and radius. */
+    position(x: number, y: number): Circle;
+    /** Set the radius. */
+    radius(r: number): Circle;
+}
+declare class Ellipse extends ShapeBuilder<Ellipse> {
+    constructor(cx: number, cy: number, rx: number, ry: number);
+    position(cx: number, cy: number): Ellipse;
+    radii(rx: number, ry: number): Ellipse;
+}
+declare class Rectangle extends ShapeBuilder<Rectangle> {
+    constructor(x: number, y: number, width: number, height: number);
+    position(x: number, y: number): Rectangle;
+    size(width: number, height: number): Rectangle;
+    /** Set the corner radius for rounded rectangles. */
+    cornerRadius(r: number): Rectangle;
+}
+declare class Square extends ShapeBuilder<Square> {
+    constructor(x: number, y: number, size: number);
+    position(x: number, y: number): Square;
+    size(value: number): Square;
+    /** Set the corner radius for rounded squares. */
+    cornerRadius(r: number): Square;
+}
+declare class Line extends ShapeBuilder<Line> {
+    constructor(x1: number, y1: number, x2: number, y2: number);
+    /** Set the start and end points. */
+    from(x: number, y: number): Line;
+    to(x: number, y: number): Line;
+    /** Set the start endpoint marker style. */
+    markerStart(style: EndpointStyle): Line;
+    /** Set the end endpoint marker style. */
+    markerEnd(style: EndpointStyle): Line;
+    /** Convenience: set both markers. */
+    markers(start: EndpointStyle, end: EndpointStyle): Line;
+}
+declare class Text extends ShapeBuilder<Text> {
+    constructor(x: number, y: number, text: string);
+    position(x: number, y: number): Text;
+    /** Set the text content. */
+    content(text: string): Text;
+    /** Set the font size. */
+    fontSize(size: number): Text;
+    /** Set the font family. */
+    fontFamily(family: string): Text;
+    /** Set the font weight. */
+    fontWeight(weight: FontWeight): Text;
+    /** Set the font style (italic, normal, etc). */
+    fontStyle(style: FontStyle): Text;
+    /** Set the text anchor (start, middle, end). */
+    anchor(value: 'start' | 'middle' | 'end'): Text;
+    /** Set letter spacing. */
+    letterSpacing(value: number): Text;
+    /** Set line height. */
+    lineHeight(value: number): Text;
+    /** Set text decoration. */
+    decoration(options: {
+        underline?: boolean;
+        strikethrough?: boolean;
+        overline?: boolean;
+    }): Text;
+    /** Set text transform (uppercase, lowercase, capitalize). */
+    transform(value: TextTransform): Text;
+    /**
+     * Place this text along a path defined by cubic-Bézier control points.
+     *
+     * Each point has `{ x, y }` and may include `handleIn` / `handleOut`
+     * for bezier curve handles.
+     *
+     * @param points - Array of path points (at least 2)
+     * @param startOffset - Percentage offset along the path (0–100). Default: 0
+     */
+    textPath(points: Array<{
+        x: number;
+        y: number;
+        handleIn?: Point;
+        handleOut?: Point;
+    }>, startOffset?: number): Text;
+    /** Set the start offset along the text path (0–100 %). */
+    textPathOffset(percent: number): Text;
+    /** Set the text path side ('left' or 'right'). */
+    textPathSide(side: 'left' | 'right'): Text;
+    /** Set the text direction ('ltr' or 'rtl'). */
+    direction(value: 'ltr' | 'rtl'): Text;
+    /** Set the unicode-bidi mode. */
+    unicodeBidi(value: 'normal' | 'embed' | 'bidi-override' | 'isolate' | 'isolate-override' | 'plaintext'): Text;
+    /** Set the dominant baseline alignment. */
+    dominantBaseline(value: string): Text;
+    /** Set the writing mode. */
+    writingMode(value: 'horizontal-tb' | 'vertical-rl' | 'vertical-lr'): Text;
+    /** Set the word spacing. */
+    wordSpacing(value: number): Text;
+    /** Set the baseline shift. */
+    baselineShift(value: string): Text;
+    /** Set the inline size for text wrapping. */
+    inlineSize(value: number): Text;
+    /** Set the overflow wrap behavior. */
+    overflowWrap(value: 'normal' | 'break-word' | 'anywhere'): Text;
+    /** Set the white-space handling. */
+    whiteSpace(value: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces'): Text;
+    /** Set variable font axis settings. */
+    fontVariationSettings(settings: Record<string, number>): Text;
+    /** Set per-character positional offsets (dx, dy, rotate). */
+    charOffsets(offsets: {
+        x: number;
+        y: number;
+        rotate: number;
+    }[]): Text;
+    /** Set the shape-inside reference for text wrapping inside a shape. */
+    shapeInsideRef(ref: string): Text;
+    /** Set padding for shape-inside text wrapping. */
+    shapePadding(value: number): Text;
+    /** Set rich text data for per-segment styling. */
+    richTextData(data: RichTextData): Text;
+}
+declare abstract class PolygonShapeBuilder<T extends PolygonShapeBuilder<T>> extends ShapeBuilder<T> {
+    constructor(type: SerializedShape['type'], cx: number, cy: number, radius: number);
+    position(cx: number, cy: number): T;
+    radius(r: number): T;
+    /** Rotate the shape's geometry (not the SVG transform). */
+    shiftAngle(degrees: number): T;
+    /** Round the polygon corners. */
+    cornerRadius(r: number): T;
+}
+declare class Triangle extends PolygonShapeBuilder<Triangle> {
+    constructor(cx: number, cy: number, radius: number);
+}
+declare class NGon extends PolygonShapeBuilder<NGon> {
+    constructor(cx: number, cy: number, radius: number, sides?: number);
+    /** Set the number of sides. */
+    sides(n: number): NGon;
+}
+declare class Star extends PolygonShapeBuilder<Star> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the number of star arms/points. */
+    arms(n: number): Star;
+    /** Set the inner radius as a percent of the outer radius (0–100). */
+    innerRadius(percent: number): Star;
+}
+declare class Cross extends PolygonShapeBuilder<Cross> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the arm width as a percent of the total width (0–100). */
+    armWidth(percent: number): Cross;
+}
+declare class Ring extends PolygonShapeBuilder<Ring> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the inner radius (hole size) as a percent (0–100). */
+    innerRadius(percent: number): Ring;
+}
+declare class Spiral extends PolygonShapeBuilder<Spiral> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the number of turns. */
+    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. */
+    direction(d: 1 | -1): Spiral;
+}
+declare class Gear extends PolygonShapeBuilder<Gear> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the number of teeth. */
+    teeth(n: number): Gear;
+    /** Set the tooth depth as a percent (0–100). */
+    toothDepth(percent: number): Gear;
+    /** Set the center hole size as a percent (0–100). 0 = no hole. */
+    holeRadius(percent: number): Gear;
+}
+declare class Arrow extends PolygonShapeBuilder<Arrow> {
+    constructor(cx: number, cy: number, radius: number);
+    /** Set the arrow head width as a percent (0–100). */
+    headWidth(percent: number): Arrow;
+    /** Set the arrow head length as a percent (0–100). */
+    headLength(percent: number): Arrow;
+    /** Set the arrow shaft width as a percent (0–100). */
+    shaftWidth(percent: number): Arrow;
+}
+declare class Spline extends ShapeBuilder<Spline> {
+    constructor(points?: (Point | SplinePoint)[]);
+    /** Set the spline points. */
+    points(pts: (Point | SplinePoint)[]): Spline;
+    /** Add a point to the spline. */
+    addPoint(x: number, y: number): Spline;
+    /** Set the curve type. */
+    curveType(type: SplineCurveType): Spline;
+    /** Set whether the spline is closed. */
+    closed(value?: boolean): Spline;
+    /** Set the tension for Catmull-Rom curves (0–1). */
+    tension(value: number): Spline;
+    /** Set arc params for ARC curve type. */
+    arcParams(params: ArcParams$1[]): Spline;
+    /** Set the start endpoint marker. */
+    markerStart(style: EndpointStyle): Spline;
+    /** Set the end endpoint marker. */
+    markerEnd(style: EndpointStyle): Spline;
+    /** Convenience: set both markers. */
+    markers(start: EndpointStyle, end: EndpointStyle): Spline;
+}
+declare class Polyline extends ShapeBuilder<Polyline> {
+    constructor(points?: Point[]);
+    /** Set the polyline points. */
+    points(pts: Point[]): Polyline;
+    /** Add a point. */
+    addPoint(x: number, y: number): Polyline;
+    /** Set whether the polyline is closed (becomes a polygon). */
+    closed(value?: boolean): Polyline;
+    /** Set the start endpoint marker. */
+    markerStart(style: EndpointStyle): Polyline;
+    /** Set the end endpoint marker. */
+    markerEnd(style: EndpointStyle): Polyline;
+    /** Convenience: set both markers. */
+    markers(start: EndpointStyle, end: EndpointStyle): Polyline;
+}
+declare class ImageShape extends ShapeBuilder<ImageShape> {
+    constructor(x: number, y: number, width: number, height: number, href: string);
+    position(x: number, y: number): ImageShape;
+    size(width: number, height: number): ImageShape;
+    /** Set the image source URL or data URI. */
+    src(href: string): ImageShape;
+    /** Toggle preserveAspectRatio. */
+    preserveAspectRatio(value: boolean): ImageShape;
+}
+
+/**
+ * Animation SDK — Fluent builder API for creating animation timelines.
+ *
+ * Provides `Keyframe`, `Track`, and `Timeline` builder classes that
+ * produce `SerializedAnimationTimeline` data for persistence and
+ * SMIL SVG rendering.
+ *
+ * @example
+ * ```ts
+ * import { Document, Circle, Timeline, Track, EasingType } from '@svgsketch/core';
+ *
+ * const doc = new Document({ width: 400, height: 400 });
+ * const circle = new Circle(100, 200, 50).fill('#3498db').id('ball');
+ * doc.add(circle);
+ *
+ * doc.setTimeline(
+ *   new Timeline(3)
+ *     .loop()
+ *     .addTrack(
+ *       new Track('ball', 'cx')
+ *         .keyframe(0, 100, EasingType.EASE_IN_OUT)
+ *         .keyframe(1.5, 300, EasingType.EASE_OUT)
+ *         .keyframe(3, 100)
+ *     )
+ * );
+ *
+ * const svg = doc.toSVG(); // includes SMIL <animate> elements
+ * ```
+ */
+
+/**
+ * Fluent builder for an animation track.
+ *
+ * A track animates a single property of a single shape over time.
+ */
+declare class Track {
+    private _track;
+    /**
+     * @param shapeId  - The ID of the shape to animate.
+     * @param property - The property to animate (e.g. 'cx', 'opacity', 'rotation', 'fillColor', 'pathMotion').
+     */
+    constructor(shapeId: string, property: string);
+    /** Override the auto-generated track ID. */
+    id(value: string): Track;
+    /**
+     * Add a keyframe at the given time.
+     *
+     * @param time   - Time in seconds from the start of the track.
+     * @param value  - The property value at this time (number or color string).
+     * @param easing - Easing curve leading *into* this keyframe.
+     *                 Defaults to LINEAR.
+     */
+    keyframe(time: number, value: number | string, easing?: EasingType): Track;
+    /** Add multiple keyframes at once. */
+    keyframes(...kfs: AnimationKeyframe[]): Track;
+    /** Disable this track (excluded from playback/export). */
+    disabled(): Track;
+    /** Lock this track from editing. */
+    locked(): Track;
+    /** Set an SVG path for motion-path animation. */
+    motionPath(path: string): Track;
+    /**
+     * Set the begin trigger for this track.
+     *
+     * @example
+     * ```ts
+     * track.beginTrigger('event', 'click')     // start on click
+     * track.beginTrigger('time', '2')           // start at 2 seconds
+     * ```
+     */
+    beginTrigger(type: AnimationTrigger['type'], value: string): Track;
+    /** Set the end trigger for this track. */
+    endTrigger(type: AnimationTrigger['type'], value: string): Track;
+    /** Set the cycle duration in seconds. */
+    cycleDuration(seconds: number): Track;
+    /** Set how many times the track repeats. */
+    cycleRepeats(count: number): Track;
+    /** Repeat the track indefinitely. */
+    infinite(): Track;
+    /** Set the cycle behavior (restart or alternate). */
+    cycle(behavior: CycleBehavior): Track;
+    /**
+     * Set the center point for transform animations (rotation, skew).
+     *
+     * For rotation this determines the point the shape orbits around.
+     * In SMIL the values are emitted as `"angle cx cy"` format.
+     *
+     * @param x - X coordinate of the rotation center.
+     * @param y - Y coordinate of the rotation center.
+     */
+    transformOrigin(x: number, y: number): Track;
+    /**
+     * Set rotation behavior for motion-path animation.
+     *
+     * @param value - `'auto'` to follow path direction, `'auto-reverse'` for reversed,
+     *                or a fixed angle in degrees.
+     */
+    motionRotate(value: 'auto' | 'auto-reverse' | number): Track;
+    /**
+     * Set whether this track's values add to or replace the base value.
+     *
+     * @param value - `'sum'` to add to base, `'replace'` to override.
+     */
+    additive(value: 'sum' | 'replace'): Track;
+    /** Build the raw AnimationTrack data. */
+    build(): AnimationTrack;
+}
+/**
+ * Fluent builder for an animation timeline.
+ *
+ * A timeline aggregates multiple tracks and defines global playback options.
+ */
+declare class Timeline {
+    private _duration;
+    private _loop;
+    private _playbackSpeed;
+    private _tracks;
+    /**
+     * @param duration - Total timeline duration in seconds.
+     */
+    constructor(duration: number);
+    /** Enable looping. */
+    loop(value?: boolean): Timeline;
+    /** Set the playback speed multiplier (e.g. 0.5 = half speed, 2 = double). */
+    speed(value: number): Timeline;
+    /** Set the timeline duration in seconds. */
+    duration(value: number): Timeline;
+    /** Add a track to the timeline. */
+    addTrack(track: Track): Timeline;
+    /** Add multiple tracks at once. */
+    addTracks(...tracks: Track[]): Timeline;
+    /**
+     * Build the AnimationTimeline data used by the runtime.
+     */
+    buildTimeline(): AnimationTimeline;
+    /**
+     * Build the serialized form suitable for persistence in .svgs files.
+     */
+    build(): SerializedAnimationTimeline;
+}
+
+/**
+ * Document builder — fluent API for assembling SVGSketch documents.
+ *
+ * Wraps `createDocument`, `createViewbox`, `stringifyDocument`,
+ * `parseDocument`, and `renderToSvg` into a single ergonomic class.
+ *
+ * @example
+ * ```ts
+ * import { Document, Circle, Rectangle } from '@svgsketch/core';
+ *
+ * const doc = new Document({ width: 800, height: 600 })
+ *   .title('My Drawing')
+ *   .add(new Circle(100, 200, 50).fill('#3498db'))
+ *   .add(new Rectangle(10, 20, 200, 100).fill('#e74c3c'));
+ *
+ * const svg = doc.toSVG();
+ * const json = doc.toJSON();
+ * ```
+ */
+
+/** Options accepted by the Document constructor. */
+interface DocumentOptions {
+    /** Canvas width. Default: 800 */
+    width?: number;
+    /** Canvas height. Default: 600 */
+    height?: number;
+    /** Viewbox ID. Auto-generated if omitted. */
+    viewboxId?: string;
+}
+declare class Document {
+    private _snapshot;
+    constructor(options?: DocumentOptions);
+    /**
+     * Create a Document from an existing HistorySnapshot.
+     */
+    static fromSnapshot(snapshot: HistorySnapshot): Document;
+    /**
+     * Parse a `.svgs` JSON string into a Document.
+     *
+     * @param json - The JSON string (content of a .svgs file)
+     * @param options - Parse options (validate, migrate)
+     */
+    static fromJSON(json: string, options?: ParseOptions): Document;
+    /**
+     * Add a shape (builder or raw SerializedShape).
+     * Returns `this` for chaining.
+     */
+    add(shape: ShapeBuilder<any> | SerializedShape): Document;
+    /**
+     * Add multiple shapes at once.
+     * Returns `this` for chaining.
+     */
+    addAll(...shapes: (ShapeBuilder<any> | SerializedShape)[]): Document;
+    /**
+     * Remove a shape by ID.
+     * @returns `true` if a shape was removed, `false` if no shape matched the ID.
+     */
+    remove(id: string): boolean;
+    /**
+     * Get all shapes in the document.
+     */
+    get shapes(): readonly SerializedShape[];
+    /**
+     * Find a shape by ID.
+     */
+    findShape(id: string): SerializedShape | undefined;
+    /**
+     * Set the canvas size.
+     */
+    size(width: number, height: number): Document;
+    /**
+     * Get the canvas width.
+     */
+    get width(): number;
+    /**
+     * Get the canvas height.
+     */
+    get height(): number;
+    /** Set the document title. */
+    title(value: string): Document;
+    /** Set the document description. */
+    description(value: string): Document;
+    /** Set the document author. */
+    author(value: string): Document;
+    /** Set document keywords. */
+    keywords(...kws: string[]): Document;
+    /** Set the document license. */
+    license(name: LicenseType, url?: string): Document;
+    /** Set the document language (e.g., 'en', 'fr'). */
+    language(lang: string): Document;
+    /** Set or merge custom metadata. */
+    customMetadata(data: Record<string, string>): Document;
+    /** Get the full metadata. */
+    get meta(): DocumentMetadata | undefined;
+    /**
+     * Define a reusable symbol from a set of shapes.
+     *
+     * @param name   - Human-readable name for the symbol.
+     * @param shapes - The shapes that make up the symbol content.
+     * @param options - Optional viewBox, thumbnail, and groups.
+     * @returns The symbol definition ID.
+     */
+    defineSymbol(name: string, shapes: (ShapeBuilder<any> | SerializedShape)[], options?: {
+        viewBox?: string;
+        thumbnail?: string;
+        groups?: SerializedGroup[];
+    }): string;
+    /**
+     * Place a symbol instance on the canvas.
+     *
+     * @param symbolId - The ID of the symbol definition.
+     * @param x - X position.
+     * @param y - Y position.
+     * @param width - Instance width (optional).
+     * @param height - Instance height (optional).
+     */
+    placeSymbolInstance(symbolId: string, x: number, y: number, width?: number, height?: number): Document;
+    /** Remove a symbol definition by ID. */
+    removeSymbol(id: string): boolean;
+    /** Get all symbol definitions. */
+    get symbols(): readonly SerializedSymbolDef[];
+    /**
+     * Add a clip group.
+     *
+     * @param clipShapeIds    - IDs of shapes forming the clip definition.
+     * @param contentShapeIds - IDs of shapes to be clipped.
+     * @param options         - Optional clip-path spec attributes.
+     * @returns The clip group ID.
+     */
+    addClipGroup(clipShapeIds: string[], contentShapeIds: string[], options?: {
+        clipPathUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        rawDefinition?: string;
+    }): string;
+    /**
+     * Add a mask group.
+     *
+     * @param maskShapeIds    - IDs of shapes forming the mask definition.
+     * @param contentShapeIds - IDs of shapes to be masked.
+     * @param options         - Optional mask spec attributes.
+     * @returns The mask group ID.
+     */
+    addMaskGroup(maskShapeIds: string[], contentShapeIds: string[], options?: {
+        maskUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        maskContentUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        maskBounds?: {
+            x: string;
+            y: string;
+            width: string;
+            height: string;
+        };
+        maskType?: 'luminance' | 'alpha';
+        rawDefinition?: string;
+    }): string;
+    /** Remove a clip or mask group by ID. */
+    removeClipMaskGroup(id: string): boolean;
+    /**
+     * Add a guide line.
+     *
+     * @param orientation - 'horizontal' or 'vertical'.
+     * @param position    - Position in canvas coordinates.
+     * @param options     - Optional color and opacity.
+     * @returns The guide ID.
+     */
+    addGuide(orientation: 'horizontal' | 'vertical', position: number, options?: {
+        color?: string;
+        opacity?: number;
+    }): string;
+    /** Remove a guide by ID. */
+    removeGuide(id: string): boolean;
+    /** Remove all guides. */
+    clearGuides(): Document;
+    /** Get all guides. */
+    get guides(): readonly Guide[];
+    /**
+     * Add a measurement annotation.
+     *
+     * @param type   - 'distance' (2 points) or 'angle' (3 points).
+     * @param points - The measurement points.
+     * @param options - Optional visibility, snap divisions, color, opacity.
+     * @returns The measurement ID.
+     */
+    addMeasurement(type: 'distance' | 'angle', points: Point[], options?: {
+        visible?: boolean;
+        snapDivisions?: number;
+        color?: string;
+        opacity?: number;
+    }): string;
+    /** Remove a measurement by ID. */
+    removeMeasurement(id: string): boolean;
+    /** Get all measurements. */
+    get measurements(): readonly Measurement[];
+    /**
+     * Add a custom pattern definition to the document library.
+     *
+     * @param name       - Display name for the pattern.
+     * @param svgContent - Inner SVG markup for the pattern tile.
+     * @param width      - Tile width.
+     * @param height     - Tile height.
+     * @returns The custom pattern ID.
+     */
+    addCustomPattern(name: string, svgContent: string, width: number, height: number): string;
+    /** Remove a custom pattern definition by ID. */
+    removeCustomPattern(id: string): boolean;
+    /** Get all custom pattern definitions. */
+    get customPatterns(): readonly CustomPatternDef[];
+    /**
+     * Add a group definition.
+     *
+     * @param groupId       - Optional custom group ID.
+     * @param parentGroupId - Optional parent group ID for nesting.
+     * @returns The group ID.
+     */
+    addGroup(groupId?: string, parentGroupId?: string): string;
+    /** Remove a group definition. Shapes in the group become ungrouped. */
+    removeGroup(groupId: string): boolean;
+    /** Move a shape into a group. */
+    moveToGroup(shapeId: string, groupId: string): Document;
+    /** Remove a shape from its group. */
+    removeFromGroup(shapeId: string): Document;
+    /** Move a shape to the front of the shapes array (top of z-order). */
+    bringToFront(shapeId: string): Document;
+    /** Move a shape to the back of the shapes array (bottom of z-order). */
+    sendToBack(shapeId: string): Document;
+    /** Move a shape to a specific position in the z-order. */
+    reorder(shapeId: string, position: number): Document;
+    /**
+     * Define a template variable with a default value.
+     *
+     * Variables can be referenced in shape properties as `{{name}}` and
+     * will be substituted at render time.
+     *
+     * @example
+     * ```ts
+     * const doc = new Document()
+     *   .defineVariable('primaryColor', 'color', '#3498db', { label: 'Primary Color' })
+     *   .defineVariable('title', 'string', 'Hello World')
+     *   .defineVariable('radius', 'number', '50')
+     *   .add(new Circle(100, 100, '{{radius}}').fill('{{primaryColor}}'));
+     *
+     * // Render with defaults
+     * const svg1 = doc.toSVG();
+     *
+     * // Render with overrides
+     * const svg2 = doc.toSVG({ variables: { primaryColor: '#e74c3c', radius: '80' } });
+     * ```
+     */
+    defineVariable(name: string, type: TemplateVariableType, defaultValue: string, options?: {
+        label?: string;
+        description?: string;
+    }): Document;
+    /**
+     * Remove a template variable definition.
+     */
+    removeVariable(name: string): Document;
+    /**
+     * Get all defined template variables.
+     */
+    get variables(): readonly TemplateVariable[];
+    /**
+     * Discover all `{{var}}` references in the document,
+     * including any that aren't formally defined.
+     */
+    inspectVariables(): {
+        defined: TemplateVariable[];
+        undeclared: string[];
+    };
+    /**
+     * Set the animation timeline for the document.
+     *
+     * Accepts a `Timeline` builder or raw `SerializedAnimationTimeline` data.
+     * When the document is rendered with `.toSVG()`, SMIL animation
+     * elements (`<animate>`, `<animateTransform>`, `<animateMotion>`)
+     * are automatically injected into the output.
+     *
+     * @example
+     * ```ts
+     * doc.setTimeline(
+     *   new Timeline(3)
+     *     .loop()
+     *     .addTrack(new Track('circle-1', 'cx').keyframe(0, 50).keyframe(3, 350))
+     * );
+     * ```
+     */
+    setTimeline(timeline: Timeline | SerializedAnimationTimeline): Document;
+    /**
+     * Remove the animation timeline from the document.
+     */
+    clearTimeline(): Document;
+    /**
+     * Get the animation timeline, if one is set.
+     */
+    get timeline(): SerializedAnimationTimeline | undefined;
+    /**
+     * Render the document to an SVG string.
+     *
+     * If the document contains template variables, they are substituted
+     * before rendering using defaults or the provided overrides.
+     *
+     * @param options - Render options (width, height, viewBox, variables, etc.)
+     */
+    toSVG(options?: RenderOptions & {
+        variables?: VariableMap;
+    }): string;
+    /**
+     * Serialize the document to a `.svgs` JSON string.
+     *
+     * Template variable placeholders are preserved (not substituted).
+     *
+     * @param options - Stringify options (indent, validate, etc.)
+     */
+    toJSON(options?: StringifyOptions): string;
+    /**
+     * Get the raw HistorySnapshot (a deep copy).
+     */
+    toSnapshot(): HistorySnapshot;
+    /**
+     * Generate code from the document in the specified format.
+     *
+     * Supported formats:
+     * - `'svg'`   — Raw SVG markup
+     * - `'react'` — React functional component (JSX)
+     * - `'vue'`   — Vue Single File Component (SFC)
+     * - `'d3'`    — D3.js code using selections
+     * - `'css'`   — CSS classes + SVG markup
+     *
+     * @param format  - Target code format
+     * @param options - Additional code generation options
+     *
+     * @example
+     * ```ts
+     * const reactCode = doc.toCode('react', { componentName: 'MyIcon' });
+     * const vueCode = doc.toCode('vue', { typescript: true });
+     * const d3Code = doc.toCode('d3', { componentName: 'buildChart' });
+     * ```
+     */
+    toCode(format: CodeFormat, options?: Omit<CodegenOptions, 'format'>): string;
+    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 };