@weasel-js/core 1.2.0 → 1.3.0-pre.0

package/dist/{registry-l3JX0Z6b.d.ts → registry-BU1_3L_C.d.ts}

@@ -1,17 +1,17 @@
-import { N as NodeId, R as RectPose, S as Scene } from './types-C2R2bjxf.js';
-import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-BhrifbZ1.js';
+import { N as NodeId, R as RectPose, S as Scene } from './types-DIQAisSG.js';
+import { M as ModifierState, A as ActionBehavior, c as ResizeAnchor, R as ResizePose, B as BoundsConstraint, P as PointSnapBehavior } from './types-miXHGrZM.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 { B as Bounds, P as PoseProjection } from './geometry-C56YbnfD.js';
-import { F as FillStyle, S as Stroke } from './paint-types-1fUdZUaH.js';
-import { D as DrawCommand } from './DrawCommand-uNkv5TjO.js';
+import { D as DrawCommand } from './DrawCommand-BnZyQaDc.js';
+import { B as Bounds, P as PoseProjection, F as FitViewToBoundsOptions, V as ViewportDims } from './geometry-Dtt_k6Dq.js';
+import { FillStyle, Stroke } from '@weasel-js/paint';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { P as Path } from './path-B6MMiodD.js';
+import { P as Path } from './path-JEV2c5If.js';
 import { Op, History } from '@weasel-js/history';
-import { L as LayoutStrategy, I as InsertAdapter } from './types-DbysOO-2.js';
+import { a as SceneAdapter, L as LayoutStrategy, I as InsertAdapter } from './types-XBcDEp3Y.js';
 import { D as DebugSink } from './types-BHK2dkMu.js';
 import { Mat3 } from '@weasel-js/geom';
 
