@pixerate/editor 0.32.0 → 0.34.0

package/dist/vector/index.d.cts

@@ -1,10 +1,12 @@
-import { C as CanvasGradientDef, A as AffineMatrix, B as BezierPathInput, a as BezierPath, S as SvgGradientDef } from '../bezier-6KPx3w7Z.cjs';
+import { C as CanvasGradientDef, A as AffineMatrix, B as BezierPathInput, a as BezierPath, S as SvgGradientDef } from '../bezier-D8bsO-L0.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;
@@ -63,6 +65,13 @@ interface VectorNodeBase {
     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 {
@@ -178,8 +187,16 @@ declare function locateVectorNode(nodes: VectorNode[], id: string): {
 } | null;
 /** Every path node in the subtree (a path node itself, or a group's descendants). */
 declare function collectPathNodes(node: VectorNode): VectorPathNode[];
-/** Geometric bounds of a node (stroke width not included), or null when it has no points. */
-declare function vectorNodeBounds(node: VectorNode): VectorBounds | null;
+/** 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). */
@@ -190,7 +207,7 @@ 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): boolean;
+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 {
@@ -201,7 +218,7 @@ interface NearestSegment {
     point: Vec2;
     distance: number;
 }
-/** The closest point on any segment of a path node. */
+/** 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). */
@@ -211,8 +228,38 @@ declare function scaleMatrix(sx: number, sy: number, origin?: Vec2): AffineMatri
 /** 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;
-/** A copy of the node with every anchor and handle transformed. Stroke widths are kept. */
+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;
 /**
@@ -292,10 +339,222 @@ 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;
 
+/**
+ * What a guide line shows: `align` lines run from a target through the snapped point or box,
+ * `construction` lines from where a drawn point leaves, `spacing` marks equal gaps and `size`
+ * the side whose length matches another object's.
+ */
+type VectorGuideKind = 'align' | 'construction' | 'spacing' | 'size';
+/** A guide line in document units. */
+interface VectorGuideLine {
+    kind: VectorGuideKind;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** What a point or box snapped to. */
+type VectorSnapKind = 'anchor' | 'centre' | 'intersect' | 'perpendicular' | 'tangent' | 'path' | 'construction' | 'align' | 'spacing' | 'size';
+/** A guide label in document units: the snap kind's name, or a distance for gaps and sizes. */
+interface VectorGuideLabel {
+    kind: VectorSnapKind;
+    x: number;
+    y: number;
+    text: string;
+}
+interface VectorSnapGuides {
+    lines: VectorGuideLine[];
+    labels: VectorGuideLabel[];
+}
+interface VectorPointSnap extends VectorSnapGuides {
+    point: Vec2;
+    /** The rule that placed the point, or null when nothing was in reach. */
+    kind: VectorSnapKind | null;
+    /** Whether x / y were set by a target (for falling back to the grid on the other axis). */
+    x: boolean;
+    y: boolean;
+}
+interface VectorRectSnap extends VectorSnapGuides {
+    /** Correction to add to the move. */
+    dx: number;
+    dy: number;
+    x: boolean;
+    y: boolean;
+}
+interface VectorScaleSnap extends VectorSnapGuides {
+    sx: number;
+    sy: number;
+    snapped: boolean;
+}
+/**
+ * The point a drawn point leaves from (the anchor before it, a shape's start, a handle's
+ * anchor) and how it keeps to it.
+ */
+interface VectorSnapLeave {
+    at: Vec2;
+    /**
+     * Shift held: keep to 45° steps round `at` (`angle`), to a diagonal (`square`, a box's
+     * corner) or to the nearer axis (`axis`, a dragged point).
+     */
+    constrain?: 'angle' | 'square' | 'axis' | null;
+    /** Construction guide angles through `at`, degrees counter-clockwise on screen. */
+    angles?: readonly number[];
+    /** Snap to the perpendicular foot and tangent points from `at` on paths (default true). */
+    curves?: boolean;
+}
+/** The construction guide angles new editors start with. */
+declare const VECTOR_CONSTRUCTION_ANGLES: readonly number[];
+/** Where `constrain` puts `p` (unchanged without one). */
+declare function constrainToLeave(leave: VectorSnapLeave | null | undefined, p: Vec2): Vec2;
+/**
+ * Snap targets in document space, gathered once per gesture. Build them with `forMove`,
+ * `forResize`, `forDrawing`, `forAnchorDrag` or `forHandle`, then call `snapFrom`,
+ * `snapRect` or `snapScale` on every pointer move. Tolerances are in document units (screen
+ * pixels divided by the zoom).
+ */
+declare class VectorSnapTargets {
+    private readonly points;
+    private readonly xs;
+    private readonly ys;
+    private readonly segments;
+    /** Bounds of the objects a moved box spaces itself evenly with. */
+    private readonly boxes;
+    /** Side lengths of the other objects (in their own frames), which a resize may match. */
+    private readonly sizes;
+    private constructor();
+    /** How many targets of each sort were gathered. */
+    get counts(): {
+        points: number;
+        lines: number;
+        segments: number;
+        boxes: number;
+    };
+    /** Targets for moving nodes `ids`: the other art's anchors, bounds and centres, the artboard, and boxes to space evenly with. */
+    static forMove(doc: VectorDocument, ids: readonly string[]): VectorSnapTargets;
+    /** Targets for resizing nodes `ids`: as for a move, plus the other objects' sizes. */
+    static forResize(doc: VectorDocument, ids: readonly string[]): VectorSnapTargets;
+    /**
+     * Targets for a drawn point (pen, shape tools): the art but `exclude`, its anchors (as
+     * points and in line), centres, edges and segments. The anchors and segments of `exclude`
+     * (the path being drawn, whose bounds grow with it) stay targets.
+     */
+    static forDrawing(doc: VectorDocument, exclude?: readonly string[]): VectorSnapTargets;
+    /**
+     * Targets for dragging anchors: the other art with its segments, and the anchors and
+     * segments that stay put on the paths being reshaped (their bounds move along, so they are
+     * no targets). The moving anchors are left out.
+     */
+    static forAnchorDrag(doc: VectorDocument, anchors: readonly VectorAnchorRef[]): VectorSnapTargets;
+    /**
+     * Targets for dragging a handle of path `nodeId`: the other art and that path's anchors
+     * (its bounds and the segments through the handle move with it, so they would chase it).
+     */
+    static forHandle(doc: VectorDocument, nodeId: string): VectorSnapTargets;
+    /** The anchors of the paths `ids` as targets (on them and in line), and their segments when `segments`. */
+    private pushPaths;
+    private pushAnchor;
+    /** The segments of `sp` (mapped by `m`) that stay put while the anchors `moving` accepts move. */
+    private pushSegments;
+    private pushRect;
+    /** Sorts the targets for `within` (stable: of targets alike, the first gathered wins). */
+    private index;
+    /**
+     * Gathers targets from the artboard and every visible node but `exclude` (and what is inside
+     * those): each leaf's anchors (also as lines for `drawing`), its segments (`segments`,
+     * `drawing`), its bounds' corners as lines and its centre; and the top-level objects' boxes and
+     * sizes (inside a group holding an excluded node, that group's other members).
+     */
+    private static collect;
+    /** Snaps a single point (see `snapFrom`). */
+    snapPoint(p: Vec2, tol: number): VectorPointSnap;
+    /**
+     * Snaps a point `p`, drawn or dragged from `leave` when given. With `leave.constrain` it keeps
+     * to its angle round `leave.at`, sliding along that way into line with the nearest target.
+     * Otherwise it lands, in order, on an anchor or centre, an intersection of two paths, the
+     * perpendicular foot or a tangent point from `leave.at`, a path, a construction guide
+     * through `leave.at` (where a target's line crosses it if one does nearby), or else lines up
+     * with targets on x and y.
+     */
+    snapFrom(p: Vec2, leave: VectorSnapLeave | null | undefined, tol: number): VectorPointSnap;
+    private label;
+    /** The anchor or centre nearest `p`, within `tol`. */
+    private nearestPoint;
+    /**
+     * Slides `q`, on the line through `at` along `dir` (beyond `at` only for a `ray`), to where
+     * the nearest target line crosses it, at most twice `tol` away: where it lands and the
+     * target point that line comes from.
+     */
+    private slide;
+    /** The guides of a point `q` slid into line with the target at `from`: the line and "align", or the target's own label when `q` sits on it. */
+    private linedUp;
+    /** Target segments whose control box reaches `p` and which pass within `tol` of it, nearest first. */
+    private segmentsNear;
+    private onSegment;
+    /** Where two of the target segments near `p` cross, the crossing nearest `p` within `tol`. */
+    private crossing;
+    /**
+     * The foot of a perpendicular, or a tangent point, from `base` on a target segment near `p`
+     * (within `tol` of it): roots of `(B(t) − base) · B′(t)` and `(B(t) − base) × B′(t)`
+     * bracketed by sign changes of samples and narrowed by bisection.
+     */
+    private curvePoint;
+    /**
+     * Snaps a moving box `r` (the moved selection's bounds): its edge or centre nearest a target
+     * line on each axis (`axes` limits which may move). With `spacing`, an axis that lines up
+     * with nothing spaces the box evenly in its row or column. Returns the correction and guides.
+     */
+    snapRect(r: VectorBounds, tol: number, options?: {
+        spacing?: boolean;
+        axes?: {
+            x?: boolean;
+            y?: boolean;
+        };
+    }): VectorRectSnap;
+    /**
+     * Equal spacing along x (`horizontal`) or y for the moved box `r`, among the objects of its
+     * row (column): the shift within `tol` that centres it between its neighbours, or leaves it
+     * as far from the neighbour before or after it as two other objects of the row are apart;
+     * and the gaps that are equal then, as (start, end, where across).
+     */
+    private evenSpacing;
+    /** A gap mark: a line across the gap with a tick at each end, and its length as a label. */
+    private gapMarks;
+    /** The other objects' side length nearest `length`, within `tol`, or null. */
+    matchSize(length: number, tol: number): number | null;
+    /**
+     * Snaps a selection-box resize. `sx / sy` are the scale `scaleFor` gave for dragging
+     * `handle` of `frame` (in the box's own, possibly rotated frame), `mods.shift` keeps the
+     * proportions and `mods.alt` scales about the centre. The handle lands on an anchor or
+     * centre within `tol`, else the corner or the side it moves lines up with the nearest
+     * target, whatever the box's angle; a handle with one way to go (a side, or a proportional
+     * corner) slides along it until one of them is on a target. An axis that snaps to nothing
+     * may match another object's width or height instead.
+     */
+    snapScale(frame: VectorBounds & {
+        angle: number;
+    }, handle: Exclude<VectorTransformHandle, 'rotate'>, sx: number, sy: number, mods: {
+        shift?: boolean;
+        alt?: boolean;
+    }, tol: number): VectorScaleSnap;
+}
+
 interface VectorSnapOptions {
-    /** Grid size in document units (0 = off, default 0). */
+    /** Grid size in document units (0 = off, default 0). Points and boxes that snap to no object snap to it. */
     grid: number;
+    /**
+     * Snap to other objects (default true): anchors, paths and their intersections, bounding-box
+     * edges and centres, the artboard, construction angles, equal spacing and matching sizes.
+     */
+    objects: boolean;
+    /** Show smart guide lines and labels while snapping (default true). */
+    guides: boolean;
+    /** How near a target pulls, in screen pixels (default 5). */
+    threshold: number;
+    /** Construction guide angles through the point a drawn point leaves from, in degrees (default 0, 45, 90, 135). */
+    angles: readonly number[];
 }
+/** Snap options new editors start with. Hold Cmd / Ctrl (`mod`) during a drag to bypass snapping. */
+declare const DEFAULT_VECTOR_SNAP: Readonly<VectorSnapOptions>;
 interface VectorEditorOptions {
     document?: VectorDocument;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
@@ -381,11 +640,15 @@ interface VectorEditorState {
     selectedAnchors: readonly VectorAnchorRef[];
     /** The path whose anchors are being edited, if any. */
     editingId: string | null;
-    /** Bounds of the selected nodes in document units. */
+    /** 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;
+    /** Smart guides of the snap in progress, in document units (null when there are none). */
+    guides: VectorSnapGuides | null;
     hitRadius: number;
     hover: VectorHover | null;
     /** A CSS cursor for the canvas. */
@@ -447,14 +710,57 @@ declare function getVisibleAnchors(state: Pick<VectorEditorState, 'document' | '
  * (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. */
+/** 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>>;
@@ -483,6 +789,11 @@ declare class VectorEditorController {
     private pointer;
     private drag;
     private interaction;
+    private guides;
+    /** Whether the last `snapDrawn` landed on an object (guides may be hidden). */
+    private snappedToObject;
+    /** Drawing targets for hovering the pen and shape tools, kept while the document and the excluded path stay the same. */
+    private hoverTargets;
     private spaceHeld;
     private clipboard;
     private readonly createId;
@@ -506,6 +817,11 @@ declare class VectorEditorController {
     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;
@@ -539,8 +855,23 @@ declare class VectorEditorController {
     setTool(tool: VectorTool): void;
     setDefaults(defaults: Partial<VectorDefaults>): void;
     setSnap(snap: Partial<VectorSnapOptions>): void;
+    /** Turns object snapping on or off (the toolbar's snapping toggle). */
+    toggleSnapping(on?: boolean): void;
+    private gridValue;
     private snapPoint;
-    private snapDelta;
+    /** The pull distance in document units. */
+    private snapTolerance;
+    private setGuides;
+    /**
+     * Where a drawn or dragged point `p` goes: onto the smart guide `targets` (gathered by
+     * `gather` when missing), else onto the grid, kept to `leave`'s constraint. Cmd / Ctrl
+     * bypasses snapping.
+     */
+    private snapDrawn;
+    /** Drawing targets for the pen and shape tools, reused while the document stays the same. */
+    private drawingTargets;
+    /** Where the pointer at `p` would place a point with the pen or a shape tool (and the guides showing why). */
+    private hoverSnap;
     /** Replaces the document. Undoable unless `{ history: false }` (then history is cleared). */
     setDocument(doc: VectorDocument, options?: {
         history?: boolean;
@@ -595,16 +926,24 @@ declare class VectorEditorController {
     }): 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;
-    /** Scales around `origin` (default: the selection centre). */
+    /** 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;
@@ -614,6 +953,11 @@ declare class VectorEditorController {
         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;
@@ -660,21 +1004,24 @@ declare class VectorEditorController {
     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 position (handles follow). */
+    /** Moves one anchor to a document position (handles follow). */
     moveAnchor(ref: VectorAnchorRef, to: Vec2): VectorActionResult;
-    /** Moves one handle (see `moveAnchorHandle` for how the opposite handle follows). */
+    /** 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 `point` (shape unchanged). */
+    /** 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;
@@ -719,6 +1066,12 @@ declare class VectorEditorController {
     private downShape;
     /** Pointer moved over the canvas (with or without a button down). */
     pointerMove(screen: Vec2, input?: VectorPointerInput): void;
+    /** Snaps a move of the selection by (dx, dy): its bounds line up with targets or space evenly, else go to the grid. */
+    private snapMove;
+    /** The anchor a point drag snaps by, where it started: the grabbed one, else the moving one nearest the press. */
+    private leadAnchor;
+    /** A shape's dragged corner moved so its width or height matches another object's, when one is within reach. */
+    private matchShapeSize;
     /** Primary button released. */
     pointerUp(screen?: Vec2, input?: VectorPointerInput): void;
     /** The pointer left the canvas. */
@@ -744,6 +1097,8 @@ declare function scaleFor(handle: VectorTransformHandle, b: VectorBounds, p: Vec
 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;
@@ -758,6 +1113,8 @@ interface VectorRenderPath {
 interface VectorRenderGroup {
     kind: 'group';
     id: string;
+    /** SVG `transform` (`matrix(…)`) for a rotated group. */
+    transform?: string;
     opacity: number;
     children: VectorRenderNode[];
 }
@@ -793,6 +1150,21 @@ interface VectorRenderHandle {
     anchorY: number;
     hovered: boolean;
 }
+/** A smart guide line in screen pixels. */
+interface VectorRenderGuideLine {
+    kind: VectorGuideKind;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** A smart guide label ("anchor", "intersect", "align", "centre", a gap or a size) at a screen position. */
+interface VectorRenderGuideLabel {
+    kind: VectorSnapKind;
+    x: number;
+    y: number;
+    text: string;
+}
 interface VectorOverlayRenderData {
     /** Outlines (screen-space path data) of hovered and selected nodes. */
     outlines: {
@@ -800,18 +1172,17 @@ interface VectorOverlayRenderData {
         d: string;
         selected: boolean;
     }[];
-    /** Selection box with resize and rotate handles (select tool), screen space. */
-    selectionBox: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-        handles: {
-            handle: VectorTransformHandle;
-            x: number;
-            y: number;
-        }[];
-    } | null;
+    /**
+     * 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. */
@@ -820,6 +1191,11 @@ interface VectorOverlayRenderData {
     penPreview: string | null;
     /** Artboard rectangle, screen space. */
     artboard: VectorBounds;
+    /** Smart guides of the snap in progress, screen space (empty when nothing snapped). */
+    guides: {
+        lines: VectorRenderGuideLine[];
+        labels: VectorRenderGuideLabel[];
+    };
     /** A short status, e.g. "W 120 × H 80" or "45°". */
     status: string | null;
 }
@@ -835,6 +1211,8 @@ declare function getVectorOverlayRenderData(state: VectorEditorState): VectorOve
 /** Colours and sizes (screen pixels) the bundled canvases draw the overlay with. */
 declare const VECTOR_OVERLAY_THEME: {
     readonly accent: "#0ea5e9";
+    /** Smart guide lines and labels. */
+    readonly guide: "#ff3dfc";
     readonly handleFill: "#ffffff";
     readonly marqueeFill: "rgba(14, 165, 233, 0.08)";
     readonly transformHandleSize: 8;
@@ -906,12 +1284,15 @@ interface VectorNodeListing {
     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;
@@ -930,4 +1311,4 @@ interface VectorNodeListing {
  */
 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 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 VectorSelectionStyle, type VectorShapeInput, type VectorSnapOptions, type VectorStyle, type VectorSubpath, type VectorSvgExportOptions, type VectorSvgImportOptions, type VectorTool, type VectorTransformHandle, type VectorViewport, applyMatrix, bezierToSubpaths, boundsFromPoints, boundsIntersect, cloneAnchor, cloneSubpath, cloneVectorDocument, cloneVectorNode, collectPathNodes, convertAnchor, createVectorCommands, ellipseSubpath, findVectorNode, getAnchor, getEditablePathIds, getTransformHandlePositions, getVectorOverlayRenderData, getVectorSceneRenderData, getVectorSelectionStyle, getVisibleAnchors, getVisibleHandles, hasPaint, hitTestVectorNode, hitTestVectorNodes, inferAnchorType, insertAnchor, isVectorTextTarget, lineSubpath, locateVectorNode, moveAnchorHandle, multiplyMatrices, nearestSegment, parseSvgTransform, parseVectorSvg, polygonSubpath, rectSubpath, removeAnchors, reverseSubpath, rotateMatrix, roundSubpaths, scaleFor, scaleMatrix, starSubpath, subpathSegment, subpathSegmentCount, subpathsToBezier, toVectorKeyInput, toVectorModifiers, toVectorPointerInput, transformVectorNode, translateAnchor, translateMatrix, unionBounds, vectorDocumentToSvg, vectorNodeBounds, vectorNodeToBezier, vectorPaintToHex, vectorPaintToSvg, vectorPathData, vectorToolLabel, walkVectorNodes };
+export { type AddVectorNodeOptions, AffineMatrix, DEFAULT_VECTOR_SNAP, IDENTITY_MATRIX, KAPPA, type NearestSegment, SvgGradientDef, VECTOR_CLIPBOARD_TYPE, VECTOR_CONSTRUCTION_ANGLES, 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 VectorGuideKind, type VectorGuideLabel, type VectorGuideLine, 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 VectorPointSnap, type VectorPointerInput, type VectorRectSnap, type VectorRenderAnchor, type VectorRenderGroup, type VectorRenderGuideLabel, type VectorRenderGuideLine, type VectorRenderHandle, type VectorRenderNode, type VectorRenderPath, type VectorScaleSnap, type VectorSceneRenderData, type VectorSelectionBoxGeometry, type VectorSelectionFrame, type VectorSelectionStyle, type VectorShapeInput, type VectorSnapGuides, type VectorSnapKind, type VectorSnapLeave, type VectorSnapOptions, VectorSnapTargets, type VectorStyle, type VectorSubpath, type VectorSvgExportOptions, type VectorSvgImportOptions, type VectorTool, type VectorTransformHandle, type VectorViewport, applyMatrix, applyMatrixLinear, bezierToSubpaths, boundsFromPoints, boundsIntersect, cloneAnchor, cloneSubpath, cloneVectorDocument, cloneVectorNode, collectPathNodes, constrainToLeave, 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 };