@weasel-js/core 1.11.0 → 1.12.0

package/dist/core/scene/sceneMutators.js

@@ -23,6 +23,7 @@ function sceneMutators(scene) {
 		},
 		setData: (id, data) => scene.update(asNodeId(id), { data }),
 		setLayer: (id, layer) => scene.setLayer(asNodeId(id), layer),
+		setDependsOn: (id, dependsOn) => scene.setDependsOn(asNodeId(id), Array.isArray(dependsOn) ? dependsOn.map(asNodeId) : dependsOn),
 		setLayout: (id, layout) => scene.setLayout(asNodeId(id), layout),
 		setHidden: (id, hidden) => scene.setHidden(asNodeId(id), hidden),
 		setLocked: (id, locked) => scene.setLocked(asNodeId(id), locked),

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

@@ -1 +1 @@
-{"version":3,"file":"sceneMutators.js","names":[],"sources":["../../../src/core/scene/sceneMutators.ts"],"sourcesContent":["/**\n * What every scene-backed adapter shares: the writes an op applies through,\n * and the structural reads those ops need. `sceneToAdapter`,\n * `defaultCommitAdapter`, and `moveGestureAdapter` all build on it.\n *\n * It leaves out the pose and node-list reads, where the adapters differ on\n * purpose. The canvas adapter answers with what is shown: the effective pose,\n * visible layers only. An adapter ops commit through answers with what the\n * document holds, which is {@link documentReads}.\n */\nimport type { LayoutStrategy } from '../../layout/types';\nimport { documentPose } from './effectivePose';\nimport { fnFieldsOfNode } from './nodeFnFields';\nimport { statedFields } from './statedFields';\nimport { asNodeId, type Node, type Scene } from './types';\n\nexport interface SceneMutators<TData, TLayer extends string, TPose> {\n  getNode(id: string): Node<TData, TLayer, TPose> | undefined;\n  getParent(id: string): string | null;\n  /** Ordered children of `parentId`; `null` names the root siblings. */\n  getChildren(parentId: string | null): string[];\n  /** Every id removing `ids` takes: their subtrees and their dependents. */\n  getRemovalClosure(ids: readonly string[]): string[];\n  setPose(id: string, pose: TPose): void;\n  setParent(id: string, parentId: string | null): void;\n  /** One undo step when called bare; inside a batch it joins that batch. */\n  setChildOrder(parentId: string | null, ids: string[]): void;\n  setData(id: string, data: TData): void;\n  setLayer(id: string, layer: TLayer): void;\n  setLayout(id: string, layout: LayoutStrategy<TPose> | string | null): void;\n  /** What a `setHidden` op writes through. */\n  setHidden(id: string, hidden: boolean): void;\n  /** What a `setLocked` op writes through. */\n  setLocked(id: string, locked: boolean): void;\n  removeNode(id: string): void;\n  /** Re-add `node` as it was, at sibling `index` when one is given. */\n  insertNode(node: Node<TData, TLayer, TPose>, index?: number): void;\n}\n\nexport function sceneMutators<TData, TLayer extends string, TPose>(\n  scene: Scene<TData, TLayer, TPose>,\n): SceneMutators<TData, TLayer, TPose> {\n  const getChildren = (parentId: string | null): string[] =>\n    (parentId === null ? [...scene.roots] : [...scene.childrenOf(asNodeId(parentId))]);\n  return {\n    getNode: (id) => scene.get(asNodeId(id)),\n    getParent: (id) => scene.get(asNodeId(id))?.parent ?? null,\n    getChildren,\n    getRemovalClosure: (ids) => [...scene.removalClosure(ids.map(asNodeId))],\n    setPose: (id, pose) => scene.setPose(asNodeId(id), pose),\n    setParent: (id, parentId) => scene.move(asNodeId(id), parentId == null ? null : asNodeId(parentId)),\n    setChildOrder: (parentId, ids) => {\n      scene.batch('Reorder', () => {\n        for (let i = 0; i < ids.length; i++) {\n          // Re-read each time: a reorder shifts later ids, sometimes into place.\n          if (getChildren(parentId)[i] === ids[i]) continue;\n          scene.reorder(asNodeId(ids[i]), i);\n        }\n      });\n    },\n    setData: (id, data) => scene.update(asNodeId(id), { data }),\n    setLayer: (id, layer) => scene.setLayer(asNodeId(id), layer),\n    setLayout: (id, layout) => scene.setLayout(asNodeId(id), layout),\n    setHidden: (id, hidden) => scene.setHidden(asNodeId(id), hidden),\n    setLocked: (id, locked) => scene.setLocked(asNodeId(id), locked),\n    removeNode: (id) => scene.remove(asNodeId(id)),\n    insertNode: (node, index) => {\n      scene.add({\n        kind: node.kind,\n        layer: node.layer,\n        pose: node.pose,\n        data: node.data,\n        id: node.id,\n        ...(index !== undefined ? { index } : {}),\n        ...(node.parent != null ? { parent: node.parent } : {}),\n        // Derivation travels with the node, or undo of a delete brings an\n        // edge back as a static path that never follows its endpoints again.\n        ...(node.dependsOn !== undefined ? { dependsOn: node.dependsOn } : {}),\n        ...statedFields(node),\n        ...fnFieldsOfNode(node),\n      });\n    },\n  };\n}\n\n/** The pose and node-list reads of an adapter ops commit through: the document,\n *  whatever a gesture is showing and whichever layers are hidden. */\nexport function documentReads<TData, TLayer extends string, TPose>(\n  scene: Scene<TData, TLayer, TPose>,\n): { getPose(id: string): TPose; getNodes(): Node<TData, TLayer, TPose>[] } {\n  return {\n    getPose: (id) => documentPose(scene, scene.get(asNodeId(id))!),\n    getNodes: () => [...scene.renderOrderNodes()],\n  };\n}\n"],"mappings":";;;;;;AAuCA,SAAgB,cACd,OACqC;CACrC,MAAM,eAAe,aAClB,aAAa,OAAO,CAAC,GAAG,MAAM,KAAK,IAAI,CAAC,GAAG,MAAM,WAAW,SAAS,QAAQ,CAAC,CAAC;CAClF,OAAO;EACL,UAAU,OAAO,MAAM,IAAI,SAAS,EAAE,CAAC;EACvC,YAAY,OAAO,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU;EACtD;EACA,oBAAoB,QAAQ,CAAC,GAAG,MAAM,eAAe,IAAI,IAAI,QAAQ,CAAC,CAAC;EACvE,UAAU,IAAI,SAAS,MAAM,QAAQ,SAAS,EAAE,GAAG,IAAI;EACvD,YAAY,IAAI,aAAa,MAAM,KAAK,SAAS,EAAE,GAAG,YAAY,OAAO,OAAO,SAAS,QAAQ,CAAC;EAClG,gBAAgB,UAAU,QAAQ;GAChC,MAAM,MAAM,iBAAiB;IAC3B,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;KAEnC,IAAI,YAAY,QAAQ,CAAC,CAAC,OAAO,IAAI,IAAI;KACzC,MAAM,QAAQ,SAAS,IAAI,EAAE,GAAG,CAAC;IACnC;GACF,CAAC;EACH;EACA,UAAU,IAAI,SAAS,MAAM,OAAO,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC;EAC1D,WAAW,IAAI,UAAU,MAAM,SAAS,SAAS,EAAE,GAAG,KAAK;EAC3D,YAAY,IAAI,WAAW,MAAM,UAAU,SAAS,EAAE,GAAG,MAAM;EAC/D,YAAY,IAAI,WAAW,MAAM,UAAU,SAAS,EAAE,GAAG,MAAM;EAC/D,YAAY,IAAI,WAAW,MAAM,UAAU,SAAS,EAAE,GAAG,MAAM;EAC/D,aAAa,OAAO,MAAM,OAAO,SAAS,EAAE,CAAC;EAC7C,aAAa,MAAM,UAAU;GAC3B,MAAM,IAAI;IACR,MAAM,KAAK;IACX,OAAO,KAAK;IACZ,MAAM,KAAK;IACX,MAAM,KAAK;IACX,IAAI,KAAK;IACT,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;IACvC,GAAI,KAAK,UAAU,OAAO,EAAE,QAAQ,KAAK,OAAO,IAAI,CAAC;IAGrD,GAAI,KAAK,cAAc,SAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;IACpE,GAAG,aAAa,IAAI;IACpB,GAAG,eAAe,IAAI;GACxB,CAAC;EACH;CACF;AACF;;;AAIA,SAAgB,cACd,OAC0E;CAC1E,OAAO;EACL,UAAU,OAAO,aAAa,OAAO,MAAM,IAAI,SAAS,EAAE,CAAC,CAAE;EAC7D,gBAAgB,CAAC,GAAG,MAAM,iBAAiB,CAAC;CAC9C;AACF"}
+{"version":3,"file":"sceneMutators.js","names":[],"sources":["../../../src/core/scene/sceneMutators.ts"],"sourcesContent":["/**\n * What every scene-backed adapter shares: the writes an op applies through,\n * and the structural reads those ops need. `sceneToAdapter`,\n * `defaultCommitAdapter`, and `moveGestureAdapter` all build on it.\n *\n * It leaves out the pose and node-list reads, where the adapters differ on\n * purpose. The canvas adapter answers with what is shown: the effective pose,\n * visible layers only. An adapter ops commit through answers with what the\n * document holds, which is {@link documentReads}.\n */\nimport type { LayoutStrategy } from '../../layout/types';\nimport { documentPose } from './effectivePose';\nimport { fnFieldsOfNode } from './nodeFnFields';\nimport { statedFields } from './statedFields';\nimport { asNodeId, type Node, type Scene } from './types';\n\nexport interface SceneMutators<TData, TLayer extends string, TPose> {\n  getNode(id: string): Node<TData, TLayer, TPose> | undefined;\n  getParent(id: string): string | null;\n  /** Ordered children of `parentId`; `null` names the root siblings. */\n  getChildren(parentId: string | null): string[];\n  /** Every id removing `ids` takes: their subtrees and their dependents. */\n  getRemovalClosure(ids: readonly string[]): string[];\n  setPose(id: string, pose: TPose): void;\n  setParent(id: string, parentId: string | null): void;\n  /** One undo step when called bare; inside a batch it joins that batch. */\n  setChildOrder(parentId: string | null, ids: string[]): void;\n  setData(id: string, data: TData): void;\n  setLayer(id: string, layer: TLayer): void;\n  /** What a `setDependsOn` op writes through. */\n  setDependsOn(id: string, dependsOn: readonly string[] | 'children' | undefined): void;\n  setLayout(id: string, layout: LayoutStrategy<TPose> | string | null): void;\n  /** What a `setHidden` op writes through. */\n  setHidden(id: string, hidden: boolean): void;\n  /** What a `setLocked` op writes through. */\n  setLocked(id: string, locked: boolean): void;\n  removeNode(id: string): void;\n  /** Re-add `node` as it was, at sibling `index` when one is given. */\n  insertNode(node: Node<TData, TLayer, TPose>, index?: number): void;\n}\n\nexport function sceneMutators<TData, TLayer extends string, TPose>(\n  scene: Scene<TData, TLayer, TPose>,\n): SceneMutators<TData, TLayer, TPose> {\n  const getChildren = (parentId: string | null): string[] =>\n    (parentId === null ? [...scene.roots] : [...scene.childrenOf(asNodeId(parentId))]);\n  return {\n    getNode: (id) => scene.get(asNodeId(id)),\n    getParent: (id) => scene.get(asNodeId(id))?.parent ?? null,\n    getChildren,\n    getRemovalClosure: (ids) => [...scene.removalClosure(ids.map(asNodeId))],\n    setPose: (id, pose) => scene.setPose(asNodeId(id), pose),\n    setParent: (id, parentId) => scene.move(asNodeId(id), parentId == null ? null : asNodeId(parentId)),\n    setChildOrder: (parentId, ids) => {\n      scene.batch('Reorder', () => {\n        for (let i = 0; i < ids.length; i++) {\n          // Re-read each time: a reorder shifts later ids, sometimes into place.\n          if (getChildren(parentId)[i] === ids[i]) continue;\n          scene.reorder(asNodeId(ids[i]), i);\n        }\n      });\n    },\n    setData: (id, data) => scene.update(asNodeId(id), { data }),\n    setLayer: (id, layer) => scene.setLayer(asNodeId(id), layer),\n    setDependsOn: (id, dependsOn) =>\n      scene.setDependsOn(asNodeId(id), Array.isArray(dependsOn) ? dependsOn.map(asNodeId) : dependsOn as 'children' | undefined),\n    setLayout: (id, layout) => scene.setLayout(asNodeId(id), layout),\n    setHidden: (id, hidden) => scene.setHidden(asNodeId(id), hidden),\n    setLocked: (id, locked) => scene.setLocked(asNodeId(id), locked),\n    removeNode: (id) => scene.remove(asNodeId(id)),\n    insertNode: (node, index) => {\n      scene.add({\n        kind: node.kind,\n        layer: node.layer,\n        pose: node.pose,\n        data: node.data,\n        id: node.id,\n        ...(index !== undefined ? { index } : {}),\n        ...(node.parent != null ? { parent: node.parent } : {}),\n        // Derivation travels with the node, or undo of a delete brings an\n        // edge back as a static path that never follows its endpoints again.\n        ...(node.dependsOn !== undefined ? { dependsOn: node.dependsOn } : {}),\n        ...statedFields(node),\n        ...fnFieldsOfNode(node),\n      });\n    },\n  };\n}\n\n/** The pose and node-list reads of an adapter ops commit through: the document,\n *  whatever a gesture is showing and whichever layers are hidden. */\nexport function documentReads<TData, TLayer extends string, TPose>(\n  scene: Scene<TData, TLayer, TPose>,\n): { getPose(id: string): TPose; getNodes(): Node<TData, TLayer, TPose>[] } {\n  return {\n    getPose: (id) => documentPose(scene, scene.get(asNodeId(id))!),\n    getNodes: () => [...scene.renderOrderNodes()],\n  };\n}\n"],"mappings":";;;;;;AAyCA,SAAgB,cACd,OACqC;CACrC,MAAM,eAAe,aAClB,aAAa,OAAO,CAAC,GAAG,MAAM,KAAK,IAAI,CAAC,GAAG,MAAM,WAAW,SAAS,QAAQ,CAAC,CAAC;CAClF,OAAO;EACL,UAAU,OAAO,MAAM,IAAI,SAAS,EAAE,CAAC;EACvC,YAAY,OAAO,MAAM,IAAI,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU;EACtD;EACA,oBAAoB,QAAQ,CAAC,GAAG,MAAM,eAAe,IAAI,IAAI,QAAQ,CAAC,CAAC;EACvE,UAAU,IAAI,SAAS,MAAM,QAAQ,SAAS,EAAE,GAAG,IAAI;EACvD,YAAY,IAAI,aAAa,MAAM,KAAK,SAAS,EAAE,GAAG,YAAY,OAAO,OAAO,SAAS,QAAQ,CAAC;EAClG,gBAAgB,UAAU,QAAQ;GAChC,MAAM,MAAM,iBAAiB;IAC3B,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK;KAEnC,IAAI,YAAY,QAAQ,CAAC,CAAC,OAAO,IAAI,IAAI;KACzC,MAAM,QAAQ,SAAS,IAAI,EAAE,GAAG,CAAC;IACnC;GACF,CAAC;EACH;EACA,UAAU,IAAI,SAAS,MAAM,OAAO,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC;EAC1D,WAAW,IAAI,UAAU,MAAM,SAAS,SAAS,EAAE,GAAG,KAAK;EAC3D,eAAe,IAAI,cACjB,MAAM,aAAa,SAAS,EAAE,GAAG,MAAM,QAAQ,SAAS,IAAI,UAAU,IAAI,QAAQ,IAAI,SAAmC;EAC3H,YAAY,IAAI,WAAW,MAAM,UAAU,SAAS,EAAE,GAAG,MAAM;EAC/D,YAAY,IAAI,WAAW,MAAM,UAAU,SAAS,EAAE,GAAG,MAAM;EAC/D,YAAY,IAAI,WAAW,MAAM,UAAU,SAAS,EAAE,GAAG,MAAM;EAC/D,aAAa,OAAO,MAAM,OAAO,SAAS,EAAE,CAAC;EAC7C,aAAa,MAAM,UAAU;GAC3B,MAAM,IAAI;IACR,MAAM,KAAK;IACX,OAAO,KAAK;IACZ,MAAM,KAAK;IACX,MAAM,KAAK;IACX,IAAI,KAAK;IACT,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;IACvC,GAAI,KAAK,UAAU,OAAO,EAAE,QAAQ,KAAK,OAAO,IAAI,CAAC;IAGrD,GAAI,KAAK,cAAc,SAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;IACpE,GAAG,aAAa,IAAI;IACpB,GAAG,eAAe,IAAI;GACxB,CAAC;EACH;CACF;AACF;;;AAIA,SAAgB,cACd,OAC0E;CAC1E,OAAO;EACL,UAAU,OAAO,aAAa,OAAO,MAAM,IAAI,SAAS,EAAE,CAAC,CAAE;EAC7D,gBAAgB,CAAC,GAAG,MAAM,iBAAiB,CAAC;CAC9C;AACF"}

