@weasel-js/core 1.15.0 → 1.15.2

package/dist/core/scene/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../src/core/scene/types.ts"],"sourcesContent":["import type { History, SerializedHistory } from '@weasel-js/history';\nimport type { SerializedSceneHistory } from './historyForm';\nimport type { ParallaxOpts } from '../viewport/parallax';\nimport type { UnitScope } from '@weasel-js/quantity';\nimport type { LayoutStrategy } from '../../layout/types';\nimport type { AddLayerSpec, LayerRecord, SystemLayerRecord, SystemLayerSpec, UserLayerRecord } from './layerTypes';\nimport type { LayoutFrame, LayoutMove } from './layoutTypes';\nimport type { PoseComposition } from './composeFrame';\nimport type { PoseRemoval, PoseWrite, PoseWriteOrigin, RemovedNode, ScenePoseReports } from './poseWrites';\nimport type { PoseHold, PoseOverride, PoseOverrides, ShownOverride } from './poseOverrideTypes';\nimport type { SceneChanges } from './sceneChanges';\nimport type {\n  SavedScene, SerializedLayer, SerializedNode, SerializedNodeV1, SerializedScene, SerializedSceneV1, SerializedSceneV2,\n} from './serializedTypes';\nimport type { SceneOptions, UseSceneOptions } from './useSceneOptions';\nimport type { SceneDocValues } from './docValues';\nimport type { SceneDeclaredFieldSetters } from './declaredFieldSetters';\nimport type { SceneEditPasses } from './editPass';\nimport type { SceneScroll } from './scrollOffsets';\nimport type { SceneArrivalHandler } from './arrivalTypes';\nimport type { RegisteredOp } from './registeredOp';\nimport type { SpecsFromSerializedOptions } from './serialization';\nimport type { RectPose } from '../geometry/rectPose';\nimport type { SceneRegistry } from './sceneRegistry';\nexport type { RectPose, RegisteredOp, SceneArrivalHandler, SceneOptions, UseSceneOptions };\nexport type { AddLayerSpec, LayerRecord, SystemLayerRecord, SystemLayerSpec, UserLayerRecord };\nexport type { PoseRemoval, PoseWrite, PoseWriteOrigin, RemovedNode, ScenePoseReports };\nexport type { LayoutFrame, LayoutMove, PoseHold, PoseOverride, PoseOverrides, ShownOverride, SerializedLayer, SerializedNode, SerializedNodeV1, SerializedScene, SerializedSceneV1, SerializedSceneV2, SavedScene };\n\n/**\n * # SceneNode — the thing in the scene\n *\n * Everything the user sees on the canvas — a shape, a group, an annotation,\n * a tile — is a node. Marks and groups are both nodes; the kit has no\n * other concept of \"scene element.\"\n *\n * Every node carries three independent slots, plus its tree position:\n *\n *   - **`data: TData`** — app-defined payload. The kit never inspects it.\n *   - **`pose: TPose`** — local transform, relative to the node's direct\n *     parent (or world, for root nodes).\n *   - **`layer: TLayer`** — a string tag associating the node with a\n *     visual `RenderLayer` at draw time. Separate from `LayerRecord` (the\n *     per-layer visible/locked metadata held by the `Scene`).\n *\n * Nodes are addressed by `NodeId` everywhere outside the scene tree. Don't\n * hold references to a `Node` object across scene updates; look up by id\n * when you need the latest.\n *\n * The kit-internal name is `Node`; the public re-export is `SceneNode`\n * (avoids collision with DOM `Node` at call sites).\n */\n\n/** Opaque branded id. Treat as opaque outside the kit. */\nimport type { NodeId } from '@weasel-js/routing';\nexport type { NodeId, SceneRegistry };\n\n/** Brand a string as a NodeId. */\nexport const asNodeId = (s: string): NodeId => s as NodeId;\n\nimport type { DerivedDep, Bivariant, DerivePathFn, DerivePoseFn, ClipFromPoseFn, CopiesFromPoseFn } from './nodeFnTypes';\nexport type { DerivedDep, Bivariant, DerivePathFn, DerivePoseFn, ClipFromPoseFn, CopiesFromPoseFn };\n\n/** A clip a node declares by name rather than by function: see `SceneNode.clip`. */\nexport type NodeClip = 'outline';\n\ninterface NodeBase<TData, TLayer extends string, TPose> {\n  id: NodeId;\n  layer: TLayer;\n  pose: TPose;\n  data: TData;\n  parent: NodeId | null;\n  /** Nodes whose poses this node's geometry is computed from. Fixed at add\n   *  time. Absent or empty means the node's geometry is authored, which is the\n   *  normal case.\n   *\n   *  `'children'` means \"my own children, in child order\" — a container that\n   *  hugs its contents, which a fixed id list cannot express because\n   *  reparenting would have to maintain it. The two forms differ in lifetime\n   *  as well as in membership: deleting a node deletes everything that names\n   *  it in `dependsOn`, but a container outlives the children it derives\n   *  from — an emptied group is still a group. */\n  dependsOn?: readonly NodeId[] | 'children';\n  /** Whether the hit-test walk can return this node. Default `true`; `false`\n   *  makes it transparent to picking, so a click on it lands on whatever is\n   *  behind — normally its own container.\n   *\n   *  For content a container owns rather than content the user selects on its\n   *  own: the label inside a box, a body's rows. It does not hide the node\n   *  from anything else — it still paints, still clips, and a consumer can\n   *  still select it by id. */\n  pickable?: boolean;\n  /** Not drawn, with its whole subtree: picking, area selection, select-all,\n   *  snapping and the selection pass over it, and an SVG export writes it with\n   *  `display=\"none\"`. Absent means shown; `Scene.isHidden` folds in its\n   *  ancestors' flags and its layer's visibility. */\n  hidden?: boolean;\n  /** Out of reach, with its whole subtree: still drawn, but picking and area\n   *  selection pass over it, the selection drops it, and every edit to it\n   *  throws, as on a locked layer. Absent means unlocked; `Scene.isLocked`\n   *  folds in its ancestors' and its layer's. */\n  locked?: boolean;\n  /** Computes this node's path from its dependencies, in `dependsOn` order —\n   *  each one the node and the pose it is painted at.\n   *  A dependency that has been removed arrives as `undefined`.\n   *  Returning `null` means \"nothing to draw right now\". Re-evaluated when a\n   *  dependency's world pose changes, never authored. */\n  derivePath?: DerivePathFn<TPose, TData, TLayer>;\n  /** Computes this node's pose from its dependencies' poses, the same way\n   *  `derivePath` computes its path — same `dependsOn` list, same\n   *  registry-keyed serialization.\n   *\n   *  Where a derived path is resolved at paint time and reaches only the\n   *  painter, a derived pose is what the node *is* at: it feeds bounds,\n   *  hit-testing, selection chrome, snapping and layout, and every reader\n   *  gets it through `effectivePose`. A pose override still wins over it.\n   *\n   *  Returning `null` means \"I have nothing to derive from right now\", and\n   *  the node falls back to its authored `pose`. `setPose` on a derived node\n   *  still writes that authored pose; it is simply not what anything reads. */\n  derivePose?: DerivePoseFn<TPose, TData, TLayer>;\n  /** Ordered child ids. Absent until the node gets its first child. */\n  children?: NodeId[];\n  /** Optional clip-path source. Re-evaluated each render. Returning `null`\n   *  means \"no clip for this node right now\"; an empty / zero-area path\n   *  means \"clip everything out\" (children render nowhere). Wins over `clip`. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\n  /** `'outline'` clips the children to this node's own outline: a mark's\n   *  painter silhouette, or for a group the silhouette of its `data.path`.\n   *  Absent, and with no `clipFromPose`, the children are not clipped. */\n  clip?: NodeClip;\n  /** Draws the whole subtree again under each affine it returns, on top of\n   *  the original, which still draws once as authored. The copies are paint,\n   *  not nodes: nothing stores them, so they follow every edit to the\n   *  children, and a pick that lands on one answers with the child it copies.\n   *  A copy is a copy of the clipped content — the clip travels with it.\n   *  Re-evaluated each render; `null` or `[]` draws no copies. */\n  copiesFromPose?: CopiesFromPoseFn<TPose, TData, TLayer>;\n  /** Its children are the operands of its own geometry, drawn only through\n   *  it: the render walk paints none of them, and a press, a region select\n   *  or select-all reaches one only while this node, or a group inside it, is\n   *  entered. A node that consumes its children is entered as a group is.\n   *  The boolean group (`booleanGroupFields`) is the kit's one. */\n  consumesChildren?: boolean;\n  /** How this node arranges its children. Whenever the node's\n   *  child set or order changes, its bounds change size, or a child's pose is\n   *  written, the scene hands the change to the strategy — `depart` for children that left it,\n   *  `arrive` for children that joined it, `childPoses` otherwise — and records the poses it writes in the same\n   *  undo entry as the change. A drag reads it too: it is the layout `move`\n   *  reflows and drops against. */\n  layout?: LayoutStrategy<TPose>;\n  /** The units its children are shown, typed and snapped in (their poses stay\n   *  in world units), and what one base unit is worth in the enclosing scope's.\n   *  It covers the children, not the node; `sceneUnitScopes` reads the chain. */\n  units?: UnitScope;\n}\n\n/** A node that is drawn and picked as one thing — a shape, a label, an image.\n *  It may still hold children, which are what it is made of. */\nexport interface MarkNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'mark';\n}\n\n/** A node the user gathers things into: what Cmd+G creates, what SVG `<g>`\n *  round-trips to. An emptied group is still a group. */\nexport interface GroupNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'group';\n}\n\n/** A node in the scene tree: either a mark or a group. Re-exported\n *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */\nexport type Node<TData, TLayer extends string, TPose = RectPose> =\n  | MarkNode<TData, TLayer, TPose>\n  | GroupNode<TData, TLayer, TPose>;\n\n/** What `Scene.add` needs to mint a node. Everything except the id is\n *  required; the id is generated unless one is supplied. */\nexport interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {\n  kind: 'mark' | 'group';\n  layer: TLayer;\n  pose: TPose;\n  data: TData;\n  parent?: NodeId | null;\n  index?: number;\n  /** Explicit id wins over the Scene's `generateId` and the kit default. */\n  id?: NodeId;\n  /** Mirrors `SceneNode.pickable`. Omit for the default, which is pickable. */\n  pickable?: boolean;\n  /** Mirrors `SceneNode.hidden`. */\n  hidden?: boolean;\n  /** Mirrors `SceneNode.locked`. */\n  locked?: boolean;\n  /** Attach a clip-path function to the node; mirrors `SceneNode.clipFromPose`. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\n  /** Mirrors `SceneNode.clip`. */\n  clip?: NodeClip;\n  /** Mirrors `SceneNode.consumesChildren`. */\n  consumesChildren?: boolean;\n  /** Mirrors `SceneNode.copiesFromPose`. */\n  copiesFromPose?: CopiesFromPoseFn<TPose, TData, TLayer>;\n  /** Mirrors `SceneNode.dependsOn`. */\n  dependsOn?: readonly NodeId[] | 'children';\n  /** Mirrors `SceneNode.derivePath`. Taken as a live function; its registry key is\n   *  looked up from it, never passed in. */\n  derivePath?: DerivePathFn<TPose, TData, TLayer>;\n  /** Mirrors `SceneNode.derivePose`, on the same terms as `derivePath`. */\n  derivePose?: DerivePoseFn<TPose, TData, TLayer>;\n  /** Mirrors `SceneNode.layout`. */\n  layout?: LayoutStrategy<TPose>;\n  /** Mirrors `SceneNode.units`. */\n  units?: UnitScope;\n}\n\n/**\n * The kit-owned scene tree: nodes, layers, and the undo history over both.\n *\n * A scene is logical, not visual — it says what exists and where, and nothing\n * about how it is painted. Every mutating method is undoable, and reads are\n * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids\n * across mutations, not node objects.\n *\n * Three type parameters keep it domain-agnostic: `TData` is the app's payload,\n * which the kit never inspects; `TPose` is the transform shape, `RectPose` by\n * default; `TLayer` is the union of layer names.\n */\nexport interface Scene<TData, TLayer extends string, TPose = RectPose>\n  extends ScenePoseReports<TPose, Node<TData, TLayer, TPose>>, SceneChanges, SceneDocValues, SceneEditPasses, SceneDeclaredFieldSetters, SceneScroll {\n  // Reads\n  readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;\n  readonly roots: readonly NodeId[];\n  readonly layers: readonly LayerRecord<TLayer>[];\n  /** The registry this scene resolves node functions against — the consumer's entries over the kit's. */\n  readonly registry: SceneRegistry<TPose, TData, TLayer>;\n  /** See {@link SceneOptions.composition}. */\n  readonly composition: PoseComposition<TPose>;\n  get(id: NodeId): Node<TData, TLayer, TPose> | undefined;\n  /** A token for the node `id` names right now, for telling one node from a\n   *  later one that reuses its id. It holds for as long as the node stays in\n   *  the scene, whatever edits it takes, and is different every time the id\n   *  enters the scene — by `add`, by an undo or redo that brings it back, or\n   *  by `loadState`. `undefined` when `id` is not in the scene. Compare tokens\n   *  for equality only; their order means nothing. */\n  incarnation(id: NodeId): number | undefined;\n  childrenOf(id: NodeId): readonly NodeId[];\n  ancestorsOf(id: NodeId): readonly NodeId[];\n  renderOrder(): Iterable<NodeId>;\n  /** The same layer-major sequence as {@link Scene.renderOrder}, as the nodes\n   *  themselves. Prefer this wherever the ids are only going to be resolved\n   *  back to nodes. Cached until a structural edit, so repeat calls hand back\n   *  the same array — a snapshot, not a live view, and not yours to mutate. */\n  renderOrderNodes(): readonly Node<TData, TLayer, TPose>[];\n  /** The nodes on one layer, in render order. Cached alongside\n   *  {@link Scene.renderOrderNodes} until a structural edit. A snapshot, not\n   *  a live view, and not yours to mutate. An unknown layer id yields an\n   *  empty array. */\n  nodesOnLayer(layer: TLayer): readonly Node<TData, TLayer, TPose>[];\n\n  /** A fresh id from this scene's `generateId`, or the kit default: the id\n   *  `add` would give a spec with none. For code that has to name a node\n   *  before it exists, such as one building an insert op. */\n  mintId(): NodeId;\n\n  // Mutations (all auto-undoable)\n  add(spec: AddNodeSpec<TData, TLayer, TPose>): NodeId;\n  /** Delete `id`, its **entire subtree**, and **everything that derives from**\n   *  any of those nodes — a node listing one of them in `dependsOn` goes too,\n   *  along with its own subtree, transitively. A dependent can live anywhere in\n   *  the tree, so this deletes nodes the caller never named and may unlink\n   *  several disjoint subtrees at once. Recorded as one undoable step; `undo()`\n   *  restores every one of them where it was, child order intact. */\n  remove(id: NodeId): void;\n  /** {@link remove} over several roots at once, as a **single** undoable step.\n   *  Ids resolve against the tree as it stands at the call, so an id that\n   *  another one would cascade away is absorbed rather than removed twice —\n   *  which is what makes it safe to pass a whole selection. Throws if any id is\n   *  not in the scene; an empty list does nothing and records no step. */\n  removeMany(ids: readonly NodeId[]): void;\n  /** Every node {@link removeMany} would take if given `ids`: each id, its\n   *  subtree, everything deriving from any of those, and those nodes' subtrees\n   *  in turn. Ids not in the scene come back unchanged.\n   *\n   *  A set, not a restore order: a dependent can be reached before the parent\n   *  it sits under, which is also in the closure. */\n  removalClosure(ids: readonly NodeId[]): readonly NodeId[];\n  update(id: NodeId, patch: { data: TData }): void;\n  setPose(id: NodeId, pose: TPose): void;\n  /** Retag `id` to `layer`. On a **container this cascades**: every descendant\n   *  is moved to the same layer, recorded as a **single** undo step.\n   *\n   *  Invariants:\n   *  - **Layer floor** — a child may not render below its parent, so retagging\n   *    to a layer *below* the node's parent throws. Retagging to the parent's\n   *    layer or any higher one is allowed; a node with no parent is\n   *    unconstrained.\n   *  - **No-op elision** — setting the layer a node already has does nothing\n   *    and pushes **no** history entry. */\n  setLayer(id: NodeId, layer: TLayer): void;\n  /** Point `id` at a different set of dependencies — retargeting an edge's end\n   *  onto another node, or switching a container between an id list and\n   *  `'children'`. Recorded as one undoable step.\n   *\n   *  Order is significant: a derivation reads its dependencies positionally,\n   *  so `[b, a]` is not `[a, b]`. Ids need not be in the scene — a declared\n   *  dependency that appears later invalidates the node when it does, the same\n   *  as one declared at `add`. Passing `undefined` drops the declaration, after\n   *  which nothing cascades the node away.\n   *\n   *  **No-op elision** — declaring what the node already declares does nothing\n   *  and pushes no history entry. */\n  setDependsOn(id: NodeId, dependsOn: readonly NodeId[] | 'children' | undefined): void;\n  /** Give container `id` a different layout — a strategy, its key in\n   *  `SceneRegistry.layout`, or `null` for none — and re-arrange its children\n   *  under it, as one undoable step. Throws for a mark, or a key the registry\n   *  does not hold. A registered layout is recorded by its key, so a\n   *  serialized history restores it; an unregistered one lives only as long\n   *  as the session.\n   *\n   *  **No-op elision** — setting the layout a container already has does\n   *  nothing and pushes no history entry. */\n  setLayout(id: NodeId, layout: LayoutStrategy<TPose> | string | null): void;\n  /** Reparent `id` under `parent` (or to a root when `parent` is `null`) at\n   *  `index` within the new sibling list, appending when `index` is omitted.\n   *  Siblings are reindexed. Recorded as one undoable step.\n   *\n   *  Rejected (throws) when:\n   *  - the move would form a **cycle** — `parent` is `id` itself or one of\n   *    `id`'s own descendants;\n   *  - it would drop `id` **below its new parent's layer** (child may not\n   *    render below its parent).\n   *\n   *  `move(id, null)` — detaching to a root — is always allowed regardless of\n   *  layer, since a root has no parent to render beneath. */\n  move(id: NodeId, parent: NodeId | null, index?: number): void;\n  /** Shift `id` to `index` within its **current** parent's child list. Unlike\n   *  {@link move}, the parent never changes — only sibling order. */\n  reorder(id: NodeId, index: number): void;\n  /** Show or hide a layer. Hiding drops its nodes from the selection. */\n  setLayerVisible(layer: TLayer, visible: boolean): void;\n  /** Lock or unlock a layer. A locked layer still paints, but its nodes are\n   *  out of reach: picking and area selection pass over them, the selection\n   *  drops them, and every node mutation on them throws. Locking is never\n   *  blocked by the lock, and neither are the other layer operations. */\n  setLayerLocked(layer: TLayer, locked: boolean): void;\n  /** Set or clear (`undefined`) a layer's parallax — see\n   *  `LayerRecord.parallax`. Undoable; an animation tweening it writes inside\n   *  {@link Scene.untracked} so no frame becomes an undo step. */\n  setLayerParallax(layer: TLayer, parallax: ParallaxOpts | undefined): void;\n  /** Whether `id` is locked: it or an ancestor carries `locked`, or sits on a\n   *  locked layer. A lock covers its whole subtree, whatever layers the\n   *  descendants are tagged to. An id not in the scene is not locked. */\n  isLocked(id: NodeId): boolean;\n  /** Whether `id` is not drawn: its own layer is hidden, or it or an ancestor\n   *  carries `hidden`. A hidden layer hides only the nodes tagged to it. An\n   *  id not in the scene is not hidden. */\n  isHidden(id: NodeId): boolean;\n  /** Hide or show node `id` and its subtree — see `SceneNode.hidden`. One\n   *  undo step; hiding drops the subtree from the selection. Never blocked by\n   *  a lock, and setting what the node already has records nothing. */\n  setHidden(id: NodeId, hidden: boolean): void;\n  /** Lock or unlock node `id` and its subtree — see `SceneNode.locked`. One\n   *  undo step; locking drops the subtree from the selection. Never blocked\n   *  by a lock, and setting what the node already has records nothing. */\n  setLocked(id: NodeId, locked: boolean): void;\n  /** Run `fn` with the lock guard lifted, for a programmatic edit that has to\n   *  reach a locked node. Undo and redo never need it. */\n  unlocked<T>(fn: () => T): T;\n  addLayer(spec: AddLayerSpec<TLayer>): void;\n  /** Drop a user layer and every node tagged to it, as one undoable step.\n   *  Removal cascades, so this also deletes nodes **on other layers** that\n   *  derive from a node on this one. */\n  removeLayer(layer: TLayer): void;\n  renameLayer(layer: TLayer, name: string): void;\n  moveLayer(layer: TLayer, index: number): void;\n\n  // Custom op seam\n  registerOp<P>(kind: string, handler: RegisteredOp<P>): void;\n  recordOp<P>(op: { kind: string; payload: P }): void;\n\n  /** Install (or clear with `null`) the active-journal accessor after scene\n   *  construction, for a journal source built with `scene.history` as a\n   *  dependency. Overrides any `getActiveJournal` set in `UseSceneOptions`. */\n  setActiveJournalAccessor(\n    fn: (() => import('@weasel-js/history').Journal | null) | null,\n  ): void;\n\n  /** Install what the scene does when nodes join a container, replacing any\n   *  handler installed before; `null` removes it. Returns a function that\n   *  removes this handler, and does nothing once another has replaced it.\n   *  See {@link SceneArrivalHandler}. */\n  setArrivalHandler(handler: SceneArrivalHandler<TPose> | null): () => void;\n\n  /** Apply a batch of ops against `adapter` as one undo entry.\n   *\n   *  The entry holds the scene writes the ops made, as a direct call records\n   *  them, and beside them any op that wrote no scene state, bound to\n   *  `adapter`. Undo restores those writes; it does not call an op's\n   *  `invert()` or the adapter again. **What an op states is not recorded**:\n   *  one applied over a document that already holds its result, as after an\n   *  `untracked` preview, records a write from that pose to itself, and undo\n   *  goes nowhere. Put the document back first.\n   *\n   *  The entry lands in the open `batch` when there is one, else on the\n   *  active journal, else on the scene's own history, where it can coalesce\n   *  under `coalesceWindowMs` with one whose ops' keys match.\n   *\n   *  Returns false when the arrival handler refused the batch: it is reverted\n   *  and unrecorded. Inside `batch` it is true; that batch may still refuse. */\n  applyBatch(ops: import('core/ops/types').Op[], label: string, adapter: unknown): boolean;\n\n  // Selection\n\n  /** The transient set of active ids — \"operate on these N as a unit\".\n   *  Shared by every view over this scene unless a view supplies its own\n   *  (see `CanvasView.selection`). Not document content: it never appears\n   *  in `toJSON`. It does ride on history entries, so undo and redo put\n   *  back the selection an edit was made under; changing it is never an\n   *  undo step of its own. Removing a node deselects it. */\n  getSelection(): readonly NodeId[];\n  setSelection(ids: readonly NodeId[]): void;\n\n  // Ephemeral presentation state\n\n  /** Per-node pose / alpha / path / data overrides the render and hit-test paths read\n   *  through. Like {@link Scene.getSelection} this is not document content:\n   *  writes are never recorded, never serialized, and do not bump\n   *  {@link Scene.getVersion}. See {@link PoseOverrides}. */\n  readonly overrides: PoseOverrides<TPose, TData>;\n\n  // History\n  /** The scene's undo/redo engine, in the shape `@weasel-js/history` defines.\n   *  Mutating members route through\n   *  the scene's own wrappers, so an undo driven through this bumps\n   *  {@link Scene.getVersion} and notifies subscribers exactly as\n   *  {@link Scene.undo} does; `getVersion` / `subscribe` on it report the\n   *  engine's history version, not the scene's. */\n  readonly history: History;\n  undo(): boolean;\n  redo(): boolean;\n  canUndo(): boolean;\n  canRedo(): boolean;\n  batch<T>(label: string, fn: () => T, options?: import('./recorder').SceneBatchOptions): T;\n  /** The layout group `id` declares, or `null` for a mark or a group with none. */\n  layoutOf(id: NodeId): LayoutStrategy<TPose> | null;\n  /** Run `fn` with every mutation applied but none recorded — for writes\n   *  that are not edits, such as a simulation stepping poses each frame.\n   *  Undo and redo move between recorded states and never restore an\n   *  untracked write; the next recorded change starts from whatever the\n   *  untracked writes left, so undoing it lands there. A `batch` inside\n   *  records nothing; inside a `batch`, these writes stay out of its entry.\n   *  Notifies once, reverts `fn`'s writes if it throws, and throws on\n   *  `applyBatch` and `history.apply` / `applyOps`, which exist to record. */\n  untracked<T>(fn: () => T): T;\n  /** Read-only snapshot of every history entry currently reachable from\n   *  the present state. Oldest applied first, then redoable entries in\n   *  the order they'd be re-applied. Each entry id is stable. */\n  historyEntries(): readonly { id: string; label: string }[];\n  /** Index of the \"current state\". Equals the count of applied entries;\n   *  `0` means \"nothing applied\" (initial). */\n  historyIndex(): number;\n  /** Jump to the given history index, clamped to [0, total]. Returns true\n   *  if any movement occurred. */\n  jumpToHistoryIndex(index: number): boolean;\n\n  // History persistence\n  /** Snapshot the undo/redo history in a JSON-serializable form (the\n   *  engine's `SerializedHistory`, marked with the scene's recorded form).\n   *  An entry holds the scene's own ops, whichever way the edit was made.\n   *  An op handed to `applyBatch` that wrote no scene state is held as\n   *  itself, and an entry with a nameless one is dropped. Payload\n   *  JSON-safety (e.g. typed arrays inside poses) is the caller's concern.\n   *  Do not call mid-`batch` — the open batch's ops are not yet recorded. */\n  serializeHistory(): SerializedSceneHistory;\n  /** Replace the undo/redo history from a `serializeHistory()` snapshot.\n   *  Call on a scene whose node/layer state already matches the snapshot's\n   *  head state (i.e. right after `loadState` from the paired scene\n   *  snapshot); node state is NOT mutated. Ops re-registered via\n   *  `registerOp` before this call round-trip; unknown kinds become no-op\n   *  placeholders; external ops rebuild via the global op-factory registry\n   *  and replay against the `setHistoryAdapter` accessor. Restored entries\n   *  never coalesce with new ones. Notifies once. A snapshot that is not in\n   *  the current recorded form (see `SCENE_HISTORY_FORM`) is dropped:\n   *  the history is left as it was. Do not call mid-`batch`:\n   *  the stacks are replaced underneath the open batch, whose eventual\n   *  flush would graft onto (and evict against) the restored stacks. */\n  restoreHistory(snapshot: SerializedHistory): void;\n  /** Install (or clear with `null`) the accessor for the adapter that\n   *  RESTORED external ops apply against on undo/redo: the ops handed to\n   *  `applyBatch` that wrote no scene state, such as a selection change,\n   *  rebuilt from a `restoreHistory` snapshot. Resolved lazily at each\n   *  apply, so wiring order relative to `restoreHistory` doesn't matter.\n   *  Live `applyBatch` entries are unaffected (they bind their call-site\n   *  adapter). If unset when a restored op applies, the op is a debug-warned\n   *  no-op. */\n  setHistoryAdapter(fn: (() => unknown) | null): void;\n\n  // Serialization\n  /** Snapshot the current scene state to a JSON-serializable shape.\n   *  History (undo/redo stacks) is NOT captured. Function fields like\n   *  `GroupNode.clipFromPose` are translated to string keys via the\n   *  scene's registry; throws if any function field has no matching key. */\n  toJSON(): SerializedScene<TData, TLayer, TPose>;\n  /** Replace this scene's entire node + layer state in place from a snapshot\n   *  produced by `toJSON()`. Unlike `sceneFromJSON`, the existing Scene\n   *  instance is preserved — holders such as `<SceneCanvas>` keep their\n   *  reference. History (undo/redo) is cleared, matching `sceneFromJSON`.\n   *  Bumps `getVersion()` and notifies subscribers exactly once. Selected\n   *  ids the snapshot does not hold leave the selection, and every pose\n   *  override is cleared.\n   *\n   *  Throws inside any other edit — `batch`, `untracked`, `applyBatch`, an\n   *  undo — which would revert to a state this replaces. Throws on an unsupported version or unknown registry/layer ids; on a\n   *  malformed snapshot the scene is left empty or partially populated (callers should treat a\n   *  `loadState` throw as fatal and reload). Snapshots from `toJSON()` are\n   *  always well-formed. `opts` reads it as `specsFromSerialized` does, under the scene's composition. */\n  loadState(\n    json: SavedScene<TData, TLayer, TPose>,\n    opts?: Omit<SpecsFromSerializedOptions<TData, TLayer, TPose>, 'composition'>,\n  ): void;\n\n}\n"],"mappings":";;AA0DA,IAAa,YAAY,MAAsB"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../src/core/scene/types.ts"],"sourcesContent":["import type { History, SerializedHistory } from '@weasel-js/history';\nimport type { SerializedSceneHistory } from './historyForm';\nimport type { ParallaxOpts } from '../viewport/parallax';\nimport type { UnitScope } from '@weasel-js/quantity';\nimport type { LayoutStrategy } from '../../layout/types';\nimport type { AddLayerSpec, LayerRecord, SystemLayerRecord, SystemLayerSpec, UserLayerRecord } from './layerTypes';\nimport type { LayoutFrame, LayoutMove } from './layoutTypes';\nimport type { PoseComposition } from './composeFrame';\nimport type { PoseRemoval, PoseWrite, PoseWriteOrigin, RemovedNode, ScenePoseReports } from './poseWrites';\nimport type { PoseHold, PoseOverride, PoseOverrides, ShownOverride } from './poseOverrideTypes';\nimport type { SceneChanges } from './sceneChanges';\nimport type {\n  SavedScene, SerializedLayer, SerializedNode, SerializedNodeV1, SerializedScene, SerializedSceneV1, SerializedSceneV2,\n} from './serializedTypes';\nimport type { SceneOptions, UseSceneOptions } from './useSceneOptions';\nimport type { SceneDocValues } from './docValues';\nimport type { SceneDeclaredFieldSetters } from './declaredFieldSetters';\nimport type { SceneEditPasses } from './editPass';\nimport type { SceneScroll } from './scrollOffsets';\nimport type { SceneArrivalHandler } from './arrivalTypes';\nimport type { RegisteredOp } from './registeredOp';\nimport type { SpecsFromSerializedOptions } from './serialization';\nimport type { RectPose } from '../geometry/rectPose';\nimport type { SceneRegistry } from './sceneRegistry';\nexport type { RectPose, RegisteredOp, SceneArrivalHandler, SceneOptions, UseSceneOptions };\nexport type { AddLayerSpec, LayerRecord, SystemLayerRecord, SystemLayerSpec, UserLayerRecord };\nexport type { PoseRemoval, PoseWrite, PoseWriteOrigin, RemovedNode, ScenePoseReports };\nexport type { LayoutFrame, LayoutMove, PoseHold, PoseOverride, PoseOverrides, ShownOverride, SerializedLayer, SerializedNode, SerializedNodeV1, SerializedScene, SerializedSceneV1, SerializedSceneV2, SavedScene };\n\n/**\n * # SceneNode — the thing in the scene\n *\n * Everything the user sees on the canvas — a shape, a group, an annotation,\n * a tile — is a node. Marks and groups are both nodes; the kit has no\n * other concept of \"scene element.\"\n *\n * Every node carries three independent slots, plus its tree position:\n *\n *   - **`data: TData`** — app-defined payload. The kit never inspects it.\n *   - **`pose: TPose`** — local transform, relative to the node's direct\n *     parent (or world, for root nodes).\n *   - **`layer: TLayer`** — a string tag associating the node with a\n *     visual `RenderLayer` at draw time. Separate from `LayerRecord` (the\n *     per-layer visible/locked metadata held by the `Scene`).\n *\n * Nodes are addressed by `NodeId` everywhere outside the scene tree. Don't\n * hold references to a `Node` object across scene updates; look up by id\n * when you need the latest.\n *\n * The kit-internal name is `Node`; the public re-export is `SceneNode`\n * (avoids collision with DOM `Node` at call sites).\n */\n\n/** Opaque branded id. Treat as opaque outside the kit. */\nimport type { NodeId } from '@weasel-js/routing';\nexport type { NodeId, SceneRegistry };\n\n/** Brand a string as a NodeId. */\nexport const asNodeId = (s: string): NodeId => s as NodeId;\n\nimport type { DerivedDep, Bivariant, DerivePathFn, DerivePoseFn, ClipFromPoseFn, CopiesFromPoseFn } from './nodeFnTypes';\nexport type { DerivedDep, Bivariant, DerivePathFn, DerivePoseFn, ClipFromPoseFn, CopiesFromPoseFn };\n\n/** A clip a node declares by name rather than by function: see `SceneNode.clip`. */\nexport type NodeClip = 'outline';\n\ninterface NodeBase<TData, TLayer extends string, TPose> {\n  id: NodeId;\n  layer: TLayer;\n  pose: TPose;\n  data: TData;\n  parent: NodeId | null;\n  /** Nodes whose poses this node's geometry is computed from. Fixed at add\n   *  time. Absent or empty means the node's geometry is authored, which is the\n   *  normal case.\n   *\n   *  `'children'` means \"my own children, in child order\" — a container that\n   *  hugs its contents, which a fixed id list cannot express because\n   *  reparenting would have to maintain it. The two forms differ in lifetime\n   *  as well as in membership: deleting a node deletes everything that names\n   *  it in `dependsOn`, but a container outlives the children it derives\n   *  from — an emptied group is still a group. */\n  dependsOn?: readonly NodeId[] | 'children';\n  /** Whether the hit-test walk can return this node. Default `true`; `false`\n   *  makes it transparent to picking, so a click on it lands on whatever is\n   *  behind — normally its own container.\n   *\n   *  For content a container owns rather than content the user selects on its\n   *  own: the label inside a box, a body's rows. It does not hide the node\n   *  from anything else — it still paints, still clips, and a consumer can\n   *  still select it by id. */\n  pickable?: boolean;\n  /** Not drawn, with its whole subtree: picking, area selection, select-all,\n   *  snapping and the selection pass over it, and an SVG export writes it with\n   *  `display=\"none\"`. Absent means shown; `Scene.isHidden` folds in its\n   *  ancestors' flags and its layer's visibility. */\n  hidden?: boolean;\n  /** Out of reach, with its whole subtree: still drawn, but picking and area\n   *  selection pass over it, the selection drops it, and every edit to it\n   *  throws, as on a locked layer. Absent means unlocked; `Scene.isLocked`\n   *  folds in its ancestors' and its layer's. */\n  locked?: boolean;\n  /** Computes this node's path from its dependencies, in `dependsOn` order —\n   *  each one the node and the pose it is painted at.\n   *  A dependency that has been removed arrives as `undefined`.\n   *  Returning `null` means \"nothing to draw right now\". Re-evaluated when a\n   *  dependency's world pose changes, never authored. */\n  derivePath?: DerivePathFn<TPose, TData, TLayer>;\n  /** Computes this node's pose from its dependencies' poses, the same way\n   *  `derivePath` computes its path — same `dependsOn` list, same\n   *  registry-keyed serialization.\n   *\n   *  Where a derived path is resolved at paint time and reaches only the\n   *  painter, a derived pose is what the node *is* at: it feeds bounds,\n   *  hit-testing, selection chrome, snapping and layout, and every reader\n   *  gets it through `effectivePose`. A pose override still wins over it.\n   *\n   *  Returning `null` means \"I have nothing to derive from right now\", and\n   *  the node falls back to its authored `pose`. `setPose` on a derived node\n   *  still writes that authored pose; it is simply not what anything reads. */\n  derivePose?: DerivePoseFn<TPose, TData, TLayer>;\n  /** Ordered child ids. Absent until the node gets its first child. */\n  children?: NodeId[];\n  /** Optional clip-path source. Re-evaluated each render. Returning `null`\n   *  means \"no clip for this node right now\"; an empty / zero-area path\n   *  means \"clip everything out\" (children render nowhere). Wins over `clip`. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\n  /** `'outline'` clips the children to this node's own outline: a mark's\n   *  painter silhouette, or for a group the silhouette of its `data.path`.\n   *  Absent, and with no `clipFromPose`, the children are not clipped. */\n  clip?: NodeClip;\n  /** Draws the whole subtree again under each affine it returns, on top of\n   *  the original, which still draws once as authored. The copies are paint,\n   *  not nodes: nothing stores them, so they follow every edit to the\n   *  children, and a pick that lands on one answers with the child it copies.\n   *  A copy is a copy of the clipped content — the clip travels with it.\n   *  Re-evaluated each render; `null` or `[]` draws no copies. */\n  copiesFromPose?: CopiesFromPoseFn<TPose, TData, TLayer>;\n  /** Its children are the operands of its own geometry, drawn only through\n   *  it: the render walk paints none of them, and a press, a region select\n   *  or select-all reaches one only while this node, or a group inside it, is\n   *  entered. A node that consumes its children is entered as a group is.\n   *  The boolean group (`booleanGroupFields`) is the kit's one. */\n  consumesChildren?: boolean;\n  /** How this node arranges its children. Whenever the node's\n   *  child set or order changes, its bounds change size, or a child's pose is\n   *  written, the scene hands the change to the strategy — `depart` for children that left it,\n   *  `arrive` for children that joined it, `childPoses` otherwise — and records the poses it writes in the same\n   *  undo entry as the change. A drag reads it too: it is the layout `move`\n   *  reflows and drops against. */\n  layout?: LayoutStrategy<TPose>;\n  /** The units its children are shown, typed and snapped in (poses stay in the root's base units), their\n   *  worth in the enclosing scope's, and the magnification they are drawn at (`drawnAt`). It covers the\n   *  children, not the node; `sceneUnitScopes` reads the chain. */\n  units?: UnitScope;\n}\n\n/** A node that is drawn and picked as one thing — a shape, a label, an image.\n *  It may still hold children, which are what it is made of. */\nexport interface MarkNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'mark';\n}\n\n/** A node the user gathers things into: what Cmd+G creates, what SVG `<g>`\n *  round-trips to. An emptied group is still a group. */\nexport interface GroupNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'group';\n}\n\n/** A node in the scene tree: either a mark or a group. Re-exported\n *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */\nexport type Node<TData, TLayer extends string, TPose = RectPose> =\n  | MarkNode<TData, TLayer, TPose>\n  | GroupNode<TData, TLayer, TPose>;\n\n/** What `Scene.add` needs to mint a node. Everything except the id is\n *  required; the id is generated unless one is supplied. */\nexport interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {\n  kind: 'mark' | 'group';\n  layer: TLayer;\n  pose: TPose;\n  data: TData;\n  parent?: NodeId | null;\n  index?: number;\n  /** Explicit id wins over the Scene's `generateId` and the kit default. */\n  id?: NodeId;\n  /** Mirrors `SceneNode.pickable`. Omit for the default, which is pickable. */\n  pickable?: boolean;\n  /** Mirrors `SceneNode.hidden`. */\n  hidden?: boolean;\n  /** Mirrors `SceneNode.locked`. */\n  locked?: boolean;\n  /** Attach a clip-path function to the node; mirrors `SceneNode.clipFromPose`. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\n  /** Mirrors `SceneNode.clip`. */\n  clip?: NodeClip;\n  /** Mirrors `SceneNode.consumesChildren`. */\n  consumesChildren?: boolean;\n  /** Mirrors `SceneNode.copiesFromPose`. */\n  copiesFromPose?: CopiesFromPoseFn<TPose, TData, TLayer>;\n  /** Mirrors `SceneNode.dependsOn`. */\n  dependsOn?: readonly NodeId[] | 'children';\n  /** Mirrors `SceneNode.derivePath`. Taken as a live function; its registry key is\n   *  looked up from it, never passed in. */\n  derivePath?: DerivePathFn<TPose, TData, TLayer>;\n  /** Mirrors `SceneNode.derivePose`, on the same terms as `derivePath`. */\n  derivePose?: DerivePoseFn<TPose, TData, TLayer>;\n  /** Mirrors `SceneNode.layout`. */\n  layout?: LayoutStrategy<TPose>;\n  /** Mirrors `SceneNode.units`. */\n  units?: UnitScope;\n}\n\n/**\n * The kit-owned scene tree: nodes, layers, and the undo history over both.\n *\n * A scene is logical, not visual — it says what exists and where, and nothing\n * about how it is painted. Every mutating method is undoable, and reads are\n * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids\n * across mutations, not node objects.\n *\n * Three type parameters keep it domain-agnostic: `TData` is the app's payload,\n * which the kit never inspects; `TPose` is the transform shape, `RectPose` by\n * default; `TLayer` is the union of layer names.\n */\nexport interface Scene<TData, TLayer extends string, TPose = RectPose>\n  extends ScenePoseReports<TPose, Node<TData, TLayer, TPose>>, SceneChanges, SceneDocValues, SceneEditPasses, SceneDeclaredFieldSetters, SceneScroll {\n  // Reads\n  readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;\n  readonly roots: readonly NodeId[];\n  readonly layers: readonly LayerRecord<TLayer>[];\n  /** The registry this scene resolves node functions against — the consumer's entries over the kit's. */\n  readonly registry: SceneRegistry<TPose, TData, TLayer>;\n  /** See {@link SceneOptions.composition}. */\n  readonly composition: PoseComposition<TPose>;\n  get(id: NodeId): Node<TData, TLayer, TPose> | undefined;\n  /** A token for the node `id` names right now, for telling one node from a\n   *  later one that reuses its id. It holds for as long as the node stays in\n   *  the scene, whatever edits it takes, and is different every time the id\n   *  enters the scene — by `add`, by an undo or redo that brings it back, or\n   *  by `loadState`. `undefined` when `id` is not in the scene. Compare tokens\n   *  for equality only; their order means nothing. */\n  incarnation(id: NodeId): number | undefined;\n  childrenOf(id: NodeId): readonly NodeId[];\n  ancestorsOf(id: NodeId): readonly NodeId[];\n  renderOrder(): Iterable<NodeId>;\n  /** The same layer-major sequence as {@link Scene.renderOrder}, as the nodes\n   *  themselves. Prefer this wherever the ids are only going to be resolved\n   *  back to nodes. Cached until a structural edit, so repeat calls hand back\n   *  the same array — a snapshot, not a live view, and not yours to mutate. */\n  renderOrderNodes(): readonly Node<TData, TLayer, TPose>[];\n  /** The nodes on one layer, in render order. Cached alongside\n   *  {@link Scene.renderOrderNodes} until a structural edit. A snapshot, not\n   *  a live view, and not yours to mutate. An unknown layer id yields an\n   *  empty array. */\n  nodesOnLayer(layer: TLayer): readonly Node<TData, TLayer, TPose>[];\n\n  /** A fresh id from this scene's `generateId`, or the kit default: the id\n   *  `add` would give a spec with none. For code that has to name a node\n   *  before it exists, such as one building an insert op. */\n  mintId(): NodeId;\n\n  // Mutations (all auto-undoable)\n  add(spec: AddNodeSpec<TData, TLayer, TPose>): NodeId;\n  /** Delete `id`, its **entire subtree**, and **everything that derives from**\n   *  any of those nodes — a node listing one of them in `dependsOn` goes too,\n   *  along with its own subtree, transitively. A dependent can live anywhere in\n   *  the tree, so this deletes nodes the caller never named and may unlink\n   *  several disjoint subtrees at once. Recorded as one undoable step; `undo()`\n   *  restores every one of them where it was, child order intact. */\n  remove(id: NodeId): void;\n  /** {@link remove} over several roots at once, as a **single** undoable step.\n   *  Ids resolve against the tree as it stands at the call, so an id that\n   *  another one would cascade away is absorbed rather than removed twice —\n   *  which is what makes it safe to pass a whole selection. Throws if any id is\n   *  not in the scene; an empty list does nothing and records no step. */\n  removeMany(ids: readonly NodeId[]): void;\n  /** Every node {@link removeMany} would take if given `ids`: each id, its\n   *  subtree, everything deriving from any of those, and those nodes' subtrees\n   *  in turn. Ids not in the scene come back unchanged.\n   *\n   *  A set, not a restore order: a dependent can be reached before the parent\n   *  it sits under, which is also in the closure. */\n  removalClosure(ids: readonly NodeId[]): readonly NodeId[];\n  update(id: NodeId, patch: { data: TData }): void;\n  setPose(id: NodeId, pose: TPose): void;\n  /** Retag `id` to `layer`. On a **container this cascades**: every descendant\n   *  is moved to the same layer, recorded as a **single** undo step.\n   *\n   *  Invariants:\n   *  - **Layer floor** — a child may not render below its parent, so retagging\n   *    to a layer *below* the node's parent throws. Retagging to the parent's\n   *    layer or any higher one is allowed; a node with no parent is\n   *    unconstrained.\n   *  - **No-op elision** — setting the layer a node already has does nothing\n   *    and pushes **no** history entry. */\n  setLayer(id: NodeId, layer: TLayer): void;\n  /** Point `id` at a different set of dependencies — retargeting an edge's end\n   *  onto another node, or switching a container between an id list and\n   *  `'children'`. Recorded as one undoable step.\n   *\n   *  Order is significant: a derivation reads its dependencies positionally,\n   *  so `[b, a]` is not `[a, b]`. Ids need not be in the scene — a declared\n   *  dependency that appears later invalidates the node when it does, the same\n   *  as one declared at `add`. Passing `undefined` drops the declaration, after\n   *  which nothing cascades the node away.\n   *\n   *  **No-op elision** — declaring what the node already declares does nothing\n   *  and pushes no history entry. */\n  setDependsOn(id: NodeId, dependsOn: readonly NodeId[] | 'children' | undefined): void;\n  /** Give container `id` a different layout — a strategy, its key in\n   *  `SceneRegistry.layout`, or `null` for none — and re-arrange its children\n   *  under it, as one undoable step. Throws for a mark, or a key the registry\n   *  does not hold. A registered layout is recorded by its key, so a\n   *  serialized history restores it; an unregistered one lives only as long\n   *  as the session.\n   *\n   *  **No-op elision** — setting the layout a container already has does\n   *  nothing and pushes no history entry. */\n  setLayout(id: NodeId, layout: LayoutStrategy<TPose> | string | null): void;\n  /** Reparent `id` under `parent` (or to a root when `parent` is `null`) at\n   *  `index` within the new sibling list, appending when `index` is omitted.\n   *  Siblings are reindexed. Recorded as one undoable step.\n   *\n   *  Rejected (throws) when:\n   *  - the move would form a **cycle** — `parent` is `id` itself or one of\n   *    `id`'s own descendants;\n   *  - it would drop `id` **below its new parent's layer** (child may not\n   *    render below its parent).\n   *\n   *  `move(id, null)` — detaching to a root — is always allowed regardless of\n   *  layer, since a root has no parent to render beneath. */\n  move(id: NodeId, parent: NodeId | null, index?: number): void;\n  /** Shift `id` to `index` within its **current** parent's child list. Unlike\n   *  {@link move}, the parent never changes — only sibling order. */\n  reorder(id: NodeId, index: number): void;\n  /** Show or hide a layer. Hiding drops its nodes from the selection. */\n  setLayerVisible(layer: TLayer, visible: boolean): void;\n  /** Lock or unlock a layer. A locked layer still paints, but its nodes are\n   *  out of reach: picking and area selection pass over them, the selection\n   *  drops them, and every node mutation on them throws. Locking is never\n   *  blocked by the lock, and neither are the other layer operations. */\n  setLayerLocked(layer: TLayer, locked: boolean): void;\n  /** Set or clear (`undefined`) a layer's parallax — see\n   *  `LayerRecord.parallax`. Undoable; an animation tweening it writes inside\n   *  {@link Scene.untracked} so no frame becomes an undo step. */\n  setLayerParallax(layer: TLayer, parallax: ParallaxOpts | undefined): void;\n  /** Whether `id` is locked: it or an ancestor carries `locked`, or sits on a\n   *  locked layer. A lock covers its whole subtree, whatever layers the\n   *  descendants are tagged to. An id not in the scene is not locked. */\n  isLocked(id: NodeId): boolean;\n  /** Whether `id` is not drawn: its own layer is hidden, or it or an ancestor\n   *  carries `hidden`. A hidden layer hides only the nodes tagged to it. An\n   *  id not in the scene is not hidden. */\n  isHidden(id: NodeId): boolean;\n  /** Hide or show node `id` and its subtree — see `SceneNode.hidden`. One\n   *  undo step; hiding drops the subtree from the selection. Never blocked by\n   *  a lock, and setting what the node already has records nothing. */\n  setHidden(id: NodeId, hidden: boolean): void;\n  /** Lock or unlock node `id` and its subtree — see `SceneNode.locked`. One\n   *  undo step; locking drops the subtree from the selection. Never blocked\n   *  by a lock, and setting what the node already has records nothing. */\n  setLocked(id: NodeId, locked: boolean): void;\n  /** Run `fn` with the lock guard lifted, for a programmatic edit that has to\n   *  reach a locked node. Undo and redo never need it. */\n  unlocked<T>(fn: () => T): T;\n  addLayer(spec: AddLayerSpec<TLayer>): void;\n  /** Drop a user layer and every node tagged to it, as one undoable step.\n   *  Removal cascades, so this also deletes nodes **on other layers** that\n   *  derive from a node on this one. */\n  removeLayer(layer: TLayer): void;\n  renameLayer(layer: TLayer, name: string): void;\n  moveLayer(layer: TLayer, index: number): void;\n\n  // Custom op seam\n  registerOp<P>(kind: string, handler: RegisteredOp<P>): void;\n  recordOp<P>(op: { kind: string; payload: P }): void;\n\n  /** Install (or clear with `null`) the active-journal accessor after scene\n   *  construction, for a journal source built with `scene.history` as a\n   *  dependency. Overrides any `getActiveJournal` set in `UseSceneOptions`. */\n  setActiveJournalAccessor(\n    fn: (() => import('@weasel-js/history').Journal | null) | null,\n  ): void;\n\n  /** Install what the scene does when nodes join a container, replacing any\n   *  handler installed before; `null` removes it. Returns a function that\n   *  removes this handler, and does nothing once another has replaced it.\n   *  See {@link SceneArrivalHandler}. */\n  setArrivalHandler(handler: SceneArrivalHandler<TPose> | null): () => void;\n\n  /** Apply a batch of ops against `adapter` as one undo entry.\n   *\n   *  The entry holds the scene writes the ops made, as a direct call records\n   *  them, and beside them any op that wrote no scene state, bound to\n   *  `adapter`. Undo restores those writes; it does not call an op's\n   *  `invert()` or the adapter again. **What an op states is not recorded**:\n   *  one applied over a document that already holds its result, as after an\n   *  `untracked` preview, records a write from that pose to itself, and undo\n   *  goes nowhere. Put the document back first.\n   *\n   *  The entry lands in the open `batch` when there is one, else on the\n   *  active journal, else on the scene's own history, where it can coalesce\n   *  under `coalesceWindowMs` with one whose ops' keys match.\n   *\n   *  Returns false when the arrival handler refused the batch: it is reverted\n   *  and unrecorded. Inside `batch` it is true; that batch may still refuse. */\n  applyBatch(ops: import('core/ops/types').Op[], label: string, adapter: unknown): boolean;\n\n  // Selection\n\n  /** The transient set of active ids — \"operate on these N as a unit\".\n   *  Shared by every view over this scene unless a view supplies its own\n   *  (see `CanvasView.selection`). Not document content: it never appears\n   *  in `toJSON`. It does ride on history entries, so undo and redo put\n   *  back the selection an edit was made under; changing it is never an\n   *  undo step of its own. Removing a node deselects it. */\n  getSelection(): readonly NodeId[];\n  setSelection(ids: readonly NodeId[]): void;\n\n  // Ephemeral presentation state\n\n  /** Per-node pose / alpha / path / data overrides the render and hit-test paths read\n   *  through. Like {@link Scene.getSelection} this is not document content:\n   *  writes are never recorded, never serialized, and do not bump\n   *  {@link Scene.getVersion}. See {@link PoseOverrides}. */\n  readonly overrides: PoseOverrides<TPose, TData>;\n\n  // History\n  /** The scene's undo/redo engine, in the shape `@weasel-js/history` defines.\n   *  Mutating members route through\n   *  the scene's own wrappers, so an undo driven through this bumps\n   *  {@link Scene.getVersion} and notifies subscribers exactly as\n   *  {@link Scene.undo} does; `getVersion` / `subscribe` on it report the\n   *  engine's history version, not the scene's. */\n  readonly history: History;\n  undo(): boolean;\n  redo(): boolean;\n  canUndo(): boolean;\n  canRedo(): boolean;\n  batch<T>(label: string, fn: () => T, options?: import('./recorder').SceneBatchOptions): T;\n  /** The layout group `id` declares, or `null` for a mark or a group with none. */\n  layoutOf(id: NodeId): LayoutStrategy<TPose> | null;\n  /** Run `fn` with every mutation applied but none recorded — for writes\n   *  that are not edits, such as a simulation stepping poses each frame.\n   *  Undo and redo move between recorded states and never restore an\n   *  untracked write; the next recorded change starts from whatever the\n   *  untracked writes left, so undoing it lands there. A `batch` inside\n   *  records nothing; inside a `batch`, these writes stay out of its entry.\n   *  Notifies once, reverts `fn`'s writes if it throws, and throws on\n   *  `applyBatch` and `history.apply` / `applyOps`, which exist to record. */\n  untracked<T>(fn: () => T): T;\n  /** Read-only snapshot of every history entry currently reachable from\n   *  the present state. Oldest applied first, then redoable entries in\n   *  the order they'd be re-applied. Each entry id is stable. */\n  historyEntries(): readonly { id: string; label: string }[];\n  /** Index of the \"current state\". Equals the count of applied entries;\n   *  `0` means \"nothing applied\" (initial). */\n  historyIndex(): number;\n  /** Jump to the given history index, clamped to [0, total]. Returns true\n   *  if any movement occurred. */\n  jumpToHistoryIndex(index: number): boolean;\n\n  // History persistence\n  /** Snapshot the undo/redo history in a JSON-serializable form (the\n   *  engine's `SerializedHistory`, marked with the scene's recorded form).\n   *  An entry holds the scene's own ops, whichever way the edit was made.\n   *  An op handed to `applyBatch` that wrote no scene state is held as\n   *  itself, and an entry with a nameless one is dropped. Payload\n   *  JSON-safety (e.g. typed arrays inside poses) is the caller's concern.\n   *  Do not call mid-`batch` — the open batch's ops are not yet recorded. */\n  serializeHistory(): SerializedSceneHistory;\n  /** Replace the undo/redo history from a `serializeHistory()` snapshot.\n   *  Call on a scene whose node/layer state already matches the snapshot's\n   *  head state (i.e. right after `loadState` from the paired scene\n   *  snapshot); node state is NOT mutated. Ops re-registered via\n   *  `registerOp` before this call round-trip; unknown kinds become no-op\n   *  placeholders; external ops rebuild via the global op-factory registry\n   *  and replay against the `setHistoryAdapter` accessor. Restored entries\n   *  never coalesce with new ones. Notifies once. A snapshot that is not in\n   *  the current recorded form (see `SCENE_HISTORY_FORM`) is dropped:\n   *  the history is left as it was. Do not call mid-`batch`:\n   *  the stacks are replaced underneath the open batch, whose eventual\n   *  flush would graft onto (and evict against) the restored stacks. */\n  restoreHistory(snapshot: SerializedHistory): void;\n  /** Install (or clear with `null`) the accessor for the adapter that\n   *  RESTORED external ops apply against on undo/redo: the ops handed to\n   *  `applyBatch` that wrote no scene state, such as a selection change,\n   *  rebuilt from a `restoreHistory` snapshot. Resolved lazily at each\n   *  apply, so wiring order relative to `restoreHistory` doesn't matter.\n   *  Live `applyBatch` entries are unaffected (they bind their call-site\n   *  adapter). If unset when a restored op applies, the op is a debug-warned\n   *  no-op. */\n  setHistoryAdapter(fn: (() => unknown) | null): void;\n\n  // Serialization\n  /** Snapshot the current scene state to a JSON-serializable shape.\n   *  History (undo/redo stacks) is NOT captured. Function fields like\n   *  `GroupNode.clipFromPose` are translated to string keys via the\n   *  scene's registry; throws if any function field has no matching key. */\n  toJSON(): SerializedScene<TData, TLayer, TPose>;\n  /** Replace this scene's entire node + layer state in place from a snapshot\n   *  produced by `toJSON()`. Unlike `sceneFromJSON`, the existing Scene\n   *  instance is preserved — holders such as `<SceneCanvas>` keep their\n   *  reference. History (undo/redo) is cleared, matching `sceneFromJSON`.\n   *  Bumps `getVersion()` and notifies subscribers exactly once. Selected\n   *  ids the snapshot does not hold leave the selection, and every pose\n   *  override is cleared.\n   *\n   *  Throws inside any other edit — `batch`, `untracked`, `applyBatch`, an\n   *  undo — which would revert to a state this replaces. Throws on an unsupported version or unknown registry/layer ids; on a\n   *  malformed snapshot the scene is left empty or partially populated (callers should treat a\n   *  `loadState` throw as fatal and reload). Snapshots from `toJSON()` are\n   *  always well-formed. `opts` reads it as `specsFromSerialized` does, under the scene's composition. */\n  loadState(\n    json: SavedScene<TData, TLayer, TPose>,\n    opts?: Omit<SpecsFromSerializedOptions<TData, TLayer, TPose>, 'composition'>,\n  ): void;\n\n}\n"],"mappings":";;AA0DA,IAAa,YAAY,MAAsB"}

package/dist/core/scene/unionOfChildren.js

@@ -1,7 +1,7 @@
 import { unionAABB } from "../geometry/unionBounds.js";
 import { poseDescriptorForNode, visualBoundsViaDescriptor } from "../geometry/poseDescriptor.js";
 
-//#region src/core/scene/unionOfChildren.ts
+// src/core/scene/unionOfChildren.ts
 /**
 * A container's pose as the envelope of what it holds, read through
 * `descriptor` — a rotated member contributes the extent of its ink. Register
@@ -20,6 +20,5 @@ function unionOfChildrenVia(descriptor) {
 	};
 }
 
-//#endregion
 export { unionOfChildrenVia };
 //# sourceMappingURL=unionOfChildren.js.map

package/dist/core/scene/unitScopes.js

@@ -1,7 +1,7 @@
 import { deepEqual } from "@weasel-js/registry";
-import { scopesOf } from "@weasel-js/quantity";
+import { magnificationOf, scopesOf } from "@weasel-js/quantity";
 
-//#region src/core/scene/unitScopes.ts
+// src/core/scene/unitScopes.ts
 /**
 * The unit scopes enclosing node `id`, outermost first, under the scene's own
 * `root`: what `resolveScoped` and `formatScoped` take for a value that
@@ -32,7 +32,23 @@ function sceneSharedUnitScopes(scene, ids, root) {
 	}
 	return shared;
 }
+var NO_ROOT = { system: {
+	base: "",
+	units: {}
+} };
+/** The scopes the scene's own nodes declare around `id`, outermost first, with
+*  no root: empty where no container above it declares one. */
+function sceneDeclaredScopes(scene, id, opts = {}) {
+	return sceneUnitScopes(scene, id, NO_ROOT, opts).slice(1);
+}
+/**
+* How large the frame `ids` share is drawn in the world: every `drawnAt` their
+* shared scope chain declares, multiplied. A length measured in world between
+* them, divided by it, is the length they were modeled at.
+*/
+function sceneMagnification(scene, ids) {
+	return magnificationOf(sceneSharedUnitScopes(scene, ids, NO_ROOT));
+}
 
-//#endregion
-export { sceneSharedUnitScopes, sceneUnitScopes };
+export { sceneDeclaredScopes, sceneMagnification, sceneSharedUnitScopes, sceneUnitScopes };
 //# sourceMappingURL=unitScopes.js.map

package/dist/core/scene/unitScopes.js.map

@@ -1 +1 @@
-{"version":3,"file":"unitScopes.js","names":[],"sources":["../../../src/core/scene/unitScopes.ts"],"sourcesContent":["import { scopesOf, type UnitScope } from '@weasel-js/quantity';\nimport { deepEqual } from '@weasel-js/registry';\nimport type { NodeId } from './types';\n\n/** What reading scopes needs of a scene. A `Scene` satisfies it. */\nexport interface ScopedScene {\n  get(id: NodeId): { kind: string; parent: NodeId | null; units?: UnitScope } | undefined;\n}\n\n/**\n * The unit scopes enclosing node `id`, outermost first, under the scene's own\n * `root`: what `resolveScoped` and `formatScoped` take for a value that\n * positions or sizes it. A container's own scope covers its children, so it\n * is counted only under `inclusive`, for a value written inside it.\n */\nexport function sceneUnitScopes(\n  scene: ScopedScene,\n  id: NodeId,\n  root: UnitScope,\n  opts: { inclusive?: boolean } = {},\n): UnitScope[] {\n  return scopesOf(id, root, {\n    parentOf: (at) => scene.get(at)?.parent,\n    scopeOf: (at) => scene.get(at)?.units,\n    ...(opts.inclusive ? { inclusive: true } : {}),\n  });\n}\n\n/**\n * The unit scopes every node of `ids` sits in, outermost first: the run of\n * their chains that agree, where two containers declaring equal scopes\n * agree. What a reader showing or snapping several nodes as one reads them\n * in; the root alone for no nodes.\n */\nexport function sceneSharedUnitScopes(scene: ScopedScene, ids: readonly NodeId[], root: UnitScope): UnitScope[] {\n  if (ids.length === 0) return [root];\n  let shared = sceneUnitScopes(scene, ids[0]!, root);\n  for (const id of ids.slice(1)) {\n    const chain = sceneUnitScopes(scene, id, root);\n    let n = 0;\n    while (n < shared.length && n < chain.length && deepEqual(shared[n], chain[n])) n++;\n    shared = shared.slice(0, n);\n  }\n  return shared;\n}\n"],"mappings":";;;;;;;;;;AAeA,SAAgB,gBACd,OACA,IACA,MACA,OAAgC,CAAC,GACpB;CACb,OAAO,SAAS,IAAI,MAAM;EACxB,WAAW,OAAO,MAAM,IAAI,EAAE,CAAC,EAAE;EACjC,UAAU,OAAO,MAAM,IAAI,EAAE,CAAC,EAAE;EAChC,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,CAAC;AACH;;;;;;;AAQA,SAAgB,sBAAsB,OAAoB,KAAwB,MAA8B;CAC9G,IAAI,IAAI,WAAW,GAAG,OAAO,CAAC,IAAI;CAClC,IAAI,SAAS,gBAAgB,OAAO,IAAI,IAAK,IAAI;CACjD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,GAAG;EAC7B,MAAM,QAAQ,gBAAgB,OAAO,IAAI,IAAI;EAC7C,IAAI,IAAI;EACR,OAAO,IAAI,OAAO,UAAU,IAAI,MAAM,UAAU,UAAU,OAAO,IAAI,MAAM,EAAE,GAAG;EAChF,SAAS,OAAO,MAAM,GAAG,CAAC;CAC5B;CACA,OAAO;AACT"}
+{"version":3,"file":"unitScopes.js","names":[],"sources":["../../../src/core/scene/unitScopes.ts"],"sourcesContent":["import { magnificationOf, scopesOf, type UnitScope } from '@weasel-js/quantity';\nimport { deepEqual } from '@weasel-js/registry';\nimport type { NodeId } from './types';\n\n/** What reading scopes needs of a scene. A `Scene` satisfies it. */\nexport interface ScopedScene {\n  get(id: NodeId): { kind: string; parent: NodeId | null; units?: UnitScope } | undefined;\n}\n\n/**\n * The unit scopes enclosing node `id`, outermost first, under the scene's own\n * `root`: what `resolveScoped` and `formatScoped` take for a value that\n * positions or sizes it. A container's own scope covers its children, so it\n * is counted only under `inclusive`, for a value written inside it.\n */\nexport function sceneUnitScopes(\n  scene: ScopedScene,\n  id: NodeId,\n  root: UnitScope,\n  opts: { inclusive?: boolean } = {},\n): UnitScope[] {\n  return scopesOf(id, root, {\n    parentOf: (at) => scene.get(at)?.parent,\n    scopeOf: (at) => scene.get(at)?.units,\n    ...(opts.inclusive ? { inclusive: true } : {}),\n  });\n}\n\n/**\n * The unit scopes every node of `ids` sits in, outermost first: the run of\n * their chains that agree, where two containers declaring equal scopes\n * agree. What a reader showing or snapping several nodes as one reads them\n * in; the root alone for no nodes.\n */\nexport function sceneSharedUnitScopes(scene: ScopedScene, ids: readonly NodeId[], root: UnitScope): UnitScope[] {\n  if (ids.length === 0) return [root];\n  let shared = sceneUnitScopes(scene, ids[0]!, root);\n  for (const id of ids.slice(1)) {\n    const chain = sceneUnitScopes(scene, id, root);\n    let n = 0;\n    while (n < shared.length && n < chain.length && deepEqual(shared[n], chain[n])) n++;\n    shared = shared.slice(0, n);\n  }\n  return shared;\n}\n\nconst NO_ROOT: UnitScope = { system: { base: '', units: {} } };\n\n/** The scopes the scene's own nodes declare around `id`, outermost first, with\n *  no root: empty where no container above it declares one. */\nexport function sceneDeclaredScopes(scene: ScopedScene, id: NodeId, opts: { inclusive?: boolean } = {}): UnitScope[] {\n  return sceneUnitScopes(scene, id, NO_ROOT, opts).slice(1);\n}\n\n/**\n * How large the frame `ids` share is drawn in the world: every `drawnAt` their\n * shared scope chain declares, multiplied. A length measured in world between\n * them, divided by it, is the length they were modeled at.\n */\nexport function sceneMagnification(scene: ScopedScene, ids: readonly NodeId[]): number {\n  return magnificationOf(sceneSharedUnitScopes(scene, ids, NO_ROOT));\n}\n"],"mappings":";;;;;;;;;;AAeA,SAAgB,gBACd,OACA,IACA,MACA,OAAgC,CAAC,GACpB;CACb,OAAO,SAAS,IAAI,MAAM;EACxB,WAAW,OAAO,MAAM,IAAI,EAAE,CAAC,EAAE;EACjC,UAAU,OAAO,MAAM,IAAI,EAAE,CAAC,EAAE;EAChC,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,CAAC;AACH;;;;;;;AAQA,SAAgB,sBAAsB,OAAoB,KAAwB,MAA8B;CAC9G,IAAI,IAAI,WAAW,GAAG,OAAO,CAAC,IAAI;CAClC,IAAI,SAAS,gBAAgB,OAAO,IAAI,IAAK,IAAI;CACjD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,GAAG;EAC7B,MAAM,QAAQ,gBAAgB,OAAO,IAAI,IAAI;EAC7C,IAAI,IAAI;EACR,OAAO,IAAI,OAAO,UAAU,IAAI,MAAM,UAAU,UAAU,OAAO,IAAI,MAAM,EAAE,GAAG;EAChF,SAAS,OAAO,MAAM,GAAG,CAAC;CAC5B;CACA,OAAO;AACT;AAEA,IAAM,UAAqB,EAAE,QAAQ;CAAE,MAAM;CAAI,OAAO,CAAC;AAAE,EAAE;;;AAI7D,SAAgB,oBAAoB,OAAoB,IAAY,OAAgC,CAAC,GAAgB;CACnH,OAAO,gBAAgB,OAAO,IAAI,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC;AAC1D;;;;;;AAOA,SAAgB,mBAAmB,OAAoB,KAAgC;CACrF,OAAO,gBAAgB,sBAAsB,OAAO,KAAK,OAAO,CAAC;AACnE"}

package/dist/core/scene/useScene.js

@@ -1,9 +1,9 @@
 import { IDENTITY_POSE_COMPOSITION } from "./composeFrame.js";
-import { asNodeId } from "./types.js";
 import { createScene } from "./scene.js";
+import { asNodeId } from "./types.js";
 import { useRef, useSyncExternalStore } from "react";
 
-//#region src/core/scene/useScene.ts
+// src/core/scene/useScene.ts
 /** A subscribe function that never notifies. `useSyncExternalStore` still runs
 *  (hooks are unconditional) but the host is never re-rendered by the store. */
 var NEVER_SUBSCRIBE = () => () => {};
@@ -37,6 +37,5 @@ function useScene(options) {
 	return scene;
 }
 
-//#endregion
 export { useScene };
 //# sourceMappingURL=useScene.js.map

package/dist/core/scene/worldSave.js

@@ -1,8 +1,8 @@
 import { composeWorldPose } from "./composeFrame.js";
-import { definesFrame } from "./effectivePose.js";
 import { scenePoseAdapter } from "./scenePoseAdapter.js";
+import { definesFrame } from "./effectivePose.js";
 
-//#region src/core/scene/worldSave.ts
+// src/core/scene/worldSave.ts
 /**
 * Reading a save from before a scene's poses composed by default. Versions 1
 * and 2 stored every pose as world; version 3 stores a child's pose in the
@@ -82,6 +82,5 @@ function localizeInScene(scene, specs) {
 	return localizeWorldPoses([...above.values(), ...specs], scene.composition).slice(above.size);
 }
 
-//#endregion
 export { localizeInScene, localizeWorldPoses, worldPosesOf };
 //# sourceMappingURL=worldSave.js.map

package/dist/core/selection/chromeState.js

@@ -1,6 +1,6 @@
 import { unionAABB } from "../geometry/unionBounds.js";
 
-//#region src/core/selection/chromeState.ts
+// src/core/selection/chromeState.ts
 /** Nothing selected, nothing resolvable — what a caller reads before a
 *  surface has attached, or where chrome state has no owner. */
 var EMPTY_CHROME_STATE = {
@@ -50,6 +50,5 @@ function buildChromeState(args) {
 	};
 }
 
-//#endregion
 export { EMPTY_CHROME_STATE, buildChromeState, paintsLayer };
 //# sourceMappingURL=chromeState.js.map

package/dist/core/selection/outermostSelection.js

@@ -0,0 +1,56 @@
+import { outermost } from "@weasel-js/select";
+
+// src/core/selection/outermostSelection.ts
+var views = /* @__PURE__ */ new WeakMap();
+/**
+* A view of `api` whose every write keeps only the outermost ids under `parentOf`, so a
+* selection kept off the scene holds a selected node's subtree the way the scene's own does.
+* `api` itself is untouched and still writes as it did.
+*
+* One view per `api` and `parentOf`, so it is as stable a memo or effect dependency as `api`.
+*/
+function outermostSelection(api, parentOf) {
+	const cached = views.get(api);
+	if (cached && cached.parentOf === parentOf) return cached.view;
+	const narrow = (ids) => outermost(ids, parentOf);
+	const set = (ids) => api.set(narrow(ids));
+	const settle = () => {
+		const ids = api.get();
+		const kept = narrow(ids);
+		if (kept !== ids) api.set(kept);
+	};
+	const view = {
+		get current() {
+			return api.current;
+		},
+		get: api.get,
+		contains: api.contains,
+		set,
+		add(id) {
+			api.add(id);
+			settle();
+		},
+		remove: api.remove,
+		toggle(id) {
+			api.toggle(id);
+			settle();
+		},
+		clear: api.clear,
+		applyClick(id, modifiers) {
+			api.applyClick(id, modifiers);
+			settle();
+		},
+		adapterMethods: {
+			getSelection: api.adapterMethods.getSelection,
+			setSelection: (ids) => api.adapterMethods.setSelection(narrow(ids))
+		}
+	};
+	views.set(api, {
+		parentOf,
+		view
+	});
+	return view;
+}
+
+export { outermostSelection };
+//# sourceMappingURL=outermostSelection.js.map

package/dist/core/selection/outermostSelection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outermostSelection.js","names":[],"sources":["../../../src/core/selection/outermostSelection.ts"],"sourcesContent":["import { outermost, type ParentOf } from '@weasel-js/select';\nimport type { NodeId } from 'core/scene/types';\nimport type { SelectionApi } from './useSelection';\n\nconst views = new WeakMap<SelectionApi, { parentOf: ParentOf<NodeId>; view: SelectionApi }>();\n\n/**\n * A view of `api` whose every write keeps only the outermost ids under `parentOf`, so a\n * selection kept off the scene holds a selected node's subtree the way the scene's own does.\n * `api` itself is untouched and still writes as it did.\n *\n * One view per `api` and `parentOf`, so it is as stable a memo or effect dependency as `api`.\n */\nexport function outermostSelection(api: SelectionApi, parentOf: ParentOf<NodeId>): SelectionApi {\n  const cached = views.get(api);\n  if (cached && cached.parentOf === parentOf) return cached.view;\n  const narrow = (ids: readonly NodeId[]) => outermost(ids, parentOf) as NodeId[];\n  const set = (ids: NodeId[]): void => api.set(narrow(ids));\n  const settle = (): void => {\n    const ids = api.get();\n    const kept = narrow(ids);\n    if (kept !== ids) api.set(kept);\n  };\n  const view: SelectionApi = {\n    get current() { return api.current; },\n    get: api.get,\n    contains: api.contains,\n    set,\n    add(id) { api.add(id); settle(); },\n    remove: api.remove,\n    toggle(id) { api.toggle(id); settle(); },\n    clear: api.clear,\n    applyClick(id, modifiers) { api.applyClick(id, modifiers); settle(); },\n    adapterMethods: {\n      getSelection: api.adapterMethods.getSelection,\n      setSelection: (ids) => api.adapterMethods.setSelection(narrow(ids)),\n    },\n  };\n  views.set(api, { parentOf, view });\n  return view;\n}\n"],"mappings":";;;AAIA,IAAM,wBAAQ,IAAI,QAA0E;;;;;;;;AAS5F,SAAgB,mBAAmB,KAAmB,UAA0C;CAC9F,MAAM,SAAS,MAAM,IAAI,GAAG;CAC5B,IAAI,UAAU,OAAO,aAAa,UAAU,OAAO,OAAO;CAC1D,MAAM,UAAU,QAA2B,UAAU,KAAK,QAAQ;CAClE,MAAM,OAAO,QAAwB,IAAI,IAAI,OAAO,GAAG,CAAC;CACxD,MAAM,eAAqB;EACzB,MAAM,MAAM,IAAI,IAAI;EACpB,MAAM,OAAO,OAAO,GAAG;EACvB,IAAI,SAAS,KAAK,IAAI,IAAI,IAAI;CAChC;CACA,MAAM,OAAqB;EACzB,IAAI,UAAU;GAAE,OAAO,IAAI;EAAS;EACpC,KAAK,IAAI;EACT,UAAU,IAAI;EACd;EACA,IAAI,IAAI;GAAE,IAAI,IAAI,EAAE;GAAG,OAAO;EAAG;EACjC,QAAQ,IAAI;EACZ,OAAO,IAAI;GAAE,IAAI,OAAO,EAAE;GAAG,OAAO;EAAG;EACvC,OAAO,IAAI;EACX,WAAW,IAAI,WAAW;GAAE,IAAI,WAAW,IAAI,SAAS;GAAG,OAAO;EAAG;EACrE,gBAAgB;GACd,cAAc,IAAI,eAAe;GACjC,eAAe,QAAQ,IAAI,eAAe,aAAa,OAAO,GAAG,CAAC;EACpE;CACF;CACA,MAAM,IAAI,KAAK;EAAE;EAAU;CAAK,CAAC;CACjC,OAAO;AACT"}

package/dist/core/selection/readOnlySelection.js

@@ -1,4 +1,4 @@
-//#region src/core/selection/readOnlySelection.ts
+// src/core/selection/readOnlySelection.ts
 var methodViews = /* @__PURE__ */ new WeakMap();
 var apiViews = /* @__PURE__ */ new WeakMap();
 var ignore = () => {};
@@ -42,6 +42,5 @@ function readOnlySelection(api) {
 	return view;
 }
 
-//#endregion
 export { readOnlySelection };
 //# sourceMappingURL=readOnlySelection.js.map

package/dist/core/selection/selectionTarget.js

@@ -1,4 +1,4 @@
-//#region src/core/selection/selectionTarget.ts
+// src/core/selection/selectionTarget.ts
 /** Synthetic id a canvas uses to address the
 *  union-AABB target when 2+ real ids are selected. The selection-overlay
 *  layer and the affordance hit-tester both resolve it to `ChromeState`'s
@@ -12,6 +12,5 @@
 *  `features`). */
 var MULTI_RESIZE_TARGET_ID = "__weasel:multi-selection";
 
-//#endregion
 export { MULTI_RESIZE_TARGET_ID };
 //# sourceMappingURL=selectionTarget.js.map

package/dist/core/selection/usePublishSceneSelection.js

@@ -1,7 +1,7 @@
 import { useMemo } from "react";
 import { usePublishSelection } from "@weasel-js/routing/react";
 
-//#region src/core/selection/usePublishSceneSelection.ts
+// src/core/selection/usePublishSceneSelection.ts
 /** The label published beside each selected id, parallel to `ids`; `undefined` when
 *  nothing is selected. Without `describe`, every entry is unlabeled. */
 function selectionKindLabels(scene, ids, describe) {
@@ -22,6 +22,5 @@ function usePublishSceneSelection(scene, ids, describe) {
 	usePublishSelection(ids, kinds);
 }
 
-//#endregion
 export { selectionKindLabels, usePublishSceneSelection };
 //# sourceMappingURL=usePublishSceneSelection.js.map

package/dist/core/selection/useSelection.js

@@ -3,7 +3,7 @@ import { useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from
 import { useLatest } from "@weasel-js/react";
 import { createSelectionStore, intentOf, select } from "@weasel-js/select";
 
-//#region src/core/selection/useSelection.ts
+// src/core/selection/useSelection.ts
 /** The order a store paints its nodes in, when it is a scene and has one. */
 function paintOrderOf(store) {
 	const { renderOrder } = store;
@@ -102,6 +102,5 @@ function useSelection(opts = {}) {
 	}, [store, optsRef]);
 }
 
-//#endregion
 export { useSelection };
 //# sourceMappingURL=useSelection.js.map

package/dist/core/shapeKinds.js

@@ -1,4 +1,4 @@
-//#region src/core/shapeKinds.ts
+// src/core/shapeKinds.ts
 /**
 * Declaration order is the enumeration order of every derived list —
 * `KIT_SHAPE_KINDS`, and through it `defaultNodeRouting` /
@@ -78,6 +78,5 @@ function kitShapeKindsOf(family) {
 	return KIT_SHAPE_KINDS.filter((k) => SHAPE_KINDS[k].family === family);
 }
 
-//#endregion
 export { KIT_SHAPE_KINDS, SHAPE_KINDS, kitShapeKindsOf, shapeKindInfo, shapeKindsWhere };
 //# sourceMappingURL=shapeKinds.js.map

package/dist/core/stableStringify.js

@@ -1,9 +1,8 @@
-//#region src/core/stableStringify.ts
+// src/core/stableStringify.ts
 /** JSON with object keys sorted, so two equal values produce one string. */
 function stableStringify(value) {
 	return JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : 1)) : v);
 }
 
