@pixerate/editor 0.33.0 → 0.35.0

package/dist/vector/index.d.cts

@@ -1,4 +1,4 @@
-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';
@@ -109,8 +109,12 @@ interface VectorAnchorRef {
 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';
+/**
+ * Canvas tools. `direct` edits anchors, handles and segments; the shape tools drag out a new
+ * shape; `scissors` cuts a path at a point, `knife` cuts filled shapes along a freehand stroke
+ * and `eraser` rubs out the area under one.
+ */
+type VectorTool = 'select' | 'direct' | 'pen' | 'pencil' | 'rect' | 'ellipse' | 'polygon' | 'star' | 'line' | 'scissors' | 'knife' | 'eraser';
 declare const VECTOR_TOOLS: readonly VectorTool[];
 /** Keyboard modifiers held during a pointer event. */
 interface VectorModifiers {
@@ -144,6 +148,14 @@ type VectorAlign = 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
 type VectorDistribute = 'horizontal' | 'vertical';
 type VectorBooleanOperation = 'union' | 'subtract' | 'intersect' | 'exclude';
 type VectorArrange = 'front' | 'forward' | 'backward' | 'back';
+/** Average: line anchors up on a horizontal line (same y), a vertical one (same x), or both. */
+type VectorAverageAxis = 'horizontal' | 'vertical' | 'both';
+/** Identifies one segment of a path node: from anchor `segment` to the next. */
+interface VectorSegmentRef {
+    nodeId: string;
+    subpath: number;
+    segment: number;
+}
 
 /**
  * Vector path geometry: anchors and handles to Bézier paths and back, bounds, hit-testing,
@@ -339,10 +351,245 @@ 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>;
+/** How path-editing gestures and the pencil, knife and eraser behave. */
+interface VectorPathEditOptions {
+    /**
+     * Deleting anchors refits the neighbouring handles so the shape stays (default true). Off,
+     * the neighbours are joined with their handles as they are.
+     */
+    keepShapeOnDelete: boolean;
+    /**
+     * Dragging one anchor with the direct tool bends its two segments like the Curvature tool,
+     * keeping the segments beyond still (default false). Alt held during the drag flips it.
+     */
+    curvatureMoves: boolean;
+    /** Pencil lazy-mouse smoothing, 0–1: the pulled string is up to 100 screen pixels long (default 0, off). */
+    pencilSmoothing: number;
+    /** Pencil strokes that look like a line, rectangle, ellipse or polygon become that shape (default false). */
+    recognizeShapes: boolean;
+    /** Eraser diameter in document units (default 10). */
+    eraserSize: number;
 }
+/** Path-editing options new editors start with. */
+declare const DEFAULT_VECTOR_PATH_EDIT: Readonly<VectorPathEditOptions>;
+/** Longest pencil lazy-mouse string (at smoothing 1), in screen pixels. */
+declare const VECTOR_PENCIL_STRING_PX = 100;
 interface VectorEditorOptions {
     document?: VectorDocument;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
@@ -353,6 +600,7 @@ interface VectorEditorOptions {
     defaults?: VectorDefaults;
     viewport?: Partial<VectorViewport>;
     snap?: Partial<VectorSnapOptions>;
+    editing?: Partial<VectorPathEditOptions>;
     /** Pick distance for anchors, handles and outlines in screen pixels (default 6). */
     hitRadius?: number;
     /** Id factory for new nodes. */
@@ -375,6 +623,7 @@ interface VectorHover {
     nodeId: string | null;
     anchor?: VectorAnchorRef;
     handle?: VectorHandleRef;
+    /** A segment under the pointer (direct tool and scissors); `point` is in document space. */
     segment?: {
         nodeId: string;
         subpath: number;
@@ -407,11 +656,20 @@ type VectorInteraction = {
 } | {
     type: 'handle';
     ref: VectorHandleRef;
+} | {
+    type: 'bend';
+    ref: VectorSegmentRef;
 } | {
     type: 'draw';
     tool: VectorTool;
     nodeId: string;
     bounds: VectorBounds;
+    string?: [Vec2, Vec2];
+} | {
+    type: 'stroke';
+    tool: 'knife' | 'eraser';
+    points: Vec2[];
+    width: number;
 } | {
     type: 'pen';
     nodeId: string;
@@ -435,6 +693,9 @@ interface VectorEditorState {
     viewport: VectorViewport;
     defaults: Readonly<Required<Pick<VectorDefaults, 'polygonSides' | 'starPoints' | 'starInnerRatio' | 'cornerRadius'>> & VectorStyle>;
     snap: VectorSnapOptions;
+    editing: VectorPathEditOptions;
+    /** 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. */
@@ -570,11 +831,17 @@ declare class VectorEditorController {
     private defaults;
     private viewport;
     private snap;
+    private editing;
     private hitRadius;
     private hover;
     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;
@@ -636,8 +903,25 @@ declare class VectorEditorController {
     setTool(tool: VectorTool): void;
     setDefaults(defaults: Partial<VectorDefaults>): void;
     setSnap(snap: Partial<VectorSnapOptions>): void;
+    /** Changes how deleting, dragging anchors, the pencil and the eraser behave. */
+    setEditing(editing: Partial<VectorPathEditOptions>): 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;
@@ -779,8 +1063,22 @@ declare class VectorEditorController {
     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 anchor to a document position. Its handles follow; with `curvature` (default:
+     * the `curvatureMoves` setting) its two segments bend instead, as the Curvature tool does.
+     */
+    moveAnchor(ref: VectorAnchorRef, to: Vec2, options?: {
+        curvature?: boolean;
+    }): VectorActionResult;
+    /** `doc` with anchor `ref` moved to document point `to` by a Curvature-tool move. */
+    private curvatureMoved;
+    /** `doc` with segment `ref` bent through document point `p` at parameter `t`. */
+    private bent;
+    /**
+     * Bends a segment so the curve passes through document point `to` at parameter `t`
+     * (default 0.5, clamped to 0.05–0.95); see `bendSegment` in `pathEdit`.
+     */
+    bendSegment(ref: VectorSegmentRef, to: Vec2, t?: number): VectorActionResult;
     /** Moves one handle to a document position (see `moveAnchorHandle` for how the opposite handle follows). */
     moveHandle(ref: VectorHandleRef, to: Vec2, options?: {
         breakHandles?: boolean;
@@ -789,12 +1087,95 @@ declare class VectorEditorController {
     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;
+    /**
+     * Deletes the selected (or given) anchors; subpaths left with one anchor and empty paths go
+     * too. With `keepShape` (default: the `keepShapeOnDelete` setting, on) the neighbours'
+     * handles are refitted so the path keeps its shape; off, the neighbours are joined as they are.
+     */
+    deleteAnchors(refs?: readonly VectorAnchorRef[], options?: {
+        keepShape?: boolean;
+    }): 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;
+    /** Unlocked path nodes in the given roots (default: the paths being edited, else the selection). */
+    private pathTargets;
+    /** Subpaths of node `from` mapped into node `to`'s own space. */
+    private subpathsIn;
+    /**
+     * Replaces a path with pieces: each entry becomes one path (the first keeps the node's id and
+     * place, the others go just above it with the same style). No pieces removes the path.
+     * Returns the ids of the paths now standing in for it.
+     */
+    private replaceWithPieces;
+    /** Clears anchor selections, editing and pen state that no longer point at anything. */
+    private dropStaleRefs;
+    /**
+     * Join: the open subpaths of the selected (or given) paths become one open path, joined
+     * nearest endpoints first (ends within `tolerance` document units merge into one anchor,
+     * others get a straight segment); a single open subpath is closed. The result replaces the
+     * lowest path, in its space and style. Default tolerance: the pick distance.
+     */
+    joinPaths(options?: {
+        ids?: readonly string[];
+        tolerance?: number;
+    }): VectorActionResult;
+    /** Average: moves the selected (or given) anchors onto their average position along `axis`, in document space. */
+    averageAnchors(axis?: VectorAverageAxis, refs?: readonly VectorAnchorRef[]): VectorActionResult;
+    /** Applies `fn` to every subpath of the target paths as one undo step. */
+    private editSubpaths;
+    /**
+     * Remove Redundant Points: drops anchors of the selected (or given) paths that can go
+     * without moving the outline more than `tolerance` document units (default 0.5).
+     */
+    removeRedundantPoints(options?: {
+        ids?: readonly string[];
+        tolerance?: number;
+    }): VectorActionResult;
+    /**
+     * Smooth: pulls handles towards smooth tangents by `amount` (0–1, default 1). With the direct
+     * tool and points selected, only those points change.
+     */
+    smoothPaths(options?: {
+        ids?: readonly string[];
+        amount?: number;
+        refs?: readonly VectorAnchorRef[];
+    }): VectorActionResult;
+    /** Splits a cut subpath into pieces: separate paths for a one-subpath node, subpaths in place for a compound one. */
+    private applyCuts;
+    /**
+     * Scissors: cuts path `nodeId` at the outline point nearest document point `point` (at an
+     * anchor when within the pick distance of one). A closed subpath opens there; an open one
+     * splits in two (a one-subpath path becomes two paths). Returns the ids of the paths.
+     */
+    cutPathAt(nodeId: string, point: Vec2): string[] | null;
+    /** Scissors on the selected (or given) anchors: each cuts its subpath there (see `cutPathAt`). */
+    cutAtAnchors(refs?: readonly VectorAnchorRef[]): VectorActionResult;
+    /** Visible, unlocked paths a stroke over `points` can reach: in `ids`, the selection, or (with neither) any whose bounds it crosses. */
+    private strokeTargets;
+    /** A stroke's points in node `id`'s own space. */
+    private localPoints;
+    /**
+     * Knife: cuts closed paths along the polyline `points` (document space) wherever it crosses
+     * them from edge to edge, with no gap between the pieces. It cuts the given paths, the
+     * selection, or (with neither) every path it crosses. Returns the ids of the pieces (empty
+     * when nothing was cut).
+     */
+    knife(points: readonly Vec2[], options?: {
+        ids?: readonly string[];
+    }): string[];
+    /**
+     * Eraser: rubs out a round stroke of diameter `size` (default: the `eraserSize` setting)
+     * along `points` (document space). Filled closed paths lose that area (pieces that come
+     * apart become separate paths); outlines are cut where they pass under it. It erases from
+     * the given paths, the selection, or (with neither) every path it reaches. Returns the ids
+     * of the paths it changed or created.
+     */
+    erase(points: readonly Vec2[], options?: {
+        ids?: readonly string[];
+        size?: number;
+    }): string[];
     /** 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). */
@@ -822,6 +1203,8 @@ declare class VectorEditorController {
     /** Endpoints of open subpaths of unlocked visible paths (pen tool resumes from them). */
     private openEndpoints;
     private computeHover;
+    /** The nearest outline point of any visible, unlocked path within the pick distance of document point `p`. */
+    private nearestOutline;
     private sameHover;
     /** Primary button down on the canvas at `screen` (pixels relative to the canvas). */
     pointerDown(screen: Vec2, input?: VectorPointerInput): void;
@@ -832,6 +1215,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. */
@@ -910,6 +1299,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: {
@@ -936,6 +1340,29 @@ 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[];
+    };
+    /**
+     * The knife or eraser stroke being drawn, screen space: `d` is an open polyline; draw the
+     * eraser's with a round-capped stroke `width` pixels wide (0 for the knife: a thin line).
+     */
+    toolStroke: {
+        tool: 'knife' | 'eraser';
+        d: string;
+        width: number;
+    } | null;
+    /** The pencil's lazy-mouse string from the pen to the pointer, screen space. */
+    pencilString: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    } | null;
+    /** Where the scissors would cut (screen space). */
+    cutPoint: Vec2 | null;
     /** A short status, e.g. "W 120 × H 80" or "45°". */
     status: string | null;
 }
@@ -951,8 +1378,12 @@ 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)";
+    /** The eraser's swath while it is dragged. */
+    readonly eraserFill: "rgba(239, 68, 68, 0.25)";
     readonly transformHandleSize: 8;
     readonly anchorSize: 7;
     readonly handleRadius: 3.5;
@@ -1007,6 +1438,25 @@ interface VectorSelectionStyle {
 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;
+/** A path-editing button of the bundled toolbars. */
+interface VectorPathAction {
+    id: 'join' | 'average' | 'cut' | 'clean' | 'smooth';
+    label: string;
+    title: string;
+    /** Shortcut after Cmd / Ctrl, if any. */
+    shortcut?: string;
+    /** Whether it can run with `selected` nodes and `points` selected anchors (direct tool). */
+    enabled: (selected: number, points: number) => boolean;
+    run: (controller: VectorEditorController) => unknown;
+}
+/** Join, Average, Cut at Points, Remove Redundant Points and Smooth, as the toolbars show them. */
+declare const VECTOR_PATH_ACTIONS: readonly VectorPathAction[];
+/** The on / off path-editing settings the toolbars toggle. */
+declare const VECTOR_EDIT_TOGGLES: readonly {
+    key: 'keepShapeOnDelete' | 'curvatureMoves' | 'recognizeShapes';
+    label: string;
+    title: string;
+}[];
 
 interface VectorCommandOptions {
     /** Id prefix (default `vector.`); use one per editor when several are registered. */
@@ -1049,4 +1499,182 @@ 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 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 };
+/**
+ * Removes anchor `index` without opening the path: its neighbours keep their handle directions
+ * and their facing handles are refitted so one cubic follows the two segments that met there
+ * as closely as possible (least maximum error over where the new curve passes the removed
+ * point). Two straight segments become one; removing an end of an open subpath drops its
+ * segment. Returns the subpath unchanged (a copy) when `index` is out of range.
+ */
+declare function removeAnchorKeepingShape(sp: VectorSubpath, index: number): VectorSubpath;
+/** Removes several anchors of a subpath, keeping the shape (see `removeAnchorKeepingShape`). */
+declare function removeAnchorsKeepingShape(sp: VectorSubpath, indices: readonly number[]): VectorSubpath;
+/**
+ * Bends segment `segment` so the curve passes through `p` at parameter `t` (clamped to
+ * 0.05–0.95): its handles go to the thirds of the chord plus one shared offset, so
+ * `B(t) = L(t) + 3t(1 − t)·offset` exactly. The end anchors keep their types (a smooth or
+ * symmetric end turns its other handle to stay in line).
+ */
+declare function bendSegment(sp: VectorSubpath, segment: number, t: number, p: Vec2): VectorSubpath;
+/** The point at parameter `t` of segment `segment` (for tests and previews). */
+declare function subpathPointAt(sp: VectorSubpath, segment: number, t: number): Vec2;
+/**
+ * Moves anchor `index` to `q` the way the Curvature tool drags a point: only the two segments
+ * at it change. A smooth or symmetric anchor turns its handles along the line through its
+ * neighbours; the neighbours' handles on those segments, and a corner's own handles, keep
+ * their directions while their lengths scale with their segment's chord, so the segments
+ * beyond don't move and a corner without handles keeps none.
+ */
+declare function curvatureMoveAnchor(sp: VectorSubpath, index: number, q: Vec2): VectorSubpath;
+/**
+ * Cuts a subpath at the anchors `at`: each becomes the end of one open piece and the start of
+ * the next, its handle off each piece dropped (the shape doesn't change). A closed subpath
+ * opens at its first cut, so one cut leaves one piece whose ends coincide. The ends of an open
+ * subpath and indices out of range don't cut; with no cut left the subpath comes back as it is.
+ */
+declare function cutSubpathAt(sp: VectorSubpath, at: readonly number[]): VectorSubpath[];
+/**
+ * Cuts a subpath at parameter `t` of segment `segment` (Scissors on a segment): an anchor is
+ * inserted there without changing the shape, then cut. Within `endTolerance` of the segment's
+ * ends (in parameter) the existing anchor is cut instead.
+ */
+declare function splitSubpathAt(sp: VectorSubpath, segment: number, t: number, endTolerance?: number): VectorSubpath[];
+/**
+ * Join: open subpaths are joined nearest-endpoints-first into one open subpath (endpoints
+ * within `tolerance` merge into one anchor, otherwise a straight segment connects them). A
+ * single open subpath is closed instead (its ends merged when they meet). Closed subpaths and
+ * lone anchors pass through unchanged, before the joined one.
+ */
+declare function joinSubpaths(subpaths: readonly VectorSubpath[], tolerance: number): VectorSubpath[];
+/**
+ * Smooth: pulls handles towards Catmull-Rom-like tangents (a third of the way to each
+ * neighbour along the line through both). `amount` 0–1 (0 = unchanged, 1 = fully smooth).
+ * Only the anchors in `only` change when it is given; endpoints of open subpaths keep their
+ * handles. Subpaths of fewer than three anchors are unchanged.
+ */
+declare function smoothSubpath(sp: VectorSubpath, amount?: number, only?: ReadonlySet<number>): VectorSubpath;
+/**
+ * Remove Redundant Points: drops anchors that can go without changing the shape by more than
+ * `tolerance` (collinear corners, duplicate points, and smooth joints that one cubic can
+ * replace).
+ */
+declare function removeRedundantPoints(sp: VectorSubpath, tolerance: number): VectorSubpath;
+
+/**
+ * Knife and eraser on Bézier paths, built on the curve booleans and `outlineStroke`.
+ *
+ * The knife cuts filled regions along a polyline with no gap: each stretch of the polyline
+ * that crosses a region from boundary to boundary (a chord) splits the boundary loop it starts
+ * and ends on into two loops sharing that chord, or, when it joins two loops (an outline and a
+ * hole), merges them into one. Crossings are exact (line–cubic roots), and the pieces share
+ * the cut edge exactly.
+ *
+ * The eraser removes the area of a round-capped stroke along a polyline: filled shapes lose it
+ * by a boolean difference; outlines are cut where they cross the stroke's outline (exact
+ * curve–curve intersections) and keep the parts outside it.
+ *
+ * Modelled on vectorcraft-main/crates/engine/src/cmd/draw2.rs (`knife`, `erase_region`,
+ * `erase_outline`, `cut_subpath`; MIT OR Apache-2.0, © ArtCraft Team and contributors; see
+ * THIRD_PARTY_NOTICES.md), without its fixed knife slit and its sampled crossing search.
+ */
+
+type FillRule = 'nonzero' | 'evenodd';
+/** One path per face (an outline with its holes) of a filled path, largest first. */
+declare function splitIntoFaces(path: BezierPathInput, fillRule?: FillRule): BezierPath[];
+/**
+ * Cuts the filled path along the open polyline `knife`. Returns one path per resulting face
+ * (an outline with its holes), or null when the knife crossed nothing from edge to edge. A
+ * stretch of the knife that starts or ends inside the shape does not cut.
+ */
+declare function knifePath(path: BezierPathInput, fillRule: FillRule, knife: readonly Point[]): BezierPath[] | null;
+/** The area a round eraser of diameter `width` covers along `points` (a disc for one point). */
+declare function eraserRegion(points: readonly Point[], width: number): BezierPath;
+/**
+ * A filled path with `region` removed: one path per remaining face, or null when the region
+ * does not overlap the fill.
+ */
+declare function eraseFromFill(path: BezierPathInput, fillRule: FillRule, region: BezierPathInput): BezierPath[] | null;
+/**
+ * The parts of a subpath's outline outside `region`, as open subpaths that keep the original
+ * curves exactly; null when the outline does not enter the region. A closed subpath's last
+ * and first parts join at its first anchor.
+ */
+declare function eraseFromOutline(sp: VectorSubpath, region: BezierPathInput): VectorSubpath[] | null;
+/** Bounds of a point list (for picking the paths a knife or eraser stroke can reach). */
+declare function polylineBounds(points: readonly Point[], pad?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+/** Ramer–Douglas–Peucker reduction of a polyline (keeps both ends). */
+declare function simplifyPolyline(points: readonly Point[], tolerance: number): Point[];
+
+/**
+ * Pencil helpers: lazy-mouse smoothing (a pulled string between the pointer and the pen) and
+ * ink-to-shape recognition (a hand-drawn stroke that is a line, rectangle, ellipse or polygon).
+ *
+ * Portions ported from (MIT OR Apache-2.0, © ArtCraft Team and contributors; see
+ * THIRD_PARTY_NOTICES.md):
+ * - photocraft-main/crates/paint/src/dynamics.rs (`Smoother`: pulled-string mode, `string`,
+ *   `finish` with catch-up on stroke end)
+ * - wordcraft-main/crates/engine/src/cmd/ink_shape.rs (`recognise`, `ellipse_rms`,
+ *   `snap_square`, `corners`, `turning`, `rdp`, `upright`)
+ */
+
+/**
+ * Pulled-string smoothing: the pen stays put until the pointer is more than `length` away,
+ * then follows it at that distance, so small wobbles never reach the stroke. Feed pointer
+ * positions to `push`; it returns the pen positions to draw through (possibly none).
+ */
+declare class LazyMouse {
+    readonly length: number;
+    private pos;
+    private last;
+    /** `length` is the string length in the units of the points (0 turns smoothing off). */
+    constructor(length: number);
+    push(p: Point): Point[];
+    /** The string from the pen to the pointer while they are apart, else null. */
+    string(): [Point, Point] | null;
+    /** End of stroke: the pen catches up with the pointer (the point to add, if it lagged). */
+    finish(): Point[];
+}
+/** A shape recognised in a stroke, in the stroke's coordinates. */
+type VectorInkShape = {
+    kind: 'line';
+    a: Point;
+    b: Point;
+} | {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | {
+    kind: 'ellipse';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | {
+    kind: 'polygon';
+    points: Point[];
+};
+interface RecognizeInkOptions {
+    /** Strokes whose longer side is smaller than this stay ink (default 6). */
+    minSize?: number;
+}
+/** Most corners a recognised polygon may have. */
+declare const VECTOR_INK_MAX_CORNERS = 8;
+/** "line", "square", "rectangle", "circle", "ellipse", "triangle" or "polygon". */
+declare function vectorInkShapeName(shape: VectorInkShape): string;
+/**
+ * The shape a hand-drawn stroke draws, if it is one: an open stroke is a line when it stays
+ * close to the chord between its ends; a closed one is an ellipse when its points sit on the
+ * ellipse inscribed in their bounds, else a polygon of 3–8 corners when that polygon stays
+ * close to every point (an upright four-cornered one is a rectangle). Nearly square boxes
+ * become squares and circles. Anything else (scribbles, curves, letters) is null.
+ */
+declare function recognizeInkShape(points: readonly Point[], options?: RecognizeInkOptions): VectorInkShape | null;
+
+export { type AddVectorNodeOptions, AffineMatrix, DEFAULT_VECTOR_PATH_EDIT, DEFAULT_VECTOR_SNAP, IDENTITY_MATRIX, KAPPA, LazyMouse, type NearestSegment, type RecognizeInkOptions, SvgGradientDef, VECTOR_CLIPBOARD_TYPE, VECTOR_CONSTRUCTION_ANGLES, VECTOR_EDIT_TOGGLES, VECTOR_INK_MAX_CORNERS, VECTOR_OVERLAY_THEME, VECTOR_PATH_ACTIONS, VECTOR_PENCIL_STRING_PX, 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 VectorAverageAxis, 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 VectorInkShape, type VectorInteraction, type VectorKeyInput, type VectorLineCap, type VectorLineJoin, type VectorMatrix, type VectorModifiers, type VectorNode, type VectorNodeListing, type VectorOverlayRenderData, type VectorPaint, type VectorPathAction, type VectorPathEditOptions, 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 VectorSegmentRef, 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, bendSegment, bezierToSubpaths, boundsFromPoints, boundsIntersect, cloneAnchor, cloneSubpath, cloneVectorDocument, cloneVectorNode, collectPathNodes, constrainToLeave, convertAnchor, createVectorCommands, curvatureMoveAnchor, cutSubpathAt, decomposeRigid, ellipseSubpath, eraseFromFill, eraseFromOutline, eraserRegion, findVectorNode, getAnchor, getAnchorWorld, getEditablePathIds, getTransformHandlePositions, getVectorOverlayRenderData, getVectorSceneRenderData, getVectorSelectionBoxGeometry, getVectorSelectionFrame, getVectorSelectionStyle, getVisibleAnchors, getVisibleHandles, hasPaint, hitTestVectorNode, hitTestVectorNodes, inferAnchorType, insertAnchor, invertMatrix, isIdentityMatrix, isVectorTextTarget, joinSubpaths, knifePath, lineSubpath, locateVectorNode, matrixRotation, moveAnchorHandle, multiplyMatrices, nearestSegment, nodeMatrix, parseSvgTransform, parseVectorSvg, polygonSubpath, polylineBounds, recognizeInkShape, rectSubpath, removeAnchorKeepingShape, removeAnchors, removeAnchorsKeepingShape, removeRedundantPoints, reverseSubpath, rotateMatrix, roundSubpaths, scaleFor, scaleMatrix, simplifyPolyline, smoothSubpath, splitIntoFaces, splitSubpathAt, starSubpath, subpathPointAt, subpathSegment, subpathSegmentCount, subpathsToBezier, toVectorKeyInput, toVectorModifiers, toVectorPointerInput, transformVectorNode, translateAnchor, translateMatrix, unionBounds, vectorDocumentToSvg, vectorInkShapeName, vectorNodeBounds, vectorNodeRotation, vectorNodeToBezier, vectorPaintToHex, vectorPaintToSvg, vectorParentMatrix, vectorPathData, vectorPathWorldBezier, vectorResizeCursor, vectorToolLabel, vectorWorldMatrix, walkVectorNodes };