@weasel-js/core 1.15.0 → 1.15.1

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

@@ -1 +1 @@
-{"version":3,"file":"scene.js","names":[],"sources":["../../../src/core/scene/scene.ts"],"sourcesContent":["import { withKitRegistry } from './kitRegistry';\nimport { createPoseOverrides } from './poseOverrides';\nimport { createScrollOffsets } from './scrollOffsets';\nimport { createArrivalWindow } from './arrivalWindow';\nimport { documentReads, sceneMutators } from './sceneMutators';\nimport { createNotifier } from './notifier';\nimport type { SerializedDoc } from './docValues';\nimport { sceneChanges } from './sceneChanges';\nimport { createPoseWriteLog } from './poseWrites';\nimport { effectivePose } from './effectivePose';\nimport { createEditMode } from './editMode';\nimport { createSceneEdits } from './sceneEdits';\nimport { createSceneRecording } from './sceneRecording';\nimport { createSceneSelection } from './sceneSelection';\nimport { createSceneState } from './sceneState';\nimport { systemLayerRecord } from './layerStack';\nimport { layerFromSerialized, specsFromSerialized, type SpecsFromSerializedOptions } from './serialization';\nimport { resolveLayoutFrame, runLayoutPass } from './layoutPass';\nimport type { PoseComposition } from './composeFrame';\nimport { RIGID_POSE_COMPOSITION } from './composePose';\nimport type { SceneOptions } from './useSceneOptions';\nimport {\n  asNodeId,\n  type AddNodeSpec,\n  type LayerRecord,\n  type NodeId,\n  type RegisteredOp,\n  type Scene,\n  type SceneRegistry,\n  type SavedScene,\n  type UseSceneOptions,\n} from './types';\n\n/** A node still in `scene`, with the pose it is shown at. */\nfunction shownNode<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>, id: NodeId) {\n  const node = scene.get(id);\n  return node && { node, pose: effectivePose(scene, node) };\n}\n\nlet defaultIdCounter = 0;\nconst defaultGenerateId = (): NodeId =>\n  asNodeId(`n${(defaultIdCounter++).toString(36)}-${Math.random().toString(36).slice(2, 8)}`);\n\n/** Build a scene outside React. `useScene` is the usual entry point; reach for\n *  this in tests, in headless rendering, or wherever a scene must outlive a\n *  component. Throws if no system layers are declared. */\nexport function createScene<TData, TLayer extends string, TPose = import('./composePose').RectPose>(\n  options: UseSceneOptions<TData, TLayer, TPose>,\n): Scene<TData, TLayer, TPose> {\n  return buildScene(options, (options.systemLayers ?? []).map(systemLayerRecord), () => options.initial, options.doc);\n}\n\ntype SceneConfig<TData, TLayer extends string, TPose> =\n  Omit<SceneOptions<TData, TLayer, TPose>, 'systemLayers' | 'initial' | 'doc'>;\n\n/** A scene holding `layers`, the document values `initialDoc`, and the nodes\n *  `initialNodes` answers with once it is handed the registry their functions\n *  resolve against. */\nfunction buildScene<TData, TLayer extends string, TPose>(\n  options: SceneConfig<TData, TLayer, TPose>,\n  layers: readonly LayerRecord<TLayer>[],\n  initialNodes: (registry: SceneRegistry<TPose, TData, TLayer>) => readonly AddNodeSpec<TData, TLayer, TPose>[] | undefined,\n  initialDoc: SerializedDoc | undefined,\n): Scene<TData, TLayer, TPose> {\n  if (layers.length === 0) throw new Error('Scene: systemLayers must declare at least one layer');\n\n  // The kit's own registry entries sit under the consumer's, so a snapshot carrying a kit-attached\n  // function (a grouped container's derived pose) reloads in any scene, not only one that registered it.\n  const registry = withKitRegistry(options.registry ?? {});\n\n  const doc = createSceneState<TData, TLayer, TPose>(registry, layers, () => arrivals.layoutDeclared(), initialDoc);\n  const { state, locks, reads } = doc;\n  const notifier = createNotifier();\n  const mode = createEditMode();\n  const poseWrites = createPoseWriteLog({ untracked: mode.untracked, changes: notifier, shown: (id) => shownNode(scene, id) });\n  const writePose = (id: string, pose: unknown): void => poseWrites.layout(() => scene.setPose(asNodeId(id), pose as TPose));\n\n  const layoutFrame = resolveLayoutFrame(options.layoutFrame);\n  const arrivals = createArrivalWindow<TData, TLayer, TPose>({\n    nodes: state.nodes,\n    layoutPass: (arrived, touched, departed) =>\n      runLayoutPass(scene, reads.layoutOf, arrived, touched, layoutFrame, departed),\n    recordsBareEdits: () => !mode.open(),\n    writePose,\n  });\n\n  const generateId = options.generateId ?? defaultGenerateId;\n  const selection = createSceneSelection(locks.reachable);\n  // A selection change is a scene change to every subscriber.\n  selection.subscribe(notifier.notify);\n\n  /** Ephemeral, deliberately not part of `state`: not document content, never in `toJSON` or history. */\n  const overrides = createPoseOverrides<TPose, TData>((id) => state.nodes.get(id), doc.store.invalidateDependents);\n  const scroll = createScrollOffsets();\n\n  const recording = createSceneRecording({\n    notifier,\n    mode,\n    passAdapter: () => ({ ...sceneMutators(scene), ...documentReads(scene) }),\n    stale: doc.stale,\n    lifted: locks.lifted,\n    selection,\n    arrivals,\n    writePose,\n    poseWrites,\n    config: options,\n  });\n\n  const edits = createSceneEdits<TData, TLayer, TPose>({\n    state,\n    store: doc.store,\n    locks,\n    layers: doc.layers,\n    invalidateOrder: doc.order.invalidate,\n    fnFields: doc.fnFields,\n    ops: { ...recording.ops, register: poseWrites.reporting(recording.ops.register) },\n    recorder: recording.recorder,\n    arrivals,\n    layoutFrame,\n    generateId,\n    narrowSelection: selection.narrow,\n    clearOverride: overrides.clear,\n  });\n  for (const [kind, handler] of Object.entries(options.ops ?? {})) recording.ops.register(kind, handler);\n\n  const scene: Scene<TData, TLayer, TPose> = {\n    get nodes() { return state.nodes; },\n    get roots() { return state.roots; },\n    get layers() { return state.layers; },\n    registry,\n\n    ...reads,\n\n    mintId: generateId,\n    composition: options.composition ?? (RIGID_POSE_COMPOSITION as PoseComposition<TPose>),\n\n    ...edits.methods,\n    ...recording.methods,\n\n    unlocked: (fn) => locks.lifted(fn),\n\n    setArrivalHandler: arrivals.setHandler,\n    onReflow: arrivals.onReflow,\n    onPoseWrite: poseWrites.subscribe,\n\n    overrides,\n    scroll,\n\n    getSelection: selection.get,\n    setSelection: (ids) => selection.set([...ids]),\n\n    loadState(json, opts) {\n      // Validate + map up front: throws on a bad version or registry key before live state is touched.\n      const specs = specsFromSerialized(json, registry, { composition: scene.composition, ...opts });\n      if (mode.open()) {\n        throw new Error('Scene: cannot loadState inside another edit — it replaces the state that edit would revert to');\n      }\n      // Ephemeral, and every id is a new node after this.\n      overrides.clearAll();\n      scroll.clearAll();\n      doc.reset(json.systemLayers.map(layerFromSerialized), json.doc);\n      recording.clearHistory();\n      poseWrites.quiet(() => edits.construct(specs));\n      selection.replace(locks.reachable(selection.get().filter((id) => state.nodes.has(id))));\n      notifier.notify();\n    },\n\n    ...sceneChanges(notifier, selection),\n  };\n\n  const initial = initialNodes(registry);\n  if (initial) {\n    poseWrites.quiet(() => edits.construct(initial));\n    notifier.notify();\n  }\n\n  return scene;\n}\n\n/** Reconstruct a Scene from a JSON snapshot produced by `scene.toJSON()`.\n *  Function fields (e.g., `clipFromPose`) are resolved by string key via the\n *  registry passed in `options`. Throws on unknown version, unknown registry\n *  keys, or invalid scene shape (cross-layer subtrees, unknown layer ids).\n *  The scene starts with empty history. */\nexport function sceneFromJSON<TData, TLayer extends string, TPose>(\n  json: SavedScene<TData, TLayer, TPose>,\n  options: {\n    registry?: SceneRegistry<TPose, TData, TLayer>;\n    historyLimit?: number;\n    coalesceWindowMs?: number;\n    generateId?: () => NodeId;\n    ops?: Readonly<Record<string, RegisteredOp<unknown>>>;\n    composition?: SceneOptions<TData, TLayer, TPose>['composition'];\n    layoutFrame?: SceneOptions<TData, TLayer, TPose>['layoutFrame'];\n  } & SpecsFromSerializedOptions<TData, TLayer, TPose> = {},\n): Scene<TData, TLayer, TPose> {\n  return buildScene(\n    options,\n    json.systemLayers.map(layerFromSerialized),\n    (registry) => specsFromSerialized(json, registry, options),\n    json.doc,\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"scene.js","names":[],"sources":["../../../src/core/scene/scene.ts"],"sourcesContent":["import { withKitRegistry } from './kitRegistry';\nimport { createPoseOverrides } from './poseOverrides';\nimport { createScrollOffsets } from './scrollOffsets';\nimport { createArrivalWindow } from './arrivalWindow';\nimport { documentReads, sceneMutators } from './sceneMutators';\nimport { createNotifier } from './notifier';\nimport type { SerializedDoc } from './docValues';\nimport { sceneChanges } from './sceneChanges';\nimport { createPoseWriteLog } from './poseWrites';\nimport { effectivePose } from './effectivePose';\nimport { createEditMode } from './editMode';\nimport { createSceneEdits } from './sceneEdits';\nimport { createSceneRecording } from './sceneRecording';\nimport { createSceneSelection } from './sceneSelection';\nimport { createSceneState } from './sceneState';\nimport { systemLayerRecord } from './layerStack';\nimport { layerFromSerialized, specsFromSerialized, type SpecsFromSerializedOptions } from './serialization';\nimport { resolveLayoutFrame, runLayoutPass } from './layoutPass';\nimport type { PoseComposition } from './composeFrame';\nimport { RIGID_POSE_COMPOSITION } from './composePose';\nimport type { SceneOptions } from './useSceneOptions';\nimport {\n  asNodeId,\n  type AddNodeSpec,\n  type LayerRecord,\n  type NodeId,\n  type RegisteredOp,\n  type Scene,\n  type SceneRegistry,\n  type SavedScene,\n  type UseSceneOptions,\n} from './types';\n\n/** A node still in `scene`, with the pose it is shown at. */\nfunction shownNode<TData, TLayer extends string, TPose>(scene: Scene<TData, TLayer, TPose>, id: NodeId) {\n  const node = scene.get(id);\n  return node && { node, pose: effectivePose(scene, node) };\n}\n\nlet defaultIdCounter = 0;\nconst defaultGenerateId = (): NodeId =>\n  asNodeId(`n${(defaultIdCounter++).toString(36)}-${Math.random().toString(36).slice(2, 8)}`);\n\n/** Build a scene outside React. `useScene` is the usual entry point; reach for\n *  this in tests, in headless rendering, or wherever a scene must outlive a\n *  component. Throws if no system layers are declared. */\nexport function createScene<TData, TLayer extends string, TPose = import('./composePose').RectPose>(\n  options: UseSceneOptions<TData, TLayer, TPose>,\n): Scene<TData, TLayer, TPose> {\n  return buildScene(options, (options.systemLayers ?? []).map(systemLayerRecord), () => options.initial, options.doc);\n}\n\ntype SceneConfig<TData, TLayer extends string, TPose> =\n  Omit<SceneOptions<TData, TLayer, TPose>, 'systemLayers' | 'initial' | 'doc'>;\n\n/** A scene holding `layers`, the document values `initialDoc`, and the nodes\n *  `initialNodes` answers with once it is handed the registry their functions\n *  resolve against. */\nfunction buildScene<TData, TLayer extends string, TPose>(\n  options: SceneConfig<TData, TLayer, TPose>,\n  layers: readonly LayerRecord<TLayer>[],\n  initialNodes: (registry: SceneRegistry<TPose, TData, TLayer>) => readonly AddNodeSpec<TData, TLayer, TPose>[] | undefined,\n  initialDoc: SerializedDoc | undefined,\n): Scene<TData, TLayer, TPose> {\n  if (layers.length === 0) throw new Error('Scene: systemLayers must declare at least one layer');\n\n  // The kit's own registry entries sit under the consumer's, so a snapshot carrying a kit-attached\n  // function (a grouped container's derived pose) reloads in any scene, not only one that registered it.\n  const registry = withKitRegistry(options.registry ?? {});\n\n  const doc = createSceneState<TData, TLayer, TPose>(registry, layers, () => arrivals.layoutDeclared(), initialDoc);\n  const { state, locks, reads } = doc;\n  const notifier = createNotifier();\n  const mode = createEditMode();\n  const poseWrites = createPoseWriteLog({ untracked: mode.untracked, changes: notifier, shown: (id) => shownNode(scene, id) });\n  const writePose = (id: string, pose: unknown): void => poseWrites.layout(() => scene.setPose(asNodeId(id), pose as TPose));\n\n  const layoutFrame = resolveLayoutFrame(options.layoutFrame);\n  const arrivals = createArrivalWindow<TData, TLayer, TPose>({\n    nodes: state.nodes,\n    layoutPass: (arrived, touched, departed) =>\n      runLayoutPass(scene, reads.layoutOf, arrived, touched, layoutFrame, departed),\n    recordsBareEdits: () => !mode.open(),\n    writePose,\n  });\n\n  const generateId = options.generateId ?? defaultGenerateId;\n  const selection = createSceneSelection(locks.reachable, (id) => state.nodes.get(id)?.parent);\n  // A selection change is a scene change to every subscriber.\n  selection.subscribe(notifier.notify);\n\n  /** Ephemeral, deliberately not part of `state`: not document content, never in `toJSON` or history. */\n  const overrides = createPoseOverrides<TPose, TData>((id) => state.nodes.get(id), doc.store.invalidateDependents);\n  const scroll = createScrollOffsets();\n\n  const recording = createSceneRecording({\n    notifier,\n    mode,\n    passAdapter: () => ({ ...sceneMutators(scene), ...documentReads(scene) }),\n    stale: doc.stale,\n    lifted: locks.lifted,\n    selection,\n    arrivals,\n    writePose,\n    poseWrites,\n    config: options,\n  });\n\n  const edits = createSceneEdits<TData, TLayer, TPose>({\n    state,\n    store: doc.store,\n    locks,\n    layers: doc.layers,\n    invalidateOrder: doc.order.invalidate,\n    fnFields: doc.fnFields,\n    ops: { ...recording.ops, register: poseWrites.reporting(recording.ops.register) },\n    recorder: recording.recorder,\n    arrivals,\n    layoutFrame,\n    generateId,\n    narrowSelection: selection.narrow,\n    clearOverride: overrides.clear,\n  });\n  for (const [kind, handler] of Object.entries(options.ops ?? {})) recording.ops.register(kind, handler);\n\n  const scene: Scene<TData, TLayer, TPose> = {\n    get nodes() { return state.nodes; },\n    get roots() { return state.roots; },\n    get layers() { return state.layers; },\n    registry,\n\n    ...reads,\n\n    mintId: generateId,\n    composition: options.composition ?? (RIGID_POSE_COMPOSITION as PoseComposition<TPose>),\n\n    ...edits.methods,\n    ...recording.methods,\n\n    unlocked: (fn) => locks.lifted(fn),\n\n    setArrivalHandler: arrivals.setHandler,\n    onReflow: arrivals.onReflow,\n    onPoseWrite: poseWrites.subscribe,\n\n    overrides,\n    scroll,\n\n    getSelection: selection.get,\n    setSelection: (ids) => selection.set([...ids]),\n\n    loadState(json, opts) {\n      // Validate + map up front: throws on a bad version or registry key before live state is touched.\n      const specs = specsFromSerialized(json, registry, { composition: scene.composition, ...opts });\n      if (mode.open()) {\n        throw new Error('Scene: cannot loadState inside another edit — it replaces the state that edit would revert to');\n      }\n      // Ephemeral, and every id is a new node after this.\n      overrides.clearAll();\n      scroll.clearAll();\n      doc.reset(json.systemLayers.map(layerFromSerialized), json.doc);\n      recording.clearHistory();\n      poseWrites.quiet(() => edits.construct(specs));\n      selection.replace(selection.legal(selection.get().filter((id) => state.nodes.has(id))));\n      notifier.notify();\n    },\n\n    ...sceneChanges(notifier, selection),\n  };\n\n  const initial = initialNodes(registry);\n  if (initial) {\n    poseWrites.quiet(() => edits.construct(initial));\n    notifier.notify();\n  }\n\n  return scene;\n}\n\n/** Reconstruct a Scene from a JSON snapshot produced by `scene.toJSON()`.\n *  Function fields (e.g., `clipFromPose`) are resolved by string key via the\n *  registry passed in `options`. Throws on unknown version, unknown registry\n *  keys, or invalid scene shape (cross-layer subtrees, unknown layer ids).\n *  The scene starts with empty history. */\nexport function sceneFromJSON<TData, TLayer extends string, TPose>(\n  json: SavedScene<TData, TLayer, TPose>,\n  options: {\n    registry?: SceneRegistry<TPose, TData, TLayer>;\n    historyLimit?: number;\n    coalesceWindowMs?: number;\n    generateId?: () => NodeId;\n    ops?: Readonly<Record<string, RegisteredOp<unknown>>>;\n    composition?: SceneOptions<TData, TLayer, TPose>['composition'];\n    layoutFrame?: SceneOptions<TData, TLayer, TPose>['layoutFrame'];\n  } & SpecsFromSerializedOptions<TData, TLayer, TPose> = {},\n): Scene<TData, TLayer, TPose> {\n  return buildScene(\n    options,\n    json.systemLayers.map(layerFromSerialized),\n    (registry) => specsFromSerialized(json, registry, options),\n    json.doc,\n  );\n}\n"],"mappings":"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"}

package/dist/core/scene/sceneChanges.js

@@ -1,4 +1,4 @@
-//#region src/core/scene/sceneChanges.ts
+// src/core/scene/sceneChanges.ts
 /** A scene's change members, over its notifier and its selection's own count of changes. */
 function sceneChanges(notifier, selection) {
 	return {
@@ -8,6 +8,5 @@ function sceneChanges(notifier, selection) {
 	};
 }
 
-//#endregion
 export { sceneChanges };
 //# sourceMappingURL=sceneChanges.js.map

package/dist/core/scene/sceneEdits.js

@@ -6,7 +6,7 @@ import { createNodeFlags } from "./nodeFlags.js";
 import { createLayerEdits } from "./layerStack.js";
 import { createTreeEdits } from "./treeEdits.js";
 
-//#region src/core/scene/sceneEdits.ts
+// src/core/scene/sceneEdits.ts
 function createSceneEdits(env) {
 	const { state, store, locks, layers, fnFields, recorder, arrivals } = env;
 	const { layoutRefs } = registerKitOps({
@@ -84,6 +84,5 @@ function createSceneEdits(env) {
 	};
 }
 
-//#endregion
 export { createSceneEdits };
 //# sourceMappingURL=sceneEdits.js.map

package/dist/core/scene/sceneJournals.js

@@ -1,4 +1,4 @@
-//#region src/core/scene/sceneJournals.ts
+// src/core/scene/sceneJournals.ts
 /** A journal drives adapter mutation itself, so its applies and undos
 *  re-enter scene mutation methods the way the facade's do. */
 function wrapJournal(raw, env, open) {
@@ -73,6 +73,5 @@ function createSceneJournals(env) {
 	};
 }
 
-//#endregion
 export { createSceneJournals };
 //# sourceMappingURL=sceneJournals.js.map

package/dist/core/scene/sceneMutators.js

@@ -1,9 +1,9 @@
 import { documentPose } from "./effectivePose.js";
-import { asNodeId } from "./types.js";
 import { fnFieldsOfNode } from "./nodeFnFields.js";
 import { statedFields } from "./statedFields.js";
+import { asNodeId } from "./types.js";
 
-//#region src/core/scene/sceneMutators.ts
+// src/core/scene/sceneMutators.ts
 function sceneMutators(scene) {
 	const getChildren = (parentId) => parentId === null ? [...scene.roots] : [...scene.childrenOf(asNodeId(parentId))];
 	return {
@@ -53,6 +53,5 @@ function documentReads(scene) {
 	};
 }
 
-//#endregion
 export { documentReads, sceneMutators };
 //# sourceMappingURL=sceneMutators.js.map

package/dist/core/scene/scenePoseAdapter.js

@@ -1,7 +1,7 @@
 import { definesFrame, documentPose } from "./effectivePose.js";
 import { viewPoseAdapter } from "./scrollOffsets.js";
 
-//#region src/core/scene/scenePoseAdapter.ts
+// src/core/scene/scenePoseAdapter.ts
 /** Build a `PoseAdapter` over a `Scene` for `composePose` helpers.
 *  `getParent` returns the live parent at call time so mid-batch
 *  parent updates compose correctly. */
@@ -24,6 +24,5 @@ function sceneViewPoseAdapter(scene) {
 	return viewPoseAdapter(scene, scenePoseAdapter(scene));
 }
 
-//#endregion
 export { scenePoseAdapter, sceneViewPoseAdapter };
 //# sourceMappingURL=scenePoseAdapter.js.map

package/dist/core/scene/sceneRecording.js

@@ -6,7 +6,7 @@ import { createOpTable } from "./opTable.js";
 import { createOuterOps } from "./outerOps.js";
 import { createRecorder } from "./recorder.js";
 
-//#region src/core/scene/sceneRecording.ts
+// src/core/scene/sceneRecording.ts
 function createSceneRecording(env) {
 	const { notifier, mode, stale, lifted, selection, arrivals, config, poseWrites } = env;
 	const { notify } = notifier;
@@ -120,6 +120,5 @@ function createSceneRecording(env) {
 	};
 }
 
-//#endregion
 export { createSceneRecording };
 //# sourceMappingURL=sceneRecording.js.map

package/dist/core/scene/sceneSelection.js

@@ -1,19 +1,23 @@
 import { createEmitter } from "@weasel-js/registry";
+import { outermost } from "@weasel-js/select";
 
-//#region src/core/scene/sceneSelection.ts
-function createSceneSelection(reachable) {
+// src/core/scene/sceneSelection.ts
+function createSceneSelection(reachable, parentOf) {
+	const legal = (next) => outermost(reachable(next), parentOf);
 	let ids = [];
 	let changes = 0;
 	const changed = createEmitter();
 	return {
 		get: () => ids,
+		legal,
 		set(next) {
-			ids = reachable(next);
+			ids = legal(next);
 			changes++;
 			changed.emit();
 		},
 		narrow(gone) {
-			ids = reachable(gone !== void 0 && ids.some((id) => gone.has(id)) ? ids.filter((id) => !gone.has(id)) : ids);
+			const kept = gone !== void 0 && ids.some((id) => gone.has(id)) ? ids.filter((id) => !gone.has(id)) : ids;
+			ids = legal(kept);
 		},
 		replace(next) {
 			ids = next;
@@ -33,6 +37,5 @@ function sceneSelectionStore(scene) {
 	};
 }
 
-//#endregion
 export { createSceneSelection, sceneSelectionStore };
 //# sourceMappingURL=sceneSelection.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"sceneSelection.js","names":[],"sources":["../../../src/core/scene/sceneSelection.ts"],"sourcesContent":["/**\n * The scene's selection: the transient set of active ids. Not document\n * content, so it never reaches `toJSON`; it does ride on history entries.\n */\nimport type { HistorySelection } from '@weasel-js/history';\nimport { createEmitter } from '@weasel-js/registry';\nimport type { NodeId } from './types';\n\nexport interface SceneSelection {\n  get(): readonly NodeId[];\n  /** Select the ids of `ids` that are in reach, and tell subscribers. */\n  set(ids: readonly NodeId[]): void;\n  /** Drop the ids in `gone`, and any a lock has put out of reach. Tells no\n   *  one: the edit that took them is what subscribers hear about. */\n  narrow(gone?: ReadonlySet<NodeId>): void;\n  /** Put a selection in place exactly as given, telling no one: for a caller\n   *  returning what it read earlier, or one that has already filtered. */\n  replace(ids: readonly NodeId[]): void;\n  subscribe(listener: () => void): () => void;\n  /** How many times subscribers have been told the selection changed. */\n  changes(): number;\n}\n\nexport function createSceneSelection(\n  /** `ids` less those out of reach; the same array when none is. */\n  reachable: (ids: readonly NodeId[]) => readonly NodeId[],\n): SceneSelection {\n  let ids: readonly NodeId[] = [];\n  let changes = 0;\n  const changed = createEmitter();\n\n  return {\n    get: () => ids,\n    set(next) {\n      ids = reachable(next);\n      changes++;\n      changed.emit();\n    },\n    narrow(gone) {\n      // A new array only when one is dropped: readers compare the selection by identity.\n      const kept = gone !== undefined && ids.some((id) => gone.has(id)) ? ids.filter((id) => !gone.has(id)) : ids;\n      ids = reachable(kept);\n    },\n    replace(next) {\n      ids = next;\n    },\n    subscribe: changed.subscribe,\n    changes: () => changes,\n  };\n}\n\n/** The scene's selection in the shape `createHistory` wants, for a consumer\n *  building a second History over the same scene (a modality machine, a\n *  journal owner) that should restore selection the way the scene's own\n *  history does. */\nexport function sceneSelectionStore(scene: {\n  getSelection(): readonly NodeId[];\n  setSelection(ids: readonly NodeId[]): void;\n}): HistorySelection {\n  return {\n    get: () => scene.getSelection(),\n    set: (ids) => scene.setSelection(ids as readonly NodeId[]),\n  };\n}\n"],"mappings":";;;AAuBA,SAAgB,qBAEd,WACgB;CAChB,IAAI,MAAyB,CAAC;CAC9B,IAAI,UAAU;CACd,MAAM,UAAU,cAAc;CAE9B,OAAO;EACL,WAAW;EACX,IAAI,MAAM;GACR,MAAM,UAAU,IAAI;GACpB;GACA,QAAQ,KAAK;EACf;EACA,OAAO,MAAM;GAGX,MAAM,UADO,SAAS,UAAa,IAAI,MAAM,OAAO,KAAK,IAAI,EAAE,CAAC,IAAI,IAAI,QAAQ,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI,GACpF;EACtB;EACA,QAAQ,MAAM;GACZ,MAAM;EACR;EACA,WAAW,QAAQ;EACnB,eAAe;CACjB;AACF;;;;;AAMA,SAAgB,oBAAoB,OAGf;CACnB,OAAO;EACL,WAAW,MAAM,aAAa;EAC9B,MAAM,QAAQ,MAAM,aAAa,GAAwB;CAC3D;AACF"}
+{"version":3,"file":"sceneSelection.js","names":[],"sources":["../../../src/core/scene/sceneSelection.ts"],"sourcesContent":["/**\n * The scene's selection: the transient set of active ids. Not document\n * content, so it never reaches `toJSON`; it does ride on history entries.\n * A selected node holds its subtree, so the selection keeps only the\n * outermost of the ids written to it.\n */\nimport type { HistorySelection } from '@weasel-js/history';\nimport { createEmitter } from '@weasel-js/registry';\nimport { outermost } from '@weasel-js/select';\nimport type { NodeId } from './types';\n\nexport interface SceneSelection {\n  get(): readonly NodeId[];\n  /** `ids` as the selection may hold them: in reach, and none held by an ancestor among them. */\n  legal(ids: readonly NodeId[]): readonly NodeId[];\n  /** Select the ids of `ids` that are in reach, and tell subscribers. */\n  set(ids: readonly NodeId[]): void;\n  /** Drop the ids in `gone`, any a lock has put out of reach, and any an\n   *  ancestor now holds. Tells no one: the edit that took them is what\n   *  subscribers hear about. */\n  narrow(gone?: ReadonlySet<NodeId>): void;\n  /** Put a selection in place exactly as given, telling no one: for a caller\n   *  returning what it read earlier, or one that has already filtered. */\n  replace(ids: readonly NodeId[]): void;\n  subscribe(listener: () => void): () => void;\n  /** How many times subscribers have been told the selection changed. */\n  changes(): number;\n}\n\nexport function createSceneSelection(\n  /** `ids` less those out of reach; the same array when none is. */\n  reachable: (ids: readonly NodeId[]) => readonly NodeId[],\n  parentOf: (id: NodeId) => NodeId | null | undefined,\n): SceneSelection {\n  const legal = (next: readonly NodeId[]) => outermost(reachable(next), parentOf);\n  let ids: readonly NodeId[] = [];\n  let changes = 0;\n  const changed = createEmitter();\n\n  return {\n    get: () => ids,\n    legal,\n    set(next) {\n      ids = legal(next);\n      changes++;\n      changed.emit();\n    },\n    narrow(gone) {\n      // A new array only when one is dropped: readers compare the selection by identity.\n      const kept = gone !== undefined && ids.some((id) => gone.has(id)) ? ids.filter((id) => !gone.has(id)) : ids;\n      ids = legal(kept);\n    },\n    replace(next) {\n      ids = next;\n    },\n    subscribe: changed.subscribe,\n    changes: () => changes,\n  };\n}\n\n/** The scene's selection in the shape `createHistory` wants, for a consumer\n *  building a second History over the same scene (a modality machine, a\n *  journal owner) that should restore selection the way the scene's own\n *  history does. */\nexport function sceneSelectionStore(scene: {\n  getSelection(): readonly NodeId[];\n  setSelection(ids: readonly NodeId[]): void;\n}): HistorySelection {\n  return {\n    get: () => scene.getSelection(),\n    set: (ids) => scene.setSelection(ids as readonly NodeId[]),\n  };\n}\n"],"mappings":";;;;AA6BA,SAAgB,qBAEd,WACA,UACgB;CAChB,MAAM,SAAS,SAA4B,UAAU,UAAU,IAAI,GAAG,QAAQ;CAC9E,IAAI,MAAyB,CAAC;CAC9B,IAAI,UAAU;CACd,MAAM,UAAU,cAAc;CAE9B,OAAO;EACL,WAAW;EACX;EACA,IAAI,MAAM;GACR,MAAM,MAAM,IAAI;GAChB;GACA,QAAQ,KAAK;EACf;EACA,OAAO,MAAM;GAEX,MAAM,OAAO,SAAS,UAAa,IAAI,MAAM,OAAO,KAAK,IAAI,EAAE,CAAC,IAAI,IAAI,QAAQ,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,IAAI;GACxG,MAAM,MAAM,IAAI;EAClB;EACA,QAAQ,MAAM;GACZ,MAAM;EACR;EACA,WAAW,QAAQ;EACnB,eAAe;CACjB;AACF;;;;;AAMA,SAAgB,oBAAoB,OAGf;CACnB,OAAO;EACL,WAAW,MAAM,aAAa;EAC9B,MAAM,QAAQ,MAAM,aAAa,GAAwB;CAC3D;AACF"}

package/dist/core/scene/sceneState.js

@@ -1,14 +1,14 @@
-import { createNodeFnFields } from "./nodeFnFields.js";
 import { createDocStore } from "./docValues.js";
 import { createLayerStack } from "./layerStack.js";
-import { createStaleReplay } from "./staleReplay.js";
 import { createLockGuard } from "./lockGuard.js";
+import { createNodeFnFields } from "./nodeFnFields.js";
 import { createNodeStore } from "./nodeStore.js";
 import { createRenderOrder } from "./renderOrder.js";
 import { serializeScene } from "./serialization.js";
+import { createStaleReplay } from "./staleReplay.js";
 import { createTreeReads } from "./treeReads.js";
 
-//#region src/core/scene/sceneState.ts
+// src/core/scene/sceneState.ts
 /**
 * A scene's document state — its nodes, roots, and layers — with the modules
 * that read and write it directly.
@@ -67,6 +67,5 @@ function createSceneState(registry, initialLayers, layoutDeclared, initialDoc) {
 	};
 }
 
-//#endregion
 export { createSceneState };
 //# sourceMappingURL=sceneState.js.map

package/dist/core/scene/scrollOffsets.js

@@ -1,7 +1,7 @@
 import { isDocument } from "./documentOf.js";
 import { createEmitter } from "@weasel-js/registry";
 
-//#region src/core/scene/scrollOffsets.ts
+// src/core/scene/scrollOffsets.ts
 /**
 * How far each container's content is scrolled: view state, never document.
 *
@@ -88,6 +88,5 @@ function viewPoseAdapter(scene, adapter) {
 	};
 }
 
-//#endregion
 export { createScrollOffsets, scrolledFrames, viewPoseAdapter };
 //# sourceMappingURL=scrollOffsets.js.map

package/dist/core/scene/serialization.js

@@ -1,9 +1,9 @@
-import { RIGID_POSE_COMPOSITION } from "./composePose.js";
 import { NODE_FN_FIELDS, fnKeysOf } from "./nodeFnFields.js";
 import { treePreorder } from "./treeOrder.js";
+import { RIGID_POSE_COMPOSITION } from "./composePose.js";
 import { localizeWorldPoses } from "./worldSave.js";
 
-//#region src/core/scene/serialization.ts
+// src/core/scene/serialization.ts
 /**
 * A scene to and from its JSON snapshot: the walk that writes one, and the
 * two readers that turn one back into layer records and node specs.
@@ -151,6 +151,5 @@ function nodeKindOf(version, n, classify) {
 	return classify ? classify(n) : "group";
 }
 
-//#endregion
 export { isSerializedScene, layerFromSerialized, nodeKindOf, serializeScene, specsFromSerialized };
 //# sourceMappingURL=serialization.js.map

package/dist/core/scene/staleReplay.js

@@ -1,6 +1,6 @@
 import { hasChildren } from "./treeShape.js";
 
-//#region src/core/scene/staleReplay.ts
+// src/core/scene/staleReplay.ts
 /** A scene edit named a node the scene does not hold, or one it already does. */
 var SceneMembershipError = class extends Error {};
 function createStaleReplay(nodes) {
@@ -58,6 +58,5 @@ function createStaleReplay(nodes) {
 	};
 }
 
-//#endregion
 export { SceneMembershipError, createStaleReplay };
 //# sourceMappingURL=staleReplay.js.map

package/dist/core/scene/statedFields.js

@@ -1,4 +1,4 @@
-//#region src/core/scene/statedFields.ts
+// src/core/scene/statedFields.ts
 /** The plain optional fields of a node or spec as a spread for `scene.add`:
 *  each present only when stated, so an unstated one keeps the scene's
 *  default, and a flag states only `true`. What a copy of a node carries over
@@ -14,6 +14,5 @@ function statedFields(n) {
 	return out;
 }
 
-//#endregion
 export { statedFields };
 //# sourceMappingURL=statedFields.js.map

package/dist/core/scene/strategyView.js

@@ -1,6 +1,6 @@
 import { samePoseValue } from "./poseSnapshot.js";
 
-//#region src/core/scene/strategyView.ts
+// src/core/scene/strategyView.ts
 /**
 * How a strategy sees a container at world `pose`: upright, in its own frame,
 * moved so its box is centered on the box `measure` gives the world pose. A
@@ -30,6 +30,5 @@ function strategyView(pose, { compose, decompose }, measure, place) {
 	};
 }
 
-//#endregion
 export { strategyView };
 //# sourceMappingURL=strategyView.js.map

package/dist/core/scene/treeEdits.js

@@ -1,8 +1,8 @@
 import { fnKeysOf } from "./nodeFnFields.js";
-import { statedFields } from "./statedFields.js";
 import { SceneMembershipError } from "./staleReplay.js";
+import { statedFields } from "./statedFields.js";
 
-//#region src/core/scene/treeEdits.ts
+// src/core/scene/treeEdits.ts
 /** What `kit:remove` carries for the nodes `ids`, read before any of them
 *  goes. Throws on an id that is not in the scene. */
 function removeSnapshot(ids, removing, store, fnFields) {
@@ -146,6 +146,5 @@ function createTreeEdits(env) {
 	};
 }
 
-//#endregion
 export { createTreeEdits };
 //# sourceMappingURL=treeEdits.js.map

package/dist/core/scene/treeOrder.js

@@ -1,6 +1,6 @@
 import { hasChildren } from "./treeShape.js";
 
-//#region src/core/scene/treeOrder.ts
+// src/core/scene/treeOrder.ts
 /** Every node reachable from `roots`, in tree preorder: a parent before its
 *  children, siblings in sibling order, whatever layer each sits on. */
 function treePreorder(roots, nodes) {
@@ -15,6 +15,5 @@ function treePreorder(roots, nodes) {
 	return out;
 }
 
-//#endregion
 export { treePreorder };
 //# sourceMappingURL=treeOrder.js.map

package/dist/core/scene/treeReads.js

@@ -1,4 +1,4 @@
-//#region src/core/scene/treeReads.ts
+// src/core/scene/treeReads.ts
 function createTreeReads(nodes) {
 	const incarnations = /* @__PURE__ */ new WeakMap();
 	let nextIncarnation = 1;
@@ -29,6 +29,5 @@ function createTreeReads(nodes) {
 	};
 }
 
-//#endregion
 export { createTreeReads };
 //# sourceMappingURL=treeReads.js.map

package/dist/core/scene/treeShape.js

@@ -1,4 +1,4 @@
-//#region src/core/scene/treeShape.ts
+// src/core/scene/treeShape.ts
 /** True for a node with no children: absent and empty are the same thing. */
 function isLeaf(node) {
 	return node.children === void 0 || node.children.length === 0;
@@ -8,6 +8,5 @@ function hasChildren(node) {
 	return node.children !== void 0 && node.children.length > 0;
 }
 
-//#endregion
 export { hasChildren, isLeaf };
 //# sourceMappingURL=treeShape.js.map

package/dist/core/scene/types.js

@@ -1,7 +1,6 @@
-//#region src/core/scene/types.ts
+// src/core/scene/types.ts
 /** Brand a string as a NodeId. */
 var asNodeId = (s) => s;
 
-//#endregion
 export { asNodeId };
 //# sourceMappingURL=types.js.map

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"}