-//#endregion
 export { stableStringify };
 //# sourceMappingURL=stableStringify.js.map

package/dist/core/stylus/stylus.js

@@ -1,6 +1,6 @@
 import { clientToWorld } from "../viewport/clientToWorld.js";
 
-//#region src/core/stylus/stylus.ts
+// src/core/stylus/stylus.ts
 /**
 * Map a 0..1 pressure value to a stroke width.
 *
@@ -58,6 +58,5 @@ function forEachCoalesced(event, ctx, cb) {
 	}
 }
 
-//#endregion
 export { forEachCoalesced, getStylusData, pressureToWidth };
 //# sourceMappingURL=stylus.js.map

package/dist/core/stylus/usePointerStylus.js

@@ -2,7 +2,7 @@ import { getStylusData } from "./stylus.js";
 import { useEffect, useRef, useState } from "react";
 import { useLatest } from "@weasel-js/react";
 
-//#region src/core/stylus/usePointerStylus.ts
+// src/core/stylus/usePointerStylus.ts
 var IDLE = {
 	pressure: 0,
 	tiltX: 0,
@@ -73,6 +73,5 @@ function usePointerStylus(target, options = {}) {
 	return state;
 }
 
-//#endregion
 export { usePointerStylus };
 //# sourceMappingURL=usePointerStylus.js.map

package/dist/core/usePaintKinds.js

@@ -1,7 +1,7 @@
 import { getPaintKind, listGradientKinds, listPaintKinds, paintKindRegistry } from "./paint/paintKinds.js";
 import { useCallback, useSyncExternalStore } from "react";
 
-//#region src/core/usePaintKinds.ts
+// src/core/usePaintKinds.ts
 /** Every registered paint kind, as {@link listPaintKinds} returns it,
 *  re-rendering the caller whenever a kind is registered or removed. */
 function usePaintKinds() {
@@ -22,6 +22,5 @@ function usePaintKind(kind) {
 	return useSyncExternalStore(paintKindRegistry.subscribe, read, read);
 }
 
-//#endregion
 export { useGradientKinds, usePaintKind, usePaintKinds };
 //# sourceMappingURL=usePaintKinds.js.map

package/dist/core/viewport/clampView.js

@@ -1,4 +1,4 @@
-//#region src/core/viewport/clampView.ts
+// src/core/viewport/clampView.ts
 /**
 * Clamp a `View` so the visible world rect stays within `bounds`.
 *
@@ -35,6 +35,5 @@ function clampView(view, bounds, canvas) {
 	};
 }
 
-//#endregion
 export { clampView };
 //# sourceMappingURL=clampView.js.map

package/dist/core/viewport/clientToWorld.js

@@ -1,4 +1,6 @@
-//#region src/core/viewport/clientToWorld.ts
+import { viewScreenToWorld } from "@weasel-js/geom";
+
+// src/core/viewport/clientToWorld.ts
 /**
 * Map a browser client coord pair to world coords.
 *
@@ -11,9 +13,12 @@
 * @param view     - current viewport transform
 */
 function clientToWorld(clientX, clientY, origin, view) {
-	return [(clientX - origin.left) / view.scale.x + view.x, (clientY - origin.top) / view.scale.y + view.y];
+	const world = viewScreenToWorld(view, {
+		x: clientX - origin.left,
+		y: clientY - origin.top
+	});
+	return [world.x, world.y];
 }
 
-//#endregion
 export { clientToWorld };
 //# sourceMappingURL=clientToWorld.js.map

package/dist/core/viewport/clientToWorld.js.map

@@ -1 +1 @@
-{"version":3,"file":"clientToWorld.js","names":[],"sources":["../../../src/core/viewport/clientToWorld.ts"],"sourcesContent":["/**\n * Convert client coords directly to world coords by subtracting the canvas\n * rect origin and then applying the inverse view transform.\n *\n * This is the composition of `clientToCanvas` + the view-inverse half of\n * `screenToWorld`, but expressed against the `ViewLike` shape used by\n * `SceneCanvas` (`{ scale: { x, y }, x, y }`) rather than the\n * `ViewTransform` shape used by `screenToWorld` (`{ panX, panY, zoom }`).\n */\nexport interface ViewLike {\n  scale: { x: number; y: number };\n  x: number;\n  y: number;\n}\n\n/**\n * Map a browser client coord pair to world coords.\n *\n * @param clientX  - `event.clientX`\n * @param clientY  - `event.clientY`\n * @param origin   - client-space origin of the surface `view` is a camera on.\n *   For a whole canvas that is its bounding rect. For a viewport node it is\n *   the canvas rect offset by the viewport's own rect, so the same call maps\n *   into that viewport's inner world.\n * @param view     - current viewport transform\n */\nexport function clientToWorld(\n  clientX: number,\n  clientY: number,\n  origin: { left: number; top: number },\n  view: ViewLike,\n): [number, number] {\n  return [\n    (clientX - origin.left) / view.scale.x + view.x,\n    (clientY - origin.top) / view.scale.y + view.y,\n  ];\n}\n"],"mappings":";;;;;;;;;;;;AA0BA,SAAgB,cACd,SACA,SACA,QACA,MACkB;CAClB,OAAO,EACJ,UAAU,OAAO,QAAQ,KAAK,MAAM,IAAI,KAAK,IAC7C,UAAU,OAAO,OAAO,KAAK,MAAM,IAAI,KAAK,CAC/C;AACF"}
+{"version":3,"file":"clientToWorld.js","names":[],"sources":["../../../src/core/viewport/clientToWorld.ts"],"sourcesContent":["import { viewScreenToWorld } from '@weasel-js/geom';\n\n/** The `View` shape: `clientToWorld` is `clientToCanvas` then `viewScreenToWorld`. */\nexport interface ViewLike {\n  scale: { x: number; y: number };\n  x: number;\n  y: number;\n}\n\n/**\n * Map a browser client coord pair to world coords.\n *\n * @param clientX  - `event.clientX`\n * @param clientY  - `event.clientY`\n * @param origin   - client-space origin of the surface `view` is a camera on.\n *   For a whole canvas that is its bounding rect. For a viewport node it is\n *   the canvas rect offset by the viewport's own rect, so the same call maps\n *   into that viewport's inner world.\n * @param view     - current viewport transform\n */\nexport function clientToWorld(\n  clientX: number,\n  clientY: number,\n  origin: { left: number; top: number },\n  view: ViewLike,\n): [number, number] {\n  const world = viewScreenToWorld(view, { x: clientX - origin.left, y: clientY - origin.top });\n  return [world.x, world.y];\n}\n"],"mappings":";;;;;;;;;;;;;;AAoBA,SAAgB,cACd,SACA,SACA,QACA,MACkB;CAClB,MAAM,QAAQ,kBAAkB,MAAM;EAAE,GAAG,UAAU,OAAO;EAAM,GAAG,UAAU,OAAO;CAAI,CAAC;CAC3F,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;AAC1B"}

package/dist/core/viewport/createVelocityTracker.js

@@ -1,4 +1,4 @@
-//#region src/core/viewport/createVelocityTracker.ts
+// src/core/viewport/createVelocityTracker.ts
 /** Hook-free velocity tracker. `useVelocityTracker` wraps one of these; the
 *  action layer builds its own, because an Action descriptor is a static
 *  object and cannot call hooks. */
@@ -38,6 +38,5 @@ function createVelocityTracker() {
 	};
 }
 