package/dist/core/scene/sceneRecording.js

@@ -1,5 +1,6 @@
 import { createHistory } from "../ops/createHistory.js";
 import { createAppliedLog } from "./appliedLog.js";
+import { createEditPasses } from "./editPass.js";
 import { createSceneHistory } from "./historyFacade.js";
 import { createOpTable } from "./opTable.js";
 import { createOuterOps } from "./outerOps.js";
@@ -9,6 +10,20 @@ import { createRecorder } from "./recorder.js";
 function createSceneRecording(env) {
 	const { notifier, mode, stale, lifted, selection, arrivals, config, poseWrites } = env;
 	const { notify } = notifier;
+	const passes = createEditPasses({
+		adapter: env.passAdapter,
+		untracked: mode.untracked
+	});
+	/** Run an op-driven edit with its arrivals settled and its passes run at
+	*  its end, in the same entry, when this call owns them. */
+	const runEdit = (ops, run) => arrivals.runEdit(ops, (all) => {
+		if (!passes.open()) return run(all);
+		try {
+			run([...all, passes.op()]);
+		} finally {
+			passes.abandon();
+		}
+	});
 	const ops = createOpTable({
 		driven: mode.open,
 		replayAlone: (step) => {
@@ -51,6 +66,7 @@ function createSceneRecording(env) {
 		makeOp: ops.op,
 		log,
 		arrivals,
+		passes,
 		selection: selection.get,
 		writePose: env.writePose,
 		labeled: poseWrites.labeled
@@ -72,7 +88,7 @@ function createSceneRecording(env) {
 		replay,
 		notify,
 		refuseUntracked,
-		runArrivalEdit: arrivals.runEdit,
+		runArrivalEdit: runEdit,
 		labeled: (label, fn) => poseWrites.labeled(label, "ops", fn),
 		activeJournal: outer.activeJournal
 	});
@@ -90,14 +106,15 @@ function createSceneRecording(env) {
 			},
 			applyBatch(batch, label, adapter) {
 				refuseUntracked("applyBatch");
-				return poseWrites.labeled(label, "ops", () => arrivals.runEdit(batch, (all) => outer.apply(engine, all, label, adapter)));
+				return poseWrites.labeled(label, "ops", () => runEdit(batch, (all) => outer.apply(engine, all, label, adapter)));
 			},
 			history,
 			...methods,
 			batch: recorder.batch,
 			untracked: recorder.untracked,
 			setActiveJournalAccessor: outer.setActiveJournalAccessor,
-			setHistoryAdapter: outer.setHistoryAdapter
+			setHistoryAdapter: outer.setHistoryAdapter,
+			addEditPass: passes.add
 		}
 	};
 }

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

@@ -1 +1 @@
-{"version":3,"file":"sceneRecording.js","names":[],"sources":["../../../src/core/scene/sceneRecording.ts"],"sourcesContent":["/**\n * How a scene's edits reach its undo stack: the op table, the log that takes\n * back an edit refused partway, the engine, and the recorder between them.\n */\nimport type { Journal } from '@weasel-js/history';\nimport { createHistory } from 'core/ops/createHistory';\nimport { createAppliedLog } from './appliedLog';\nimport type { ArrivalWindow } from './arrivalWindow';\nimport type { EditMode } from './editMode';\nimport { createSceneHistory, type SceneHistoryMethods } from './historyFacade';\nimport type { Notifier } from './notifier';\nimport type { PoseWriteLog } from './poseWrites';\nimport { createOpTable, type OpTable } from './opTable';\nimport { createOuterOps } from './outerOps';\nimport { createRecorder, type Recorder, type RecorderEnv } from './recorder';\nimport type { SceneSelection } from './sceneSelection';\nimport type { StaleReplay } from './staleReplay';\nimport type { NodeId, RegisteredOp, Scene } from './types';\n\nexport interface SceneRecordingEnv {\n  notifier: Notifier;\n  mode: EditMode;\n  stale: StaleReplay;\n  /** Run with the lock guard lifted. */\n  lifted<T>(fn: () => T): T;\n  selection: Pick<SceneSelection, 'get' | 'set' | 'replace'>;\n  arrivals: RecorderEnv['arrivals'] & Pick<ArrivalWindow<unknown>, 'runEdit'>;\n  writePose(id: string, pose: unknown): void;\n  poseWrites: Pick<PoseWriteLog<unknown>, 'labeled' | 'replaying'>;\n  config: {\n    getActiveJournal?: (() => Journal | null) | undefined;\n    coalesceWindowMs?: number | undefined;\n    historyLimit?: number | undefined;\n  };\n}\n\nexport interface SceneRecording {\n  ops: Pick<OpTable, 'register' | 'run'>;\n  recorder: Recorder;\n  clearHistory(): void;\n  methods: SceneHistoryMethods & Pick<\n    Scene<unknown, string, unknown>,\n    | 'registerOp' | 'recordOp' | 'applyBatch' | 'history' | 'batch' | 'untracked'\n    | 'setActiveJournalAccessor' | 'setHistoryAdapter'\n  >;\n}\n\nexport function createSceneRecording(env: SceneRecordingEnv): SceneRecording {\n  const { notifier, mode, stale, lifted, selection, arrivals, config, poseWrites } = env;\n  const { notify } = notifier;\n\n  const ops = createOpTable({\n    driven: mode.open,\n    replayAlone: (step) => { replay(step); notify(); },\n    skips: stale.skips,\n    // Only a replay is logged: a first apply is recorded by the entry it\n    // creates, and reverting it would leave that entry describing nothing.\n    applied: (kind, payload, reverted) => { if (!mode.records()) logApplied(kind, payload, reverted); },\n  });\n\n  const outer = createOuterOps({\n    own: (name, args) => (ops.handlers.has(name) ? ops.op(name, args) : null),\n    recorder: () => recorder,\n    // Deferred rather than muted, so a throwing op cannot strand subscribers\n    // after earlier ops in the batch already mutated state.\n    driving: (step) => notifier.deferred(() => mode.during('engine', () => atomically(step, () => true))),\n    getActiveJournal: config.getActiveJournal ?? null,\n  });\n\n  // The scene's undo/redo engine. Its recorded ops close over their payloads,\n  // so the engine's adapter argument is unused.\n  const engine = createHistory(undefined, {\n    selection: { get: selection.get, set: (ids) => selection.set(ids as readonly NodeId[]) },\n    ...(config.coalesceWindowMs !== undefined ? { coalesceWindowMs: config.coalesceWindowMs } : {}),\n    ...(config.historyLimit !== undefined ? { historyLimit: config.historyLimit } : {}),\n    rebuildOp: outer.rebuild,\n  });\n\n  const log = createAppliedLog({\n    registered: ops.handlers,\n    lifted,\n    getSelection: selection.get,\n    setSelection: selection.replace,\n    notify,\n  });\n  const { atomically, logApplied } = log;\n\n  const recorder = createRecorder({\n    notifier,\n    mode,\n    engine,\n    runOp: ops.run,\n    makeOp: ops.op,\n    log,\n    arrivals,\n    selection: selection.get,\n    writePose: env.writePose,\n    labeled: poseWrites.labeled,\n  });\n  const { record, engineDriven } = recorder;\n\n  /** Run an engine step that replays recorded ops — undo, redo, goto, a\n   *  journal stepping. The engine inverts whole ops when one throws; this\n   *  also reverts the scene writes of the op that threw partway. */\n  function replay(step: () => void): void {\n    poseWrites.replaying(() => atomically(() => lifted(() => stale.during(() => engineDriven(step))), () => true));\n  }\n\n  function refuseUntracked(verb: string): void {\n    if (mode.untracked()) throw new Error(`Scene: cannot ${verb} inside untracked() — it records`);\n  }\n\n  const { history, methods } = createSceneHistory({\n    engine,\n    applying: (step) => atomically(() => engineDriven(step), () => true),\n    causing: outer.causing,\n    replay,\n    notify,\n    refuseUntracked,\n    runArrivalEdit: arrivals.runEdit,\n    labeled: (label, fn) => poseWrites.labeled(label, 'ops', fn),\n    activeJournal: outer.activeJournal,\n  });\n\n  return {\n    ops,\n    recorder,\n    clearHistory: () => engine.clear(),\n    methods: {\n      registerOp(kind, handler) {\n        if (kind.startsWith('kit:')) {\n          throw new Error(`Scene: op kind \"${kind}\" is reserved (kit:* prefix)`);\n        }\n        ops.register(kind, handler as RegisteredOp<unknown>);\n      },\n      recordOp(op) {\n        record(op.kind, op.payload, op.kind);\n      },\n      applyBatch(batch, label, adapter) {\n        refuseUntracked('applyBatch');\n        return poseWrites.labeled(label, 'ops', () =>\n          arrivals.runEdit(batch, (all) => outer.apply(engine, all, label, adapter)));\n      },\n      history,\n      ...methods,\n      batch: recorder.batch,\n      untracked: recorder.untracked,\n      setActiveJournalAccessor: outer.setActiveJournalAccessor,\n      setHistoryAdapter: outer.setHistoryAdapter,\n    },\n  };\n}\n"],"mappings":";;;;;;;;AA+CA,SAAgB,qBAAqB,KAAwC;CAC3E,MAAM,EAAE,UAAU,MAAM,OAAO,QAAQ,WAAW,UAAU,QAAQ,eAAe;CACnF,MAAM,EAAE,WAAW;CAEnB,MAAM,MAAM,cAAc;EACxB,QAAQ,KAAK;EACb,cAAc,SAAS;GAAE,OAAO,IAAI;GAAG,OAAO;EAAG;EACjD,OAAO,MAAM;EAGb,UAAU,MAAM,SAAS,aAAa;GAAE,IAAI,CAAC,KAAK,QAAQ,GAAG,WAAW,MAAM,SAAS,QAAQ;EAAG;CACpG,CAAC;CAED,MAAM,QAAQ,eAAe;EAC3B,MAAM,MAAM,SAAU,IAAI,SAAS,IAAI,IAAI,IAAI,IAAI,GAAG,MAAM,IAAI,IAAI;EACpE,gBAAgB;EAGhB,UAAU,SAAS,SAAS,eAAe,KAAK,OAAO,gBAAgB,WAAW,YAAY,IAAI,CAAC,CAAC;EACpG,kBAAkB,OAAO,oBAAoB;CAC/C,CAAC;CAID,MAAM,SAAS,cAAc,QAAW;EACtC,WAAW;GAAE,KAAK,UAAU;GAAK,MAAM,QAAQ,UAAU,IAAI,GAAwB;EAAE;EACvF,GAAI,OAAO,qBAAqB,SAAY,EAAE,kBAAkB,OAAO,iBAAiB,IAAI,CAAC;EAC7F,GAAI,OAAO,iBAAiB,SAAY,EAAE,cAAc,OAAO,aAAa,IAAI,CAAC;EACjF,WAAW,MAAM;CACnB,CAAC;CAED,MAAM,MAAM,iBAAiB;EAC3B,YAAY,IAAI;EAChB;EACA,cAAc,UAAU;EACxB,cAAc,UAAU;EACxB;CACF,CAAC;CACD,MAAM,EAAE,YAAY,eAAe;CAEnC,MAAM,WAAW,eAAe;EAC9B;EACA;EACA;EACA,OAAO,IAAI;EACX,QAAQ,IAAI;EACZ;EACA;EACA,WAAW,UAAU;EACrB,WAAW,IAAI;EACf,SAAS,WAAW;CACtB,CAAC;CACD,MAAM,EAAE,QAAQ,iBAAiB;;;;CAKjC,SAAS,OAAO,MAAwB;EACtC,WAAW,gBAAgB,iBAAiB,aAAa,MAAM,aAAa,aAAa,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC;CAC/G;CAEA,SAAS,gBAAgB,MAAoB;EAC3C,IAAI,KAAK,UAAU,GAAG,MAAM,IAAI,MAAM,iBAAiB,KAAK,iCAAiC;CAC/F;CAEA,MAAM,EAAE,SAAS,YAAY,mBAAmB;EAC9C;EACA,WAAW,SAAS,iBAAiB,aAAa,IAAI,SAAS,IAAI;EACnE,SAAS,MAAM;EACf;EACA;EACA;EACA,gBAAgB,SAAS;EACzB,UAAU,OAAO,OAAO,WAAW,QAAQ,OAAO,OAAO,EAAE;EAC3D,eAAe,MAAM;CACvB,CAAC;CAED,OAAO;EACL;EACA;EACA,oBAAoB,OAAO,MAAM;EACjC,SAAS;GACP,WAAW,MAAM,SAAS;IACxB,IAAI,KAAK,WAAW,MAAM,GACxB,MAAM,IAAI,MAAM,mBAAmB,KAAK,6BAA6B;IAEvE,IAAI,SAAS,MAAM,OAAgC;GACrD;GACA,SAAS,IAAI;IACX,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI;GACrC;GACA,WAAW,OAAO,OAAO,SAAS;IAChC,gBAAgB,YAAY;IAC5B,OAAO,WAAW,QAAQ,OAAO,aAC/B,SAAS,QAAQ,QAAQ,QAAQ,MAAM,MAAM,QAAQ,KAAK,OAAO,OAAO,CAAC,CAAC;GAC9E;GACA;GACA,GAAG;GACH,OAAO,SAAS;GAChB,WAAW,SAAS;GACpB,0BAA0B,MAAM;GAChC,mBAAmB,MAAM;EAC3B;CACF;AACF"}
+{"version":3,"file":"sceneRecording.js","names":[],"sources":["../../../src/core/scene/sceneRecording.ts"],"sourcesContent":["/**\n * How a scene's edits reach its undo stack: the op table, the log that takes\n * back an edit refused partway, the engine, and the recorder between them.\n */\nimport type { Journal } from '@weasel-js/history';\nimport type { Op } from 'core/ops/types';\nimport { createHistory } from 'core/ops/createHistory';\nimport { createAppliedLog } from './appliedLog';\nimport type { ArrivalWindow } from './arrivalWindow';\nimport type { EditMode } from './editMode';\nimport { createEditPasses } from './editPass';\nimport { createSceneHistory, type SceneHistoryMethods } from './historyFacade';\nimport type { Notifier } from './notifier';\nimport type { PoseWriteLog } from './poseWrites';\nimport { createOpTable, type OpTable } from './opTable';\nimport { createOuterOps } from './outerOps';\nimport { createRecorder, type Recorder, type RecorderEnv } from './recorder';\nimport type { SceneSelection } from './sceneSelection';\nimport type { StaleReplay } from './staleReplay';\nimport type { NodeId, RegisteredOp, Scene } from './types';\n\nexport interface SceneRecordingEnv {\n  notifier: Notifier;\n  mode: EditMode;\n  stale: StaleReplay;\n  /** Run with the lock guard lifted. */\n  lifted<T>(fn: () => T): T;\n  selection: Pick<SceneSelection, 'get' | 'set' | 'replace'>;\n  arrivals: RecorderEnv['arrivals'] & Pick<ArrivalWindow<unknown>, 'runEdit'>;\n  /** The adapter an edit pass's ops apply through. */\n  passAdapter(): unknown;\n  writePose(id: string, pose: unknown): void;\n  poseWrites: Pick<PoseWriteLog<unknown>, 'labeled' | 'replaying'>;\n  config: {\n    getActiveJournal?: (() => Journal | null) | undefined;\n    coalesceWindowMs?: number | undefined;\n    historyLimit?: number | undefined;\n  };\n}\n\nexport interface SceneRecording {\n  ops: Pick<OpTable, 'register' | 'run'>;\n  recorder: Recorder;\n  clearHistory(): void;\n  methods: SceneHistoryMethods & Pick<\n    Scene<unknown, string, unknown>,\n    | 'registerOp' | 'recordOp' | 'applyBatch' | 'history' | 'batch' | 'untracked'\n    | 'setActiveJournalAccessor' | 'setHistoryAdapter' | 'addEditPass'\n  >;\n}\n\nexport function createSceneRecording(env: SceneRecordingEnv): SceneRecording {\n  const { notifier, mode, stale, lifted, selection, arrivals, config, poseWrites } = env;\n  const { notify } = notifier;\n  const passes = createEditPasses({ adapter: env.passAdapter, untracked: mode.untracked });\n\n  /** Run an op-driven edit with its arrivals settled and its passes run at\n   *  its end, in the same entry, when this call owns them. */\n  const runEdit = (ops: Op[], run: (ops: Op[]) => void): boolean => arrivals.runEdit(ops, (all) => {\n    if (!passes.open()) return run(all);\n    try {\n      run([...all, passes.op()]);\n    } finally {\n      passes.abandon();\n    }\n  });\n\n  const ops = createOpTable({\n    driven: mode.open,\n    replayAlone: (step) => { replay(step); notify(); },\n    skips: stale.skips,\n    // Only a replay is logged: a first apply is recorded by the entry it\n    // creates, and reverting it would leave that entry describing nothing.\n    applied: (kind, payload, reverted) => { if (!mode.records()) logApplied(kind, payload, reverted); },\n  });\n\n  const outer = createOuterOps({\n    own: (name, args) => (ops.handlers.has(name) ? ops.op(name, args) : null),\n    recorder: () => recorder,\n    // Deferred rather than muted, so a throwing op cannot strand subscribers\n    // after earlier ops in the batch already mutated state.\n    driving: (step) => notifier.deferred(() => mode.during('engine', () => atomically(step, () => true))),\n    getActiveJournal: config.getActiveJournal ?? null,\n  });\n\n  // The scene's undo/redo engine. Its recorded ops close over their payloads,\n  // so the engine's adapter argument is unused.\n  const engine = createHistory(undefined, {\n    selection: { get: selection.get, set: (ids) => selection.set(ids as readonly NodeId[]) },\n    ...(config.coalesceWindowMs !== undefined ? { coalesceWindowMs: config.coalesceWindowMs } : {}),\n    ...(config.historyLimit !== undefined ? { historyLimit: config.historyLimit } : {}),\n    rebuildOp: outer.rebuild,\n  });\n\n  const log = createAppliedLog({\n    registered: ops.handlers,\n    lifted,\n    getSelection: selection.get,\n    setSelection: selection.replace,\n    notify,\n  });\n  const { atomically, logApplied } = log;\n\n  const recorder = createRecorder({\n    notifier,\n    mode,\n    engine,\n    runOp: ops.run,\n    makeOp: ops.op,\n    log,\n    arrivals,\n    passes,\n    selection: selection.get,\n    writePose: env.writePose,\n    labeled: poseWrites.labeled,\n  });\n  const { record, engineDriven } = recorder;\n\n  /** Run an engine step that replays recorded ops — undo, redo, goto, a\n   *  journal stepping. The engine inverts whole ops when one throws; this\n   *  also reverts the scene writes of the op that threw partway. */\n  function replay(step: () => void): void {\n    poseWrites.replaying(() => atomically(() => lifted(() => stale.during(() => engineDriven(step))), () => true));\n  }\n\n  function refuseUntracked(verb: string): void {\n    if (mode.untracked()) throw new Error(`Scene: cannot ${verb} inside untracked() — it records`);\n  }\n\n  const { history, methods } = createSceneHistory({\n    engine,\n    applying: (step) => atomically(() => engineDriven(step), () => true),\n    causing: outer.causing,\n    replay,\n    notify,\n    refuseUntracked,\n    runArrivalEdit: runEdit,\n    labeled: (label, fn) => poseWrites.labeled(label, 'ops', fn),\n    activeJournal: outer.activeJournal,\n  });\n\n  return {\n    ops,\n    recorder,\n    clearHistory: () => engine.clear(),\n    methods: {\n      registerOp(kind, handler) {\n        if (kind.startsWith('kit:')) {\n          throw new Error(`Scene: op kind \"${kind}\" is reserved (kit:* prefix)`);\n        }\n        ops.register(kind, handler as RegisteredOp<unknown>);\n      },\n      recordOp(op) {\n        record(op.kind, op.payload, op.kind);\n      },\n      applyBatch(batch, label, adapter) {\n        refuseUntracked('applyBatch');\n        return poseWrites.labeled(label, 'ops', () =>\n          runEdit(batch, (all) => outer.apply(engine, all, label, adapter)));\n      },\n      history,\n      ...methods,\n      batch: recorder.batch,\n      untracked: recorder.untracked,\n      setActiveJournalAccessor: outer.setActiveJournalAccessor,\n      setHistoryAdapter: outer.setHistoryAdapter,\n      addEditPass: passes.add,\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/core/scene/sceneSelection.js

@@ -3,11 +3,13 @@ import { createEmitter } from "@weasel-js/registry";
 //#region src/core/scene/sceneSelection.ts
 function createSceneSelection(reachable) {
 	let ids = [];
+	let changes = 0;
 	const changed = createEmitter();
 	return {
 		get: () => ids,
 		set(next) {
 			ids = reachable(next);
+			changes++;
 			changed.emit();
 		},
 		narrow(gone) {
@@ -16,7 +18,8 @@ function createSceneSelection(reachable) {
 		replace(next) {
 			ids = next;
 		},
-		subscribe: changed.subscribe
+		subscribe: changed.subscribe,
+		changes: () => changes
 	};
 }
 /** The scene's selection in the shape `createHistory` wants, for a consumer

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}\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  const changed = createEmitter();\n\n  return {\n    get: () => ids,\n    set(next) {\n      ids = reachable(next);\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  };\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":";;;AAqBA,SAAgB,qBAEd,WACgB;CAChB,IAAI,MAAyB,CAAC;CAC9B,MAAM,UAAU,cAAc;CAE9B,OAAO;EACL,WAAW;EACX,IAAI,MAAM;GACR,MAAM,UAAU,IAAI;GACpB,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;CACrB;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 */\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"}

package/dist/core/scene/sceneState.js

@@ -1,4 +1,5 @@
 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";
@@ -12,12 +13,13 @@ import { createTreeReads } from "./treeReads.js";
 * A scene's document state — its nodes, roots, and layers — with the modules
 * that read and write it directly.
 */
-function createSceneState(registry, initialLayers, layoutDeclared) {
+function createSceneState(registry, initialLayers, layoutDeclared, initialDoc) {
 	const state = {
 		nodes: /* @__PURE__ */ new Map(),
 		roots: [],
 		layers: [],
-		layerIndex: /* @__PURE__ */ new Map()
+		layerIndex: /* @__PURE__ */ new Map(),
+		docValues: /* @__PURE__ */ new Map()
 	};
 	const order = createRenderOrder(state);
 	/** The registry-keyed function fields, each with its key maps. A function
@@ -29,6 +31,8 @@ function createSceneState(registry, initialLayers, layoutDeclared) {
 	const layers = createLayerStack(state, order.invalidate);
 	layers.reset(initialLayers);
 	const locks = createLockGuard(state);
+	const docValues = createDocStore(state.docValues);
+	docValues.reset(initialDoc);
 	const reads = {
 		...createTreeReads(state.nodes),
 		renderOrder: order.ids,
@@ -40,7 +44,7 @@ function createSceneState(registry, initialLayers, layoutDeclared) {
 			const node = state.nodes.get(id);
 			return node?.kind === "container" ? node.layout ?? null : null;
 		},
-		toJSON: () => serializeScene(state, fnFields)
+		toJSON: () => serializeScene(state, fnFields, docValues.toJSON())
 	};
 	return {
 		state,
@@ -51,8 +55,10 @@ function createSceneState(registry, initialLayers, layoutDeclared) {
 		store,
 		layers,
 		reads,
-		/** Empty the document and give it `records` as its layers. */
-		reset(records) {
+		docValues,
+		/** Empty the document and give it `records` as its layers and `values` as its document values. */
+		reset(records, values) {
+			docValues.reset(values);
 			store.dependents.clear();
 			store.childDerived.clear();
 			state.nodes.clear();

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

@@ -1 +1 @@
-{"version":3,"file":"sceneState.js","names":[],"sources":["../../../src/core/scene/sceneState.ts"],"sourcesContent":["/**\n * A scene's document state — its nodes, roots, and layers — with the modules\n * that read and write it directly.\n */\nimport { createLayerStack } from './layerStack';\nimport { createLockGuard } from './lockGuard';\nimport { createNodeFnFields } from './nodeFnFields';\nimport { createNodeStore } from './nodeStore';\nimport { createRenderOrder } from './renderOrder';\nimport { serializeScene } from './serialization';\nimport { createStaleReplay } from './staleReplay';\nimport { createTreeReads } from './treeReads';\nimport type { LayerRecord, Node, NodeId, Scene, SceneRegistry } from './types';\n\nexport function createSceneState<TData, TLayer extends string, TPose>(\n  registry: SceneRegistry<TPose, TData, TLayer>,\n  initialLayers: readonly LayerRecord<TLayer>[],\n  /** Called when a node is given a layout. */\n  layoutDeclared: () => void,\n) {\n  const state = {\n    nodes: new Map<NodeId, Node<TData, TLayer, TPose>>(),\n    roots: [] as NodeId[],\n    layers: [] as LayerRecord<TLayer>[],\n    layerIndex: new Map<TLayer, number>(),\n  };\n  const order = createRenderOrder(state);\n  /** The registry-keyed function fields, each with its key maps. A function\n   *  cannot travel through a serializable op payload, so an op carries its key. */\n  const fnFields = createNodeFnFields<TPose>(registry, (field) => {\n    if (field === 'layout') layoutDeclared();\n  });\n  const store = createNodeStore(state, order.invalidate, fnFields);\n  const layers = createLayerStack(state, order.invalidate);\n  layers.reset(initialLayers);\n  const locks = createLockGuard(state);\n\n  const reads: Pick<\n    Scene<TData, TLayer, TPose>,\n    | 'get' | 'incarnation' | 'childrenOf' | 'ancestorsOf' | 'renderOrder' | 'renderOrderNodes'\n    | 'nodesOnLayer' | 'isLocked' | 'isHidden' | 'layoutOf' | 'toJSON'\n  > = {\n    ...createTreeReads(state.nodes),\n    renderOrder: order.ids,\n    renderOrderNodes: order.nodes,\n    nodesOnLayer: order.nodesOnLayer,\n    isLocked: (id) => locks.isLocked(id),\n    isHidden: (id) => locks.isHidden(id),\n    layoutOf(id) {\n      const node = state.nodes.get(id);\n      return node?.kind === 'container' ? (node.layout ?? null) : null;\n    },\n    toJSON: () => serializeScene(state, fnFields),\n  };\n\n  return {\n    state,\n    order,\n    locks,\n    stale: createStaleReplay(state.nodes),\n    fnFields,\n    store,\n    layers,\n    reads,\n\n    /** Empty the document and give it `records` as its layers. */\n    reset(records: readonly LayerRecord<TLayer>[]): void {\n      store.dependents.clear();\n      store.childDerived.clear();\n      state.nodes.clear();\n      state.roots.length = 0;\n      layers.reset(records);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,SAAgB,iBACd,UACA,eAEA,gBACA;CACA,MAAM,QAAQ;EACZ,uBAAO,IAAI,IAAwC;EACnD,OAAO,CAAC;EACR,QAAQ,CAAC;EACT,4BAAY,IAAI,IAAoB;CACtC;CACA,MAAM,QAAQ,kBAAkB,KAAK;;;CAGrC,MAAM,WAAW,mBAA0B,WAAW,UAAU;EAC9D,IAAI,UAAU,UAAU,eAAe;CACzC,CAAC;CACD,MAAM,QAAQ,gBAAgB,OAAO,MAAM,YAAY,QAAQ;CAC/D,MAAM,SAAS,iBAAiB,OAAO,MAAM,UAAU;CACvD,OAAO,MAAM,aAAa;CAC1B,MAAM,QAAQ,gBAAgB,KAAK;CAEnC,MAAM,QAIF;EACF,GAAG,gBAAgB,MAAM,KAAK;EAC9B,aAAa,MAAM;EACnB,kBAAkB,MAAM;EACxB,cAAc,MAAM;EACpB,WAAW,OAAO,MAAM,SAAS,EAAE;EACnC,WAAW,OAAO,MAAM,SAAS,EAAE;EACnC,SAAS,IAAI;GACX,MAAM,OAAO,MAAM,MAAM,IAAI,EAAE;GAC/B,OAAO,MAAM,SAAS,cAAe,KAAK,UAAU,OAAQ;EAC9D;EACA,cAAc,eAAe,OAAO,QAAQ;CAC9C;CAEA,OAAO;EACL;EACA;EACA;EACA,OAAO,kBAAkB,MAAM,KAAK;EACpC;EACA;EACA;EACA;;EAGA,MAAM,SAA+C;GACnD,MAAM,WAAW,MAAM;GACvB,MAAM,aAAa,MAAM;GACzB,MAAM,MAAM,MAAM;GAClB,MAAM,MAAM,SAAS;GACrB,OAAO,MAAM,OAAO;EACtB;CACF;AACF"}
+{"version":3,"file":"sceneState.js","names":[],"sources":["../../../src/core/scene/sceneState.ts"],"sourcesContent":["/**\n * A scene's document state — its nodes, roots, and layers — with the modules\n * that read and write it directly.\n */\nimport { createDocStore, type SerializedDoc } from './docValues';\nimport { createLayerStack } from './layerStack';\nimport { createLockGuard } from './lockGuard';\nimport { createNodeFnFields } from './nodeFnFields';\nimport { createNodeStore } from './nodeStore';\nimport { createRenderOrder } from './renderOrder';\nimport { serializeScene } from './serialization';\nimport { createStaleReplay } from './staleReplay';\nimport { createTreeReads } from './treeReads';\nimport type { LayerRecord, Node, NodeId, Scene, SceneRegistry } from './types';\n\nexport function createSceneState<TData, TLayer extends string, TPose>(\n  registry: SceneRegistry<TPose, TData, TLayer>,\n  initialLayers: readonly LayerRecord<TLayer>[],\n  /** Called when a node is given a layout. */\n  layoutDeclared: () => void,\n  initialDoc?: SerializedDoc,\n) {\n  const state = {\n    nodes: new Map<NodeId, Node<TData, TLayer, TPose>>(),\n    roots: [] as NodeId[],\n    layers: [] as LayerRecord<TLayer>[],\n    layerIndex: new Map<TLayer, number>(),\n    docValues: new Map<string, unknown>(),\n  };\n  const order = createRenderOrder(state);\n  /** The registry-keyed function fields, each with its key maps. A function\n   *  cannot travel through a serializable op payload, so an op carries its key. */\n  const fnFields = createNodeFnFields<TPose>(registry, (field) => {\n    if (field === 'layout') layoutDeclared();\n  });\n  const store = createNodeStore(state, order.invalidate, fnFields);\n  const layers = createLayerStack(state, order.invalidate);\n  layers.reset(initialLayers);\n  const locks = createLockGuard(state);\n  const docValues = createDocStore(state.docValues);\n  docValues.reset(initialDoc);\n\n  const reads: Pick<\n    Scene<TData, TLayer, TPose>,\n    | 'get' | 'incarnation' | 'childrenOf' | 'ancestorsOf' | 'renderOrder' | 'renderOrderNodes'\n    | 'nodesOnLayer' | 'isLocked' | 'isHidden' | 'layoutOf' | 'toJSON'\n  > = {\n    ...createTreeReads(state.nodes),\n    renderOrder: order.ids,\n    renderOrderNodes: order.nodes,\n    nodesOnLayer: order.nodesOnLayer,\n    isLocked: (id) => locks.isLocked(id),\n    isHidden: (id) => locks.isHidden(id),\n    layoutOf(id) {\n      const node = state.nodes.get(id);\n      return node?.kind === 'container' ? (node.layout ?? null) : null;\n    },\n    toJSON: () => serializeScene(state, fnFields, docValues.toJSON()),\n  };\n\n  return {\n    state,\n    order,\n    locks,\n    stale: createStaleReplay(state.nodes),\n    fnFields,\n    store,\n    layers,\n    reads,\n    docValues,\n\n    /** Empty the document and give it `records` as its layers and `values` as its document values. */\n    reset(records: readonly LayerRecord<TLayer>[], values?: SerializedDoc): void {\n      docValues.reset(values);\n      store.dependents.clear();\n      store.childDerived.clear();\n      state.nodes.clear();\n      state.roots.length = 0;\n      layers.reset(records);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,iBACd,UACA,eAEA,gBACA,YACA;CACA,MAAM,QAAQ;EACZ,uBAAO,IAAI,IAAwC;EACnD,OAAO,CAAC;EACR,QAAQ,CAAC;EACT,4BAAY,IAAI,IAAoB;EACpC,2BAAW,IAAI,IAAqB;CACtC;CACA,MAAM,QAAQ,kBAAkB,KAAK;;;CAGrC,MAAM,WAAW,mBAA0B,WAAW,UAAU;EAC9D,IAAI,UAAU,UAAU,eAAe;CACzC,CAAC;CACD,MAAM,QAAQ,gBAAgB,OAAO,MAAM,YAAY,QAAQ;CAC/D,MAAM,SAAS,iBAAiB,OAAO,MAAM,UAAU;CACvD,OAAO,MAAM,aAAa;CAC1B,MAAM,QAAQ,gBAAgB,KAAK;CACnC,MAAM,YAAY,eAAe,MAAM,SAAS;CAChD,UAAU,MAAM,UAAU;CAE1B,MAAM,QAIF;EACF,GAAG,gBAAgB,MAAM,KAAK;EAC9B,aAAa,MAAM;EACnB,kBAAkB,MAAM;EACxB,cAAc,MAAM;EACpB,WAAW,OAAO,MAAM,SAAS,EAAE;EACnC,WAAW,OAAO,MAAM,SAAS,EAAE;EACnC,SAAS,IAAI;GACX,MAAM,OAAO,MAAM,MAAM,IAAI,EAAE;GAC/B,OAAO,MAAM,SAAS,cAAe,KAAK,UAAU,OAAQ;EAC9D;EACA,cAAc,eAAe,OAAO,UAAU,UAAU,OAAO,CAAC;CAClE;CAEA,OAAO;EACL;EACA;EACA;EACA,OAAO,kBAAkB,MAAM,KAAK;EACpC;EACA;EACA;EACA;EACA;;EAGA,MAAM,SAAyC,QAA8B;GAC3E,UAAU,MAAM,MAAM;GACtB,MAAM,WAAW,MAAM;GACvB,MAAM,aAAa,MAAM;GACzB,MAAM,MAAM,MAAM;GAClB,MAAM,MAAM,SAAS;GACrB,OAAO,MAAM,OAAO;EACtB;CACF;AACF"}

package/dist/core/scene/serialization.js

@@ -29,9 +29,10 @@ function layerFromSerialized(spec) {
 		kind: "system"
 	};
 }
-/** The snapshot of `state`: layers in order, nodes in tree preorder. Throws
+/** The snapshot of `state`: layers in order, nodes in tree preorder, and the
+*  document values when there are any. Throws
 *  when a node carries a function the registry has no key for. */
-function serializeScene(state, fnFields) {
+function serializeScene(state, fnFields, doc) {
 	const nodes = [];
 	for (const n of treePreorder(state.roots, state.nodes)) {
 		const id = n.id;
@@ -68,7 +69,8 @@ function serializeScene(state, fnFields) {
 			}
 			return layer;
 		}),
-		nodes
+		nodes,
+		...doc ? { doc } : {}
 	};
 }
 /** Map a `SerializedScene` to construction specs. Shared by `sceneFromJSON`

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

@@ -1 +1 @@
-{"version":3,"file":"serialization.js","names":[],"sources":["../../../src/core/scene/serialization.ts"],"sourcesContent":["/**\n * A scene to and from its JSON snapshot: the walk that writes one, and the\n * two readers that turn one back into layer records and node specs.\n */\nimport {\n  NODE_FN_FIELDS, fnKeysOf, type FnBearingNode, type NodeFnField,\n} from './nodeFnFields';\nimport { treePreorder } from './treeOrder';\nimport type {\n  AddNodeSpec, LayerRecord, Node, NodeId, SceneRegistry, SerializedLayer, SerializedNode, SerializedScene,\n} from './types';\n\n/** Whether `value` is a snapshot `specsFromSerialized` reads, as against a live scene. */\nexport function isSerializedScene<TData, TLayer extends string, TPose>(\n  value: unknown,\n): value is SerializedScene<TData, TLayer, TPose> {\n  return typeof value === 'object' && value != null\n    && (value as { version?: unknown }).version === 1\n    && Array.isArray((value as { nodes?: unknown }).nodes);\n}\n\n/** What a snapshot is written from. */\nexport interface SerializableState<TData, TLayer extends string, TPose> {\n  nodes: Map<NodeId, Node<TData, TLayer, TPose>>;\n  roots: NodeId[];\n  layers: LayerRecord<TLayer>[];\n}\n\n/** One layer record from its snapshot form. A snapshot with no `kind` predates\n *  user layers, so everything in it was a system layer. */\nexport function layerFromSerialized<TLayer extends string>(\n  spec: SerializedLayer<TLayer>,\n): LayerRecord<TLayer> {\n  const base = {\n    id: spec.id,\n    visible: spec.visible ?? true,\n    locked: spec.locked ?? false,\n    ...(spec.parallax ? { parallax: spec.parallax } : {}),\n    ...(spec.annotation ? { annotation: true } : {}),\n  };\n  return spec.kind === 'user'\n    ? { ...base, kind: 'user', name: spec.name ?? spec.id }\n    : { ...base, kind: 'system' };\n}\n\n/** The snapshot of `state`: layers in order, nodes in tree preorder. Throws\n *  when a node carries a function the registry has no key for. */\nexport function serializeScene<TData, TLayer extends string, TPose>(\n  state: SerializableState<TData, TLayer, TPose>,\n  fnFields: readonly NodeFnField[],\n): SerializedScene<TData, TLayer, TPose> {\n  const nodes: SerializedNode<TData, TLayer, TPose>[] = [];\n  for (const n of treePreorder(state.roots, state.nodes)) {\n    const id = n.id;\n    const out: SerializedNode<TData, TLayer, TPose> = {\n      id,\n      kind: n.kind,\n      layer: n.layer,\n      pose: n.pose,\n      data: n.data,\n    };\n    if (n.parent != null) out.parent = n.parent;\n    if (n.dependsOn === 'children') out.dependsOn = 'children';\n    else if (n.dependsOn && n.dependsOn.length > 0) out.dependsOn = n.dependsOn;\n    if (n.pickable === false) out.pickable = false;\n    if (n.hidden === true) out.hidden = true;\n    if (n.locked === true) out.locked = true;\n    if (n.kind === 'container' && n.units !== undefined) out.units = n.units;\n    Object.assign(\n      out,\n      fnKeysOf(fnFields, n as unknown as FnBearingNode, 'jsonKey', (field) => {\n        throw new Error(\n          `Scene.toJSON: node '${id}' has ${field.spec.field} but no matching registry key. ` +\n          `The function must be registered via createScene's registry option to round-trip.`\n        );\n      }),\n    );\n    nodes.push(out);\n  }\n  const systemLayers = state.layers.map((l) => {\n    const layer: SerializedLayer<TLayer> = { id: l.id };\n    if (l.visible === false) layer.visible = false;\n    if (l.locked === true) layer.locked = true;\n    if (l.parallax) layer.parallax = l.parallax;\n    if (l.annotation) layer.annotation = true;\n    if (l.kind === 'user') {\n      layer.kind = 'user';\n      layer.name = l.name;\n    }\n    return layer;\n  });\n  return { version: 1, systemLayers, nodes };\n}\n\n/** Map a `SerializedScene` to construction specs. Shared by `sceneFromJSON`\n *  (new instance) and `Scene.loadState` (in-place). Validates version and\n *  resolves every `NODE_FN_FIELDS` key → function via the registry;\n *  throws on an unsupported version or an unknown registry key. */\nexport function specsFromSerialized<TData, TLayer extends string, TPose>(\n  json: SerializedScene<TData, TLayer, TPose>,\n  registry: SceneRegistry<TPose, TData, TLayer>,\n): AddNodeSpec<TData, TLayer, TPose>[] {\n  if (json.version !== 1) {\n    throw new Error(`Scene: unsupported version ${json.version}; only v1 supported`);\n  }\n  return json.nodes.map((n) => {\n    const spec: AddNodeSpec<TData, TLayer, TPose> = {\n      id: n.id as NodeId,\n      kind: n.kind,\n      layer: n.layer,\n      pose: n.pose,\n      data: n.data,\n    };\n    if (n.parent !== undefined) spec.parent = n.parent as NodeId;\n    if (n.pickable !== undefined) spec.pickable = n.pickable;\n    if (n.hidden === true) spec.hidden = true;\n    if (n.locked === true) spec.locked = true;\n    if (n.units !== undefined) spec.units = n.units;\n    if (n.dependsOn !== undefined) {\n      spec.dependsOn = n.dependsOn === 'children'\n        ? 'children'\n        : (n.dependsOn as readonly NodeId[]);\n    }\n    const serialized = n as unknown as Record<string, string | undefined>;\n    for (const field of NODE_FN_FIELDS) {\n      const key = serialized[field.jsonKey];\n      if (key === undefined) continue;\n      const fn = (registry[field.field] as Record<string, unknown> | undefined)?.[key];\n      if (!fn) {\n        throw new Error(\n          `Scene: unknown ${field.field} key '${key}'. ` +\n          `Register a function with this key in the registry option.`,\n        );\n      }\n      (spec as unknown as Record<string, unknown>)[field.field] = fn;\n    }\n    return spec;\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"serialization.js","names":[],"sources":["../../../src/core/scene/serialization.ts"],"sourcesContent":["/**\n * A scene to and from its JSON snapshot: the walk that writes one, and the\n * two readers that turn one back into layer records and node specs.\n */\nimport {\n  NODE_FN_FIELDS, fnKeysOf, type FnBearingNode, type NodeFnField,\n} from './nodeFnFields';\nimport type { SerializedDoc } from './docValues';\nimport { treePreorder } from './treeOrder';\nimport type {\n  AddNodeSpec, LayerRecord, Node, NodeId, SceneRegistry, SerializedLayer, SerializedNode, SerializedScene,\n} from './types';\n\n/** Whether `value` is a snapshot `specsFromSerialized` reads, as against a live scene. */\nexport function isSerializedScene<TData, TLayer extends string, TPose>(\n  value: unknown,\n): value is SerializedScene<TData, TLayer, TPose> {\n  return typeof value === 'object' && value != null\n    && (value as { version?: unknown }).version === 1\n    && Array.isArray((value as { nodes?: unknown }).nodes);\n}\n\n/** What a snapshot is written from. */\nexport interface SerializableState<TData, TLayer extends string, TPose> {\n  nodes: Map<NodeId, Node<TData, TLayer, TPose>>;\n  roots: NodeId[];\n  layers: LayerRecord<TLayer>[];\n}\n\n/** One layer record from its snapshot form. A snapshot with no `kind` predates\n *  user layers, so everything in it was a system layer. */\nexport function layerFromSerialized<TLayer extends string>(\n  spec: SerializedLayer<TLayer>,\n): LayerRecord<TLayer> {\n  const base = {\n    id: spec.id,\n    visible: spec.visible ?? true,\n    locked: spec.locked ?? false,\n    ...(spec.parallax ? { parallax: spec.parallax } : {}),\n    ...(spec.annotation ? { annotation: true } : {}),\n  };\n  return spec.kind === 'user'\n    ? { ...base, kind: 'user', name: spec.name ?? spec.id }\n    : { ...base, kind: 'system' };\n}\n\n/** The snapshot of `state`: layers in order, nodes in tree preorder, and the\n *  document values when there are any. Throws\n *  when a node carries a function the registry has no key for. */\nexport function serializeScene<TData, TLayer extends string, TPose>(\n  state: SerializableState<TData, TLayer, TPose>,\n  fnFields: readonly NodeFnField[],\n  doc?: SerializedDoc,\n): SerializedScene<TData, TLayer, TPose> {\n  const nodes: SerializedNode<TData, TLayer, TPose>[] = [];\n  for (const n of treePreorder(state.roots, state.nodes)) {\n    const id = n.id;\n    const out: SerializedNode<TData, TLayer, TPose> = {\n      id,\n      kind: n.kind,\n      layer: n.layer,\n      pose: n.pose,\n      data: n.data,\n    };\n    if (n.parent != null) out.parent = n.parent;\n    if (n.dependsOn === 'children') out.dependsOn = 'children';\n    else if (n.dependsOn && n.dependsOn.length > 0) out.dependsOn = n.dependsOn;\n    if (n.pickable === false) out.pickable = false;\n    if (n.hidden === true) out.hidden = true;\n    if (n.locked === true) out.locked = true;\n    if (n.kind === 'container' && n.units !== undefined) out.units = n.units;\n    Object.assign(\n      out,\n      fnKeysOf(fnFields, n as unknown as FnBearingNode, 'jsonKey', (field) => {\n        throw new Error(\n          `Scene.toJSON: node '${id}' has ${field.spec.field} but no matching registry key. ` +\n          `The function must be registered via createScene's registry option to round-trip.`\n        );\n      }),\n    );\n    nodes.push(out);\n  }\n  const systemLayers = state.layers.map((l) => {\n    const layer: SerializedLayer<TLayer> = { id: l.id };\n    if (l.visible === false) layer.visible = false;\n    if (l.locked === true) layer.locked = true;\n    if (l.parallax) layer.parallax = l.parallax;\n    if (l.annotation) layer.annotation = true;\n    if (l.kind === 'user') {\n      layer.kind = 'user';\n      layer.name = l.name;\n    }\n    return layer;\n  });\n  return { version: 1, systemLayers, nodes, ...(doc ? { doc } : {}) };\n}\n\n/** Map a `SerializedScene` to construction specs. Shared by `sceneFromJSON`\n *  (new instance) and `Scene.loadState` (in-place). Validates version and\n *  resolves every `NODE_FN_FIELDS` key → function via the registry;\n *  throws on an unsupported version or an unknown registry key. */\nexport function specsFromSerialized<TData, TLayer extends string, TPose>(\n  json: SerializedScene<TData, TLayer, TPose>,\n  registry: SceneRegistry<TPose, TData, TLayer>,\n): AddNodeSpec<TData, TLayer, TPose>[] {\n  if (json.version !== 1) {\n    throw new Error(`Scene: unsupported version ${json.version}; only v1 supported`);\n  }\n  return json.nodes.map((n) => {\n    const spec: AddNodeSpec<TData, TLayer, TPose> = {\n      id: n.id as NodeId,\n      kind: n.kind,\n      layer: n.layer,\n      pose: n.pose,\n      data: n.data,\n    };\n    if (n.parent !== undefined) spec.parent = n.parent as NodeId;\n    if (n.pickable !== undefined) spec.pickable = n.pickable;\n    if (n.hidden === true) spec.hidden = true;\n    if (n.locked === true) spec.locked = true;\n    if (n.units !== undefined) spec.units = n.units;\n    if (n.dependsOn !== undefined) {\n      spec.dependsOn = n.dependsOn === 'children'\n        ? 'children'\n        : (n.dependsOn as readonly NodeId[]);\n    }\n    const serialized = n as unknown as Record<string, string | undefined>;\n    for (const field of NODE_FN_FIELDS) {\n      const key = serialized[field.jsonKey];\n      if (key === undefined) continue;\n      const fn = (registry[field.field] as Record<string, unknown> | undefined)?.[key];\n      if (!fn) {\n        throw new Error(\n          `Scene: unknown ${field.field} key '${key}'. ` +\n          `Register a function with this key in the registry option.`,\n        );\n      }\n      (spec as unknown as Record<string, unknown>)[field.field] = fn;\n    }\n    return spec;\n  });\n}\n"],"mappings":"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"}

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 } from './poseOverrideTypes';\nimport type { SerializedLayer, SerializedNode, SerializedScene } from './serializedTypes';\nimport type { UseSceneOptions } from './useSceneOptions';\n\nimport type { RectPose } from '../geometry/rectPose';\nexport type { RectPose };\nexport type { AddLayerSpec, LayerRecord, SystemLayerRecord, SystemLayerSpec, UserLayerRecord };\nexport type { UseSceneOptions };\nexport type { PoseRemoval, PoseWrite, PoseWriteOrigin, RemovedNode, ScenePoseReports };\nexport type { LayoutFrame, LayoutMove, PoseHold, PoseOverride, PoseOverrides, SerializedLayer, SerializedNode, SerializedScene };\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. Containers and leaves 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 };\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\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}\n\n/** A node with no children — a shape, a label, an image. */\nexport interface LeafNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'leaf';\n}\n\n/** A node with an ordered list of children. This is the real group: what\n *  Cmd+G creates, what SVG `<g>` round-trips to. A container has its own pose,\n *  which its children's poses are relative to, and may optionally clip them. */\nexport interface ContainerNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'container';\n  children: NodeId[];\n  /** Optional clip-path source. Re-evaluated each render. Returning `null`\n   *  means \"no clip for this container right now\"; an empty / zero-area path\n   *  means \"clip everything out\" (children render nowhere). */\n  clipFromPose?: ClipFromPoseFn<TPose>;\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  /** How this container arranges its children. Whenever the container's\n   *  child set or order changes, or its bounds change size, the scene hands\n   *  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 unit system this container's contents are written in, and what one\n   *  of its base units is worth in the enclosing scope's. It covers the\n   *  children, not the container; `sceneUnitScopes` reads the chain. */\n  units?: UnitScope;\n}\n\n/** A node in the scene tree: either a leaf or a container. Re-exported\n *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */\nexport type Node<TData, TLayer extends string, TPose = RectPose> =\n  | LeafNode<TData, TLayer, TPose>\n  | ContainerNode<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: 'leaf' | 'container';\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  /** Only meaningful when `kind === 'container'`. Attach a clip-path function\n   *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\n  /** Mirrors `ContainerNode.copiesFromPose`; ignored for leaves. */\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 `ContainerNode.layout`; ignored for leaves. */\n  layout?: LayoutStrategy<TPose>;\n  /** Mirrors `ContainerNode.units`; ignored for leaves. */\n  units?: UnitScope;\n}\n\n/** A custom scene mutation registered with `Scene.registerOp`: how to apply\n *  it and how to undo it. The pair is what makes it participate in history. */\nexport interface RegisteredOp<P> {\n  apply: (payload: P) => void;\n  revert: (payload: P) => void;\n  /** Opts this kind into coalescing under `UseSceneOptions.coalesceWindowMs`:\n   *  two entries of this kind that return the same key inside the window\n   *  merge, and undoing the merged entry calls `revert` with the first\n   *  payload only. Declare it only when `revert` restores an absolute state\n   *  (a stored \"from\" value), never for a relative payload such as a delta.\n   *  Omitted, or returning `undefined`, the op is always its own entry. */\n  coalesceKey?: (payload: P) => string | undefined;\n}\n\n/** Per-scene registry mapping string keys to live function references.\n *  Passed to `createScene({ ..., registry })` and `sceneFromJSON(json, { registry })`.\n *  Each function-field type has its own keyed map. */\nexport interface SceneRegistry<TPose, TData = unknown, TLayer extends string = string> {\n  /** Maps registry keys to `clipFromPose` factory functions for container nodes. */\n  clipFromPose?: Readonly<Record<string, ClipFromPoseFn<TPose>>>;\n  /** Maps registry keys to `copiesFromPose` functions for container nodes. */\n  copiesFromPose?: Readonly<Record<string, CopiesFromPoseFn<TPose, TData, TLayer>>>;\n  /** Maps registry keys to `derivePath` functions for nodes with `dependsOn`. */\n  derivePath?: Readonly<Record<string, DerivePathFn<TPose, TData, TLayer>>>;\n  /** Maps registry keys to `derivePose` functions for nodes with `dependsOn`. */\n  derivePose?: Readonly<Record<string, DerivePoseFn<TPose, TData, TLayer>>>;\n  /** Maps registry keys to container layout strategies. */\n  layout?: Readonly<Record<string, LayoutStrategy<TPose>>>;\n  // A new function field is a row in `NODE_FN_FIELDS` (core/scene/nodeFnFields.ts)\n  // plus its entry here; the field name is the registry key by construction.\n}\n\n/**\n * Decides what one edit's changes to containers do to their children.\n * `arrivals` maps each container to the ids that joined it — by an `add`\n * under it or a `move` into it, whatever op or call made them — in the order\n * they arrived. `changed` names every container whose child set or order\n * changed, or whose pose changed size, arrivals included. Both are read once\n * the edit's other mutations have landed.\n *\n * Return the poses to write, in each node's stored frame; they become part of\n * the same edit, and so of the same undo step. An empty map writes nothing.\n * Return `null` to refuse: the whole edit is reverted (see\n * `SceneArrivalRefused`).\n *\n * Runs only for live edits. Undo, redo and a restored history replay the\n * arrangement that was decided the first time. With none installed, a scene\n * holding declared layouts (`ContainerNode.layout`) runs its own.\n */\nexport type SceneArrivalHandler<TPose> = (\n  arrivals: ReadonlyMap<NodeId, readonly NodeId[]>,\n  changed: ReadonlySet<NodeId>,\n  /** The nodes that left each container in the edit, by the container they\n   *  left — removed, or moved out. */\n  departures: ReadonlyMap<NodeId, readonly NodeId[]>,\n) => ReadonlyMap<NodeId, TPose> | null;\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>> {\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\n   *  entries over the kit's. */\n  readonly registry: SceneRegistry<TPose, TData, TLayer>;\n  /** See {@link UseSceneOptions.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 leaf, 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   *  - `parent` exists but is a **leaf**, not a container;\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 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>;\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): T;\n  /** The layout container `id` declares, or `null` for a leaf or a\n   *  container that declares none. */\n  layoutOf(id: NodeId): LayoutStrategy<TPose> | null;\n  /** Declare the unit scope of container `id`, or clear it with `null`. */\n  setUnits(id: NodeId, units: UnitScope | null): void;\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   *  `ContainerNode.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. */\n  loadState(json: SerializedScene<TData, TLayer, TPose>): void;\n\n  // Subscription (used by useScene; also for non-React observers)\n  subscribe(listener: () => void): () => void;\n  /** Monotonically increasing version. Snapshot for `useSyncExternalStore`. */\n  getVersion(): number;\n}\n"],"mappings":";;AAiDA,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 } from './poseOverrideTypes';\nimport type { SceneChanges } from './sceneChanges';\nimport type { SerializedLayer, SerializedNode, SerializedScene } from './serializedTypes';\nimport type { UseSceneOptions } from './useSceneOptions';\nimport type { SceneDocValues } from './docValues';\nimport type { SceneEditPasses } from './editPass';\nimport type { RectPose } from '../geometry/rectPose';\nexport type { RectPose, UseSceneOptions };\nexport type { AddLayerSpec, LayerRecord, SystemLayerRecord, SystemLayerSpec, UserLayerRecord };\nexport type { PoseRemoval, PoseWrite, PoseWriteOrigin, RemovedNode, ScenePoseReports };\nexport type { LayoutFrame, LayoutMove, PoseHold, PoseOverride, PoseOverrides, SerializedLayer, SerializedNode, SerializedScene };\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. Containers and leaves 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 };\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\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}\n\n/** A node with no children — a shape, a label, an image. */\nexport interface LeafNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'leaf';\n}\n\n/** A node with an ordered list of children. This is the real group: what\n *  Cmd+G creates, what SVG `<g>` round-trips to. A container has its own pose,\n *  which its children's poses are relative to, and may optionally clip them. */\nexport interface ContainerNode<TData, TLayer extends string, TPose = RectPose>\n  extends NodeBase<TData, TLayer, TPose> {\n  kind: 'container';\n  children: NodeId[];\n  /** Optional clip-path source. Re-evaluated each render. Returning `null`\n   *  means \"no clip for this container right now\"; an empty / zero-area path\n   *  means \"clip everything out\" (children render nowhere). */\n  clipFromPose?: ClipFromPoseFn<TPose>;\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  /** How this container arranges its children. Whenever the container'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 container; `sceneUnitScopes` reads the chain. */\n  units?: UnitScope;\n}\n\n/** A node in the scene tree: either a leaf or a container. Re-exported\n *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */\nexport type Node<TData, TLayer extends string, TPose = RectPose> =\n  | LeafNode<TData, TLayer, TPose>\n  | ContainerNode<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: 'leaf' | 'container';\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  /** Only meaningful when `kind === 'container'`. Attach a clip-path function\n   *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\n  /** Mirrors `ContainerNode.copiesFromPose`; ignored for leaves. */\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 `ContainerNode.layout`; ignored for leaves. */\n  layout?: LayoutStrategy<TPose>;\n  /** Mirrors `ContainerNode.units`; ignored for leaves. */\n  units?: UnitScope;\n}\n\n/** A custom scene mutation registered with `Scene.registerOp`: how to apply\n *  it and how to undo it. The pair is what makes it participate in history. */\nexport interface RegisteredOp<P> {\n  apply: (payload: P) => void;\n  revert: (payload: P) => void;\n  /** Opts this kind into coalescing under `UseSceneOptions.coalesceWindowMs`:\n   *  two entries of this kind that return the same key inside the window\n   *  merge, and undoing the merged entry calls `revert` with the first\n   *  payload only. Declare it only when `revert` restores an absolute state\n   *  (a stored \"from\" value), never for a relative payload such as a delta.\n   *  Omitted, or returning `undefined`, the op is always its own entry. */\n  coalesceKey?: (payload: P) => string | undefined;\n}\n\n/** Per-scene registry mapping string keys to live function references.\n *  Passed to `createScene({ ..., registry })` and `sceneFromJSON(json, { registry })`.\n *  Each function-field type has its own keyed map. */\nexport interface SceneRegistry<TPose, TData = unknown, TLayer extends string = string> {\n  /** Maps registry keys to `clipFromPose` factory functions for container nodes. */\n  clipFromPose?: Readonly<Record<string, ClipFromPoseFn<TPose>>>;\n  /** Maps registry keys to `copiesFromPose` functions for container nodes. */\n  copiesFromPose?: Readonly<Record<string, CopiesFromPoseFn<TPose, TData, TLayer>>>;\n  /** Maps registry keys to `derivePath` functions for nodes with `dependsOn`. */\n  derivePath?: Readonly<Record<string, DerivePathFn<TPose, TData, TLayer>>>;\n  /** Maps registry keys to `derivePose` functions for nodes with `dependsOn`. */\n  derivePose?: Readonly<Record<string, DerivePoseFn<TPose, TData, TLayer>>>;\n  /** Maps registry keys to container layout strategies. */\n  layout?: Readonly<Record<string, LayoutStrategy<TPose>>>;\n  // A new function field is a row in `NODE_FN_FIELDS` (core/scene/nodeFnFields.ts)\n  // plus its entry here; the field name is the registry key by construction.\n}\n\n/**\n * Decides what one edit's changes to containers do to their children.\n * `arrivals` maps each container to the ids that joined it — by an `add`\n * under it or a `move` into it, whatever op or call made them — in the order\n * they arrived. `changed` names every container whose child set or order\n * changed, whose pose changed size, or one of whose children was posed,\n * arrivals included. Both are read once the edit's other mutations have landed.\n *\n * Return the poses to write, in each node's stored frame; they become part of\n * the same edit, and so of the same undo step. An empty map writes nothing.\n * Return `null` to refuse: the whole edit is reverted (see\n * `SceneArrivalRefused`).\n *\n * Runs only for live edits. Undo, redo and a restored history replay the\n * arrangement that was decided the first time. With none installed, a scene\n * holding declared layouts (`ContainerNode.layout`) runs its own.\n */\nexport type SceneArrivalHandler<TPose> = (\n  arrivals: ReadonlyMap<NodeId, readonly NodeId[]>,\n  changed: ReadonlySet<NodeId>,\n  /** The nodes that left each container in the edit, by the container they\n   *  left — removed, or moved out. */\n  departures: ReadonlyMap<NodeId, readonly NodeId[]>,\n) => ReadonlyMap<NodeId, TPose> | null;\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 {\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\n   *  entries over the kit's. */\n  readonly registry: SceneRegistry<TPose, TData, TLayer>;\n  /** See {@link UseSceneOptions.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 leaf, 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   *  - `parent` exists but is a **leaf**, not a container;\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 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>;\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 container `id` declares, or `null` for a leaf or a\n   *  container that declares none. */\n  layoutOf(id: NodeId): LayoutStrategy<TPose> | null;\n  /** Declare the unit scope of container `id`, or clear it with `null`. */\n  setUnits(id: NodeId, units: UnitScope | null): void;\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   *  `ContainerNode.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. */\n  loadState(json: SerializedScene<TData, TLayer, TPose>): void;\n\n}\n"],"mappings":";;AAkDA,IAAa,YAAY,MAAsB"}

package/dist/core/scene/unitScopes.js

@@ -1,3 +1,4 @@
+import { deepEqual } from "@weasel-js/registry";
 import { scopesOf } from "@weasel-js/quantity";
 
 //#region src/core/scene/unitScopes.ts
@@ -14,7 +15,24 @@ function sceneUnitScopes(scene, id, root, opts = {}) {
 		...opts.inclusive ? { inclusive: true } : {}
 	});
 }
+/**
+* The unit scopes every node of `ids` sits in, outermost first: the run of
+* their chains that agree, where two containers declaring equal scopes
+* agree. What a reader showing or snapping several nodes as one reads them
+* in; the root alone for no nodes.
+*/
+function sceneSharedUnitScopes(scene, ids, root) {
+	if (ids.length === 0) return [root];
+	let shared = sceneUnitScopes(scene, ids[0], root);
+	for (const id of ids.slice(1)) {
+		const chain = sceneUnitScopes(scene, id, root);
+		let n = 0;
+		while (n < shared.length && n < chain.length && deepEqual(shared[n], chain[n])) n++;
+		shared = shared.slice(0, n);
+	}
+	return shared;
+}
 
 //#endregion
-export { sceneUnitScopes };
+export { 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 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"],"mappings":";;;;;;;;;AAcA,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"}
+{"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"}

package/dist/core/selection/usePublishSceneSelection.js

@@ -2,28 +2,22 @@ import { useMemo } from "react";
 import { usePublishSelection } from "@weasel-js/routing/react";
 
 //#region src/core/selection/usePublishSceneSelection.ts
-function defaultKindLabel(node) {
-	if (node.kind === "container") return "group";
-	const pose = node.pose;
-	if (pose && typeof pose === "object" && "kind" in pose && typeof pose.kind === "string") return "path";
-}
 /** The label published beside each selected id, parallel to `ids`; `undefined` when
-*  nothing is selected. `describeKind` replaces the default for every node. */
-function selectionKindLabels(scene, ids, describeKind) {
+*  nothing is selected. Without `describe`, every entry is unlabeled. */
+function selectionKindLabels(scene, ids, describe) {
 	if (ids.length === 0) return void 0;
 	return ids.map((id) => {
 		const node = scene.get(id);
-		if (!node) return void 0;
-		return describeKind ? describeKind(node) : defaultKindLabel(node);
+		return node && describe ? describe(node) : void 0;
 	});
 }
 /** Publishes a scene's selection, with a kind label per id, into any surrounding
 *  `<SelectionContextProvider>`. A no-op without one. */
-function usePublishSceneSelection(scene, ids, describeKind) {
-	const kinds = useMemo(() => selectionKindLabels(scene, ids, describeKind), [
+function usePublishSceneSelection(scene, ids, describe) {
+	const kinds = useMemo(() => selectionKindLabels(scene, ids, describe), [
 		scene,
 		ids,
-		describeKind
+		describe
 	]);
 	usePublishSelection(ids, kinds);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"usePublishSceneSelection.js","names":[],"sources":["../../../src/core/selection/usePublishSceneSelection.ts"],"sourcesContent":["import { usePublishSelection } from '@weasel-js/routing/react';\nimport type { Node, NodeId, Scene } from 'core/scene/types';\nimport { useMemo } from 'react';\n\ntype KindLabel = string | undefined;\n\n// Not the routing kind: this reads the node and its pose where `NodeRouting.classify` reads\n// `data`, and the two disagree on most nodes (`SceneCanvas.selectionKinds.test.tsx`).\nfunction defaultKindLabel(node: Node<unknown, string, unknown>): KindLabel {\n  if (node.kind === 'container') return 'group';\n  const pose = node.pose as { kind?: unknown } | null;\n  if (pose && typeof pose === 'object' && 'kind' in pose && typeof pose.kind === 'string') return 'path';\n  return undefined;\n}\n\n/** The label published beside each selected id, parallel to `ids`; `undefined` when\n *  nothing is selected. `describeKind` replaces the default for every node. */\nexport function selectionKindLabels<TData, TLayer extends string, TPose>(\n  scene: Pick<Scene<TData, TLayer, TPose>, 'get'>,\n  ids: readonly NodeId[],\n  describeKind?: (node: Node<TData, TLayer, TPose>) => KindLabel,\n): readonly KindLabel[] | undefined {\n  if (ids.length === 0) return undefined;\n  return ids.map((id) => {\n    const node = scene.get(id);\n    if (!node) return undefined;\n    return describeKind ? describeKind(node) : defaultKindLabel(node as Node<unknown, string, unknown>);\n  });\n}\n\n/** Publishes a scene's selection, with a kind label per id, into any surrounding\n *  `<SelectionContextProvider>`. A no-op without one. */\nexport function usePublishSceneSelection<TData, TLayer extends string, TPose>(\n  scene: Pick<Scene<TData, TLayer, TPose>, 'get'>,\n  ids: readonly NodeId[],\n  describeKind?: (node: Node<TData, TLayer, TPose>) => KindLabel,\n): void {\n  const kinds = useMemo(() => selectionKindLabels(scene, ids, describeKind), [scene, ids, describeKind]);\n  usePublishSelection(ids, kinds);\n}\n"],"mappings":";;;;AAQA,SAAS,iBAAiB,MAAiD;CACzE,IAAI,KAAK,SAAS,aAAa,OAAO;CACtC,MAAM,OAAO,KAAK;CAClB,IAAI,QAAQ,OAAO,SAAS,YAAY,UAAU,QAAQ,OAAO,KAAK,SAAS,UAAU,OAAO;AAElG;;;AAIA,SAAgB,oBACd,OACA,KACA,cACkC;CAClC,IAAI,IAAI,WAAW,GAAG,OAAO;CAC7B,OAAO,IAAI,KAAK,OAAO;EACrB,MAAM,OAAO,MAAM,IAAI,EAAE;EACzB,IAAI,CAAC,MAAM,OAAO;EAClB,OAAO,eAAe,aAAa,IAAI,IAAI,iBAAiB,IAAsC;CACpG,CAAC;AACH;;;AAIA,SAAgB,yBACd,OACA,KACA,cACM;CACN,MAAM,QAAQ,cAAc,oBAAoB,OAAO,KAAK,YAAY,GAAG;EAAC;EAAO;EAAK;CAAY,CAAC;CACrG,oBAAoB,KAAK,KAAK;AAChC"}
+{"version":3,"file":"usePublishSceneSelection.js","names":[],"sources":["../../../src/core/selection/usePublishSceneSelection.ts"],"sourcesContent":["import { usePublishSelection } from '@weasel-js/routing/react';\nimport type { Node, NodeId, Scene } from 'core/scene/types';\nimport { useMemo } from 'react';\n\ntype KindLabel = string | undefined;\n\n/** The label published beside each selected id, parallel to `ids`; `undefined` when\n *  nothing is selected. Without `describe`, every entry is unlabeled. */\nexport function selectionKindLabels<TData, TLayer extends string, TPose>(\n  scene: Pick<Scene<TData, TLayer, TPose>, 'get'>,\n  ids: readonly NodeId[],\n  describe?: (node: Node<TData, TLayer, TPose>) => KindLabel,\n): readonly KindLabel[] | undefined {\n  if (ids.length === 0) return undefined;\n  return ids.map((id) => {\n    const node = scene.get(id);\n    return node && describe ? describe(node) : undefined;\n  });\n}\n\n/** Publishes a scene's selection, with a kind label per id, into any surrounding\n *  `<SelectionContextProvider>`. A no-op without one. */\nexport function usePublishSceneSelection<TData, TLayer extends string, TPose>(\n  scene: Pick<Scene<TData, TLayer, TPose>, 'get'>,\n  ids: readonly NodeId[],\n  describe?: (node: Node<TData, TLayer, TPose>) => KindLabel,\n): void {\n  const kinds = useMemo(() => selectionKindLabels(scene, ids, describe), [scene, ids, describe]);\n  usePublishSelection(ids, kinds);\n}\n"],"mappings":";;;;;;AAQA,SAAgB,oBACd,OACA,KACA,UACkC;CAClC,IAAI,IAAI,WAAW,GAAG,OAAO;CAC7B,OAAO,IAAI,KAAK,OAAO;EACrB,MAAM,OAAO,MAAM,IAAI,EAAE;EACzB,OAAO,QAAQ,WAAW,SAAS,IAAI,IAAI;CAC7C,CAAC;AACH;;;AAIA,SAAgB,yBACd,OACA,KACA,UACM;CACN,MAAM,QAAQ,cAAc,oBAAoB,OAAO,KAAK,QAAQ,GAAG;EAAC;EAAO;EAAK;CAAQ,CAAC;CAC7F,oBAAoB,KAAK,KAAK;AAChC"}