@pixerate/editor 0.31.0 → 0.33.0

package/dist/vector/index.d.cts

@@ -0,0 +1,1052 @@
+import { C as CanvasGradientDef, A as AffineMatrix, B as BezierPathInput, a as BezierPath, S as SvgGradientDef } from '../bezier-6KPx3w7Z.cjs';
+import { P as Point } from '../types-BFkYA4eF.cjs';
+import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
+import { C as CommandSpec } from '../registry-D0GADKc7.cjs';
+import '../types-DsiXGmjo.cjs';
+import '../schema-DYDGdYL9.cjs';
+
+/** An affine matrix `[a, b, c, d, e, f]`: `x' = a·x + c·y + e`, `y' = b·x + d·y + f` (SVG order). */
+type VectorMatrix = readonly [number, number, number, number, number, number];
+/** A point in document coordinates. */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+/**
+ * How an anchor's handles relate:
+ * - `corner`: handles move independently (or are absent).
+ * - `smooth`: handles stay on one line through the anchor, lengths independent.
+ * - `symmetric`: handles stay on one line with equal lengths.
+ */
+type VectorAnchorType = 'corner' | 'smooth' | 'symmetric';
+/**
+ * One anchor of a subpath. Handles are absolute document positions; a missing (or `null`)
+ * handle sits on the anchor, so a segment with no handles at either end is a straight line.
+ */
+interface VectorAnchor {
+    x: number;
+    y: number;
+    /** Control point of the segment arriving at this anchor. */
+    in?: Vec2 | null;
+    /** Control point of the segment leaving this anchor. */
+    out?: Vec2 | null;
+    /** Default `corner`. */
+    type?: VectorAnchorType;
+}
+/** A chain of anchors joined by line or cubic Bézier segments. */
+interface VectorSubpath {
+    anchors: VectorAnchor[];
+    /** Joins the last anchor back to the first. */
+    closed: boolean;
+}
+/** A fill or stroke: any CSS colour, a gradient, or `null` / `'none'` for no paint. */
+type VectorPaint = string | CanvasGradientDef | null;
+type VectorFillRule = 'nonzero' | 'evenodd';
+type VectorLineCap = 'butt' | 'round' | 'square';
+type VectorLineJoin = 'miter' | 'round' | 'bevel';
+/** Paint and stroke settings of a path. */
+interface VectorStyle {
+    fill?: VectorPaint;
+    stroke?: VectorPaint;
+    /** Default 1. */
+    strokeWidth?: number;
+    strokeLinecap?: VectorLineCap;
+    strokeLinejoin?: VectorLineJoin;
+    strokeDasharray?: number[];
+    /** Default `nonzero`. */
+    fillRule?: VectorFillRule;
+}
+interface VectorNodeBase {
+    id: string;
+    name?: string;
+    /** Default true. */
+    visible?: boolean;
+    /** Locked nodes are drawn but cannot be picked or edited on the canvas. */
+    locked?: boolean;
+    /** 0–1, default 1. */
+    opacity?: number;
+    /**
+     * Placement in the parent's space: a rigid matrix (rotation + translation). Anchors and
+     * children are in the node's own space. Omitted for unrotated nodes, whose positions are
+     * stored directly. Scale and skew are never stored here — `transformVectorNode` bakes
+     * them into the geometry, so stroke widths and the rotated selection box stay exact.
+     */
+    transform?: VectorMatrix;
+}
+/** A shape made of one or more subpaths (holes and compound shapes included). */
+interface VectorPathNode extends VectorNodeBase, VectorStyle {
+    type: 'path';
+    subpaths: VectorSubpath[];
+}
+/** A group of nodes that select and transform together. */
+interface VectorGroupNode extends VectorNodeBase {
+    type: 'group';
+    children: VectorNode[];
+}
+type VectorNode = VectorPathNode | VectorGroupNode;
+/** A vector drawing: an artboard and its nodes, bottom to top. */
+interface VectorDocument {
+    width: number;
+    height: number;
+    /** Artboard colour (default: transparent). */
+    background?: string;
+    nodes: VectorNode[];
+}
+/** An axis-aligned rectangle. */
+interface VectorBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Identifies one anchor of a path node. */
+interface VectorAnchorRef {
+    nodeId: string;
+    subpath: number;
+    index: number;
+}
+/** Identifies one handle of an anchor. */
+interface VectorHandleRef extends VectorAnchorRef {
+    handle: 'in' | 'out';
+}
+/** Canvas tools. `direct` edits anchors and handles; the shape tools drag out a new shape. */
+type VectorTool = 'select' | 'direct' | 'pen' | 'pencil' | 'rect' | 'ellipse' | 'polygon' | 'star' | 'line';
+declare const VECTOR_TOOLS: readonly VectorTool[];
+/** Keyboard modifiers held during a pointer event. */
+interface VectorModifiers {
+    shift?: boolean;
+    alt?: boolean;
+    /** Cmd on macOS, Ctrl elsewhere. */
+    mod?: boolean;
+}
+/** The eight resize handles of a selection box and the rotation handle. */
+type VectorTransformHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'rotate';
+declare const VECTOR_TRANSFORM_HANDLES: readonly VectorTransformHandle[];
+/** Pan and zoom of the canvas: `screen = document × zoom + (x, y)`. */
+interface VectorViewport {
+    /** Screen position of the document origin, in screen pixels. */
+    x: number;
+    y: number;
+    zoom: number;
+}
+/** What the next shape and pen path are drawn with. */
+interface VectorDefaults extends VectorStyle {
+    /** Sides of the polygon tool (default 6). */
+    polygonSides?: number;
+    /** Points of the star tool (default 5). */
+    starPoints?: number;
+    /** Inner radius of the star tool as a fraction of the outer one (default 0.5). */
+    starInnerRatio?: number;
+    /** Corner radius of the rectangle tool (default 0). */
+    cornerRadius?: number;
+}
+type VectorAlign = 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
+type VectorDistribute = 'horizontal' | 'vertical';
+type VectorBooleanOperation = 'union' | 'subtract' | 'intersect' | 'exclude';
+type VectorArrange = 'front' | 'forward' | 'backward' | 'back';
+
+/**
+ * Vector path geometry: anchors and handles to Bézier paths and back, bounds, hit-testing,
+ * affine transforms, segment splitting, anchor-type conversion and shape factories.
+ */
+
+declare const cloneAnchor: (a: VectorAnchor) => VectorAnchor;
+declare const cloneSubpath: (s: VectorSubpath) => VectorSubpath;
+/** A deep copy of a node (ids kept). */
+declare function cloneVectorNode<T extends VectorNode>(node: T): T;
+declare function cloneVectorDocument(doc: VectorDocument): VectorDocument;
+/** True when the paint draws something (not `null`, `'none'`, `'transparent'` or empty). */
+declare function hasPaint(paint: VectorPaint | undefined): boolean;
+/** Number of segments of a subpath (a closed one has a segment from the last anchor back to the first). */
+declare function subpathSegmentCount(sp: VectorSubpath): number;
+/** Control points of segment `i` of a subpath: 2 for a line, 4 for a cubic. */
+declare function subpathSegment(sp: VectorSubpath, i: number): Point[];
+/** Absolute `M` / `L` / `C` / `Z` commands of subpaths. */
+declare function subpathsToBezier(subpaths: readonly VectorSubpath[]): BezierPath;
+/** The node's outline as Bézier commands. Groups have none. */
+declare function vectorNodeToBezier(node: VectorNode): BezierPath;
+/** SVG path data (`d`) of a path node or subpaths. */
+declare function vectorPathData(input: VectorPathNode | readonly VectorSubpath[], precision?: number): string;
+/** Infers the anchor type from its handles. */
+declare function inferAnchorType(a: VectorAnchor): VectorAnchorType;
+/**
+ * Converts SVG path data or Bézier commands to editable subpaths. Quadratics become cubics,
+ * arcs become cubics, a closing anchor that repeats the first one is merged into it, and
+ * each anchor's type is inferred from its handles.
+ */
+declare function bezierToSubpaths(input: BezierPathInput): VectorSubpath[];
+/** Calls `fn` for every node, depth first, parents before children. */
+declare function walkVectorNodes(nodes: readonly VectorNode[], fn: (node: VectorNode, parent: VectorGroupNode | null, depth: number) => void): void;
+/** Finds a node by id anywhere in the tree. */
+declare function findVectorNode(nodes: readonly VectorNode[], id: string): VectorNode | undefined;
+/** The list that contains node `id` (the root list or a group's children) and its index there. */
+declare function locateVectorNode(nodes: VectorNode[], id: string): {
+    list: VectorNode[];
+    index: number;
+    parent: VectorGroupNode | null;
+} | null;
+/** Every path node in the subtree (a path node itself, or a group's descendants). */
+declare function collectPathNodes(node: VectorNode): VectorPathNode[];
+/** The node's local → parent matrix (identity when it has no `transform`). */
+declare function nodeMatrix(node: VectorNode): AffineMatrix;
+/** A path node's outline in the space `parent` maps to (default: its parent's space). */
+declare function vectorPathWorldBezier(node: VectorPathNode, parent?: AffineMatrix): BezierPath;
+/**
+ * Geometric bounds of a node (stroke width not included) in the space `parent` maps to —
+ * by default the node's parent space, which for top-level nodes is the document. Null when
+ * the node has no points.
+ */
+declare function vectorNodeBounds(node: VectorNode, parent?: AffineMatrix): VectorBounds | null;
+/** The smallest box around all non-null boxes, or null. */
+declare function unionBounds(list: readonly (VectorBounds | null | undefined)[]): VectorBounds | null;
+/** True when two boxes overlap (touching counts). */
+declare function boundsIntersect(a: VectorBounds, b: VectorBounds): boolean;
+/** A box from two corners in any order. */
+declare function boundsFromPoints(a: Vec2, b: Vec2): VectorBounds;
+/**
+ * Whether `p` hits a node: inside its fill (when it has one) or within half its stroke
+ * width plus `tolerance` of its outline. A group is hit when any visible child is.
+ */
+declare function hitTestVectorNode(node: VectorNode, p: Vec2, tolerance?: number, parent?: AffineMatrix): boolean;
+/** The topmost node hit by `p` (skipping hidden and locked ones), or null. */
+declare function hitTestVectorNodes(nodes: readonly VectorNode[], p: Vec2, tolerance?: number): VectorNode | null;
+interface NearestSegment {
+    subpath: number;
+    segment: number;
+    /** Curve parameter 0–1 on the segment. */
+    t: number;
+    point: Vec2;
+    distance: number;
+}
+/** The closest point on any segment of a path node (`p` and the result are in the node's own space). */
+declare function nearestSegment(node: VectorPathNode, p: Vec2): NearestSegment | null;
+declare const IDENTITY_MATRIX: AffineMatrix;
+/** `a` then `b` (apply `a` first). */
+declare function multiplyMatrices(a: AffineMatrix, b: AffineMatrix): AffineMatrix;
+declare const translateMatrix: (dx: number, dy: number) => AffineMatrix;
+declare function scaleMatrix(sx: number, sy: number, origin?: Vec2): AffineMatrix;
+/** Rotation by `degrees` clockwise (y points down) around `origin`. */
+declare function rotateMatrix(degrees: number, origin?: Vec2): AffineMatrix;
+declare function applyMatrix(m: AffineMatrix, p: Vec2): Vec2;
+declare function isIdentityMatrix(m: AffineMatrix, eps?: number): boolean;
+/** The inverse matrix (the identity for a singular one). */
+declare function invertMatrix(m: AffineMatrix): AffineMatrix;
+/** Applies only the linear part (for directions and offsets). */
+declare function applyMatrixLinear(m: AffineMatrix, v: Vec2): Vec2;
+/**
+ * The rotation of a matrix in degrees, clockwise (y down), in (−180, 180]. For a mirrored
+ * matrix it is the rotation left after undoing a horizontal flip, so a flipped rotated shape
+ * keeps its angle.
+ */
+declare function matrixRotation(m: AffineMatrix): number;
+/**
+ * Splits `m` into `residual` then `rigid` (`m = residual × rigid` in apply order): `rigid` is
+ * the nearest rotation plus the translation, `residual` the linear rest (scale, skew,
+ * reflection). An unrotated `m` gives an identity `rigid` and everything in `residual`.
+ */
+declare function decomposeRigid(m: AffineMatrix): {
+    rigid: AffineMatrix;
+    residual: AffineMatrix;
+};
+/**
+ * A copy of the node moved by `m`, given in its parent's space. The node's rotation and
+ * translation go to its rigid `transform`; scale and skew are baked into its anchors (or its
+ * children), so the result draws exactly as `m` says. Stroke widths are kept.
+ */
+declare function transformVectorNode<T extends VectorNode>(node: T, m: AffineMatrix): T;
+/** The node's rotation in degrees (from its `transform` and its ancestors' when `parent` is given). */
+declare function vectorNodeRotation(node: VectorNode, parent?: AffineMatrix): number;
+/** The local → document matrix of node `id` (ancestors' transforms included), or null. */
+declare function vectorWorldMatrix(nodes: readonly VectorNode[], id: string): AffineMatrix | null;
+/** The parent space → document matrix of node `id` (identity for top-level nodes), or null. */
+declare function vectorParentMatrix(nodes: readonly VectorNode[], id: string): AffineMatrix | null;
+/** Moves an anchor and its handles by (dx, dy). */
+declare function translateAnchor(a: VectorAnchor, dx: number, dy: number): VectorAnchor;
+/**
+ * Moves one handle to `pos`, keeping the other in line for `smooth` anchors and mirrored for
+ * `symmetric` ones. With `breakHandles` the anchor becomes a `corner` and only this handle moves.
+ */
+declare function moveAnchorHandle(a: VectorAnchor, side: 'in' | 'out', pos: Vec2, breakHandles?: boolean): VectorAnchor;
+/**
+ * Converts anchor `index` of a subpath. `corner` removes both handles; `smooth` and
+ * `symmetric` keep existing handles in line, or add handles a third of the way to the
+ * neighbours along the line between them.
+ */
+declare function convertAnchor(sp: VectorSubpath, index: number, type: VectorAnchorType): VectorSubpath;
+/**
+ * Inserts an anchor on segment `segment` at parameter `t` without changing the curve's
+ * shape (de Casteljau split). Returns the new subpath and the new anchor's index.
+ */
+declare function insertAnchor(sp: VectorSubpath, segment: number, t: number): {
+    subpath: VectorSubpath;
+    index: number;
+};
+/**
+ * Removes anchors from a subpath. An open subpath with fewer than 2 anchors left, or a
+ * closed one with fewer than 2, is returned with whatever remains (callers drop empty ones).
+ */
+declare function removeAnchors(sp: VectorSubpath, indices: readonly number[]): VectorSubpath;
+/** Reverses a subpath's direction (handles swap sides). */
+declare function reverseSubpath(sp: VectorSubpath): VectorSubpath;
+/** Handle length that makes a cubic approximate a quarter circle. */
+declare const KAPPA = 0.5522847498307936;
+/** A rectangle, optionally with rounded corners (clamped to half the shorter side). */
+declare function rectSubpath(b: VectorBounds, radius?: number): VectorSubpath;
+/** An ellipse inscribed in a box (four smooth anchors). */
+declare function ellipseSubpath(b: VectorBounds): VectorSubpath;
+/** A regular polygon inscribed in a box, first vertex at the top. */
+declare function polygonSubpath(b: VectorBounds, sides?: number): VectorSubpath;
+/** A star inscribed in a box, first point at the top. `innerRatio` is inner / outer radius. */
+declare function starSubpath(b: VectorBounds, points?: number, innerRatio?: number): VectorSubpath;
+/** A straight open line. */
+declare function lineSubpath(a: Vec2, b: Vec2): VectorSubpath;
+/** Rounds every coordinate to `precision` decimals (stable JSON and SVG output). */
+declare function roundSubpaths(subpaths: readonly VectorSubpath[], precision?: number): VectorSubpath[];
+
+/**
+ * SVG export and import for vector documents. Import is DOM-free (works in Node and
+ * workers): it reads `<svg>`, `<g>`, `<path>`, `<rect>`, `<circle>`, `<ellipse>`, `<line>`,
+ * `<polyline>`, `<polygon>`, linear / radial gradients, presentation attributes, `style`
+ * declarations and `transform`s. Text, images, clip paths, masks, filters and `<use>` are
+ * skipped.
+ */
+
+interface VectorSvgExportOptions {
+    /** Decimal places for coordinates (default 3). */
+    precision?: number;
+    /** Draw `document.background` as a full-size rect (default true). */
+    background?: boolean;
+    /** Include hidden nodes with `display="none"` instead of leaving them out (default false). */
+    includeHidden?: boolean;
+    /** Prefix for gradient ids (default `vg-`), to keep ids unique when several SVGs share a page. */
+    idPrefix?: string;
+    /** Indent nested elements (default true). */
+    pretty?: boolean;
+}
+/** A paint as an SVG attribute value plus the gradient def it needs (if any). */
+declare function vectorPaintToSvg(paint: VectorPaint | undefined, gradientId: string): {
+    value: string;
+    gradient: SvgGradientDef | null;
+};
+/** Serializes a vector document as a standalone SVG string. */
+declare function vectorDocumentToSvg(doc: VectorDocument, options?: VectorSvgExportOptions): string;
+interface VectorSvgImportOptions {
+    /** Makes ids for elements without a usable `id` (default `node-1`, `node-2`, …). */
+    createId?: () => string;
+}
+/** Parses an SVG `transform` attribute into one matrix. */
+declare function parseSvgTransform(value: string | undefined): AffineMatrix;
+/** Parses SVG markup into a vector document. Throws when there is no `<svg>` element. */
+declare function parseVectorSvg(svg: string, options?: VectorSvgImportOptions): VectorDocument;
+
+interface VectorSnapOptions {
+    /** Grid size in document units (0 = off, default 0). */
+    grid: number;
+}
+interface VectorEditorOptions {
+    document?: VectorDocument;
+    /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
+    history?: HistoryManager;
+    /** Starting tool (default `select`). */
+    tool?: VectorTool;
+    /** Style and settings for new shapes and paths. */
+    defaults?: VectorDefaults;
+    viewport?: Partial<VectorViewport>;
+    snap?: Partial<VectorSnapOptions>;
+    /** Pick distance for anchors, handles and outlines in screen pixels (default 6). */
+    hitRadius?: number;
+    /** Id factory for new nodes. */
+    createId?: () => string;
+    /** Called after the document changes (edits, undo, redo, load). */
+    onChange?: (document: VectorDocument) => void;
+}
+/** A pointer event as the controller needs it. Positions are in screen pixels relative to the canvas. */
+interface VectorPointerInput extends VectorModifiers {
+    /** 0 = primary, 1 = middle (pans), 2 = secondary. Default 0. */
+    button?: number;
+}
+/** A key press as the controller needs it. */
+interface VectorKeyInput extends VectorModifiers {
+    /** `KeyboardEvent.key`. */
+    key: string;
+}
+/** What the pointer is over. */
+interface VectorHover {
+    nodeId: string | null;
+    anchor?: VectorAnchorRef;
+    handle?: VectorHandleRef;
+    segment?: {
+        nodeId: string;
+        subpath: number;
+        segment: number;
+        t: number;
+        point: Vec2;
+    };
+    transformHandle?: VectorTransformHandle;
+}
+/** The drag in progress, for overlays and status text. */
+type VectorInteraction = {
+    type: 'marquee';
+    bounds: VectorBounds;
+} | {
+    type: 'move';
+    dx: number;
+    dy: number;
+} | {
+    type: 'scale';
+    handle: VectorTransformHandle;
+    sx: number;
+    sy: number;
+} | {
+    type: 'rotate';
+    angle: number;
+} | {
+    type: 'anchors';
+    dx: number;
+    dy: number;
+} | {
+    type: 'handle';
+    ref: VectorHandleRef;
+} | {
+    type: 'draw';
+    tool: VectorTool;
+    nodeId: string;
+    bounds: VectorBounds;
+} | {
+    type: 'pen';
+    nodeId: string;
+} | {
+    type: 'pan';
+};
+/** A snapshot of the editor. The same object is returned until something changes. */
+interface VectorEditorState {
+    document: VectorDocument;
+    tool: VectorTool;
+    /** Selected node ids (top-level nodes or group members picked with the direct tool). */
+    selection: readonly string[];
+    /** Selected anchors (direct tool). */
+    selectedAnchors: readonly VectorAnchorRef[];
+    /** The path whose anchors are being edited, if any. */
+    editingId: string | null;
+    /** Axis-aligned bounds of the selected nodes in document units. */
+    selectionBounds: VectorBounds | null;
+    /** The selection box, rotated with the selection when its nodes share a rotation. */
+    selectionFrame: VectorSelectionFrame | null;
+    viewport: VectorViewport;
+    defaults: Readonly<Required<Pick<VectorDefaults, 'polygonSides' | 'starPoints' | 'starInnerRatio' | 'cornerRadius'>> & VectorStyle>;
+    snap: VectorSnapOptions;
+    hitRadius: number;
+    hover: VectorHover | null;
+    /** A CSS cursor for the canvas. */
+    cursor: string;
+    interaction: VectorInteraction | null;
+    /** The path the pen tool is adding to. */
+    pen: {
+        nodeId: string;
+        subpath: number;
+    } | null;
+    /** Last pointer position in document units (for the pen preview), or null when outside. */
+    pointer: Vec2 | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    /** Bumped on every change. */
+    revision: number;
+}
+type VectorActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+interface AddVectorNodeOptions {
+    /** Group to add into (default: the root). */
+    parentId?: string;
+    /** Position in the parent's list (default: on top). */
+    index?: number;
+    /** Select the new node (default true). */
+    select?: boolean;
+    /** Undo step label. */
+    label?: string;
+}
+/** A shape description for `addShape` (and the agent command of the same name). */
+interface VectorShapeInput extends VectorStyle {
+    kind: 'rect' | 'ellipse' | 'polygon' | 'star' | 'line';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    cornerRadius?: number;
+    sides?: number;
+    points?: number;
+    innerRatio?: number;
+    name?: string;
+}
+/** Clipboard payload type written by `copy()`. */
+declare const VECTOR_CLIPBOARD_TYPE = "pixerate/vector";
+/** Screen distance of the rotation handle above the selection box. */
+declare const VECTOR_ROTATE_HANDLE_OFFSET = 24;
+/** Ids of the path nodes whose anchors are shown (the edited path plus selected paths). */
+declare function getEditablePathIds(state: Pick<VectorEditorState, 'document' | 'selection' | 'editingId' | 'tool' | 'pen'>): string[];
+/** Every anchor drawn on the canvas. */
+declare function getVisibleAnchors(state: Pick<VectorEditorState, 'document' | 'selection' | 'editingId' | 'tool' | 'pen'>): VectorAnchorRef[];
+/**
+ * Handles drawn on the canvas: those of selected anchors and of the segments next to them
+ * (direct tool), or of the last anchor of the pen path.
+ */
+declare function getVisibleHandles(state: Pick<VectorEditorState, 'document' | 'selection' | 'editingId' | 'tool' | 'pen' | 'selectedAnchors'>): VectorHandleRef[];
+/** Looks up an anchor (positions in its node's own space). */
+declare function getAnchor(doc: VectorDocument, ref: VectorAnchorRef): VectorAnchor | undefined;
+/** An anchor with its position and handles in document space (its node's transforms applied). */
+declare function getAnchorWorld(doc: VectorDocument, ref: VectorAnchorRef): {
+    x: number;
+    y: number;
+    in?: Vec2;
+    out?: Vec2;
+    type?: VectorAnchorType;
+} | undefined;
+/**
+ * The selection box: `angle` is the shared rotation of the selected nodes (0 when they
+ * differ), `x / y / width / height` the bounds in the box's own frame (document space
+ * rotated by −angle). A frame point `q` is at `rotateMatrix(angle)` applied to `q`.
+ */
+interface VectorSelectionFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    angle: number;
+}
+/** The selection frame of nodes `ids` (see `VectorSelectionFrame`), or null when they have no points. */
+declare function getVectorSelectionFrame(doc: VectorDocument, ids: readonly string[]): VectorSelectionFrame | null;
+/** Screen positions of the selection box handles for a box given in screen pixels. */
+declare function getTransformHandlePositions(box: VectorBounds): {
+    handle: VectorTransformHandle;
+    x: number;
+    y: number;
+}[];
+/**
+ * Screen geometry of a selection box. `box` and each handle's `x / y` are the unrotated box
+ * in screen pixels; draw them inside a group with `transform` (a `rotate(angle cx cy)`),
+ * or use `screen` for the true on-screen positions (hit-testing).
+ */
+interface VectorSelectionBoxGeometry {
+    box: VectorBounds;
+    angle: number;
+    transform: string;
+    handles: {
+        handle: VectorTransformHandle;
+        x: number;
+        y: number;
+        screen: Vec2;
+    }[];
+    /** The four corners on screen, clockwise from the top left. */
+    corners: Vec2[];
+}
+declare function getVectorSelectionBoxGeometry(frame: VectorSelectionFrame, viewport: VectorViewport): VectorSelectionBoxGeometry;
+/** The resize cursor for a handle of a box rotated by `angle` degrees. */
+declare function vectorResizeCursor(handle: VectorTransformHandle, angle?: number): string;
+declare function vectorToolLabel(tool: VectorTool): string;
+/** Keyboard shortcut of each tool (single letters, no modifiers). */
+declare const VECTOR_TOOL_SHORTCUTS: Readonly<Record<VectorTool, string>>;
+/** Short glyphs for tool buttons (pair them with `vectorToolLabel` for the accessible name). */
+declare const VECTOR_TOOL_GLYPHS: Readonly<Record<VectorTool, string>>;
+/**
+ * Headless state for a vector editor: a document of paths and groups, select / direct /
+ * pen / pencil / shape tools driven by pointer and key events, undo, transforms, boolean
+ * operations, alignment, grouping, SVG import / export and a viewport. Any UI forwards
+ * pointer events (in canvas pixels) and renders `getState()`; `getState()` returns the same
+ * object until something changes, so it works with `useSyncExternalStore` and Svelte runes.
+ */
+declare class VectorEditorController {
+    readonly history: HistoryManager;
+    private doc;
+    private selection;
+    private anchors;
+    private editingId;
+    private pen;
+    private tool;
+    private defaults;
+    private viewport;
+    private snap;
+    private hitRadius;
+    private hover;
+    private pointer;
+    private drag;
+    private interaction;
+    private spaceHeld;
+    private clipboard;
+    private readonly createId;
+    private readonly onChange?;
+    private readonly listeners;
+    private readonly cleanups;
+    private applying;
+    /** Set while a commit records a change that was already applied, so `restore` still reports it. */
+    private committing;
+    private revision;
+    private state;
+    constructor(options?: VectorEditorOptions);
+    /** Stops listening to the history. */
+    destroy(): void;
+    /** The current snapshot (stable until the next change). */
+    getState: () => VectorEditorState;
+    /** Calls `listener` after every change. Returns an unsubscribe function. */
+    subscribe: (listener: (state: VectorEditorState) => void) => (() => void);
+    getDocument(): VectorDocument;
+    getNode(id: string): VectorNode | undefined;
+    private computeState;
+    private notify;
+    private boundsOf;
+    private frameOf;
+    /** Local → document matrix of a node in `doc` (default: the current document). */
+    private worldOf;
+    /** A document point in node `id`'s own space. */
+    private toLocal;
+    private cursorFor;
+    private snapshot;
+    private restore;
+    /** Records the change from `before` to the current state as one undo step. */
+    private commit;
+    /** Runs `fn` (which updates fields) and records it as one undo step. */
+    private change;
+    private setDoc;
+    private replaceNode;
+    private freshIds;
+    private newId;
+    screenToDocument(p: Vec2): Vec2;
+    documentToScreen(p: Vec2): Vec2;
+    setViewport(viewport: Partial<VectorViewport>): void;
+    /** Zooms by `factor` keeping the document point under `screen` in place. */
+    zoomAt(screen: Vec2, factor: number): void;
+    panBy(dx: number, dy: number): void;
+    /** Fits the artboard (or `bounds`) into a canvas of `size` screen pixels. */
+    zoomToFit(size: {
+        width: number;
+        height: number;
+    }, options?: {
+        padding?: number;
+        bounds?: VectorBounds;
+    }): void;
+    /** Zoom at the canvas centre-ish: positive `delta` zooms out (wheel convention). Use with `wheel`. */
+    wheel(screen: Vec2, delta: {
+        x: number;
+        y: number;
+    }, mods?: VectorModifiers): void;
+    setTool(tool: VectorTool): void;
+    setDefaults(defaults: Partial<VectorDefaults>): void;
+    setSnap(snap: Partial<VectorSnapOptions>): void;
+    private snapPoint;
+    private snapDelta;
+    /** Replaces the document. Undoable unless `{ history: false }` (then history is cleared). */
+    setDocument(doc: VectorDocument, options?: {
+        history?: boolean;
+        label?: string;
+    }): void;
+    /** Changes the artboard size or background. */
+    setArtboard(patch: Partial<Pick<VectorDocument, 'width' | 'height' | 'background'>>): void;
+    /** Replaces the document with parsed SVG markup (one undo step). */
+    loadSvg(svg: string, options?: {
+        history?: boolean;
+    }): VectorActionResult;
+    /** Adds the nodes of SVG markup on top of the document, selected. */
+    importSvg(svg: string): VectorActionResult;
+    toSvg(options?: VectorSvgExportOptions): string;
+    toJSON(): VectorDocument;
+    /** Adds a node (ids are kept unless taken). Returns its id. */
+    addNode(node: VectorNode, options?: AddVectorNodeOptions): string;
+    /** Builds a path node for a shape with the current defaults (not added). */
+    createShapeNode(input: VectorShapeInput): VectorPathNode;
+    /** Adds a shape drawn with the current defaults. Returns its id. */
+    addShape(input: VectorShapeInput, options?: AddVectorNodeOptions): string;
+    /** Adds a path from SVG path data. Returns its id. */
+    addPath(d: string, style?: VectorStyle & {
+        name?: string;
+    }, options?: AddVectorNodeOptions): string;
+    private styleFor;
+    /** Merges `patch` into a node (paths take style and geometry; groups name / visibility / opacity). */
+    updateNode(id: string, patch: Partial<VectorPathNode> | Partial<VectorGroupNode>, options?: {
+        label?: string;
+    }): VectorActionResult;
+    /** Applies style (and opacity) to the selected (or given) nodes; groups pass it to every path inside. */
+    setStyle(style: VectorStyle & {
+        opacity?: number;
+    }, ids?: readonly string[], options?: {
+        label?: string;
+    }): VectorActionResult;
+    rename(id: string, name: string): VectorActionResult;
+    setVisible(id: string, visible: boolean): VectorActionResult;
+    setLocked(id: string, locked: boolean): VectorActionResult;
+    /** Removes nodes by id. */
+    removeNodes(ids: readonly string[], options?: {
+        label?: string;
+    }): VectorActionResult;
+    select(ids: readonly string[], options?: {
+        add?: boolean;
+        toggle?: boolean;
+    }): void;
+    selectAll(): void;
+    clearSelection(): void;
+    selectAnchors(refs: readonly VectorAnchorRef[], options?: {
+        add?: boolean;
+    }): void;
+    /** Top-level ids of the selection (members of selected groups are covered by the group). */
+    private selectedRoots;
+    /** `m`, given in a frame rotated by `angle`, as a document-space matrix. */
+    private inFrame;
+    /** Applies a matrix to the selected (or given) nodes as one undo step. */
+    transform(matrix: AffineMatrix, options?: {
+        ids?: readonly string[];
+        label?: string;
+    }): VectorActionResult;
+    /** `doc` with nodes `ids` moved by `m`, given in document space. */
+    private transformed;
+    translate(dx: number, dy: number, options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    /** The selection frame's centre in document space. */
+    private frameCenter;
+    /**
+     * Scales along the selection box's own axes (rotated with the selection when its nodes
+     * share a rotation) around `origin` (default: the box centre, in document space).
+     */
+    scale(sx: number, sy?: number, options?: {
+        ids?: readonly string[];
+        origin?: Vec2;
+    }): VectorActionResult;
+    /** Rotates clockwise by `degrees` around `origin` (default: the selection centre). */
+    rotate(degrees: number, options?: {
+        ids?: readonly string[];
+        origin?: Vec2;
+    }): VectorActionResult;
+    /** Sets each selected (or given) node's rotation to `degrees`, turning it around its own centre. */
+    setRotation(degrees: number, options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    /** Mirrors along the selection box's own axes. */
+    flip(axis: 'horizontal' | 'vertical', options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    /**
+     * Aligns the selected nodes to their combined bounds, or to the artboard when one node is
+     * selected (or `to: 'artboard'`).
+     */
+    align(edge: VectorAlign, options?: {
+        ids?: readonly string[];
+        to?: 'selection' | 'artboard';
+    }): VectorActionResult;
+    /** Spaces three or more selected nodes evenly (equal gaps). */
+    distribute(direction: VectorDistribute, options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    /** Copies the selection (offset by `offset`, default 10, 10) on top of each original. */
+    duplicate(options?: {
+        ids?: readonly string[];
+        offset?: Vec2;
+    }): string[];
+    private withDuplicates;
+    /** Groups the selected nodes (they must share a parent). Returns the group id. */
+    group(options?: {
+        ids?: readonly string[];
+        name?: string;
+    }): string | null;
+    /** Replaces selected groups with their children. */
+    ungroup(options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    /** Changes stacking order within each node's parent. */
+    arrange(op: VectorArrange, options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    /**
+     * Combines the selected paths (two or more) into one with a boolean operation. `subtract`
+     * removes the upper shapes from the lowest one. The result takes the lowest shape's style
+     * and place.
+     */
+    booleanOp(op: VectorBooleanOperation, options?: {
+        ids?: readonly string[];
+    }): string | null;
+    /** Joins the selected paths into one compound path (subpaths kept, lowest style). */
+    combine(options?: {
+        ids?: readonly string[];
+    }): string | null;
+    /** A document-space path mapped into the parent space of node `id`. */
+    private intoParentSpace;
+    /** Splits selected compound paths into one path per subpath. */
+    breakApart(options?: {
+        ids?: readonly string[];
+    }): VectorActionResult;
+    private updateAnchors;
+    /** Moves anchors by a document-space offset (converted into each node's own space). */
+    private movedAnchors;
+    /** Moves one anchor to a document position (handles follow). */
+    moveAnchor(ref: VectorAnchorRef, to: Vec2): VectorActionResult;
+    /** Moves one handle to a document position (see `moveAnchorHandle` for how the opposite handle follows). */
+    moveHandle(ref: VectorHandleRef, to: Vec2, options?: {
+        breakHandles?: boolean;
+    }): VectorActionResult;
+    /** Converts the selected (or given) anchors between corner, smooth and symmetric. */
+    convertAnchors(type: VectorAnchorType, refs?: readonly VectorAnchorRef[]): VectorActionResult;
+    /** Adds an anchor on the nearest segment of `nodeId` to document point `point` (shape unchanged). */
+    insertAnchorAt(nodeId: string, point: Vec2): VectorAnchorRef | null;
+    /** Deletes the selected anchors; empty subpaths and paths go too. */
+    deleteAnchors(refs?: readonly VectorAnchorRef[]): VectorActionResult;
+    /** Opens or closes the subpaths that contain selected anchors (or all subpaths of `nodeId`). */
+    setClosed(closed: boolean, nodeId?: string): VectorActionResult;
+    /** Reverses the direction of every subpath of the selected paths. */
+    reversePaths(ids?: readonly string[]): VectorActionResult;
+    /** Ends the pen path being drawn (a lone anchor is removed). */
+    finishPath(): void;
+    /** Copies the selection. Returns JSON text for the system clipboard (or null). */
+    copy(): string | null;
+    cut(): string | null;
+    /**
+     * Pastes `text` (from `copy()`, or SVG markup) or the internal clipboard, offset by 10, 10.
+     * Returns the new ids.
+     */
+    paste(text?: string, options?: {
+        offset?: Vec2;
+    }): string[];
+    undo(): boolean;
+    redo(): boolean;
+    /** Deletes selected anchors (direct tool) or nodes. */
+    deleteSelection(): VectorActionResult;
+    /** The fields the anchor / handle helpers read, without building a full state. */
+    private view;
+    private tolerance;
+    private hitTransformHandle;
+    private hitHandle;
+    private hitAnchor;
+    /** Deepest unlocked visible path under `p`. */
+    private hitPath;
+    /** Endpoints of open subpaths of unlocked visible paths (pen tool resumes from them). */
+    private openEndpoints;
+    private computeHover;
+    private sameHover;
+    /** Primary button down on the canvas at `screen` (pixels relative to the canvas). */
+    pointerDown(screen: Vec2, input?: VectorPointerInput): void;
+    private downSelect;
+    private downDirect;
+    private downPen;
+    private downPencil;
+    private downShape;
+    /** Pointer moved over the canvas (with or without a button down). */
+    pointerMove(screen: Vec2, input?: VectorPointerInput): void;
+    /** Primary button released. */
+    pointerUp(screen?: Vec2, input?: VectorPointerInput): void;
+    /** The pointer left the canvas. */
+    pointerLeave(): void;
+    /** Abandons the drag in progress (Escape, lost capture). */
+    cancelDrag(): void;
+    /** Double click: select tool enters path editing, direct tool toggles an anchor or adds one. */
+    doubleClick(screen: Vec2): void;
+    /**
+     * Handles editor shortcuts. Returns true when the key was used (call `preventDefault`).
+     * Do not forward keys typed into text inputs.
+     */
+    keyDown(input: VectorKeyInput): boolean;
+    keyUp(input: VectorKeyInput): void;
+}
+/** Scale factors and origin for dragging a selection-box handle to `p`. */
+declare function scaleFor(handle: VectorTransformHandle, b: VectorBounds, p: Vec2, mods?: VectorModifiers): {
+    sx: number;
+    sy: number;
+    origin: Vec2;
+};
+
+interface VectorRenderPath {
+    kind: 'path';
+    id: string;
+    /** SVG `transform` (`matrix(…)`) for a rotated node. */
+    transform?: string;
+    d: string;
+    /** `none`, a colour, or `url(#id)` of a gradient in `defs`. */
+    fill: string;
+    stroke: string;
+    strokeWidth: number;
+    strokeLinecap?: string;
+    strokeLinejoin?: string;
+    strokeDasharray?: string;
+    fillRule: 'nonzero' | 'evenodd';
+    opacity: number;
+}
+interface VectorRenderGroup {
+    kind: 'group';
+    id: string;
+    /** SVG `transform` (`matrix(…)`) for a rotated group. */
+    transform?: string;
+    opacity: number;
+    children: VectorRenderNode[];
+}
+type VectorRenderNode = VectorRenderPath | VectorRenderGroup;
+interface VectorSceneRenderData {
+    /** SVG `transform` for the document layer: `translate(x y) scale(zoom)`. */
+    transform: string;
+    width: number;
+    height: number;
+    background?: string;
+    /** Gradients referenced by `fill` / `stroke` values. */
+    defs: SvgGradientDef[];
+    /** Visible nodes, bottom to top. */
+    nodes: VectorRenderNode[];
+}
+interface VectorRenderAnchor {
+    ref: VectorAnchorRef;
+    /** Screen position. */
+    x: number;
+    y: number;
+    type: VectorAnchorType;
+    selected: boolean;
+    hovered: boolean;
+    /** The pen tool closes the path when this anchor is clicked. */
+    closes: boolean;
+}
+interface VectorRenderHandle {
+    ref: VectorHandleRef;
+    x: number;
+    y: number;
+    /** Screen position of the handle's anchor (draw a line to it). */
+    anchorX: number;
+    anchorY: number;
+    hovered: boolean;
+}
+interface VectorOverlayRenderData {
+    /** Outlines (screen-space path data) of hovered and selected nodes. */
+    outlines: {
+        id: string;
+        d: string;
+        selected: boolean;
+    }[];
+    /**
+     * Selection box with resize and rotate handles (select tool). `x / y / width / height` and
+     * each handle's `x / y` are the unrotated box in screen pixels: draw them inside
+     * `<g transform={transform}>`. `corners` and each handle's `screen` are true positions.
+     */
+    selectionBox: (VectorBounds & {
+        angle: number;
+        transform: string;
+        corners: Vec2[];
+        handles: VectorSelectionBoxGeometry['handles'];
+    }) | null;
+    anchors: VectorRenderAnchor[];
+    handles: VectorRenderHandle[];
+    /** Marquee rectangle, screen space. */
+    marquee: VectorBounds | null;
+    /** Rubber-band segment from the pen path's last anchor to the pointer, screen space. */
+    penPreview: string | null;
+    /** Artboard rectangle, screen space. */
+    artboard: VectorBounds;
+    /** A short status, e.g. "W 120 × H 80" or "45°". */
+    status: string | null;
+}
+/**
+ * The document layer. Render the nodes inside `<g transform={transform}>` and `defs` in a
+ * `<defs>` block. Pass a unique `idPrefix` when several editors share a page.
+ */
+declare function getVectorSceneRenderData(state: Pick<VectorEditorState, 'document' | 'viewport'>, options?: {
+    idPrefix?: string;
+}): VectorSceneRenderData;
+/** The editing overlay in screen pixels. Render it on top of the scene, untransformed. */
+declare function getVectorOverlayRenderData(state: VectorEditorState): VectorOverlayRenderData;
+/** Colours and sizes (screen pixels) the bundled canvases draw the overlay with. */
+declare const VECTOR_OVERLAY_THEME: {
+    readonly accent: "#0ea5e9";
+    readonly handleFill: "#ffffff";
+    readonly marqueeFill: "rgba(14, 165, 233, 0.08)";
+    readonly transformHandleSize: 8;
+    readonly anchorSize: 7;
+    readonly handleRadius: 3.5;
+};
+interface ModifierEventLike {
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+}
+/** Modifiers of a mouse / pointer / key event (`mod` is Cmd or Ctrl). */
+declare function toVectorModifiers(event: ModifierEventLike): {
+    shift: boolean;
+    alt: boolean;
+    mod: boolean;
+};
+/** A pointer event as `VectorEditorController.pointerDown/Move/Up` input. */
+declare function toVectorPointerInput(event: ModifierEventLike & {
+    button?: number;
+}): {
+    button: number | undefined;
+    shift: boolean;
+    alt: boolean;
+    mod: boolean;
+};
+/** A key event as `VectorEditorController.keyDown/keyUp` input. */
+declare function toVectorKeyInput(event: ModifierEventLike & {
+    key: string;
+}): {
+    shift: boolean;
+    alt: boolean;
+    mod: boolean;
+    key: string;
+};
+/** True for targets that should keep their own keys (inputs, textareas, contenteditable). */
+declare function isVectorTextTarget(target: unknown): boolean;
+/** Style shown in a style panel: the first selected path's, with `mixed` flags when paths differ. */
+interface VectorSelectionStyle {
+    fill: VectorPaint;
+    stroke: VectorPaint;
+    strokeWidth: number;
+    opacity: number;
+    mixed: {
+        fill: boolean;
+        stroke: boolean;
+        strokeWidth: boolean;
+        opacity: boolean;
+    };
+    /** Ids of the paths the style applies to. */
+    pathIds: string[];
+}
+declare function getVectorSelectionStyle(state: Pick<VectorEditorState, 'document' | 'selection'>): VectorSelectionStyle | null;
+/** A paint as `#rrggbb` for `<input type="color">`, or null for none, gradients and other CSS colours. */
+declare function vectorPaintToHex(paint: VectorPaint | undefined): string | null;
+
+interface VectorCommandOptions {
+    /** Id prefix (default `vector.`); use one per editor when several are registered. */
+    prefix?: string;
+    /** Palette group (default `Vector`). */
+    group?: string;
+    /** Command scope. Omit for global commands. */
+    scope?: string;
+}
+/** A node as listed for agents. */
+interface VectorNodeListing {
+    id: string;
+    type: 'path' | 'group';
+    name?: string;
+    depth: number;
+    /** Axis-aligned bounds in document units. */
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    /** Rotation in degrees, clockwise (ancestors' rotations included). */
+    rotation: number;
+    visible: boolean;
+    locked: boolean;
+    selected: boolean;
+    fill?: unknown;
+    stroke?: unknown;
+    strokeWidth?: number;
+    /** SVG path data (paths only). */
+    d?: string;
+    children?: number;
+}
+/**
+ * Palette and agent commands for a vector editor: list, select, add shapes and paths, style,
+ * transform, align, arrange, group, boolean operations and SVG import / export. Register them
+ * in a `CommandRegistry` and agents get them through `createCommandToolProvider`. Failures
+ * throw sentences, which the registry returns as `{ ok: false, code: 'failed', message }`.
+ */
+declare function createVectorCommands(controller: VectorEditorController, options?: VectorCommandOptions): CommandSpec[];
+
+export { type AddVectorNodeOptions, AffineMatrix, IDENTITY_MATRIX, KAPPA, type NearestSegment, SvgGradientDef, VECTOR_CLIPBOARD_TYPE, VECTOR_OVERLAY_THEME, VECTOR_ROTATE_HANDLE_OFFSET, VECTOR_TOOLS, VECTOR_TOOL_GLYPHS, VECTOR_TOOL_SHORTCUTS, VECTOR_TRANSFORM_HANDLES, type Vec2, type VectorActionResult, type VectorAlign, type VectorAnchor, type VectorAnchorRef, type VectorAnchorType, type VectorArrange, type VectorBooleanOperation, type VectorBounds, type VectorCommandOptions, type VectorDefaults, type VectorDistribute, type VectorDocument, VectorEditorController, type VectorEditorOptions, type VectorEditorState, type VectorFillRule, type VectorGroupNode, type VectorHandleRef, type VectorHover, type VectorInteraction, type VectorKeyInput, type VectorLineCap, type VectorLineJoin, type VectorMatrix, type VectorModifiers, type VectorNode, type VectorNodeListing, type VectorOverlayRenderData, type VectorPaint, type VectorPathNode, type VectorPointerInput, type VectorRenderAnchor, type VectorRenderGroup, type VectorRenderHandle, type VectorRenderNode, type VectorRenderPath, type VectorSceneRenderData, type VectorSelectionBoxGeometry, type VectorSelectionFrame, type VectorSelectionStyle, type VectorShapeInput, type VectorSnapOptions, type VectorStyle, type VectorSubpath, type VectorSvgExportOptions, type VectorSvgImportOptions, type VectorTool, type VectorTransformHandle, type VectorViewport, applyMatrix, applyMatrixLinear, bezierToSubpaths, boundsFromPoints, boundsIntersect, cloneAnchor, cloneSubpath, cloneVectorDocument, cloneVectorNode, collectPathNodes, convertAnchor, createVectorCommands, decomposeRigid, ellipseSubpath, findVectorNode, getAnchor, getAnchorWorld, getEditablePathIds, getTransformHandlePositions, getVectorOverlayRenderData, getVectorSceneRenderData, getVectorSelectionBoxGeometry, getVectorSelectionFrame, getVectorSelectionStyle, getVisibleAnchors, getVisibleHandles, hasPaint, hitTestVectorNode, hitTestVectorNodes, inferAnchorType, insertAnchor, invertMatrix, isIdentityMatrix, isVectorTextTarget, lineSubpath, locateVectorNode, matrixRotation, moveAnchorHandle, multiplyMatrices, nearestSegment, nodeMatrix, parseSvgTransform, parseVectorSvg, polygonSubpath, rectSubpath, removeAnchors, reverseSubpath, rotateMatrix, roundSubpaths, scaleFor, scaleMatrix, starSubpath, subpathSegment, subpathSegmentCount, subpathsToBezier, toVectorKeyInput, toVectorModifiers, toVectorPointerInput, transformVectorNode, translateAnchor, translateMatrix, unionBounds, vectorDocumentToSvg, vectorNodeBounds, vectorNodeRotation, vectorNodeToBezier, vectorPaintToHex, vectorPaintToSvg, vectorParentMatrix, vectorPathData, vectorPathWorldBezier, vectorResizeCursor, vectorToolLabel, vectorWorldMatrix, walkVectorNodes };