@weasel-js/path-tools 0.0.0-stage → 1.11.0

package/dist/index.d.ts

@@ -0,0 +1,1550 @@
+import { PathEditExtension, SnapSource, FeaturePreset, EditableShape, BlendEffect, BendAlongEffect, RepeatAlongEffect, PathNode, Tool, SurfaceContribution, NodeId, PathPaint, BooleanOpResult, BooleansAdapter, BooleanOpOptions, BooleanStrokes, RenderLayer, SceneNode, PathRepresentation, AnchorMarkerShape, EditAnchorsDep, RectPose, AddNodeSpec } from '@weasel-js/core';
+import { DrawCommand } from '@weasel-js/renderer';
+import { AnchorSet, Point, PolygonPath, View, CornerFrame, SoftFalloff, PathConstraintKind, PathConstraint, LengthenMode, Affine, SpiroKind, SegmentType, CornerShape, TrimResult, SpiroPoint, SpiroContour, CornerKeyword } from '@weasel-js/geom';
+import * as _weasel_js_routing from '@weasel-js/routing';
+import { Action, ActionDeps, ToolKeybinding } from '@weasel-js/routing';
+export { ActionParamSchema } from '@weasel-js/routing';
+import { CursorSpec } from '@weasel-js/cursor';
+import { PathWarp, DistortMode, EnvelopeMapping } from '@weasel-js/geom/warp';
+import { VertexWidth, Stroke, HalfWidths } from '@weasel-js/paint';
+import { StrokeEdgeHit, StrokeSide } from '@weasel-js/stroke';
+import { PrefGroup } from '@weasel-js/prefs';
+
+/**
+ * The balance lines path edit can draw over the open path: one per curved
+ * segment, from its first handle's tip to its second's, with the grip
+ * `balanceHandles` drags at the middle, pressed as `balance:N`.
+ */
+
+/** Chrome-caps id the balance lines and their grips are drawn and hit-tested
+ *  under. Off by default. */
+declare const PATH_BALANCE_CHROME_ID = "path-edit.balance";
+/** How the balance lines are drawn. */
+interface PathEditBalanceStyle {
+    /** Color of the line between a segment's handle tips and of its grip's rim. */
+    color?: string;
+    /** Fill of the grip. */
+    gripFill?: string;
+    /** Radius of the grip, in screen px. Default 4. */
+    gripRadiusPx?: number;
+}
+/** Draw commands for `set`'s balance lines and their grips, in screen space. */
+declare function balanceCommands(set: AnchorSet, toScreen: (p: Point) => Point, style?: PathEditBalanceStyle): DrawCommand[];
+/** The balance lines as a path-edit extension: drawn, and their grips
+ *  pressed, while chrome-caps shows {@link PATH_BALANCE_CHROME_ID}. */
+declare function createBalanceExtension(style?: PathEditBalanceStyle): PathEditExtension;
+
+/**
+ * The curvature comb path edit can draw over the open path.
+ */
+
+/** Chrome-caps id the curvature comb is drawn under. Off by default. */
+declare const PATH_COMB_CHROME_ID = "path-edit.comb";
+/** How the curvature comb is drawn. */
+interface PathEditCombOptions {
+    /** Tooth length per unit of curvature, in world units: a tooth over a
+     *  stretch of radius r is `scale / r` long. Default 2000. */
+    scale?: number;
+    /** Teeth per segment, ends included. Default 24. */
+    samplesPerSegment?: number;
+    /** Color of the teeth and of the line through their tips. */
+    color?: string;
+}
+/** Draw commands for `set`'s curvature comb, in screen space. */
+declare function combCommands(set: AnchorSet, toScreen: (p: Point) => Point, opts?: PathEditCombOptions): DrawCommand[];
+/** The comb as a path-edit extension, drawn while chrome-caps shows
+ *  {@link PATH_COMB_CHROME_ID}. `options` is read every frame. */
+declare function createCombExtension(options?: () => PathEditCombOptions | undefined): PathEditExtension;
+
+/**
+ * The corner widgets path edit shows on the open path: one inside each corner
+ * anchor, at the middle of its cut, pushed a fixed distance further in on
+ * screen so that it clears the anchor square at a zero radius. The overlay
+ * paints it and the hit-test presses it, as `corner:N`, from this one
+ * placement.
+ */
+
+/** Chrome-caps id the corner widgets are drawn and hit-tested under. On by
+ *  default. */
+declare const PATH_CORNERS_CHROME_ID = "path-edit.corners";
+/** Screen distance from the middle of a corner's cut to its widget. */
+declare const CORNER_WIDGET_STANDOFF_PX = 14;
+/** The corner anchors of `path` that show a widget. */
+declare function cornerWidgetFrames(path: PolygonPath): CornerFrame[];
+/** How the widgets are drawn. */
+interface CornerWidgetStyle {
+    /** Default: path edit's anchor fill. */
+    fill?: string;
+    /** Default: path edit's anchor stroke. */
+    stroke?: string;
+}
+/**
+ * The widget of every corner anchor of `path`, in screen space: a small
+ * square whose corner toward the anchor is cut in the corner's shape. A
+ * corner with no spec draws as round, the shape a drag gives it.
+ */
+declare function cornerWidgetCommands(path: PolygonPath, view: View, style?: CornerWidgetStyle): DrawCommand[];
+/** The corner widgets as a path-edit extension: drawn, and pressed as
+ *  `corner:N`, while chrome-caps shows {@link PATH_CORNERS_CHROME_ID}. */
+declare function createCornerWidgetsExtension(style?: CornerWidgetStyle): PathEditExtension;
+
+/**
+ * The small marks the path-edit overlay draws for a path's constraints, in
+ * screen pixels, and where a click finds them: a letter beside a horizontal
+ * or vertical segment, paired strokes beside parallel ones, a foot beside
+ * perpendicular ones, ticks across equal ones, a dimension bar beside a fixed
+ * length, a pin by a fixed anchor, a ring by coincident ones, a line
+ * touching a circle by a tangent one, and a dot on a line by one held on a
+ * segment. Marks sit
+ * on the inside of the shape, toward the centroid of its anchors, so a click
+ * on one lands on the shape rather than on empty canvas.
+ */
+
+/** Colors for the constraint marks. */
+interface ConstraintGlyphStyle {
+    /** A constraint that holds. */
+    stroke: string;
+    /** One that does not: it conflicts with the others. */
+    conflictStroke: string;
+}
+
+/** Angle snapping for a control-handle drag. */
+interface HandleSnapOptions {
+    /** Snap to every multiple of this many degrees. Default 45; 0 turns the
+     *  steps off and leaves only the opposite handle. */
+    stepDeg?: number;
+    /** How near, in degrees, the handle must come to an angle to snap. Read
+     *  by the drag as it starts. Default 6. */
+    reachDeg?: number;
+    /** Also snap onto the line through the anchor's other handle. Default true. */
+    opposite?: boolean;
+}
+/** Options, or a thunk read on every move: null or undefined from it leaves
+ *  the handle unsnapped. */
+type HandleSnapOptionsInput = HandleSnapOptions | (() => HandleSnapOptions | null | undefined);
+/**
+ * A handle drag's angle targets: the multiples of `stepDeg` either side of
+ * the handle, and the angle that puts it in line with the anchor's other
+ * handle, which the drag brings as `also.anchors`, ahead of a step it ties
+ * with. Each draws its line.
+ */
+declare function handleSnapSource(options?: HandleSnapOptionsInput): SnapSource;
+/**
+ * Handle snapping as a path-edit extension: each control-handle drag runs a
+ * `'handle'` session on the canvas's `snap` dep, in polar coordinates about
+ * its anchor, and the handle keeps the length the pointer and the locks give
+ * it. A held angle lock holds the angle; a held length lock keeps the length
+ * while the angle snaps. The angles come from {@link handleSnapSource}, which
+ * `createHandleSnapPreset` registers beside it.
+ */
+declare function createHandleSnapExtension(options?: HandleSnapOptionsInput): PathEditExtension;
+
+/** How far soft selection reaches, and how it fades. */
+interface SoftSelectionOptions {
+    /** How far along the path the influence reaches, in screen pixels. */
+    radiusPx: number;
+    /** How the influence fades over the radius. Default `'smooth'`. */
+    falloff?: SoftFalloff;
+    /** Told each radius the wheel scrubs to, so a host can keep it for the next drag. */
+    onRadius?: (radiusPx: number) => void;
+}
+/** Soft selection as a path-edit extension. `options` is read as each anchor
+ *  drag starts; null or undefined leaves that drag hard. */
+declare function createSoftSelectionExtension(options: () => SoftSelectionOptions | null | undefined): PathEditExtension;
+
+/**
+ * Which way the open path runs, drawn over it: an arrow at the middle of
+ * every segment and a ring round each subpath's start anchor.
+ */
+
+/** Chrome-caps id the direction arrows and start rings are drawn under. Off by default. */
+declare const PATH_DIRECTION_CHROME_ID = "path-edit.direction";
+/** How the direction marks are drawn. */
+interface PathDirectionStyle {
+    /** Color of the arrows and the start rings. */
+    color?: string;
+    /** Length of an arrow, tip to base, in screen pixels. */
+    arrowPx?: number;
+    /** Radius of a start ring, in screen pixels. */
+    ringPx?: number;
+}
+/** Draw commands for `set`'s direction arrows and start rings, in screen space. */
+declare function directionCommands(set: AnchorSet, toScreen: (p: Point) => Point, style?: PathDirectionStyle): DrawCommand[];
+/** The direction marks as a path-edit extension, drawn in `style` while
+ *  chrome-caps shows {@link PATH_DIRECTION_CHROME_ID}. */
+declare function createDirectionExtension(style?: PathDirectionStyle): PathEditExtension;
+
+/**
+ * The package's behavior as `<SceneCanvas features>` presets: one per tool
+ * family, and `pathTools` for all of them. Each assumes core's `paths`
+ * preset, which opens a path for editing.
+ */
+
+/** The Simplify brush, a path-edit tool that refits the curve it passes over. */
+declare const simplifyBrushPreset: FeaturePreset;
+/** The `handleLock.angle` and `handleLock.length` toggles. */
+declare const handleLocksPreset: FeaturePreset;
+/**
+ * Soft selection: dragging anchors in path edit also moves the anchors near
+ * them along the path, by a falloff over `options`' radius, read as each drag
+ * starts. The wheel scrubs the radius mid-drag. Null or undefined from
+ * `options` leaves a drag hard.
+ */
+declare function createSoftSelectionPreset(options: () => SoftSelectionOptions | null | undefined): FeaturePreset;
+/**
+ * Handle snapping: a dragged control handle's angle snaps to steps and to the
+ * line through its anchor's other handle, as `options` says. A thunk is read
+ * every move, and null or undefined from it leaves the handle unsnapped.
+ */
+declare function createHandleSnapPreset(options?: HandleSnapOptionsInput): FeaturePreset;
+/** Handle snapping every 45°, within 6°, and to the opposite handle. */
+declare const handleSnapPreset: FeaturePreset;
+/** Bridge, on whole paths and on two selected anchors. */
+declare const bridgePreset: FeaturePreset;
+/** `trimPath`, which `useTrimTool` binds. */
+declare const trimPreset: FeaturePreset;
+/** `extendToMeet`, which `useExtendTool` binds. */
+declare const extendPreset: FeaturePreset;
+/** Lengthen, a path-edit tool whose drag on an open end grows or trims the
+ *  path from that end, and its toggle. */
+declare const lengthenPreset: FeaturePreset;
+/** `smudgeBrush`, which `useSmudgeBrushTool` binds. */
+declare const smudgePreset: FeaturePreset;
+/** Harmonize curvature. */
+declare const harmonizePreset: FeaturePreset;
+/** Anchor selection along the path: grow, shrink, every Nth, corners, smooth
+ *  anchors, and the complement. */
+declare const anchorSelectionPreset: FeaturePreset;
+/** Resample, which spreads anchors evenly by arc length. */
+declare const resamplePreset: FeaturePreset;
+/** Add extremes, an anchor at each curve's leftmost, rightmost, top, and bottom. */
+declare const addExtremesPreset: FeaturePreset;
+/** The curvature comb over the open path, drawn as `options` says, read every
+ *  frame. Off until chrome-caps shows `path-edit.comb`. */
+declare function createCurvatureCombPreset(options?: () => PathEditCombOptions | undefined): FeaturePreset;
+/** The curvature comb with its default look. */
+declare const curvatureCombPreset: FeaturePreset;
+/**
+ * Balance handles: a line between each curved segment's handle tips with a
+ * grip to drag (`balanceHandles`) or double-click (`equalizeHandles`), drawn
+ * in `style`. Off until chrome-caps shows `path-edit.balance`. It refines
+ * `paths`, so a grip's double-click goes ahead of entering path edit.
+ */
+declare function createBalancePreset(style?: PathEditBalanceStyle): FeaturePreset;
+/** Balance handles with their default look. */
+declare const balancePreset: FeaturePreset;
+/** Path constraints: their actions, their marks in `style`'s colors, and
+ *  every edit of a constrained path finished so they hold. */
+declare function createConstraintsPreset(style?: Partial<ConstraintGlyphStyle>): FeaturePreset;
+/** Path constraints with their default colors. */
+declare const constraintsPreset: FeaturePreset;
+/**
+ * Corner shape: a widget inside each corner anchor of the open path, drawn in
+ * `style`, whose drag sets the corner's radius (`editCorner`), and the
+ * commands on the selected corners (`setCorners`, `cycleCornerShape`). The
+ * widgets show while chrome-caps shows `path-edit.corners`, which is on by
+ * default. It refines `paths`, so a widget's drag goes ahead of the marquee.
+ */
+declare function createCornerShapePreset(style?: CornerWidgetStyle): FeaturePreset;
+/** Corner shape with path edit's anchor colors. */
+declare const cornerShapePreset: FeaturePreset;
+/**
+ * Where a path starts and which way it runs: `setPathStart` and
+ * `reversePath`, and arrows and start rings over the open path, drawn in
+ * `style`. The marks are off until chrome-caps shows `path-edit.direction`.
+ */
+declare function createPathStructurePreset(style?: PathDirectionStyle): FeaturePreset;
+/** Path start and direction with the marks' default look. */
+declare const pathStructurePreset: FeaturePreset;
+/** `convertSegments` and `convertSegmentAt`, turning segments straight or
+ *  curved. It refines `paths`, so a segment's Shift+double-click goes ahead
+ *  of entering path edit. */
+declare const segmentTypePreset: FeaturePreset;
+/** Blend, Bend along, and Repeat along, live, and the actions that edit and
+ *  expand them. The scene must hold `withPathEffectsRegistry`'s derivations. */
+declare const pathEffectsPreset: FeaturePreset;
+/** `expandWarp` and `configureWarp`; the warp tools bring their own drags. */
+declare const warpPreset: FeaturePreset;
+/** Every preset above, spiro curves, the comb, balance, constraints, path
+ *  direction, and corner shape with their defaults — except soft selection and
+ *  handle snapping, which change what every anchor or handle drag does. */
+declare const pathTools: FeaturePreset;
+
+/**
+ * Add and remove geometric constraints on the anchors selected in path edit.
+ * Neither has a default binding: a consumer binds each kind it offers, with
+ * the kind as a param (see `<SceneCanvas tune>`).
+ */
+
+/** Params for `constrainAnchors`. */
+interface ConstrainAnchorsParams {
+    kind: PathConstraintKind;
+    /** For `length`: the length to hold. Default: each pair's length now. */
+    length?: number;
+}
+/**
+ * The constraints of `kind` that `anchors`, in the order they were selected,
+ * ask for: each anchor for `fixed`; each anchor with both handles for
+ * `tangent`; for `onPath`, three anchors, the first held on the segment the
+ * other two end; each consecutive pair for `horizontal`,
+ * `vertical`, `length`, and `coincident`; and for the kinds relating two
+ * segments, three anchors as two segments sharing the middle one or four as
+ * two pairs. Empty when the anchors cannot make that kind.
+ */
+declare function constraintsForAnchors(kind: PathConstraintKind, anchors: readonly number[], path: PolygonPath, length?: number): PathConstraint[];
+/**
+ * Delete the constraint selected in path edit, as a command. Delete and
+ * Backspace reach it through `deleteAnchors`, which deletes whichever of the
+ * two is selected, so the keys have one binding.
+ */
+declare const deleteConstraintAction: Action & {
+    requires: string[];
+};
+/**
+ * Constrain the selected anchors: params `{ kind, length? }`, read as
+ * {@link constraintsForAnchors} reads them. The path moves the least that
+ * makes every constraint hold; a constraint that conflicts with the rest is
+ * kept all the same, left unsolved, and shown as a conflict.
+ */
+declare const constrainAnchorsAction: Action & {
+    requires: string[];
+};
+/**
+ * Remove the constraints whose anchors are all selected — only those of
+ * `kind` when the params name one.
+ */
+declare const unconstrainAnchorsAction: Action & {
+    requires: string[];
+};
+
+/** The path-edit tool under which a drag on an open end lengthens the path. */
+declare const LENGTHEN_TOOL = "lengthen";
+/** Params `lengthenPath` reads on every move. */
+interface LengthenPathParams {
+    /** How an unmodified drag grows the end; Shift picks the other. Default `'tangent'`. */
+    mode?: LengthenMode;
+}
+/**
+ * Lengthen, the path-edit tool's drag. While path edit's `lengthen` tool is
+ * on, dragging an open path's end anchor lengthens the path from that end
+ * (`lengthenPathEnd`): straight along its end tangent, or along an arc with
+ * the curvature the end has. Dragging back into the path shortens it along
+ * itself. The `mode` param (`'tangent'`, the default, or `'curvature'`) picks
+ * which, and Shift picks the other; both are read on every move. One undo
+ * step per drag. With the tool off, a drag on the anchor is `editAnchors`'
+ * and moves it.
+ */
+declare const lengthenPathAction: Action & {
+    requires: string[];
+};
+/** The bar toggle for Lengthen: `pathEditTool.lengthen`. */
+declare const lengthenToolAction: Action & {
+    requires: string[];
+};
+
+/** What the `resamplePath` action reads from its params. */
+type ResamplePathParams = {
+    /** Anchors in the result. 0 or absent keeps the count the path has. */
+    count?: number;
+    /** Distance between anchors along the path; overrides `count` when above 0. */
+    spacing?: number;
+    /** Hold corner anchors where they are. Default `true`. */
+    keepCorners?: boolean;
+    /** How far the result may stray from the original. Default 0.5. */
+    tolerance?: number;
+};
+/**
+ * Redistribute each selected path's anchors evenly by arc length
+ * (`resamplePath`), to `params.count` anchors or at `params.spacing`, with
+ * corners held unless `params.keepCorners` is false, and curves refitted
+ * within `params.tolerance` of the original ({@link ResamplePathParams}).
+ * Ongoing: `begin` previews it, each update with new params recomputes it,
+ * and committing writes one undo entry.
+ */
+declare const resamplePathAction: _weasel_js_routing.Action & {
+    requires: string[];
+};
+
+/** The path-edit tool under which a plain drag brushes. */
+declare const SIMPLIFY_BRUSH_TOOL = "simplifyBrush";
+/** The brush's radius on screen when no param names one. */
+declare const SIMPLIFY_BRUSH_RADIUS_PX = 12;
+/** Params the brush reads on every move, so a thunk can change them mid-stroke. */
+interface SimplifyBrushParams {
+    /** Brush radius in screen pixels. */
+    radiusPx?: number;
+    /** How far the refit may stray from the original, in world units, as for
+     *  the Simplify command. */
+    tolerance?: number;
+}
+/** The kit's brush-ring cursor drawn `radiusPx` in radius on screen. */
+declare function brushRingCursor(radiusPx: number): CursorSpec;
+/**
+ * The Simplify command, brushed on. While path edit's
+ * `simplifyBrush` tool is on, a plain drag gathers every anchor a round brush
+ * passes over, and each unbroken stretch of them along a subpath is refitted
+ * as one span by Simplify's own fitter (`simplifyAnchorsAt`) at `tolerance`.
+ * Only anchors the shape does not need go, so brushing again goes further.
+ * The path previews the result while the brush is down and commits as one
+ * undo step on release.
+ */
+declare const simplifyBrushAction: Action & {
+    requires: string[];
+};
+/** The bar toggle for the brush: `pathEditTool.simplifyBrush`. */
+declare const simplifyBrushToolAction: Action & {
+    requires: string[];
+};
+
+/**
+ * The Smudge brush's drag: the selected paths' outlines under a round brush
+ * follow the pointer, as one undo entry per stroke.
+ */
+
+/** The brush's radius in screen px when no param gives one. */
+declare const DEFAULT_SMUDGE_RADIUS_PX = 40;
+/** How much of the pointer's motion the outline under the brush's center follows,
+ *  when no param gives it. */
+declare const DEFAULT_SMUDGE_STRENGTH = 0.6;
+/** The params `smudgeBrush` reads, each on every pointer move. */
+interface SmudgeBrushParams {
+    /** The brush's radius, in screen px. */
+    radiusPx?: number;
+    /** `1` moves the outline under the brush's center as far as the pointer; less, less. */
+    strength?: number;
+}
+/**
+ * A drag that pushes the outline of every selected path along with
+ * the pointer (`smudgePath` in `@weasel-js/geom`). Each pointer move is one dab from
+ * where the last one ended: points under the brush move with it, most at its center
+ * and not at all at its rim, and a long segment the brush meets gets anchors added
+ * so it can bend there. `params.radiusPx` is the brush's radius on screen, so it
+ * covers the same part of the canvas at every zoom, and `params.strength` how closely
+ * the outline follows; both are read on every move. The cursor is a ring the size of
+ * the brush. The stroke commits as one undo entry; canceling it leaves the paths as
+ * they were.
+ */
+declare const smudgeBrushAction: Action & {
+    requires: string[];
+};
+
+/**
+ * A warp a node is holding: the path it warped, the warp, and the tolerance
+ * the result was refitted to, kept on the node as `data.warp` beside the
+ * `data.path` (or polygon pose) they produced. The geometry stays what every
+ * reader uses; the warp only says how to make it again, so it can be edited
+ * until it is expanded away.
+ *
+ * The warp lives in its own frame, fixed when it was made. `frame` carries
+ * that frame onto the stored path, so moving, resizing or rotating the node
+ * keeps the warp without touching it. A writer that changes the geometry some
+ * other way leaves a warp that no longer reproduces it, and such a warp is
+ * ignored, the way a stale shape generator is.
+ */
+
+/** What `data.warp` holds. */
+interface HeldPathWarp {
+    /** Shared by every node warped together, so one handle drives them all. */
+    id: string;
+    /** The path before warping, in the warp's frame. */
+    source: PolygonPath;
+    warp: PathWarp;
+    /** How far the refitted result may stray from the exact warp. */
+    tolerance: number;
+    /** From the warp's frame to the frame the node stores its path in. */
+    frame: Affine;
+}
+/** A held warp that still reproduces its node, and where its frame lands in
+ *  world space now. */
+interface ResolvedPathWarp {
+    held: HeldPathWarp;
+    /** From the warp's frame to world space. */
+    toWorld: Affine;
+}
+/** The warp a node's `data` holds, whether or not it still matches. */
+declare function heldPathWarpOf(data: unknown): HeldPathWarp | null;
+/** `data` without its warp: the shape as plain geometry. */
+declare function withoutPathWarp<T>(data: T): T;
+/**
+ * The warp `node` holds and its frame in world space, or null when it holds
+ * none or the one it holds no longer reproduces its geometry. A node whose
+ * stored path was rewritten by an affine map since — a polygon pose moved,
+ * resized or rotated, which rewrites its coordinates — still resolves: the
+ * map is recovered from the two sets of points and replaces `frame`.
+ */
+declare function resolvePathWarp(node: EditableShape | null | undefined): ResolvedPathWarp | null;
+
+/**
+ * What every warp action shares: finding the selected paths' warps of one
+ * kind, making fresh ones where a path holds none, and writing a changed warp
+ * back as the geometry it makes plus the warp itself.
+ */
+
+/** Which warp a tool or action works with. */
+type WarpKind = PathWarp['kind'];
+/** The settings a warp is made or remade with. Each applies only to the kinds
+ *  it names; absent ones leave a held warp as it is. */
+interface WarpSettings {
+    /** A distort's map. Default `'free'`. */
+    mode?: DistortMode;
+    /** An envelope's interpolation. Default `'bicubic'`. */
+    mapping?: EnvelopeMapping;
+    /** An envelope's patch rows and columns. Default 3 each. */
+    rows?: number;
+    cols?: number;
+    /** How far, in world units, the refitted result may stray from the exact
+     *  warp. Default {@link DEFAULT_WARP_TOLERANCE}. */
+    tolerance?: number;
+}
+/** The refit tolerance of a warp made without one. */
+declare const DEFAULT_WARP_TOLERANCE = 0.5;
+/** The patch rows and columns of an envelope made without them. */
+declare const DEFAULT_ENVELOPE_SIZE = 3;
+/**
+ * `shape` (a node's pose and data) warped by `warp`, whose controls are in
+ * world space, and holding it — for a scene that opens on a warp already
+ * made. Null when `shape` holds no editable polygon.
+ */
+declare function withPathWarp<S extends {
+    pose: unknown;
+    data: unknown;
+}>(shape: S, warp: PathWarp, opts?: {
+    id?: string;
+    tolerance?: number;
+}): {
+    pose: unknown;
+    data: unknown;
+} | null;
+
+/**
+ * The params this package's actions read, merged into routing's
+ * `ActionParamSchema` so `<SceneCanvas tune>` types them.
+ */
+
+/** A path effect's settings as params; a blend's `reverse` also takes
+ *  `'auto'`, handing the direction back to `autoAlign`. */
+type SettingsOf<E> = {
+    [K in Exclude<keyof E, 'kind'>]?: E[K];
+};
+type BlendParams = Omit<SettingsOf<BlendEffect>, 'reverse'> & {
+    reverse?: boolean | 'auto';
+};
+/** Either field left out keeps that part of each selected corner. */
+type SetCornersParams = {
+    shape: CornerShape;
+    radius: number;
+};
+type EditPathEffectParams = BlendParams & SettingsOf<BendAlongEffect> & SettingsOf<RepeatAlongEffect> & {
+    ids?: readonly string[];
+};
+declare module '@weasel-js/routing' {
+    interface ActionParamSchema {
+        blend: BlendParams;
+        bendAlong: SettingsOf<BendAlongEffect>;
+        repeatAlong: SettingsOf<RepeatAlongEffect>;
+        editPathEffect: EditPathEffectParams;
+        simplifyBrush: SimplifyBrushParams;
+        smudgeBrush: SmudgeBrushParams;
+        lengthenPath: LengthenPathParams;
+        bridgePaths: {
+            tension?: number;
+        };
+        bridgeAnchors: {
+            tension?: number;
+        };
+        setSpiroKind: {
+            kind?: SpiroKind;
+        };
+        'spiro.placePoint': {
+            kind?: SpiroKind;
+        };
+        constrainAnchors: ConstrainAnchorsParams;
+        unconstrainAnchors: {
+            kind?: PathConstraintKind;
+        };
+        'distort.drag': WarpSettings;
+        'envelope.drag': WarpSettings;
+        'puppet.drag': WarpSettings;
+        'puppet.addPin': WarpSettings;
+        configureWarp: WarpSettings & {
+            kind?: WarpKind;
+        };
+        convertSegments: {
+            to?: SegmentType;
+        };
+        convertSegmentAt: {
+            to?: SegmentType;
+        };
+        selectEveryNthAnchor: {
+            n?: number;
+        };
+        resamplePath: ResamplePathParams;
+        setCorners: SetCornersParams;
+    }
+}
+
+/**
+ * Toggles for the locks every path-edit handle drag holds without a
+ * modifier: its angle, its length, or both, which freezes it. They set the
+ * `editAnchors` dep's `handleLocks`, so a bar, the command palette, and
+ * `<SceneCanvas tune>`'s `handleLock` param, which they start from, all
+ * reach the one value the drag reads.
+ */
+
+/** Hold every handle drag to the handle's angle, as Shift does. */
+declare const handleLockAngleAction: Action & {
+    requires: string[];
+};
+/** Hold every handle drag to the handle's length, as Mod (Cmd or Ctrl) does. */
+declare const handleLockLengthAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Bridge: join open path ends with a curve that leaves each end along the
+ * direction its path was heading, on whole paths or on the two anchors
+ * selected in path edit.
+ */
+
+/** How long Bridge makes each handle, as a fraction of the gap, when its
+ *  params name no `tension`. */
+declare const DEFAULT_BRIDGE_TENSION = 0.4;
+/** A bridge's `params.tension`, or the default. Negative reads as `0`. */
+declare function bridgeTensionOf(params: Record<string, unknown> | undefined): number;
+/**
+ * Bridge open paths: as `joinPaths`, but the gap is spanned by
+ * a curve leaving each end along the direction its path was heading, each
+ * handle `params.tension` times the gap long (default
+ * {@link DEFAULT_BRIDGE_TENSION}). Two paths become one. In path edit,
+ * `bridgeAnchors` bridges the two selected anchors instead.
+ */
+declare const bridgePathsAction: Action & {
+    requires: string[];
+};
+/**
+ * Bridge the two selected anchors, each the end of an open
+ * subpath, as `joinAnchors` does, but with a curve leaving each end along the
+ * direction its path was heading, each handle `params.tension` times the gap
+ * long (`bridgePaths`'s default when absent). The anchor selection is
+ * cleared.
+ */
+declare const bridgeAnchorsAction: Action & {
+    requires: string[];
+};
+
+/** Trim segment: cut a stroke back to the crossings on either side of a click. */
+
+/** What a trim at the press in `params` would do: the stroke it reaches, and
+ *  what `trimPathAt` makes of it. Null when it reaches none it can trim.
+ *  `params` as {@link trimPathAction} reads them; a hover's pointer serves
+ *  as the press, which is how a tool previews the piece. */
+declare function planTrim(deps: ActionDeps, params: unknown): {
+    target: PathNode;
+    result: TrimResult;
+} | null;
+/**
+ * Trim segment: remove the piece of the stroke under the press
+ * between the nearest crossings on either side — with any other node's
+ * outline, or with itself — as `trimPathAt` cuts it. The topmost stroke
+ * within `radiusPx` of the press (default 6) is the one trimmed; a stroke
+ * with nothing left is deleted. Params: `pressX`, `pressY` in world space,
+ * which a click binding supplies.
+ */
+declare const trimPathAction: Action & {
+    requires: string[];
+};
+
+/** Extend to next path: carry an open end along its tangent until it meets a stroke. */
+
+/**
+ * Extend to next path: carry each open end of the selected
+ * paths along its tangent to the first stroke it meets (`extendToMeet`). In
+ * path edit, the selected end anchors of the edited path, or all its open
+ * ends when none is selected. Given a press (`pressX`, `pressY`, as a click
+ * binding supplies), the open end nearest it of the topmost stroke within
+ * `radiusPx` instead. An end that meets nothing stays put. One undo step.
+ */
+declare const extendToMeetAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Make the selected smooth anchors curvature-continuous by adjusting their
+ * handle lengths, or every smooth anchor of the path while none is selected.
+ */
+declare const harmonizeAnchorsAction: _weasel_js_routing.Action & {
+    requires: string[];
+};
+
+/**
+ * Where a path starts and which way it runs: make the selected anchor its
+ * subpath's start, and reverse a path's direction. Both reorder anchors
+ * without moving them, and what a node keeps per anchor moves with them.
+ */
+
+/**
+ * Make the selected anchor where its subpath starts. A closed
+ * subpath turns to start there; an open one can start only at an end, so its
+ * last anchor reverses it (`setSubpathStart`). The anchor stays selected.
+ */
+declare const setPathStartAction: Action & {
+    requires: string[];
+};
+/**
+ * Run paths the other way, keeping their shape. In path edit it
+ * reverses the subpaths holding the selected anchors — every subpath when
+ * none is selected — and the selection follows its anchors. Otherwise it
+ * reverses every selected path whole, in one undo entry. A closed subpath
+ * keeps its start; an open one starts where it ended (`reverseSubpaths`).
+ */
+declare const reversePathAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Make segments of the path being edited straight or curved, in place
+ * (`convertSegments`): the selected segments from the keyboard, or the one
+ * under a Shift+double-click.
+ */
+
+/**
+ * Convert the selected segments — those whose two ends are both
+ * selected anchors. `params.to` `'line'` straightens them, `'curve'` curves
+ * them with handles at their thirds so they keep their shape, and no `to`
+ * (Shift+C) curves them all when any is straight and straightens them
+ * otherwise.
+ */
+declare const convertSegmentsAction: Action & {
+    requires: string[];
+};
+/**
+ * Shift+double-click a segment of the path being edited to flip
+ * it between straight and curved. Off every segment the click falls through.
+ */
+declare const convertSegmentAtAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Anchor selection along the path in path edit: grow or shrink it by one
+ * anchor, every Nth anchor, corners or smooth anchors, and the complement.
+ * They change which anchors are selected and nothing else, so none of them
+ * is an undo step.
+ */
+
+/** The group every action here is in, which an `ActionBar` can show. */
+declare const ANCHOR_SELECTION_GROUP = "anchorSelection";
+/** Add each selected anchor's neighbors along the path. `]`. */
+declare const growAnchorSelectionAction: Action & {
+    requires: string[];
+};
+/** Drop the anchors at the ends of each selected run. `[`. */
+declare const shrinkAnchorSelectionAction: Action & {
+    requires: string[];
+};
+/**
+ * Select every `params.n`th anchor (default 2) along each subpath, counting
+ * from its first selected anchor, or from the start of every subpath when
+ * none is selected. Alt+N.
+ */
+declare const selectEveryNthAnchorAction: Action & {
+    requires: string[];
+};
+/** Select every corner anchor of the edited path. Alt+C. */
+declare const selectCornerAnchorsAction: Action & {
+    requires: string[];
+};
+/** Select every smooth anchor of the edited path. Alt+M. */
+declare const selectSmoothAnchorsAction: Action & {
+    requires: string[];
+};
+/** Select the anchors that are not selected, and only those. Alt+I. */
+declare const invertAnchorSelectionAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Add extremes in path edit: an anchor at each turn of a curved segment, in x
+ * and in y, with the shape left as it was.
+ */
+
+/**
+ * Split the curved segments of the edited path at their x and y extremes:
+ * those whose two ends are both selected, or every one while no anchor is.
+ * The selected anchors stay selected, and the new ones join them. Alt+X.
+ * Enabled only where it would add an anchor.
+ */
+declare const addExtremeAnchorsAction: Action & {
+    requires: string[];
+};
+
+/**
+ * The balance grip on each curved segment of the path being edited, midway
+ * along the line joining its two handle tips:
+ *
+ *   - `balanceHandles` — drag the grip to scale both handles together, each
+ *     along its own direction, so the segment fills out toward its corner or
+ *     flattens toward its chord without turning at either end.
+ *   - `equalizeHandles` — double-click the grip to give both handles the same
+ *     proportion of the way to that corner.
+ *
+ * The grips are the `balance:N` affordances path edit lays out, shown and
+ * hit-tested only while chrome-caps shows `path-edit.balance`. N is the flat
+ * index of the anchor the segment starts at.
+ *
+ * Under a `pathSymmetry` dep a grip drag moves every image of both handles,
+ * as `editAnchors` moves a dragged handle's. Both keep each handle's angle, so an angle lock holds through them. A length
+ * lock in force for handle drags (the `editAnchors` dep's `handleLocks`, or Mod)
+ * holds the drag still, as it would a handle drag with the angle held too.
+ */
+
+/** Drag a segment's balance grip to scale both its handles together. */
+declare const balanceHandlesAction: Action & {
+    requires: string[];
+};
+/** Double-click a segment's balance grip to even out its handles' proportions. */
+declare const equalizeHandlesAction: Action & {
+    requires: string[];
+};
+
+/**
+ * The path-effect actions: make a live blend, bend, or repeat from the
+ * selection; change one's settings; and expand one into ordinary paths.
+ */
+
+/** The `group` every path-effect action is in, for an `<ActionBar>`. */
+declare const PATH_EFFECTS_GROUP = "pathEffects";
+/**
+ * Steps between the first two selected shapes, in the order they were
+ * selected: `params.steps` of them, each shape, fill, stroke and turn
+ * interpolated, laid along a third selected path where there is one. The
+ * blend is live — editing a source moves its steps — and goes just under the
+ * upper of the first two. Its other params are `BlendEffect`'s.
+ */
+declare const blendAction: Action & {
+    requires: string[];
+};
+/**
+ * The first selected shape bent along the second, live: editing the spine
+ * re-bends it. Params are `BendAlongEffect`'s.
+ */
+declare const bendAlongAction: Action & {
+    requires: string[];
+};
+/**
+ * Copies of the first selected shape along the second, live. Params are
+ * `RepeatAlongEffect`'s.
+ */
+declare const repeatAlongAction: Action & {
+    requires: string[];
+};
+/**
+ * Change the settings of path effects: `params.ids` when given, else the
+ * selected ones. Every other param is a setting, laid over each effect's
+ * own, and one that would change nothing commits nothing. Consecutive edits
+ * of one effect coalesce, so a slider dragged through many values is one
+ * undo step where the scene coalesces.
+ */
+declare const editPathEffectAction: Action & {
+    requires: string[];
+};
+/**
+ * Turn each selected path effect into the ordinary paths it shows, in its
+ * slot and in its paint, and select them. Its sources stay; the paths no
+ * longer follow them.
+ */
+declare const expandPathEffectAction: Action & {
+    requires: string[];
+};
+
+/**
+ * The warp actions. A warp tool binds the per-kind ones (`<kind>.drag`,
+ * `puppet.addPin`, `puppet.removePin`) and owns them; `expandWarp` and
+ * `configureWarp` work on whatever warp the selection holds and ship with
+ * the `paths` preset.
+ */
+
+/** What a press on a warp control hands the drag that follows. */
+interface WarpHandleScratch {
+    /** The warp the control belongs to, or null for one shown over a selection
+     *  holding none yet, which the drag makes. */
+    warpId: string | null;
+    /** The control's index, as `warpControls` counts them. */
+    index: number;
+}
+/** The scratch a control press carried, or null when the press was elsewhere. */
+declare function warpHandleScratchOf(hit: unknown): WarpHandleScratch | null;
+/**
+ * Drop the warp from each selected path, keeping the geometry it made: the
+ * shape becomes plain geometry that path editing and other warps start from.
+ */
+declare const expandWarpAction: Action;
+/**
+ * Remake the selection's warps under new settings (`params`, a
+ * {@link WarpSettings}, plus an optional `kind` limiting it to one kind of
+ * warp): switch a distort between free and perspective, an envelope between
+ * its mappings or to a finer grid, or refit at another tolerance. One undo step.
+ */
+declare const configureWarpAction: Action;
+
+/**
+ * Corner shape in path edit: drag a corner's widget to set its radius.
+ *
+ * A drag measures how far the pointer moves along the corner's bisector and
+ * turns that into a cut along the edges, clamped to the room the neighboring
+ * corners leave. Pressing the widget of a selected anchor gives every
+ * selected corner the same radius. The release commits one undo step.
+ */
+
+/** The shape a corner with no spec yet takes. */
+declare const DEFAULT_CORNER_SHAPE: CornerShape;
+/** Drag a corner widget to set the corner's radius. */
+declare const editCornerAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Commands on the corners of the anchors selected in path edit: set their
+ * shape or radius, or step their shape through the `corner-shape` keywords.
+ */
+
+/** The share of a corner's room that a shape given to a sharp corner cuts. */
+declare const DEFAULT_CORNER_TRIM_SHARE = 0.25;
+/**
+ * Set the selected corners' shape, radius, or both, from the `shape` (a
+ * keyword or a finite `superellipse()` parameter) and `radius` params; each
+ * is left alone when its param is absent, except that a shape given to a
+ * sharp corner also gives it a radius. A UI control's action: it has no
+ * default binding.
+ */
+declare const setCornersAction: Action & {
+    requires: string[];
+};
+/**
+ * Step the selected corners to the next `corner-shape` keyword, keeping
+ * their radius. Every one takes the keyword after the first selected
+ * corner's shape, so a mixed selection comes out alike, and a sharp corner
+ * gets a radius that shows it.
+ */
+declare const cycleCornerShapeAction: Action & {
+    requires: string[];
+};
+
+/** Options for a tool that acts on the stroke under a click. */
+interface StrokeClickToolOptions {
+    /** Override the default keybinding. Pass `null` to omit. */
+    keybinding?: ToolKeybinding | null;
+    /** How far from a stroke a click may land and still reach it, in screen
+     *  pixels. Read on every click. Default 6. */
+    radiusPx?: number | (() => number);
+}
+
+/** Options for `useTrimTool`; the default keybinding is `{ key: 'Y' }`. */
+type UseTrimToolOptions = StrokeClickToolOptions;
+/**
+ * Trim segment tool. A click on a stroke removes its piece between the
+ * crossings on either side — a declarative shell over the `trimPath` action,
+ * which owns the hit-test and the commit. While it is up, the piece under the
+ * pointer is drawn dashed, through the same `planTrim` the click commits.
+ */
+declare function useTrimTool(options?: UseTrimToolOptions): Tool;
+
+/** Options for `useExtendTool`; the default keybinding is `{ key: 'U' }`. */
+type UseExtendToolOptions = StrokeClickToolOptions;
+/**
+ * Extend to next path tool. A click near an open end of a stroke carries
+ * that end along its tangent to the next stroke it meets — a declarative
+ * shell over the `extendToMeet` action.
+ */
+declare function useExtendTool(options?: UseExtendToolOptions): Tool;
+
+/** Options for `useSmudgeBrushTool`. */
+interface UseSmudgeBrushToolOptions {
+    /** Override the default keybinding (`{ key: 'S' }`). Pass `null` to omit. */
+    keybinding?: ToolKeybinding | null;
+}
+/**
+ * Smudge brush tool. A round brush that pushes the outline of the selected
+ * paths along with the pointer — a declarative shell whose one binding routes a
+ * drag to the `smudgeBrush` action, which owns the stroke, its preview, its ring
+ * cursor, and its one undo entry. The brush's radius (screen px) and strength are
+ * that action's params: `tune={{ smudgeBrush: { params: () => ({ radiusPx, strength }) } }}`.
+ */
+declare function useSmudgeBrushTool(options?: UseSmudgeBrushToolOptions): Tool;
+
+/** A warp tool: a `Tool` that also registers the layer showing its controls. */
+type WarpTool = Tool & Pick<SurfaceContribution, 'attach'>;
+/** Options every warp tool takes. */
+interface WarpToolOptions {
+    /** Palette label. */
+    label?: string;
+    /** Override the default keybinding (Distort `F`, Envelope `M`, Puppet Warp
+     *  `B`). Pass `null` to omit. */
+    keybinding?: ToolKeybinding | null;
+    /** How far, in world units, a warped path's refitted curves may stray from
+     *  the exact warp. Default 0.5. */
+    tolerance?: number;
+}
+/** Options for {@link useDistortTool}. */
+interface UseDistortToolOptions extends WarpToolOptions {
+    /** The map a new distort starts with: `'free'` (bilinear, the default) or
+     *  `'perspective'` (projective). */
+    mode?: DistortMode;
+}
+/** Options for {@link useEnvelopeTool}. */
+interface UseEnvelopeToolOptions extends WarpToolOptions {
+    /** Patch rows and columns of a new envelope's mesh. Default 3 each. */
+    rows?: number;
+    cols?: number;
+    /** How a new envelope interpolates its mesh. Default `'bicubic'`. */
+    mapping?: EnvelopeMapping;
+}
+/** Options for {@link usePuppetTool}. */
+type UsePuppetToolOptions = WarpToolOptions;
+/**
+ * Distort the selected paths by their box's four corners, each dragged on its
+ * own. The first drag gives the selection a distort, kept on each path as
+ * `data.warp` until it is expanded (`expandWarp`); selecting the paths again
+ * with this tool shows its corners where they were left. `configureWarp`
+ * switches a held distort between free and perspective.
+ */
+declare function useDistortTool(options?: UseDistortToolOptions): WarpTool;
+/**
+ * Warp the selected paths through a mesh of control points over their box:
+ * drag any point and the shape bends smoothly around it. The mesh is held on
+ * each path until it is expanded, and `configureWarp` changes its grid or its
+ * interpolation.
+ */
+declare function useEnvelopeTool(options?: UseEnvelopeToolOptions): WarpTool;
+/**
+ * Pin the selected paths where they are clicked, and drag a pin to bend them:
+ * the rest of the shape follows as rigidly as the pins allow, and a pin left
+ * alone holds its place. Alt-click a pin to take it out. The pins are held on
+ * each path until it is expanded.
+ */
+declare function usePuppetTool(options?: UsePuppetToolOptions): WarpTool;
+
+/** The id of the layer showing a `kind` warp's controls. A binding reaches
+ *  its controls through `affordance:layer:<id>`. */
+declare const warpLayerId: (kind: WarpKind) => string;
+
+/**
+ * Shape building: the selected paths cut into the faces their outlines bound,
+ * then a pick of those faces united into one path, or deleted, as one undo step.
+ */
+
+/** What a pick of faces does: unite them into one path, or delete them. */
+type ShapeBuilderMode = 'merge' | 'delete';
+/** One face of the selection: a connected region no outline crosses. */
+interface ShapeBuilderFace {
+    path: PolygonPath;
+    /** The topmost source covering the face, which a path made of it stands in for. */
+    sourceId: NodeId;
+    /** Set when that source's stroke went into the face: the paint it wears. */
+    paint?: PathPaint;
+}
+/** The faces of the selection, and the commit that rebuilds it from a pick of them. */
+interface ShapeBuilderPlan {
+    kind: 'faces';
+    /** Back to front by the sources they cover, exclusives first. */
+    faces: readonly ShapeBuilderFace[];
+    /** The index of the face holding the world point, or -1. */
+    faceAt(x: number, y: number): number;
+    /**
+     * Replace the selection with its faces, the `picked` ones united into one
+     * path standing in for the source of the first one picked (`'merge'`) or
+     * left out (`'delete'`). Every other face becomes a path of its own. One
+     * undo step, and what it made is selected. Commits nothing for an empty pick.
+     */
+    commit(picked: readonly number[], mode: ShapeBuilderMode): BooleanOpResult;
+}
+/**
+ * The faces the selected paths cut each other into, or why there are none.
+ * Reads the adapter and changes nothing; the plan's `commit` writes.
+ */
+declare function planShapeBuilder(adapter: BooleansAdapter, opts?: BooleanOpOptions): ShapeBuilderPlan | Exclude<BooleanOpResult, {
+    kind: 'applied';
+}>;
+/**
+ * The faces a run of world points passes through, each once, in the order
+ * the run enters them. `step` is the world distance between the samples
+ * taken along each segment; a face narrower than it can be stepped over.
+ */
+declare function facesAlong(plan: Pick<ShapeBuilderPlan, 'faceAt'>, run: readonly {
+    x: number;
+    y: number;
+}[], step: number): number[];
+
+/** Options for `useShapeBuilderTool`. */
+interface UseShapeBuilderToolOptions {
+    /** Override the default keybinding (`{ key: 'M', shift: true }`). Pass `null` to omit. */
+    keybinding?: ToolKeybinding | null;
+    /** What a stroked path gives the faces. Default `'unfilled'`, as the
+     *  Pathfinder actions: an unfilled stroke counts as the region it covers. */
+    strokes?: BooleanStrokes;
+    /** What a drag or a click does without Alt: unite the faces (`'merge'`, the
+     *  default) or delete them. With Alt it does the other. Read on every gesture. */
+    mode?: ShapeBuilderMode;
+}
+/**
+ * Shape builder. With two or more paths selected, the faces their outlines cut
+ * each other into are what the tool works on: the face under the pointer is
+ * shown, a drag unites every face it passes through into one path wearing the
+ * paint of the first, and an Alt-drag deletes them (the other way round under
+ * `mode: 'delete'`). A click takes the one face. Every face not taken becomes a path of its own, and each gesture is
+ * one undo step. With fewer than two selected, a drag marquee-selects.
+ *
+ * It reads the `booleansAdapter` dep the Pathfinder actions do.
+ */
+declare function useShapeBuilderTool(options?: UseShapeBuilderToolOptions): Tool;
+
+/** Options for `useGirthTool`. */
+interface UseGirthToolOptions {
+    /** Override the default keybinding (`{ key: 'W', shift: true }`). Pass `null` to omit. */
+    keybinding?: ToolKeybinding | null;
+    /** Screen px around a stroke's edge within which a press takes hold of it,
+     *  and along the path within which it takes the anchor there rather than
+     *  inserting one. Default 6. */
+    reach?: number;
+}
+/**
+ * Girth tool: shapes a stroke's width along its length, into its
+ * `vertexWidths`, by dragging the stroke's edges. Hovering near either edge
+ * marks the grab point on it and the width point a press there moves: the
+ * anchor at that spot, or a new one inserted between two, keeping the path's
+ * shape. Dragging moves the grabbed edge along the path's normal, the other
+ * edge mirroring it so the width stays centered; inward pinches it, down to
+ * zero. With Alt held only the grabbed edge moves, writing a `{ left, right }`
+ * pair. Either drag is live and one undo entry. Alt-click on a width point
+ * clears it, so it takes the stroke's own width. The last stroke touched shows
+ * its anchors, with a line across the stroke at each that has a width.
+ */
+declare function useGirthTool(options?: UseGirthToolOptions): Tool;
+
+/** What the Girth tool's overlay shows, in world space: the anchors of the
+ *  stroke last hovered or pressed on, each with its unit normal toward its
+ *  right edge and its `vertexWidths` entry (`NaN` for none), and, over an
+ *  edge, the grab point on it and the width point a press there moves. */
+interface GirthFocus {
+    anchors: readonly Point[];
+    normals: readonly Point[];
+    widths: readonly VertexWidth[];
+    /** The stroke's own width, which an unset entry takes. */
+    fallback: number;
+    grab?: {
+        edge: Point;
+        at: Point;
+    };
+}
+/** The Girth tool's own state, shared by its actions and its overlay. */
+interface GirthEnv {
+    focus(): GirthFocus | null;
+    setFocus(next: GirthFocus | null): void;
+    /** Screen px around a stroke's edge within which a press takes hold of it,
+     *  and along the path within which it takes the anchor there. */
+    reachPx(): number;
+}
+/** Id of the action that drags a stroke's edge. */
+declare const GIRTH_DRAG_ID = "girth.drag";
+/** Id of the action that clears the width point under a click. */
+declare const GIRTH_CLEAR_ID = "girth.clear";
+/** Id of the action that marks the edge under a hover. */
+declare const GIRTH_HOVER_ID = "girth.hover";
+/** Id of the action that drops the hover mark when the pointer leaves. */
+declare const GIRTH_UNHOVER_ID = "girth.unhover";
+/**
+ * The Girth tool's actions, which write a stroke's `vertexWidths`.
+ * `girth.drag` takes hold of the stroke edge under the press, at the anchor
+ * there or at one it inserts, shape kept, between two. The edge follows the
+ * pointer along the path's normal, the other edge mirroring it so the width
+ * stays centered; with Alt held only the grabbed edge moves, which writes a
+ * `{ left, right }` pair. Either is live, and one undo entry. `girth.clear`
+ * clears the width point under a click, so it takes the stroke's own width
+ * again. `girth.hover` and `girth.unhover` show and hide the grab point under
+ * the pointer.
+ */
+declare function createGirthActions(env: GirthEnv): Action[];
+
+/**
+ * A screen-space layer marking the width points of the stroke the Girth tool
+ * last touched: a dot on each anchor, white where it has a width of its own,
+ * with a line across the stroke from its left edge to its right. Over an
+ * edge it adds the grab point on that edge, ringing the width point a press
+ * there moves.
+ */
+declare function createGirthOverlay(source: {
+    focus(): GirthFocus | null;
+    subscribe(fn: () => void): () => void;
+}): RenderLayer<unknown>;
+
+/**
+ * What the Girth tool reads and writes: the stroke edge under a point, the
+ * width point a press on it moves — inserting an anchor where the press falls
+ * between two — and the per-vertex widths a drag leaves behind.
+ */
+
+/** A stroked path node and its centerline in world space. */
+interface WidthTarget {
+    id: NodeId;
+    node: SceneNode<unknown, string, unknown>;
+    path: PolygonPath;
+    stroke: Stroke;
+    /** The stroke's own width in world units: what an unset entry takes. */
+    fallback: number;
+}
+/** A stroke edge found under a point, and the width point a press there
+ *  moves: anchor `index`, or one inserted at `at` when `index` is null. */
+interface WidthEdgeHit {
+    target: WidthTarget;
+    edge: StrokeEdgeHit;
+    index: number | null;
+    at: Point;
+}
+/**
+ * The width point a drag edits, on a node's geometry as the press leaves it:
+ * `path` gained an anchor at `index` when the press fell between two.
+ */
+interface WidthGrip {
+    target: WidthTarget;
+    /** The world path, with the inserted anchor if there is one. */
+    path: PolygonPath;
+    /** One entry per anchor of `path`; `NaN` takes the stroke's own width. */
+    widths: VertexWidth[];
+    index: number;
+    at: Point;
+    inserted: boolean;
+    /** The edge taken hold of, and the unit normal it moves along. */
+    side: StrokeSide;
+    normal: Point;
+    /** Each edge's distance from the path at the width point, before the drag. */
+    start: HalfWidths;
+    /** What the nib multiplies a stored width by there, so a drag moves the
+     *  edge as drawn. */
+    factor: number;
+}
+
+/** Spiro curves: path edit edits a spiro node's points and solves the curve
+ *  again through them (`spiroRepresentation`), `setSpiroKind` sets the kind
+ *  of the selected points, and `releaseSpiro` converts a spiro curve to an
+ *  ordinary path. `useSpiroTool` draws them. */
+declare const spiroPreset: FeaturePreset;
+
+/** Options for {@link useSpiroTool}. */
+interface UseSpiroToolOptions {
+    /** Select the new curve once it commits. Default `true`. */
+    autoSelect?: boolean;
+    /** Screen-px radius of "click the first point to close". Default `8`. */
+    closeHitRadius?: number;
+}
+/**
+ * Active-slot Tool that draws a spiro curve (`solveSpiro`) by placing its
+ * on-curve points: each click places one, of the kind `params.kind` of the
+ * `spiro.placePoint` action (default `'smooth'`; Alt-click places a corner),
+ * and the preview solves the curve through the points and the cursor as it
+ * moves. Clicking the first point of three or more closes the curve; Enter,
+ * a double-click or Mod-click finishes it open; Backspace takes back the last
+ * point and Escape discards them all, as does switching tools.
+ *
+ * The curve is inserted through the `insert` dep as a `'path'`, its spiro
+ * form beside it on `data.representation`, so a consumer shapes the node by
+ * overriding that dep. With `spiroPreset` on, path edit then edits its points
+ * (`spiroRepresentation`).
+ */
+declare function useSpiroTool(options?: UseSpiroToolOptions): Tool;
+
+/**
+ * Commands on spiro curves (`spiroShape`): set the kind of the points
+ * selected in path edit, and convert a spiro curve to an ordinary path.
+ */
+
+/**
+ * @experimental In path edit on a spiro curve, give the selected points the
+ * kind `params.kind` (default `'smooth'`) and solve the curve again. One
+ * variant per kind.
+ */
+declare const setSpiroKindAction: Action & {
+    requires: string[];
+};
+/**
+ * @experimental Convert the selected spiro curves, or the one in path edit, to
+ * ordinary paths: the curve stays as drawn and its anchors and handles become
+ * editable, while the spiro points stop being solved. Path edit's anchor
+ * selection is cleared, since the anchors it numbered are gone.
+ */
+declare const releaseSpiroAction: Action & {
+    requires: string[];
+};
+
+/**
+ * Spiro curves in path edit: a spiro node is edited through its straight-sided
+ * control path, whose anchors are the curve's points, and every edit solves
+ * the curve again through them. Each point draws by its kind, and a press on
+ * the curve between two points adds one there.
+ */
+
+/** How path edit reads and writes a spiro form. */
+declare const spiroRepresentation: PathRepresentation;
+/** The path-edit extension carrying {@link spiroRepresentation}. */
+declare const spiroExtension: PathEditExtension;
+
+/**
+ * How a spiro point is marked, by its kind: a circle for a smooth point, a
+ * diamond for a g4 point, a square for a corner, and a half-disc for a point
+ * beside a straight segment, its flat side toward the line.
+ */
+
+/**
+ * The marker shape of a spiro point of `kind`. A `left` point's line arrives
+ * from its previous neighbor and a `right` point's leaves toward its next,
+ * both in the same screen space; without that neighbor the half-disc faces
+ * right.
+ */
+declare function spiroMarker(kind: SpiroKind): AnchorMarkerShape;
+
+/** What the spiro tool has placed, as the preview reads it each frame. */
+interface SpiroPreviewState {
+    points: readonly SpiroPoint[];
+    /** Where the next point would go, or null while the pointer is away. */
+    cursor: SpiroPoint | null;
+    /** True while a click would close the curve on its first point. */
+    closeHint: boolean;
+}
+/** Options for {@link createSpiroPreviewLayer}. */
+interface CreateSpiroPreviewLayerOptions {
+    state: () => SpiroPreviewState;
+    /** The color the curve and markers are drawn in. */
+    color?: string;
+}
+/** Render layer drawing the spiro tool's curve in progress; nothing while
+ *  no point is placed. */
+declare function createSpiroPreviewLayer(opts: CreateSpiroPreviewLayerOptions): RenderLayer<unknown>;
+
+/**
+ * A spiro node: a path node whose `data.representation` is a spiro form,
+ * saying its `data.path` is a solved spiro curve and which of the path's
+ * anchors are the curve's points (`spiroToPath`). The path stays the geometry
+ * every reader uses; path edit edits the points instead, through the
+ * straight-sided control path, and each edit solves the curve again
+ * (`spiroRepresentation`). Converting to a path drops the form.
+ */
+
+/** The `kind` of a spiro form. */
+declare const SPIRO_FORM = "spiro";
+/** A spiro form, as `data.representation` holds it: each point's kind, and
+ *  the anchor of `data.path` it became. */
+type SpiroShape = {
+    kind: typeof SPIRO_FORM;
+    kinds: SpiroKind[];
+    at: number[];
+};
+/** `form` as a spiro form, or null when it is not a well-formed one. */
+declare function asSpiro(form: unknown): SpiroShape | null;
+/** The spiro form a node's `data` holds, or `null`. */
+declare function spiroOf(data: unknown): SpiroShape | null;
+/** `data` without its spiro form: the curve as plain geometry. */
+declare function withoutSpiro<T>(data: T): T;
+/** The node data a solved spiro curve is stored as: its path, and the form
+ *  that says which anchors are points. */
+declare function spiroNodeData(contours: readonly SpiroContour[], like?: PolygonPath): {
+    path: PolygonPath;
+    representation: SpiroShape;
+};
+/** The contours `spiro` reads out of `path`, or null when it does not
+ *  describe it. */
+declare function spiroContours(path: PolygonPath, spiro: SpiroShape): SpiroContour[] | null;
+/** The straight-sided path through `spiro`'s points on `path`: what path
+ *  edit shows and moves. Null when `spiro` does not describe `path`. */
+declare function spiroEditPath(path: PolygonPath, spiro: SpiroShape): PolygonPath | null;
+/**
+ * The curve an edit of the control path makes, solved through its anchors:
+ * `control` is the edited control path, `path` the curve it was edited from.
+ * Each point keeps its kind (`spiroContoursFromControl`). Null when `spiro`
+ * does not describe `path`.
+ */
+declare function respiro(path: PolygonPath, spiro: SpiroShape, control: PolygonPath): {
+    path: PolygonPath;
+    spiro: SpiroShape;
+} | null;
+/** The curve `path` makes with the points at `flatIndexes` set to `kind`. Null
+ *  when `spiro` does not describe `path`, or no kind changes. */
+declare function respiroWithKind(path: PolygonPath, spiro: SpiroShape, flatIndexes: Iterable<number>, kind: SpiroKind): {
+    path: PolygonPath;
+    spiro: SpiroShape;
+} | null;
+
+/**
+ * Path constraints in path edit: their marks on the open path, a click
+ * selecting one, Delete removing it, and every edit finished so they hold.
+ */
+
+/** Owner id of the constraint marks, as `EditAnchorsDep.selectedMark` names them. */
+declare const CONSTRAINTS_EXTENSION_ID = "constraints";
+/**
+ * Replace the open path's constraints with `constraints` as one history
+ * entry, moving it the least that makes them all hold. When they cannot all
+ * hold the path stays as it is and the list is stored all the same, the
+ * conflict left for the marks to show. Clears the selected mark, since the
+ * list is renumbered. Answers the indices in conflict, as
+ * `constraintConflictsOf` names them — empty when every one holds — or null
+ * when the dep cannot store.
+ */
+declare function setConstraints(dep: EditAnchorsDep, constraints: readonly PathConstraint[], label: string): number[] | null;
+/** The constraint selected in path edit, as an index into the open path's list, or null. */
+declare function selectedConstraintOf(dep: EditAnchorsDep): number | null;
+/** The constraints extension, its marks drawn in `style`'s colors. */
+declare function createConstraintsExtension(style?: Partial<ConstraintGlyphStyle>): PathEditExtension;
+
+/**
+ * Constraints between nodes. A link is a node of its own: its `dependsOn`
+ * names the nodes it ties, in order, and its `data.constraintLink` holds one
+ * `PathConstraint` whose anchors are numbered over theirs one after another —
+ * with two nodes of 4 and 5 anchors, anchor 6 is the second node's anchor 2.
+ * Being a node, it is saved and undone with the scene, and deleting a node it
+ * ties deletes it too. It draws nothing and takes no clicks; keep it on a
+ * layer that is not exported, such as an annotation layer.
+ *
+ * An edit of any node a link ties solves every node the links reach in one
+ * solve: an anchor held on another node's segment slides along it when
+ * dragged and follows it when that node is edited.
+ */
+
+/** What a link node keeps in `data`. */
+interface ConstraintLinkData {
+    constraintLink: PathConstraint;
+}
+/** The constraint `data` holds as a link, or null when it is not one. */
+declare function constraintLinkOf(data: unknown): PathConstraint | null;
+/** Options for {@link constraintLinkNode}. */
+interface ConstraintLinkNodeOptions<TPose> {
+    layer: string;
+    /** The nodes it ties, in the order its anchors number them. */
+    nodes: readonly string[];
+    constraint: PathConstraint;
+    id?: string;
+    /** Default: an empty box at the origin. */
+    pose?: TPose;
+}
+/** A link node, ready for `scene.add`. Registers the painter that keeps link nodes from drawing. */
+declare function constraintLinkNode<TPose = RectPose>(opts: ConstraintLinkNodeOptions<TPose>): AddNodeSpec<ConstraintLinkData, string, TPose>;
+
+/**
+ * The controls for the selected corners of a path in edit: a schema any
+ * prefs form draws, the values and mixed fields it shows for a selection,
+ * and the `setCorners` params a change to one of them makes.
+ */
+
+/** How far the parameter slider reaches either side of the bevel; the
+ *  `square` and `notch` keywords stand for the two infinities beyond it. */
+declare const CORNER_K_SLIDER_RANGE = 4;
+/** What the corner controls ask for while no corner is selected. */
+declare const CORNER_CONTROLS_PROMPT = "Click a corner anchor (Shift-click for more) to edit it";
+/** The corner controls as a prefs schema: the keywords, the parameter, and
+ *  the radius, each disabled while no corner is selected. */
+declare const CORNER_CONTROLS: PrefGroup;
+/** What the controls show for a selection. */
+interface CornerControlsState {
+    /** `shape` is null where no keyword applies, so a form does not fall back
+     *  to the leaf's default. */
+    values: {
+        count: number;
+        shape: CornerKeyword | null;
+        k?: number;
+        radius?: number;
+    };
+    /** The fields whose selected corners disagree. */
+    mixed: ReadonlySet<string>;
+}
+/** The controls for the corners of `path` among `selected` anchors. A sharp
+ *  corner shows no shape and no parameter. */
+declare function cornerControlsState(path: PolygonPath | null, selected: ReadonlySet<number>): CornerControlsState;
+/** The `setCorners` params a change of `field` to `value` makes, or null for
+ *  a field that sets nothing. */
+declare function cornerControlsParams(field: string, value: unknown): {
+    shape: CornerShape;
+} | {
+    radius: number;
+} | null;
+
+/** The part of a scene the controls read. */
+interface CornerControlsScene {
+    get(id: NodeId): EditableShape | undefined;
+    subscribe(listener: () => void): () => void;
+}
+/** Which path is open for anchor editing and which of its anchors are
+ *  selected: what a `PathEditHost` that owns the anchor selection knows. */
+interface CornerControlsSelection {
+    editingId(): string | null;
+    selectedAnchors(): ReadonlySet<number>;
+    subscribe(listener: () => void): () => void;
+}
+/** What {@link useCornerControls} gives a corner panel to draw. */
+interface UseCornerControlsReturn {
+    /** The schema a prefs form draws: `CORNER_CONTROLS`. Its `name` is the
+     *  controls' title. */
+    schema: typeof CORNER_CONTROLS;
+    /** What to show above the form, or null once a corner is selected. */
+    prompt: string | null;
+    values: Record<string, unknown>;
+    mixed: ReadonlySet<string>;
+    /** A prefs form's `onChange` for `CORNER_CONTROLS`. */
+    onChange: (field: string, value: unknown) => void;
+}
+/**
+ * A corner panel over the selected corners of the path open for anchor
+ * editing: their shared shape and radius, kept current as the scene or the
+ * selection changes, and an `onChange` that writes through `setCorners`.
+ */
+declare function useCornerControls(scene: CornerControlsScene, selection: CornerControlsSelection): UseCornerControlsReturn;
+
+/**
+ * A node's path constraints: kept as `data.constraints`, numbered by the
+ * anchors of its editable polygon, and solved in the frame that polygon is
+ * drawn in, so `horizontal` on a rotated `data.path` node turns with it.
+ */
+
+/** The constraints a node's data holds, or none. */
+declare function constraintsOf(data: unknown): readonly PathConstraint[];
+/** Radians the frame `horizontal` and `vertical` read is turned from the world's: a `data.path` node's rotation. */
+declare function constraintAxisOf(node: EditableShape | null | undefined): number;
+/**
+ * Indices of `node`'s constraints that do not hold in its committed path, and
+ * the others each conflict needs: every member of a smallest set that cannot
+ * all hold. Edits leave the ones that do not hold out of the solve, and so
+ * does a whole-shape transform — resize, rotate, flip — which carries the
+ * list unchanged: a constraint the transform breaks, such as a set length
+ * under a scale or an equal length under a non-uniform one, is reported here
+ * rather than solved back.
+ */
+declare function constraintConflictsOf(node: EditableShape | null | undefined): number[];
+
+/** A glyph this package draws, by its bare name. */
+type PathToolsIconName = 'smudgeBrush' | 'distort' | 'envelope' | 'puppetWarp' | 'blend' | 'bendAlong' | 'repeatAlong' | 'expand' | 'balanceHandles' | 'equalizeHandles' | 'lengthen' | 'trim' | 'extend' | 'girth' | 'spiro' | 'reversePath' | 'setPathStart' | 'cornerRadius' | 'cornerShape' | 'convertSegment' | 'straightenSegment' | 'curveSegment' | 'extremeAnchors';
+declare module '@weasel-js/icons' {
+    interface IconName {
+        'path-tools:smudgeBrush': true;
+        'path-tools:distort': true;
+        'path-tools:envelope': true;
+        'path-tools:puppetWarp': true;
+        'path-tools:blend': true;
+        'path-tools:bendAlong': true;
+        'path-tools:repeatAlong': true;
+        'path-tools:expand': true;
+        'path-tools:balanceHandles': true;
+        'path-tools:equalizeHandles': true;
+        'path-tools:lengthen': true;
+        'path-tools:trim': true;
+        'path-tools:extend': true;
+        'path-tools:girth': true;
+        'path-tools:spiro': true;
+        'path-tools:reversePath': true;
+        'path-tools:setPathStart': true;
+        'path-tools:cornerRadius': true;
+        'path-tools:cornerShape': true;
+        'path-tools:convertSegment': true;
+        'path-tools:straightenSegment': true;
+        'path-tools:curveSegment': true;
+        'path-tools:extremeAnchors': true;
+    }
+}
+
+export { ANCHOR_SELECTION_GROUP, CONSTRAINTS_EXTENSION_ID, CORNER_CONTROLS, CORNER_CONTROLS_PROMPT, CORNER_K_SLIDER_RANGE, CORNER_WIDGET_STANDOFF_PX, type ConstrainAnchorsParams, type ConstraintGlyphStyle, type ConstraintLinkData, type ConstraintLinkNodeOptions, type CornerControlsScene, type CornerControlsSelection, type CornerControlsState, type CornerWidgetStyle, type CreateSpiroPreviewLayerOptions, DEFAULT_BRIDGE_TENSION, DEFAULT_CORNER_SHAPE, DEFAULT_CORNER_TRIM_SHARE, DEFAULT_ENVELOPE_SIZE, DEFAULT_SMUDGE_RADIUS_PX, DEFAULT_SMUDGE_STRENGTH, DEFAULT_WARP_TOLERANCE, GIRTH_CLEAR_ID, GIRTH_DRAG_ID, GIRTH_HOVER_ID, GIRTH_UNHOVER_ID, type GirthEnv, type GirthFocus, type HandleSnapOptions, type HandleSnapOptionsInput, type HeldPathWarp, LENGTHEN_TOOL, type LengthenPathParams, PATH_BALANCE_CHROME_ID, PATH_COMB_CHROME_ID, PATH_CORNERS_CHROME_ID, PATH_DIRECTION_CHROME_ID, PATH_EFFECTS_GROUP, type PathDirectionStyle, type PathEditBalanceStyle, type PathEditCombOptions, type PathToolsIconName, type ResamplePathParams, type ResolvedPathWarp, SIMPLIFY_BRUSH_RADIUS_PX, SIMPLIFY_BRUSH_TOOL, SPIRO_FORM, type ShapeBuilderFace, type ShapeBuilderMode, type ShapeBuilderPlan, type SimplifyBrushParams, type SmudgeBrushParams, type SoftSelectionOptions, type SpiroPreviewState, type SpiroShape, type StrokeClickToolOptions, type UseCornerControlsReturn, type UseDistortToolOptions, type UseEnvelopeToolOptions, type UseExtendToolOptions, type UseGirthToolOptions, type UsePuppetToolOptions, type UseShapeBuilderToolOptions, type UseSmudgeBrushToolOptions, type UseSpiroToolOptions, type UseTrimToolOptions, type WarpHandleScratch, type WarpKind, type WarpSettings, type WarpTool, type WarpToolOptions, type WidthEdgeHit, type WidthGrip, type WidthTarget, addExtremeAnchorsAction, addExtremesPreset, anchorSelectionPreset, asSpiro, balanceCommands, balanceHandlesAction, balancePreset, bendAlongAction, blendAction, bridgeAnchorsAction, bridgePathsAction, bridgePreset, bridgeTensionOf, brushRingCursor, combCommands, configureWarpAction, constrainAnchorsAction, constraintAxisOf, constraintConflictsOf, constraintLinkNode, constraintLinkOf, constraintsForAnchors, constraintsOf, constraintsPreset, convertSegmentAtAction, convertSegmentsAction, cornerControlsParams, cornerControlsState, cornerShapePreset, cornerWidgetCommands, cornerWidgetFrames, createBalanceExtension, createBalancePreset, createCombExtension, createConstraintsExtension, createConstraintsPreset, createCornerShapePreset, createCornerWidgetsExtension, createCurvatureCombPreset, createDirectionExtension, createGirthActions, createGirthOverlay, createHandleSnapExtension, createHandleSnapPreset, createPathStructurePreset, createSoftSelectionExtension, createSoftSelectionPreset, createSpiroPreviewLayer, curvatureCombPreset, cycleCornerShapeAction, deleteConstraintAction, directionCommands, editCornerAction, editPathEffectAction, equalizeHandlesAction, expandPathEffectAction, expandWarpAction, extendPreset, extendToMeetAction, facesAlong, growAnchorSelectionAction, handleLockAngleAction, handleLockLengthAction, handleLocksPreset, handleSnapPreset, handleSnapSource, harmonizeAnchorsAction, harmonizePreset, heldPathWarpOf, invertAnchorSelectionAction, lengthenPathAction, lengthenPreset, lengthenToolAction, pathEffectsPreset, pathStructurePreset, pathTools, planShapeBuilder, planTrim, releaseSpiroAction, repeatAlongAction, resamplePathAction, resamplePreset, resolvePathWarp, respiro, respiroWithKind, reversePathAction, segmentTypePreset, selectCornerAnchorsAction, selectEveryNthAnchorAction, selectSmoothAnchorsAction, selectedConstraintOf, setConstraints, setCornersAction, setPathStartAction, setSpiroKindAction, shrinkAnchorSelectionAction, simplifyBrushAction, simplifyBrushPreset, simplifyBrushToolAction, smudgeBrushAction, smudgePreset, spiroContours, spiroEditPath, spiroExtension, spiroMarker, spiroNodeData, spiroOf, spiroPreset, spiroRepresentation, trimPathAction, trimPreset, unconstrainAnchorsAction, useCornerControls, useDistortTool, useEnvelopeTool, useExtendTool, useGirthTool, usePuppetTool, useShapeBuilderTool, useSmudgeBrushTool, useSpiroTool, useTrimTool, warpHandleScratchOf, warpLayerId, warpPreset, withPathWarp, withoutPathWarp, withoutSpiro };