@@ -26,7 +26,8 @@ interface ChromeState {
      *  computable. */
     boundsOf(id: string): Bounds | null;
     /** Multi-union AABB when `multiActive`. Computed lazily from `boundsOf`
-     *  over every selected id; null otherwise. */
+     *  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;
@@ -401,11 +402,19 @@ declare function drawLayers<TData>(layers: RenderLayer<TData>[], data: TData, vi
 /**
  * Resolve one layer's visibility: `alwaysOn` wins, then an explicit entry in
  * `visibility`, then `defaultVisible`, defaulting to shown.
- *
- * Hit-testing asks this too. A layer that is hidden but still claims pointer
- * events is a pointer landing on nothing the user can see.
  */
 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
@@ -671,6 +680,96 @@ type ChromeId = 'selection.outline' | 'selection.resize-handles' | 'selection.ro
  */
 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;
@@ -916,7 +1015,7 @@ type OngoingOverlay = {
      * renderer narrows on `shape` and casts the field shape it expects.
      */
     kind: 'insertPreview';
-    shape: 'rect' | 'ellipse' | 'line' | 'polygon' | 'star' | 'pencil' | 'image';
+    shape: KitInsertShape;
     bounds: {
         x: number;
         y: number;
@@ -1379,6 +1478,499 @@ interface ContentHandlerEntry {
 /** Register a content handler. Returns a disposer that removes it. */
 declare function registerContentHandler(entry: ContentHandlerEntry): () => 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;
+    easing?: EasingFn;
+}
+/** 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`. */
+    events: {
+        t: number;
+        fire: () => 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;
+    /** 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;
+}
+
+/** 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;
+    /** 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?: EasingFn;
+    /** 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;
+    /** 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?: EasingFn;
+    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?: EasingFn;
+    /** `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?: EasingFn;
+    /** 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
@@ -1640,16 +2232,16 @@ interface GeometryProjection {
     }, m: Mat3): unknown | null;
 }
 
-/** Minimal view API the action layer consumes. May be refined later. */
+/** 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. Receives no args; the consumer reads its own bounds
-     *  + host dims and dispatches `setView(...)`. */
-    recenter?(): 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
@@ -1658,6 +2250,13 @@ interface ViewApi {
         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;
 }
 /**
  * Adapter dep for `areaSelectAction`.
@@ -2609,14 +3208,13 @@ interface DispatcherContext {
     /** Platform flag for `mod` shorthand resolution. */
     isMac: boolean;
     /**
-     * Thunk returning a fresh `RuleCtx` for the current frame. When
-     * supplied, the dispatcher filters matched candidates by their
-     * declared `Action.eligible` rule (omitted => always eligible).
-     * When omitted, no eligibility filtering is applied — preserves
-     * backward compatibility for callers (tests, legacy harnesses) that
-     * don't wire up chrome-caps state.
+     * 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;
+    getRuleCtx?: () => RuleCtx | undefined;
 }
 /**
  * Handle returned by `Dispatcher.beginUiOngoing()` for driving an
@@ -3088,17 +3686,14 @@ interface ActionsRegistry {
 declare function ActionsProvider({ children }: {
     children: ReactNode;
 }): ReactElement;
-/**
- * @experimental
- * Returns the parent `ActionsRegistry`, or `null` when no provider is in scope.
- */
 declare function useActionsRegistry(): ActionsRegistry | null;
 /**
  * @experimental
- * Register an `Action` for the lifetime of the calling component. No-op when
- * no `ActionsProvider` is in scope. Re-registers on `action` reference change
- * (consumers should memoize stable identities to avoid churn).
+ * 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 BooleanOp as $, type Action as A, type BooleansAdapter as B, type Condition as C, type Dims as D, type Eligibility as E, ALWAYS as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, type ActionDeps as J, ActionDisabledReason as K, type LayerHit as L, type ActionEnabledResult as M, type ActionEntry as N, type OverlayPosition as O, ActionsProvider as P, ActiveToolContextProvider as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, ActiveToolContextProviderIfRoot as W, type ActiveToolContextProviderProps as X, type ActiveToolContextValue as Y, type AreaSelectDep as Z, type BindingOpts as _, type DeviceProfile as a, drawOneLayer as a$, type BooleanOpResult as a0, type BoundGesture as a1, type BuildRuleCtxArgs as a2, type ClaimableGesture as a3, type ClipboardDep as a4, type ClipboardIngestCtx as a5, type CustomPaintContext as a6, type DepName as a7, type DepRegistry as a8, DepRegistryProvider as a9, type ResizePolicy as aA, type ResolveAllOptions as aB, type ResolveOnlyResult as aC, type ResolvedCandidate as aD, type SelectionExtendKey as aE, type SelectionMode as aF, type Selector as aG, type SnapDep as aH, type SvgUnpacker as aI, type TextEditDep as aJ, type ToolCtx as aK, type ToolModifiers as aL, type ToolPresentation as aM, type ToolSlot as aN, type UiOngoingControl as aO, type ViewApi as aP, actionBindings as aQ, applyBooleanOp as aR, buildRuleCtx as aS, clipboardCopyAction as aT, clipboardCutAction as aU, composeRectPose as aV, composeWorldPose as aW, createDispatcher as aX, decomposeRectPose as aY, describeRule as aZ, drawLayers as a_, type DispatcherContext as aa, type DragSample as ab, type EditAnchorsDep as ac, type GestureBinding as ad, IDENTITY_POSE_COMPOSITION as ae, type ImmediateInvoker as af, type IngestCtx as ag, type IngestionDep as ah, type InsertDep as ai, type InvocationCtx as aj, type Invoker as ak, type LassoSelectDep as al, type LayerCommandCache as am, type LayoutDep as an, type MatchResult as ao, NEVER as ap, type NodeAtPointDep as aq, type OngoingHandle as ar, type OngoingInvoker as as, type OngoingOverlay as at, type Point2 as au, PointerContextProvider as av, type PointerContextValue as aw, type PointerWorldPos as ax, type PoseAdapter as ay, type PoseComposition as az, type DetectedDeviceFacts as b, enterTextEditAction as b0, evaluate as b1, evaluateEnabled as b2, isLayerVisible as b3, rebaseLocalPose as b4, registerContentHandler as b5, resolveParams as b6, sliceAction as b7, specificity as b8, translateRectPose as b9, useAction as ba, useActionsRegistry as bb, useActiveToolContext as bc, useDepRegistry as bd, useDepSource as be, useOptionalActiveToolContext as bf, useOptionalDepRegistry as bg, usePointerContext as bh, useSelection as bi, worldPoseLookup as bj, type Rule as c, type RuleCtx as d, type ChromeCtx as e, type ChromeId as f, type DepSchema as g, type ActionsRegistry as h, type AffordanceHit as i, type Dispatcher as j, type ToolDef as k, type ViewportToolDef as l, type AnyTool as m, type ToolKeybinding as n, type ChromeState as o, type SelectionApi as p, type ContentHandlerEntry as q, type SvgIngestOptions as r, type ActionsProp as s, type Affordance as t, type AffordanceRegion as u, type AffordanceBinding as v, type CommonAffordanceScratch as w, type BindingScope as x, type Contribution as y, type ScopedBinding as z };
+export { ALWAYS as $, type Action as A, type BuiltinShapeToolId as B, type Condition as C, type Dims as D, ColorOverrideRegistry as E, type BooleansAdapter as F, type GeometryProjection as G, type HotkeyTrigger as H, type InsertExtras as I, type EasingFn as J, type SpringPresetName as K, type LayerHit as L, type SpringPreset as M, type UseAnimatorOptions as N, type OverlayPosition as O, type AnimationHandle as P, type VertexColorChannel as Q, type RenderLayer as R, type SliceDep as S, type Tool as T, type UseSelectionOptions as U, type VisibilityRules as V, type SampledTrack as W, type Eligibility as X, type BindingScope as Y, type Contribution as Z, type ScopedBinding as _, type DeviceProfile as a, type ResolveOnlyResult as a$, type ActionDeps as a0, ActionDisabledReason as a1, type ActionEnabledResult as a2, type ActionEntry as a3, ActionsProvider as a4, ActiveToolContextProvider as a5, ActiveToolContextProviderIfRoot as a6, type ActiveToolContextProviderProps as a7, type ActiveToolContextValue as a8, type AnimateToBoundsOptions as a9, type Interpolate as aA, type InterpolatorFactory as aB, type InvocationCtx as aC, type Invoker as aD, KIT_SHAPE_KINDS as aE, type Keyframe as aF, type LassoSelectDep as aG, type LayerCommandCache as aH, type LayoutDep as aI, type LoopFactory as aJ, type LoopOptions as aK, type MatchResult as aL, NEVER as aM, type NestedTimeline as aN, type NodeAtPointDep as aO, type OngoingHandle as aP, type OngoingInvoker as aQ, type PhysicsHandle as aR, type PhysicsOptions as aS, type Point2 as aT, PointerContextProvider as aU, type PointerContextValue as aV, type PointerWorldPos as aW, type PoseAdapter as aX, type PoseComposition as aY, type ResizePolicy as aZ, type ResolveAllOptions as a_, type AreaSelectDep as aa, type BindingOpts as ab, type BooleanOp as ac, type BooleanOpResult as ad, type BoundGesture as ae, type BuildRuleCtxArgs as af, type ClaimableGesture as ag, type ClipboardDep as ah, type ClipboardIngestCtx as ai, type ColorOverride as aj, type ColorOverrideFn as ak, type CustomPaintContext as al, type DecayOptions as am, type DepName as an, type DepRegistry as ao, DepRegistryProvider as ap, type DispatcherContext as aq, type DragSample as ar, type EditAnchorsDep as as, type EventTrack as at, type GestureBinding as au, IDENTITY_POSE_COMPOSITION as av, type ImmediateInvoker as aw, type IngestCtx as ax, type IngestionDep as ay, type InsertDep as az, type DetectedDeviceFacts as b, worldPoseLookup as b$, type ResolvedCandidate as b0, type SelectionExtendKey as b1, type SelectionMode as b2, type Selector as b3, type SnapDep as b4, type SpringOptions as b5, type StaggerBuilder as b6, type StaggerDelay as b7, type StaggerFactory as b8, type StaggerOptions as b9, composeWorldPose as bA, createDispatcher as bB, decomposeRectPose as bC, describeRule as bD, drawLayers as bE, drawOneLayer as bF, enterTextEditAction as bG, evaluate as bH, evaluateEnabled as bI, isLayerPainted as bJ, isLayerVisible as bK, rebaseLocalPose as bL, registerContentHandler as bM, resolveParams as bN, sliceAction as bO, specificity as bP, translateRectPose as bQ, useAction as bR, useActionsRegistry as bS, useActiveToolContext as bT, useDepRegistry as bU, useDepSource as bV, useOptionalActiveToolContext as bW, useOptionalDepRegistry as bX, usePointerContext as bY, useSelection as bZ, useViewAnimation as b_, type StaggerPerItem as ba, type StaggerSpringPoseOptions as bb, type StaggerTweenOptions as bc, type SvgUnpacker as bd, type TextEditDep as be, type TimelineHandle as bf, type TimelineOptions as bg, type TimelineTrack as bh, type ToolCtx as bi, type ToolModifiers as bj, type ToolPresentation as bk, type ToolSlot as bl, type Track as bm, type TweenLoopOptions as bn, type TweenOptions as bo, type UiOngoingControl as bp, VIEW_ANIMATION_KEY as bq, type ViewAnimationApi as br, type ViewApi as bs, type ViewChannel as bt, actionBindings as bu, applyBooleanOp as bv, buildRuleCtx as bw, clipboardCopyAction as bx, clipboardCutAction as by, composeRectPose as bz, type Rule as c, 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 ContentHandlerEntry as s, type SvgIngestOptions as t, type ActionsProp as u, type Animator as v, type Affordance as w, type AffordanceRegion as x, type AffordanceBinding as y, type CommonAffordanceScratch as z };