@weasel-js/core 1.6.1 → 1.7.0

package/dist/{builtins-HWyuLzE-.d.ts → builtins-DLn2lCr_.d.ts}

@@ -1,15 +1,18 @@
 import { GradStop, ColorSpace, TextureHandle, FillStyle, Stroke, ScreenLength } from '@weasel-js/paint';
-import { NodeId, Bounds, View, SelectionApi, ActionDeps, IngestItem, DragSample, Point2 } from '@weasel-js/routing';
+import { NodeId, Bounds, View, ModifierState, SelectionApi, ActionDeps, IngestItem, DragSample, Point2, AnyToolOf, Contribution as Contribution$1, ContributionChrome as ContributionChrome$1, Tool as Tool$1, ToolDef as ToolDef$1 } from '@weasel-js/routing';
 import { P as Path } from './path-JEV2c5If.js';
-import { ResolvedRun, TextStyle, TextVerticalAlign } from '@weasel-js/text';
-import { Mat3 } from '@weasel-js/geom';
 import { ReactNode } from 'react';
 import * as _weasel_js_history from '@weasel-js/history';
 import { Op, History, SerializedHistory } from '@weasel-js/history';
-import { a as SceneAdapter, L as LayoutStrategy, b as LayoutDropTargetMode, I as InsertAdapter } from './types-CxC8P6W0.js';
+import { a as SceneAdapter, L as LayoutStrategy, b as LayoutDropTargetMode, I as InsertAdapter } from './types-D-9QWBy5.js';
 import { P as PoseDescriptor } from './poseDescriptor-rZa9W5hJ.js';
-import { ActiveToolContextValue } from '@weasel-js/routing/react';
-import { B as BoundsConstraint, P as PointSnapBehavior } from './types-D_74YlWs.js';
+import { ActiveToolContextValue, ToolsApi as ToolsApi$1, UseToolsOptions as UseToolsOptions$1 } from '@weasel-js/routing/react';
+import { B as BoundsConstraint, P as PointSnapBehavior } from './types-qYpyTAiZ.js';
+import { Mat3 } from '@weasel-js/geom';
+import { ResolvedRun, TextStyle, TextVerticalAlign } from '@weasel-js/text';
+import { CursorSpec } from '@weasel-js/cursor';
+import { ClaimableGesture } from '@weasel-js/gestures';
+import { Reflection } from '@weasel-js/registry';
 
 /**
  * Axis-aligned rectangle pose with optional rotation. The canonical pose
@@ -1101,6 +1104,12 @@ interface ShaderProgramHandle {
  * | TextureHandle           | bind to next tex unit + uniform1i    |
  */
 type ShaderUniform = number | [number, number] | [number, number, number] | [number, number, number, number] | Float32Array | TextureHandle;
+interface ProgramSource {
+    vert: string;
+    frag: string;
+}
+/** Every registered program's GLSL source, keyed by program id. */
+declare const programSourceRegistry: Reflection<ProgramSource>;
 /**
  * Register a custom shader program by id.
  *
@@ -1774,6 +1783,512 @@ interface CullRect {
  */
 declare function cullDrawCommands(cmds: DrawCommand[], transform: GlMat3, rect: CullRect): DrawCommand[];
 
