@svgsketch/core 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -40,7 +40,18 @@ declare enum EasingType {
     EASE_OUT_BACK = "ease-out-back",
     EASE_IN_OUT_BACK = "ease-in-out-back",
     CUSTOM_BEZIER = "custom-bezier",
-    LINEAR_FUNCTION = "linear-function"
+    LINEAR_FUNCTION = "linear-function",
+    STEPS = "steps"
+}
+/**
+ * Step position for CSS `steps()` easing. Follows CSS Easing 1 §3.2.
+ * `start`/`end` are legacy aliases for `jump-start`/`jump-end`.
+ */
+type StepPosition = 'jump-start' | 'jump-end' | 'jump-none' | 'jump-both';
+/** Parameters for a `steps(count, position)` easing function. */
+interface StepsParams {
+    count: number;
+    position: StepPosition;
 }
 /**
  * Map from EasingType → cubic-bezier control points [x1, y1, x2, y2].
@@ -97,6 +108,8 @@ interface AnimationKeyframe {
     customBezier?: [number, number, number, number];
     /** Control points for CSS linear() easing when easing is LINEAR_FUNCTION. */
     linearPoints?: LinearEasingPoint[];
+    /** Step count and jump position when easing is STEPS. */
+    stepsParams?: StepsParams;
 }
 /** A control point for a CSS linear() easing function. */
 interface LinearEasingPoint {
@@ -152,6 +165,15 @@ interface AnimationTrack {
      * @default 'replace' (except transforms, which default to 'sum')
      */
     additive?: 'sum' | 'replace';
+    /**
+     * Scoping for this track.
+     * - Absent / 'document' — plays on the main document timeline (default).
+     * - `'marker:<markerId>'` — scoped to a marker definition's inner shapes.
+     *   Only evaluated when the editor is isolation-editing that marker;
+     *   exported as SMIL inside the `<marker>` element so it animates at
+     *   every attached vertex.
+     */
+    scope?: string;
 }
 /**
  * The top-level animation timeline for a document.
@@ -196,6 +218,8 @@ interface SerializedAnimationTimeline {
         };
         motionRotate?: 'auto' | 'auto-reverse' | number;
         additive?: 'sum' | 'replace';
+        /** Scoping — see `AnimationTrack.scope`. */
+        scope?: string;
         /**
          * 6-element CSS matrix of the track's ancestor transform context, captured
          * at the time the animation was authored. Preserves visual fidelity when
@@ -222,6 +246,7 @@ interface SerializedAnimationTimeline {
                 value: number;
                 position: number;
             }[];
+            stepsParams?: StepsParams;
         }[];
     }[];
 }
@@ -288,6 +313,19 @@ interface Viewbox {
     width: number;
     height: number;
 }
+/** Direction hint for connector routing tangents. */
+type ConnectionDirection = 'n' | 's' | 'e' | 'w' | 'any';
+/** A named anchor point on a shape where connectors can attach. */
+interface ConnectionPoint {
+    /** Stable id — 'n','s','e','w','center' for derived; 'custom-<uuid>' for user-placed. */
+    id: string;
+    /** Location in canvas/workspace coordinates (post-transform). */
+    point: Point;
+    /** Tangent hint used by connector routing. */
+    direction: ConnectionDirection;
+    /** 'derived' anchors are computed from shape geometry; 'custom' are persisted overrides. */
+    kind: 'derived' | 'custom';
+}
 type FillType = 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'none';
 type StrokeType = 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern' | 'none';
 type GradientSpreadMethod = 'pad' | 'repeat' | 'reflect';
@@ -297,6 +335,23 @@ interface GradientStop {
     color: string;
     opacity: number;
 }
+/**
+ * How gradient coordinates are interpreted.
+ *
+ * - `'objectBoundingBox'` (default): coordinates are fractions of the
+ *   painted element's bounding box, where `1` equals the full width or
+ *   height. The gradient rescales to each shape.
+ * - `'userSpaceOnUse'`: coordinates are absolute user-space values, so
+ *   the gradient is a fixed color field in the document. Multiple
+ *   shapes referencing the same gradient see a consistent field, and
+ *   clipped shapes reveal a specific slice of it. Required for
+ *   round-tripping source SVGs that author gradients this way.
+ *
+ * When omitted, the renderer treats the gradient as `objectBoundingBox`
+ * for backward compatibility with documents authored before this field
+ * was added.
+ */
+type GradientUnits = 'objectBoundingBox' | 'userSpaceOnUse';
 interface LinearGradient {
     type: 'linear-gradient';
     id: string;
@@ -307,6 +362,20 @@ interface LinearGradient {
     stops: GradientStop[];
     spreadMethod: GradientSpreadMethod;
     opacity: number;
+    /**
+     * When present and equal to `'userSpaceOnUse'`, `x1`/`y1`/`x2`/`y2`
+     * are in document user space (post any ancestor bake), not in the
+     * element's bbox-normalised [0, 1] space. See `GradientUnits`.
+     */
+    gradientUnits?: GradientUnits;
+    /**
+     * Original `id` from the imported source SVG. Runtime `id` is always
+     * a fresh GUID (to keep editor uniqueness invariants), but `sourceId`
+     * is retained so export can restore human-friendly ids when there is
+     * no collision. Cleared whenever the gradient is mutated through the
+     * editor — at that point the source id no longer describes the data.
+     */
+    sourceId?: string;
 }
 interface RadialGradient {
     type: 'radial-gradient';
@@ -321,6 +390,13 @@ interface RadialGradient {
     stops: GradientStop[];
     spreadMethod: GradientSpreadMethod;
     opacity: number;
+    /**
+     * When present and equal to `'userSpaceOnUse'`, `cx`/`cy`/`fx`/`fy`/
+     * `r`/`ry` are in document user space. See `GradientUnits`.
+     */
+    gradientUnits?: GradientUnits;
+    /** See `LinearGradient.sourceId`. */
+    sourceId?: string;
 }
 /**
  * Per-pattern-type tuneable parameters.
@@ -402,6 +478,8 @@ interface PatternFill {
     y?: number;
     /** ID of the `CustomPatternDef` this fill was built from (if any). */
     customPatternId?: string;
+    /** See `LinearGradient.sourceId`. */
+    sourceId?: string;
 }
 type GradientDefinition = LinearGradient | RadialGradient | PatternFill;
 /** Style overrides for a single rich-text segment. */
@@ -453,7 +531,7 @@ interface CustomPatternDef {
     /** Tile height in userSpaceOnUse coordinates. */
     height: number;
 }
-type FilterType = 'drop-shadow' | 'inner-shadow' | 'gaussian-blur' | 'motion-blur' | 'point-light' | 'spot-light' | 'outline' | 'sharpen' | 'pixelate' | 'warp' | 'morphology' | 'contouring-discrete' | 'contouring-table' | 'round-edges' | 'grayscale' | 'channel-painter' | 'brightness' | 'contrast' | 'opacity' | 'invert' | 'hue-rotate' | 'saturate' | 'black-and-white' | 'sepia' | 'duotone' | 'xray' | 'noise' | 'emboss' | 'film-grain' | 'watercolor' | 'gouache' | 'ink-blot' | 'crumpled-plastic' | 'riddled' | 'glow' | 'inner-glow';
+type FilterType = 'drop-shadow' | 'inner-shadow' | 'gaussian-blur' | 'motion-blur' | 'point-light' | 'spot-light' | 'diffuse-lighting' | 'specular-lighting' | 'outline' | 'sharpen' | 'pixelate' | 'warp' | 'morphology' | 'contouring-discrete' | 'contouring-table' | 'round-edges' | 'grayscale' | 'channel-painter' | 'brightness' | 'contrast' | 'opacity' | 'invert' | 'hue-rotate' | 'saturate' | 'black-and-white' | 'sepia' | 'duotone' | 'xray' | 'noise' | 'emboss' | 'film-grain' | 'watercolor' | 'gouache' | 'ink-blot' | 'crumpled-plastic' | 'riddled' | 'glow' | 'inner-glow' | 'raw-svg';
 type BlurQuality = 'normal' | 'high';
 interface BaseFilter {
     id: string;
@@ -516,6 +594,41 @@ interface SpotLightFilter extends BaseFilter {
     specularConstant: number;
     specularExponent: number;
 }
+type LightSource = {
+    kind: 'point';
+    x: number;
+    y: number;
+    z: number;
+} | {
+    kind: 'spot';
+    x: number;
+    y: number;
+    z: number;
+    pointsAtX: number;
+    pointsAtY: number;
+    pointsAtZ: number;
+    limitingConeAngle?: number;
+    specularExponent?: number;
+} | {
+    kind: 'distant';
+    azimuth: number;
+    elevation: number;
+};
+interface DiffuseLightingFilter extends BaseFilter {
+    type: 'diffuse-lighting';
+    surfaceScale: number;
+    diffuseConstant: number;
+    color: string;
+    lightSource: LightSource;
+}
+interface SpecularLightingFilter extends BaseFilter {
+    type: 'specular-lighting';
+    surfaceScale: number;
+    specularConstant: number;
+    specularExponent: number;
+    color: string;
+    lightSource: LightSource;
+}
 type OutlinePosition = 'outside' | 'center' | 'inside';
 interface OutlineFilter extends BaseFilter {
     type: 'outline';
@@ -664,7 +777,29 @@ interface InnerGlowFilter extends BaseFilter {
     radius: number;
     intensity: number;
 }
-type ShapeFilter = DropShadowFilter | InnerShadowFilter | GaussianBlurFilter | MotionBlurFilter | PointLightFilter | SpotLightFilter | OutlineFilter | SharpenFilter | PixelateFilter | WarpFilter | MorphologyFilter | ContouringDiscreteFilter | ContouringTableFilter | RoundEdgesFilter | GrayscaleFilter | ChannelPainterFilter | BrightnessFilter | ContrastFilter | OpacityFilter | InvertFilter | HueRotateFilter | SaturateFilter | BlackAndWhiteFilter | SepiaFilter | DuotoneFilter | XrayFilter | NoiseFilter | EmbossFilter | FilmGrainFilter | WatercolorFilter | GouacheFilter | InkBlotFilter | CrumpledPlasticFilter | RiddledFilter | GlowFilter | InnerGlowFilter;
+/**
+ * Passthrough for `<filter>` definitions the editor doesn't model as a preset.
+ * The parser serialises the element's inner markup and authored region
+ * attributes verbatim; the filter manager re-emits them on render. Absent
+ * attributes stay `undefined` so the UA applies the SVG spec initial values
+ * (filterUnits=objectBoundingBox, primitiveUnits=userSpaceOnUse, filter region
+ * -10% -10% 120% 120%, color-interpolation-filters=linearRGB).
+ */
+interface RawSvgFilter extends BaseFilter {
+    type: 'raw-svg';
+    svgContent: string;
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+    filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+    colorInterpolationFilters?: 'auto' | 'sRGB' | 'linearRGB';
+    floodColor?: string;
+    floodOpacity?: string;
+    lightingColor?: string;
+}
+type ShapeFilter = DropShadowFilter | InnerShadowFilter | GaussianBlurFilter | MotionBlurFilter | PointLightFilter | SpotLightFilter | DiffuseLightingFilter | SpecularLightingFilter | OutlineFilter | SharpenFilter | PixelateFilter | WarpFilter | MorphologyFilter | ContouringDiscreteFilter | ContouringTableFilter | RoundEdgesFilter | GrayscaleFilter | ChannelPainterFilter | BrightnessFilter | ContrastFilter | OpacityFilter | InvertFilter | HueRotateFilter | SaturateFilter | BlackAndWhiteFilter | SepiaFilter | DuotoneFilter | XrayFilter | NoiseFilter | EmbossFilter | FilmGrainFilter | WatercolorFilter | GouacheFilter | InkBlotFilter | CrumpledPlasticFilter | RiddledFilter | GlowFilter | InnerGlowFilter | RawSvgFilter;
 type SegmentCurveType = 'LINEAR' | 'CUBIC' | 'QUADRATIC' | 'ARC';
 interface SplinePoint {
     x: number;
@@ -733,6 +868,84 @@ interface DocumentMetadata {
     licenseUrl: string;
     language: string;
     customMetadata: Record<string, string>;
+    /**
+     * Decimal precision for coordinate values when the document is
+     * serialized — file save, cloud sync, undo capture, and SVG export.
+     * Stored on the document so collaborators stay consistent and
+     * round-trips are deterministic.
+     *
+     * Range 0-12. Defaults to 3 (sub-pixel precision adequate for screen
+     * rendering; matches SVGO's `floatPrecision` and Adobe Illustrator's
+     * SVG export defaults). Set higher (6-8) when authoring assets for
+     * high-fidelity interchange. Values above 8 carry no practical benefit
+     * at the coordinate ranges typical of SVG documents.
+     *
+     * Imported SVGs are NOT rounded on the way in; the first edit or save
+     * conforms them to this precision.
+     */
+    coordinatePrecision?: number;
+}
+/**
+ * A document-level `<script>` element. Scripts are stored as inert data
+ * alongside document metadata — never executed inside the editor — and
+ * re-emitted on export.
+ *
+ * Spec reference: SVG 2 §15.9 (The `<script>` element).
+ */
+interface DocumentScript {
+    /** Internal id (guid) used for list keying inside the editor. */
+    id: string;
+    /** Preserved `id` attribute from the source SVG, if any. */
+    svgId?: string;
+    /** Whether this script has inline body text or an external href. */
+    source: 'inline' | 'external';
+    /** Script body for inline scripts. Empty for external. */
+    content: string;
+    /** URL for external scripts. */
+    href?: string;
+    /** MIME type. Defaults to 'application/ecmascript' per SVG 2. */
+    type: string;
+    /** CORS setting. */
+    crossorigin?: 'anonymous' | 'use-credentials';
+    /** async attribute (SVG 2 aligns with HTML). */
+    async?: boolean;
+    /** defer attribute (SVG 2 aligns with HTML). */
+    defer?: boolean;
+    /** Unknown/extra attributes preserved for round-trip fidelity. */
+    customAttrs?: Record<string, string>;
+}
+/**
+ * A document-level `<style>` block captured from the imported SVG and
+ * re-emitted verbatim on export.
+ *
+ * Styles with `preserved: true` are opaque CSS blobs the editor refuses
+ * to reinterpret because their matched elements live inside `<defs>`
+ * subtrees (mask / clipPath / symbol / pattern) that never become canvas
+ * shapes. Keeping them intact is the only way to round-trip author CSS
+ * that drives mask-interior animations (e.g. `stroke-dashoffset` flow on
+ * `<use>` elements inside a `<mask>`).
+ *
+ * Spec reference: SVG 2 §16 (The `<style>` element).
+ */
+interface DocumentStyle {
+    /** Internal id (guid) used for list keying inside the editor. */
+    id: string;
+    /** Preserved `id` attribute from the source SVG, if any. */
+    svgId?: string;
+    /** Raw CSS source — `@keyframes`, rules, `@media`, etc. */
+    css: string;
+    /** `type` attribute. Defaults to `text/css`. */
+    type?: string;
+    /** `media` attribute, if specified. */
+    media?: string;
+    /**
+     * When true, this block was captured verbatim during import because
+     * the editor cannot safely reinterpret its effect. Must be emitted
+     * as-is on export.
+     */
+    preserved: boolean;
+    /** Unknown/extra attributes preserved for round-trip fidelity. */
+    customAttrs?: Record<string, string>;
 }
 /** Type of a template variable's value. */
 type TemplateVariableType = 'string' | 'color' | 'number';
@@ -842,6 +1055,14 @@ interface CommonNodeProps {
     dashOffset: number;
     strokeDasharray: string | null;
     filters: unknown[];
+    filterColorInterpolation: 'auto' | 'sRGB' | 'linearRGB' | null;
+    filterUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
+    primitiveUnits: 'userSpaceOnUse' | 'objectBoundingBox' | null;
+    filterX: string | null;
+    filterY: string | null;
+    filterWidth: string | null;
+    filterHeight: string | null;
+    rawTransform: string | null;
     metadata: unknown | null;
     cssClipPath: string | null;
     cssMaskProperties: Record<string, string> | null;
@@ -1064,6 +1285,16 @@ interface SerializedShape {
         rx?: number;
         ry?: number;
         cornerRadius?: number;
+        cornerShape?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerMode?: 'uniform' | 'non-uniform';
+        cornerRadiusTL?: number;
+        cornerRadiusTR?: number;
+        cornerRadiusBL?: number;
+        cornerRadiusBR?: number;
+        cornerShapeTL?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerShapeTR?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerShapeBL?: 'round' | 'notch' | 'bevel' | 'scoop';
+        cornerShapeBR?: 'round' | 'notch' | 'bevel' | 'scoop';
         fontSize?: number;
         text?: string;
         fontFamily?: string;
@@ -1097,6 +1328,8 @@ interface SerializedShape {
             x: number;
             dy: number;
         }[];
+        textLength?: number;
+        lengthAdjust?: 'spacing' | 'spacingAndGlyphs';
         /**
          * Whether this text element uses the rich-text model (styled runs with
          * per-character formatting) versus the plain-text model. When true,
@@ -1119,6 +1352,15 @@ interface SerializedShape {
         borderColor?: string;
         borderWidth?: number | string;
         strokeOpacity?: number;
+        /** CSS `paint-order` (SVG 2). Canonical SVG token string, e.g.
+         *  'stroke fill markers'. Omitted when equivalent to default 'normal'. */
+        paintOrder?: string;
+        /** Marker id applied as `marker-start` (rendered `url(#id)` in SVG). */
+        markerStart?: string;
+        /** Marker id applied as `marker-mid`. */
+        markerMid?: string;
+        /** Marker id applied as `marker-end`. */
+        markerEnd?: string;
         cx?: number;
         cy?: number;
         sides?: number;
@@ -1136,6 +1378,16 @@ interface SerializedShape {
         headWidthPercent?: number;
         headLengthPercent?: number;
         shaftWidthPercent?: number;
+        tailAngleDeg?: number;
+        tailLengthPercent?: number;
+        tailWidthPercent?: number;
+        lobeRadiusPercent?: number;
+        cleftDepthPercent?: number;
+        boltSegments?: number;
+        boltJaggednessPercent?: number;
+        boltWidthPercent?: number;
+        cloudBumps?: number;
+        cloudPuffinessPercent?: number;
         x1?: number;
         y1?: number;
         x2?: number;
@@ -1150,11 +1402,29 @@ interface SerializedShape {
         endEndpoint?: 'none' | 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'square';
         locked?: boolean;
         visible?: boolean;
+        /**
+         * SVG `visibility` presentation attribute. Distinct from `visible`:
+         * `visible` (boolean) is the editor's user-toggled layer hide
+         * (display:none semantics); `visibility` is the SVG attribute
+         * (preserves layout, can be flipped by SMIL
+         * `<animate attributeName="visibility">`). Conflating the two breaks
+         * SMIL visibility animations on imported SVGs because display:none
+         * overrides the SVG visibility attribute.
+         */
+        visibility?: 'visible' | 'hidden' | 'collapse';
         fillType?: FillType;
         fillGradient?: LinearGradient | RadialGradient | PatternFill;
         strokeType?: StrokeType;
         strokeGradient?: LinearGradient | RadialGradient | PatternFill;
         filters?: ShapeFilter[];
+        filterColorInterpolation?: 'auto' | 'sRGB' | 'linearRGB';
+        filterUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        primitiveUnits?: 'userSpaceOnUse' | 'objectBoundingBox';
+        filterX?: string;
+        filterY?: string;
+        filterWidth?: string;
+        filterHeight?: string;
+        rawTransform?: string;
         splinePoints?: SplinePoint[];
         splineCurveType?: SplineCurveType;
         splineClosed?: boolean;
@@ -1167,6 +1437,40 @@ interface SerializedShape {
         originalHeight?: number;
         preserveAspectRatio?: boolean;
         imageOpacity?: number;
+        mediaKind?: 'audio' | 'video';
+        mediaMimeType?: string;
+        naturalDuration?: number;
+        begin?: number;
+        trimStart?: number;
+        trimEnd?: number;
+        volume?: number;
+        muted?: boolean;
+        loop?: boolean;
+        playbackRate?: number;
+        mediaOpacity?: number;
+        /** Auto-generated volume ramp length at clip start (seconds). */
+        fadeInDuration?: number;
+        /** Auto-generated volume ramp length at clip end (seconds). */
+        fadeOutDuration?: number;
+        /** First-frame thumbnail (data URI or /api/image-assets URL). Video only. */
+        posterHref?: string;
+        /** Crop rectangle in source pixels. Video only. */
+        sourceRect?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        /**
+         * BCP 47 language tag matched against the user agent's language
+         * preferences via SVG's `systemLanguage` conditional-processing
+         * attribute. Meaningful when a `<switch>` wraps multiple
+         * localized media alternatives — the UA picks the foreignObject
+         * whose language matches. No editor UI yet; preserved on
+         * import/export for forward compatibility with translated
+         * soundtracks / captioned video versions.
+         */
+        systemLanguage?: string;
         shapeInsideRef?: string;
         shapePadding?: number;
         isTextPath?: boolean;
@@ -1214,6 +1518,40 @@ interface SerializedShape {
          * when serialized to standalone SVG.
          */
         bindings?: Record<string, string>;
+        /** User-placed custom connection anchors. Derived anchors are not persisted. */
+        connectionPoints?: ConnectionPoint[];
+        /** Connector shape: reference to the source shape + anchor it attaches to. */
+        sourceRef?: {
+            shapeId: string;
+            anchorId: string;
+        } | null;
+        /** Connector shape: reference to the target shape + anchor it attaches to. */
+        targetRef?: {
+            shapeId: string;
+            anchorId: string;
+        } | null;
+        /** Connector shape: cached absolute source point (recomputed when source moves). */
+        sourcePoint?: Point;
+        /** Connector shape: cached absolute target point. */
+        targetPoint?: Point;
+        /** Connector shape: interior waypoints for orthogonal routing. */
+        waypoints?: Point[];
+        /** Connector shape: path routing algorithm. */
+        routingMode?: 'straight' | 'orthogonal' | 'rounded-ortho' | 'curved';
+        /** Connector shape: in-path label (double-click to edit). */
+        label?: string;
+        /** Connector shape: label position along the path (0–1). */
+        labelPosition?: number;
+        /** Connector shape: perpendicular offset of the label. */
+        labelOffset?: number;
+        /** Connector shape: stroke style to Mermaid edge mapping. */
+        mermaidEdgeStyle?: 'solid' | 'thick' | 'dotted';
+        /** Parallelogram/trapezoid slant amount as a % of width. */
+        slantPercent?: number;
+        /** Trapezoid top width as a % of the bottom width (0–100). */
+        topWidthPercent?: number;
+        /** Document shape: wave amplitude as a % of height. */
+        waveAmplitudePercent?: number;
     };
 }
 type SerializedViewbox = Viewbox;
@@ -1255,6 +1593,15 @@ interface HistorySnapshot {
     clipMaskGroups?: SerializedClipMaskGroup[];
     /** Document-level metadata (title, description, author, etc.) */
     documentMetadata?: DocumentMetadata;
+    /** Document-level `<script>` elements (SVG 2 §15.9). */
+    documentScripts?: DocumentScript[];
+    /**
+     * Document-level `<style>` blocks captured from the source SVG and
+     * re-emitted verbatim on export. Used for CSS whose effect targets
+     * def-scoped content (mask / clipPath / symbol interiors) that the
+     * editor cannot translate into AnimationTracks.
+     */
+    documentStyles?: DocumentStyle[];
     /** Template variable definitions with defaults. */
     templateVariables?: TemplateVariable[];
     /** Animation timeline (tracks, keyframes, easing). */
@@ -1263,6 +1610,12 @@ interface HistorySnapshot {
     customPatterns?: CustomPatternDef[];
     /** Symbol definitions (reusable component templates). */
     symbols?: SerializedSymbolDef[];
+    /**
+     * Marker definitions (reusable vertex-attached graphics: arrowheads, dots,
+     * etc.). Built-in markers are reconstituted at load time by MarkerManager
+     * and are NOT persisted here — only user-authored defs are stored.
+     */
+    markers?: SerializedMarkerDef[];
 }
 /**
  * A variant axis on a component symbol. Each axis has a name (e.g.
@@ -1322,6 +1675,74 @@ interface SerializedSymbolDef {
      */
     variantThumbnails?: Record<string, string>;
 }
+/**
+ * A reusable `<marker>` definition (SVG 2 §11.6). Markers are vertex-attached
+ * graphics — arrowheads, vertex dots, decorations — referenced via
+ * `marker-start` / `marker-mid` / `marker-end` attributes on stroked shapes.
+ *
+ * The browser handles per-vertex positioning, scaling (via `markerUnits`),
+ * and orientation (via `orient`, including tangent-aware `auto` mode on
+ * curved paths). MarkerManager only maintains the DOM `<defs>` entries in
+ * sync with this serialized state.
+ *
+ * Simpler than `SerializedSymbolDef` — markers have no variants, no instance
+ * overrides, and no placed instances (they attach via attribute references).
+ */
+interface SerializedMarkerDef {
+    /**
+     * Unique identifier.
+     * - Built-in markers use stable ids: `mkr-builtin-arrow`, `mkr-builtin-open-arrow`,
+     *   `mkr-builtin-circle`, `mkr-builtin-diamond`, `mkr-builtin-square`.
+     * - User-created markers use `mkr-<guid>`.
+     */
+    id: string;
+    /** Human-readable name shown in the markers panel. */
+    name: string;
+    /** SVG viewBox string ("minX minY width height"). */
+    viewBox: string;
+    /** X reference point — where the marker's "tip" aligns with the host vertex. */
+    refX: number;
+    refY: number;
+    markerWidth: number;
+    markerHeight: number;
+    /**
+     * `strokeWidth` scales the marker with the host's stroke-width (default,
+     * typical for arrows). `userSpaceOnUse` renders at fixed size regardless
+     * of stroke.
+     */
+    markerUnits: 'strokeWidth' | 'userSpaceOnUse';
+    /**
+     * `auto` rotates to match the path tangent at each vertex.
+     * `auto-start-reverse` reverses the start marker (so arrowheads don't
+     * point inward at path starts). A number is a fixed rotation in degrees.
+     */
+    orient: 'auto' | 'auto-start-reverse' | number;
+    /**
+     * Inner geometry. For user markers this is the authoritative source —
+     * edited via isolation mode and re-rendered into the DOM `<marker>` child.
+     * For built-ins this is `[]` in v1; built-ins render from the descriptor
+     * registry (`getMarkerDescriptors()`) and are not editable.
+     */
+    shapes: SerializedShape[];
+    /** Groups within the marker (mirrors `SerializedSymbolDef.groups`). */
+    groups?: SerializedGroup[];
+    /** Base64 data-URI thumbnail for the markers panel. */
+    thumbnail?: string;
+    /**
+     * Animation tracks scoped to the marker's inner shapes. Each track's
+     * `shapeId` references an id in `shapes`. During isolation editing these
+     * tracks are merged into the document timeline (tagged `scope:
+     * 'marker:<id>'`) so the user can edit them; on save they're extracted
+     * back here. On SVG export the tracks render as SMIL `<animate>` elements
+     * inside the `<marker>` DOM so they play at every attached vertex.
+     */
+    animations?: SerializedAnimationTimeline['tracks'];
+    /**
+     * True for editor-shipped built-ins (arrow, open-arrow, circle, diamond,
+     * square). Built-ins are non-deletable, non-renamable, and non-editable.
+     */
+    builtIn?: boolean;
+}
 interface SerializedGroup {
     id: string;
     parentId: string | null;
@@ -1715,6 +2136,65 @@ declare function extractVariables(snapshot: HistorySnapshot): ExtractedVariables
  */
 declare function parseVariableArgs(args: string[]): VariableMap;
 
+/**
+ * @svgsketch/core — Coordinate precision utilities.
+ *
+ * Pure rounding utilities used at every state-capture boundary in the
+ * editor (per-shape command capture, full snapshot capture, SVG export)
+ * to enforce a configurable decimal precision on persisted/exported
+ * coordinate values.
+ *
+ * Rounding fires only on the way OUT of the document model (save, export,
+ * undo capture). Imports are never rounded — see DocumentMetadata's
+ * `coordinatePrecision` field for the policy.
+ *
+ * Industry context: Adobe Illustrator, Inkscape, Affinity Designer, and
+ * SVGO all expose a precision control. Default 3 decimals matches SVGO
+ * and Illustrator.
+ */
+
+/** Default precision when DocumentMetadata.coordinatePrecision is unset. */
+declare const DEFAULT_COORDINATE_PRECISION = 3;
+/**
+ * Maximum precision we accept. Above 12 the rounding becomes a no-op for
+ * practical SVG coordinate ranges (float64 has ~15-17 significant digits).
+ */
+declare const MAX_COORDINATE_PRECISION = 12;
+/**
+ * Resolve an optional precision value to a concrete one. Clamps to the
+ * supported range and substitutes the default for `undefined` / `null` /
+ * non-finite inputs.
+ */
+declare function getEffectivePrecision(p: number | undefined | null): number;
+/**
+ * Round a single number to N decimal places. Non-finite inputs (NaN,
+ * Infinity) pass through unchanged so we never poison data with NaN.
+ */
+declare function roundCoord(value: number, precision: number): number;
+/**
+ * Round every numeric token in a string in place. Does not touch any
+ * non-numeric content (operators, commands, whitespace).
+ */
+declare function roundNumberString(s: string, precision: number): string;
+/**
+ * Round all coordinate-bearing numeric fields in a SerializedShape's
+ * state. Returns a new object — input is not mutated.
+ *
+ * `id` and `type` are passed through unchanged.
+ */
+declare function roundSerializedShape(shape: SerializedShape, precision: number): SerializedShape;
+/**
+ * Round all coordinate-bearing fields in a complete HistorySnapshot.
+ * Used at the snapshot-level capture boundary (file save, cloud sync).
+ *
+ * Returns a new snapshot with shapes, viewboxes, guides, measurements,
+ * and the animation timeline rounded. Document metadata (titles, IDs,
+ * etc.) and structural fields (groups, clipMaskGroups, scripts, symbols)
+ * pass through with their numeric leaves rounded but their structure
+ * preserved.
+ */
+declare function roundSnapshot(snapshot: HistorySnapshot, precision: number): HistorySnapshot;
+
 /**
  * Document-level SVG renderer.
  *
@@ -1832,6 +2312,41 @@ declare function computeCrossVertices(radius: number, armWidthPercent: number, s
  * Compute arrow vertices (7 points forming an arrow).
  */
 declare function computeArrowVertices(radius: number, headWidthPercent: number, headLengthPercent: number, shaftWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute speech-bubble vertices — square body with a tail protruding at a
+ * chosen angle. The base endpoints lie on the chosen body edge (keeping the
+ * body outline continuous); the tip extends in the direction of `tailAngleDeg`
+ * at length `tailLengthPercent * radius`.
+ *
+ * The `shiftAngleDeg` rotates the entire shape (body + tail).
+ */
+declare function computeSpeechBubbleVertices(radius: number, tailAngleDeg: number, tailLengthPercent: number, tailWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute lightning-bolt vertices — a zigzag ribbon from top tip to bottom tip.
+ * `boltSegments` line segments make the zigzag (alternating x offsets of
+ * `boltJaggednessPercent * radius`); the ribbon is `boltWidthPercent * radius`
+ * wide, perpendicular to each segment's bisector normal.
+ */
+declare function computeLightningVertices(radius: number, boltSegments: number, boltJaggednessPercent: number, boltWidthPercent: number, shiftAngleDeg?: number): Point[];
+/**
+ * Compute heart path — two cubic Béziers meeting at the bottom tip and the
+ * upper cleft. `lobeRadiusPercent` controls the horizontal extent of the two
+ * top lobes; `cleftDepthPercent` controls how deep the central dip sits.
+ */
+declare function computeHeartPath(radius: number, lobeRadiusPercent: number, cleftDepthPercent: number, shiftAngleDeg?: number): string;
+/**
+ * Compute cloud path — a classic cartoon-cloud silhouette built as the outer
+ * boundary of N overlapping circles placed around an elongated ellipse.
+ * Circles go all the way around (top, sides, bottom), and the silhouette is
+ * closed by walking each circle's outer arc via the intersection with its
+ * next neighbor. Every transition between bumps is tangent-smooth — no flat
+ * edges, no corners.
+ *
+ * `cloudBumps` (3..8) — number of bump circles forming the silhouette.
+ * `cloudPuffinessPercent` (40..80) — drives bump overlap; higher values
+ * smooth the underside; lower values leave the bumps more pronounced.
+ */
+declare function computeCloudPath(radius: number, cloudBumps: number, cloudPuffinessPercent: number, shiftAngleDeg?: number): string;
 /**
  * Convert an array of vertices to an SVG path string.
  * Supports optional rounded corners via quadratic Bézier.
@@ -1845,9 +2360,6 @@ declare function computeRingPath(radius: number, innerRadiusPercent: number, fil
  * Generate SVG path for an Archimedean spiral.
  */
 declare function computeSpiralPath(radius: number, turns: number, thicknessPercent: number, spiralDirection?: number, shiftAngleDeg?: number): string;
-/**
- * Compute gear vertices (4 vertices per tooth).
- */
 declare function computeGearVertices(teeth: number, radius: number, toothDepthPercent: number, shiftAngleDeg?: number): Point[];
 /**
  * Generate full gear path including optional center hole.
@@ -1957,6 +2469,7 @@ declare function generatePatternSvgContent(patternType: string, scale: number, c
  *
  * @packageDocumentation
  */
+
 interface MarkerDescriptor {
     /** Marker element id (e.g., 'line-marker-arrow'). */
     id: string;
@@ -1981,6 +2494,22 @@ declare const MARKER_HEIGHT = 6;
  * `markerUnits="strokeWidth"`, and `orient="auto-start-reverse"`.
  */
 declare function getMarkerDescriptors(): MarkerDescriptor[];
+/**
+ * Maps the legacy marker ids (used by line endpoint shape state) to the new
+ * first-class MarkerManager ids. The legacy ids remain valid references in
+ * the DOM — built-ins are emitted under BOTH ids to preserve backwards
+ * compat with saved docs that reference `url(#line-marker-arrow)`.
+ */
+declare const BUILTIN_MARKER_ID_MAP: Record<string, string>;
+/**
+ * Return `SerializedMarkerDef`s for the built-in line endpoint markers.
+ *
+ * Built-ins carry `shapes: []` — their geometry is rendered by the editor
+ * directly from the descriptor registry rather than from `SerializedShape`s.
+ * This keeps descriptor → shape conversion out of v1 scope. Consequence:
+ * built-ins are non-editable (the markers panel disables Edit on them).
+ */
+declare function getBuiltInMarkerDefs(): SerializedMarkerDef[];
 
 /**
  * SMIL animation renderer — converts SerializedAnimationTimeline
@@ -3255,4 +3784,4 @@ declare class Document {
     private _ensureMetadata;
 }
 
-export { type AnimatablePropertyDescriptor, type AnimationKeyframe, type AnimationTimeline, type AnimationTrack, type AnimationTrigger, type AnimationTriggerType, type AnyNodeProps, type ArcParams$1 as ArcParams, type AriaRole, Arrow, type ArrowNodeProps, type BaseFilter, type BlackAndWhiteFilter, type BlurQuality, type BrightnessFilter, CURRENT_SCHEMA_VERSION, type ChannelPainterFilter, Circle, type CircleNodeProps, type CodeFormat, type CodegenOptions, type CommonNodeProps, type ContouringDiscreteFilter, type ContouringTableFilter, type ContrastFilter, type CornerShapeValue, type CreateDocumentOptions, type CreateShapeOptions, Cross, type CrossNodeProps, type CrumpledPlasticFilter, type CustomPatternDef, type CycleBehavior, Document, type DocumentMetadata, type DocumentNodeProps, type DocumentOptions, type DropShadowFilter, type DuotoneFilter, EASING_CURVES, EVENT_TRIGGER_OPTIONS, EasingType, Ellipse, type EllipseNodeProps, type EmbossFilter, type ExtractedVariables, type FillType, type FilmGrainFilter, type FilterType, type GaussianBlurFilter, Gear, type GearNodeProps, type GlowFilter, type GouacheFilter, type GradientDefinition, type GradientSpreadMethod, type GradientStop, type GrayscaleFilter, type GroupNodeProps, type Guide, type HistorySnapshot, type HueRotateFilter, type ImageAttribution, type ImageNodeProps, ImageShape, type InkBlotFilter, type InnerGlowFilter, type InnerShadowFilter, type InvertFilter, type LicenseType, Line, type LineEndpointValue, type LineNodeProps, type LinearEasingPoint, type LinearGradient, LinearGradientBuilder, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, MIGRATIONS, type MarkerDescriptor, type Measurement, type Migration, type MorphologyFilter, type MorphologyOperator, type MotionBlurFilter, NGon, type NGonNodeProps, type NodeTypePropsMap, type NoiseFilter, type OpacityFilter, type OutlineFilter, type OutlinePosition, type ParseOptions, PatternBuilder, type PatternElement, type PatternFill, type PatternParams, type PatternSvgContentResult, type PatternType, type PixelateFilter, type Point, type PointLightFilter, type PolygonBaseNodeProps, Polyline, type PolylineNodeProps, type RadialGradient, RadialGradientBuilder, Rectangle, type RectangleNodeProps, type RenderOptions, type RichTextData, type RichTextLine, type RichTextSegment, type RichTextSegmentStyle, type RiddledFilter, Ring, type RingNodeProps, type RoundEdgesFilter, type SaturateFilter, type SegmentCurveType, type SepiaFilter, type SerializedAnimationTimeline, type SerializedClipMaskGroup, type SerializedGroup, type SerializedShape, type SerializedSymbolDef, type SerializedVariantAxis, type SerializedViewbox, ShapeBuilder, type ShapeFilter, type ShapeMetadata, type SharpenFilter, Spiral, type SpiralNodeProps, Spline, SplineCurveType, type SplineNodeProps, type SplinePoint, SplinePointType, type SpotLightFilter, Square, type SquareNodeProps, Star, type StarNodeProps, type StringifyOptions, type StrokeType, type SymbolInstanceNodeProps, type TemplateVariable, type TemplateVariableSource, type TemplateVariableType, Text, type TextNodeProps, Timeline, Track, Triangle, type TriangleNodeProps, type ValidationError, type ValidationResult, type VariableMap, type Viewbox, type WarpFilter, type WarpType, type WatercolorFilter, type XrayFilter, computeArrowVertices, computeCrossVertices, computeDashArray, computeGearPath, computeGearVertices, computePolygonVertices, computeRectanglePath, computeRingPath, computeSpiralPath, computeSplinePath, computeStarVertices, createDocument, createShape, createViewbox, escXml, extractVariables, filterAttr, generateCode, generateCssCode, generateD3Code, generateId, generatePatternSvgContent, generateReactCode, generateSvgCode, generateVueCode, getEasingCubicBezier, getMarkerDescriptors, getPatternElements, linearGradient, migrateSnapshot, parseDocument, parseVariableArgs, pattern, radialGradient, renderAnimationElements, renderCircle, renderEllipse, renderFilterDefs, renderFilterPrimitivesForType, renderImage, renderLine, renderPolygonShape, renderPolyline, renderRectangle, renderShape, renderSpline, renderText, renderToSvg, stringifyDocument, substituteString, substituteVariables, validateSnapshot, verticesToPath };
+export { type AnimatablePropertyDescriptor, type AnimationKeyframe, type AnimationTimeline, type AnimationTrack, type AnimationTrigger, type AnimationTriggerType, type AnyNodeProps, type ArcParams$1 as ArcParams, type AriaRole, Arrow, type ArrowNodeProps, BUILTIN_MARKER_ID_MAP, type BaseFilter, type BlackAndWhiteFilter, type BlurQuality, type BrightnessFilter, CURRENT_SCHEMA_VERSION, type ChannelPainterFilter, Circle, type CircleNodeProps, type CodeFormat, type CodegenOptions, type CommonNodeProps, type ConnectionDirection, type ConnectionPoint, type ContouringDiscreteFilter, type ContouringTableFilter, type ContrastFilter, type CornerShapeValue, type CreateDocumentOptions, type CreateShapeOptions, Cross, type CrossNodeProps, type CrumpledPlasticFilter, type CustomPatternDef, type CycleBehavior, DEFAULT_COORDINATE_PRECISION, type DiffuseLightingFilter, Document, type DocumentMetadata, type DocumentNodeProps, type DocumentOptions, type DocumentScript, type DocumentStyle, type DropShadowFilter, type DuotoneFilter, EASING_CURVES, EVENT_TRIGGER_OPTIONS, EasingType, Ellipse, type EllipseNodeProps, type EmbossFilter, type ExtractedVariables, type FillType, type FilmGrainFilter, type FilterType, type GaussianBlurFilter, Gear, type GearNodeProps, type GlowFilter, type GouacheFilter, type GradientDefinition, type GradientSpreadMethod, type GradientStop, type GradientUnits, type GrayscaleFilter, type GroupNodeProps, type Guide, type HistorySnapshot, type HueRotateFilter, type ImageAttribution, type ImageNodeProps, ImageShape, type InkBlotFilter, type InnerGlowFilter, type InnerShadowFilter, type InvertFilter, type LicenseType, type LightSource, Line, type LineEndpointValue, type LineNodeProps, type LinearEasingPoint, type LinearGradient, LinearGradientBuilder, type LinkTarget, MARKER_HEIGHT, MARKER_VIEWBOX, MARKER_WIDTH, MAX_COORDINATE_PRECISION, MIGRATIONS, type MarkerDescriptor, type Measurement, type Migration, type MorphologyFilter, type MorphologyOperator, type MotionBlurFilter, NGon, type NGonNodeProps, type NodeTypePropsMap, type NoiseFilter, type OpacityFilter, type OutlineFilter, type OutlinePosition, type ParseOptions, PatternBuilder, type PatternElement, type PatternFill, type PatternParams, type PatternSvgContentResult, type PatternType, type PixelateFilter, type Point, type PointLightFilter, type PolygonBaseNodeProps, Polyline, type PolylineNodeProps, type RadialGradient, RadialGradientBuilder, type RawSvgFilter, Rectangle, type RectangleNodeProps, type RenderOptions, type RichTextData, type RichTextLine, type RichTextSegment, type RichTextSegmentStyle, type RiddledFilter, Ring, type RingNodeProps, type RoundEdgesFilter, type SaturateFilter, type SegmentCurveType, type SepiaFilter, type SerializedAnimationTimeline, type SerializedClipMaskGroup, type SerializedGroup, type SerializedMarkerDef, type SerializedShape, type SerializedSymbolDef, type SerializedVariantAxis, type SerializedViewbox, ShapeBuilder, type ShapeFilter, type ShapeMetadata, type SharpenFilter, type SpecularLightingFilter, Spiral, type SpiralNodeProps, Spline, SplineCurveType, type SplineNodeProps, type SplinePoint, SplinePointType, type SpotLightFilter, Square, type SquareNodeProps, Star, type StarNodeProps, type StepPosition, type StepsParams, type StringifyOptions, type StrokeType, type SymbolInstanceNodeProps, type TemplateVariable, type TemplateVariableSource, type TemplateVariableType, Text, type TextNodeProps, Timeline, Track, Triangle, type TriangleNodeProps, type ValidationError, type ValidationResult, type VariableMap, type Viewbox, type WarpFilter, type WarpType, type WatercolorFilter, type XrayFilter, computeArrowVertices, computeCloudPath, computeCrossVertices, computeDashArray, computeGearPath, computeGearVertices, computeHeartPath, computeLightningVertices, computePolygonVertices, computeRectanglePath, computeRingPath, computeSpeechBubbleVertices, computeSpiralPath, computeSplinePath, computeStarVertices, createDocument, createShape, createViewbox, escXml, extractVariables, filterAttr, generateCode, generateCssCode, generateD3Code, generateId, generatePatternSvgContent, generateReactCode, generateSvgCode, generateVueCode, getBuiltInMarkerDefs, getEasingCubicBezier, getEffectivePrecision, getMarkerDescriptors, getPatternElements, linearGradient, migrateSnapshot, parseDocument, parseVariableArgs, pattern, radialGradient, renderAnimationElements, renderCircle, renderEllipse, renderFilterDefs, renderFilterPrimitivesForType, renderImage, renderLine, renderPolygonShape, renderPolyline, renderRectangle, renderShape, renderSpline, renderText, renderToSvg, roundCoord, roundNumberString, roundSerializedShape, roundSnapshot, stringifyDocument, substituteString, substituteVariables, validateSnapshot, verticesToPath };