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

package/dist/index.d.ts

@@ -0,0 +1,713 @@
+import { PathEditExtension, FeaturePreset, EditableShape, BlendEffect, BendAlongEffect, RepeatAlongEffect, PathNode, Tool, SurfaceContribution, EditAnchorsDep } from '@weasel-js/core';
+import { DrawCommand } from '@weasel-js/renderer';
+import { AnchorSet, PathConstraintKind, PolygonPath, PathConstraint, PathWarp, Affine, DistortMode, EnvelopeMapping, TrimResult } 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';
+
+/**
+ * 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;
+}
+type ToScreen$1 = (p: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};
+/** Draw commands for `set`'s balance lines and their grips, in screen space. */
+declare function balanceCommands(set: AnchorSet, toScreen: ToScreen$1, 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;
+}
+type ToScreen = (p: {
+    x: number;
+    y: number;
+}) => {
+    x: number;
+    y: number;
+};
+/** Draw commands for `set`'s curvature comb, in screen space. */
+declare function combCommands(set: AnchorSet, toScreen: ToScreen, 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 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, and a ring by coincident ones. 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;
+}
+
+/**
+ * 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;
+/** 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;
+/** `smudgeBrush`, which `useSmudgeBrushTool` binds. */
+declare const smudgePreset: FeaturePreset;
+/** Harmonize curvature. */
+declare const harmonizePreset: 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;
+/** 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, the comb, balance, and constraints with their defaults. */
+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 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 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;
+}
+/**
+ * @experimental 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 only scaled and moved since — a polygon pose dragged, say —
+ * still resolves: the box-to-box map between the two is folded into `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';
+};
+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;
+        bridgePaths: {
+            tension?: number;
+        };
+        bridgeAnchors: {
+            tension?: number;
+        };
+        constrainAnchors: ConstrainAnchorsParams;
+        unconstrainAnchors: {
+            kind?: PathConstraintKind;
+        };
+        'distort.drag': WarpSettings;
+        'envelope.drag': WarpSettings;
+        'puppet.drag': WarpSettings;
+        'puppet.addPin': WarpSettings;
+        configureWarp: WarpSettings & {
+            kind?: WarpKind;
+        };
+    }
+}
+
+/**
+ * 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;
+/**
+ * @experimental 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[];
+};
+/**
+ * @experimental 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;
+/**
+ * @experimental 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. */
+
+/**
+ * @experimental 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[];
+};
+
+/**
+ * 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. The blend is live — editing either source moves its steps —
+ * and goes just under the upper source. 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;
+
+/** 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;
+
+/**
+ * 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. False when the dep cannot store.
+ */
+declare function setConstraints(dep: EditAnchorsDep, constraints: readonly PathConstraint[], label: string): boolean;
+/** 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;
+
+/**
+ * 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:
+ * the ones that conflict with the rest. Edits leave them 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[];
+
+export { CONSTRAINTS_EXTENSION_ID, type ConstrainAnchorsParams, type ConstraintGlyphStyle, DEFAULT_BRIDGE_TENSION, DEFAULT_ENVELOPE_SIZE, DEFAULT_SMUDGE_RADIUS_PX, DEFAULT_SMUDGE_STRENGTH, DEFAULT_WARP_TOLERANCE, type HeldPathWarp, PATH_BALANCE_CHROME_ID, PATH_COMB_CHROME_ID, PATH_EFFECTS_GROUP, type PathEditBalanceStyle, type PathEditCombOptions, type ResolvedPathWarp, SIMPLIFY_BRUSH_RADIUS_PX, SIMPLIFY_BRUSH_TOOL, type SimplifyBrushParams, type SmudgeBrushParams, type StrokeClickToolOptions, type UseDistortToolOptions, type UseEnvelopeToolOptions, type UseExtendToolOptions, type UsePuppetToolOptions, type UseSmudgeBrushToolOptions, type UseTrimToolOptions, type WarpHandleScratch, type WarpKind, type WarpSettings, type WarpTool, balanceCommands, balanceHandlesAction, balancePreset, bendAlongAction, blendAction, bridgeAnchorsAction, bridgePathsAction, bridgePreset, bridgeTensionOf, brushRingCursor, combCommands, configureWarpAction, constrainAnchorsAction, constraintAxisOf, constraintConflictsOf, constraintsForAnchors, constraintsOf, constraintsPreset, createBalanceExtension, createBalancePreset, createCombExtension, createConstraintsExtension, createConstraintsPreset, createCurvatureCombPreset, curvatureCombPreset, deleteConstraintAction, editPathEffectAction, equalizeHandlesAction, expandPathEffectAction, expandWarpAction, extendPreset, extendToMeetAction, handleLockAngleAction, handleLockLengthAction, handleLocksPreset, harmonizeAnchorsAction, harmonizePreset, heldPathWarpOf, pathEffectsPreset, pathTools, planTrim, repeatAlongAction, resolvePathWarp, selectedConstraintOf, setConstraints, simplifyBrushAction, simplifyBrushPreset, simplifyBrushToolAction, smudgeBrushAction, smudgePreset, trimPathAction, trimPreset, unconstrainAnchorsAction, useDistortTool, useEnvelopeTool, useExtendTool, usePuppetTool, useSmudgeBrushTool, useTrimTool, warpHandleScratchOf, warpLayerId, warpPreset, withPathWarp, withoutPathWarp };