+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`. Recomputed from `boundsOf` over
+     *  every selected id on each read, 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[];
+}
+
+/**
+ * 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.
+     *
+     * A name claims that layer and every layer under it in the `:` namespace, so
+     * `'scene'` covers the `scene:<layerId>` layers a scene with declared layers
+     * draws as — the same set `before`/`after: 'scene'` anchors against. The
+     * separator is required: `'scene'` does not reach `scenery`. A name matching
+     * no layer being drawn is warned about rather than ignored.
+     */
+    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.
+ */
+/** Something outside React whose changes a paint reads — a mode registry, a
+ *  scoping lookup. A notification repaints the canvas; the listener takes no
+ *  arguments and the returned function unsubscribes. */
+interface RedrawSource {
+    subscribe(listener: () => void): () => void;
+}
+/** The `subscribe` for a layer that draws `sources`: it notifies whenever any
+ *  of them does. A thunk is read when the subscription is made. Every layer
+ *  that draws other layers declares this, so wrapping never silences what
+ *  repaints a source. */
+declare function subscribeToSources(sources: readonly {
+    subscribe?: RedrawSource['subscribe'];
+}[] | (() => readonly {
+    subscribe?: RedrawSource['subscribe'];
+}[])): RedrawSource['subscribe'];
+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';
+    /**
+     * Where the layer learns that state `draw` reads, outside the scene and the
+     * props, has changed. The canvas painting it subscribes while the layer is
+     * mounted and repaints on every notification, so a layer reading a mode
+     * registry needs no consumer code to follow a mode switch.
+     */
+    subscribe?: RedrawSource['subscribe'];
+    /**
+     * 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[];
+
 /** Per-axis limits on a view's position. Any side may be left open. */
 interface PanBounds {
     minX?: number;
@@ -2844,6 +3359,33 @@ interface ContentHandlerEntry {
 /** Register a content handler. Returns a disposer that removes it. */
 declare function registerContentHandler(entry: ContentHandlerEntry): () => void;
 
+/**
+ * The lifecycle the ongoing transform actions (`move`, `resize`, `rotate`)
+ * share: what their committed batch is called in history, whether it is
+ * recorded at all, and the callbacks fired as the gesture opens and closes.
+ *
+ * Move and rotate read it from their binding's params; resize reads it from
+ * the `resizePolicy` dep, where the rest of its options already live.
+ */
+
+/** The lifecycle options, as a binding's params or the resize policy carry
+ *  them. */
+interface GestureLifecycleOptions {
+    /** History label for the committed batch. Unset, the batch takes its first
+     *  op's label (a layout drop or a behavior names its own), else the
+     *  action's. */
+    label?: string;
+    /** Commit through `scene.untracked`: the edit lands, but no undo entry
+     *  records it and the consumer `applyOps` hook is bypassed. Unset, any
+     *  behavior's `defaultTransient: true` turns it on. */
+    transient?: boolean;
+    /** Fired once the gesture starts changing poses, with the ids it moves. */
+    onGestureStart?(ids: string[]): void;
+    /** Fired once per `onGestureStart`: `true` when the gesture wrote to the
+     *  document, `false` on cancel, abort, or a release with nothing to write. */
+    onGestureEnd?(committed: boolean): void;
+}
+
 /** 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
@@ -3239,7 +3781,7 @@ interface InsertDep {
  * 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> {
+interface ResizePolicy<TPose> extends GestureLifecycleOptions {
     /** Bounds-frame constraints. Constrained to `TPose extends Bounds` since
      *  constraints read/write `{x,y,width,height}`. For non-rect TPose pass `[]`. */
     constraints: TPose extends Bounds ? BoundsConstraint<TPose>[] : never[];
@@ -3309,7 +3851,7 @@ interface ClipboardDep {
 /**
  * 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.
+ * paths via `splitPathBySegment`, and applies the result as one undoable batch.
  */
 interface SliceDep {
     commit(a: Point2, b: Point2): void;
@@ -3446,7 +3988,7 @@ declare module '@weasel-js/routing' {
          * 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
+         * scans the scene, splits crossed paths via `splitPathBySegment`, and
          * applies the result as one undoable batch.
          *
          * Optional: when absent, `sliceAction` is a no-op.
@@ -3513,6 +4055,32 @@ declare module '@weasel-js/routing' {
     }
 }
 
+/**
+ * The routing types that carry an overlay, bound to the kit's `RenderLayer`.
+ *
+ * `@weasel-js/routing` never reads an overlay — it collects the live ones and
+ * hands them back in scope order — so it leaves the element type open. What a
+ * weasel canvas draws is a `RenderLayer`, and every kit call site should see
+ * that rather than `unknown`, so core binds the parameter once, here, and
+ * re-exports these names under the ones they have always had.
+ */
+
+/** What a canvas overlay is, at this layer. */
+type Overlay = RenderLayer<unknown>;
+declare module '@weasel-js/routing' {
+    interface OverlaySchema {
+        overlay: RenderLayer<unknown>;
+    }
+}
+type Contribution = Contribution$1<Overlay>;
+type ContributionChrome = ContributionChrome$1<Overlay>;
+type Tool<TScratch = unknown> = Tool$1<TScratch, Overlay>;
+type AnyTool = AnyToolOf<Overlay>;
+type ToolDef<TScratch = void> = ToolDef$1<TScratch, Overlay>;
+type ToolsApi = ToolsApi$1<Overlay>;
+type UseToolsOptions = UseToolsOptions$1<Overlay>;
+declare const useTools: (opts: UseToolsOptions) => ToolsApi;
+
 /** Options for stroke tessellation. */
 interface StrokeOptions {
     flattenTolerance?: number;
@@ -3572,4 +4140,4 @@ declare function vignette({ amount, feather }: {
     feather?: number;
 }): Effect[];
 
-export { type DerivedDep as $, type SliceDep as A, type VertexColorChannel as B, type CullRect as C, type DrawCommand as D, type Effect as E, type InsertExtras as F, type GlMat3 as G, type SerializedScene as H, IDENTITY_COLOR_MATRIX as I, type GeometryProjection as J, type ContentHandlerEntry as K, type SvgIngestOptions as L, type Mesh as M, type Node as N, type PanBounds as O, type PathDrawCommand as P, type Animator as Q, type RenderTarget as R, SPRITE_STRIDE as S, type TextDrawCommand as T, ColorOverrideRegistry as U, type ViewAnimationOptions as V, WeaselRenderer as W, type UseSceneOptions as X, type SceneRegistry as Y, type RegisteredOp as Z, type PoseOverrides as _, type GroupDrawCommand as a, type StaggerDelay as a$, type ViewportDims as a0, type ViewApi as a1, ShaderProgram as a2, type BooleansAdapter as a3, type UseAnimatorOptions as a4, type SpringPresetName as a5, type EasingSpec as a6, type AnimationHandle as a7, type SampledTrack as a8, type AddLayerSpec as a9, type InterpolatorFactory as aA, type Keyframe as aB, type LassoSelectDep as aC, type LayerRecord as aD, type LayoutDep as aE, type LeafNode as aF, type LoopFactory as aG, type LoopOptions as aH, type NestedTimeline as aI, type NodeAtPointDep as aJ, type PhysicsHandle as aK, type PhysicsOptions as aL, PointerContextProvider as aM, type PointerContextValue as aN, type PointerWorldPos as aO, type PoseAdapter as aP, type PoseClosure as aQ, type PoseOverride as aR, RECT_POSE_COMPOSITION as aS, RIGID_POSE_COMPOSITION as aT, type ResizePolicy as aU, SPRING_PRESETS as aV, type SerializedNode as aW, type SnapDep as aX, type SpringOptions as aY, type SpringPreset as aZ, type StaggerBuilder as a_, type AddNodeSpec as aa, type AnimateToBoundsOptions as ab, type AreaSelectDep as ac, type BezierEasing as ad, type BooleanOp as ae, type BooleanOpResult as af, type ClipboardDep as ag, type ClipboardIngestCtx as ah, type ColorOverride as ai, type ColorOverrideFn as aj, type ContainerNode as ak, type DecayLoopConfig as al, type DecayOptions as am, EASINGS as an, type EasingFn as ao, type EasingName as ap, type EditAnchorsDep as aq, type EventBooking as ar, type EventBookingHandle as as, type EventTrack as at, type FitViewToBoundsOptions as au, IDENTITY_POSE_COMPOSITION as av, type IngestCtx as aw, type IngestionDep as ax, type InsertDep as ay, type Interpolate as az, type ImageDrawCommand as b, fitViewToBounds as b$, type StaggerFactory as b0, type StaggerOptions as b1, type StaggerPerItem as b2, type StaggerSpringPoseOptions as b3, type StaggerTweenOptions as b4, type SvgUnpacker as b5, type SystemLayerRecord as b6, type SystemLayerSpec as b7, type TextEditDep as b8, type TimelineClock as b9, easeInExpo as bA, easeInOut as bB, easeInOutBack as bC, easeInOutBounce as bD, easeInOutCirc as bE, easeInOutCubic as bF, easeInOutElastic as bG, easeInOutExpo as bH, easeInOutQuad as bI, easeInOutQuart as bJ, easeInOutQuint as bK, easeInOutSine as bL, easeInQuad as bM, easeInQuart as bN, easeInQuint as bO, easeInSine as bP, easeOut as bQ, easeOutBack as bR, easeOutBounce as bS, easeOutCirc as bT, easeOutCubic as bU, easeOutElastic as bV, easeOutExpo as bW, easeOutQuad as bX, easeOutQuart as bY, easeOutQuint as bZ, easeOutSine as b_, type TimelineEvent as ba, type TimelineHandle as bb, type TimelineOptions as bc, type TimelineTrack as bd, type Track as be, type TweenLoopOptions as bf, type TweenOptions as bg, type UserLayerRecord as bh, VIEW_ANIMATION_KEY as bi, type ViewAnimationApi as bj, type ViewChannel as bk, applyBooleanOp as bl, asNodeId as bm, composeRectPose as bn, composeRigidPose as bo, composeWorldPose as bp, createPointerStore as bq, cubicBezierEasing as br, decomposeRectPose as bs, decomposeRigidPose as bt, easeIn as bu, easeInBack as bv, easeInBounce as bw, easeInCirc as bx, easeInCubic as by, easeInElastic as bz, type ImageMinification as c, linear as c0, rebaseLocalPose as c1, registerContentHandler as c2, resolveEasing as c3, resolveStrokeWidth as c4, translateRectPose as c5, useDecayLoop as c6, usePointerContext as c7, usePointerPosition as c8, useViewAnimation as c9, useViewAnimationOn as ca, worldPoseLookup as cb, ShaderCompileError as d, type ShaderDrawCommand as e, type ShaderProgramHandle as f, type ShaderUniform as g, type SolidPaint as h, type SpriteSheet as i, type SpritesDrawCommand as j, type StrokeOptions as k, type WeaselRendererOptions as l, blur as m, buildGradientRamp as n, cullDrawCommands as o, frameRect as p, mat3 as q, registerEffect as r, registerProgram as s, tessellateStroke as t, vignette as u, viewToMat3 as v, type Scene as w, type RectPose as x, type InertiaConfig as y, type PoseComposition as z };
+export { type InsertExtras as $, type Scene as A, type RectPose as B, type CullRect as C, type DrawCommand as D, type Effect as E, type InertiaConfig as F, type GlMat3 as G, type GestureLifecycleOptions as H, IDENTITY_COLOR_MATRIX as I, type PoseComposition as J, type SliceDep as K, type ToolsApi as L, type Mesh as M, type Node as N, type Tool as O, type PathDrawCommand as P, type Contribution as Q, type RenderTarget as R, SPRITE_STRIDE as S, type TextDrawCommand as T, type LayerHit as U, type ViewAnimationOptions as V, WeaselRenderer as W, type ChromeState as X, type VertexColorChannel as Y, type RedrawSource as Z, type LayerGroup as _, type GroupDrawCommand as a, type LoopFactory as a$, type SerializedScene as a0, type GeometryProjection as a1, type ContentHandlerEntry as a2, type SvgIngestOptions as a3, type AnyTool as a4, type PanBounds as a5, type Animator as a6, ColorOverrideRegistry as a7, type UseSceneOptions as a8, type SceneRegistry as a9, type ColorOverrideFn as aA, type ContainerNode as aB, type ContributionChrome as aC, type CustomPaintContext as aD, type DecayLoopConfig as aE, type DecayOptions as aF, EASINGS as aG, type EasingFn as aH, type EasingName as aI, type EditAnchorsDep as aJ, type EventBooking as aK, type EventBookingHandle as aL, type EventTrack as aM, type FitViewToBoundsOptions as aN, IDENTITY_POSE_COMPOSITION as aO, type IngestCtx as aP, type IngestionDep as aQ, type InsertDep as aR, type Interpolate as aS, type InterpolatorFactory as aT, type Keyframe as aU, type LassoSelectDep as aV, type LayerCommandCache as aW, type LayerDrawFailure as aX, type LayerRecord as aY, type LayoutDep as aZ, type LeafNode as a_, type RegisteredOp as aa, type PoseOverrides as ab, type DerivedDep as ac, type ViewportDims as ad, type ViewApi as ae, type Affordance as af, type AffordanceRegion as ag, type AffordanceBinding as ah, type CommonAffordanceScratch as ai, ShaderProgram as aj, type BooleansAdapter as ak, type UseAnimatorOptions as al, type SpringPresetName as am, type EasingSpec as an, type AnimationHandle as ao, type SampledTrack as ap, type AddLayerSpec as aq, type AddNodeSpec as ar, type AnimateToBoundsOptions as as, type AreaSelectDep as at, type BezierEasing as au, type BooleanOp as av, type BooleanOpResult as aw, type ClipboardDep as ax, type ClipboardIngestCtx as ay, type ColorOverride as az, type ImageDrawCommand as b, easeInOutBack as b$, type LoopOptions as b0, type NestedTimeline as b1, type NodeAtPointDep as b2, type PhysicsHandle as b3, type PhysicsOptions as b4, PointerContextProvider as b5, type PointerContextValue as b6, type PointerWorldPos as b7, type PoseAdapter as b8, type PoseClosure as b9, type Track as bA, type TweenLoopOptions as bB, type TweenOptions as bC, type UseToolsOptions as bD, type UserLayerRecord as bE, VIEW_ANIMATION_KEY as bF, type ViewAnimationApi as bG, type ViewChannel as bH, applyBooleanOp as bI, asNodeId as bJ, composeRectPose as bK, composeRigidPose as bL, composeWorldPose as bM, createPointerStore as bN, cubicBezierEasing as bO, decomposeRectPose as bP, decomposeRigidPose as bQ, drawLayers as bR, drawOneLayer as bS, easeIn as bT, easeInBack as bU, easeInBounce as bV, easeInCirc as bW, easeInCubic as bX, easeInElastic as bY, easeInExpo as bZ, easeInOut as b_, type PoseOverride as ba, RECT_POSE_COMPOSITION as bb, RIGID_POSE_COMPOSITION as bc, type ResizePolicy as bd, SPRING_PRESETS as be, type SerializedNode as bf, type SnapDep as bg, type SpringOptions as bh, type SpringPreset as bi, type StaggerBuilder as bj, type StaggerDelay as bk, type StaggerFactory as bl, type StaggerOptions as bm, type StaggerPerItem as bn, type StaggerSpringPoseOptions as bo, type StaggerTweenOptions as bp, type SvgUnpacker as bq, type SystemLayerRecord as br, type SystemLayerSpec as bs, type TextEditDep as bt, type TimelineClock as bu, type TimelineEvent as bv, type TimelineHandle as bw, type TimelineOptions as bx, type TimelineTrack as by, type ToolDef as bz, type ImageMinification as c, easeInOutBounce as c0, easeInOutCirc as c1, easeInOutCubic as c2, easeInOutElastic as c3, easeInOutExpo as c4, easeInOutQuad as c5, easeInOutQuart as c6, easeInOutQuint as c7, easeInOutSine as c8, easeInQuad as c9, usePointerPosition as cA, useTools as cB, useViewAnimation as cC, useViewAnimationOn as cD, worldPoseLookup as cE, easeInQuart as ca, easeInQuint as cb, easeInSine as cc, easeOut as cd, easeOutBack as ce, easeOutBounce as cf, easeOutCirc as cg, easeOutCubic as ch, easeOutElastic as ci, easeOutExpo as cj, easeOutQuad as ck, easeOutQuart as cl, easeOutQuint as cm, easeOutSine as cn, fitViewToBounds as co, isLayerPainted as cp, isLayerVisible as cq, linear as cr, rebaseLocalPose as cs, registerContentHandler as ct, resolveEasing as cu, resolveStrokeWidth as cv, subscribeToSources as cw, translateRectPose as cx, useDecayLoop as cy, usePointerContext as cz, type ProgramSource as d, ShaderCompileError as e, type ShaderDrawCommand as f, type ShaderProgramHandle as g, type ShaderUniform as h, type SolidPaint as i, type SpriteSheet as j, type SpritesDrawCommand as k, type StrokeOptions as l, type WeaselRendererOptions as m, blur as n, buildGradientRamp as o, cullDrawCommands as p, frameRect as q, mat3 as r, programSourceRegistry as s, registerEffect as t, registerProgram as u, tessellateStroke as v, viewToMat3 as w, vignette as x, type RenderLayer as y, type Dims as z };