-//#endregion
 export { createVelocityTracker };
 //# sourceMappingURL=createVelocityTracker.js.map

package/dist/core/viewport/fitToBounds.js

@@ -1,6 +1,6 @@
 import { normalizeZoom } from "./zoomBounds.js";
 
-//#region src/core/viewport/fitToBounds.ts
+// src/core/viewport/fitToBounds.ts
 /**
 * Compute the largest uniform zoom (px per content-unit) that fits a content
 * rect of `contentW x contentH` (in content units) into a viewport rect of
@@ -30,6 +30,5 @@ function fitToBounds(viewportW, viewportH, contentW, contentH, paddingPx = 0, cl
 	};
 }
 
-//#endregion
 export { fitToBounds, fitZoom };
 //# sourceMappingURL=fitToBounds.js.map

package/dist/core/viewport/fitViewToBounds.js

@@ -1,6 +1,6 @@
 import { DEFAULT_MAX_ZOOM, DEFAULT_MIN_ZOOM, normalizeZoom } from "./zoomBounds.js";
 
-//#region src/core/viewport/fitViewToBounds.ts
+// src/core/viewport/fitViewToBounds.ts
 /**
 * Compute the target {@link View} that fits `bounds` (world space) inside
 * `viewportDims` (CSS px). The bounds are centered in the viewport with
@@ -57,6 +57,5 @@ function fitViewToBounds(bounds, viewportDims, currentView, opts = {}) {
 	};
 }
 
-//#endregion
 export { fitViewToBounds };
 //# sourceMappingURL=fitViewToBounds.js.map

package/dist/core/viewport/interpolateView.js

@@ -1,4 +1,4 @@
-//#region src/core/viewport/interpolateView.ts
+// src/core/viewport/interpolateView.ts
 /**
 * Per-axis camera curve. Two views that differ in scale agree at exactly one
 * screen point; holding the world point under it fixed is what makes a zoom
@@ -49,6 +49,5 @@ function interpolateView(from, to) {
 	};
 }
 
-//#endregion
 export { interpolateView };
 //# sourceMappingURL=interpolateView.js.map

package/dist/core/viewport/parallax.js

@@ -1,4 +1,4 @@
-//#region src/core/viewport/parallax.ts
+// src/core/viewport/parallax.ts
 function asXY(v) {
 	return typeof v === "number" ? {
 		x: v,
@@ -139,6 +139,5 @@ function planeMatrix(m) {
 	];
 }
 
-//#endregion
 export { deriveParallaxView, fromPlane, planeMap, planeMatrix, planeToPlane, rectFromPlane, rectToPlane, toPlane };
 //# sourceMappingURL=parallax.js.map

package/dist/core/viewport/sceneNodeClientRect.js

@@ -1,7 +1,7 @@
 import { viewToTransform } from "./view.js";
 import { worldToScreen } from "./viewTransform.js";
 
-//#region src/core/viewport/sceneNodeClientRect.ts
+// src/core/viewport/sceneNodeClientRect.ts
 /**
 * Project a scene node's world AABB to client (viewport) coordinates,
 * e.g. to anchor a `Callout` at a canvas-drawn object. Snapshot
@@ -22,6 +22,5 @@ function sceneNodeClientRect(opts) {
 	};
 }
 
-//#endregion
 export { sceneNodeClientRect };
 //# sourceMappingURL=sceneNodeClientRect.js.map

package/dist/core/viewport/screenSlop.js

@@ -1,6 +1,6 @@
 import { multiply, scale } from "@weasel-js/geom";
 
-//#region src/core/viewport/screenSlop.ts
+// src/core/viewport/screenSlop.ts
 /**
 * Pointer forgiveness measured on screen.
 *
@@ -51,6 +51,5 @@ function hasSlop(slop) {
 	return typeof slop === "number" ? slop > 0 : slop.px > 0;
 }
 
-//#endregion
 export { hasSlop, slopForStrokeHit, widenSlop };
 //# sourceMappingURL=screenSlop.js.map