@weasel-js/core 1.4.4 → 1.5.1

package/dist/registry-BY-wI9gm.d.ts

@@ -1,4003 +0,0 @@
-import { N as NodeId, R as RectPose, S as Scene } from './types-bcc7jcUy.js';
-import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-ei3UMl9R.js';
-import { V as View } from './view-DSQgxBJB.js';
-import { CapabilityTag } from '@weasel-js/modes';
-import * as React from 'react';
-import { MutableRefObject, ReactNode, ReactElement } from 'react';
-import { GestureSpec, IngestItem, InputEvent } from '@weasel-js/gestures';
-import { D as DrawCommand, E as Effect } from './DrawCommand-CD-ug3d9.js';
-import { B as Bounds, P as PoseProjection, F as FitViewToBoundsOptions, V as ViewportDims } from './geometry-6fCNhAux.js';
-import { FillStyle, Stroke } from '@weasel-js/paint';
-import { CursorSpec } from '@weasel-js/cursor';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { P as Path } from './path-JEV2c5If.js';
-import { Op, History } from '@weasel-js/history';
-import { a as SceneAdapter, L as LayoutStrategy, I as InsertAdapter } from './types-DEALFt5F.js';
-import { D as DebugSink } from './types-BHK2dkMu.js';
-import { Mat3 } from '@weasel-js/geom';
-
-interface ChromeState {
-    /** Currently selected ids. Live; reflects useSelection's React state. */
-    readonly selection: readonly NodeId[];
-    /** True when the canvas is in multi-mode AND >= 2 ids are selected. */
-    readonly multiActive: boolean;
-    /** Bounds for any selection member id. Honors active-tool overlay state
-     *  (move/resize/rotate ghosts → ghost bounds; otherwise → committed
-     *  pose bounds). Returns null for unknown ids or ids whose bounds aren't
-     *  computable. */
-    boundsOf(id: string): Bounds | null;
-    /** Multi-union AABB when `multiActive`. Computed lazily from `boundsOf`
-     *  over every selected id, expanding rotated members to the extent of
-     *  their ink; null otherwise. */
-    readonly unionBounds: Bounds | null;
-    /** Active modifier state at the moment of the call. */
-    readonly modifiers: ModifierState;
-    /** True iff the node's pose-descriptor declares it can carry a rotation.
-     *  Affordances consult this to decide whether to expose rotate cursors /
-     *  drag-bands. Defaults to `true` when the descriptor doesn't declare
-     *  (back-compat) or when the id is unknown — the rotation gesture will
-     *  no-op visually for poses without AABB fields, but the affordance
-     *  doesn't lie about the cursor. Optional on the interface so unit-test
-     *  call sites that construct `ChromeState` by hand keep compiling;
-     *  affordances should treat an absent predicate as "true". */
-    canRotate?(id: string): boolean;
-}
-
-/**
- * @experimental
- * A single interactive piece of chrome. Pure functions; the kit composes
- * multiple affordances into a single RenderLayer per tool via
- * `composeAffordanceLayer`.
- *
- * Affordances declare interactive regions in a target's *local* frame.
- * The framework (`composeAffordanceLayer`) composes the target's bounds
- * transform (rotation around the AABB center, when present) for both paint
- * and hit-test, so the affordance never touches rotation, view.scale, or
- * world↔screen math.
- */
-interface Affordance {
-    /** Stable id for debug overlays + visibility maps. */
-    id: string;
-    /** Enumerate this affordance's interactive regions. Each region lives in
-     *  some target id's local frame (or in the world frame when `targetId`
-     *  is `null`). Returning `[]` means "no chrome for this state" (no
-     *  selection, multi-mode disabled, etc.). */
-    regions(state: ChromeState): readonly AffordanceRegion[];
-    /** Optional non-interactive decoration (e.g., a leader line drawn from
-     *  a bounds edge to a handle — visual only, not draggable). Receives
-     *  raw state + view because the decoration may live outside any single
-     *  target's local frame. Most affordances leave this undefined. */
-    decorate?(state: ChromeState, view: View): DrawCommand[];
-}
-/**
- * @experimental
- * One interactive region produced by an affordance. The framework owns
- * the local↔world transform for `targetId` (when non-null), so `shape`,
- * `paint.sizePx`, and `hitRadiusPx` are always specified in coordinates
- * the affordance can reason about directly.
- */
-interface AffordanceRegion<TScratch = unknown> {
-    /** Stable id, e.g. `corner-min-min`. Used for debug overlays + a11y. */
-    id: string;
-    /** Target id whose `state.boundsOf(targetId)` defines this region's
-     *  local frame. `bounds.rotation` (if present) is the only transform
-     *  applied — translation is the AABB origin; scale is identity. Pass
-     *  `null` for affordances anchored to the viewport / world frame
-     *  (identity transform). */
-    targetId: string | null;
-    /** Region geometry, expressed in the target's local frame.
-     *
-     *  - `point` — circular hit (`hitRadiusPx` is screen-space).
-     *  - `rect`  — axis-aligned rect (target rotation applies).
-     *  - `annulus` — outer ellipse minus inner rect cutout. Used for
-     *    invisible zones that sit *around* the AABB (e.g. rotate-on-
-     *    hover band). The outer ellipse is defined by world-space
-     *    semi-axes `rx` / `ry` around `(cx, cy)`; the inner rect is the
-     *    same target-local rect that defines the AABB. Hit-test:
-     *    inside outer ellipse AND outside inner rect. */
-    shape: {
-        kind: 'point';
-        x: number;
-        y: number;
-        hitRadiusPx: number;
-    } | {
-        kind: 'rect';
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    } | {
-        kind: 'annulus';
-        /** Outer-ellipse center (target-local). */
-        cx: number;
-        cy: number;
-        /** Outer-ellipse semi-axes (target-local). */
-        rx: number;
-        ry: number;
-        /** Inner rect (target-local) — the cutout. Typically the
-         *  selection's AABB. */
-        innerX: number;
-        innerY: number;
-        innerWidth: number;
-        innerHeight: number;
-        /** Minimum band thickness outside the inner rect, in **screen**
-         *  pixels. The framework widens `rx`/`ry` to at least
-         *  `innerHalfExtent + minBandPx / meanScale(view.scale)` for both
-         *  paint and hit-test.
-         *
-         *  This exists because the clamp has to know the view and the
-         *  affordance doesn't: `ChromeState` carries no scale. Expressing the
-         *  floor in world units instead (which is what the rotate ring used
-         *  to do) makes the band shrink on screen as you zoom in, until the
-         *  ring around a small shape is too thin to hover. */
-        minBandPx?: number;
-    };
-    /** Optional paint. World position is derived from `shape` + target
-     *  transform; visual size stays in screen pixels (so handles don't
-     *  warp under zoom or non-uniform scale). Omit for hit-only regions.
-     *
-     *  - `square` — small fixed-size square (only valid over `point` shapes).
-     *  - `annulus` — fill + stroke the annulus ring (only valid over
-     *    `annulus` shapes). Uses even-odd fill rule to punch the inner-rect
-     *    cutout.
-     *  - `custom` — emit arbitrary draw commands; receives a {@link CustomPaintContext}. */
-    paint?: {
-        kind: 'square';
-        sizePx: number;
-        fill?: FillStyle;
-        stroke?: Stroke;
-    } | {
-        kind: 'annulus';
-        fill?: FillStyle;
-        stroke?: Stroke;
-        insetPx?: number;
-    } | {
-        kind: 'custom';
-        draw: (ctx: CustomPaintContext) => DrawCommand[];
-    };
-    /** Discriminator a press on this region reports as `AffordanceHit.kind` —
-     *  the string routing specs match on (`'handle:top-left'`,
-     *  `'rotate-handle'`, `'anchor:3'`). Omit for regions that only exist
-     *  inside a consumer-registered layer, where the layer id is the
-     *  discriminator; `buildAffordanceAt` falls back to
-     *  `<affordanceId>:<regionId>`. */
-    hitKind?: string;
-    /** Cursor to show while hovering this region. Read by the hover-cursor
-     *  pump in `useGestureDispatcher` via `AffordanceHit.cursor`, which
-     *  `buildAffordanceAt` fills in from the region the walk landed on. */
-    cursor?: CursorSpec;
-    /** `'exclusive'` bars every binding whose target doesn't consult the
-     *  affordance. Read only when the affordance is composed into a
-     *  consumer-registered layer; kit chrome routes through
-     *  `buildAffordanceAt`, which reports `'shared'`. */
-    strength?: 'exclusive' | 'shared';
-    /** Which gestures an exclusive claim bars. Omitted bars all of them. */
-    claimedKinds?: readonly ClaimableGesture[];
-    /** Drag binding produced when this region is hit. Lazily called so
-     *  affordances don't pay binding-construction cost on every paint frame —
-     *  state snapshots (e.g., capturing per-leaf poses at click time) belong
-     *  inside `bind()`, not inside `regions()`. */
-    bind(): AffordanceBinding<TScratch>;
-}
-/** Context passed to a region's `paint.kind === 'custom'` draw callback.
- *  Provides both the world-space anchor (already transformed) and the
- *  original local shape, for affordances that want to do additional
- *  geometry themselves. */
-interface CustomPaintContext {
-    /** World-space mapping of `shape`. For `point`, only `x`/`y` are set.
-     *  For `rect`, all four fields are set. */
-    world: {
-        x: number;
-        y: number;
-        width?: number;
-        height?: number;
-    };
-    /** The original local shape (same object identity as `region.shape`). */
-    local: AffordanceRegion['shape'];
-    view: View;
-    state: ChromeState;
-}
-/**
- * @experimental
- * Result of an affordance hit — what the region computed about itself.
- *
- * `initialScratch` is the payload: what the region already knows (which
- * corner, which target id) so the action that picks up the drag doesn't
- * re-derive it. `<SceneCanvas>` reads it out of the layer hit-test and packs
- * it into `AffordanceHit`, which flows to the matching action through
- * `InvocationCtx.drag.affordance`.
- *
- * This used to also carry a `drag: DragChannel` naming the handlers the
- * tool-routing dispatcher should wire up. Every implementation supplied a
- * no-op stub that claimed, because the real routing had already moved to
- * bindings; the field went with that dispatcher.
- */
-interface AffordanceBinding<TScratch = unknown> {
-    initialScratch?: TScratch;
-}
-/**
- * The fields `buildAffordanceAt` lifts out of a region's `initialScratch`
- * when it turns a region hit into an `AffordanceHit`.
- *
- * Scratch is otherwise opaque — whatever the affordance wants to hand the
- * action that picks up the drag. These few names are the exception: they mean
- * the same thing to every affordance, and the actions that consume them
- * (`resizeAction`, `rotateAction`) read them off `AffordanceHit` rather than
- * out of scratch. An affordance that doesn't set them simply produces a hit
- * without those fields.
- */
-interface CommonAffordanceScratch {
-    /** The node (or `MULTI_RESIZE_TARGET_ID`) this chrome acts on. Becomes
-     *  `AffordanceHit.targetIds`. */
-    targetId?: string;
-    /** For resize chrome: which corner stays pinned. Mirrors the kit's
-     *  `ResizeAnchor`, spelled inline so `affordances/` doesn't take a type
-     *  dependency on the gesture layer for one field. */
-    anchor?: {
-        x: 'min' | 'max' | 'free';
-        y: 'min' | 'max' | 'free';
-    };
-    /** World-space invariant point of the transform — the fixed corner for a
-     *  resize, the pivot for a rotation. */
-    fixedPoint?: {
-        x: number;
-        y: number;
-    };
-}
-/**
- * What a **registered layer's** `hitTest` returns. Extends `AffordanceBinding`
- * so existing implementations keep typechecking; the added fields are how a
- * consumer's own chrome says the things kit chrome says through
- * `AffordanceRegion` — which cursor to show, and whether it owns the point
- * outright.
- */
-interface LayerHit<TScratch = unknown> extends AffordanceBinding<TScratch> {
-    /** Cursor while the pointer is over this hit. Reaches the hover-cursor
-     *  pump as `AffordanceHit.cursor`, the same path kit chrome uses. */
-    cursor?: CursorSpec;
-    /** `'exclusive'` bars every binding whose target doesn't consult the
-     *  affordance. Omitted means `'shared'` — today's behavior. Same name and
-     *  meaning as `AffordanceHit.strength`, which it becomes. */
-    strength?: 'exclusive' | 'shared';
-    /** Which gestures an exclusive claim bars. Omitted bars all of them. */
-    claimedKinds?: readonly ClaimableGesture[];
-}
-/**
- * Gesture kinds an affordance claim can bar, in the spec vocabulary bindings
- * are written in. `'pointer'` is one token because `pointerDown` / `click` /
- * `drag` are a single press protocol — at the event level the first two are
- * the same `kind: 'pointerdown'`, told apart only by `stage`.
- */
-type ClaimableGesture = 'pointer' | 'doubleClick' | 'contextMenu' | 'longPress' | 'wheel';
-
-/**
- * Canvas size in CSS pixels — passed to `draw` for layers that anchor to
- * canvas edges (e.g. the debug overlay's layer-list panel). The GL backend
- * supplies it explicitly so layers don't have to know about DPR.
- */
-interface Dims {
-    width: number;
-    height: number;
-}
-/**
- * What a layer's `draw` threw, and which layer threw it.
- *
- * A `draw` runs on the frame loop, so a throw that escapes it surfaces as an
- * uncaught `requestAnimationFrame` error on the window and takes the whole
- * frame with it — every other layer included. One broken layer painting
- * nothing, named in the console, is the lesser wrong.
- */
-interface LayerDrawFailure {
-    layerId: string;
-    error: unknown;
-}
-/**
- * Several consecutive layers composited as one.
- *
- * A layer's own `effects` run over that layer alone, which is the wrong
- * picture whenever a pass reads neighboring pixels: `blur(A over B)` is not
- * `blur(A) over blur(B)`, and it costs a buffer and a pass chain per layer. A
- * group draws its members into one buffer, runs one chain over it, and
- * composites the result back once.
- *
- * Membership is by `RenderLayer.id` — the same names `layerOrder` and
- * `layerVisibility` use, not the `layers` map's slot keys.
- *
- * Only *consecutive* members share a buffer, because anything drawn between
- * two members has to land between them. A group whose members are separated in
- * the render order is drawn as one bracket per run, with a warning: the
- * picture is right, the declaration almost certainly is not.
- *
- * This is a render-stack bracket, not a scene `ContainerNode` — it holds no
- * ids, survives no reload, and nothing in the scene knows about it.
- */
-interface LayerGroup {
-    /** Names the group in warnings; not a layer id and never drawn. */
-    id: string;
-    /** Member layer ids. Order here is ignored — the render order decides. */
-    layers: readonly string[];
-    /**
-     * Passes over the group's combined pixels, in order. A thunk is re-read on
-     * every frame, so an animating radius costs no React render; an array is
-     * read once per frame either way.
-     */
-    effects?: readonly Effect[] | ((view: View, dims: Dims) => readonly Effect[]);
-    /** Opacity applied to the group's composited result, not to each member. */
-    alpha?: number;
-    /** 4×5 color matrix (row-major, 20 numbers) applied to the composited
-     *  result. See `GroupDrawCommand.colorMatrix`. */
-    colorMatrix?: number[];
-}
-/** One layer's memoized output, keyed by layer id. Owned by the canvas that
- *  calls `drawLayers`, not by `drawLayers` itself — the function is pure. */
-type LayerCommandCache = Map<string, {
-    deps: readonly unknown[];
-    cmds: DrawCommand[];
-}>;
-/**
- * A single named render sub-layer within a canvas renderer.
- *
- * @template TData - The data object passed to each draw call.
- */
-interface RenderLayer<TData> {
-    /** Unique identifier used in visibility maps and ordering arrays. When a
-     *  cache is in use, an id must identify the same logical layer across
-     *  frames — reusing it for a different layer can serve cross-layer commands. */
-    id: string;
-    /** Human-readable name for UI toggles. */
-    label: string;
-    /**
-     * Emit a DrawCommand tree for the GL backend to dispatch.
-     *
-     * For world-space layers (the default), emit commands in WORLD COORDS —
-     * `drawLayers` automatically wraps them in `{ kind: 'group', transform:
-     * viewToMat3(view), ... }` before handing them to the renderer. Do NOT
-     * apply the view transform yourself.
-     *
-     * For screen-space layers (`space: 'screen'`), emit commands in CSS-pixel
-     * coords directly; `drawLayers` passes them through unchanged. If part
-     * of a screen-space layer's output needs to track the view, wrap that
-     * subset manually with `viewToMat3(view)`.
-     */
-    draw: (data: TData, view: View, dims: Dims) => DrawCommand[];
-    /**
-     * Optional cache key. When present and a `LayerCommandCache` is supplied to
-     * `drawLayers`, the layer's previous `DrawCommand[]` is reused as long as
-     * every entry is `Object.is`-equal to the previous call's. A layer with no
-     * `deps` rebuilds on every frame.
-     *
-     * **The returned commands must be treated as immutable.** A cached tree is
-     * handed to the renderer again on later frames, so mutating a tree you
-     * previously returned corrupts the cache silently rather than erroring.
-     *
-     * **Screen-space layers are not protected against a stale `view`/`dims`
-     * the way world-space layers are** (see `space` below) — include them in
-     * `deps` if `draw` reads them.
-     */
-    deps?: (data: TData, view: View, dims: Dims) => readonly unknown[];
-    /**
-     * Whether the layer is shown when no explicit visibility entry exists.
-     * Defaults to `true` when absent.
-     */
-    defaultVisible?: boolean;
-    /**
-     * When true, the layer is always drawn regardless of the visibility map.
-     * Useful for layers that must never be hidden (e.g. base grid).
-     */
-    alwaysOn?: boolean;
-    /**
-     * Coordinate space the layer draws in.
-     *
-     * - `'world'` (default): the layer's `draw` returns world-space commands;
-     *   `drawLayers` wraps them in a `kind: 'group'` with `viewToMat3(view)`
-     *   automatically.
-     * - `'screen'`: the layer's `draw` returns screen-space (CSS-pixel)
-     *   commands; `drawLayers` passes them through unchanged. World-anchored
-     *   chrome inside a screen-space layer must call `worldToScreen` or wrap
-     *   the relevant subset with `viewToMat3(view)` manually.
-     */
-    space?: 'world' | 'screen';
-    /**
-     * Full-screen passes run over this layer's own pixels before it joins the
-     * frame — a blur here blurs the world and leaves the HUD drawn above it
-     * sharp, which is the thing a CSS `filter` on the `<canvas>` cannot do.
-     *
-     * Costs nothing while empty: the renderer allocates no offscreen buffer
-     * until a layer actually declares one. See `GroupDrawCommand.effects` for
-     * what a pass may read, and {@link LayerGroup} to run one chain over
-     * several layers at once instead of one chain each.
-     */
-    effects?: readonly Effect[];
-    /**
-     * Optional hit-test for **consumer-attached** layers.
-     *
-     * Only layers registered through `CanvasExtensionApi.registerLayer` are
-     * hit-tested: `hitTestExtras` walks them last-registered-first on
-     * pointerdown, and `<SceneCanvas>` folds the result into its `affordanceAt`
-     * thunk ahead of the kit's own selection chrome. First non-null result
-     * wins; null means "I don't claim this hit, try the next layer."
-     *
-     * Layers that reach the draw stack some other way — a `Tool.overlay`, an
-     * entry in the `layers` map — are painted but never hit-tested, so defining
-     * `hitTest` on one has no effect. (The kit's own chrome doesn't need it: it
-     * goes through `buildAffordanceAt`.)
-     *
-     * Coordinates are world-space. The `data` arg is the layer's
-     * configured data slot (same as `draw`); `view` and `dims` mirror
-     * `draw`'s arguments.
-     */
-    hitTest?: (worldX: number, worldY: number, data: TData, view: View, dims: Dims, 
-    /** Chrome-caps visibility predicate. When supplied, the layer must
-     *  not return a hit from any chrome element whose id reports
-     *  `false`. Absent → every element is hittable. */
-    isVisible?: (id: string) => boolean) => LayerHit | null;
-    /**
-     * Called on every pointermove when no gesture is currently captured.
-     * Lets layers (e.g. HUD widgets) track hover state without participating
-     * in the drag pipeline. Coords are world-space; the layer is responsible
-     * for any further conversion (e.g. world→screen for screen-space layers)
-     * and for its own throttling.
-     */
-    onUncapturedMove?: (worldX: number, worldY: number, evt: PointerEvent, view: View, dims: Dims) => void;
-    /**
-     * Called when the cursor leaves the canvas element. Lets layers clear
-     * any hover state they're holding.
-     */
-    onUncapturedLeave?: () => void;
-}
-/**
- * Walk visible layers and concatenate their emitted DrawCommand arrays into
- * one flat list, ready to feed to `WeaselRenderer.render(commands)`.
- *
- * Visibility resolution order:
- *   1. `alwaysOn` — always drawn, ignores visibility map.
- *   2. Explicit entry in `visibility` map — overrides default.
- *   3. `layer.defaultVisible` — falls back to `true` when absent.
- *
- * Transform composition: world-space layers (the default; `space` unset or
- * `'world'`) have their commands wrapped in a `kind: 'group'` with
- * `viewToMat3(view)` before they reach the renderer. Screen-space layers
- * (`space: 'screen'`) pass through unchanged.
- *
- * A layer whose `draw` throws is dropped for the frame and reported through
- * `onLayerError` — the rest of the frame still paints.
- *
- * `groups` brackets runs of consecutive layers so they composite as one — see
- * `LayerGroup`. A layer named by no group is emitted exactly as it was before
- * groups existed, and a frame that declares none allocates nothing.
- */
-declare function drawLayers<TData>(layers: RenderLayer<TData>[], data: TData, visibility: Record<string, boolean>, order: string[] | undefined, view: View | undefined, dims: Dims, cache?: LayerCommandCache, onLayerError?: (failure: LayerDrawFailure) => void, groups?: readonly LayerGroup[]): DrawCommand[];
-/**
- * Resolve one layer's visibility: `alwaysOn` wins, then an explicit entry in
- * `visibility`, then `defaultVisible`, defaulting to shown.
- */
-declare function isLayerVisible<TData>(layer: RenderLayer<TData>, visibility: Record<string, boolean>): boolean;
-/**
- * Does this layer reach the screen at all — both gates, in the order
- * `drawLayers` applies them.
- *
- * **A listed `order` is the whole list**, so omission from it drops a layer
- * that `visibility` would have shown, and `alwaysOn` does not rescue it.
- * Hit-testing asks this, not `isLayerVisible`: a layer that is not painted
- * but still claims pointer events is a pointer landing on nothing the user
- * can see.
- */
-declare function isLayerPainted<TData>(layer: RenderLayer<TData>, visibility: Record<string, boolean>, order: string[] | undefined): boolean;
-/**
- * Draw one layer and put its commands in the space its `space` declares:
- * world-space output wrapped in a `viewToMat3(view)` group, screen-space
- * output passed through.
- *
- * Anything rendering layers through a view — the canvas itself, a viewport
- * node's inner pass — goes through here. A second copy of this rule that
- * forgets the wrap draws world content at raw world coords, which looks
- * plausible at the identity view and wrong everywhere else.
- *
- * A `draw` that throws yields no commands, and `onLayerError` is told which
- * layer it was. The layer's cache entry goes with it, so the next frame is a
- * real re-attempt rather than a stale tree served under fresh deps.
- */
-declare function drawOneLayer<TData>(layer: RenderLayer<TData>, data: TData, view: View, dims: Dims, cache?: LayerCommandCache, onLayerError?: (failure: LayerDrawFailure) => void): DrawCommand[];
-
-/**
- * Facts about the device the canvas is running on.
- *
- * One object, recomputed when the underlying media queries change, read by
- * two consumers: the chrome-caps rule layer (via `RuleCtx.device`) and the
- * handle-sizing constants (via `targetScale`).
- *
- * Deliberately NOT a form-factor concept. There is no `isPhone` here and
- * there should never be one: chrome layout is the consuming app's decision.
- * The kit's job is to stop assuming a mouse.
- */
-interface DeviceProfile {
-    /** `matchMedia('(pointer: coarse)')` — the primary pointer is imprecise. */
-    readonly coarsePointer: boolean;
-    /** `matchMedia('(hover: hover)')` — the primary pointer can hover. */
-    readonly canHover: boolean;
-    /** Live device pixel ratio. */
-    readonly dpr: number;
-    /** Multiplier for handle sizes and hit radii. Derived from
-     *  `coarsePointer` unless explicitly overridden. */
-    readonly targetScale: number;
-}
-/** The detected half of a profile — everything except the derived scale. */
-type DetectedDeviceFacts = Omit<DeviceProfile, 'targetScale'>;
-
-/**
- * Live state read by rule evaluation. Built once per frame on the consuming
- * surface — chrome-caps, the affordance pipeline, the dispatcher's
- * eligibility filter — and discarded.
- *
- * Adding a new field is additive: existing rules don't change, new
- * selector atoms can read it.
- */
-interface RuleCtx {
-    readonly focused: boolean;
-    readonly selection: readonly NodeId[];
-    readonly multiActive: boolean;
-    readonly modifiers: ModifierState;
-    readonly action: {
-        readonly kind: string | null;
-        readonly id: string | null;
-    };
-    readonly hover: NodeId | null;
-    readonly view: View;
-    /** Active mode id. `'normal'` when no non-default mode is engaged. */
-    readonly mode: string;
-    /** Capability tags allowed by the active mode (the union of
-     *  `ModeDefinition.allows` plus implicit tags). The `capability:`
-     *  selector reads this to determine whether a tag is permitted. */
-    readonly allowedCapabilities: ReadonlySet<CapabilityTag>;
-    /** Whether the current selection may be resized. `<SceneCanvas>` folds
-     *  `selectTool.resize.resizable` over the selection (true only when every
-     *  selected node is resizable). Read by the `resizable:` selector to gate
-     *  `selection.resize-handles`. Absent (legacy ctx builders) is treated as
-     *  resizable — back-compat: handles show unless a consumer opts a node out. */
-    readonly selectionResizable?: boolean;
-    /** Whether a path is currently in anchor-edit mode. Read by the
-     *  `editingAnchors:` selector, which gates the path-edit chrome.
-     *
-     *  This is deliberately a fact about state, not about permission: the
-     *  anchor overlay and the anchor hit-test must agree, and the thing they
-     *  must agree on is "is there an edited path right now", which no
-     *  capability or mode id answers. A mode that allows `edits-anchors`
-     *  with nothing being edited should draw no anchors. Absent is treated
-     *  as false. */
-    readonly editingAnchors?: boolean;
-    /** Device facts — pointer coarseness, hover capability, density.
-     *
-     *  Absent (legacy ctx builders) is treated as
-     *  {@link DEFAULT_DEVICE_PROFILE}: a fine pointer that can hover, at
-     *  density 1. That is what the kit assumed before this field existed, so
-     *  an absent profile is behavior-preserving by construction. */
-    readonly device?: DeviceProfile;
-}
-/** The live state a `RuleCtx` is assembled from — the chrome context plus
- *  what the active mode allows. */
-interface BuildRuleCtxArgs {
-    focused: boolean;
-    selection: readonly NodeId[];
-    multiActive: boolean;
-    modifiers: ModifierState;
-    action: {
-        kind: string | null;
-        id: string | null;
-    };
-    hover: NodeId | null;
-    view: View;
-    mode: string;
-    allowedCapabilities: ReadonlySet<CapabilityTag>;
-    /** Optional — omitted means "resizable" (handles show). See {@link RuleCtx}. */
-    selectionResizable?: boolean;
-    /** Optional — omitted means "no path is being anchor-edited". */
-    editingAnchors?: boolean;
-    /** Optional — omitted means {@link DEFAULT_DEVICE_PROFILE}. */
-    device?: DeviceProfile;
-}
-/** Gather the current canvas and mode state into the context that action
- *  eligibility and chrome-visibility rules are evaluated against. */
-declare function buildRuleCtx(args: BuildRuleCtxArgs): RuleCtx;
-
-/**
- * A selector is a conjunction of key/value tests. Multiple keys at the same
- * level AND together. Each key maps to a selector primitive in the evaluator.
- */
-interface Selector {
-    selection?: {
-        is?: number;
-        atLeast?: number;
-        empty?: boolean;
-    };
-    mode?: string | {
-        not: string;
-    } | {
-        in: readonly string[];
-    };
-    capability?: CapabilityTag | readonly CapabilityTag[] | {
-        in: readonly CapabilityTag[];
-    } | {
-        not: CapabilityTag;
-    };
-    gesturing?: boolean;
-    actionIs?: string;
-    modifierHeld?: keyof ModifierState;
-    focused?: boolean;
-    hovering?: boolean;
-    hoveringSelected?: boolean;
-    zoomAtLeast?: number;
-    /** Matches `ctx.editingAnchors` — true while a path is in anchor-edit
-     *  mode. Absent flag is treated as `false`. */
-    editingAnchors?: boolean;
-    /** Matches `ctx.selectionResizable`. Absent flag is treated as `true`
-     *  (resizable), so `{ resizable: true }` passes for legacy ctx builders
-     *  that don't compute it. */
-    resizable?: boolean;
-    /** Matches `ctx.device.coarsePointer` — the primary pointer is imprecise
-     *  (touch, most styluses). Absent device is treated as `false`. */
-    coarsePointer?: boolean;
-    /** Matches `ctx.device.canHover` — the primary pointer can hover. Absent
-     *  device is treated as `true`. */
-    canHover?: boolean;
-}
-/**
- * Composable visibility/eligibility rule. Trees of `all`/`any`/`not` nodes
- * over `Selector` leaves. `when` is the escape hatch — its closure is
- * opaque to introspection and should be avoided when a declarative form
- * exists. Empty `all` is true; empty `any` is false.
- */
-type Rule = Selector | {
-    all: readonly Rule[];
-} | {
-    any: readonly Rule[];
-} | {
-    not: Rule;
-} | {
-    when: (ctx: RuleCtx) => boolean;
-};
-/** Constant rules. Kept here so they have a single source. */
-declare const ALWAYS: Rule;
-/** A rule that never passes. `any` of nothing is false. */
-declare const NEVER: Rule;
-/**
- * Render a {@link Rule} as a short human-readable string, for inspectors and
- * diagnostics that need to say WHICH rule decided something.
- *
- * ```
- * { capability: 'edits-page' }               → capability:edits-page
- * { all: [{ mode: 'normal' }, { focused: true }] } → all(mode:normal, focused:true)
- * { not: { selection: { empty: true } } }    → not(selection:empty=true)
- * { when: function hasPath() { … } }         → when(hasPath)
- * ```
- *
- * Never throws and always terminates — unlike `JSON.stringify`, which throws
- * on a cyclic value and renders the `when` arm as a useless `{}`.
- */
-declare function describeRule(rule: Rule): string;
-/** Evaluate a rule against a context. Pure, and cheap enough to run per
- *  frame for every piece of chrome. */
-declare function evaluate(rule: Rule, ctx: RuleCtx): boolean;
-
-/**
- * Live state read by chrome-visibility {@link Condition}s. Backward-compat
- * alias for the legacy ChromeCtx shape — kept for consumers that still
- * import `ChromeCtx`. Subset of `RuleCtx`: legacy ChromeCtx didn't carry
- * mode/capability info. The resolver builds a `RuleCtx` for evaluation;
- * surfaces that still operate in `ChromeCtx` shape supply defaults
- * (mode='normal', empty allowedCapabilities) at the construction site.
- */
-interface ChromeCtx {
-    readonly focused: boolean;
-    readonly selection: readonly NodeId[];
-    readonly multiActive: boolean;
-    readonly modifiers: ModifierState;
-    readonly action: {
-        readonly kind: string | null;
-        readonly id: string | null;
-    };
-    readonly hover: NodeId | null;
-    readonly view: View;
-}
-/**
- * Composable visibility predicate with fluent surface. Carries its underlying
- * `Rule` tree at `.rule` so the resolver can introspect / share trees with
- * the affordance pipeline and the dispatcher's eligibility filter.
- *
- * Callable form `cond(ctx)` evaluates the tree against ctx. The fluent
- * methods return new Conditions wrapping new trees.
- *
- * **Chain semantics: strict left-to-right, no precedence.**
- * `a.and(b).or(c)` is `(a && b) || c`; `a.or(b).and(c)` is
- * `(a || b) && c`. Mix `.and` and `.or` only when you mean
- * left-to-right evaluation. For grouped disjunction, name the
- * subexpression or use the top-level `or(...)`.
- */
-interface Condition {
-    (ctx: RuleCtx): boolean;
-    readonly rule: Rule;
-    /** `this && other` */
-    and(other: Condition | Rule): Condition;
-    /** `this || other` */
-    or(other: Condition | Rule): Condition;
-    /** `this && !other` */
-    andNot(other: Condition | Rule): Condition;
-    /** `this || !other` */
-    orNot(other: Condition | Rule): Condition;
-}
-/**
- * Stable identifier for one user-visible chrome element. The same id
- * gates both paint and hit-test — there is no separate
- * `affordance.X` / `selection.X` split — so toggling a rule cannot
- * leave a visually-present but un-hittable handle (or vice versa).
- *
- * Naming convention by lifecycle:
- *
- *   - `selection.*` — chrome reflecting committed selection state
- *     (persists between actions).
- *   - `action.*` — chrome that only exists during an in-flight
- *     action (vanishes on commit / cancel).
- *   - `snap.*` — snapping system chrome (guides, target highlights).
- *   - `grid`, `debug.*` — environment chrome.
- *
- * The intersection `(string & {})` keeps the union open so consumers
- * can register their own ids; the kit's built-ins are listed
- * explicitly for autocomplete.
- */
-type ChromeId = 'selection.outline' | 'selection.resize-handles' | 'selection.rotation-handle' | 'action.marquee' | 'action.lasso' | 'action.move-ghosts' | 'action.insert-preview' | 'action.commands' | 'snap.guides' | 'snap.targets' | 'grid' | (string & {});
-/**
- * Consumer override map. Merged on top of the kit's
- * `defaultVisibilityRules`; absent keys fall through to defaults,
- * absent ids fall through to `always`. Entries may be either fluent
- * `Condition` instances OR raw `Rule` trees — the resolver normalizes.
- */
-type VisibilityRules = Partial<Record<ChromeId, Condition | Rule>>;
-
-/**
- * The kit's built-in shape kinds — one table, every other spelling derived.
- *
- * Lives in `core/` rather than beside the shape tools because both layers ask
- * questions of the same set: the interactions layer decides whether
- * `insertAction` can paint a live preview for a kind, and the canvas layer
- * decides which shape tools `useBuiltinShapeTools` mounts and what
- * `BUNDLE_TOOLS` / `defaultNodeRouting` / `defaultNodeProperties` enumerate.
- *
- * This module imports nothing on purpose: `useBuiltinShapeTools` imports the
- * package barrel, so anything barrel-reachable that needs these lists at
- * module-evaluation time must not route through it.
- */
-/** What the kit knows about one built-in shape kind. */
-interface ShapeKindDescriptor {
-    /** Mounted as a built-in shape tool by `useBuiltinShapeTools`, and so a
-     *  member of `BuiltinShapeToolId` / `KIT_SHAPE_KINDS`. `image` is false:
-     *  `useImageTool` needs a `src` and can't be auto-mounted. */
-    readonly tool: boolean;
-    /** `insertAction` emits an `insertPreview` overlay for this kind, and the
-     *  dispatcher overlay layer knows how to draw it. Kinds without one still
-     *  commit; they just have no live drag preview (`pen` and `lasso` don't
-     *  route through `insertAction` at all). */
-    readonly insertPreview: boolean;
-}
-/**
- * Declaration order is the enumeration order of every derived list —
- * `KIT_SHAPE_KINDS`, and through it `defaultNodeRouting` /
- * `defaultNodeProperties` / `BUNDLE_TOOLS.exhaustive`.
- */
-declare const SHAPE_KINDS: {
-    readonly rect: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly ellipse: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly line: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly polygon: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly star: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly pen: {
-        readonly tool: true;
-        readonly insertPreview: false;
-    };
-    readonly pencil: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly lasso: {
-        readonly tool: true;
-        readonly insertPreview: false;
-    };
-    readonly text: {
-        readonly tool: true;
-        readonly insertPreview: true;
-    };
-    readonly image: {
-        readonly tool: false;
-        readonly insertPreview: true;
-    };
-};
-/** The keys of a shape-kind table whose descriptor sets `F` to `true`. */
-type ShapeKindsWhere<T, F extends keyof ShapeKindDescriptor> = {
-    [K in keyof T]: T[K] extends Record<F, true> ? K : never;
-}[keyof T];
-/**
- * Built-in shape tool ids handled by `useBuiltinShapeTools`. Each maps to a
- * kit tool hook + a default `create` that produces a leaf node compatible
- * with `PATH_PAINTER`.
- */
-type BuiltinShapeToolId = ShapeKindsWhere<typeof SHAPE_KINDS, 'tool'>;
-/** The insert kinds the kit's dispatcher overlay layer knows how to render.
- *  Consumer-defined kinds fall outside it: no live preview, commit unaffected. */
-type KitInsertShape = ShapeKindsWhere<typeof SHAPE_KINDS, 'insertPreview'>;
-/** Runtime, iterable list of the shape-tool ids in `BuiltinShapeToolId`.
- *  Surfaced so consumers (e.g. the Bundle Inspector) can enumerate the
- *  builtin shape kinds without re-encoding the union. */
-declare const KIT_SHAPE_KINDS: readonly BuiltinShapeToolId[];
-
-/** A 2D point in either world or screen coordinates. */
-interface Point2 {
-    x: number;
-    y: number;
-}
-/**
- * Information about which UI affordance was hit at pointerdown.
- *
- * Populated by the dispatcher when the `affordanceAt` thunk is provided to
- * `useGestureDispatcher`. Tools / action invokers that only fire on a specific
- * affordance (e.g. a resize handle) use this field as a guard — if the
- * affordance is absent or is the wrong kind, they return `{}` and let other
- * bindings handle the drag.
- *
- * `kind` is a discriminator string:
- *   - `'handle:top-left'` / `'handle:top-right'` / `'handle:bottom-left'` /
- *     `'handle:bottom-right'` — corner resize handles.
- *   - `'rotate-handle'` — the rotation affordance.
- *   - `'anchor:N'` — a path anchor at index N.
- *
- * `fixedPoint` is the world-space point that should remain stationary during
- * the gesture. For resize handles this is the opposite (diagonally fixed)
- * corner; for rotate it is the pivot.
- *
- * `targetIds` are the node ids this affordance belongs to.
- */
-interface AffordanceHit {
-    /** Discriminator string, e.g. `'handle:bottom-right'`. */
-    kind: string;
-    /** Id of whatever produced this hit — a kit affordance's `id`, or the
-     *  registered layer's id. Read only by the dispatcher's dead-claim warning today. */
-    owner?: string;
-    /** `'exclusive'` means no binding may act on this point unless its target
-     *  consults the affordance. `'shared'` (the default) competes on scope and
-     *  specificity as bindings always have. */
-    strength?: 'exclusive' | 'shared';
-    /** Which gestures an exclusive claim bars. Omitted bars all of them. */
-    claimedKinds?: readonly ClaimableGesture[];
-    /** World-space fixed/pivot point. For resize: opposite corner. For rotate: pivot. */
-    fixedPoint?: {
-        x: number;
-        y: number;
-    };
-    /** Which nodes this affordance belongs to. */
-    targetIds?: string[];
-    /** Set when `kind` matches `'handle:*'`. Identifies which corner stays
-     *  fixed during a resize so consumers (resizeAction) don't re-parse `kind`.
-     *  Other affordance kinds (rotate-handle, anchor:N, controlIn:N, controlOut:N)
-     *  leave this undefined. */
-    anchor?: ResizeAnchor;
-    /** Cursor to show while the pointer hovers this affordance (no
-     *  gesture in flight). Consumed by the hover-cursor pump in
-     *  `useGestureDispatcher`; unset = the pump falls through to
-     *  action-cursor prediction, then to the active tool's cursor. */
-    cursor?: CursorSpec;
-    /**
-     * Free-form payload from whatever produced the hit, carried through to the
-     * matching action untouched.
-     *
-     * Kit affordances describe themselves fully in the fields above and leave
-     * this unset. It exists for affordances the kit doesn't know the shape of —
-     * a registered layer's own chrome, where the hit-test already resolved
-     * *which* of its pieces was hit and the action would otherwise have to
-     * redo that work. `@weasel-js/hud` passes the hit widget here.
-     */
-    payload?: unknown;
-}
-/**
- * One accumulated point on a drag trail: world-space position plus whatever
- * stylus state the originating `PointerEvent` carried.
- *
- * The stylus fields are absent for mouse/touch on browsers that don't report
- * them, and for synthetic events. Consumers that want pressure-driven output
- * (e.g. `Stroke.vertexWidths` from a pencil stroke) read them off the samples
- * their `insert` dep receives — see `apps/site/demos/VertexWidthsDemo.tsx`.
- */
-interface DragSample extends Point2 {
-    /** 0..1. Mouse/touch report 0.5 while a button is held, per the spec. */
-    pressure?: number;
-    /** Degrees, ±90. Zero for mouse/touch. */
-    tiltX?: number;
-    /** Degrees, ±90. Zero for mouse/touch. */
-    tiltY?: number;
-}
-/** Per-invocation runtime context the dispatcher hands to an Invoker.
- *  Gesture-kind-specific fields (`drag`, `wheel`, `multiTouch`, `key`) are
- *  populated only for matching gesture kinds. */
-interface InvocationCtx {
-    world: Point2;
-    screen: Point2;
-    modifiers: ModifierState;
-    deps: ActionDeps;
-    drag?: {
-        start: Point2;
-        current: Point2;
-        delta: Point2;
-        /**
-         * Drag delta in client/screen coordinates (CSS pixels from the drag
-         * origin). Use this — never `delta` — for any action whose effect
-         * mutates the viewport itself (pan, view-zoom), because world-space
-         * deltas become self-referential as the view shifts mid-drag.
-         *
-         * Populated when the dispatcher received `clientX`/`clientY` on the
-         * underlying pointer events. Absent for legacy callers that don't
-         * provide them.
-         */
-        screenDelta?: Point2;
-        affordance?: AffordanceHit;
-        /**
-         * Full pointermove history for the current drag, in world space, with
-         * per-sample stylus state when the browser reported it.
-         * Accumulated by the dispatcher on every `pointermove` pump event.
-         * Available only during `onMove` and `onEnd` calls (not on `start`).
-         * Used by `lassoSelectAction` to build its polygon vertex list and by
-         * `insertAction`'s pencil kind to carry the freehand stroke.
-         */
-        points?: DragSample[];
-    };
-    wheel?: {
-        deltaX: number;
-        deltaY: number;
-        deltaZ: number;
-    };
-    multiTouch?: {
-        centroid: Point2;
-        spread: number;
-        rotation: number;
-        /**
-         * Pinch-zoom geometry. Populated by the dispatcher when a multitouch
-         * handle is in flight and a pointermove-pump fires.
-         * `startSpread` is the spread at the moment the gesture began.
-         * `currentSpread` is the spread at the current frame.
-         */
-        pinch?: {
-            startSpread: number;
-            currentSpread: number;
-            centroid: Point2;
-        };
-    };
-    key?: {
-        key: string;
-        repeat: boolean;
-    };
-    /**
-     * Per-invocation parameters. Populated by `ActionsRegistry.begin()` for
-     * UI-driven ongoing actions (color picker, opacity slider) so handles can
-     * read the current value on `start` and updated values on `onMove`. The
-     * gesture dispatcher does not populate this field; gesture-driven actions
-     * receive params via `BindingOpts.params` on `start` (the `opts` arg).
-     */
-    params?: Record<string, unknown>;
-}
-/** Per-invocation options the dispatcher reads from a `GestureBinding`'s
- *  `opts` field and passes to `OngoingInvoker.start`. Today carries
- *  behaviors; extensible. */
-interface BindingOpts {
-    behaviors?: ActionBehavior<unknown, unknown, unknown>[];
-    /** Per-binding action parameters. The action's invoker reads
-     *  these via the second arg to `run` (or via InvocationCtx for ongoing
-     *  invokers, when needed). Loose typing (Record<string, unknown>) for
-     *  now; consider per-action typing later via BindingOpts<A>.
-     *
-     *  params may also be a thunk evaluated each time the
-     *  dispatcher (or invoker) needs the value. Thunks let tools close over
-     *  refs that mutate during a gesture (e.g. polygon `sides` adjusted
-     *  mid-drag via ArrowUp). For ongoing invokers that want the latest
-     *  values at commit, the invoker can re-call the thunk inside `onEnd`
-     *  via `resolveParams(opts?.params)`. */
-    params?: Record<string, unknown> | (() => Record<string, unknown>);
-}
-/** Resolve `BindingOpts.params` to a concrete record (calling the thunk if
- *  needed). Returns `undefined` for absent params. */
-declare function resolveParams(params: BindingOpts['params']): Record<string, unknown> | undefined;
-/** Convention-shaped action dependencies bag. Actions declare which
- *  contexts they consume; the dispatcher composes them per call.
- *  Consumer-side contexts (e.g. ColorContext) plug in by extending. */
-interface ActionDeps {
-    selection?: unknown;
-    view?: unknown;
-    scene?: unknown;
-    pointer?: unknown;
-    activeTool?: unknown;
-    [k: string]: unknown;
-}
-/**
- * Discriminated overlay shape returned by `OngoingHandle.overlay()`.
- * Dispatcher-side chrome surface for in-flight
- * gestures that paint non-ghost visuals. The canvas's
- * `useDispatcherOverlayLayer` walks every in-flight handle, calls
- * `overlay()`, and dispatches on `kind` to draw the appropriate shape.
- *
- * `marquee` mirrors `AreaSelectOverlay`; `lasso` mirrors `LassoSelectOverlay`.
- * `commands` is the generic escape hatch — actions emit arbitrary
- * `DrawCommand[]` for previews the typed variants can't express (insert
- * shape outlines, paste ghosts of synthetic nodes, custom chrome). World-
- * space is the default; the layer wraps in `viewToMat3` so commands track
- * the camera. Set `space: 'screen'` for projections you've already done
- * yourself (rare).
- */
-type OngoingOverlay = {
-    kind: 'marquee';
-    start: {
-        x: number;
-        y: number;
-    };
-    current: {
-        x: number;
-        y: number;
-    };
-    shiftHeld: boolean;
-} | {
-    kind: 'lasso';
-    vertices: ReadonlyArray<{
-        x: number;
-        y: number;
-    }>;
-    current: {
-        x: number;
-        y: number;
-    };
-    shiftHeld: boolean;
-} | {
-    kind: 'commands';
-    commands: readonly DrawCommand[];
-    /** Coordinate space the commands are authored in. Default `'world'`
-     *  — the layer wraps them in `viewToMat3(view)` so they track the
-     *  camera. `'screen'` emits them as-is (CSS pixels). */
-    space?: 'world' | 'screen';
-} | {
-    /**
-     * Live insert-drag preview — dispatched by `insertAction` while the
-     * user is dragging out a new shape. Pre-commit there is no scene node
-     * to ghost via `previewIds()`/`previewPose()`, so insert paints its
-     * preview through the dispatcher overlay layer instead.
-     *
-     * `shape` is the kit's built-in insert kind. `bounds` is the AABB of
-     * the current drag (start/current normalized). `extras` is the
-     * per-kind extras the action already collected — the overlay
-     * renderer rebuilds the shape using the same path builders the
-     * commit factory uses, so the preview matches the eventual node.
-     *
-     * `extras` is opaque (`unknown`) at the union level; the overlay
-     * renderer narrows on `shape` and casts the field shape it expects.
-     */
-    kind: 'insertPreview';
-    shape: KitInsertShape;
-    bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    extras: unknown;
-    /** World-space point to paint a small "anchor" dot at. Sells the
-     *  click point as the drag's anchor — particularly useful for
-     *  radial shapes (polygon/star) where no vertex sits on the
-     *  click point, and for any shape in center mode where the dot
-     *  marks the center the shape grows around. */
-    anchorPoint?: {
-        x: number;
-        y: number;
-    };
-};
-/** Handle returned from an `OngoingInvoker.start`. The dispatcher pumps
- *  `onMove` on subsequent input events of the same gesture and calls
- *  `onEnd` exactly once (with `'commit'` on natural completion or `'cancel'`
- *  on pointercancel / blur / escape). */
-interface OngoingHandle {
-    /**
-     * Optional logical action kind — a stable, human-readable tag the
-     * dispatcher exposes via `getActiveAction()` for chrome-visibility
-     * rules and any other surface that wants to react to "what action
-     * is currently in flight" without inspecting handles directly.
-     *
-     * Examples: `'marquee'`, `'lasso'`, `'move'`, `'resize'`, `'rotate'`,
-     * `'pan'`, `'pinch'`.
-     *
-     * Distinct from the dispatcher's internal `gestureId` (`pointer-mouse`,
-     * `key-held-Space`, etc.) which keys per-pointer state and is not
-     * meaningful to consumers.
-     *
-     * When omitted, the action is "anonymous" — `getActiveAction().kind`
-     * reports `null` even though a handle is in flight. This is fine for
-     * actions that don't have visible chrome of their own.
-     */
-    kind?: string;
-    onMove?(ctx: InvocationCtx): void;
-    onEnd?(ctx: InvocationCtx, reason: 'commit' | 'cancel'): void;
-    /**
-     * Optional preview surface — dispatcher-side ghost overlay.
-     *
-     * An ongoing-action implementation may populate `previewIds()` +
-     * `previewPose(id)` to expose its in-flight preview state for the
-     * canvas's preview-ghost layer (`usePreviewGhostLayer`) to render on
-     * top of the committed scene during the gesture.
-     *
-     * Returning `null` (or omitting the method entirely) means "no preview
-     * this gesture" — the canvas will skip this handle as a source.
-     *
-     * Semantics mirror the tool-side `Tool.previewIds` / `Tool.previewPose`
-     * pair: `previewIds()` enumerates the displaced node ids; `previewPose(id)`
-     * returns the interim pose for one of those ids (shape opaque — the
-     * canvas casts to its `TPose` parameter). The preview-ghost layer
-     * merges all sources via first-non-null semantics, with tool-side
-     * previews taking precedence over dispatcher-side (preserves
-     * backwards-compat during the registry-unification migration).
-     */
-    previewIds?(): Iterable<string> | null;
-    previewPose?(id: string): unknown | null;
-    /**
-     * Subset of `previewIds()` the ghost layer paints at full opacity. The
-     * ghost alpha says "this is in flight under the pointer"; a node the
-     * gesture merely displaces — a layout sibling reflowing into its
-     * destination slot — is not, and reads better settled. Honored at
-     * subtree-root granularity.
-     */
-    previewOpaqueIds?(): Iterable<string> | null;
-    /**
-     * When `false`, the preview-ghost layer paints the ghost AND the
-     * source node stays visible at its committed pose. Defaults to
-     * `true` (move/resize/rotate semantics: ghost replaces the source
-     * during the gesture). Clone overrides to `false` so the original
-     * stays put and the ghost appears at the drag target.
-     */
-    previewHidesSource?: boolean;
-    /**
-     * Optional per-id preview *data*. Falls back to the committed
-     * `node.data` when null/absent. Use when the gesture mutates
-     * `node.data` (e.g. anchor-edit on nodes that store the polygon on
-     * `data.path`) rather than (or in addition to) the pose. The preview-
-     * ghost layer assembles a synthetic node from `{ ...node, pose:
-     * previewPose ?? node.pose, data: previewData ?? node.data }` before
-     * calling the scene slot's `drawOne`.
-     *
-     * Sources compose first-non-null per axis: an action can emit only
-     * `previewPose` (translation), only `previewData` (data-only edit),
-     * or both (pose + data both change, e.g. anchor drag on a data.path
-     * node where the bounds shift).
-     */
-    previewData?(id: string): unknown | null;
-    /**
-     * Optional chrome surface — dispatcher-side overlay layer.
-     *
-     * An ongoing-action implementation may populate `overlay()` to expose a
-     * non-ghost visual (marquee rectangle, lasso polyline) for the canvas's
-     * `useDispatcherOverlayLayer` to paint while the gesture is in flight.
-     * Returning `null` (or omitting the method) means "no overlay this
-     * gesture" — the canvas will skip this handle as a chrome source.
-     *
-     * Distinct from the `previewIds()`/`previewPose(id)` ghost surface,
-     * which paints displaced scene-node silhouettes. Marquee and lasso
-     * gestures don't displace any node, but still need on-screen feedback.
-     */
-    overlay?(): OngoingOverlay | null;
-}
-/** Fire-once invocation. Runs to completion synchronously (or fires off an
- *  async side-effect; the registry doesn't wait). */
-interface ImmediateInvoker {
-    timing: 'immediate';
-    /** `params` carries the matched binding's opts.params. Invoked from the
-     *  command palette, or anywhere else with no per-binding context, `params`
-     *  is undefined; descriptors should default to a sensible variant. */
-    run(deps: ActionDeps, params?: Record<string, unknown>): void;
-}
-/** Phase-machine invocation. `start` opens the phase and returns the handle
- *  the dispatcher pumps. */
-interface OngoingInvoker {
-    timing: 'ongoing';
-    start(ctx: InvocationCtx, opts?: BindingOpts): OngoingHandle;
-}
-/** Pluggable invocation strategy for an Action. Future variants
- *  (`longPress`, `twoStage`, `modal`) extend this union without touching
- *  the `Action` type. */
-type Invoker = ImmediateInvoker | OngoingInvoker;
-
-/**
- * GestureBinding — connects a GestureSpec to an Action id (with per-binding
- * options). Tools own arrays of these on their `bindings` field; ambient
- * gesture-bindings are registered globally.
- *
- * See `docs/superpowers/specs/2026-05-16-registry-unification-design.md`.
- */
-
-/** An interaction: a gesture spec composed with the id of the action it
- *  invokes. Tools declare arrays of these; the dispatcher matches an incoming
- *  input event against them and runs the winner's action. */
-interface GestureBinding {
-    spec: GestureSpec;
-    actionId: string;
-    opts?: BindingOpts;
-}
-
-/**
- * Pose composition for hierarchical scene graphs.
- *
- * As of the nesting change, `getPose(id)` on adapters returns the
- * **local** pose — relative to the object's direct parent. Anything in the
- * kit that needs to draw, hit-test, snap, or otherwise reason about world
- * coordinates routes through `composeWorldPose`, which walks the parent
- * chain and folds local poses together via a consumer-supplied `compose`.
- *
- * Pose shape is generic, so the compose strategy is too. For the common
- * `{x, y, width, height}` axis-aligned rect, use `composeRectPose` —
- * translation only, child dimensions preserved. Custom pose shapes (paths,
- * matrix transforms) supply their own.
- *
- * The inverse — `rebaseLocalPose` — converts a world-space pose into a
- * local pose under a target parent. Used when reparenting so the visual
- * world position of a child is preserved across the parent change.
- */
-/** Re-exported; the declaration lives in `core/scene/types.ts`, which names
- *  it and may not import from features. */
-
-/** Minimal adapter needed by `composeWorldPose` and friends — pose lookup plus parent walk. */
-interface PoseAdapter<TPose> {
-    getPose(id: string): TPose;
-    getParent(id: string): string | null;
-}
-/** Consumer's pose-composition strategy for hierarchical scenes. `compose`
- *  folds a child's pose (in parent's frame) up to the next frame; `decompose`
- *  is its inverse. Default is IDENTITY — an absolute-pose scene where every
- *  node already stores world coords (parent is grouping-only, no transform). */
-interface PoseComposition<TPose> {
-    compose: (parent: TPose, child: TPose) => TPose;
-    decompose: (parent: TPose, world: TPose) => TPose;
-}
-/** Default pose-composition strategy: IDENTITY. Both `compose` and
- *  `decompose` return the child/world pose unchanged, modeling an
- *  absolute-pose scene where every node stores world coords and parents are
- *  grouping-only (no transform). With this strategy `composeWorldPose`
- *  returns a node's own raw pose and `rebaseLocalPose` is a no-op. */
-declare const IDENTITY_POSE_COMPOSITION: PoseComposition<unknown>;
-/**
- * Walk `id`'s parent chain (root first to id last) and fold local poses into
- * a world pose via `compose`. Returns the world pose for `id`. Cycle-safe:
- * a visited-set guard breaks if the chain ever loops back to itself.
- *
- * `compose(parent, child)` interprets `child` as expressed *in `parent`'s
- * local frame* and returns the equivalent pose in the next frame up. For a
- * standard translation-only rect: `world = { x: p.x + c.x, y: p.y + c.y,
- * width: c.width, height: c.height }`.
- */
-declare function composeWorldPose<TPose>(adapter: PoseAdapter<TPose>, id: string, compose: (parent: TPose, child: TPose) => TPose): TPose;
-/**
- * Default `compose` for axis-aligned rectangles. Adds translation; preserves
- * child width/height. Treat as the canonical compose for any
- * `{x, y, width, height}` pose under a translation-only hierarchy.
- *
- * Generic over the concrete pose type so callers with a wider pose
- * (e.g. `RectPose & { rotation }`) can pass it through; the extra fields
- * are taken from the child unchanged.
- */
-declare function composeRectPose<TPose extends RectPose>(parent: TPose, child: TPose): TPose;
-/**
- * Translate a `RectPose`-shaped pose by `(dx, dy)`. Suitable as the default
- * `translatePose` for `useMove` when poses carry top-level `x`/`y`. Other
- * fields (width/height, plus any extra props on `TPose`) are preserved.
- */
-declare function translateRectPose<TPose extends RectPose>(pose: TPose, dx: number, dy: number): TPose;
-/**
- * Convert `worldPose` into a local pose expressed under `newParentId`'s
- * frame. Used when reparenting so the child's visual world position is
- * preserved despite the change of frame. Inverse of one `compose` step.
- *
- * `decompose(parent, world)` returns the local pose `child` such that
- * `compose(parent, child) === world`. For axis-aligned rects:
- * `child = { ...world, x: world.x - parent.x, y: world.y - parent.y }`.
- *
- * Pass `newParentId === null` for the root frame; the function returns
- * `worldPose` unchanged.
- */
-declare function rebaseLocalPose<TPose>(adapter: PoseAdapter<TPose>, worldPose: TPose, newParentId: string | null, compose: (parent: TPose, child: TPose) => TPose, decompose: (parent: TPose, world: TPose) => TPose): TPose;
-/** Inverse of `composeRectPose` — subtracts parent translation. */
-declare function decomposeRectPose<TPose extends RectPose>(parent: TPose, world: TPose): TPose;
-/**
- * Build a `(id) => world pose | null` callback over a `PoseAdapter`.
- * Convenience for RenderLayers that take a `getPose` callback (selection
- * overlays, debug layers, etc.) so consumers don't hand-write a
- * `composeWorldPose` call per layer.
- *
- * Returns `null` when `adapter.getPose` or `adapter.getParent` throws — the
- * common case is an id removed mid-render between selection state and the
- * next paint. Layers should treat `null` as "skip this id."
- */
-declare function worldPoseLookup<TPose>(adapter: PoseAdapter<TPose>, compose: (parent: TPose, child: TPose) => TPose): (id: string) => TPose | null;
-
-/** Boolean op identifiers — five Pathfinder primaries plus Crop. */
-type BooleanOp = 'union' | 'intersect' | 'subtract' | 'exclude' | 'divide' | 'crop';
-/**
- * z-position descriptor for a path node. `parentId` is the direct parent
- * (or `null` for a top-level node); `index` is the position within that
- * parent's child order. Used by the optional `getZOrder` hook below to
- * reposition the result of a boolean op at the topmost source's slot.
- */
-/** @internal */
-interface BooleanZOrder {
-    parentId: string | null;
-    index: number;
-}
-/** Adapter the hook and the pure core both consume. */
-interface BooleansAdapter {
-    getSelection(): NodeId[];
-    getWorldPath(id: NodeId): Path | undefined;
-    compareZ(a: NodeId, b: NodeId): number;
-    /**
-     * Mint a new node from a boolean-op result `Path`. `producedBy` names the
-     * op that synthesized it — adapters that store provenance (e.g. for a
-     * layer-panel icon) record it; others ignore the arg.
-     */
-    createPathNode(path: Path, producedBy: BooleanOp): {
-        id: string;
-    };
-    /**
-     * Optional: return the full object for an id, used by the delete ops so
-     * their `invert` (an insert) can restore the complete object on undo.
-     * If omitted, a `{ id }` stub is captured — undo will reinstate the id
-     * but consumers reading other fields (path, fill, etc.) will see them as
-     * undefined. Mirrors `DeleteAdapter.getNode`; should be provided whenever
-     * undo over boolean ops is expected to be lossless.
-     */
-    getNode?(id: NodeId): {
-        id: string;
-    } | undefined | null;
-    /**
-     * Optional: return the parent + child-index of `id` so the result of a
-     * boolean op can be placed in the topmost source's z-slot. Adapters that
-     * also expose `getChildren`/`setChildOrder` (the `ReorderAdapter`
-     * contract) will have the kit emit a `createMoveToIndexOp` after the
-     * inserts. Adapters that omit this method get v1 behavior — the result
-     * lands wherever the adapter's plain `insertNode` defaults to.
-     */
-    getZOrder?(id: NodeId): BooleanZOrder | undefined;
-    applyOps?(ops: Op[], label?: string): void;
-    setSelection?(ids: NodeId[]): void;
-    insertNode?(node: {
-        id: string;
-    }): void;
-    removeNode?(id: string): void;
-}
-/** Outcome reported back to callers (lets the hook surface no-op signals). */
-type BooleanOpResult = {
-    kind: 'applied';
-    resultIds: string[];
-} | {
-    kind: 'noop';
-    reason: 'no-paths' | 'too-few-for-subtract' | 'empty-result';
-};
-/**
- * Run one Boolean operation over the selected paths and commit the result as a
- * single undoable batch.
- *
- * Operands are ordered back-to-front, which is what makes `subtract` mean
- * "everything in front removed from the backmost shape". Returns without
- * mutating anything when the selection holds no paths, or too few for the
- * requested operation.
- */
-declare function applyBooleanOp(adapter: BooleansAdapter, op: BooleanOp): BooleanOpResult;
-
-/**
- * Selection click policy. `single` always replaces; `multi` toggles when the
- * configured extend key is held, otherwise replaces.
- */
-type SelectionMode = 'single' | 'multi';
-/** Modifier key used to extend the selection in `multi` mode. */
-type SelectionExtendKey = 'shift' | 'meta' | 'ctrl';
-/** API returned by {@link useSelection}. */
-interface SelectionApi {
-    /** Current selection. Re-renders trigger when this reference changes. */
-    current: readonly NodeId[];
-    /** Imperative read for use inside event callbacks (avoids stale closures). */
-    get(): NodeId[];
-    /** Replace selection. */
-    set(ids: NodeId[]): void;
-    /** Add id (multi-mode appends; single-mode replaces). */
-    add(id: NodeId): void;
-    /** Remove id from selection. */
-    remove(id: NodeId): void;
-    /** Toggle id in/out of selection. */
-    toggle(id: NodeId): void;
-    /** Clear selection. */
-    clear(): void;
-    /** True if id is selected. */
-    contains(id: NodeId): boolean;
-    /**
-     * Apply a click to the selection per the configured mode/extend key.
-     * - `single`: replaces selection with `[id]`, regardless of modifiers.
-     * - `multi`: with the extend key held, toggles `id` in/out of the selection;
-     *   otherwise replaces with `[id]`.
-     */
-    applyClick(id: NodeId, modifiers: {
-        shift: boolean;
-        meta: boolean;
-        ctrl: boolean;
-    }): void;
-    /** Pre-built methods for spreading into an adapter that needs them. */
-    adapterMethods: {
-        getSelection: () => NodeId[];
-        setSelection: (ids: NodeId[]) => void;
-    };
-}
-/** Somewhere selection can live outside this hook. `Scene` satisfies it;
- *  so does any store with the same three methods. */
-interface SelectionStore {
-    getSelection(): readonly NodeId[];
-    setSelection(ids: readonly NodeId[]): void;
-    subscribe(listener: () => void): () => void;
-}
-/** Options for {@link useSelection}. */
-interface UseSelectionOptions {
-    /** Default `'single'`. */
-    mode?: SelectionMode;
-    /** Default `'shift'`. Ignored in single-mode. */
-    extend?: SelectionExtendKey;
-    /** Default `[]`. */
-    initial?: readonly NodeId[];
-    /** Keep the selection on this store rather than in the hook, so every
-     *  consumer of the same scene shares one selection and undo / redo can
-     *  restore it. `initial` then only seeds a store that has none yet.
-     *  Omit it and the hook owns a selection nobody else sees. */
-    scene?: SelectionStore;
-    /** When `true`, every mutator (`set`/`add`/`remove`/`toggle`/`clear`/
-     *  `applyClick`) is a no-op — selection stays at whatever `initial`
-     *  pinned it to. Useful for demos that exist to showcase a single
-     *  pre-selected node (e.g. the bezier-edit curve) and don't want a
-     *  stray click to deselect. */
-    lock?: boolean;
-}
-/**
- * Default implementation of the `getSelection` / `setSelection` adapter
- * contract every action hook (delete, duplicate, nudge, group, ...) requires.
- *
- * Owns selection state, exposes a click-policy helper (single vs multi with
- * an extend key), and pre-builds the two adapter methods consumers otherwise
- * hand-roll in every demo:
- *
- * ```tsx
- * const selection = useSelection({ mode: 'multi' });
- * const adapter = { ...arrayAdapter({...}), ...selection.adapterMethods };
- * ```
- */
-declare function useSelection(opts?: UseSelectionOptions): SelectionApi;
-
-/** Context handed to every content handler for one ingest event. */
-interface IngestCtx {
-    /** World-space arrival point (drop / pointed imperative ingest); `null`
-     *  for paste and point-less calls — handlers pick their own policy
-     *  (the kit image handler centers on the viewport). */
-    point: {
-        x: number;
-        y: number;
-    } | null;
-    /** Visible canvas area in world coordinates. */
-    viewportWorldRect(): {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    /** The kit insert dep — id/layer/undoable-op supplied; the canonical way
-     *  for a handler to mint a node (`insert.commit(bounds, { kind, ... })`). */
-    insert: InsertDep;
-    /** Raw op commit for handlers that build their own ops. */
-    applyOps(ops: Op[], label?: string): void;
-    scene: Scene<unknown, string, unknown>;
-    selection: SelectionApi;
-    /** Consumer file→src resolver (SceneCanvas `ingestion.resolveSrc`).
-     *  When absent, the kit image handler embeds as a `data:` URI. */
-    resolveSrc?: (file: File) => Promise<string>;
-    /** Kit SVG-handler options (SceneCanvas `ingestion.svg`) — e.g.
-     *  `{ unpack: unpackSvgFiles }` (from `@weasel-js/svg`) to parse SVG files
-     *  into scene nodes. */
-    svg?: SvgIngestOptions;
-    /** Clipboard-paste seam — present when the hosting `SceneCanvas` supplied
-     *  an adapter with `commitPaste`. `reviver` comes from
-     *  `SceneCanvasProps.ingestion.clipboard`. Absent ⇒ the kit weasel-JSON
-     *  handler declines inert (dwarn, nothing ingested) — its matched items
-     *  were already consumed at match time, so they do NOT fall through;
-     *  only match-level misses flow on to other handlers. */
-    clipboard?: ClipboardIngestCtx;
-    /** Set to `true` by the kit weasel-JSON handler when it successfully
-     *  pastes a payload in this event. The `ctx` object is shared across all
-     *  handlers in one `runIngest` call, and higher-priority handlers' `handle`
-     *  bodies run (synchronously) before lower ones — so `kit:svg`'s
-     *  `text/plain` SVG fallback reads this to decline the SVG flavor of a copy
-     *  whose canonical weasel-JSON flavor already ingested (avoids a
-     *  double-paste when both flavors ride one clipboard event). */
-    consumedWeaselPayload?: boolean;
-    /** Full action-deps bag, for consumer handlers that need more. */
-    deps: ActionDeps;
-}
-/** A handler for content arriving by paste, drop or file picker. Handlers are
- *  matched by MIME glob or predicate and run highest-priority first; the kit's
- *  own register at a low priority so a consumer's handler wins by default. */
-interface ContentHandlerEntry {
-    /** Stable identifier — used for unregistration and debugging
-     *  (`'kit:image'`, `'app:csv'`). */
-    id: string;
-    /** MIME glob(s) (`'image/*'`, `'text/csv'`) or an item predicate. */
-    match: string | string[] | ((item: IngestItem) => boolean);
-    /** Higher runs earlier. Kit defaults register at -100 so any consumer
-     *  handler (default 0) beats them. */
-    priority?: number;
-    handle(items: IngestItem[], ctx: IngestCtx): void | Promise<void>;
-}
-/** Register a content handler. Returns a disposer that removes it. */
-declare function registerContentHandler(entry: ContentHandlerEntry): () => void;
-
-/** Per-axis limits on a view's position. Any side may be left open. */
-interface PanBounds {
-    minX?: number;
-    maxX?: number;
-    minY?: number;
-    maxY?: number;
-}
-/** Momentum settings for a pan: how quickly a flung view slows, when it stops,
- *  and what happens at the pan limits. The `DecayLoopConfig` fields a caller
- *  chooses up front, without the per-gesture `velocity` / `onTick`. */
-interface InertiaConfig {
-    friction?: number;
-    minSpeed?: number;
-    /** What to do when inertial pan reaches `bounds`. Default: no clamping. */
-    boundary?: 'stop' | 'bounce' | 'spring';
-    /** View-coordinate limits for boundary clamping. Requires `boundary` to take effect. */
-    bounds?: PanBounds;
-}
-/** How a decay should run: its starting velocity, how fast it slows, and what
- *  happens if it reaches the pan limits. */
-interface DecayLoopConfig {
-    velocity: {
-        vx: number;
-        vy: number;
-    };
-    friction?: number;
-    minSpeed?: number;
-    /** Bounds for boundary clamping. Requires `boundary` to take effect. */
-    viewBounds?: PanBounds;
-    /**
-     * What to do when the accumulated position hits `viewBounds`. Default: no clamping.
-     * - `'stop'`: clamp at boundary, kill velocity component.
-     * - `'bounce'`: linear reflection — flip velocity sign, magnitude preserved.
-     * - `'spring'`: damped reflection — flip velocity sign and shrink magnitude
-     *   by `SPRING_DAMPING` per bounce so the motion settles naturally.
-     */
-    boundary?: 'stop' | 'bounce' | 'spring';
-    /** Starting position for internal boundary tracking. Required when `viewBounds` is set. */
-    initialPosition?: {
-        x: number;
-        y: number;
-    };
-    onTick: (dx: number, dy: number) => void;
-    onEnd?: () => void;
-}
-/** A rAF loop that coasts a value to a stop under friction, reporting the
- *  per-frame delta. What turns a released pan drag into momentum scrolling. */
-declare function useDecayLoop(): {
-    start: (config: DecayLoopConfig) => void;
-    cancel: () => void;
-};
-
-/** Which of a node's two per-anchor color arrays an override applies to. */
-type VertexColorChannel = 'fill' | 'stroke';
-/** Function-form override: receives the consumer-supplied base color
- *  array and the current animation timestamp (ms, from the animator's
- *  clock). Returns a flat RGBA float array (values in 0..1, matching
- *  the renderer's `stroke.vertexColors` / `PathDrawCommand.vertexColors`
- *  color space) of the same length as `base`. */
-type ColorOverrideFn = (base: readonly number[], tMs: number) => number[];
-/** Either a static per-anchor RGBA float array (0..1) or a function-form
- *  override (see {@link ColorOverrideFn}). */
-type ColorOverride = readonly number[] | ColorOverrideFn;
-/** Per-node, per-channel store of color overrides consulted by `createPathLayer`
- *  before falling back to the consumer's `getVertexColors` / `getStrokeVertexColors`
- *  accessor. Attached to `useAnimator` as `animator.colorOverrides`. */
-declare class ColorOverrideRegistry {
-    private readonly map;
-    private _version;
-    set(id: string, channel: VertexColorChannel, override: ColorOverride): void;
-    clear(id: string, channel: VertexColorChannel): void;
-    clearAll(): void;
-    get(id: string, channel: VertexColorChannel): ColorOverride | undefined;
-    version(): number;
-}
-
-/** One keyframe. `easing` shapes the approach INTO this key from the previous
- *  one, so the first key's easing is never consulted. */
-interface Keyframe<T> {
-    /** Time within the track's timeline, in ms. */
-    t: number;
-    value: T;
-    /** A function, the name of a built-in, or cubic-bezier control points. */
-    easing?: EasingSpec;
-}
-/** A track sampled as a pure function of the playhead. Scrubbing one is free
- *  and order-independent. */
-interface SampledTrack<T> {
-    kind: 'sampled';
-    label?: string;
-    /** Sorted ascending by `t`. `sampleTrack` assumes this and does not sort. */
-    keys: Keyframe<T>[];
-    /** Required when T is not `number`; defaults to numeric lerp otherwise. */
-    interpolate?: Interpolate<T>;
-    /** Built once per segment and cached. Takes precedence over `interpolate`. */
-    interpolator?: InterpolatorFactory<T>;
-    onTick: (value: T) => void;
-}
-/** A track of edge crossings. Fires only when the playhead advances forward
- *  under playback — never on `seek`. */
-interface EventTrack {
-    kind: 'event';
-    label?: string;
-    /** Sorted ascending by `t`. `fire` is told how far behind the frame its edge
-     *  was crossed, in ms — never negative, and measured against `duration` on
-     *  the loop seam, where the outgoing lap's tail fires after the wrap. */
-    events: {
-        t: number;
-        fire: (lateBy: number) => void;
-    }[];
-}
-/** A nested timeline, evaluated at `playhead - at`. Children are NOT registered
- *  with the animator separately; the parent evaluates them. */
-interface TimelineTrack {
-    kind: 'timeline';
-    label?: string;
-    at: number;
-    timeline: NestedTimeline;
-}
-type Track = SampledTrack<any> | EventTrack | TimelineTrack;
-/** What a child timeline may declare. The parent owns playback, so `loop`,
- *  `autoplay`, `onDone` and `cancelKey` have no meaning below the root. */
-interface NestedTimeline {
-    tracks: Track[];
-    /** Defaults to the largest end time across `tracks`. */
-    duration?: number;
-}
-interface TimelineOptions extends NestedTimeline {
-    /** `true` loops forever, `n` loops n additional times. Default false. */
-    loop?: boolean | number;
-    /** Default true. When false the timeline registers but holds at t=0 until resumed. */
-    autoplay?: boolean;
-    onDone?: () => void;
-    cancelKey?: string;
-}
-interface TimelineHandle extends AnimationHandle {
-    /** Move the playhead. Never fires event tracks, at any depth. */
-    seek(t: number): void;
-    /** Change the loop policy. `true` loops forever, `n` allows n more laps,
-     *  `false` stops at `duration`. Sets policy only — a timeline already parked
-     *  at `duration` does not restart, because `rearm` declines to revive one.
-     *  Rewind it with `seek(0)` and `resume()` to play it again. */
-    setLoop(loop: boolean | number): void;
-    /** The loop policy as it now stands: `true` endless, `false` stopping at
-     *  `duration`, `n` for n laps still allowed. A finite count falls as laps
-     *  are consumed, matching what `setLoop` takes. */
-    loop(): boolean | number;
-    /** Current playhead in ms. */
-    time(): number;
-    duration(): number;
-    tracks(): readonly Track[];
-    /** Run `fn`, then recompute duration, drop cached interpolators, and notify.
-     *  Every mutation must go through this — an edited keyframe otherwise keeps
-     *  interpolating toward its old value with no visible error. */
-    edit(fn: () => void): void;
-    /** Notified after each `edit`. Returns an unsubscribe. */
-    subscribe(cb: () => void): () => void;
-}
-
-/** No easing: constant rate from start to finish. */
-declare const linear: EasingFn;
-/** Accelerates from a standstill, gently. */
-declare const easeInQuad: EasingFn;
-/** Decelerates to a stop, gently. The safe default for UI motion. */
-declare const easeOutQuad: EasingFn;
-/** Accelerates then decelerates, gently. */
-declare const easeInOutQuad: EasingFn;
-/** Accelerates from a standstill, moderately. */
-declare const easeInCubic: EasingFn;
-/** Decelerates to a stop, moderately. */
-declare const easeOutCubic: EasingFn;
-/** Accelerates then decelerates, moderately. */
-declare const easeInOutCubic: EasingFn;
-/** Accelerates from a standstill, sharply. */
-declare const easeInQuart: EasingFn;
-/** Decelerates to a stop, sharply. */
-declare const easeOutQuart: EasingFn;
-/** Accelerates then decelerates, sharply. */
-declare const easeInOutQuart: EasingFn;
-/** Accelerates from a standstill, very sharply. */
-declare const easeInQuint: EasingFn;
-/** Decelerates to a stop, very sharply. */
-declare const easeOutQuint: EasingFn;
-/** Accelerates then decelerates, very sharply. */
-declare const easeInOutQuint: EasingFn;
-/** Accelerates from a standstill along a sine curve — the mildest
- *  acceleration of the built-ins. */
-declare const easeInSine: EasingFn;
-/** Decelerates to a stop along a sine curve — the mildest
- *  deceleration of the built-ins. */
-declare const easeOutSine: EasingFn;
-/** Accelerates then decelerates along a sine curve. */
-declare const easeInOutSine: EasingFn;
-/** Accelerates exponentially: barely moves at first, then rushes. */
-declare const easeInExpo: EasingFn;
-/** Decelerates exponentially: leaps away, then creeps in. */
-declare const easeOutExpo: EasingFn;
-/** Exponential at both ends — a very fast middle between two
- *  near-still extremes. */
-declare const easeInOutExpo: EasingFn;
-/** Accelerates along a circular arc: slow start, abrupt arrival. */
-declare const easeInCirc: EasingFn;
-/** Decelerates along a circular arc: abrupt start, slow arrival. */
-declare const easeOutCirc: EasingFn;
-/** Circular arcs at both ends. */
-declare const easeInOutCirc: EasingFn;
-/** Pulls back past the start before moving forward. Overshoots below 0. */
-declare const easeInBack: EasingFn;
-/** Overshoots the target, then settles back onto it. Exceeds 1. */
-declare const easeOutBack: EasingFn;
-/** Overshoots at both ends. Leaves the 0–1 range on each side. */
-declare const easeInOutBack: EasingFn;
-/** Oscillates around the start with growing amplitude, then snaps away. */
-declare const easeInElastic: EasingFn;
-/** Springs past the target and wobbles into it. Exceeds 1. */
-declare const easeOutElastic: EasingFn;
-/** Wobbles at both ends. Leaves the 0–1 range on each side. */
-declare const easeInOutElastic: EasingFn;
-/** Lands on the target and bounces, in hops of decreasing height. */
-declare const easeOutBounce: EasingFn;
-/** Bounces up to the start before departing — `easeOutBounce` reversed. */
-declare const easeInBounce: EasingFn;
-/** Bounces at both ends. */
-declare const easeInOutBounce: EasingFn;
-/** Alias for `easeInQuad`, kept for call sites that predate the
- *  named-curve library. */
-declare const easeIn: EasingFn;
-/** Alias for `easeOutQuad`, kept for call sites that predate the
- *  named-curve library. */
-declare const easeOut: EasingFn;
-/** Alias for `easeInOutQuad`, kept for call sites that predate the
- *  named-curve library. */
-declare const easeInOut: EasingFn;
-/** All easings in one bag — useful for demos / pickers. */
-declare const EASINGS: {
-    readonly linear: EasingFn;
-    readonly easeInQuad: EasingFn;
-    readonly easeOutQuad: EasingFn;
-    readonly easeInOutQuad: EasingFn;
-    readonly easeInCubic: EasingFn;
-    readonly easeOutCubic: EasingFn;
-    readonly easeInOutCubic: EasingFn;
-    readonly easeInQuart: EasingFn;
-    readonly easeOutQuart: EasingFn;
-    readonly easeInOutQuart: EasingFn;
-    readonly easeInQuint: EasingFn;
-    readonly easeOutQuint: EasingFn;
-    readonly easeInOutQuint: EasingFn;
-    readonly easeInSine: EasingFn;
-    readonly easeOutSine: EasingFn;
-    readonly easeInOutSine: EasingFn;
-    readonly easeInExpo: EasingFn;
-    readonly easeOutExpo: EasingFn;
-    readonly easeInOutExpo: EasingFn;
-    readonly easeInCirc: EasingFn;
-    readonly easeOutCirc: EasingFn;
-    readonly easeInOutCirc: EasingFn;
-    readonly easeInBack: EasingFn;
-    readonly easeOutBack: EasingFn;
-    readonly easeInOutBack: EasingFn;
-    readonly easeInElastic: EasingFn;
-    readonly easeOutElastic: EasingFn;
-    readonly easeInOutElastic: EasingFn;
-    readonly easeInBounce: EasingFn;
-    readonly easeOutBounce: EasingFn;
-    readonly easeInOutBounce: EasingFn;
-};
-/** The name of one of the built-in easing curves. */
-type EasingName = keyof typeof EASINGS;
-/** Named spring tunings, from softest to firmest. Springs settle on a target
- *  rather than running for a fixed duration, so these are an alternative to an
- *  easing curve, not a modifier on one. */
-declare const SPRING_PRESETS: Record<SpringPresetName, SpringPreset>;
-
-/** Cubic-bezier control points, CSS `cubic-bezier()` order. The curve's two
- *  endpoints are implicit at (0,0) and (1,1). */
-interface BezierEasing {
-    /** `readonly` so an `as const` preset is assignable; nothing ever writes it. */
-    bezier: readonly [number, number, number, number];
-}
-/** An easing curve as a value: a function, the name of a built-in, or control
- *  points. Anything an editor has to name, show or serialize must not be a bare
- *  function, which is why the union exists. */
-type EasingSpec = EasingFn | EasingName | BezierEasing;
-/** Build the easing curve for four cubic-bezier control points. `x1`/`x2` are
- *  clamped to [0,1] — CSS `cubic-bezier()`'s constraint for a monotone x(t),
- *  which both `solveForX` root-finders assume. `y1`/`y2` are unclamped: an
- *  overshoot easing (back, elastic) needs them outside 0..1. */
-declare function cubicBezierEasing(x1: number, y1: number, x2: number, y2: number): EasingFn;
-/** Resolve a spec to the function that shapes progress. `undefined` is linear. */
-declare function resolveEasing(spec?: EasingSpec): EasingFn;
-
-/** An easing curve: maps normalized progress `t ∈ [0, 1]` to eased progress.
- *  Curves may leave the 0–1 range in the middle (back, elastic) but should
- *  pass through 0 at 0 and 1 at 1. */
-type EasingFn = (t: number) => number;
-
-/** Blends two `T` values at eased progress `t`. Called once per frame; see
- *  {@link InterpolatorFactory} when the blend has setup worth hoisting. */
-type Interpolate<T> = (from: T, to: T, t: number) => T;
-/** Factory interpolator: built ONCE at tween start with (from, to), the returned
- *  function is called with `t ∈ [0, 1]` each frame. Use for interpolators with
- *  expensive setup (color-space conversion, path-string parsing) — d3-interpolate's
- *  shape exactly. For cheap interpolations the per-tick `Interpolate<T>` form is
- *  fine; this is the escape hatch when setup-per-tick is wasteful. */
-type InterpolatorFactory<T> = (from: T, to: T) => (t: number) => T;
-/** A spring's physical parameters. Higher stiffness settles faster, higher
- *  damping overshoots less, higher mass makes both sluggish. */
-interface SpringPreset {
-    stiffness: number;
-    damping: number;
-    mass: number;
-}
-/** One of the tunings in `SPRING_PRESETS`. */
-type SpringPresetName = 'gentle' | 'wobbly' | 'stiff' | 'slow';
-/** A running animation. Cancel it, or bend its time — pausing and time-scaling
- *  act on this animation's own virtual clock, independent of the animator's. */
-interface AnimationHandle {
-    /** Monotonic id assigned by the animator. */
-    id: number;
-    /** Cancel this animation. Idempotent — no-op once already finished/canceled. */
-    cancel(): void;
-    /** Freeze this animation's virtual clock. Idempotent. */
-    pause(): void;
-    /** Resume this animation's virtual clock. Idempotent. */
-    resume(): void;
-    /** Multiply this animation's virtual-clock rate by `scale`. 1 = normal. */
-    setTimeScale(scale: number): void;
-    /** This animation's own time scale. 1 once it has finished, since the
-     *  animator no longer holds an entry to read. */
-    timeScale(): number;
-    /** True iff this handle is currently paused. */
-    isPaused(): boolean;
-}
-/** A duration-based animation from `from` to `to` over `ms`, shaped by an
- *  easing curve. Reach for a spring instead when the motion should respond to
- *  where the value already is rather than restart from a fixed duration. */
-interface TweenOptions<T> {
-    from: T;
-    to: T;
-    ms: number;
-    easing?: EasingSpec;
-    /** Required when T is not `number`. For T = number, defaults to linear numeric lerp.
-     *  Called per-tick with `(from, to, t)`. For interpolators with expensive setup,
-     *  prefer `interpolator` which is built once at tween start. */
-    interpolate?: Interpolate<T>;
-    /** Factory interpolator built once at tween start. Takes precedence over
-     *  `interpolate` when both are provided. Use this for d3-interpolate or any
-     *  `(from, to) => (t) => v` shape. */
-    interpolator?: InterpolatorFactory<T>;
-    onTick: (value: T) => void;
-    onDone?: () => void;
-    /** Any new animation passed the same cancelKey cancels the prior one in flight. */
-    cancelKey?: string;
-}
-/** A spring animation: runs until the value settles on `to` rather than for a
- *  set duration, so it absorbs an initial velocity naturally. Non-numeric `T`
- *  needs the four vector helpers. */
-interface SpringOptions<T> {
-    from: T;
-    to: T;
-    /** Initial velocity in T-units per second. Default: zero (T-shape-aware). */
-    velocity?: T;
-    preset?: SpringPresetName;
-    stiffness?: number;
-    damping?: number;
-    mass?: number;
-    interpolate?: Interpolate<T>;
-    /** Vector helpers — required for non-numeric T. */
-    add?: (a: T, b: T) => T;
-    subtract?: (a: T, b: T) => T;
-    scale?: (v: T, k: number) => T;
-    magnitude?: (v: T) => number;
-    /** Velocity magnitude below which the spring is considered settled. Default 0.01. */
-    restThreshold?: number;
-    onTick: (value: T) => void;
-    onDone?: () => void;
-    cancelKey?: string;
-}
-/** Spring and decay as one animation. With a `to`, a spring pulls toward it;
- *  with `to: null`, the value coasts on its velocity. Either can become the
- *  other mid-flight through the handle. */
-interface PhysicsOptions<T> {
-    from: T;
-    /** Target. `null` ⇒ no spring force (decay-mode). */
-    to?: T | null;
-    /** Initial velocity in T-units per second. */
-    velocity?: T;
-    preset?: SpringPresetName;
-    stiffness?: number;
-    damping?: number;
-    mass?: number;
-    restThreshold?: number;
-    /** Vector helpers — required for non-numeric T. */
-    add?: (a: T, b: T) => T;
-    subtract?: (a: T, b: T) => T;
-    scale?: (v: T, k: number) => T;
-    magnitude?: (v: T) => number;
-    onTick: (value: T) => void;
-    onDone?: () => void;
-    cancelKey?: string;
-}
-/** An `AnimationHandle` that can also be steered while it runs — the point of
- *  the physics primitive. */
-interface PhysicsHandle<T = unknown> extends AnimationHandle {
-    /** Retarget mid-flight. `null` ⇒ switch to decay-mode (no spring force). */
-    setTarget(to: T | null): void;
-    /** Replace the current velocity in T-units per second. */
-    setVelocity(v: T): void;
-}
-/** Momentum: coast from `from` at `velocity`, slowing by `friction` each
- *  second until below `threshold`. What a flick-to-pan leaves behind. */
-interface DecayOptions<T> {
-    from: T;
-    velocity: T;
-    /** Per-second velocity multiplier in (0, 1). Default 0.95. */
-    friction?: number;
-    /** Velocity magnitude below which decay stops. Default 0.5. */
-    threshold?: number;
-    add: (a: T, b: T) => T;
-    scale: (v: T, k: number) => T;
-    magnitude: (v: T) => number;
-    onTick: (value: T) => void;
-    onDone?: () => void;
-    cancelKey?: string;
-}
-/** Options for `useAnimator`. Everything here is an injection seam for tests;
- *  the defaults are the real clock, rAF, and `setTimeout`. */
-interface UseAnimatorOptions {
-    /** Optional clock injection for tests. Returns ms since some epoch. */
-    now?: () => number;
-    /** Optional rAF / cAF injection for tests. Defaults to window.requestAnimationFrame. */
-    requestFrame?: (cb: (t: number) => void) => number;
-    cancelFrame?: (handle: number) => void;
-    /** Optional `setTimeout` injection used by `stagger` for per-item delays.
-     *  Defaults to the global `setTimeout`. Tests inject a virtual scheduler. */
-    setTimer?: (cb: () => void, ms: number) => unknown;
-    /** Companion to `setTimer`. Defaults to global `clearTimeout`. */
-    clearTimer?: (handle: unknown) => void;
-}
-/**
- * Owns every running animation on a canvas and drives them from one rAF loop.
- * Beyond the primitives (`tween`, `spring`, `decay`, `physics`) it offers
- * composition — `loop`, `stagger` — and bulk control by handle, by cancel-key,
- * or over everything at once.
- *
- * An animator does not know about the scene: animations report values through
- * `onTick` and the caller decides what to do with them.
- */
-interface Animator {
-    tween<T>(opts: TweenOptions<T>): AnimationHandle;
-    spring<T>(opts: SpringOptions<T>): AnimationHandle;
-    decay<T>(opts: DecayOptions<T>): AnimationHandle;
-    /** Unified spring/decay primitive. With `to` set, behaves as a spring;
-     *  with `to: null`, behaves as a velocity-driven decay. Supports
-     *  mid-flight retargeting via the returned handle's `setTarget`. */
-    physics<T>(opts: PhysicsOptions<T>): PhysicsHandle<T>;
-    /** Cancel a specific animation by handle. Pose stays at current value (no jump). */
-    cancel(handle: AnimationHandle): void;
-    /** Cancel every animation currently active under `key`. */
-    cancelKey(key: string): void;
-    /** Cancel everything. Useful from a destructor or "reset scene" path. */
-    cancelAll(): void;
-    /** True iff at least one animation is active. With `key`, scoped to that cancelKey. */
-    isActive(key?: string): boolean;
-    /**
-     * True while the animator is currently executing an animation tick. Useful
-     * for adapter wrappers (e.g. `animateOnSetPose`) that need to detect
-     * "this `setPose` was called from inside another animation's onTick"
-     * (momentum decay, in-flight tween, spring) and avoid recursively
-     * scheduling a new wrap-animation that would fight the caller.
-     */
-    isTicking(): boolean;
-    /** Freeze every animation managed by this animator. */
-    pause(): void;
-    /** Resume every animation managed by this animator. */
-    resume(): void;
-    /** True iff the animator is currently globally paused. */
-    isPaused(): boolean;
-    /** Multiply every animation's virtual-clock rate by `scale`. 1 = normal. */
-    setTimeScale(scale: number): void;
-    /** The global time scale. Per-animation scales multiply on top of it. */
-    timeScale(): number;
-    /** Freeze every animation whose `cancelKey` matches. */
-    pauseKey(key: string): void;
-    /** Resume every animation whose `cancelKey` matches. */
-    resumeKey(key: string): void;
-    /** Set per-animation timeScale for every animation whose `cancelKey` matches. */
-    setTimeScaleByKey(key: string, scale: number): void;
-    /**
-     * Loop primitive: repeatedly invoke `factory` to produce a child animation.
-     * The factory must wire its returned handle's `onDone` to call `next` so
-     * the loop advances. Returns a handle whose pause/resume/setTimeScale/cancel
-     * delegate to the current in-flight child (and prevent future iterations
-     * on cancel).
-     *
-     * The loop is registered with the animator under a supervisor entry so
-     * `animator.cancel(handle)`, `animator.cancelKey(opts.cancelKey)`, and
-     * `animator.isActive(opts.cancelKey)` all work for it.
-     */
-    loop(factory: LoopFactory, opts?: LoopOptions): AnimationHandle;
-    /** Sugar over `loop` for the common case of looping a tween between two
-     *  values with optional direction handling (`restart` | `reverse` |
-     *  `alternate`). Registered with the animator like `loop`. */
-    tweenLoop<T>(opts: TweenLoopOptions<T>): AnimationHandle;
-    /**
-     * Stagger primitive: schedule a per-item animation, offset by `delay` ms
-     * per index (or a custom function of the index). Two forms:
-     *   - Factory form: pass `factory` directly, returns a composite
-     *     `AnimationHandle`.
-     *   - Builder form: omit `factory`, get a `StaggerBuilder` for fluent
-     *     `.each` / `.tween` / `.springPose` calls.
-     *
-     * The composite handle's `cancel` cancels pending timers AND in-flight
-     * children. `pause` / `resume` / `setTimeScale` propagate to in-flight
-     * children; `pause`/`resume` also freeze and thaw pending per-item timers
-     * (the remaining time before each pending fire is preserved across the
-     * pause).
-     *
-     * The stagger is registered with the animator under a supervisor entry so
-     * `animator.cancel(handle)`, `animator.cancelKey(opts.cancelKey)`, and
-     * `animator.isActive(opts.cancelKey)` all work for it.
-     */
-    stagger<TItem>(items: readonly TItem[], delay: StaggerDelay): StaggerBuilder<TItem>;
-    stagger<TItem>(items: readonly TItem[], delay: StaggerDelay, factory: StaggerFactory<TItem>, opts?: StaggerOptions): AnimationHandle;
-    /**
-     * Keyframe timeline. Registered like any other animation, so its playhead
-     * responds to `pause`, `setTimeScale` and `cancelKey`. Sampled tracks are a
-     * pure function of the playhead; event tracks fire only on forward playback.
-     */
-    timeline(opts: TimelineOptions): TimelineHandle;
-    /** Per-node, per-channel color override registry consulted by the renderer's
-     *  path layer before reading consumer accessors. Used by `tweenVertexColors`,
-     *  `springVertexColors`, `cycleVertexColors`, `staggerVertexColors`. Cleared
-     *  automatically on animator unmount. */
-    colorOverrides: ColorOverrideRegistry;
-    /**
-     * Subscribe to a callback fired once per RAF frame while any animation is
-     * active. Returns an unsubscribe function. Used by consumers (typically
-     * `<SceneCanvas>`) that need to repaint when an animation's side-effect
-     * is read from a non-scene channel (e.g. `colorOverrides` consulted from
-     * a custom `drawOne`) — scene mutations naturally trigger a repaint, but
-     * `colorOverrides` writes do not.
-     *
-     * The callback fires AFTER the per-frame tick of each registered
-     * animation, so by the time it runs `colorOverrides.get(...)` returns
-     * the latest values. If no animations are active, no tick fires.
-     */
-    onTick(cb: () => void): () => void;
-    /**
-     * Keep the animator's RAF loop running until the returned cancel
-     * function is called. Use for animations whose effect is read on every
-     * frame but which don't have a natural progress state (e.g.
-     * `cycleVertexColors`, which expresses its current value as a function
-     * of `performance.now()` rather than as a tween from `from` to `to`).
-     * Without a keep-alive entry the loop would idle and `onTick` would
-     * stop firing even though the override is still installed.
-     */
-    keepAlive(): () => void;
-}
-/** Options for `Animator.loop`. */
-interface LoopOptions {
-    /** Maximum number of iterations. Default Infinity. */
-    count?: number;
-    /** Invoked when the loop reaches `count` iterations naturally (not on cancel). */
-    onDone?: () => void;
-    /** Any new animation passed the same cancelKey cancels the prior one in flight.
-     *  Also enables `animator.cancelKey` / `animator.isActive(key)` for this loop. */
-    cancelKey?: string;
-}
-/** Options for the top-level `Animator.stagger` factory form (third overload). */
-interface StaggerOptions {
-    /** Cancel-key for the supervising registration. `animator.cancelKey(key)`
-     *  cancels the whole stagger; `animator.isActive(key)` returns true while
-     *  any timer or child is alive. */
-    cancelKey?: string;
-}
-/** Produces one iteration of a loop. Must arrange for `next` to be called when
- *  the animation it returns finishes, or the loop stalls after one pass. */
-type LoopFactory = (iteration: number, next: () => void) => AnimationHandle;
-/** Per-index delay schedule. Number ⇒ `index * delay` ms. Function ⇒ caller
- *  decides the absolute delay for each index (e.g. `i => i * i * 30`). */
-type StaggerDelay = number | ((index: number) => number);
-/** Produces the animation for one staggered item. */
-type StaggerFactory<TItem> = (item: TItem, index: number) => AnimationHandle;
-/** A `T` value or a function that derives one from the per-item context. Used
- *  by the fluent builder methods (`.tween`, `.springPose`) so each item can
- *  vary an option (e.g. `to: (_item, i) => (i + 1) * 10`). */
-type StaggerPerItem<T, TItem> = T | ((item: TItem, index: number) => T);
-/** Options for the stagger builder's `.tween`: a tween per item, where
- *  `from`, `to` and `ms` may each vary by item. */
-interface StaggerTweenOptions<T, TItem> {
-    from: StaggerPerItem<T, TItem>;
-    to: StaggerPerItem<T, TItem>;
-    ms: StaggerPerItem<number, TItem>;
-    easing?: EasingSpec;
-    interpolate?: Interpolate<T>;
-    onTick: (value: T, item: TItem, index: number) => void;
-    onDone?: (item: TItem, index: number) => void;
-}
-/** Options for the stagger builder's `.springPose`: the spring tuning, and
- *  whether each item's settle is recorded as an undoable op. */
-interface StaggerSpringPoseOptions<TPose> {
-    preset?: SpringPresetName;
-    stiffness?: number;
-    damping?: number;
-    mass?: number;
-    geometry?: PoseProjection<TPose>;
-    recordOp?: boolean;
-    opLabel?: string;
-}
-/** Fluent form of `Animator.stagger`: pick what to run per item after the
- *  items and the delay schedule are already fixed. */
-interface StaggerBuilder<TItem> {
-    /** Run an arbitrary per-item factory. */
-    each(factory: StaggerFactory<TItem>): AnimationHandle;
-    /** Sugar: per-item `animator.tween` with per-item-varying options. */
-    tween<T>(opts: StaggerTweenOptions<T, TItem>): AnimationHandle;
-    /** Sugar: per-item `springPose` against an adapter. `poseFn` returns the
-     *  target pose for each item. Each item must either be a primitive
-     *  (string/number) or expose a string `id` field — otherwise pose ids
-     *  would collide on `"[object Object]"` and successive tweens would
-     *  cancel each other. Throws on items that satisfy neither. */
-    springPose<TPose>(adapter: SceneAdapter<{
-        id: string;
-    }, TPose>, poseFn: (item: TItem, index: number) => TPose, opts?: StaggerSpringPoseOptions<TPose>): AnimationHandle;
-}
-/** Options for `Animator.tweenLoop` — a tween's options plus how each
- *  iteration relates to the last. */
-interface TweenLoopOptions<T> {
-    from: T;
-    to: T;
-    ms: number;
-    easing?: EasingSpec;
-    /** `restart` (default): from→to every iteration.
-     *  `reverse`: to→from every iteration.
-     *  `alternate`: even iterations from→to, odd iterations to→from. */
-    direction?: 'restart' | 'reverse' | 'alternate';
-    count?: number;
-    interpolate?: Interpolate<T>;
-    onTick: (value: T) => void;
-    onDone?: () => void;
-    cancelKey?: string;
-}
-
-/** Cancel-key prefix. Each hook instance appends its own id, so two runners
- *  sharing an animator do not cancel each other. */
-declare const VIEW_ANIMATION_KEY = "view";
-/** How the camera should move. */
-interface ViewAnimationOptions {
-    /** Duration in ms. Default 250. */
-    ms?: number;
-    /** Easing curve. Default `easeOutCubic`. */
-    easing?: EasingSpec;
-    /** Replace the kit's log-scale / fixed-anchor curve. */
-    interpolator?: InterpolatorFactory<View>;
-    /** Fires when the target is reached. Not called on cancel. */
-    onDone?: () => void;
-}
-/** Options accepted by {@link ViewAnimationApi.animateToBounds}. */
-interface AnimateToBoundsOptions extends FitViewToBoundsOptions, ViewAnimationOptions {
-}
-/** What the runner reads and writes. On `<SceneCanvas>` this is the same
- *  channel `view.set` uses, so a camera animation on an uncontrolled canvas
- *  costs no React render. */
-interface ViewChannel {
-    get(): View;
-    set(v: View): void;
-}
-/** The camera animation surface. One animation at a time. */
-interface ViewAnimationApi {
-    /** Glide from the live view to `to`. A thunk receives the pending target when
-     *  one is in flight, so successive discrete steps compound. */
-    animate(to: View | ((base: View) => View), opts?: ViewAnimationOptions): void;
-    /** `fitViewToBounds` composed with `animate`. */
-    animateToBounds(bounds: Bounds, dims: ViewportDims, opts?: AnimateToBoundsOptions): void;
-    /** Cancel. The view stays where it is — no jump to the target. */
-    stop(): void;
-    isAnimating(): boolean;
-    /** Where the in-flight animation is heading, or null when none is. */
-    target(): View | null;
-    /** Cancel unless the write that prompted this came from the runner's own
-     *  per-frame write. Feed it from every channel that can move the camera. */
-    stopIfExternal(): void;
-}
-/**
- * Animate the viewport `View`. Runs on the kit's {@link Animator} — pass one to
- * share a canvas's animator, or omit it and the hook makes its own.
- *
- * Every animation from one instance registers under that instance's cancel key,
- * so starting one cancels whatever *it* had in flight, and each starts from the
- * *live* view rather than a captured value — an interrupted camera never jumps.
- * Two instances on one animator are independent.
- */
-declare function useViewAnimation(view: ViewChannel, animator?: Animator): ViewAnimationApi;
-
-/**
- * @experimental
- * PointerContext — a tiny ambient context that publishes the world-space
- * position of the canvas pointer, refreshed on every `pointermove` over
- * the canvas. Cleared (set to `null`) on `pointerleave`.
- *
- * Why ref-based and not state-based: cursor moves fire dozens of times per
- * second; routing those through React state would re-render every consumer
- * in the tree. The context exposes a stable `pointerRef` whose `.current`
- * is mutated directly by the publisher, plus a thunk `getDropPoint()` that
- * reads it on demand. Consumers (e.g. `useClipboard`) pull via the thunk
- * inside their callbacks — no subscription, no re-render.
- *
- * `<SceneCanvas>` publishes automatically. `useClipboardOps` consumes when
- * the caller didn't pass an explicit `getDropPoint` option. Other future
- * hit-on-cursor consumers (drop-zone hover, context-menu anchor) can reuse
- * the same context.
- */
-
-/** @experimental World-space pointer position, or `null` when the pointer
- *  isn't over the publishing canvas. */
-type PointerWorldPos = {
-    worldX: number;
-    worldY: number;
-} | null;
-/** @experimental */
-interface PointerContextValue {
-    /** Live ref — mutate to publish, read for the latest snapshot. The
-     *  identity is stable for the lifetime of the provider. */
-    readonly pointerRef: MutableRefObject<PointerWorldPos>;
-    /** Convenience thunk equivalent to `() => pointerRef.current`. Stable
-     *  identity for the lifetime of the provider; safe to pass to hooks. */
-    readonly getDropPoint: () => PointerWorldPos;
-}
-/**
- * @experimental
- * Wrap the part of the React tree that should share a pointer-position
- * context. Usually placed at the demo / app root, alongside
- * `<ActionsProvider>` and `<SelectionContextProvider>`.
- *
- * Most consumers don't need to mount this directly — `<SceneCanvas>` mounts
- * an internal provider when no parent provider is in scope, so child hooks
- * (`useClipboard` without an explicit `getDropPoint`) read the canvas's
- * tracked pointer for free.
- */
-declare function PointerContextProvider({ children }: {
-    children: ReactNode;
-}): ReactNode;
-/** @experimental Read the surrounding pointer-context value, or `null` when
- *  no provider is in scope. */
-declare function usePointerContext(): PointerContextValue | null;
-
-/** Which tool is active, plus the stack of tools temporarily held active by a
- *  hotkey (space-for-hand and the like). The dispatcher reads this to decide
- *  whose bindings are in scope. */
-interface ActiveToolContextValue {
-    active: string;
-    hotkeyStack: string[];
-    setActive(id: string): void;
-    pushHotkey(id: string): void;
-    popHotkey(): void;
-}
-/** Props for `<ActiveToolContextProvider>`. */
-interface ActiveToolContextProviderProps {
-    children: ReactNode;
-    initialActive?: string;
-}
-/** Provides active-tool state for a canvas. `<SceneCanvas>` mounts one. */
-declare function ActiveToolContextProvider({ children, initialActive, }: ActiveToolContextProviderProps): react_jsx_runtime.JSX.Element;
-/** The active-tool state in scope. Throws outside a provider; use
- *  `useActiveToolContextOptional` where one is not guaranteed. */
-declare function useActiveToolContext(): ActiveToolContextValue;
-/**
- * Like `useActiveToolContext`, but returns `null` when no
- * `<ActiveToolContextProvider>` is in scope instead of throwing. Used by
- * `useStandardActions` to preserve its silent-no-op contract when no provider
- * is present.
- */
-declare function useOptionalActiveToolContext(): ActiveToolContextValue | null;
-/**
- * Conditional `<ActiveToolContextProvider>` wrapper. Mounts a provider only
- * when no parent provider is in scope — otherwise renders children unwrapped
- * so callers (e.g. `<WeaselProvider>`, `<SceneCanvas>`) defer to the host's
- * existing scope. Mirrors `ActionsProviderIfRoot` / `DepRegistryProviderIfRoot`.
- */
-declare function ActiveToolContextProviderIfRoot({ children, }: {
-    children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-
-/**
- * `enterTextEditAction` — immediate Action descriptor for entering in-place
- * text editing on a selected text node.
- *
- * ## Status: REAL
- *
- * Fires via `useTextTool.bindings` when the user clicks on a
- * selected text node. Calls `deps.textEdit.startEdit(id)` to activate the
- * contenteditable overlay managed by `useTextEdit` / `useSceneTextEdit`.
- *
- * ## No defaultBinding / defaultBinding
- *
- * This action has no ambient key or gesture binding — it fires ONLY via
- * `useTextTool`'s `Tool.bindings` entry:
- *
- * ```ts
- * bindings: [
- *   { spec: { kind: 'click', target: 'selected-body' }, actionId: 'enterTextEdit' },
- * ]
- * ```
- *
- * Keeping it binding-free avoids ambient double-fire and scopes the action to
- * the text tool context where `classifyTarget` is already wired.
- *
- * ## Self-guard: only act on text nodes
- *
- * The `'selected-body'` target yields a match for any selected node kind. To
- * avoid entering text-edit mode when the text tool happens to have a non-text
- * node selected, the action self-guards via an optional `isTextNode` predicate
- * on `TextEditDep`:
- *
- * - When `isTextNode` is absent: action fires unconditionally (the binding
- *   spec is the real gate — consumers should only bind this action from the
- *   text tool).
- * - When `isTextNode(id)` returns `false`: action is a no-op for that node.
- *
- * ### Pre-filtering at dispatch time
- *
- * `classifyTarget` now surfaces node kind, so a binding can pre-filter instead
- * of relying on the self-guard:
- *
- * ```ts
- * { spec: { kind: 'click', target: 'kind:text:selected' }, actionId: 'enterTextEdit' }
- * ```
- *
- * That reads the *routing trait's* kind, so it matches whatever names the
- * consumer registered in `<SceneCanvas routing>` — `'text'` under the kit's
- * inferred default. `isTextNode` stays on `TextEditDep` because it also covers
- * consumers who bind the broader `'selected-body'` target, and because it is
- * the only guard for a consumer who opted out of routing entirely.
- *
- * ## Migration plan for useTextTool
- *
- * When wiring `useTextTool` to `Tool.bindings`:
- *
- * 1. Add to `useTextTool`'s `bindings`:
- *    ```ts
- *    { spec: { kind: 'click', target: 'selected-body' }, actionId: 'enterTextEdit' }
- *    ```
- * 2. Register a `textEdit` dep sourced from the `useTextEdit` / `useSceneTextEdit`
- *    return value, plus an `isTextNode` predicate that checks `data.kind === 'text'`
- *    (or however the consumer identifies text nodes).
- * 3. The existing `hitExisting` gate in `useTextTool`'s click route becomes
- *    redundant — remove it in the same pass.
- */
-
-/**
- * Dep for `enterTextEditAction`.
- *
- * Wrap the return value of `useTextEdit` / `useSceneTextEdit` to source this
- * dep. The `isTextNode` predicate is optional — when absent the action fires
- * unconditionally (the binding spec acts as the gate).
- *
- * @example
- * ```ts
- * const textEdit = useSceneTextEdit({ scene, container });
- * useDepSource('textEdit', () => ({
- *   startEdit: textEdit.startEdit,
- *   isTextNode: (id) => scene.get(id as NodeId)?.data?.kind === 'text',
- * }));
- * ```
- */
-interface TextEditDep {
-    /**
-     * Begin editing the node with `id`. Activates the contenteditable overlay
-     * managed by `useTextEdit` / `useSceneTextEdit`.
-     */
-    startEdit(id: string, opts?: {
-        caret?: number | 'all';
-    }): void;
-    /**
-     * Optional predicate: returns `true` when the node with `id` is a text node.
-     * When absent the action fires on any selected node (binding spec is the gate).
-     * When present and returning `false`, the invocation is a no-op.
-     */
-    isTextNode?(id: string): boolean;
-}
-/**
- * @experimental
- * Static descriptor for the `enterTextEdit` Action.
- *
- * Requires dep-schema entries: `textEdit`, `selection`.
- *
- * No `defaultBinding` / `defaultBinding` — fires only via `Tool.bindings`.
- * Self-guards via `TextEditDep.isTextNode` when provided.
- */
-declare const enterTextEditAction: Action & {
-    requires: string[];
-};
-
-/**
- * Consumer-supplied commit for the Slice action. `commit` receives the finite
- * slice segment (world coords); the consumer scans the scene, splits crossed
- * paths via `splitPathByLine`, and applies the result as one undoable batch.
- */
-interface SliceDep {
-    commit(a: Point2, b: Point2): void;
-}
-/**
- * @experimental
- * Static descriptor for the `slice` Action.
- *
- * Ongoing drag invoker: tracks a slice line from drag start to current
- * pointer, renders a live line overlay while the gesture is in flight,
- * and on commit calls `SliceDep.commit(a, b)`. No-ops gracefully when
- * the `slice` dep is absent.
- */
-declare const sliceAction: Action & {
-    requires: string[];
-};
-
-/**
- * Clipboard dep — the imperative surface `useClipboardOps` returns.
- *
- * Consumers publish their live clipboard through `useDepSource('clipboard',
- * …)` from inside the `<DepRegistryProvider>` (i.e. under `<SceneCanvas>`).
- * The kit deliberately does not build one for them: `useClipboardOps` needs
- * an adapter and a selection reader that only the consumer can supply.
- */
-interface ClipboardDep {
-    copy(): void;
-    paste(): void;
-    isEmpty(): boolean;
-}
-/**
- * @experimental
- * Static descriptor for the `clipboard.copy` Action (Cmd/Ctrl+C).
- */
-declare const clipboardCopyAction: Action & {
-    requires: string[];
-};
-/**
- * @experimental
- * Static descriptor for the `clipboard.cut` Action (Cmd/Ctrl+X) — copy, then
- * the same batched delete `deleteAction` performs, as one undo entry.
- */
-declare const clipboardCutAction: Action & {
-    requires: string[];
-};
-
-/** Optional consumer seam: given a node and the affine `m` that a pose-transform
- *  action applied to the node's POSE, return updated `data` with the node's
- *  data-held geometry transformed by `m`, or `null` if this node has no
- *  data-held geometry (the kit leaves `data` alone). */
-interface GeometryProjection {
-    transform(node: {
-        id?: string;
-        data: unknown;
-        pose: unknown;
-    }, m: Mat3): unknown | null;
-}
-
-/** Minimal view API the action layer consumes. */
-interface ViewApi {
-    get(): View;
-    set(v: View): void;
-    /** Optional recenter callback. When wired, `viewportZoomAction`'s `reset`
-     *  branch (Cmd-0) calls this instead of resetting to identity — letting
-     *  consumers re-fit the page (or other reference bounds) into the workspace.
-     *  Return the target `View` to let the action animate there; return nothing
-     *  to keep dispatching the view yourself. */
-    recenter?(): View | void;
-    /** Optional canvas-local host dimensions (CSS px). When wired,
-     *  `viewportZoomAction`'s keyboard branches (Cmd+= / Cmd+-) anchor at the
-     *  host center instead of the top-left origin. Null when the host isn't
-     *  measurable (unmounted). */
-    hostSize?(): {
-        width: number;
-        height: number;
-    } | null;
-    /** Optional camera animation. `<SceneCanvas>` wires these three; a consumer
-     *  publishing their own `view` dep need not, and actions fall back to `set`. */
-    animate?(to: View, opts?: ViewAnimationOptions): void;
-    stopAnimation?(): void;
-    /** Where an in-flight camera animation is heading, or null. Compute the next
-     *  discrete step from this so repeated presses compound. */
-    animationTarget?(): View | null;
-    /** Optional momentum decay. `<SceneCanvas>` wires this from `useDecayLoop`;
-     *  a consumer publishing their own `view` dep need not, and `viewport.dragPan`
-     *  simply lands the pan without coasting. */
-    decay?(config: DecayLoopConfig): void;
-    stopDecay?(): void;
-}
-/**
- * Adapter dep for `areaSelectAction`.
- *
- * Provided by `<SceneCanvas>` / `<StandardActionsRegistrar>` via AABB
- * overlap over scene nodes. Consumers with custom hit-testing override this
- * dep entry in their own registrar.
- */
-/**
- * Topmost-node-at-world-point dep, consumed by `moveAction` for
- * reparent-on-drop and available to any action that needs a single-best
- * pick. Mirrors the same hit-test plumbing `<SceneCanvas>` feeds to the
- * tool dispatcher; consumers with custom hit-testing override here.
- *
- * `exclude` is iterated once per call and treated as a set membership
- * test — the dep walks hits front-to-back and returns the first id not
- * in the exclude set. Pass moving-node roots + their descendants when
- * the caller wants to ignore the nodes it's manipulating.
- */
-type NodeAtPointDep = (point: {
-    x: number;
-    y: number;
-}, exclude?: Iterable<NodeId>) => NodeId | null;
-/** What an area-selecting action needs: a way to ask what a region covers,
- *  and a way to read and replace the selection. */
-interface AreaSelectDep {
-    /** Return ids of all scene nodes whose AABB overlaps `bounds`. */
-    hitTestArea(bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }): NodeId[];
-    /** Return the current selection id list. */
-    getSelection(): NodeId[];
-    /** Replace the current selection. */
-    setSelection(ids: NodeId[]): void;
-}
-/**
- * Adapter dep for `editAnchorsAction`.
- *
- * Provides narrow read/write access to the editable polygon for a single
- * node. Consumers register this dep so anchor-edit actions can read/write
- * the polygon WITHOUT knowing whether it lives directly on the node's
- * pose (`pose.kind === 'polygon'`) or on `node.data.path` (the kit's
- * built-in pen-tool default, also WeaselDraw's shape).
- *
- * Note on live previews: in-flight edit state is surfaced through the
- * dispatcher's standard `OngoingHandle.previewIds/previewPose/previewData`
- * triple (not this dep), so chrome and preview-ghost stay in lock-step
- * via one source of truth.
- */
-interface EditAnchorsDep {
-    /** Id of the node currently being edited. Empty string means no node is
-     *  currently in edit mode — the chrome and gesture both opt out. */
-    editingId: string;
-    /** Enter/exit edit mode for a specific node. Pass `null` (or an empty
-     *  string) to exit. `enterPathEditAction` and `exitPathEditAction` call
-     *  this; consumers can call it directly to drive edit mode programmatically. */
-    setEditingId(id: string | null): void;
-    /** Returns the COMMITTED editable polygon in world coordinates, or
-     *  null if this node has no editable polygon. Does NOT consult in-
-     *  flight previews — callers that need live state read the dispatcher's
-     *  in-flight handles. */
-    getEditablePath(id: string): unknown;
-    /** Returns where the polygon is stored — `'pose'` when `node.pose`
-     *  IS the polygon, `'data'` when it lives on `node.data.path` with a
-     *  rect pose, or `null` when the node has no editable polygon. The
-     *  action uses this to know which preview-ghost axis to populate
-     *  (`previewPose` only / `previewData` + `previewPose` for data.path). */
-    getStorageKind(id: string): 'pose' | 'data' | null;
-    /** Returns the node's raw `pose` and `data` so storage-aware actions
-     *  can capture origin state at gesture-start and synthesize a matching
-     *  `previewPose` / `previewData` during `onMove`. Used by
-     *  `editAnchorsAction` for the data.path branch (rect pose + data
-     *  carrying extra fields like fill / stroke that must be preserved
-     *  through the preview). Returns null when the node is gone. */
-    getNodeShape(id: string): {
-        pose: unknown;
-        data: unknown;
-    } | null;
-    /** Commit `worldPath` as the new value for `id`. Implementation routes
-     *  to setPose (when pose IS the polygon) or batched setPose+update
-     *  (when the polygon lives on data.path). Records one history entry
-     *  labelled `label`. */
-    applyEdit(id: string, worldPath: unknown, label: string): void;
-    /**
-     * Anchors currently selected within the edited path, as **flat anchor
-     * indices** — the same numbering `enumerateAnchors` produces and the
-     * `anchor:N` affordance kinds carry.
-     *
-     * Selection is transient UI state, deliberately not part of the scene:
-     * it is cleared whenever `editingId` changes, and any edit that
-     * renumbers anchors (insert, delete) is responsible for leaving it
-     * coherent. Empty means "no anchor selected" — the keyboard actions
-     * (nudge, delete) no-op rather than acting on all anchors, matching
-     * Illustrator.
-     */
-    selectedAnchors: ReadonlySet<number>;
-    /** Replace the anchor selection. Pass an empty iterable to clear. */
-    setSelectedAnchors(next: Iterable<number>): void;
-    /**
-     * In-flight anchor-marquee rect in world coords, or null when no
-     * marquee drag is active. Written by `marqueeAnchorsAction` and read by
-     * the path-editing overlay — the same "ongoing action owns the preview,
-     * chrome just draws it" split the move/resize ghosts use.
-     */
-    marquee: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    } | null;
-    /** Set or clear the in-flight marquee rect. */
-    setMarquee(rect: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    } | null): void;
-}
-/**
- * Adapter dep for `lassoSelectAction`.
- *
- * Provides polygon-lasso hit-testing + selection read/write.
- * Consumers that don't implement `hitTestLasso` can omit it; the action
- * falls back to a bounding-box AABB test via `hitTestArea`.
- */
-interface LassoSelectDep {
-    /**
-     * Hit-test against a closed polygon (vertex order CW or CCW; last→first
-     * closing edge is implicit). Returns matching node ids.
-     * Optional — when absent, `lassoSelectAction` falls back to AABB via
-     * `hitTestArea`.
-     */
-    hitTestLasso?(polygon: ReadonlyArray<{
-        x: number;
-        y: number;
-    }>, mode: 'centers' | 'intersect' | 'enclosed'): string[];
-    /** Return ids of nodes whose AABB overlaps the given rect (fallback). */
-    hitTestArea(bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }): string[];
-    /** Return the current selection id list. */
-    getSelection(): string[];
-    /** Replace the current selection. */
-    setSelection(ids: string[]): void;
-}
-/**
- * Options for the kit `image/svg+xml` content handler, threaded from
- * SceneCanvas's `ingestion={{ svg }}` prop.
- */
-interface SvgIngestOptions {
-    /** Parse dropped/pasted/picked SVG files into native scene nodes (path /
-     *  text leaves under containers mirroring the source `<g>` structure)
-     *  instead of the default single embedded-image node.
-     *
-     *  Pass `unpackSvgFiles` from `@weasel-js/svg`:
-     *
-     *  ```ts
-     *  import { unpackSvgFiles } from '@weasel-js/svg';
-     *  <SceneCanvas ingestion={{ svg: { unpack: unpackSvgFiles } }} />
-     *  ```
-     *
-     *  It is injected rather than flagged on with `true` because the SVG parser
-     *  lives in `@weasel-js/svg`, which depends on this package — core importing
-     *  it back would make the two mutually dependent and unpublishable
-     *  separately. Passing the function keeps the parser out of core's bundle
-     *  for consumers who never unpack. */
-    unpack?: SvgUnpacker;
-}
-/** Parses SVG files and inserts the resulting nodes into `ctx.scene`, as one
- *  `applyOps` batch per file. Implemented by `unpackSvgFiles` in
- *  `@weasel-js/svg`; see {@link SvgIngestOptions.unpack}. */
-type SvgUnpacker = (files: File[], ctx: IngestCtx) => Promise<void>;
-/**
- * Clipboard-paste seam consumed by the kit weasel-JSON content handler
- * (`IngestCtx.clipboard`). Built by `<SceneCanvas>` from its own synthesized
- * adapter + the `ingestion.clipboard` prop; absent when the consumer set
- * `ingestion.clipboard.enabled === false` or the adapter lacks `commitPaste`.
- * Absence makes the handler decline inert (dwarn, nothing ingested) — its
- * matched items were already consumed at match time and do not fall through
- * to other handlers.
- */
-interface ClipboardIngestCtx {
-    /** The hosting canvas's adapter — `commitPaste` materializes the pasted
-     *  nodes (fresh ids, offset applied); insertion still goes through ops. */
-    adapter: InsertAdapter<{
-        id: string;
-    }>;
-    /** JSON reviver for the weasel wire payload (typed arrays etc.) — from
-     *  `SceneCanvasProps.ingestion.clipboard.reviver`. */
-    reviver?: (key: string, value: unknown) => unknown;
-}
-/**
- * Dep for the `ingest` action (external-content ingestion).
- * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>` via
- * `useIngestionDepSource` — canvas rect + current view.
- */
-interface IngestionDep {
-    /** Visible canvas area in world coordinates. */
-    viewportWorldRect(): {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-    /** Consumer file→src resolver (from SceneCanvas's `ingestion` prop).
-     *  Live accessor — read it at use time. Destructuring (or copying the
-     *  property early) snapshots the current value and won't track later
-     *  prop changes across an `await`. */
-    resolveSrc?: (file: File) => Promise<string>;
-    /** Kit SVG-handler options (from SceneCanvas's `ingestion` prop).
-     *  Live accessor, same caveat as `resolveSrc`. */
-    svg?: SvgIngestOptions;
-    /** Clipboard-paste seam for the kit weasel-JSON handler.
-     *  Live accessor, same caveat as `resolveSrc`. */
-    clipboard?: ClipboardIngestCtx;
-}
-/**
- * Per-kind extra geometry passed to `InsertDep.commit`.
- *
- * Built-in tools populate a typed variant so the kit's default factory can
- * render the true tool params (line endpoints, polygon side count, star
- * geometry, pencil sample list). Consumer-defined tools may pass any
- * `{ kind: string; ... }` payload; the kit's factory falls back to AABB
- * inscription for unknown kinds.
- *
- * `bounds` is still passed alongside as a useful AABB pose hint — factories
- * may use it as the node's pose even when richer geometry is available.
- */
-type InsertExtras = {
-    kind: 'rect';
-} | {
-    kind: 'ellipse';
-} | {
-    kind: 'line';
-    a: {
-        x: number;
-        y: number;
-    };
-    b: {
-        x: number;
-        y: number;
-    };
-} | {
-    kind: 'polygon';
-    sides: number;
-    rotation: number;
-    center?: {
-        x: number;
-        y: number;
-    };
-    radius?: number;
-} | {
-    kind: 'star';
-    points: number;
-    innerRadiusRatio: number;
-    rotation: number;
-    center?: {
-        x: number;
-        y: number;
-    };
-    outerRadius?: number;
-} | {
-    kind: 'pencil';
-    samples: ReadonlyArray<DragSample>;
-} | {
-    kind: 'text';
-    text?: string;
-} | {
-    kind: 'image';
-    src?: string;
-    opacity?: number;
-    /** Chrome-only: what the in-flight drag paints. Read by the overlay
-     *  layer, ignored by the insert dep. */
-    preview?: 'bitmap' | 'outline';
-} | {
-    kind: string;
-    [extra: string]: unknown;
-};
-/**
- * World-space point snapping — grid, guides, or any consumer rule.
- *
- * Sourced by `<SceneCanvas>` from its `toolOptions.snapPoint`. Actions apply
- * it to the coords they ingest so the live preview and the committed
- * geometry agree; `insertAction` snaps the drag's start and current point.
- *
- * Optional: when the dep is absent, actions treat it as identity.
- */
-interface SnapDep {
-    /** Snap a world-space point. Return `p` unchanged to opt out. */
-    point(p: {
-        x: number;
-        y: number;
-    }): {
-        x: number;
-        y: number;
-    };
-}
-/**
- * Adapter dep for `insertAction`.
- *
- * Provided by `<SceneCanvas>` / `<StandardActionsRegistrar>`. The `extras`
- * carry the active tool's kind + per-kind geometry. Callers
- * that need typed data must supply a richer `insert` dep.
- */
-interface InsertDep {
-    /**
-     * Materialise a new node from the given drag-rect bounds and typed
-     * per-kind extras. Returns the new node's id, or `null` if the consumer
-     * rejected the insert (e.g. sub-threshold bounds, unknown kind).
-     */
-    commit(bounds: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    }, extras: InsertExtras): NodeId | null;
-}
-/**
- * Adapter dep for `resizeAction`.
- *
- * Carries the four behavior-shaping options the legacy `useResize` hook
- * exposed through `UseResizeOptions`: bounds-frame behaviors (e.g.
- * `lockAspectWithModifier`), world-space anchor-point snap behaviors (e.g.
- * `pointSnapToGrid`), group-expansion (`expandIds`), and pose↔bounds
- * projection (`geometry`).
- *
- * Optional in `DepSchema`: when absent, `resizeAction` falls back to
- * identity defaults (no behaviors, identity expandIds, `RECT_POSE_DESCRIPTOR`
- * geometry). Consumers wire the dep via `useDepSource('resizePolicy', ...)`
- * from any descendant of `<DepRegistryProvider>` / `<SceneCanvas>`.
- *
- * The generic is erased to `unknown` at the schema entry; consumers cast at
- * the call site (mirrors the `scene` entry's convention).
- */
-interface ResizePolicy<TPose> {
-    /** Bounds-frame constraints. Constrained to `TPose extends ResizePose` since
-     *  constraints read/write `{x,y,width,height}`. For non-rect TPose pass `[]`. */
-    constraints: TPose extends ResizePose ? BoundsConstraint<TPose>[] : never[];
-    /** World-space anchor-point snap behaviors. Same TPose constraint as
-     *  `constraints`. */
-    pointSnap: TPose extends ResizePose ? PointSnapBehavior<TPose>[] : never[];
-    /** Group-expansion at gesture start. Identity (`ids => ids`) when group
-     *  resize isn't wanted. */
-    expandIds: (ids: string[]) => string[];
-    /** Projection from `TPose` to bounds and back. Use `RECT_POSE_DESCRIPTOR`
-     *  for plain rect poses. */
-    projection: PoseProjection<TPose>;
-}
-/**
- * Layout-strategy lookup by container id, consumed by `moveAction` to run
- * the drag-time reflow pass. Sourced by `<SceneCanvas>` from its `layouts`
- * prop. Optional: `getLayout` returns null for any container when no layout
- * is configured, so the reflow pass is a no-op then.
- */
-interface LayoutDep {
-    getLayout(containerId: string): LayoutStrategy<unknown> | null;
-}
-/**
- * The names an action may declare in `requires`, and what each resolves to.
- *
- * This is the whole vocabulary of things an action can reach — selection,
- * scene, view, history, and the rest. Consumers add their own entries by
- * augmenting the interface (`declare module '@weasel-js/core'`), which is what
- * makes a custom dep name type-check in `requires` and in the deps bag.
- */
-interface DepSchema {
-    /** Kit selection state — ids of currently selected nodes. */
-    selection: SelectionApi;
-    /** Current viewport — camera position + scale. */
-    view: ViewApi;
-    /**
-     * Scene tree — structural reads + undoable mutations.
-     *
-     * The entry uses the fully-erased form `Scene<unknown, string, unknown>`
-     * because `DepSchema` must be concrete. Actions that need a typed scene
-     * should cast: `deps.scene as Scene<MyData, MyLayer, MyPose>`.
-     */
-    scene: Scene<unknown, string, unknown>;
-    /** Undo/redo history bound to the current scene. */
-    history: History;
-    /**
-     * Canvas pointer position in world space.
-     *
-     * Exposes `pointerRef` (mutable live ref) and `getDropPoint()` thunk.
-     * Marked `@experimental` in the source.
-     */
-    pointer: PointerContextValue;
-    /** Currently active tool id + hotkey-hold stack. */
-    activeTool: ActiveToolContextValue;
-    /**
-     * Area-select dep — AABB hit-test + selection read/write.
-     *
-     * Sourced from `<SceneCanvas>` via AABB overlap over all scene
-     * nodes. Override per-consumer for custom hit-testing (e.g. contain-mode,
-     * lock-aware filtering).
-     */
-    areaSelect: AreaSelectDep;
-    /**
-     * Topmost node at a world-space point. Sourced by `<SceneCanvas>` from
-     * the same picker that feeds the tool dispatcher's `getNodeAtPoint`.
-     * Optional: actions that read this (e.g. `moveAction` reparent-on-drop)
-     * fall back to a no-op when the dep isn't registered.
-     */
-    nodeAtPoint?: NodeAtPointDep;
-    /**
-     * Insert dep — node factory for drag-to-insert.
-     *
-     * Sourced from `<SceneCanvas>`. The `kind` param comes from
-     * the active binding's `opts.params.kind`. Override per-consumer to
-     * provide a typed node factory (e.g. with custom data payloads).
-     */
-    insert: InsertDep;
-    /**
-     * Snap dep — world-space point snapping (grid / guides).
-     *
-     * Sourced by `<SceneCanvas>` from `toolOptions.snapPoint`. Optional:
-     * absent means no snapping (identity).
-     */
-    snap?: SnapDep;
-    /**
-     * Lasso-select dep — polygon hit-test + selection read/write.
-     *
-     * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>`.
-     * Falls back to AABB hit-test when `hitTestLasso` is absent.
-     */
-    lassoSelect: LassoSelectDep;
-    /**
-     * Edit-anchors dep — narrow read/write of one polygon's path pose.
-     *
-     * Sourced from consumer. Wraps `getPose`/`setPose`/`applyOps`
-     * for the currently-being-edited polygon node.
-     *
-     * The `editAnchorsAction` requires this dep to be registered when anchor
-     * editing is active. If absent, `start` returns an empty handle (no-op).
-     */
-    editAnchors: EditAnchorsDep;
-    /**
-     * Text-edit dep — activates the in-place text editing overlay.
-     *
-     * Sourced from consumer via `useTextEdit` / `useSceneTextEdit`.
-     * The `enterTextEditAction` requires this dep to be registered by the text
-     * tool when text editing is available.
-     *
-     * The optional `isTextNode` predicate guards against entering edit mode on
-     * non-text nodes. A binding can pre-filter instead with a
-     * `target: 'kind:text:selected'` spec; the guard remains for consumers who
-     * bind the broader `'selected-body'` target or opted out of routing.
-     */
-    textEdit: TextEditDep;
-    /**
-     * Resize-policy dep — bounds constraints, point-snap behaviors,
-     * group expansion, and pose↔bounds projection for `resizeAction`.
-     *
-     * Optional: when omitted, `resizeAction` falls back to identity defaults
-     * (no constraints, no snap, identity expandIds, `RECT_POSE_DESCRIPTOR`).
-     * Consumers wire via `useDepSource('resizePolicy', ...)` or the
-     * `useResizePolicy` helper.
-     */
-    resizePolicy?: ResizePolicy<unknown>;
-    /**
-     * Booleans adapter — read selection ids, fetch world-space `Path`s,
-     * compare z-order, and mint result nodes for Pathfinder ops.
-     *
-     * Consumers wire via `useBooleansAdapter(adapter)` (a thin wrapper
-     * around `useDepSource('booleansAdapter', ...)`). The descriptor's
-     * `enabled` predicate reads `deps.selection` for the count check; the
-     * invoker reads `deps.booleansAdapter` to execute the op.
-     */
-    booleansAdapter?: BooleansAdapter;
-    /**
-     * Gesture dispatcher control surface — exposes `cancelAll(reason)` so
-     * actions that need to abort an in-flight handle (Escape cancels a
-     * drag, etc.) can do so. Sourced by `<SceneCanvas>` from the
-     * dispatcher instance it already owns.
-     */
-    dispatcher?: {
-        cancelAll(reason: 'commit' | 'cancel'): void;
-    };
-    /**
-     * Layout-strategy lookup. Sourced by `<SceneCanvas>` from `layouts`.
-     * Optional: absent (or all-null) → `moveAction` skips reflow.
-     */
-    layout?: LayoutDep;
-    /**
-     * Slice dep — consumer-supplied commit for the Slice action.
-     *
-     * Receives the finite slice segment in world coordinates; the consumer
-     * scans the scene, splits crossed paths via `splitPathByLine`, and
-     * applies the result as one undoable batch.
-     *
-     * Optional: when absent, `sliceAction` is a no-op.
-     */
-    slice?: SliceDep;
-    /**
-     * Clipboard dep — the imperative surface `useClipboardOps` returns.
-     *
-     * Published by the consumer (`useDepSource('clipboard', …)` from under
-     * `<SceneCanvas>`), because `useClipboardOps` needs an adapter and a
-     * selection reader only the consumer has. Feeds `clipboard.copy` /
-     * `clipboard.cut`; both no-op when the dep is absent.
-     */
-    clipboard?: ClipboardDep;
-    /**
-     * Optional consumer commit hook. When present, `moveAction` (and other
-     * default actions) submit their committed ops through it instead of
-     * `scene.applyBatch`, so apps with their own history integration
-     * (checkpoint + push entry) capture the gesture as one undo entry.
-     * When absent, commits fall back to `scene.applyBatch`.
-     */
-    applyOps?: (ops: Op[], label: string) => void;
-    /** Optional pose-composition strategy for hierarchical (local-pose) scenes.
-     *  When absent, defaults to IDENTITY (absolute-pose: nodes store world
-     *  coords). Local-pose consumers supply { compose: composeRectPose,
-     *  decompose: decomposeRectPose } (or their pose shape's equivalent). */
-    poseComposition?: PoseComposition<unknown>;
-    /**
-     * Ingestion dep — canvas viewport rect + consumer file→src resolver.
-     *
-     * Sourced from `<SceneCanvas>` / `<StandardActionsRegistrar>` via
-     * `useIngestionDepSource`. Feeds `ingestAction` with the world-space
-     * viewport rect for paste-placement and image fit-clamping, and forwards
-     * the consumer's optional `resolveSrc` seam.
-     *
-     * Optional: when absent, the `ingest` action no-ops (there is no
-     * placement geometry to work with).
-     */
-    ingestion?: IngestionDep;
-    /**
-     * Optional consumer seam for the eager-sync layer: lets pose-transform
-     * actions (resize/move/nudge/flip — NOT rotate) ALSO rewrite a node's
-     * data-held geometry. Given a node and the affine `m` applied to its pose,
-     * `transform(node, m)` returns updated `data` (geometry mapped by `m`) or
-     * `null` for nodes with no data-held geometry.
-     *
-     * Strictly opt-in: when absent (or when `transform` returns null), the kit
-     * emits only the pose op and leaves `data` untouched. apps/draw wires this
-     * to mirror `data.path` through `transformPath`. Rotate intentionally never
-     * consults this seam (rotation lives on the pose, baked at render).
-     */
-    geometryProjection?: GeometryProjection;
-}
-/**
- * Every dep name the registry knows about — derived from {@link DepSchema} so
- * the two can't drift.
- *
- * Declared here rather than beside the registry so that this `keyof` reference
- * resolves to the exported `DepSchema` declaration; from another module it
- * resolves to that module's import alias, which the API docs can't link.
- */
-type DepName = keyof DepSchema;
-
-/** Holds the live sources an action's declared dependencies resolve to.
- *  Sources are thunks, read at invocation time, so an action never captures
- *  stale state. */
-interface DepRegistry {
-    register<K extends DepName>(name: K, source: () => DepSchema[K]): () => void;
-    get<K extends DepName>(name: K): DepSchema[K] | undefined;
-}
-/** Provides the dep registry for a canvas. `<SceneCanvas>` mounts one; a
- *  consumer registering its own dep sources must be inside it. */
-declare function DepRegistryProvider({ children }: {
-    children: ReactNode;
-}): react_jsx_runtime.JSX.Element;
-/** The dep registry in scope. Throws outside a `<DepRegistryProvider>`. */
-declare function useDepRegistry(): DepRegistry;
-/**
- * Like `useDepRegistry`, but returns `null` when no `<DepRegistryProvider>` is
- * in scope instead of throwing. Used by `useStandardActions` to preserve its
- * silent-no-op contract when neither provider is present.
- */
-declare function useOptionalDepRegistry(): DepRegistry | null;
-/** Register a live source for `name` for the lifetime of the calling
- *  component. The `source` thunk is called at dispatch time and should
- *  return the latest value. */
-declare function useDepSource<K extends DepName>(name: K, source: () => DepSchema[K]): void;
-
-/**
- * When an entry's bindings are live. A set, not one value: the hand tool is
- * palette-selectable AND engaged by holding space, and both hold at once.
- */
-interface Eligibility {
-    /** Selectable as the focused entry — exclusive, one at a time. */
-    focus?: boolean;
-    /** Also live while this key is held. */
-    offhand?: HotkeyTrigger;
-    /** Live regardless of what is focused. */
-    always?: boolean;
-    /** Live only for input this entry's own affordances produced. */
-    claimed?: boolean;
-    /** Modality filter, applied wherever it would otherwise be live. */
-    capabilities?: CapabilityTag[];
-}
-/**
- * Where an entry's overlay sits in the layer stack, relative to the
- * selection chrome. `'top'` is the default and renders above everything;
- * the other two exist for chrome that belongs under the selection handles
- * (a snap-target highlight, say). With no selection overlay in the stack,
- * all three collapse to `'top'`.
- */
-type OverlayPosition = 'top' | 'before-selection' | 'after-selection';
-/**
- * A registry entry: what it contributes, and when it is eligible. Every role
- * is optional and independent — an entry that only routes input declares only
- * `bindings` and `actions`.
- */
-interface Contribution {
-    id: string;
-    eligibility: Eligibility;
-    bindings?: GestureBinding[];
-    actions?: Action[];
-    /** One layer, or several composed in the given order. */
-    overlay?: RenderLayer<unknown> | RenderLayer<unknown>[];
-    /** Defaults to `'top'`. Applies to every layer in `overlay`. */
-    overlayPosition?: OverlayPosition;
-    presentation?: ToolPresentation;
-    /** Reflection escape hatch — the authored form, when there was one. */
-    def?: unknown;
-}
-
-/**
- * Configurable activation-key descriptor for tools that expose their
- * keybinding to the host (currently Lasso and Eyedropper). Captures
- * only the fields meaningful to a caller-supplied tool-select key —
- * dispatcher-internal fields (`skipInEditable`, `enabled`,
- * `preventDefault`) live on `KeyBinding` in keyHelpers.ts and are
- * not part of the configurable surface.
- */
-interface ToolKeybinding {
-    /** Key or list of keys to match (case-insensitive against `event.key`). */
-    key: string | readonly string[];
-    /** Require Cmd (mac) / Ctrl (others). Default `false`. */
-    mod?: boolean;
-    /** Require Alt. Default `false`. */
-    alt?: boolean;
-    /**
-     * Shift policy. `undefined`/`false` forbids shift, `true` requires
-     * shift, `'optional'` allows either.
-     */
-    shift?: boolean | 'optional';
-}
-/**
- * What a tool declares.
- *
- * A tool is a declarative shell, not an event handler: it names the gestures
- * it responds to and, for each, the action to invoke. The dispatcher owns the
- * gesture, and the action owns the preview and the commit — so a tool
- * definition is mostly `bindings`, plus presentation and any actions the tool
- * itself introduces.
- */
-interface ToolDef<TScratch = void> {
-    id: string;
-    /** Capability tags for modality eligibility. Forwarded onto `Tool.capabilities`. */
-    capabilities?: CapabilityTag[];
-    /**
-     * Actions this tool owns and needs registered while it is in the tools
-     * registry — e.g. polygon's `polygon.adjustSides`, which its own bindings
-     * reference by id.
-     *
-     * Declared here rather than registered by the hook with `useAction`,
-     * because tool hooks run wherever the consumer calls them — for
-     * `<SceneCanvas>` that is ABOVE `<ActionsProviderIfRoot>`, where
-     * `useActionsRegistry()` returns null and `useAction` silently no-ops. The
-     * result was a binding pointing at an action id nothing had registered, so
-     * the gesture fell through to whatever matched next (polygon's
-     * wheel/arrow-key side adjustment did nothing and `nudge.*` moved the
-     * selection instead). `<ToolActionsMounter>` registers these from inside
-     * the provider.
-     */
-    actions?: Action[];
-    /** Hook name as exported from the kit barrel (e.g. `'useHandTool'`).
-     *  Set by built-in hooks for inspector / debugging. Consumer-authored
-     *  tools may set this to surface their hook name; omitted is fine.
-     *  Introspection-only — do not make this load-bearing in production.
-     *  Read off the def via `Tool.def` (the reflection escape hatch). */
-    hookName?: string;
-    presentation?: ToolPresentation<TScratch>;
-    /** Optional caller-supplied activation key. Most built-in tools have their
-     *  activation key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`;
-     *  this field is for tools that want their activation key to be
-     *  configurable by the host (currently Lasso and Eyedropper). The dynamic
-     *  loop in `useKeybindings.ts` picks this up and appends a binding entry
-     *  to the consolidated `tool.activate` action (with `opts.params.toolId`
-     *  set so the invoker knows which tool to switch to). */
-    keybinding?: ToolKeybinding;
-    /** Held-key trigger: this tool engages while the key is down and
-     *  disengages on release. Carried onto `Tool.eligibility.offhand`, which
-     *  assembly reads to register the consolidated `tool.offhand` action — the
-     *  declaration is the wiring, with nothing for the host to do. */
-    hotkey?: HotkeyTrigger;
-    onActivate?: (ctx: ToolCtx<TScratch>) => void;
-    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
-    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
-    /** Override the default scratch initializer. Default is `() => null`
-     *  cast to `TScratch`, which works for tools whose scratch is fresh
-     *  every gesture. Tools that need scratch identity to survive across
-     *  gesture boundaries (e.g. the pen tool's multi-click subpath state)
-     *  pass a stable-ref-returning thunk here. The factory forwards this
-     *  onto the returned `Tool.initScratch`. */
-    initScratch?: () => TScratch;
-    /** Declarative gesture bindings, forwarded onto `Tool.bindings`. The
-     *  gesture dispatcher consults these at active scope while this tool is the
-     *  active one, and at hotkey scope while it is held. This is the tool's
-     *  entire input surface — the `initial` / `engaged` phase tables that used
-     *  to sit beside it are gone, along with the second dispatcher that read
-     *  them. */
-    bindings?: GestureBinding[];
-    /** Optional overlay layer rendered while the tool occupies any slot
-     *  (active, hotkey, or ambient), surfaced on `Tool.overlay`.
-     *
-     *  The layer's `draw` closure should read dynamic state through refs or
-     *  closures captured in the enclosing render scope, and gate on it there —
-     *  `if (!scratch.something) return []` — rather than expecting the kit to
-     *  swap layers as the gesture progresses.
-     *
-     *  Pass an array to contribute several layers; they render in order. */
-    overlay?: RenderLayer<unknown> | RenderLayer<unknown>[];
-    /** Where `overlay` sits relative to the selection chrome. Defaults to
-     *  `'top'`, above everything. */
-    overlayPosition?: OverlayPosition;
-}
-/** Viewport-tool spec. Once phase tables went away this stopped differing
- *  from `ToolDef` in any structural way; `defineViewportTool` survives as the
- *  authoring signal that a tool pans/zooms the view rather than the scene. */
-type ViewportToolDef<TScratch = void> = ToolDef<TScratch>;
-
-/** Modifier-key snapshot at event dispatch time. */
-interface ToolModifiers {
-    alt: boolean;
-    shift: boolean;
-    meta: boolean;
-    ctrl: boolean;
-}
-/** Per-event context passed to every channel handler. `scratch` is typed
- *  via the tool's `TScratch` parameter; it survives across a single
- *  gesture (pointer-down through end/cancel) and is replaced on next
- *  gesture start by `initScratch()`. */
-interface ToolCtx<TScratch = unknown> {
-    worldX: number;
-    worldY: number;
-    modifiers: ToolModifiers;
-    selection: SelectionApi;
-    /** Adapter/scene access — opaque at this layer; tools that need it
-     *  cast to a known shape. This layer doesn't constrain it. */
-    adapter: unknown;
-    applyOps: (ops: Op[], label: string) => void;
-    /** Current viewport. Reflects camera-position semantics — see
-     *  `View` JSDoc. */
-    view: View;
-    /** Mutate the viewport. In controlled mode this calls the consumer's
-     *  `onViewChange`; in uncontrolled mode it updates Canvas's internal
-     *  state. View changes are not undoable. */
-    setView: (next: View) => void;
-    /** Bounding rect of the canvas element in viewport coords. Used by
-     *  zoom/pan tools to convert event clientX/clientY to canvas-relative
-     *  anchors. */
-    canvasRect: DOMRect;
-    /** Screen-space pointer coords relative to `canvasRect`. Useful for
-     *  viewport tools that pan/zoom in screen space (e.g. hand-pan
-     *  computes deltas in pixels, not world units). Optional — populated
-     *  by the dispatcher on pointer events; absent on keyboard events. */
-    screenPoint?: {
-        x: number;
-        y: number;
-    };
-    /** Optional debug sink. When `<Canvas debug={...}>` is enabled, Canvas
-     *  threads its sink here so tool-internal hit math (handle hitboxes,
-     *  rotation handle, etc.) lands in the same overlay as Canvas's own
-     *  bounds/origin records. Tools should call this conditionally with `?.`. */
-    debug?: DebugSink;
-    scratch: TScratch;
-}
-/** Hotkey-slot trigger key. The slot is engaged while this key is held —
- *  hence "hotkey": active as long as the key is hot. `null` (or omitted)
- *  means the tool is not eligible for the hotkey slot. */
-type HotkeyTrigger = 'space' | 'alt' | 'ctrl' | 'meta' | 'shift';
-/** World-space AABB shape used by `previewBounds`. Alias of the kit-wide
- *  `Bounds` type — the optional `rotation` field carries through so a tool
- *  can report an oriented preview rect (e.g. mid-rotate). */
-type ToolBounds = Bounds;
-/** Presentation metadata for tool palettes / menus. Optional on every
- *  tool — consumers that render a palette (`<ToolPalette>`) read these
- *  fields to display the tool; consumers that don't can ignore them.
- *
- *  Note: cursor is NOT here. `Tool.cursor` (inherited from `Contribution`)
- *  is already plumbed through `<Canvas>` to `style.cursor` on the host. */
-interface ToolPresentation<TScratch = unknown> {
-    /** Human-readable label, distinct from the `id`. Falls back to `id`. */
-    label?: string;
-    /** Inline-SVG icon component output. May be a static `ReactNode` or a
-     *  function of scratch state (rare; useful for shape-aware affordances). */
-    icon?: React.ReactNode | ((scratch?: TScratch) => React.ReactNode);
-    /** Palette grouping key. Tools sharing a group render contiguously
-     *  with separators between groups. Free-form string; the kit
-     *  recommends 'select' | 'shape' | 'draw' | 'type' | 'view'. */
-    group?: string;
-    /** Display override for the keyboard shortcut. When omitted the palette
-     *  derives one from `Tool.keybinding` via its own formatter. */
-    shortcut?: string;
-}
-/**
- * The focus-declaring case of a `Contribution`: a mode the user switches
- * into, plus the hooks that only make sense for one (`initScratch`,
- * activate/deactivate, live preview, `cursor`). Everything else — bindings,
- * actions, overlay, presentation — is inherited.
- */
-interface Tool<TScratch = unknown> extends Contribution {
-    /** Optional caller-supplied key. Most built-in tools have their activation
-     *  key declared in `BUILTIN_SELECT_KEYS` in `useKeybindings.ts`; this field
-     *  is for tools that want their activation key to be configurable by the
-     *  host (currently Lasso and Eyedropper). The dynamic loop in
-     *  `useKeybindings.ts` picks this up and appends a binding entry to the
-     *  consolidated `tool.activate` action (with `opts.params.toolId` set so
-     *  the invoker knows which tool to switch to). */
-    keybinding?: ToolKeybinding;
-    initScratch?: () => TScratch;
-    cursor?: CursorSpec | ((ctx: ToolCtx<TScratch>) => CursorSpec);
-    onActivate?: (ctx: ToolCtx<TScratch>) => void;
-    onDeactivate?: (ctx: ToolCtx<TScratch>) => void;
-    /** Returns the in-flight preview pose for `id` if this tool is mid-gesture
-     *  on it; otherwise `null`. Lets `Canvas.helpersRef.getEffectivePose`
-     *  reflect live gesture state without reaching into hook internals. The
-     *  return type is `unknown` here because the Tool interface is pose-agnostic;
-     *  callers that know the pose shape (e.g. Canvas typed by `TPose`) cast at
-     *  the use site. */
-    previewPose?: (id: string) => unknown;
-    /** Returns the in-flight preview bounds for `id` if this tool is mid-gesture
-     *  on it; otherwise `null`. Optional companion to `previewPose` for tools that
-     *  can compute bounds without round-tripping through a geometry adapter. */
-    previewBounds?: (id: string) => ToolBounds | null;
-    /** Returns ids whose committed scene-render should be suppressed while this
-     *  tool is mid-gesture (e.g. cascade move's dragged + descendant ids whose
-     *  preview ghosts replace the committed pose). The standard scene slot
-     *  consults this alongside `previewPose` to avoid double-rendering. Returns
-     *  `null` when no gesture is in flight. */
-    previewIds?: () => Iterable<string> | null;
-}
-/** Internal — which slot a tool occupies in the dispatch order. */
-type ToolSlot = 'hotkey' | 'active' | 'ambient';
-/** Internal alias for "a Tool of any scratch type" — used in registries and
- *  dispatchers that hold tools of heterogeneous scratch shapes. `any` is
- *  intentional: `Tool<TScratch>` is invariant in TScratch, so `Tool<unknown>`
- *  is too strict for containers that accept any concrete `Tool<T>`. */
-type AnyTool = Tool<any>;
-
-/**
- * Pure matcher primitives live in `@weasel-js/gestures`. This file
- * re-exports them for kit-internal consumers and layers the actions-layer
- * binding-scope / matchBest logic on top.
- */
-
-/** Where a binding came from, which is also its priority: a held hotkey beats
- *  the active tool, which beats bindings that are always in scope. */
-type BindingScope = 'ambient' | 'active' | 'hotkey';
-/** A binding paired with where it came from, ready to be matched against an
- *  event. */
-interface ScopedBinding {
-    binding: GestureBinding;
-    scope: BindingScope;
-    /** Tool id that owns this binding — `'&'`-channel phase atoms resolve
-     *  to this. `null` for ambient bindings that came from a registered
-     *  Action with no owning tool. */
-    ownerToolId: string | null;
-}
-/** The binding that won a match. */
-interface MatchResult {
-    binding: GestureBinding;
-    scope: BindingScope;
-    /** Tool id that owns the binding — propagated from `ScopedBinding`
-     *  so the dispatcher can record it as the handle owner. */
-    ownerToolId: string | null;
-}
-/** CSS-style specificity tuple for a GestureSpec. Higher tuple wins under
- *  lexicographic compare. Dimensions, in order of precedence:
- *
- *    [0] target — how much the spec's target narrows; see `targetRank`.
- *    [1] mods   — count of required modifier keys (shift/alt/ctrl/meta/mod).
- *                 `'optional'` does NOT count.
- *    [2] phase  — how much the spec's `phase` narrows; see `phaseRank`.
- *    [3] exact  — per-kind tiebreak: 2 for a drop/paste spec with a
- *                 non-empty `types` MIME filter, else 1.
- *
- *  Identical tuples fall back to registration order in the matcher's
- *  stable sort, preserving the pre-specificity tiebreaker. */
-declare function specificity(spec: GestureSpec): readonly [number, number, number, number];
-
-/**
- * Dispatcher orchestrator — pure module, no React, no DOM.
- *
- * Assembles `ScopedBinding[]` from the actions registry, active tool, and
- * hotkey stack; matches input events via `matchSorted`; gates each candidate
- * on `enabled()`; then invokes `immediate` or `ongoing` invokers and tracks
- * in-flight handles.
- *
- * ## Specificity-ordered fall-through
- * `matchSorted` returns every matching binding in precedence order
- * (hotkey > active > ambient, first-declared within scope). The dispatcher
- * walks that list and fires the first action whose `enabled()` returns
- * `true`. If every candidate's `enabled()` returns a disabled reason, the
- * event is unhandled. This mirrors CSS-style specificity matching with a
- * `:not(:disabled)` filter, and lets a tool declare a high-specificity
- * binding (e.g. drag-on-empty → areaSelect) that gracefully falls through
- * to a lower-specificity ambient binding (e.g. drag → viewport.dragPan)
- * when its required deps aren't wired.
- *
- * ## gestureId scheme
- * - `key-held` ongoing actions: `key-held-<key>` (e.g. `key-held- ` for Space).
- *   Chosen because key-held gestures are identified by the held key alone.
- * - `pointerdown` / drag ongoing actions: `pointer-<pointerId>`, taken from
- *   the originating DOM `PointerEvent`. Each physical pointer — mouse, each
- *   touch, the stylus — gets its own handle slot. Events with no
- *   `pointerId` (synthesized probes, programmatic drags, most tests) key to
- *   `pointer-mouse`, so a single synthetic pointer behaves as it always has.
- * - `multitouch` ongoing actions: `multitouch-<fingers>`.
- * - Fallback for any other kind that triggers an ongoing invoker: `ongoing-<kind>`.
- *
- * ## Action-lookup miss behavior
- * When `matchBest` resolves a binding whose `actionId` has no entry in
- * `ctx.actions.list()`, the dispatcher emits `console.warn` and returns
- * `'unhandled'`. The user's input gesture falls through as if unmatched.
- * This preserves input flow (nothing is swallowed silently) while flagging
- * the misconfiguration at dev time.
- */
-
-/** Everything the dispatcher must consult to route one input event: the
- *  registered actions and their deps, which tool is active, which hotkeys are
- *  held, and — optionally — the chrome state that action eligibility rules are
- *  evaluated against. Rebuilt per event rather than held, so the dispatcher
- *  itself stays stateless apart from in-flight gestures. */
-interface DispatcherContext {
-    /** All registered actions; the dispatcher walks `.defaultBinding` for ambient bindings. */
-    actions: ActionsRegistry;
-    /** Dep sources keyed by name. */
-    depRegistry: DepRegistry;
-    /** Active tool's id (from ActiveToolContext). */
-    activeToolId: string;
-    /** Held-hotkey stack, top of stack last. */
-    hotkeyStack: readonly string[];
-    /** Lookup for tool definitions. */
-    toolsById: ReadonlyMap<string, Tool>;
-    /** Platform flag for `mod` shorthand resolution. */
-    isMac: boolean;
-    /**
-     * Thunk returning a fresh `RuleCtx` for the current frame — the routed
-     * view's, when the surface hosts several. When it answers, the dispatcher
-     * filters matched candidates by their declared `Action.eligible` rule
-     * (omitted => always eligible). Absent, or answering `undefined`, applies
-     * no eligibility filtering.
-     */
-    getRuleCtx?: () => RuleCtx | undefined;
-}
-/**
- * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
- * ongoing invoker from a UI control (color picker, slider).
- *
- *  - `update(params)` rebuilds an `InvocationCtx` with the new params and
- *    calls the handle's `onMove`. Safe to call many times.
- *  - `end(reason)` calls `onEnd(ctx, reason)` once and removes the handle
- *    from the in-flight map. Idempotent — further calls are no-ops.
- */
-interface UiOngoingControl {
-    readonly gestureId: string;
-    update(params?: Record<string, unknown>): void;
-    end(reason: 'commit' | 'cancel'): void;
-}
-/**
- * Successful `Dispatcher.resolveOnly` prediction: the binding + action that
- * would fire if `event` were dispatched for real. `action` is the resolved
- * descriptor so callers (the hover-cursor pump) can read metadata like
- * `Action.cursor` without a second registry lookup.
- */
-interface ResolveOnlyResult {
-    actionId: string;
-    action: Action;
-    scope: BindingScope;
-    /** Tool id owning the winning binding; `null` for ambient action bindings. */
-    ownerToolId: string | null;
-}
-/**
- * One candidate from `Dispatcher.resolveAll` — a binding that matched the
- * event, with why it did or didn't get to fire.
- *
- * Verdicts:
- *  - `would-fire`  — eligible, `enabled()` passed, and nothing above it fired.
- *    At most one candidate per call carries this.
- *  - `ineligible`  — the action's `eligible` rule evaluated false against the
- *    live `RuleCtx`. `reason` is the rule, serialized.
- *  - `disabled`    — `enabled()` returned a disabled reason, carried verbatim.
- *  - `shadowed`    — never asked, for one of two reasons: something above it
- *    already fired, or it is a repeat binding of the action that itself won
- *    higher in the list (several bindings may point at one action, and the
- *    dispatcher runs each action at most once). A repeat of an action that was
- *    already judged `ineligible` or `disabled` is NOT shadowed — it inherits
- *    that action's verdict, since that is the reason it doesn't fire.
- */
-interface ResolvedCandidate {
-    actionId: string;
-    action: Action;
-    binding: GestureBinding;
-    scope: BindingScope;
-    ownerToolId: string | null;
-    /** The tuple from `specificity(binding.spec)`, surfaced so a reader can see
-     *  why one candidate outranks another rather than inferring it. */
-    specificity: readonly [number, number, number, number];
-    verdict: {
-        kind: 'would-fire';
-    } | {
-        kind: 'ineligible';
-        reason: string;
-    } | {
-        kind: 'disabled';
-        reason: string;
-    } | {
-        kind: 'shadowed';
-    };
-}
-/** Options for {@link Dispatcher.resolveAll}. */
-interface ResolveAllOptions {
-    /**
-     * Evaluate eligibility and `enabled()` for candidates below the winner
-     * instead of short-circuiting them to `shadowed`.
-     *
-     * Off by default, and deliberately so: the default walk's early exit is what
-     * keeps `resolveOnly`'s `enabled()` call count identical to a real dispatch,
-     * and `enabled()` predicates are only contractually pure — not free.
-     *
-     * Turn it on for diagnostics, where "this one was outranked" is a less
-     * useful answer than "this one was outranked AND would have been disabled
-     * anyway". With it on, `shadowed` narrows to its precise meaning: this
-     * candidate would have fired, but something above it did.
-     */
-    evaluateShadowed?: boolean;
-}
-/**
- * Routes input events to actions.
- *
- * For each event it assembles the bindings in scope (hotkey, then active tool,
- * then ambient), matches them in specificity order, filters by eligibility and
- * each action's `enabled` gate, and invokes the first survivor. Ongoing
- * actions — anything that runs across a drag — are kept in flight here and
- * pumped with subsequent moves until the gesture ends.
- */
-interface Dispatcher {
-    /**
-     * Route an input event through the binding pipeline. Returns `'handled'`
-     * when a binding matched and the action invoked successfully (whether it
-     * returned ops or not). Returns `'unhandled'` when no binding matched or
-     * the matched action's `enabled()` returned a disabled reason.
-     */
-    handleInput(event: InputEvent, ctx: DispatcherContext): 'handled' | 'unhandled';
-    /**
-     * Predict which action `event` would route to WITHOUT invoking it. Replays
-     * the same walk as `handleInput` — scope assembly, specificity-sorted
-     * match, eligibility filter, per-candidate `enabled()` gate — and returns
-     * the first candidate that would fire, or `null` when the event would go
-     * unhandled. Pure query: no invoker runs, no in-flight state changes, no
-     * trace-log entry.
-     *
-     * Known divergence from a real dispatch: an ongoing invoker that matches
-     * but returns an empty handle at `start()` (runtime bail) makes the real
-     * dispatch fall through to the next candidate; prediction cannot see that
-     * and reports the bailing action. Keep `enabled()` accurate on actions
-     * that rely on prediction (hover cursors).
-     */
-    resolveOnly(event: InputEvent, ctx: DispatcherContext): ResolveOnlyResult | null;
-    /**
-     * Every binding that matches `event`, in dispatch precedence order, each
-     * with a verdict explaining whether it would fire. Same walk as
-     * `resolveOnly` — scope assembly, specificity-sorted match, eligibility
-     * check, per-candidate `enabled()` gate — without stopping at the winner
-     * and without invoking anything. Nothing is dropped: candidates that
-     * `resolveOnly`'s walk would filter out are kept here and labelled
-     * `ineligible` instead. Pure query: no invoker runs, no in-flight state
-     * changes, no trace-log entry.
-     *
-     * `resolveOnly` is the first `would-fire` entry of this list.
-     *
-     * Shares `resolveOnly`'s known divergence from a real dispatch: an ongoing
-     * invoker that matches but returns an empty handle at `start()` makes the
-     * real dispatch fall through, and this cannot see that.
-     *
-     * By default everything below the winner is `shadowed` without being asked,
-     * which is what keeps this walk as cheap as the dispatch it replays. Pass
-     * `{ evaluateShadowed: true }` to keep evaluating past the winner, so a
-     * lower candidate that is ALSO ineligible or disabled says so — see
-     * {@link ResolveAllOptions.evaluateShadowed}.
-     */
-    resolveAll(event: InputEvent, ctx: DispatcherContext, opts?: ResolveAllOptions): ResolvedCandidate[];
-    /**
-     * Synthesize an end-of-gesture for every in-flight ongoing handle.
-     * Used by tool-switch cancellation (Q2 decision).
-     */
-    cancelAll(reason: 'commit' | 'cancel'): void;
-    /**
-     * Read-only view of currently in-flight ongoing handles, keyed by gestureId.
-     * For debug/testing.
-     */
-    inFlight(): ReadonlyMap<string, OngoingHandle>;
-    /**
-     * CSS cursor for the gesture currently in flight, or `null` when nothing
-     * is. Reads `Action.activeCursor` (falling back to `Action.cursor`) off the
-     * action whose handle is open — the hover pump applies this instead of its
-     * prediction once a gesture starts, which is how `grab` becomes `grabbing`.
-     */
-    inFlightCursor(): string | null;
-    /**
-     * Read-only iterator over currently in-flight `OngoingHandle` instances.
-     *
-     * Surface for the canvas's preview-ghost layer (`usePreviewGhostLayer`)
-     * to walk each handle's `previewIds()` / `previewPose(id)` and render
-     * dispatcher-driven gesture previews. Read-only by design:
-     * external consumers must not mutate the in-flight map.
-     */
-    getInFlightHandles(): Iterable<OngoingHandle>;
-    /**
-     * Subscribe to in-flight state changes. The callback fires after every
-     * mutation that affects what the preview-ghost / dispatcher-overlay
-     * layers read — handle start, every `onMove` pump, end, cancel,
-     * cancel-all. Consumers re-read `getInFlightHandles()` and re-render.
-     *
-     * Returns an unsubscribe function.
-     */
-    subscribe(fn: () => void): () => void;
-    /**
-     * Monotonic counter bumped on exactly the events {@link subscribe} fires
-     * on. The snapshot half of the `useSyncExternalStore` contract: pair it
-     * with `subscribe` to drive a render off in-flight gesture state without
-     * a `useReducer` force-rerender.
-     *
-     * Starts at 0 and only ever increases. Two reads returning the same number
-     * mean nothing pumped in between; it does **not** guarantee that a bump
-     * changed anything observable (a pump that matched no binding still
-     * counts — see `subscribe`).
-     */
-    getVersion(): number;
-    /**
-     * Snapshot of the currently active action, for surfaces (chrome-caps
-     * visibility rules, debug HUDs) that need to react to "what action
-     * is in flight right now."
-     *
-     * - `kind` — the `OngoingHandle.kind` reported by the in-flight
-     *   handle (e.g. `'marquee'`, `'move'`). `null` when no action is
-     *   in flight OR the handle didn't declare a kind.
-     * - `id` — the dispatcher's internal `gestureId` (`pointer-1`,
-     *   `key-held-Space`, …) — the pointer/key channel the action rode
-     *   in on. `null` when no action is in flight.
-     *
-     * When multiple handles are in flight simultaneously (e.g. a key-held
-     * action overlapping a pointer action), the most-recently-started
-     * handle wins. This matches user intent: the latest interaction is
-     * the one consumers care about.
-     *
-     * That rule used to be near-vacuous on the pointer side, because every
-     * pointer shared one handle slot and two pointer drags could not coexist.
-     * With per-pointer keying they can — but only via paths that bypass the
-     * multi-pointer policy in `useGestureDispatcher` (which stops a second
-     * finger from opening a drag while a pinch is live), such as a mouse and
-     * a pen used together. Latest-start remains the right answer there.
-     */
-    getActiveAction(): {
-        kind: string | null;
-        id: string | null;
-    };
-    /**
-     * Start an ongoing action driven by UI (not a gesture). Builds an
-     * `InvocationCtx` with the given `deps` and `params`, calls
-     * `action.invoker.start(ctx, { params })`, and registers the returned
-     * handle in the in-flight map so `getInFlightHandles()` reports it —
-     * enabling preview rendering via `SceneCanvas`.
-     *
-     * Returns `null` if `actionId` is unknown, the action's invoker is not
-     * ongoing, or `start` returned an empty handle.
-     *
-     * If a UI-driven handle for the same `actionId` is already in flight,
-     * it is committed (`end('commit')`) before the new one starts.
-     */
-    beginUiOngoing(actionId: string, deps: ActionDeps, params?: Record<string, unknown>): UiOngoingControl | null;
-}
-/** Build a dispatcher. `getAction` overrides how action ids are resolved;
- *  by default the `DispatcherContext`'s registry is used. */
-declare function createDispatcher(opts?: {
-    getAction?: (id: string) => Action | undefined;
-}): Dispatcher;
-
-/**
- * @experimental
- * A single entry in `Action.defaultBinding[]`. Either a bare `GestureSpec`
- * (no per-binding opts) or an object form that pairs a spec with
- * `BindingOpts` for parametric actions (e.g. `{ params: { axis: 'x' } }`).
- * Use the object form when two bindings for the same action differ only in
- * a runtime parameter — the dispatcher extracts `opts.params` and passes
- * them to `ImmediateInvoker.run` as its second argument.
- */
-type BoundGesture = GestureSpec | {
-    spec: GestureSpec;
-    opts: BindingOpts;
-};
-/**
- * @experimental
- * Flatten an action's `defaultBinding` into `GestureBinding`s. A bare
- * `GestureSpec` has `kind` at top level; the object form has `spec`.
- */
-declare function actionBindings(action: Action): GestureBinding[];
-/**
- * @experimental
- * Single registered action. v1: one binding per action.
- */
-interface Action {
-    id: string;
-    label: string;
-    /** The gesture-spec form of the binding, read by the gesture dispatcher.
-     *  May be a single `GestureSpec`, a bare `GestureSpec[]` (any-of semantics),
-     *  or a `BoundGesture[]` where each entry is either a bare `GestureSpec` or
-     *  `{ spec, opts }` — use the object form for parametric actions where two
-     *  bindings for the same action differ only by `opts.params` (e.g. `flip`
-     *  with `axis: 'x'` vs `'y'`). The dispatcher extracts `opts.params` and
-     *  passes them to `ImmediateInvoker.run` as its second argument. */
-    defaultBinding?: GestureSpec | BoundGesture[];
-    /** Names of the deps this action's invoker reads (keys of `DepSchema`).
-     *  The dispatcher (and `trigger`, when `requires` is present) resolves
-     *  each name against the `DepRegistry` at invocation time and passes the
-     *  resulting bag to the invoker. Dev builds warn when the invoker reads a
-     *  dep it didn't declare here — see `buildDepsFromRequires`. */
-    requires?: readonly DepName[];
-    /** Inline-SVG icon for palette / toolbar surfaces. Mirrors
-     *  `ToolPresentation.icon` so a generic `<ActionBar>` can render from
-     *  action metadata the same way `<ToolPalette>` renders from tool
-     *  metadata. May be a static `ReactNode` or a function (rare; useful
-     *  for state-aware icons like a "lock" toggle). */
-    icon?: ReactNode | (() => ReactNode);
-    /** Grouping key for palette/menu surfaces. Free-form string; the kit
-     *  ships defaults for `'align'` (six edges/centers), `'distribute'`
-     *  (two axes), and recommends `'pathfinder'` for boolean ops. */
-    group?: string;
-    /** Display override for the keyboard shortcut. When omitted, palette
-     *  surfaces derive a label from `defaultBinding` via their own
-     *  formatter. */
-    shortcut?: string;
-    /** Pluggable invocation strategy. The gesture dispatcher routes matched
-     *  bindings through `invoker.start` / `invoker.run` depending on timing.
-     *  All kit-standard descriptors ship one; consumer-supplied actions
-     *  without an invoker can still register but won't be triggered. */
-    invoker?: Invoker;
-    /** When set to `'hotkey'`, this action's `defaultBinding` rides the hotkey
-     *  `BindingScope` instead of the ambient scope — meaning it beats any
-     *  active-tool binding on the same input shape. Use for tool-switch
-     *  shortcuts and global held-key triggers. Default: ambient. */
-    scope?: 'hotkey';
-    /**
-     * @experimental
-     * Optional predicate the command palette consults when rendering. Return
-     * `true` when the action is currently triggerable. Return a reason string
-     * (e.g. `'Selection required'`) when disabled — the palette greys out
-     * the row, skips it in keyboard nav, ignores clicks, and shows the
-     * reason next to the label. Keystroke dispatch (the registered binding)
-     * is unaffected; the action's own `run` should self-guard.
-     *
-     * **Contract:** must be pure (no side effects), fast (< 4ms in dev), and
-     * must not throw. If a call throws or exceeds the budget in dev mode,
-     * `evaluateEnabled` logs a one-time warning per action id; throws are
-     * caught and treated as disabled with reason `'(predicate threw)'`.
-     *
-     * Snapshot-on-open semantics: the palette evaluates `enabled` once when
-     * opened and does NOT re-evaluate on selection changes while open. Live
-     * reactive updates are deferred — palette is short-lived.
-     *
-     * The reason set is a closed enum — to add a new reason, edit
-     * `ActionDisabledReason` and the consumer's display map.
-     *
-     * The optional `deps` argument is the same bag passed to
-     * `ImmediateInvoker.run`; callers (`evaluateEnabled` / the ActionBar) may
-     * synthesize it from the surrounding `DepRegistry` so predicates can
-     * inspect selection / scene / etc. Predicates that don't need deps just
-     * ignore the arg.
-     */
-    enabled?: (deps?: ActionDeps) => true | ActionDisabledReason;
-    /**
-     * Declarative eligibility rule, evaluated against the current
-     * `RuleCtx` by the dispatcher before invoking `start()`. Omitted =
-     * always eligible.
-     *
-     * Accepts either a fluent `Condition` (callable with `.rule`) or a
-     * raw `Rule` tree; the dispatcher normalizes via `.rule` unwrap.
-     *
-     * Prefer `capability:`-based rules (e.g. `{ capability: 'transforms-selection' }`)
-     * over `mode:` rules — capability rules survive new modes being added
-     * that allow the same capability.
-     */
-    eligible?: Rule | Condition;
-    /**
-     * CSS cursor shown while the pointer hovers a spot where this action
-     * would win the drag. The hover-cursor pump (in `useGestureDispatcher`)
-     * runs `Dispatcher.resolveOnly` on each idle pointermove — the same
-     * match walk a real pointerdown takes — and applies the winning
-     * action's `cursor`, so the hint and the actual click target stay in
-     * sync by construction. Omitted = no override (the active tool's
-     * `Tool.cursor` shows). Affordance hits are resolved earlier in the
-     * pump via `AffordanceRegion.cursor` and never reach this field.
-     *
-     * Static value only. Prediction runs `enabled()` but cannot run the
-     * invoker, so an action that matches yet bails at `start()` (empty
-     * handle) may still show its cursor — keep `enabled` accurate for
-     * actions that declare one.
-     */
-    cursor?: CursorSpec;
-    /**
-     * CSS cursor shown while THIS action's ongoing handle is in flight —
-     * grabbing while panning, `move` while dragging a selection, `crosshair`
-     * while pulling a marquee.
-     *
-     * Separate from `cursor` because the two answer different questions:
-     * `cursor` is a prediction ("a drag from here would pan"), this is a state
-     * ("you are panning"). An action can declare either, both, or neither;
-     * with only `cursor` set, the hover hint holds for the duration of the
-     * gesture.
-     *
-     * This is where mid-gesture cursors live now. They used to come from the
-     * tool side — `ViewportToolDef.engaged.cursor` for a phase-gated string,
-     * or a function-form `Tool.cursor` reading the gesture scratch out of the
-     * tool-routing dispatcher. Both belonged to a pipeline whose whole job was
-     * being taken over by bindings, and neither could describe a cursor for an
-     * action a tool doesn't own.
-     */
-    activeCursor?: CursorSpec;
-}
-/**
- * @experimental
- * Closed enum of reasons an action might report itself as disabled. The
- * consumer (palette, menu, etc.) maps these symbolic values to display
- * strings via its own label map — see `demo/CommandPalette.tsx` for the
- * canonical mapping.
- */
-declare const ActionDisabledReason: {
-    readonly SelectionRequired: "selection-required";
-    readonly SceneEmpty: "scene-empty";
-    readonly NotApplicable: "not-applicable";
-    /** Sentinel: the predicate threw. Surfaced by `evaluateEnabled`'s catch. */
-    readonly PredicateThrew: "predicate-threw";
-};
-/** Why an action is unavailable right now. */
-type ActionDisabledReason = (typeof ActionDisabledReason)[keyof typeof ActionDisabledReason];
-/**
- * @experimental
- * Result of evaluating an Action's `enabled` predicate.
- */
-interface ActionEnabledResult {
-    enabled: boolean;
-    reason?: ActionDisabledReason;
-}
-/**
- * @experimental
- * Safely evaluate an action's `enabled` predicate. Returns `{enabled: true}`
- * when no predicate is supplied. Catches throws and treats them as disabled
- * with reason `'(predicate threw)'`. In dev mode, warns once per action id
- * when a single call exceeds 4ms (single frame at 240fps — generous; real
- * predicates should be sub-millisecond).
- */
-declare function evaluateEnabled(action: Action, deps?: ActionDeps): ActionEnabledResult;
-/**
- * @experimental
- * Partial override or full descriptor passed via `<SceneCanvas actions={...}>`.
- * `null` disables a default at this id.
- */
-type ActionEntry = null | Partial<Action> | Action;
-/**
- * @experimental
- * Shape of the `actions` prop on `<SceneCanvas>`. `null` disables all defaults.
- */
-type ActionsProp = null | Record<string, ActionEntry>;
-/**
- * @experimental
- * Imperative API exposed by `useActionsRegistry()`.
- */
-interface ActionsRegistry {
-    /** Add an action and return its release. Registrants for one id stack,
-     *  newest live, so releasing yours uncovers whoever you displaced. Call it
-     *  from an effect and release it in that effect's cleanup — registering from
-     *  a render body pushes an entry per render and releases none. */
-    register(action: Action): () => void;
-    /** Drop every registrant of `id`. This is the "this action should not exist"
-     *  door, not a release — for that, call what `register` returned. */
-    unregister(id: string): void;
-    /** Declare `id` not for this scope: it stays registered, and every other
-     *  scope over the same store still resolves it, but here it lists as absent
-     *  and neither `trigger` nor `begin` will fire it. Returns a release; an
-     *  `<ActionsScope>` drops what it muted when it unmounts. This is the
-     *  "not for me" door — `unregister` is the "should not exist" one. */
-    mute(id: string): () => void;
-    list(): readonly Action[];
-    /** Fire an immediate-invoker action by id. The optional `params` arg is
-     *  forwarded to `ImmediateInvoker.run` as its second argument — use it for
-     *  parametric actions (e.g. `trigger('tool.activate', { toolId: 'rect' })`).
-     *  Ongoing-invoker actions are not reachable from `trigger`. */
-    trigger(id: string, params?: Record<string, unknown>): boolean;
-    /**
-     * Subscribe to registry mutations. The callback fires after any
-     * `register`/`unregister` that changes the version. Returns an
-     * unsubscribe function. Designed for `useSyncExternalStore`-driven
-     * surfaces (e.g. `<ActionBar>` in `@weasel-js/ui`) that need to
-     * re-render when the action set changes.
-     */
-    subscribe(listener: () => void): () => void;
-    /**
-     * Start an ongoing action driven by UI (color picker, opacity slider).
-     * Returns a control object with `update(params)` and `end(reason)`.
-     *
-     * Returns `null` if no dispatcher is wired into this registry, the
-     * action is unknown, or its invoker is not ongoing.
-     *
-     * See `Dispatcher.beginUiOngoing` for full semantics including
-     * auto-commit when a prior UI handle for the same action is in flight.
-     */
-    begin(id: string, params?: Record<string, unknown>): UiOngoingControl | null;
-    /** Wire a dispatcher into the registry so `begin()` can delegate to it.
-     *  Returns a release that clears the slot only while this dispatcher still
-     *  holds it: a canvas displaced by a later one must not take input away from
-     *  the canvas now on screen. Call with `null` to detach unconditionally. */
-    setDispatcher(d: Dispatcher | null): () => void;
-    /** Wire a `DepRegistry` into the registry so `trigger()` / `begin()` can
-     *  resolve action deps even when this provider is mounted ABOVE the dep
-     *  registry (e.g. a consumer's root `<ActionsProvider>` reused by
-     *  SceneCanvas's `ActionsProviderIfRoot`). Takes precedence over the dep
-     *  registry read from context at the provider's own level. Call with
-     *  `null` to detach unconditionally; the returned release clears the slot
-     *  only while this registry still holds it. */
-    setDepRegistry(r: DepRegistry | null): () => void;
-}
-/**
- * @experimental
- * A view of the registry in scope that can declare ids not for itself. Wrap
- * anything that should be able to opt out of an action — a second
- * `<SceneCanvas>` sharing the host's `<ActionsProvider>` mounts one — and its
- * `mute` calls stay inside it. Renders nothing of its own.
- *
- * Not a `BindingScope`: that names the tier a binding matches at (hotkey /
- * active / ambient), which this has nothing to do with.
- */
-declare function ActionsScope({ children }: {
-    children: ReactNode;
-}): ReactElement;
-/**
- * @experimental
- * Mounts an `ActionsRegistry` for its lifetime. Children call
- * `useActionsRegistry()` or `useAction()` to participate. Mounts no input
- * listener of its own — the gesture dispatcher owns input.
- */
-declare function ActionsProvider({ children }: {
-    children: ReactNode;
-}): ReactElement;
-declare function useActionsRegistry(): ActionsRegistry | null;
-/**
- * @experimental
- * Register an `Action` for the lifetime of the calling component. No-op (with
- * a dev-only warning) when no `ActionsProvider` is in scope. Re-registers on
- * `action` reference change (consumers should memoize stable identities to
- * avoid churn).
- */
-declare function useAction(action: Action): void;
-
-export { type Contribution as $, type Action as A, type BuiltinShapeToolId as B, type Condition as C, type Dims as D, type AffordanceBinding as E, type CommonAffordanceScratch as F, type GeometryProjection as G, type HotkeyTrigger as H, type InertiaConfig as I, ColorOverrideRegistry as J, type BooleansAdapter as K, type LayerHit as L, type UseAnimatorOptions as M, type SpringPresetName as N, type OverlayPosition as O, type PanBounds as P, type EasingSpec as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, type AnimationHandle as W, type VertexColorChannel as X, type SampledTrack as Y, type Eligibility as Z, type BindingScope as _, type DeviceProfile as a, type PhysicsOptions as a$, type ScopedBinding as a0, ALWAYS as a1, type ActionDeps as a2, ActionDisabledReason as a3, type ActionEnabledResult as a4, type ActionEntry as a5, ActionsProvider as a6, ActionsScope as a7, ActiveToolContextProvider as a8, ActiveToolContextProviderIfRoot as a9, type EditAnchorsDep as aA, type EventTrack as aB, type GestureBinding as aC, IDENTITY_POSE_COMPOSITION as aD, type ImmediateInvoker as aE, type IngestCtx as aF, type IngestionDep as aG, type InsertDep as aH, type Interpolate as aI, type InterpolatorFactory as aJ, type InvocationCtx as aK, type Invoker as aL, KIT_SHAPE_KINDS as aM, type Keyframe as aN, type LassoSelectDep as aO, type LayerCommandCache as aP, type LayerDrawFailure as aQ, type LayoutDep as aR, type LoopFactory as aS, type LoopOptions as aT, type MatchResult as aU, NEVER as aV, type NestedTimeline as aW, type NodeAtPointDep as aX, type OngoingHandle as aY, type OngoingInvoker as aZ, type PhysicsHandle as a_, type ActiveToolContextProviderProps as aa, type ActiveToolContextValue as ab, type AnimateToBoundsOptions as ac, type AreaSelectDep as ad, type BezierEasing as ae, type BindingOpts as af, type BooleanOp as ag, type BooleanOpResult as ah, type BoundGesture as ai, type BuildRuleCtxArgs as aj, type ClaimableGesture as ak, type ClipboardDep as al, type ClipboardIngestCtx as am, type ColorOverride as an, type ColorOverrideFn as ao, type CustomPaintContext as ap, type DecayLoopConfig as aq, type DecayOptions as ar, type DepName as as, type DepRegistry as at, DepRegistryProvider as au, type DispatcherContext as av, type DragSample as aw, EASINGS as ax, type EasingFn as ay, type EasingName as az, type DetectedDeviceFacts as b, easeInOutBounce as b$, type Point2 as b0, PointerContextProvider as b1, type PointerContextValue as b2, type PointerWorldPos as b3, type PoseAdapter as b4, type PoseComposition as b5, type ResizePolicy as b6, type ResolveAllOptions as b7, type ResolveOnlyResult as b8, type ResolvedCandidate as b9, type UiOngoingControl as bA, VIEW_ANIMATION_KEY as bB, type ViewAnimationApi as bC, type ViewApi as bD, type ViewChannel as bE, actionBindings as bF, applyBooleanOp as bG, buildRuleCtx as bH, clipboardCopyAction as bI, clipboardCutAction as bJ, composeRectPose as bK, composeWorldPose as bL, createDispatcher as bM, cubicBezierEasing as bN, decomposeRectPose as bO, describeRule as bP, drawLayers as bQ, drawOneLayer as bR, easeIn as bS, easeInBack as bT, easeInBounce as bU, easeInCirc as bV, easeInCubic as bW, easeInElastic as bX, easeInExpo as bY, easeInOut as bZ, easeInOutBack as b_, SPRING_PRESETS as ba, type SelectionExtendKey as bb, type SelectionMode as bc, type Selector as bd, type SnapDep as be, type SpringOptions as bf, type SpringPreset as bg, type StaggerBuilder as bh, type StaggerDelay as bi, type StaggerFactory as bj, type StaggerOptions as bk, type StaggerPerItem as bl, type StaggerSpringPoseOptions as bm, type StaggerTweenOptions as bn, type SvgUnpacker as bo, type TextEditDep as bp, type TimelineHandle as bq, type TimelineOptions as br, type TimelineTrack as bs, type ToolCtx as bt, type ToolModifiers as bu, type ToolPresentation as bv, type ToolSlot as bw, type Track as bx, type TweenLoopOptions as by, type TweenOptions as bz, type Rule as c, easeInOutCirc as c0, easeInOutCubic as c1, easeInOutElastic as c2, easeInOutExpo as c3, easeInOutQuad as c4, easeInOutQuart as c5, easeInOutQuint as c6, easeInOutSine as c7, easeInQuad as c8, easeInQuart as c9, useAction as cA, useActionsRegistry as cB, useActiveToolContext as cC, useDecayLoop as cD, useDepRegistry as cE, useDepSource as cF, useOptionalActiveToolContext as cG, useOptionalDepRegistry as cH, usePointerContext as cI, useSelection as cJ, useViewAnimation as cK, worldPoseLookup as cL, easeInQuint as ca, easeInSine as cb, easeOut as cc, easeOutBack as cd, easeOutBounce as ce, easeOutCirc as cf, easeOutCubic as cg, easeOutElastic as ch, easeOutExpo as ci, easeOutQuad as cj, easeOutQuart as ck, easeOutQuint as cl, easeOutSine as cm, enterTextEditAction as cn, evaluate as co, evaluateEnabled as cp, isLayerPainted as cq, isLayerVisible as cr, linear as cs, rebaseLocalPose as ct, registerContentHandler as cu, resolveEasing as cv, resolveParams as cw, sliceAction as cx, specificity as cy, translateRectPose as cz, type RuleCtx as d, type ChromeCtx as e, type ChromeId as f, type ViewAnimationOptions as g, type DepSchema as h, type ActionsRegistry as i, type AffordanceHit as j, type Dispatcher as k, type ToolDef as l, type ViewportToolDef as m, type AnyTool as n, type ToolKeybinding as o, type OngoingOverlay as p, type ChromeState as q, type SelectionApi as r, type LayerGroup as s, type InsertExtras as t, type ContentHandlerEntry as u, type SvgIngestOptions as v, type ActionsProp as w, type Animator as x, type Affordance as y, type AffordanceRegion as z };