@weasel-js/labkit 1.4.0 → 1.4.2

package/dist/_dts/types-C-gh9Ap-.d.ts

@@ -1,695 +0,0 @@
-/**
- * An invertible mutation. Applied via an adapter; produces an inverse op
- * that, when applied to the same adapter, undoes the original.
- *
- * Adapters are intentionally typed loosely here so different op types can
- * require different adapter capabilities. Each op is responsible for
- * narrowing the adapter via the methods it calls.
- *
- * Lives here rather than in `@weasel-js/core` because an invertible,
- * replayable mutation is a history concept: this package is what pushes ops
- * onto a stack, inverts them, coalesces them, and rebuilds them from a
- * serialized snapshot. Nothing about the shape is core-specific — it names no
- * scene, node, or pose type. Core re-exports it from `core/ops/types` so its
- * own call sites read unchanged.
- */
-interface Op {
-    /** Apply the mutation. Return `false` (or `'noop'`) to signal that
-     *  nothing changed — the history layer then skips pushing an undo
-     *  entry for the batch when *every* op reports no-op. Returning
-     *  `undefined`/`void` means "mutated" (the common case; existing ops
-     *  don't need to change). */
-    apply(adapter: unknown): void | boolean | 'noop';
-    invert(): Op;
-    label?: string;
-    coalesceKey?: string;
-    /** Stable factory name for op-registry lookup. Kit-emitted ops always
-     *  set this; consumer ops without a name can't round-trip through
-     *  `History.serialize()` and are dropped from persisted snapshots. */
-    name?: string;
-    /** Serializable args (JSON / structured-clone-safe) that, paired with
-     *  `name`, reconstruct the op via the registry's `rebuildOp`. */
-    args?: unknown;
-}
-
-/** Options for `history.beginJournal()`. */
-interface BeginJournalOptions {
-    /** Label for the single parent-history entry the journal flushes on commit. */
-    label: string;
-    /** Caller-supplied tag naming what this journal is scoped to — typically the
-     *  id of the node being edited. The history layer only carries it; callers
-     *  read it back off the journal to decide whether a suspended journal
-     *  matches what they are about to edit. */
-    targetId?: string;
-}
-/**
- * A scoped sub-history forked from a `History`, opened by
- * `history.beginJournal()`. Applies, undoes and redoes against the same
- * adapter as its parent, but keeps its entries to itself: `commit` flushes the
- * journal's net forward ops to the parent as one entry, `cancel` rewinds them
- * and contributes nothing. Use it when a self-contained editing session (a
- * text edit, a modal drag) should collapse to a single step in the parent's
- * undo stack while still offering undo *within* the session.
- *
- * A journal is active, suspended or closed. `commit` and `cancel` are
- * terminal; `suspend` lets the parent be used again and can be reversed with
- * `history.resumeJournal()`. Every mutating method throws when the journal is
- * not active.
- */
-interface Journal {
-    readonly targetId: string | undefined;
-    readonly forkedAtEntryId: number;
-    applyBatch(ops: Op[], label: string): void;
-    undo(): void;
-    redo(): void;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    entries(): {
-        undo: HistoryEntry[];
-        redo: HistoryEntry[];
-    };
-    commit(label: string): void;
-    cancel(): void;
-    suspend(): void;
-    isActive(): boolean;
-}
-
-/** Wire form of a single op inside a serialized history. The pair
- *  `(name, args)` reconstructs a live `Op` via the op-factory registry. */
-interface SerializedOp {
-    name: string;
-    args: unknown;
-}
-/** Wire form of one history entry. `forwardOps` / `baseOps` mirror the
- *  in-memory entry's fields (see `Entry` above) but only carry the
- *  serializable `(name, args)` projection of each op. */
-interface SerializedHistoryEntry {
-    id: number;
-    label: string;
-    forwardOps: SerializedOp[];
-    baseOps: SerializedOp[];
-    selectionBefore?: readonly string[];
-    selectionAfter?: readonly string[];
-}
-/** Snapshot of an entire `History` instance. Designed to live alongside the
- *  scene snapshot in IDB so a reload restores the undo / redo stacks to
- *  exactly where they were. */
-interface SerializedHistory {
-    version: 1;
-    undoStack: SerializedHistoryEntry[];
-    /** Stored newest-first, mirroring the in-memory stack so a deserialized
-     *  history matches the original's `entries().redo` ordering. */
-    redoStack: SerializedHistoryEntry[];
-    nextEntryId: number;
-    /** Entries dropped because at least one of their ops lacked a `name`
-     *  and therefore couldn't round-trip through the op-factory registry.
-     *  Always present (zero when nothing was dropped) so callers can detect
-     *  loss without parsing the debug log. */
-    droppedEntries: number;
-}
-/** Read-only view of a history entry exposed via `History.entries()`. */
-interface HistoryEntry {
-    /** Stable monotonic id (preserved across coalesce merges). */
-    id: number;
-    /** Human-readable label (the `label` arg passed to `applyOps`). */
-    label: string;
-    /** Push/last-coalesce timestamp (ms). */
-    timestamp: number;
-    /** Set of node ids touched by any op in this entry. Populated from ops
-     *  whose `args` carry an `id` field (transform, setPath, reparent) or a
-     *  `node.id` field (insert, delete). Ops without a recognisable id field
-     *  contribute nothing. May be `undefined` for deserialized entries
-     *  restored from an older snapshot that predates this field. */
-    touchedIds?: ReadonlySet<string>;
-    /** Selection restored when this entry is undone. */
-    selectionBefore?: readonly string[];
-    /** Selection restored when this entry is redone. */
-    selectionAfter?: readonly string[];
-}
-/** Op-batched undo/redo controller returned by `createHistory`. */
-interface History {
-    apply(op: Op, label?: string): void;
-    applyOps(ops: Op[], label: string): void;
-    undo(): void;
-    redo(): void;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    /** Number of entries on the undo stack (O(1); `entries().undo.length`
-     *  without materializing the views). */
-    undoDepth(): number;
-    /** Number of entries on the redo stack (O(1)). */
-    redoDepth(): number;
-    clear(): void;
-    /** Snapshot of the current undo + redo stacks. `undo` is oldest→newest
-     *  (i.e. the last element is what `undo()` would pop next); `redo` is
-     *  also oldest→newest from the user's perspective (i.e. the *first*
-     *  element is what `redo()` would pop next — see implementation note).
-     *  Callers should treat the arrays as immutable. */
-    entries(): {
-        undo: HistoryEntry[];
-        redo: HistoryEntry[];
-    };
-    /** Walk the history forward/back until exactly `n` entries are on the
-     *  undo stack (0 ≤ n ≤ entries().undo.length + entries().redo.length).
-     *  Equivalent to repeated `undo()`/`redo()` calls but doesn't bother
-     *  rebuilding entry snapshots between steps. No-op if already at `n`. */
-    goto(n: number): void;
-    /** Monotonic counter bumped on every push/undo/redo/clear/coalesce.
-     *  Cheap to read; callers use it as a React dep to detect changes. */
-    getVersion(): number;
-    /** Subscribe to history changes. Fires after every push/undo/redo/
-     *  clear/coalesce. Returns an unsubscribe fn. */
-    subscribe(listener: () => void): () => void;
-    /** Snapshot the undo + redo stacks in a structured-clone-safe form.
-     *  Entries whose ops aren't all kit-registered (i.e. any op missing a
-     *  `name`) are dropped from the snapshot with a debug-level log — they
-     *  can't round-trip, so we omit them rather than emit a half-restorable
-     *  entry. The in-memory stacks aren't modified. */
-    serialize(): SerializedHistory;
-    /** Replace the current undo + redo stacks with the deserialized contents
-     *  of `snapshot`. Ops are rebuilt via the `rebuildOp` option when
-     *  provided, then the global registry; unknown names become no-op
-     *  placeholders so stack ordering survives across kit-version skew.
-     *  Bumps `version` and notifies subscribers exactly once. */
-    restore(snapshot: SerializedHistory): void;
-    /** Push an entry whose ops have already been applied to the adapter.
-     *  Unlike `applyOps`, does NOT call `op.apply()`. Used by Journal.commit
-     *  to flush a session's net forward ops to the parent as one entry without
-     *  re-mutating the scene. */
-    recordEntry(ops: Op[], label: string, options?: RecordEntryOptions): void;
-    /** Concatenated forwardOps of every undo-stack entry, in order. Snapshot
-     *  of "what changes are currently applied via this history" — useful for
-     *  Journal.commit to flush to a parent, and for any caller that wants to
-     *  diff against a baseline. */
-    allForwardOps(): Op[];
-    /** The id that will be assigned to the *next* pushed entry. Stable
-     *  monotonic counter; callers use it to tag a fork point (see Journal). */
-    currentEntryId(): number;
-    /** Open a scoped sub-history. All apply/undo/redo on the returned Journal
-     *  affect the same adapter; on commit, the Journal's net forward ops are
-     *  flushed to this History as one entry. See spec docs/superpowers/specs/
-     *  2026-05-24-modality-design.md for the full lifecycle. */
-    beginJournal(opts: BeginJournalOptions): Journal;
-    /** Re-activate a suspended journal. Throws if the journal was committed or
-     *  cancelled (those are terminal), or if a different journal is currently
-     *  active — at most one journal writes to the adapter at a time, on resume
-     *  as well as on open. Staleness checking is the caller's
-     *  responsibility — consult `journal.forkedAtEntryId` against
-     *  `currentEntryId()` and your own op-semantic rules to decide whether
-     *  to resume or discard before calling this. */
-    resumeJournal(journal: Journal): void;
-}
-/** Options for `recordEntry`. */
-interface RecordEntryOptions {
-    /** Selection as of before the already-applied ops ran. `recordEntry` is
-     *  called after the fact, so the live selection has moved on by then and
-     *  the engine cannot sample it — a caller that wants undo to restore the
-     *  selection captures it when the batch opens and passes it here. */
-    selectionBefore?: readonly string[];
-}
-
-/**
- * Path data model. Vector-graphics primitive used kit-wide as the canonical
- * shape (replacing per-shape ad-hoc poses). SVG-style command stream so we
- * cover lines, polygons, beziers, and multi-contour shapes (think the inner
- * hole of an "O") under one type.
- *
- * Storage: command codes in a `Uint8Array`, parameters in a `Float32Array`.
- * Each command consumes a fixed number of float coords from the parameter
- * array; the parser walks both arrays in lockstep. This keeps interaction
- * hot loops monomorphic and keeps GC pressure low under heavy edits.
- *
- * Two path subtypes are distinguished at the type level so common-case
- * machinery (selection AABBs, area-select intersection, hit-testing rect
- * silhouettes) can short-circuit on `RectPath` without paying the polygon
- * kernel cost. Polymorphic kernels accept either via the `Path` union and
- * dispatch on `kind`.
- */
-
-/** Fill rule used by polygon path hit-testing and `ctx.fill()`. */
-type PathFillRule = 'nonzero' | 'evenodd';
-/**
- * Polygon path with arbitrary contours and optional bezier segments.
- * Multi-contour: each `M` opens a new subpath; `Z` closes the current one.
- * Open subpaths (no `Z`) render as polylines and don't contribute to fills.
- */
-interface PolygonPath {
-    kind: 'polygon';
-    commands: Uint8Array;
-    coords: Float32Array;
-    fillRule: PathFillRule;
-}
-/**
- * Axis-aligned rectangle. Fast path for the (very common) case where the
- * shape is just a rect — preserves O(1) bounds and hit-test, avoids the
- * polygon kernel entirely. Promote to `PolygonPath` only when the shape
- * grows beyond what a rect can express.
- */
-interface RectPath {
-    kind: 'rect';
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/** Canonical path shape — either an axis-aligned rect (fast path) or a polygon command stream. */
-type Path = PolygonPath | RectPath;
-
-/**
- * Axis-aligned rectangle pose with optional rotation. The canonical pose
- * shape used by `composeRectPose` and the `unionBounds` helper. Rotation is
- * in radians, pivoted on the unrotated AABB center; absent === 0. Kit-side
- * code that consumes rotation already reads `pose.rotation ?? 0`
- * (`wrapNodeOutput`, `rotate/handle.ts`, `pathInWorld.ts`), so
- * the slot exists on every default scene whether or not the consumer
- * populates it.
- */
-interface RectPose {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    /** Rotation in radians around the unrotated AABB center. Absent === 0. */
-    rotation?: number;
-}
-/**
- * # SceneNode — the thing in the scene
- *
- * A `SceneNode` is the single canonical unit of a weasel scene. Everything
- * the user sees on the canvas — a shape, a group, an annotation, a tile —
- * is one of these. Containers and leaves are both nodes; the kit has no
- * other concept of "scene element."
- *
- * ## Three orthogonal slots
- *
- * Every node carries three independent slots, plus its tree position:
- *
- *   - **`data: TData`** — app-defined payload. The kit never inspects it.
- *     Color, label, kind, glyph, sample-rate, whatever the app's domain
- *     calls for. Mutated via `Scene.update(id, { data })`.
- *
- *   - **`pose: TPose`** — local transform, relative to the node's direct
- *     parent (or world, for root nodes). Default `RectPose` is
- *     `{ x, y, width, height }`, but `TPose` is fully generic so apps can
- *     use rotated rects, paths, ellipses, etc. The kit composes world
- *     poses via `composeWorldPose` when rendering / hit-testing / snapping.
- *
- *   - **`layer: TLayer`** — a string tag associating the node with a
- *     visual `RenderLayer` at draw time. Separate from `LayerRecord` (the
- *     per-layer visible/locked metadata held by the `Scene`).
- *
- * Tree position lives on the node itself: every node has a `parent` (or
- * `null` for roots), and `ContainerNode` adds an ordered `children: NodeId[]`.
- *
- * ## Identity is by `NodeId`, not by reference
- *
- * Nodes are addressed by `NodeId` everywhere outside the scene tree:
- * selection is `NodeId[]`, ops reference `NodeId`s, adapter methods accept
- * `string` ids and look up the node on demand. The `Node` object itself is
- * a snapshot of current state — don't hold references to it across scene
- * updates; look up by id when you need the latest.
- *
- * Picking helpers (`pickBest`, `pickEvery`) likewise return ids, not nodes —
- * they're hit-testing primitives that stay ignorant of node payload shape.
- *
- * ## Vocabulary
- *
- * The kit-internal name is `Node`; the public re-export is `SceneNode`
- * (avoids collision with DOM `Node` at call sites). Adapter methods speak
- * the same vocabulary: `getNode`, `getNodes`, `insertNode`, `removeNode`,
- * `cloneNode`, `addNode`. Older code, demos, and comments may still say
- * "object" or "item" — those are historical aliases for the same concept.
- */
-/** Opaque branded id. Treat as opaque outside the kit. */
-type NodeId = string & {
-    readonly __brand: 'NodeId';
-};
-interface NodeBase<TData, TLayer extends string, TPose> {
-    id: NodeId;
-    layer: TLayer;
-    pose: TPose;
-    data: TData;
-    parent: NodeId | null;
-    /** Nodes whose poses this node's geometry is computed from. Fixed at add
-     *  time. Absent or empty means the node's geometry is authored, which is the
-     *  normal case. */
-    dependsOn?: readonly NodeId[];
-    /** Computes this node's path from its dependencies' poses, in `dependsOn`
-     *  order. A dependency that has been removed arrives as `undefined`.
-     *  Returning `null` means "nothing to draw right now". Re-evaluated when a
-     *  dependency's world pose changes, never authored. Absolute-pose `Scene`
-     *  makes that the dependency's own pose, and an ancestor's move reaches it as
-     *  a `setPose` of its own from the container cascade.
-     *  `node` is deliberately widened: naming `TData`/`TLayer` here puts them in
-     *  a contravariant position, making `Scene` invariant in both and breaking
-     *  assignment kit-wide. The cost is that a `derivePath` casts to read `node.data`. */
-    derivePath?: (node: Node<unknown, string, TPose>, deps: readonly (TPose | undefined)[]) => Path | null;
-}
-/** A node with no children — a shape, a label, an image. */
-interface LeafNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
-    kind: 'leaf';
-}
-/** A node with an ordered list of children. This is the real group: what
- *  Cmd+G creates, what SVG `<g>` round-trips to. A container has its own pose,
- *  which its children's poses are relative to, and may optionally clip them. */
-interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
-    kind: 'container';
-    children: NodeId[];
-    /** Optional clip-path source. Re-evaluated each render. Returning `null`
-     *  means "no clip for this container right now"; an empty / zero-area path
-     *  means "clip everything out" (children render nowhere). When set, the
-     *  renderer rasterizes the returned path into the stencil buffer and
-     *  paints descendants only where it covers. */
-    clipFromPose?: (pose: TPose) => Path | null;
-}
-/** A node in the scene tree: either a leaf or a container. Re-exported
- *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */
-type Node<TData, TLayer extends string, TPose = RectPose> = LeafNode<TData, TLayer, TPose> | ContainerNode<TData, TLayer, TPose>;
-interface LayerRecordBase<TLayer extends string> {
-    id: TLayer;
-    visible: boolean;
-    locked: boolean;
-}
-/** A layer declared when the scene was created. Fixed set, no display name —
- *  these are the kit's own render bands, not something a user manages. */
-interface SystemLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
-    kind: 'system';
-}
-/** A layer the user created and can rename, reorder or delete. */
-interface UserLayerRecord<TLayer extends string> extends LayerRecordBase<TLayer> {
-    kind: 'user';
-    name: string;
-}
-/** Per-layer metadata held by the scene: whether it is visible and locked,
- *  and where it sits in the render stack. Distinct from a node's `layer` tag,
- *  which merely names one of these. */
-type LayerRecord<TLayer extends string> = SystemLayerRecord<TLayer> | UserLayerRecord<TLayer>;
-/** What `Scene.add` needs to mint a node. Everything except the id is
- *  required; the id is generated unless one is supplied. */
-interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
-    kind: 'leaf' | 'container';
-    layer: TLayer;
-    pose: TPose;
-    data: TData;
-    parent?: NodeId | null;
-    index?: number;
-    /** Explicit id wins over the Scene's `generateId` and the kit default. */
-    id?: NodeId;
-    /** Only meaningful when `kind === 'container'`. Attach a clip-path function
-     *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
-    clipFromPose?: (pose: TPose) => Path | null;
-    /** Mirrors `SceneNode.dependsOn`. */
-    dependsOn?: readonly NodeId[];
-    /** Mirrors `SceneNode.derivePath`. Taken as a live function; its registry key is
-     *  looked up from it, never passed in. */
-    derivePath?: (node: Node<unknown, string, TPose>, deps: readonly (TPose | undefined)[]) => Path | null;
-}
-/** A custom scene mutation registered with `Scene.registerOp`: how to apply
- *  it and how to undo it. The pair is what makes it participate in history. */
-interface RegisteredOp<P> {
-    apply: (payload: P) => void;
-    revert: (payload: P) => void;
-}
-/** One of the layers a scene is created with. */
-interface SystemLayerSpec<TLayer extends string> {
-    id: TLayer;
-    visible?: boolean;
-    locked?: boolean;
-}
-/** Argument to `Scene.addLayer`. Always produces a `UserLayerRecord`
- *  (`kind: 'user'`). */
-interface AddLayerSpec<TLayer extends string> {
-    id: TLayer;
-    name: string;
-    /** Default `true`. */
-    visible?: boolean;
-    /** Default `false`. */
-    locked?: boolean;
-    /** Render-stack position. Default: top of stack (highest render index). */
-    index?: number;
-}
-/** JSON-serializable shape of a Scene's current state. Produced by
- *  `scene.toJSON()`; consumed by `sceneFromJSON()`. Function fields
- *  (e.g., `clipFromPose`) appear as string keys (`clipFromPoseKey`) and
- *  are resolved through `SceneRegistry` at load time. */
-interface SerializedScene<TData, TLayer extends string, TPose> {
-    version: 1;
-    systemLayers: readonly SystemLayerSpec<TLayer>[];
-    nodes: readonly SerializedNode<TData, TLayer, TPose>[];
-}
-/** JSON-serializable shape of a single node. Mirrors `AddNodeSpec` but
- *  with function fields replaced by registry keys. */
-interface SerializedNode<TData, TLayer extends string, TPose> {
-    id: string;
-    kind: 'leaf' | 'container';
-    layer: TLayer;
-    pose: TPose;
-    data: TData;
-    /** Parent id; omitted for roots. */
-    parent?: string;
-    /** Registry key for the container's clip-path factory.
-     *  Containers only; omitted when the container has no clip. */
-    clipFromPoseKey?: string;
-    /** Ids this node's geometry derives from. Omitted when it derives from nothing. */
-    dependsOn?: readonly string[];
-    /** Registry key for the node's `derivePath` function. Omitted when it has none. */
-    derivePathKey?: string;
-}
-/**
- * One node's ephemeral presentation override — what a frame loop wants to say
- * about a node without saying it about the document.
- *
- * Not document content: never recorded in history, never in `toJSON`, and
- * writing one does not bump `Scene.getVersion()`. Hoist one entry per node and
- * mutate it in place on a frame loop; `PoseOverrides.commit()` is what makes a
- * mutation visible.
- */
-interface PoseOverride<TPose> {
-    /** Replaces the node's document pose everywhere the render and hit-test
-     *  paths read one, including the clip a container derives from its pose.
-     *  Resolved by `effectivePose` — reading `node.pose` directly is how those
-     *  paths came to disagree about where a node is. */
-    pose?: TPose;
-    /** Multiplied into the node's painted alpha, on top of any `alphaFor`. */
-    alpha?: number;
-}
-/**
- * The scene's ephemeral per-node overrides — see {@link PoseOverride}.
- *
- * The intended shape of a frame is: `set` each node once, mutate the entries
- * in place per frame, `commit()` once. `commit` is not optional bookkeeping —
- * the painter memo keys on pose *reference*, so a mutation without a commit
- * paints the previous frame with no error.
- *
- * To promote a frame to document state (dropping a drag, baking an animation),
- * write it once through `Scene.setPose` and `clear` the override.
- */
-interface PoseOverrides<TPose> {
-    /** Store `entry` for `id` **by reference**; the caller keeps mutating it. */
-    set(id: NodeId, entry: PoseOverride<TPose>): void;
-    get(id: NodeId): PoseOverride<TPose> | undefined;
-    has(id: NodeId): boolean;
-    /** The overridden ids, as a snapshot array. */
-    ids(): readonly NodeId[];
-    clear(id: NodeId): void;
-    clearAll(): void;
-    /** Publish this frame's in-place mutations: invalidate the painter memo for
-     *  every overridden node, then notify subscribers. */
-    commit(): void;
-    /** Notified after every write. The canvas uses this to repaint without a
-     *  scene version bump. */
-    subscribe(fn: () => void): () => void;
-    /** Monotonic write counter. A snapshot for observers that poll. */
-    getGeneration(): number;
-}
-/**
- * The kit-owned scene tree: nodes, layers, and the undo history over both.
- *
- * A scene is logical, not visual — it says what exists and where, and nothing
- * about how it is painted. Every mutating method is undoable, and reads are
- * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids
- * across mutations, not node objects.
- *
- * Three type parameters keep it domain-agnostic: `TData` is the app's payload,
- * which the kit never inspects; `TPose` is the transform shape, `RectPose` by
- * default; `TLayer` is the union of layer names.
- */
-interface Scene<TData, TLayer extends string, TPose = RectPose> {
-    readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;
-    readonly roots: readonly NodeId[];
-    readonly layers: readonly LayerRecord<TLayer>[];
-    get(id: NodeId): Node<TData, TLayer, TPose> | undefined;
-    childrenOf(id: NodeId): readonly NodeId[];
-    ancestorsOf(id: NodeId): readonly NodeId[];
-    renderOrder(): Iterable<NodeId>;
-    /** The same layer-major sequence as {@link Scene.renderOrder}, as the nodes
-     *  themselves. Prefer this wherever the ids are only going to be resolved
-     *  back to nodes: the traversal already holds them, and re-looking each one
-     *  up was ~40% of the area hit-test's per-node cost. Cached until a
-     *  structural edit, so repeat calls hand back the same array — a snapshot,
-     *  not a live view, and not yours to mutate. */
-    renderOrderNodes(): readonly Node<TData, TLayer, TPose>[];
-    add(spec: AddNodeSpec<TData, TLayer, TPose>): NodeId;
-    /** Delete `id`, its **entire subtree**, and **everything that derives from**
-     *  any of those nodes — a node listing one of them in `dependsOn` goes too,
-     *  along with its own subtree, transitively. A dependent can live anywhere in
-     *  the tree, so this deletes nodes the caller never named and may unlink
-     *  several disjoint subtrees at once. Recorded as one undoable step; `undo()`
-     *  restores every one of them where it was, child order intact. */
-    remove(id: NodeId): void;
-    /** {@link remove} over several roots at once, as a **single** undoable step.
-     *  Ids resolve against the tree as it stands at the call, so an id that
-     *  another one would cascade away is absorbed rather than removed twice —
-     *  which is what makes it safe to pass a whole selection. Throws if any id is
-     *  not in the scene; an empty list does nothing and records no step. */
-    removeMany(ids: readonly NodeId[]): void;
-    update(id: NodeId, patch: {
-        data: TData;
-    }): void;
-    setPose(id: NodeId, pose: TPose): void;
-    /** Retag `id` to `layer`. On a **container this cascades**: every descendant
-     *  is moved to the same layer, recorded as a **single** undo step.
-     *
-     *  Invariants:
-     *  - **Layer floor** — a child may not render below its parent, so retagging
-     *    to a layer *below* the node's parent throws. Retagging to the parent's
-     *    layer or any higher one is allowed; a node with no parent is
-     *    unconstrained.
-     *  - **No-op elision** — setting the layer a node already has does nothing
-     *    and pushes **no** history entry. */
-    setLayer(id: NodeId, layer: TLayer): void;
-    /** Reparent `id` under `parent` (or to a root when `parent` is `null`) at
-     *  `index` within the new sibling list, appending when `index` is omitted.
-     *  Siblings are reindexed. Recorded as one undoable step.
-     *
-     *  Rejected (throws) when:
-     *  - `parent` exists but is a **leaf**, not a container;
-     *  - the move would form a **cycle** — `parent` is `id` itself or one of
-     *    `id`'s own descendants;
-     *  - it would drop `id` **below its new parent's layer** (child may not
-     *    render below its parent).
-     *
-     *  `move(id, null)` — detaching to a root — is always allowed regardless of
-     *  layer, since a root has no parent to render beneath. */
-    move(id: NodeId, parent: NodeId | null, index?: number): void;
-    /** Shift `id` to `index` within its **current** parent's child list. Unlike
-     *  {@link move}, the parent never changes — only sibling order. */
-    reorder(id: NodeId, index: number): void;
-    setLayerVisible(layer: TLayer, visible: boolean): void;
-    setLayerLocked(layer: TLayer, locked: boolean): void;
-    addLayer(spec: AddLayerSpec<TLayer>): void;
-    /** Drop a user layer and every node tagged to it, as one undoable step.
-     *  Removal cascades, so this also deletes nodes **on other layers** that
-     *  derive from a node on this one. */
-    removeLayer(layer: TLayer): void;
-    renameLayer(layer: TLayer, name: string): void;
-    moveLayer(layer: TLayer, index: number): void;
-    registerOp<P>(kind: string, handler: RegisteredOp<P>): void;
-    recordOp<P>(op: {
-        kind: string;
-        payload: P;
-    }): void;
-    /** Install (or clear) the active-journal accessor after scene construction.
-     *  Useful when the journal source (typically a mode machine) is built
-     *  with `scene.history` as a dependency — a chicken-and-egg situation
-     *  where the accessor can't be passed in via `UseSceneOptions`.
-     *
-     *  Pass `null` to detach. Overrides any `getActiveJournal` set in
-     *  `UseSceneOptions`. */
-    setActiveJournalAccessor(fn: (() => Journal | null) | null): void;
-    /** Apply a batch of ops with journal-aware routing.
-     *
-     *  - **Without active journal** (or no `getActiveJournal` in options):
-     *    the ops themselves are recorded as one undo entry on the scene's own
-     *    history, rebound to `adapter` — undo replays each op's `invert()`
-     *    against that same adapter. Consecutive `applyBatch` entries can
-     *    coalesce via matching op `coalesceKey`s when the scene opts into
-     *    `coalesceWindowMs`.
-     *  - **With active journal**: routes ops to `journal.applyBatch(ops, label)`.
-     *    The scene's history recording is suppressed for the duration so the
-     *    journal's inner history — not the scene's undo stack — tracks the batch.
-     *    Mutations still happen on `adapter` / scene state.
-     *
-     *  `adapter` must be the same adapter the ops expect (typically a
-     *  `SceneCanvasAdapter`). Pass `this` from `sceneToAdapter` or a compatible
-     *  adapter. */
-    applyBatch(ops: Op[], label: string, adapter: unknown): void;
-    /** The transient set of active ids — "operate on these N as a unit".
-     *  Shared by every view over this scene unless a view supplies its own
-     *  (see `CanvasView.selection`). Not document content: it never appears
-     *  in `toJSON`. It does ride on history entries, so undo and redo put
-     *  back the selection an edit was made under; changing it is never an
-     *  undo step of its own. */
-    getSelection(): readonly NodeId[];
-    setSelection(ids: readonly NodeId[]): void;
-    /** Per-node pose / alpha overrides the render and hit-test paths read
-     *  through. Like {@link Scene.getSelection} this is not document content:
-     *  writes are never recorded, never serialized, and do not bump
-     *  {@link Scene.getVersion}. See {@link PoseOverrides}. */
-    readonly overrides: PoseOverrides<TPose>;
-    undo(): boolean;
-    redo(): boolean;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    batch<T>(label: string, fn: () => T): T;
-    /** Read-only snapshot of every history entry currently reachable from
-     *  the present state. Oldest applied first, then redoable entries in
-     *  the order they'd be re-applied. Each entry id is stable. */
-    historyEntries(): readonly {
-        id: string;
-        label: string;
-    }[];
-    /** Index of the "current state". Equals the count of applied entries;
-     *  `0` means "nothing applied" (initial). */
-    historyIndex(): number;
-    /** Jump to the given history index by calling undo/redo repeatedly.
-     *  Clamps to [0, total]. Returns true if any movement occurred. */
-    jumpToHistoryIndex(index: number): boolean;
-    /** Snapshot the undo/redo history in a JSON-serializable form (the
-     *  engine's `SerializedHistory`). Entries containing any nameless op are
-     *  dropped (hand-rolled anonymous ops passed to `applyBatch`); kit and
-     *  consumer-registered ops always carry names. Payload JSON-safety
-     *  (e.g. typed arrays inside poses) is the caller's concern. Do not call
-     *  mid-`batch` — the open batch's ops are not yet recorded. */
-    serializeHistory(): SerializedHistory;
-    /** Replace the undo/redo history from a `serializeHistory()` snapshot.
-     *  Call on a scene whose node/layer state already matches the snapshot's
-     *  head state (i.e. right after `loadState` from the paired scene
-     *  snapshot); node state is NOT mutated. Ops re-registered via
-     *  `registerOp` before this call round-trip; unknown kinds become no-op
-     *  placeholders; external ops rebuild via the global op-factory registry
-     *  and replay against the `setHistoryAdapter` accessor. Restored entries
-     *  never coalesce with new ones. Notifies once. Do not call mid-`batch`:
-     *  the stacks are replaced underneath the open batch, whose eventual
-     *  flush would graft onto (and evict against) the restored stacks. */
-    restoreHistory(snapshot: SerializedHistory): void;
-    /** Install (or clear with `null`) the accessor for the adapter that
-     *  RESTORED external ops (recorded via `applyBatch`, rebuilt from a
-     *  `restoreHistory` snapshot) apply against on undo/redo. Resolved lazily
-     *  at each apply, so wiring order relative to `restoreHistory` doesn't
-     *  matter. Live `applyBatch` entries are unaffected (they bind their
-     *  call-site adapter). If unset when a restored op applies, the op is a
-     *  debug-warned no-op. */
-    setHistoryAdapter(fn: (() => unknown) | null): void;
-    /** Snapshot the current scene state to a JSON-serializable shape.
-     *  History (undo/redo stacks) is NOT captured. Function fields like
-     *  `ContainerNode.clipFromPose` are translated to string keys via the
-     *  scene's registry; throws if any function field has no matching key. */
-    toJSON(): SerializedScene<TData, TLayer, TPose>;
-    /** Replace this scene's entire node + layer state in place from a snapshot
-     *  produced by `toJSON()`. Unlike `sceneFromJSON`, the existing Scene
-     *  instance is preserved — holders such as `<SceneCanvas>` keep their
-     *  reference. History (undo/redo) is cleared, matching `sceneFromJSON`.
-     *  Bumps `getVersion()` and notifies subscribers exactly once.
-     *
-     *  Throws on an unsupported version or unknown registry/layer ids; on a
-     *  malformed snapshot the scene is left empty or partially populated (callers should treat a
-     *  `loadState` throw as fatal and reload). Snapshots from `toJSON()` are
-     *  always well-formed. */
-    loadState(json: SerializedScene<TData, TLayer, TPose>): void;
-    subscribe(listener: () => void): () => void;
-    /** Monotonically increasing version. Snapshot for `useSyncExternalStore`. */
-    getVersion(): number;
-}
-
-export type { History as H, Node as N, Op as O, Path as P, Scene as S, NodeId as a };