@pixerate/editor 0.23.0 → 0.25.0

package/dist/canvas/index.d.cts

@@ -3,6 +3,7 @@ export { h as CanvasDockingCallbacks, i as CollapseNodeOptions, j as Displacemen
 import { b as CanvasNodeUpdate, N as NodeRectOptions, A as AlignEdge, c as AlignNodesOptions, D as DistributeAxis, a as DistributeMode, d as DistributeNodesOptions, S as SizeDimension, M as MatchSizeOptions, Z as ZOrderOperation, C as CanvasArrangeAction } from '../arrangeShortcuts-B8O3f8-P.cjs';
 export { e as ArrangeShortcutBinding, f as DEFAULT_ARRANGE_SHORTCUTS, L as LOCKED_DATA_KEY, g as LOCKED_PREVIOUS_FLAGS_KEY, h as alignNodes, i as applyNodeUpdates, j as createNodeLookup, k as distributeNodes, l as getAbsolutePosition, m as getNodeRect, n as getNodeSize, o as invertNodeUpdates, p as isLocked, q as lockNodes, r as matchArrangeShortcut, s as matchSize, t as readStyleSize, u as reorderNodes, v as toggleLockNodes, w as unlockNodes, x as withStyleSize } from '../arrangeShortcuts-B8O3f8-P.cjs';
 import { C as Command } from '../types-GT5a5YAX.cjs';
+import { r as TokenType, o as TokenScope, f as TokenLiteral, c as TokenVariable, e as TokenResolution, d as TokenModeContext, T as TokenState } from '../model-C1zApQM8.cjs';
 
 declare const DEFAULT_NODE_WIDTH = 200;
 declare const DEFAULT_NODE_HEIGHT = 60;
@@ -898,6 +899,346 @@ interface PolygonToPathOptions {
  */
 declare function polygonToSvgPath(input: MultiPolygon | PolygonRing[], options?: PolygonToPathOptions): string;
 
+/**
+ * Bézier path model shared by the curve-preserving path operations: absolute `M` / `L` /
+ * `Q` / `C` / `Z` commands, conversion from SVG path data (arcs become cubics), segment
+ * math (evaluation, splitting, extrema, nearest point), exact areas, winding numbers and
+ * arc-length utilities.
+ */
+
+/** One absolute path command. Every subpath starts with `M`; `Z` closes it. */
+type BezierCommand = {
+    type: 'M';
+    x: number;
+    y: number;
+} | {
+    type: 'L';
+    x: number;
+    y: number;
+} | {
+    type: 'Q';
+    x1: number;
+    y1: number;
+    x: number;
+    y: number;
+} | {
+    type: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+} | {
+    type: 'Z';
+};
+/** A path as a list of absolute move / line / quadratic / cubic / close commands. */
+type BezierPath = BezierCommand[];
+/** Anything the path operations accept as a path: SVG path data, parsed commands or a `BezierPath`. */
+type BezierPathInput = string | readonly BezierCommand[] | readonly PathCommand[];
+/**
+ * One segment as its control points: 2 points for a line, 3 for a quadratic and 4 for a
+ * cubic Bézier.
+ */
+type BezierSegment = readonly Point[];
+/** A subpath as a chain of segments (each starts where the previous one ends). */
+interface BezierContour {
+    segments: BezierSegment[];
+    closed: boolean;
+}
+/** Point at parameter `t` (de Casteljau, works for any degree). */
+declare function segmentPoint(seg: BezierSegment, t: number): Point;
+/** First derivative at `t`. */
+declare function segmentDerivative(seg: BezierSegment, t: number): Point;
+/**
+ * Unit tangent at `t`. Where the derivative vanishes (a handle on its anchor) the direction
+ * a hair further along is used, and the chord as the last resort.
+ */
+declare function segmentTangent(seg: BezierSegment, t: number): Point;
+/** Signed curvature at `t` (positive when turning counter-clockwise in a y-up frame). */
+declare function segmentCurvature(seg: BezierSegment, t: number): number;
+/** Splits a segment at `t` (de Casteljau). */
+declare function splitSegment(seg: BezierSegment, t: number): [Point[], Point[]];
+/** The part of a segment between parameters `t0` and `t1` (reversed when `t1 < t0`). */
+declare function subSegment(seg: BezierSegment, t0: number, t1: number): Point[];
+/** Parameters in (0, 1) where the segment's `axis` coordinate has a local extremum. */
+declare function segmentExtrema(seg: BezierSegment, axis: 0 | 1): number[];
+/** Exact axis-aligned bounds of a segment. */
+declare function segmentBounds(seg: BezierSegment): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/** Arc length of the segment between `t0` and `t1` (default the whole segment). */
+declare function segmentLength(seg: BezierSegment, t0?: number, t1?: number, tolerance?: number): number;
+/** Parameter at arc length `length` from the segment start (clamped to [0, 1]). */
+declare function segmentParamAtLength(seg: BezierSegment, length: number, total?: number): number;
+/**
+ * Nearest point of the segment to `p`: the parameter and the distance. Coarse sampling
+ * followed by Newton refinement around the best samples.
+ */
+declare function segmentNearest(seg: BezierSegment, p: Point): {
+    t: number;
+    distance: number;
+};
+/** Converts an SVG elliptical arc (SVG 1.1 F.6.5) to cubic segments, at most 90° each. */
+declare function arcToCubics(from: Point, cmd: {
+    rx: number;
+    ry: number;
+    rotation: number;
+    largeArc: boolean;
+    sweep: boolean;
+    x: number;
+    y: number;
+}): Point[][];
+/**
+ * Converts SVG path data or parsed commands to a `BezierPath` (absolute `M` / `L` / `Q` /
+ * `C` / `Z`); elliptical arcs become cubic Béziers (at most 90° each).
+ */
+declare function toBezierPath(input: BezierPathInput): BezierPath;
+/** Splits a path into contours of segments. Zero-length segments are dropped. */
+declare function pathToContours(input: BezierPathInput): BezierContour[];
+/** Builds a path from contours (a closed contour's closing line is left to `Z`). */
+declare function contoursToPath(contours: readonly BezierContour[]): BezierPath;
+interface BezierPathToSvgOptions {
+    /** Decimal places (default 3). */
+    precision?: number;
+    /** Added to every point before formatting. */
+    offset?: {
+        x: number;
+        y: number;
+    };
+}
+/** Writes a path as compact SVG path data. */
+declare function bezierPathToSvg(input: BezierPathInput, options?: BezierPathToSvgOptions): string;
+/** 2D affine matrix `[a, b, c, d, e, f]` mapping `(x, y)` to `(a x + c y + e, b x + d y + f)`. */
+type AffineMatrix = readonly [number, number, number, number, number, number];
+/** Applies an affine transform to every point (exact for Bézier curves). */
+declare function transformBezierPath(input: BezierPathInput, m: AffineMatrix): BezierPath;
+/** Number of drawing segments (`L` / `Q` / `C`, plus the closing line of `Z` when it has length). */
+declare function countPathSegments(input: BezierPathInput): {
+    lines: number;
+    quads: number;
+    cubics: number;
+};
+/** The contour's segments, with the closing line added when the contour is closed (or filled). */
+declare function closeContour(contour: BezierContour, force?: boolean): BezierSegment[];
+/** Exact bounds of a path, or `null` when it has no points. */
+declare function bezierPathBounds(input: BezierPathInput): {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+} | null;
+/**
+ * Signed area of the path as drawn: every subpath closed, contributions summed (positive
+ * for counter-clockwise subpaths in a y-up frame). Exact for curves. Overlapping subpaths
+ * count with their multiplicity; use `bezierPathArea` for the filled area.
+ */
+declare function bezierPathSignedArea(input: BezierPathInput): number;
+/** Signed area of a closed chain of segments. */
+declare function contourSignedArea(segs: readonly BezierSegment[]): number;
+/** Arc length of a path (closing lines of closed subpaths included). */
+declare function bezierPathLength(input: BezierPathInput): number;
+/** Point, unit tangent and angle (radians) at an arc length along the path. */
+interface PathPointAtLength {
+    point: Point;
+    tangent: Point;
+    angle: number;
+    /** Subpath index. */
+    contour: number;
+    /** Segment index within the subpath (closing line last). */
+    segment: number;
+    /** Parameter within the segment. */
+    t: number;
+}
+/**
+ * The point at arc length `length` from the start of the path (clamped to the path). Arc
+ * lengths run through the subpaths in order, as `bezierPathLength` counts them.
+ */
+declare function bezierPathPointAtLength(input: BezierPathInput, length: number): PathPointAtLength | null;
+/**
+ * Splits a segment chain by arc length: the part between `from` and `to` (measured from the
+ * chain's start) as new segments.
+ */
+declare function trimSegments(segs: readonly BezierSegment[], from: number, to: number, lengths?: number[]): Point[][];
+/**
+ * Winding number of a set of closed segment chains around `point` (ray to +x, half-open
+ * crossing rule). Points exactly on the outline may report either side.
+ */
+declare function windingNumber(chains: readonly (readonly BezierSegment[])[], point: Point): number;
+/** Whether `point` is inside the filled path (every subpath closed for filling). */
+declare function pointInBezierPath(input: BezierPathInput, point: Point, fillRule?: PolygonFillRule): boolean;
+/** Distance from `point` to the path outline (closing lines of closed subpaths included). */
+declare function distanceToBezierPath(input: BezierPathInput | readonly BezierContour[], point: Point): number;
+
+/** Boolean operations (same names as `polygonBoolean`). `xor` is Exclude. */
+type PathBooleanOperation = PolygonBooleanOperation;
+/** A path with the fill rule it is read with (default `nonzero`). */
+interface PathOperand {
+    path: BezierPathInput;
+    fillRule?: PolygonFillRule;
+}
+type PathOperandInput = BezierPathInput | PathOperand;
+interface PathOpsOptions {
+    /**
+     * Distance below which points are treated as equal. Defaults to `1e-9` times the
+     * largest coordinate magnitude (at least `1e-9`).
+     */
+    epsilon?: number;
+    /** Fall back to the polygon engine when the curve engine fails (default `true`). */
+    fallback?: boolean;
+    /** Flattening tolerance used by the polygon fallback (default 0.05). */
+    fallbackTolerance?: number;
+    /** Called with the reason whenever the polygon fallback is used. */
+    onFallback?: (reason: string) => void;
+    /**
+     * Work budget of the curve–curve intersection search (flat sub-curve pairs per pair of
+     * pieces, default 20,000). Exceeding it (nearly coincident curves) falls back.
+     */
+    subdivisionBudget?: number;
+}
+/** Which engine produced a result, and why the curve engine was not used. */
+interface PathOpsReport {
+    engine: 'curve' | 'polygon';
+    fallbackReason?: string;
+    /** Set when the input cannot be processed at all (non-finite coordinates); the result is empty. */
+    error?: string;
+}
+interface PathBooleanResult extends PathOpsReport {
+    path: BezierPath;
+}
+/** One region of `dividePaths`, with the indices of the operands that cover it. */
+interface PathPiece {
+    path: BezierPath;
+    operands: number[];
+}
+interface DividePathsResult extends PathOpsReport {
+    pieces: PathPiece[];
+}
+/** Raised by the curve engine when it cannot produce a reliable arrangement. */
+declare class PathOpsError extends Error {
+    constructor(message: string);
+}
+/**
+ * Applies a boolean operation to any number of path operands, keeping curves:
+ * - `union`: covered by any operand.
+ * - `intersection`: covered by every operand.
+ * - `difference`: the first operand minus all others.
+ * - `xor`: covered by an odd number of operands (Exclude).
+ *
+ * Open subpaths are closed for filling. Non-finite input gives an empty path (`error`); with
+ * `fallback: false` a failure of the curve engine throws a `PathOpsError`. The result is a set of simple closed subpaths that
+ * never cross (they may touch at points): outer subpaths run counter-clockwise in a y-up
+ * frame (clockwise on screen), holes the other way, so it fills the same with `nonzero`
+ * and `evenodd`. Segments of the inputs are kept as exact sub-curves.
+ */
+declare function pathBoolean(operation: PathBooleanOperation, operands: PathOperandInput[], options?: PathOpsOptions): PathBooleanResult;
+declare const unitePaths: (a: PathOperandInput, b: PathOperandInput, options?: PathOpsOptions) => BezierPath;
+declare const intersectPaths: (a: PathOperandInput, b: PathOperandInput, options?: PathOpsOptions) => BezierPath;
+declare const subtractPaths: (a: PathOperandInput, b: PathOperandInput, options?: PathOpsOptions) => BezierPath;
+declare const excludePaths: (a: PathOperandInput, b: PathOperandInput, options?: PathOpsOptions) => BezierPath;
+/**
+ * Splits the arrangement of the operands into its regions (Divide): every connected area
+ * covered by the same set of operands becomes one piece (an outer subpath with its holes).
+ * Pieces are ordered by operand set, then by area (largest first).
+ */
+declare function dividePaths(operands: PathOperandInput[], options?: PathOpsOptions): DividePathsResult;
+/**
+ * Resolves self-intersections and overlaps of one filled path into simple, consistently
+ * oriented subpaths (outer subpaths and holes) under its fill rule.
+ */
+declare function normalizeBezierPath(path: BezierPathInput, fillRule?: PolygonFillRule, options?: PathOpsOptions): BezierPath;
+/** Filled area of a path under its fill rule (overlaps counted once; exact for curves). */
+declare function bezierPathArea(path: BezierPathInput, fillRule?: PolygonFillRule, options?: PathOpsOptions): number;
+
+/**
+ * Offset Path and Outline Stroke on Bézier paths.
+ *
+ * The stroker offsets every segment by ± half the width (lines exactly, curves by cubic
+ * approximations refined until they stay within `tolerance` of the true offset), joins the
+ * pieces (miter with a miter limit, round or bevel on the outer side of a turn; through the
+ * vertex on the inner side) and adds caps (butt, round, square) to open subpaths. Dashes
+ * follow arc length, restart on every subpath and join across the start of a closed
+ * subpath. The raw outline overlaps itself, so it is filled with the non-zero rule and
+ * normalised with the curve boolean engine.
+ *
+ * When the stroke is wider than a curve's radius of curvature the inner offset turns inside
+ * out and its loops cancel winding, leaving holes that are really covered. Every face of
+ * the true result is bounded by the arrangement, so a face is spurious exactly when a point
+ * deep inside it is closer to the path than the offset distance (holes when growing,
+ * islands when insetting); such faces are dropped.
+ *
+ * Portions ported from vectorcraft-main/crates/pathops/src/offset.rs,
+ * vectorcraft-main/crates/pathops/src/boolean.rs (`try_merge`) and
+ * vectorcraft-main/crates/effects/src/stroke/dash.rs (MIT OR Apache-2.0, © ArtCraft Team
+ * and contributors). See THIRD_PARTY_NOTICES.md.
+ */
+
+/** Line join (as SVG `stroke-linejoin`). */
+type StrokeJoin = 'miter' | 'round' | 'bevel';
+/** Line cap (as SVG `stroke-linecap`). */
+type StrokeCap = 'butt' | 'round' | 'square';
+interface OutlineStrokeOptions extends PathOpsOptions {
+    /** Stroke width. Non-positive or non-finite widths give an empty result. */
+    width: number;
+    /** Default `miter` (as SVG). */
+    join?: StrokeJoin;
+    /** Default `butt` (as SVG). */
+    cap?: StrokeCap;
+    /** Miter length / stroke width above which a miter join is bevelled (default 4, as SVG). */
+    miterLimit?: number;
+    /** Dash pattern (as SVG `stroke-dasharray`); odd patterns repeat twice. */
+    dash?: readonly number[];
+    /** Distance into the dash pattern at the start of each subpath (as `stroke-dashoffset`). */
+    dashOffset?: number;
+    /** Maximum distance between the approximated and the true offset curve (default 0.01). */
+    tolerance?: number;
+}
+interface OffsetPathOptions extends PathOpsOptions {
+    /** Corner style of the grown / shrunk outline (default `miter`). */
+    join?: StrokeJoin;
+    /** Miter limit (default 4). */
+    miterLimit?: number;
+    /** Fill rule of the input (default `nonzero`). */
+    fillRule?: PolygonFillRule;
+    /** Maximum distance between the approximated and the true offset curve (default 0.01). */
+    tolerance?: number;
+}
+interface DashedPath {
+    /** The dashes, as open subpaths. */
+    contours: BezierContour[];
+    /** Zero-length dashes: where they sit and the path direction there. */
+    dots: {
+        point: Point;
+        tangent: Point;
+    }[];
+}
+/**
+ * Applies a dash pattern (SVG `stroke-dasharray` / `stroke-dashoffset` semantics) to the
+ * subpaths. Returns `null` when the pattern is invalid (negative or non-finite entries),
+ * has no positive entry, or would make more than 200,000 dashes: the line is solid.
+ */
+declare function dashContours(contours: readonly BezierContour[], pattern: readonly number[], offset?: number): DashedPath | null;
+/**
+ * The raw (overlapping) outline of a stroke as closed subpaths to fill with `nonzero`.
+ * `outlineStroke` normalises it; this is useful for previews.
+ */
+declare function strokeOutlineRings(input: BezierPathInput, options: OutlineStrokeOptions): BezierPath;
+/**
+ * Outline Stroke: the filled area painted by stroking `path`, as one clean path (overlaps
+ * removed, consistently oriented). Joins, caps, miter limit and dashes follow SVG.
+ */
+declare function outlineStroke(input: BezierPathInput, options: OutlineStrokeOptions): BezierPath;
+/**
+ * Offset Path: grows (`distance > 0`) or shrinks (`distance < 0`) the filled area by
+ * `distance`. Closed subpaths are a filled region (read with `fillRule`); open subpaths are
+ * outlined with a stroke of width `2·|distance|` and butt caps (when growing). Loops of the
+ * offset curves are removed.
+ */
+declare function offsetPath(input: BezierPathInput, distance: number, options?: OffsetPathOptions): BezierPath;
+
 /**
  * Shape nodes and Freeform-style shape boolean operations (Unite / Intersect / Subtract /
  * Exclude / Divide) on canvas nodes.
@@ -929,6 +1270,22 @@ declare function shapeNodeToPolygon(node: CanvasNode, lookup?: ReadonlyMap<strin
     rings: PolygonRing[];
     fillRule: PolygonFillRule;
 } | null;
+/**
+ * A shape as an exact Bézier path in node-local pixels (rotation and path view boxes
+ * applied; arcs become cubics), with the fill rule it is read with.
+ */
+declare function shapeToBezierPath(shape: ShapeDescription, size: ShapeSize): {
+    path: BezierPath;
+    fillRule: PolygonFillRule;
+};
+/**
+ * A shape node's outline as an exact Bézier path in absolute flow coordinates (parent
+ * offsets, size and rotation applied), or `null` for non-shape nodes.
+ */
+declare function shapeNodeToBezierPath(node: CanvasNode, lookup?: ReadonlyMap<string, CanvasNode>, options?: NodeRectOptions): {
+    path: BezierPath;
+    fillRule: PolygonFillRule;
+} | null;
 /** Why `combineShapeNodes` refused. */
 type CombineShapeNodesRefusal = 
 /** A selected shape is locked; locked shapes are never consumed. */
@@ -955,9 +1312,20 @@ interface CombineShapeNodesOptions extends ShapeNodePolygonOptions {
     /** Ramer–Douglas–Peucker simplification tolerance for the result (default 0, off). */
     simplify?: number;
     /**
-     * How the result's outline is written: `'fit'` (default) fits smooth cubic curves to the
-     * flattened result, so booleans of curved shapes stay curved (sharp corners and straight
-     * edges are kept); `'lines'` writes the polygon as straight segments.
+     * Geometry engine. `'curve'` (default) computes the operation on the exact Bézier
+     * outlines and keeps the inputs' curves (circles stay cubic arcs, rectangles stay four
+     * lines); it falls back to `'polygon'` when it cannot resolve the input (reported as
+     * `engine` / `fallbackReason` on the result). `'polygon'` flattens the shapes and uses
+     * `polygonBoolean` (the behaviour before curve booleans). `curves: 'lines'` implies
+     * `'polygon'` unless an engine is named.
+     */
+    engine?: 'curve' | 'polygon';
+    /** Called with the reason when the curve engine falls back to polygons. */
+    onFallback?: (reason: string) => void;
+    /**
+     * Polygon engine only: how the result's outline is written: `'fit'` (default) fits
+     * smooth cubic curves to the flattened result (sharp corners and straight edges are
+     * kept); `'lines'` writes the polygon as straight segments.
      */
     curves?: 'lines' | 'fit';
     /** Curve-fitting tolerance in flow units for `curves: 'fit'` (default: `tolerance`, 0.25). */
@@ -976,6 +1344,10 @@ type CombineShapeNodesResult<TNode extends CanvasNode = CanvasNode> = {
     removeIds: string[];
     /** New path shape node(s): one, or one per region for `divide`. */
     nodes: TNode[];
+    /** Engine that produced the geometry (`polygon` after a fallback). */
+    engine: 'curve' | 'polygon';
+    /** Why the curve engine fell back to polygons. */
+    fallbackReason?: string;
 } | {
     ok: false;
     operation: ShapeOperation;
@@ -1029,6 +1401,129 @@ declare function revertShapeCombination<TNode extends CanvasNode>(nodes: TNode[]
     removeIds: Iterable<string>;
     nodes: TNode[];
 }, previous: TNode[]): TNode[];
+/** Per-node path edits: `offset` (Offset Path) and `outlineStroke` (Outline Stroke). */
+type ShapePathEditOperation = 'offset' | 'outlineStroke';
+/** Why `offsetShapeNodes` / `outlineShapeNodeStrokes` refused. */
+type ShapePathEditRefusal = 
+/** A selected shape is locked. */
+'locked'
+/** No shape node was selected. */
+ | 'no-shapes'
+/** Outline Stroke: no selected shape has a visible stroke. */
+ | 'no-stroke'
+/** Every result is empty (e.g. an inset larger than the shapes). */
+ | 'empty'
+/** The offset distance or stroke width is not a finite number. */
+ | 'invalid';
+type ShapePathEditResult<TNode extends CanvasNode = CanvasNode> = {
+    ok: true;
+    operation: ShapePathEditOperation;
+    /** Ids of the replaced nodes. */
+    removeIds: string[];
+    /** All new nodes (a replaced node may come back with the same id). */
+    nodes: TNode[];
+    /** Each replaced node with the nodes that take its place, in stacking order. */
+    replacements: {
+        id: string;
+        nodes: TNode[];
+    }[];
+} | {
+    ok: false;
+    operation: ShapePathEditOperation;
+    reason: ShapePathEditRefusal;
+};
+interface ShapePathEditBaseOptions extends NodeRectOptions {
+    /** Id factory for new nodes (default `crypto.randomUUID`, with a counter fallback). */
+    createId?: (index: number) => string;
+    /** Node `type` for the new nodes (default: the source node's type). */
+    nodeType?: string;
+    /** Decimal places in the path data (default 3). */
+    precision?: number;
+    /** Select the new nodes (default `true`). */
+    select?: boolean;
+    /** Maximum error of the approximated offset curves in flow units (default 0.01). */
+    tolerance?: number;
+    /** Point-merge tolerance passed to the boolean engine. */
+    epsilon?: number;
+    /** Called with the reason when the curve engine falls back to polygons. */
+    onFallback?: (reason: string) => void;
+}
+interface OffsetShapeNodesOptions extends ShapePathEditBaseOptions {
+    /** Corner style of the offset outline (default `miter`). */
+    join?: StrokeJoin;
+    /** Miter limit (default 4). */
+    miterLimit?: number;
+    /** Keep the original shape above the offset one (Illustrator style; default `false`: replace it). */
+    keepOriginal?: boolean;
+}
+interface OutlineShapeStrokesOptions extends ShapePathEditBaseOptions {
+    /** Stroke width in flow units (default: the shape's `strokeWidth`, 1 when unset). */
+    width?: number;
+    /** Default `miter`, as SVG. */
+    join?: StrokeJoin;
+    /** Default `butt`, as SVG. */
+    cap?: StrokeCap;
+    /** Default 4, as SVG. */
+    miterLimit?: number;
+    /** Dash pattern (as `stroke-dasharray`). */
+    dash?: readonly number[];
+    dashOffset?: number;
+    /**
+     * Keep the shape's fill as the original node with its stroke removed, below the outlined
+     * stroke (default `true`). With `false`, or when the shape has no visible fill, the node is
+     * replaced by the outlined stroke alone.
+     */
+    keepFill?: boolean;
+}
+/** Whether a shape draws a stroke (a stroke colour other than `none` and a positive width). */
+declare function hasVisibleStroke(shape: ShapeDescription | null): boolean;
+/** Checks whether `offsetShapeNodes` can run (it cannot predict an `empty` result). */
+declare function canOffsetShapeNodes(nodes: CanvasNode[], ids: Iterable<string>): {
+    ok: true;
+    shapeIds: string[];
+} | {
+    ok: false;
+    reason: 'locked' | 'no-shapes';
+};
+/** Checks whether `outlineShapeNodeStrokes` can run. */
+declare function canOutlineShapeNodeStrokes(nodes: CanvasNode[], ids: Iterable<string>): {
+    ok: true;
+    shapeIds: string[];
+} | {
+    ok: false;
+    reason: 'locked' | 'no-shapes' | 'no-stroke';
+};
+/**
+ * Offset Path on shape nodes: each selected shape grows (`distance > 0`) or shrinks
+ * (`distance < 0`) by `distance` flow units, keeping curves. The result replaces the shape
+ * (or sits below it with `keepOriginal`) as a `path` shape node with the same paint. Shapes
+ * whose offset is empty are left unchanged; refuses when every result is empty, a selected
+ * shape is locked or no shape is selected. Pure: apply with `applyShapeReplacement`.
+ */
+declare function offsetShapeNodes<TNode extends CanvasNode>(nodes: TNode[], ids: Iterable<string>, distance: number, options?: OffsetShapeNodesOptions): ShapePathEditResult<TNode>;
+/**
+ * Outline Stroke on shape nodes: each selected shape with a visible stroke gets its stroke
+ * converted to a filled `path` shape node (filled with the stroke colour, no stroke), using
+ * the stroke width in flow units (strokes do not scale with the node) and SVG's default
+ * miter join, miter limit 4 and butt caps unless overridden. The shape's fill stays as the
+ * original node without its stroke, below the outline (`keepFill`). Pure: apply with
+ * `applyShapeReplacement`.
+ */
+declare function outlineShapeNodeStrokes<TNode extends CanvasNode>(nodes: TNode[], ids: Iterable<string>, options?: OutlineShapeStrokesOptions): ShapePathEditResult<TNode>;
+/**
+ * Applies a successful `offsetShapeNodes` / `outlineShapeNodeStrokes` result: each replaced
+ * node is swapped in place for its replacement nodes, so the stacking order of everything
+ * else is kept. With `deselect` (default `true`) other nodes are deselected when the
+ * result is selected. Undo with `revertShapeCombination(nodes, result, previous)`.
+ */
+declare function applyShapeReplacement<TNode extends CanvasNode>(nodes: TNode[], change: {
+    replacements: {
+        id: string;
+        nodes: TNode[];
+    }[];
+}, options?: {
+    deselect?: boolean;
+}): TNode[];
 
 /** A resize handle, named like xyflow's `ControlPosition`. */
 type ResizeHandle = 'top-left' | 'top' | 'top-right' | 'right' | 'bottom-right' | 'bottom' | 'bottom-left' | 'left';
@@ -1100,6 +1595,214 @@ declare function snapNodeResize(nodes: CanvasNode[], id: string, rect: Rect, han
  */
 declare function getResizingNodeRect(node: CanvasNode, lookup: ReadonlyMap<string, CanvasNode>, options?: NodeRectOptions): Rect;
 
+/**
+ * Figma-style auto layout for xyflow sub-flows.
+ *
+ * A *frame* is any node with `data.layout` (an {@link AutoLayout}); its children are the nodes
+ * whose `parentId` is the frame, in node-array order. Children may carry `data.childLayout`
+ * (an {@link AutoLayoutChild}) for their own sizing, min / max, absolute positioning,
+ * constraints and grid cell. The functions here are pure: they return `CanvasNodeUpdate`s
+ * (positions relative to the parent, sizes) for `applyNodeUpdates`.
+ */
+/** Data key holding a frame's {@link AutoLayout}. */
+declare const AUTO_LAYOUT_DATA_KEY = "layout";
+/** Data key holding a child's {@link AutoLayoutChild}. */
+declare const CHILD_LAYOUT_DATA_KEY = "childLayout";
+type AutoLayoutMode = 'horizontal' | 'vertical' | 'grid';
+/** `fixed` keeps the size, `hug` fits the content (frames and text), `fill` shares the parent's free space. */
+type AutoLayoutSizing = 'fixed' | 'hug' | 'fill';
+type AutoLayoutAlignMain = 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+type AutoLayoutAlignCross = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+/** How wrapped lines share the free cross space: packed by `alignCross` (`auto`) or spread (`space-between`). */
+type AutoLayoutAlignContent = 'auto' | 'space-between';
+/** `number` (all sides), `[vertical, horizontal]`, `[top, right, bottom, left]` or per side. */
+type AutoLayoutPadding = number | [number, number] | [number, number, number, number] | {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+interface AutoLayoutSize {
+    width?: number;
+    height?: number;
+}
+interface AutoLayoutSizingPair {
+    width?: AutoLayoutSizing;
+    height?: AutoLayoutSizing;
+}
+/** A grid track: pixels, `'hug'` (fits its content), `'2fr'` or `{ fr: 2 }` (shares the rest like CSS `fr`). */
+type AutoLayoutGridTrack = number | 'hug' | `${number}fr` | {
+    fr: number;
+};
+interface AutoLayoutGrid {
+    /** Column count (all `1fr`) or the column tracks (default 2 columns). */
+    columns?: number | AutoLayoutGridTrack[];
+    /** Minimum row count or the row tracks (default 1); rows are added to fit the children. Missing tracks are `1fr`. */
+    rows?: number | AutoLayoutGridTrack[];
+}
+/** A frame's auto layout (`node.data.layout`). */
+interface AutoLayout {
+    mode: AutoLayoutMode;
+    /** Main-axis gap (grid: column gap). Negative gaps overlap. Default 0. */
+    gap?: number;
+    /** Gap between wrapped lines (grid: row gap). Default: `gap`. */
+    rowGap?: number;
+    /** Default 0. */
+    padding?: AutoLayoutPadding;
+    /** Horizontal / vertical: wrap into lines when the main axis runs out (ignored while hugging it). */
+    wrap?: boolean;
+    /** Default `start`. Grid: the cell alignment along x (`start`, `center`, `end`). */
+    alignMain?: AutoLayoutAlignMain;
+    /** Default `start`. `baseline` applies to horizontal layouts. Grid: the cell alignment along y. */
+    alignCross?: AutoLayoutAlignCross;
+    alignContent?: AutoLayoutAlignContent;
+    /** The frame's own sizing (`childLayout.sizing` wins when both are set). Default `fixed`. */
+    sizing?: AutoLayoutSizingPair;
+    /** The frame's own limits (`childLayout.min` / `max` win when set). */
+    min?: AutoLayoutSize;
+    max?: AutoLayoutSize;
+    grid?: AutoLayoutGrid;
+}
+type AutoLayoutHorizontalConstraint = 'left' | 'right' | 'leftRight' | 'center' | 'scale';
+type AutoLayoutVerticalConstraint = 'top' | 'bottom' | 'topBottom' | 'center' | 'scale';
+interface AutoLayoutConstraints {
+    horizontal?: AutoLayoutHorizontalConstraint;
+    vertical?: AutoLayoutVerticalConstraint;
+}
+type AutoLayoutCellAlign = 'start' | 'center' | 'end';
+/** A grid child's cell. Column / row are 0-based anchors; unanchored children flow in reading order. */
+interface AutoLayoutGridArea {
+    column?: number;
+    row?: number;
+    columnSpan?: number;
+    rowSpan?: number;
+    /** The child's own alignment in its cell (wins over the frame's). */
+    alignX?: AutoLayoutCellAlign;
+    alignY?: AutoLayoutCellAlign;
+}
+/** A child's layout properties (`node.data.childLayout`). */
+interface AutoLayoutChild {
+    sizing?: AutoLayoutSizingPair;
+    min?: AutoLayoutSize;
+    max?: AutoLayoutSize;
+    /** Ignore auto layout: keep its place and follow `constraints` when the frame resizes. */
+    absolute?: boolean;
+    /** How the child follows its parent's resizes (default left / top). */
+    constraints?: AutoLayoutConstraints;
+    gridArea?: AutoLayoutGridArea;
+}
+/**
+ * Measuring hooks. `size` defaults to `getNodeSize` (xyflow `measured` size, then `width` /
+ * `height`, then style). Nodes for which `textSize` returns a size are *text-like*: they can
+ * hug, and wrap (`textHeight`) when their width is set by the layout.
+ */
+interface AutoLayoutMeasure {
+    size?: (node: CanvasNode) => {
+        width: number;
+        height: number;
+    } | undefined;
+    /** Natural (unwrapped) size of a text-like node. */
+    textSize?: (node: CanvasNode) => {
+        width: number;
+        height: number;
+    } | undefined;
+    /** Height of a text-like node wrapped at `width`. */
+    textHeight?: (node: CanvasNode, width: number) => number | undefined;
+    /** Distance from the node's top to its first text baseline (for `alignCross: 'baseline'`). */
+    textBaseline?: (node: CanvasNode) => number | undefined;
+}
+interface AutoLayoutOptions {
+    measure?: AutoLayoutMeasure;
+    /** Size resolution for unmeasured nodes when `measure.size` is not given. */
+    rectOptions?: NodeRectOptions;
+}
+type Axis = 'width' | 'height';
+/** Clamps a size to `[min, max]`; non-finite or negative sizes become 0 and min wins over a smaller max. */
+declare function clampLayoutSize(value: number, min?: number, max?: number): number;
+/** The node's auto layout, or `undefined` when it is not an auto layout frame. */
+declare function getAutoLayout(node: CanvasNode | undefined | null): AutoLayout | undefined;
+/** Whether the node is an auto layout frame. */
+declare function isAutoLayoutFrame(node: CanvasNode | undefined | null): boolean;
+/** The node's child layout properties (empty when unset). */
+declare function getChildLayout(node: CanvasNode | undefined | null): AutoLayoutChild;
+/** Effective sizing of a node on one axis: `childLayout.sizing`, then `layout.sizing`, then `fixed`. */
+declare function getLayoutSizing(node: CanvasNode, axis: Axis): AutoLayoutSizing;
+/** Padding as `[top, right, bottom, left]`, sanitised (non-finite and negative values become 0). */
+declare function resolvePadding(padding: AutoLayoutPadding | undefined): [number, number, number, number];
+/** A grid child's cell (0-based column / row and spans). */
+interface AutoLayoutGridCell {
+    id: string;
+    column: number;
+    row: number;
+    columnSpan: number;
+    rowSpan: number;
+}
+/** A grid frame's resolved geometry (frame-local): column x ranges, row y ranges, cells and the size it wants. */
+interface AutoLayoutGridGeometry {
+    columns: [number, number][];
+    rows: [number, number][];
+    cells: AutoLayoutGridCell[];
+    width: number;
+    height: number;
+}
+/**
+ * Lays out one auto layout frame's children and sizes the frame when it hugs (nested frames
+ * that are resized by the layout are laid out again). Returns the position / size updates.
+ */
+declare function layoutFrame(nodes: CanvasNode[], frameId: string, options?: AutoLayoutOptions): CanvasNodeUpdate[];
+/** Lays out every auto layout frame, children before parents, so nested hugging settles in one pass. */
+declare function layoutAll(nodes: CanvasNode[], options?: AutoLayoutOptions): CanvasNodeUpdate[];
+/**
+ * Lays out `changedId` (when it is a frame) and then each of its auto layout ancestors,
+ * innermost first. Use it after a node inside a frame was added, removed, resized or moved.
+ */
+declare function layoutUp(nodes: CanvasNode[], changedId: string, options?: AutoLayoutOptions): CanvasNodeUpdate[];
+/** {@link layoutUp} for several changed nodes at once (each chain once, innermost frames first). */
+declare function layoutUpMany(nodes: CanvasNode[], changedIds: Iterable<string>, options?: AutoLayoutOptions): CanvasNodeUpdate[];
+/**
+ * Children of `parentId` follow their constraints after the parent was resized from
+ * `previousSize` to its current size. In an auto layout frame only absolute children move
+ * (the layout places the others). Returns the updates.
+ */
+declare function applyConstraints(nodes: CanvasNode[], parentId: string, previousSize: {
+    width: number;
+    height: number;
+}, options?: AutoLayoutOptions): CanvasNodeUpdate[];
+/** The resolved grid of a grid frame (frame-local), from its children's current sizes. */
+declare function getAutoLayoutGrid(nodes: CanvasNode[], frameId: string, options?: AutoLayoutOptions): AutoLayoutGridGeometry | undefined;
+/** Ids of the children a frame places (visible, not absolute), in order. */
+declare function getFlowChildren(nodes: CanvasNode[], frameId: string): string[];
+/** The nearest auto layout frame that places `id` (its parent, when `id` is a flow child). */
+declare function getLayoutParent(nodes: CanvasNode[], id: string): CanvasNode | undefined;
+/**
+ * Makes a node's sizing coherent with where it sits, and that of its children: `fill` needs an
+ * auto layout parent that does not hug that axis (and a flow child), `hug` needs an auto layout
+ * frame or a text-like node (see `measure.textSize`); otherwise the axis becomes `fixed`.
+ * Writes `data.childLayout.sizing`. Returns a new array (unchanged nodes keep their identity).
+ */
+declare function makeSizingCoherent<TNode extends CanvasNode>(nodes: TNode[], id: string, options?: AutoLayoutOptions): TNode[];
+interface AutoLayoutInsertTarget {
+    frameId: string;
+    /** Index among the frame's flow children, not counting the dragged node. */
+    index: number;
+    /** Insertion marker (absolute flow coordinates) for `<CanvasGuidesLayer>`. */
+    guide: GuideLine;
+}
+/**
+ * Where a node dropped at `point` (absolute flow coordinates) goes among the flow children of
+ * auto layout frame `frameId`: the reading-order index of the slot under the point. `excludeId`
+ * (the dragged node) is left out of the siblings.
+ */
+declare function getAutoLayoutInsertTarget(nodes: CanvasNode[], frameId: string, point: XYPosition, options?: AutoLayoutOptions & {
+    excludeId?: string;
+}): AutoLayoutInsertTarget | undefined;
+/**
+ * Moves child `childId` of an auto layout frame to flow index `index` (among its flow siblings)
+ * by reordering the node array; parents still precede their children. Returns a new array
+ * (the same array when nothing moves).
+ */
+declare function moveLayoutChild<TNode extends CanvasNode>(nodes: TNode[], childId: string, index: number): TNode[];
+
 /** Minimal history surface (`HistoryManager` satisfies it). */
 interface ArrangeHistoryTarget {
     execute(command: Command): void;
@@ -1129,6 +1832,11 @@ interface CanvasArrangeControllerOptions<TNode extends CanvasNode = CanvasNode>
     rectOptions?: NodeRectOptions;
     /** Called whenever the guide segments change (set while dragging, cleared on drop). */
     onGuidesChange?: (guides: GuideLine[]) => void;
+    /**
+     * Re-run auto layout (`data.layout` frames) around the nodes an arrange action moves or
+     * resizes, in the same undoable step. `true` uses the default measuring.
+     */
+    autoLayout?: boolean | AutoLayoutOptions;
 }
 /**
  * A React Flow / SvelteFlow style node change; only `position` changes are inspected.
@@ -1176,6 +1884,23 @@ declare function createCanvasArrangeController<TNode extends CanvasNode = Canvas
     divide: (ids?: Iterable<string>, o?: CombineShapeNodesOptions) => CombineShapeNodesResult<TNode>;
     /** Whether the shape operations can run on `ids` (default: the selection). */
     canCombineShapes: (ids?: Iterable<string>) => boolean;
+    /**
+     * Offset Path: grows (`distance > 0`) or shrinks (`distance < 0`) every shape among
+     * `ids` (default: the selection) by `distance` flow units, keeping curves, as one
+     * undoable step. Refuses without changing anything when a shape is locked, no shape is
+     * selected or every result is empty.
+     */
+    offsetShapes(distance: number, ids?: Iterable<string>, offsetOptions?: OffsetShapeNodesOptions): ShapePathEditResult<TNode>;
+    /** Whether `offsetShapes` can run on `ids` (default: the selection). */
+    canOffsetShapes: (ids?: Iterable<string>) => boolean;
+    /**
+     * Outline Stroke: converts the strokes of the shapes among `ids` (default: the
+     * selection) to filled path shapes, as one undoable step. Refuses when a shape is
+     * locked or no selected shape has a visible stroke.
+     */
+    outlineStroke(ids?: Iterable<string>, outlineOptions?: OutlineShapeStrokesOptions): ShapePathEditResult<TNode>;
+    /** Whether `outlineStroke` can run on `ids` (default: the selection). */
+    canOutlineStroke: (ids?: Iterable<string>) => boolean;
     /**
      * Runs a shortcut action. Scene actions are not handled here (see the scenes store);
      * returns `false` for them and for unknown actions.
@@ -1370,4 +2095,209 @@ declare function fitPathData(ring: readonly Point[], options?: FitPathDataOption
  */
 declare function fitFreehandPath(points: readonly Point[], options?: Omit<FitPathDataOptions, 'closed'>): string;
 
-export { AlignEdge, AlignNodesOptions, type ArrangeHistoryTarget, CONNECTION_LINE_TYPES, CanvasArrangeAction, type CanvasArrangeController, type CanvasArrangeControllerOptions, CanvasClipboardPayload, type CanvasConnectionLineType, CanvasEdge, type CanvasHeightOptions, CanvasLayoutOptions, CanvasNode, CanvasNodeStyle, CanvasNodeUpdate, type CanvasScene, type CanvasScenesOptions, type CanvasScenesState, CanvasScenesStore, type CanvasViewport, type Clock, type CombineShapeNodesOptions, type CombineShapeNodesRefusal, type CombineShapeNodesResult, type ConnectorSnap, type ConnectorSnapOptions, type ConnectorSnapTarget, type CubicSegment, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, DirectionalDisplacementOptions, DistributeAxis, DistributeMode, DistributeNodesOptions, type EllipseShape, FanOutTrajectoryOptions, type FitCubicsOptions, type FitPathDataOptions, type FitViewportOptions, type FlattenOptions, type GuideIndex, type GuideLine, IncrementalLayoutOptions, ManualClock, MatchSizeOptions, type MeasureGuide, type MeasureSelectionOptions, type MeasureSelectionResult, type MultiNodeTransitionOptions, type MultiPolygon, NodeRectOptions, NodeTransition, type PathCommand, type PathShape, PlaceBesideOptions, Point, type PolygonBooleanOperation, type PolygonBooleanOptions, type PolygonFillRule, type PolygonInput, type PolygonOperand, type PolygonPiece, type PolygonRing, type PolygonToPathOptions, type PolygonWithHoles, Position, type PositionChangeLike, RESIZE_HANDLES, Rect, type RectShape, ReflowDisplacementOptions, type RegularPolygonShape, type ResizeHandle, SHAPE_DATA_KEY, SHAPE_KINDS, SHAPE_NODE_TYPE, SHAPE_OPERATIONS, type SerializedCanvasScenes, type ShapeDescription, type ShapeKind, type ShapeNodePolygonOptions, type ShapeOperation, type ShapePaint, type ShapeRenderData, type ShapeSize, Side, SizeDimension, type SnapGuidesOptions, type SnapNodeDragOptions, type SnapNodeDragResult, type SnapNodeResizeOptions, type SnapNodeResizeResult, type SnapResizeOptions, type SnapResizeResult, type SnapResult, type StarShape, StreamingLayoutManager, type StreamingLayoutManagerOptions, TrajectoryFunction, XYPosition, ZOrderOperation, applyShapeCombination, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canCombineShapeNodes, canvasHeight, centerNodes, centre, collectDescendantIds, combineShapeNodes, computeNodesBoundingBox, computeSnapGuides, connectedOnly, createBezierTrajectory, createCanvasArrangeController, createCanvasScenesStore, createFanOutTrajectory, createGuideIndex, createNodeGuideIndex, cubicPointAt, cubicsToPathData, defaultEasing, dividePolygons, ensureLayout, estimateCanvasHeight, estimateNodeSize, findConnectorSnap, fitCubicRun, fitCubics, fitFreehandPath, fitPathData, fitViewportToNodes, fitViewportToRect, flattenSvgPath, flowSide, formatNumber, getCenteredNodePosition, getLayoutedNodes, getNodeShape, getResizingNodeRect, getShapeRenderData, getShapeSvg, handlePoint, inferResizeHandle, intersectPolygons, isEventFromTextInput, isMeasureModifierHeld, isShapeDescription, isShapeNode, isStraightCubic, isValidCanvasEdge, isValidCanvasNode, isValidCanvasScene, isValidUrl, layoutBounds, linearPositionTrajectory, linearTrajectory, measureBetween, measureLabel, measureSelection, measureToLine, multiPolygonArea, multiPolygonBounds, nearestHandlePositions, oppositePosition, overlaps, pageHidden, parseCanvasClipboardData, parseCanvasScenes, parseSvgPath, placeBeside, pointInMultiPolygon, pointInRings, polygonArea, polygonBoolean, polygonToSvgPath, positionToSide, realClock, remapPastedNodes, repositionNodesTo, resizeHandleAxes, revertShapeCombination, ringSignedArea, runMultiNodeTransition, serializeCanvasNodes, shapeNodeToPolygon, shapeToPolygon, sideToPosition, simplifyRing, snapNodeDrag, snapNodeResize, snapResize, snapToGrid, subtractPolygons, unionPolygons, withStyleOpacity, xorPolygons };
+interface CanvasAutoLayoutControllerOptions<TNode extends CanvasNode = CanvasNode> extends AutoLayoutOptions {
+    getNodes: () => TNode[];
+    setNodes: (nodes: TNode[]) => void;
+    /** When set, controller actions (add / remove / resize / reorder / apply) are one undoable step each. */
+    history?: ArrangeHistoryTarget;
+    /** Turns automatic relayout off (explicit `applyAutoLayout` still works). Default `true`. */
+    enabled?: boolean;
+    /** Reorder flow children by dragging them inside their frame (default `true`). */
+    dragReorder?: boolean;
+    /** Called when the drop marker of a reorder drag changes (empty when none). */
+    onGuidesChange?: (guides: GuideLine[]) => void;
+}
+/**
+ * Merges the updates of several layout passes (later ones win per field).
+ */
+declare function mergeNodeUpdates(...lists: CanvasNodeUpdate[][]): CanvasNodeUpdate[];
+/**
+ * Updates that re-run auto layout around `ids` after a change: each id's own layout (if a
+ * frame) and its auto layout ancestors, plus the frames that lost removed children
+ * (`parentIds`). Pure helper used by the controllers.
+ */
+declare function relayoutUpdates(nodes: CanvasNode[], ids: Iterable<string>, options?: AutoLayoutOptions): CanvasNodeUpdate[];
+/**
+ * Framework-agnostic auto layout controller shared by the React hook and the Svelte rune.
+ * Applies auto layout to frames (`data.layout`) after nodes inside them are added, removed,
+ * resized or reordered, either through its own (undoable) actions or by watching the flow's
+ * node changes (`noteChanges` + `flush`), and reorders flow children dragged within a frame.
+ */
+declare function createCanvasAutoLayoutController<TNode extends CanvasNode = CanvasNode>(options: CanvasAutoLayoutControllerOptions<TNode>): {
+    /** Drop marker of the active reorder drag (flow coordinates); empty otherwise. */
+    readonly guides: GuideLine[];
+    /**
+     * Lays out frame `frameId` and its auto layout ancestors (default: every frame) as one
+     * (optionally undoable) step. Returns the updates.
+     */
+    applyAutoLayout(frameId?: string): CanvasNodeUpdate[];
+    /** Updates that relayout around `ids` on the current nodes, without applying them. */
+    layoutUpdates(ids: Iterable<string>): CanvasNodeUpdate[];
+    /**
+     * Applies the relayout around `ids` (frames, or nodes inside frames) directly, not
+     * recorded in history: auto layout is derived state, re-run after any change.
+     */
+    relayout(ids: Iterable<string>): CanvasNodeUpdate[];
+    /**
+     * Adds `node` (into the frame named by its `parentId`, at flow `index` when given) and
+     * lays out its frame, as one step.
+     */
+    addNode(node: TNode, addOptions?: {
+        index?: number;
+    }): CanvasNodeUpdate[];
+    /** Removes nodes (and their descendants) and lays out the frames they leave, as one step. */
+    removeNodes(ids: Iterable<string>): CanvasNodeUpdate[];
+    /**
+     * Resizes node `id` (its children follow their constraints) and lays out around it,
+     * as one step.
+     */
+    resizeNode(id: string, size: {
+        width?: number;
+        height?: number;
+    }): CanvasNodeUpdate[];
+    /** Moves flow child `childId` to flow index `index` in its frame and lays it out, as one step. */
+    moveChild(childId: string, index: number): CanvasNodeUpdate[];
+    /** Where flow child `id` would drop if released at `point` (default: its centre). */
+    getInsertTarget(id: string, point?: XYPosition): AutoLayoutInsertTarget | undefined;
+    /** Records the start position of a reorder drag. Optional: `dragReorder` records it lazily. */
+    beginReorderDrag(id: string): void;
+    /**
+     * While flow child `id` is dragged (as currently positioned in `getNodes()`): updates the
+     * drop marker. Returns the insert target.
+     */
+    dragReorder(id: string, point?: XYPosition): AutoLayoutInsertTarget | undefined;
+    /**
+     * Ends a reorder drag: moves `id` to the slot under `point` (default: its centre) and lays
+     * the frame out, as one undoable step whose undo puts the node back where the drag began.
+     */
+    endReorderDrag(id: string, point?: XYPosition): CanvasNodeUpdate[];
+    /**
+     * Notes a batch of React Flow / SvelteFlow style node changes (before or after they are
+     * applied) so `flush` can relayout: dimension changes (measured sizes, resize ends),
+     * added and removed nodes, and position changes of flow children (reorder drags).
+     * Returns the changes unchanged.
+     */
+    noteChanges<TChange extends PositionChangeLike>(changes: TChange[]): TChange[];
+    /**
+     * Notes nodes that were already removed (e.g. SvelteFlow's `ondelete`), so `flush`
+     * relayouts the frames they left. The nodes must still carry their `parentId`.
+     */
+    noteRemoved(removed: Iterable<{
+        id: string;
+        parentId?: string;
+    }>): void;
+    /** Whether `noteChanges` left work for `flush`. */
+    readonly hasPending: boolean;
+    /**
+     * Applies the work noted by `noteChanges` to the current nodes: drop markers while
+     * dragging, committed reorders on drop (undoable), and a relayout (not recorded) for
+     * size, add and remove changes. Call it once the changes are applied.
+     */
+    flush(): CanvasNodeUpdate[];
+    /** Whether `id` is an auto layout frame. */
+    isFrame: (id: string) => boolean;
+};
+type CanvasAutoLayoutController<TNode extends CanvasNode = CanvasNode> = ReturnType<typeof createCanvasAutoLayoutController<TNode>>;
+
+/**
+ * Design-token bindings on canvas nodes.
+ *
+ * - `node.data.tokenBindings` maps a property key (`fill`, `opacity`, `gap`, …) to a variable id.
+ * - `node.data.tokenModes` maps a collection id to a mode id: an explicit mode for the node and
+ *   its descendants (via `parentId`); the nearest ancestor wins, then the root `modes` option,
+ *   then the collection's default mode.
+ *
+ * Bound properties are *materialised*: `resolveCanvasTokens` writes the resolved values into
+ * the ordinary node fields (`data.shape.fill`, `style.backgroundColor`, `data.layout.gap`, …), so
+ * renderers, auto layout and exports need no token awareness, and a node whose variable is
+ * gone keeps its last value. Both keys live in `data`, so they survive copy / paste,
+ * duplication and serialisation unchanged.
+ */
+/** Data key holding a node's property → variable id bindings. */
+declare const TOKEN_BINDINGS_DATA_KEY = "tokenBindings";
+/** Data key holding a node's explicit collection → mode choices. */
+declare const TOKEN_MODES_DATA_KEY = "tokenModes";
+/** A node property a variable can drive. */
+interface CanvasTokenProperty {
+    key: string;
+    label: string;
+    /** The variable type it takes. */
+    type: TokenType;
+    /** The scope pickers filter by (variables scoped elsewhere are not offered). */
+    scope?: TokenScope | ((node: CanvasNode) => TokenScope | undefined);
+    appliesTo(node: CanvasNode): boolean;
+    read(node: CanvasNode): TokenLiteral | undefined;
+    /** Returns the node with the value written, or the same node when nothing changes. */
+    write(node: CanvasNode, value: TokenLiteral): CanvasNode;
+}
+/** A style property (camelCase name) from a style string or object. */
+declare function readNodeStyleProperty(style: CanvasNodeStyle | undefined | null, prop: string): string | number | undefined;
+/**
+ * Returns `style` with one property set (or removed with `undefined`), keeping its
+ * representation. Numbers become `px` in style strings unless `unitless`.
+ */
+declare function writeNodeStyleProperty(style: CanvasNodeStyle | undefined | null, prop: string, value: string | number | undefined, unitless?: boolean): CanvasNodeStyle | undefined;
+/** The built-in bindable properties. */
+declare const CANVAS_TOKEN_PROPERTIES: readonly CanvasTokenProperty[];
+interface CanvasTokenOptions {
+    /** Modes for nodes without an explicit mode up their tree (e.g. the page's). */
+    modes?: TokenModeContext;
+    /** Bindable properties (default {@link CANVAS_TOKEN_PROPERTIES}); add your own to extend. */
+    properties?: readonly CanvasTokenProperty[];
+}
+/** The node's property → variable id bindings. */
+declare function getNodeTokenBindings(node: CanvasNode | undefined | null): Readonly<Record<string, string>>;
+/** The node's own explicit modes (collection id → mode id). */
+declare function getNodeTokenModes(node: CanvasNode | undefined | null): Readonly<Record<string, string>>;
+declare function getCanvasTokenProperty(key: string, options?: CanvasTokenOptions): CanvasTokenProperty | undefined;
+/** Properties a variable can be bound to on this node. */
+declare function getBindableTokenProperties(node: CanvasNode, options?: CanvasTokenOptions): CanvasTokenProperty[];
+/** The scope of a property on a node. */
+declare function getTokenPropertyScope(property: CanvasTokenProperty, node: CanvasNode): TokenScope | undefined;
+/** Variables a picker offers for `property` on `node`: the property's type, in scope. */
+declare function getTokensForProperty(state: TokenState, property: CanvasTokenProperty, node: CanvasNode): TokenVariable[];
+/**
+ * The modes `node` is in: the root `modes`, overridden by each ancestor's explicit modes from
+ * the top down, then the node's own. Modes `state` doesn't know are ignored.
+ */
+declare function getEffectiveTokenModes(node: CanvasNode, nodes: readonly CanvasNode[] | ReadonlyMap<string, CanvasNode>, state?: TokenState, options?: Pick<CanvasTokenOptions, 'modes'>): Record<string, string>;
+/**
+ * Writes every bound property's resolved value into its node. Returns the same array when
+ * nothing changed (unchanged nodes keep their identity), so it is safe to run on every change.
+ * Bindings that don't resolve (deleted variable, cycle) keep the node's current value.
+ */
+declare function resolveCanvasTokens<TNode extends CanvasNode>(nodes: readonly TNode[], state: TokenState, options?: CanvasTokenOptions): TNode[];
+interface CanvasTokenBindingInfo {
+    property: CanvasTokenProperty;
+    variableId: string;
+    variable: TokenVariable | undefined;
+    resolution: TokenResolution;
+}
+/** Each binding of a node with its variable and resolution (for inspectors and diagnostics). */
+declare function inspectNodeTokens(node: CanvasNode, nodes: readonly CanvasNode[], state: TokenState, options?: CanvasTokenOptions): CanvasTokenBindingInfo[];
+/**
+ * Binds `property` of each node in `ids` to `variableId` (or unbinds with `null`, keeping the
+ * current value) and resolves. Throws `type-mismatch` when the variable's type doesn't fit the
+ * property, `not-found` for unknown variables or properties. Nodes the property doesn't apply
+ * to are left alone.
+ */
+declare function bindCanvasToken<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, propertyKey: string, variableId: string | null, state: TokenState, options?: CanvasTokenOptions): TNode[];
+/**
+ * Sets (or with `null` clears, back to "Auto") the explicit mode of `collectionId` on each node
+ * in `ids`, then resolves, so descendants follow.
+ */
+declare function setCanvasTokenMode<TNode extends CanvasNode>(nodes: readonly TNode[], ids: Iterable<string>, collectionId: string, modeId: string | null, state: TokenState, options?: CanvasTokenOptions): TNode[];
+/**
+ * Detaches bindings to `variableIds` (default: every binding whose variable is missing from
+ * `state`): each property keeps its value resolved in `state` and the binding is removed. Pass
+ * the state from *before* a delete (`TokenChangeEvent.previous`) so deleted variables still
+ * resolve.
+ */
+declare function detachTokenBindings<TNode extends CanvasNode>(nodes: readonly TNode[], state: TokenState, variableIds?: Iterable<string>, options?: CanvasTokenOptions): TNode[];
+/**
+ * Removes explicit modes `state` no longer knows (deleted collections or modes), like figcraft
+ * resetting such layers to "Auto". Resolution already ignores them; this tidies the data.
+ */
+declare function pruneCanvasTokenModes<TNode extends CanvasNode>(nodes: readonly TNode[], state: TokenState): TNode[];
+
+export { AUTO_LAYOUT_DATA_KEY, type AffineMatrix, AlignEdge, AlignNodesOptions, type ArrangeHistoryTarget, type AutoLayout, type AutoLayoutAlignContent, type AutoLayoutAlignCross, type AutoLayoutAlignMain, type AutoLayoutCellAlign, type AutoLayoutChild, type AutoLayoutConstraints, type AutoLayoutGrid, type AutoLayoutGridArea, type AutoLayoutGridCell, type AutoLayoutGridGeometry, type AutoLayoutGridTrack, type AutoLayoutHorizontalConstraint, type AutoLayoutInsertTarget, type AutoLayoutMeasure, type AutoLayoutMode, type AutoLayoutOptions, type AutoLayoutPadding, type AutoLayoutSize, type AutoLayoutSizing, type AutoLayoutSizingPair, type AutoLayoutVerticalConstraint, type BezierCommand, type BezierContour, type BezierPath, type BezierPathInput, type BezierPathToSvgOptions, type BezierSegment, CANVAS_TOKEN_PROPERTIES, CHILD_LAYOUT_DATA_KEY, CONNECTION_LINE_TYPES, CanvasArrangeAction, type CanvasArrangeController, type CanvasArrangeControllerOptions, type CanvasAutoLayoutController, type CanvasAutoLayoutControllerOptions, CanvasClipboardPayload, type CanvasConnectionLineType, CanvasEdge, type CanvasHeightOptions, CanvasLayoutOptions, CanvasNode, CanvasNodeStyle, CanvasNodeUpdate, type CanvasScene, type CanvasScenesOptions, type CanvasScenesState, CanvasScenesStore, type CanvasTokenBindingInfo, type CanvasTokenOptions, type CanvasTokenProperty, type CanvasViewport, type Clock, type CombineShapeNodesOptions, type CombineShapeNodesRefusal, type CombineShapeNodesResult, type ConnectorSnap, type ConnectorSnapOptions, type ConnectorSnapTarget, type CubicSegment, DEFAULT_NODE_HEIGHT, DEFAULT_NODE_WIDTH, DEFAULT_PLACEMENT_GAP, type DashedPath, DirectionalDisplacementOptions, DistributeAxis, DistributeMode, DistributeNodesOptions, type DividePathsResult, type EllipseShape, FanOutTrajectoryOptions, type FitCubicsOptions, type FitPathDataOptions, type FitViewportOptions, type FlattenOptions, type GuideIndex, type GuideLine, IncrementalLayoutOptions, ManualClock, MatchSizeOptions, type MeasureGuide, type MeasureSelectionOptions, type MeasureSelectionResult, type MultiNodeTransitionOptions, type MultiPolygon, NodeRectOptions, NodeTransition, type OffsetPathOptions, type OffsetShapeNodesOptions, type OutlineShapeStrokesOptions, type OutlineStrokeOptions, type PathBooleanOperation, type PathBooleanResult, type PathCommand, type PathOperand, type PathOperandInput, PathOpsError, type PathOpsOptions, type PathOpsReport, type PathPiece, type PathPointAtLength, type PathShape, PlaceBesideOptions, Point, type PolygonBooleanOperation, type PolygonBooleanOptions, type PolygonFillRule, type PolygonInput, type PolygonOperand, type PolygonPiece, type PolygonRing, type PolygonToPathOptions, type PolygonWithHoles, Position, type PositionChangeLike, RESIZE_HANDLES, Rect, type RectShape, ReflowDisplacementOptions, type RegularPolygonShape, type ResizeHandle, SHAPE_DATA_KEY, SHAPE_KINDS, SHAPE_NODE_TYPE, SHAPE_OPERATIONS, type SerializedCanvasScenes, type ShapeDescription, type ShapeKind, type ShapeNodePolygonOptions, type ShapeOperation, type ShapePaint, type ShapePathEditOperation, type ShapePathEditRefusal, type ShapePathEditResult, type ShapeRenderData, type ShapeSize, Side, SizeDimension, type SnapGuidesOptions, type SnapNodeDragOptions, type SnapNodeDragResult, type SnapNodeResizeOptions, type SnapNodeResizeResult, type SnapResizeOptions, type SnapResizeResult, type SnapResult, type StarShape, StreamingLayoutManager, type StreamingLayoutManagerOptions, type StrokeCap, type StrokeJoin, TOKEN_BINDINGS_DATA_KEY, TOKEN_MODES_DATA_KEY, TrajectoryFunction, XYPosition, ZOrderOperation, applyConstraints, applyShapeCombination, applyShapeReplacement, arcToCubics, bezierPathArea, bezierPathBounds, bezierPathLength, bezierPathPointAtLength, bezierPathSignedArea, bezierPathToSvg, bindCanvasToken, blendLayout, boundsOf, calculateDagreReflowDisplacement, calculateDirectionalDisplacement, canCombineShapeNodes, canOffsetShapeNodes, canOutlineShapeNodeStrokes, canvasHeight, centerNodes, centre, clampLayoutSize, closeContour, collectDescendantIds, combineShapeNodes, computeNodesBoundingBox, computeSnapGuides, connectedOnly, contourSignedArea, contoursToPath, countPathSegments, createBezierTrajectory, createCanvasArrangeController, createCanvasAutoLayoutController, createCanvasScenesStore, createFanOutTrajectory, createGuideIndex, createNodeGuideIndex, cubicPointAt, cubicsToPathData, dashContours, defaultEasing, detachTokenBindings, distanceToBezierPath, dividePaths, dividePolygons, ensureLayout, estimateCanvasHeight, estimateNodeSize, excludePaths, findConnectorSnap, fitCubicRun, fitCubics, fitFreehandPath, fitPathData, fitViewportToNodes, fitViewportToRect, flattenSvgPath, flowSide, formatNumber, getAutoLayout, getAutoLayoutGrid, getAutoLayoutInsertTarget, getBindableTokenProperties, getCanvasTokenProperty, getCenteredNodePosition, getChildLayout, getEffectiveTokenModes, getFlowChildren, getLayoutParent, getLayoutSizing, getLayoutedNodes, getNodeShape, getNodeTokenBindings, getNodeTokenModes, getResizingNodeRect, getShapeRenderData, getShapeSvg, getTokenPropertyScope, getTokensForProperty, handlePoint, hasVisibleStroke, inferResizeHandle, inspectNodeTokens, intersectPaths, intersectPolygons, isAutoLayoutFrame, isEventFromTextInput, isMeasureModifierHeld, isShapeDescription, isShapeNode, isStraightCubic, isValidCanvasEdge, isValidCanvasNode, isValidCanvasScene, isValidUrl, layoutAll, layoutBounds, layoutFrame, layoutUp, layoutUpMany, linearPositionTrajectory, linearTrajectory, makeSizingCoherent, measureBetween, measureLabel, measureSelection, measureToLine, mergeNodeUpdates, moveLayoutChild, multiPolygonArea, multiPolygonBounds, nearestHandlePositions, normalizeBezierPath, offsetPath, offsetShapeNodes, oppositePosition, outlineShapeNodeStrokes, outlineStroke, overlaps, pageHidden, parseCanvasClipboardData, parseCanvasScenes, parseSvgPath, pathBoolean, pathToContours, placeBeside, pointInBezierPath, pointInMultiPolygon, pointInRings, polygonArea, polygonBoolean, polygonToSvgPath, positionToSide, pruneCanvasTokenModes, readNodeStyleProperty, realClock, relayoutUpdates, remapPastedNodes, repositionNodesTo, resizeHandleAxes, resolveCanvasTokens, resolvePadding, revertShapeCombination, ringSignedArea, runMultiNodeTransition, segmentBounds, segmentCurvature, segmentDerivative, segmentExtrema, segmentLength, segmentNearest, segmentParamAtLength, segmentPoint, segmentTangent, serializeCanvasNodes, setCanvasTokenMode, shapeNodeToBezierPath, shapeNodeToPolygon, shapeToBezierPath, shapeToPolygon, sideToPosition, simplifyRing, snapNodeDrag, snapNodeResize, snapResize, snapToGrid, splitSegment, strokeOutlineRings, subSegment, subtractPaths, subtractPolygons, toBezierPath, transformBezierPath, trimSegments, unionPolygons, unitePaths, windingNumber, withStyleOpacity, writeNodeStyleProperty, xorPolygons };