@weasel-js/core 1.9.4 → 1.10.0

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

@@ -1 +1 @@
-{"version":3,"file":"serialization.js","names":["layerFromSerialized","base","spec","serializeScene","nodes","n","treePreorder","state","id","out","fnKeysOf","fnFields","field","layer","l","specsFromSerialized","json","serialized","NODE_FN_FIELDS","key","fn","registry"],"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/** 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  };\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    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.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.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":";;;AAqBA,SAAgBA,EACd,GACqB;CACrB,IAAMC,IAAO;EACX,IAAIC,EAAK;EACT,SAASA,EAAK,WAAW;EACzB,QAAQA,EAAK,UAAU;EACvB,GAAIA,EAAK,WAAW,EAAE,UAAUA,EAAK,SAAS,IAAI,CAAC;CACrD;CACA,OAAOA,EAAK,SAAS,SACjB;EAAE,GAAGD;EAAM,MAAM;EAAQ,MAAMC,EAAK,QAAQA,EAAK;CAAG,IACpD;EAAE,GAAGD;EAAM,MAAM;CAAS;AAChC;AAIA,SAAgBE,EACd,GACA,GACuC;CACvC,IAAMC,IAAgD,CAAC;CACvD,KAAK,IAAMC,KAAKC,EAAaC,EAAM,OAAOA,EAAM,KAAK,GAAG;EACtD,IAAMC,IAAKH,EAAE,IACPI,IAA4C;GAChD;GACA,MAAMJ,EAAE;GACR,OAAOA,EAAE;GACT,MAAMA,EAAE;GACR,MAAMA,EAAE;EACV;EAcA,AAbIA,EAAE,UAAU,SAAM,EAAI,SAASA,EAAE,SACjCA,EAAE,cAAc,aAAY,EAAI,YAAY,aACvCA,EAAE,aAAaA,EAAE,UAAU,SAAS,MAAG,EAAI,YAAYA,EAAE,YAC9DA,EAAE,aAAa,OAAO,EAAI,WAAW,KACzC,OAAO,OACLI,GACAC,EAASC,GAAUN,GAA+B,YAAY,MAAU;GACtE,MAAU,MACR,uBAAuBG,EAAG,QAAQI,EAAM,KAAK,MAAM,gHAErD;EACF,CAAC,CACH,GACAR,EAAM,KAAKK,CAAG;CAChB;CAYA,OAAO;EAAE,SAAS;EAAG,cAXAF,EAAM,OAAO,KAAK,MAAM;GAC3C,IAAMM,IAAiC,EAAE,IAAIC,EAAE,GAAG;GAQlD,OAPIA,EAAE,YAAY,OAAO,EAAM,UAAU,KACrCA,EAAE,WAAW,OAAM,EAAM,SAAS,KAClCA,EAAE,aAAU,EAAM,WAAWA,EAAE,WAC/BA,EAAE,SAAS,WACb,EAAM,OAAO,QACb,EAAM,OAAOA,EAAE,OAEVD;EACT,CACqB;EAAc;CAAM;AAC3C;AAMA,SAAgBE,EACd,GACA,GACqC;CACrC,IAAIC,EAAK,YAAY,GACnB,MAAU,MAAM,8BAA8BA,EAAK,QAAQ,oBAAoB;CAEjF,OAAOA,EAAK,MAAM,KAAK,MAAM;EAC3B,IAAMd,IAA0C;GAC9C,IAAIG,EAAE;GACN,MAAMA,EAAE;GACR,OAAOA,EAAE;GACT,MAAMA,EAAE;GACR,MAAMA,EAAE;EACV;EAGA,AAFIA,EAAE,WAAW,KAAA,MAAW,EAAK,SAASA,EAAE,SACxCA,EAAE,aAAa,KAAA,MAAW,EAAK,WAAWA,EAAE,WAC5CA,EAAE,cAAc,KAAA,MAClB,EAAK,YAAYA,EAAE,cAAc,aAC7B,aACCA,EAAE;EAET,IAAMY,IAAaZ;EACnB,KAAK,IAAMO,KAASM,GAAgB;GAClC,IAAMC,IAAMF,EAAWL,EAAM;GAC7B,IAAIO,MAAQ,KAAA,GAAW;GACvB,IAAMC,IAAMC,EAAST,EAAM,MAAM,GAA2CO;GAC5E,IAAI,CAACC,GACH,MAAU,MACR,kBAAkBR,EAAM,MAAM,QAAQO,EAAI,6DAE5C;GAEF,EAA6CP,EAAM,SAASQ;EAC9D;EACA,OAAOlB;CACT,CAAC;AACH"}
+{"version":3,"file":"serialization.js","names":["isSerializedScene","value","layerFromSerialized","base","spec","serializeScene","nodes","n","treePreorder","state","id","out","fnKeysOf","fnFields","field","layer","l","specsFromSerialized","json","serialized","NODE_FN_FIELDS","key","fn","registry"],"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  };\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.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.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.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":";;;AAaA,SAAgBA,EACd,GACgD;CAChD,OAAO,OAAOC,KAAU,cAAYA,KAC9BA,EAAgC,YAAY,KAC7C,MAAM,QAASA,EAA8B,KAAK;AACzD;AAWA,SAAgBC,EACd,GACqB;CACrB,IAAMC,IAAO;EACX,IAAIC,EAAK;EACT,SAASA,EAAK,WAAW;EACzB,QAAQA,EAAK,UAAU;EACvB,GAAIA,EAAK,WAAW,EAAE,UAAUA,EAAK,SAAS,IAAI,CAAC;CACrD;CACA,OAAOA,EAAK,SAAS,SACjB;EAAE,GAAGD;EAAM,MAAM;EAAQ,MAAMC,EAAK,QAAQA,EAAK;CAAG,IACpD;EAAE,GAAGD;EAAM,MAAM;CAAS;AAChC;AAIA,SAAgBE,EACd,GACA,GACuC;CACvC,IAAMC,IAAgD,CAAC;CACvD,KAAK,IAAMC,KAAKC,EAAaC,EAAM,OAAOA,EAAM,KAAK,GAAG;EACtD,IAAMC,IAAKH,EAAE,IACPI,IAA4C;GAChD;GACA,MAAMJ,EAAE;GACR,OAAOA,EAAE;GACT,MAAMA,EAAE;GACR,MAAMA,EAAE;EACV;EAeA,AAdIA,EAAE,UAAU,SAAM,EAAI,SAASA,EAAE,SACjCA,EAAE,cAAc,aAAY,EAAI,YAAY,aACvCA,EAAE,aAAaA,EAAE,UAAU,SAAS,MAAG,EAAI,YAAYA,EAAE,YAC9DA,EAAE,aAAa,OAAO,EAAI,WAAW,KACrCA,EAAE,SAAS,eAAeA,EAAE,UAAU,KAAA,MAAW,EAAI,QAAQA,EAAE,QACnE,OAAO,OACLI,GACAC,EAASC,GAAUN,GAA+B,YAAY,MAAU;GACtE,MAAU,MACR,uBAAuBG,EAAG,QAAQI,EAAM,KAAK,MAAM,gHAErD;EACF,CAAC,CACH,GACAR,EAAM,KAAKK,CAAG;CAChB;CAYA,OAAO;EAAE,SAAS;EAAG,cAXAF,EAAM,OAAO,KAAK,MAAM;GAC3C,IAAMM,IAAiC,EAAE,IAAIC,EAAE,GAAG;GAQlD,OAPIA,EAAE,YAAY,OAAO,EAAM,UAAU,KACrCA,EAAE,WAAW,OAAM,EAAM,SAAS,KAClCA,EAAE,aAAU,EAAM,WAAWA,EAAE,WAC/BA,EAAE,SAAS,WACb,EAAM,OAAO,QACb,EAAM,OAAOA,EAAE,OAEVD;EACT,CACqB;EAAc;CAAM;AAC3C;AAMA,SAAgBE,EACd,GACA,GACqC;CACrC,IAAIC,EAAK,YAAY,GACnB,MAAU,MAAM,8BAA8BA,EAAK,QAAQ,oBAAoB;CAEjF,OAAOA,EAAK,MAAM,KAAK,MAAM;EAC3B,IAAMd,IAA0C;GAC9C,IAAIG,EAAE;GACN,MAAMA,EAAE;GACR,OAAOA,EAAE;GACT,MAAMA,EAAE;GACR,MAAMA,EAAE;EACV;EAIA,AAHIA,EAAE,WAAW,KAAA,MAAW,EAAK,SAASA,EAAE,SACxCA,EAAE,aAAa,KAAA,MAAW,EAAK,WAAWA,EAAE,WAC5CA,EAAE,UAAU,KAAA,MAAW,EAAK,QAAQA,EAAE,QACtCA,EAAE,cAAc,KAAA,MAClB,EAAK,YAAYA,EAAE,cAAc,aAC7B,aACCA,EAAE;EAET,IAAMY,IAAaZ;EACnB,KAAK,IAAMO,KAASM,GAAgB;GAClC,IAAMC,IAAMF,EAAWL,EAAM;GAC7B,IAAIO,MAAQ,KAAA,GAAW;GACvB,IAAMC,IAAMC,EAAST,EAAM,MAAM,GAA2CO;GAC5E,IAAI,CAACC,GACH,MAAU,MACR,kBAAkBR,EAAM,MAAM,QAAQO,EAAI,6DAE5C;GAEF,EAA6CP,EAAM,SAASQ;EAC9D;EACA,OAAOlB;CACT,CAAC;AACH"}

package/dist/core/scene/staleReplay.js

@@ -0,0 +1,51 @@
+//#region src/core/scene/staleReplay.ts
+var e = class extends Error {};
+function t(e) {
+	let t = 0, n = /* @__PURE__ */ new WeakMap(), r = (t) => t === null || e.has(t), i = (t, n) => {
+		let r = e.get(t);
+		return r?.kind !== "container" || r.children.every((e) => n?.has(e) === !0);
+	};
+	function a(t, n, a) {
+		switch (t) {
+			case "kit:add": {
+				let t = n;
+				return a ? e.has(t.id) || !r(t.parent) : !e.has(t.id) || !i(t.id);
+			}
+			case "kit:remove": {
+				let t = n;
+				if (!a) return t.nodes.some((t) => e.has(t.id)) || !t.detached.every((e) => r(e.parent));
+				let o = new Set(t.nodes.map((e) => e.id));
+				return !t.nodes.every((t) => e.has(t.id) && i(t.id, o));
+			}
+			case "kit:move": {
+				let t = n;
+				return !e.has(t.id) || !r(a ? t.toParent : t.fromParent);
+			}
+			case "kit:setPose":
+			case "kit:setData":
+			case "kit:setLayer":
+			case "kit:setDependsOn":
+			case "kit:setLayout":
+			case "kit:setUnits": return !e.has(n.id);
+			default: return !1;
+		}
+	}
+	function o(e, r, i) {
+		return t === 0 || typeof r != "object" || !r ? !1 : n.get(r) === !i ? n.delete(r) : a(e, r, i) ? (n.set(r, i), !0) : !1;
+	}
+	return {
+		during(e) {
+			t++;
+			try {
+				return e();
+			} finally {
+				t--;
+			}
+		},
+		skips: o
+	};
+}
+//#endregion
+export { e as SceneMembershipError, t as createStaleReplay };
+
+//# sourceMappingURL=staleReplay.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"staleReplay.js","names":["SceneMembershipError","createStaleReplay","replaying","skipped","holds","id","nodes","childless","node","within","c","stale","kind","p","payload","forward","n","d","taken","skips","step"],"sources":["../../../src/core/scene/staleReplay.ts"],"sourcesContent":["/**\n * What a replay does with an op whose node is not where its entry left it.\n *\n * An untracked edit changes the tree without the history stack hearing of it,\n * so an entry can name a node that edit removed, or add one it already put\n * back. Replaying such an op is skipped rather than refused: a refusal leaves\n * the entry on top of its stack, and every entry beneath it out of reach. The\n * inverse of a skipped op is skipped too, so undo then redo changes nothing.\n */\nimport type { RemoveSnapshot } from './kitOps';\nimport type { Node, NodeId } from './types';\n\n/** A scene edit named a node the scene does not hold, or one it already does. */\nexport class SceneMembershipError extends Error {}\n\nexport interface StaleReplay {\n  /** Run a step that replays recorded ops. */\n  during<T>(step: () => T): T;\n  /** Whether replaying this kit op would address a node that is gone, or\n   *  restore one that is already there. Always false outside `during`. */\n  skips(kind: string, payload: unknown, forward: boolean): boolean;\n}\n\nexport function createStaleReplay<TData, TLayer extends string, TPose>(\n  nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>,\n): StaleReplay {\n  let replaying = 0;\n  /** Kit payloads whose last replay was skipped, by the direction it ran in. */\n  const skipped = new WeakMap<object, boolean>();\n  const holds = (id: NodeId | null): boolean => id === null || nodes.has(id);\n  const childless = (id: NodeId, within?: ReadonlySet<NodeId>): boolean => {\n    const node = nodes.get(id);\n    return node?.kind !== 'container' || node.children.every((c) => within?.has(c) === true);\n  };\n\n  function stale(kind: string, payload: unknown, forward: boolean): boolean {\n    switch (kind) {\n      case 'kit:add': {\n        const p = payload as { id: NodeId; parent: NodeId | null };\n        return forward ? nodes.has(p.id) || !holds(p.parent) : !nodes.has(p.id) || !childless(p.id);\n      }\n      case 'kit:remove': {\n        const p = payload as RemoveSnapshot<TData, TLayer, TPose>;\n        if (!forward) return p.nodes.some((n) => nodes.has(n.id)) || !p.detached.every((d) => holds(d.parent));\n        const taken = new Set(p.nodes.map((n) => n.id));\n        return !p.nodes.every((n) => nodes.has(n.id) && childless(n.id, taken));\n      }\n      case 'kit:move': {\n        const p = payload as { id: NodeId; fromParent: NodeId | null; toParent: NodeId | null };\n        return !nodes.has(p.id) || !holds(forward ? p.toParent : p.fromParent);\n      }\n      case 'kit:setPose':\n      case 'kit:setData':\n      case 'kit:setLayer':\n      case 'kit:setDependsOn':\n      case 'kit:setLayout':\n      case 'kit:setUnits':\n        return !nodes.has((payload as { id: NodeId }).id);\n      default:\n        return false;\n    }\n  }\n\n  function skips(kind: string, payload: unknown, forward: boolean): boolean {\n    if (replaying === 0 || typeof payload !== 'object' || payload === null) return false;\n    if (skipped.get(payload) === !forward) return skipped.delete(payload);\n    if (!stale(kind, payload, forward)) return false;\n    skipped.set(payload, forward);\n    return true;\n  }\n\n  return {\n    during(step) {\n      replaying++;\n      try {\n        return step();\n      } finally {\n        replaying--;\n      }\n    },\n    skips,\n  };\n}\n"],"mappings":";AAaA,IAAaA,IAAb,cAA0C,MAAM,CAAC;AAUjD,SAAgBC,EACd,GACa;CACb,IAAIC,IAAY,GAEVC,oBAAU,IAAI,QAAyB,GACvCC,KAAS,MAA+BC,MAAO,QAAQC,EAAM,IAAID,CAAE,GACnEE,KAAa,GAAY,MAA0C;EACvE,IAAMC,IAAOF,EAAM,IAAID,CAAE;EACzB,OAAOG,GAAM,SAAS,eAAeA,EAAK,SAAS,OAAO,MAAMC,GAAQ,IAAIC,CAAC,MAAM,EAAI;CACzF;CAEA,SAASC,EAAM,GAAc,GAAkB,GAA2B;EACxE,QAAQC,GAAR;GACE,KAAK,WAAW;IACd,IAAMC,IAAIC;IACV,OAAOC,IAAUT,EAAM,IAAIO,EAAE,EAAE,KAAK,CAACT,EAAMS,EAAE,MAAM,IAAI,CAACP,EAAM,IAAIO,EAAE,EAAE,KAAK,CAACN,EAAUM,EAAE,EAAE;GAC5F;GACA,KAAK,cAAc;IACjB,IAAMA,IAAIC;IACV,IAAI,CAACC,GAAS,OAAOF,EAAE,MAAM,MAAM,MAAMP,EAAM,IAAIU,EAAE,EAAE,CAAC,KAAK,CAACH,EAAE,SAAS,OAAO,MAAMT,EAAMa,EAAE,MAAM,CAAC;IACrG,IAAMC,IAAQ,IAAI,IAAIL,EAAE,MAAM,KAAK,MAAMG,EAAE,EAAE,CAAC;IAC9C,OAAO,CAACH,EAAE,MAAM,OAAO,MAAMP,EAAM,IAAIU,EAAE,EAAE,KAAKT,EAAUS,EAAE,IAAIE,CAAK,CAAC;GACxE;GACA,KAAK,YAAY;IACf,IAAML,IAAIC;IACV,OAAO,CAACR,EAAM,IAAIO,EAAE,EAAE,KAAK,CAACT,EAAMW,IAAUF,EAAE,WAAWA,EAAE,UAAU;GACvE;GACA,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK;GACL,KAAK,gBACH,OAAO,CAACP,EAAM,IAAKQ,EAA2B,EAAE;GAClD,SACE,OAAO;EACX;CACF;CAEA,SAASK,EAAM,GAAc,GAAkB,GAA2B;EAKxE,OAJIjB,MAAc,KAAK,OAAOY,KAAY,aAAYA,IAAyB,KAC3EX,EAAQ,IAAIW,CAAO,MAAM,CAACC,IAAgBZ,EAAQ,OAAOW,CAAO,IAC/DH,EAAMC,GAAME,GAASC,CAAO,KACjCZ,EAAQ,IAAIW,GAASC,CAAO,GACrB,MAFoC;CAG7C;CAEA,OAAO;EACL,OAAO,GAAM;GACX;GACA,IAAI;IACF,OAAOK,EAAK;GACd,UAAU;IACR;GACF;EACF;EACA;CACF;AACF"}

package/dist/core/scene/statedFields.js

@@ -0,0 +1,9 @@
+//#region src/core/scene/statedFields.ts
+var e = (e) => ({
+	...e.pickable === void 0 ? {} : { pickable: e.pickable },
+	...e.kind === "container" && e.units !== void 0 ? { units: e.units } : {}
+});
+//#endregion
+export { e as statedFields };
+
+//# sourceMappingURL=statedFields.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"statedFields.js","names":["statedFields","n"],"sources":["../../../src/core/scene/statedFields.ts"],"sourcesContent":["import type { UnitScope } from '@weasel-js/quantity';\n\ninterface Stated { kind?: 'leaf' | 'container'; pickable?: boolean; units?: UnitScope }\n\n/** The plain optional fields of a node or spec as a spread for `scene.add`:\n *  each present only when stated, so an unstated one keeps the scene's\n *  default. A leaf states no `units`. */\nexport const statedFields = (n: Stated): { pickable?: boolean; units?: UnitScope } => ({\n  ...(n.pickable !== undefined ? { pickable: n.pickable } : {}),\n  ...(n.kind === 'container' && n.units !== undefined ? { units: n.units } : {}),\n});\n"],"mappings":";AAOA,IAAaA,KAAgB,OAA0D;CACrF,GAAIC,EAAE,aAAa,KAAA,IAAuC,CAAC,IAA5B,EAAE,UAAUA,EAAE,SAAS;CACtD,GAAIA,EAAE,SAAS,eAAeA,EAAE,UAAU,KAAA,IAAY,EAAE,OAAOA,EAAE,MAAM,IAAI,CAAC;AAC9E"}

package/dist/core/scene/treeEdits.js

@@ -0,0 +1,127 @@
+import { fnKeysOf as e } from "./nodeFnFields.js";
+import { statedFields as t } from "./statedFields.js";
+import { SceneMembershipError as n } from "./staleReplay.js";
+//#region src/core/scene/treeEdits.ts
+function r(t, n, r, i) {
+	let a = t.map((e) => {
+		let t = r.requireNode(e);
+		return t.kind === "container" ? {
+			...t,
+			children: [...t.children]
+		} : { ...t };
+	}), o = a.filter((e) => e.parent === null || !n.has(e.parent)).map((e) => ({
+		id: e.id,
+		parent: e.parent,
+		index: r.siblingsOf(e.parent).indexOf(e.id)
+	})).sort((e, t) => e.index - t.index), s = a.flatMap((t) => {
+		let n = e(i, t, "opKey");
+		return Object.keys(n).length === 0 ? [] : [{
+			id: t.id,
+			...n
+		}];
+	});
+	return {
+		nodes: a,
+		detached: o,
+		...s.length > 0 ? { fnKeys: s } : {}
+	};
+}
+function i(i) {
+	let { nodes: a, fnFields: o } = i, { requireNode: s, siblingsOf: c, descendants: l, removalClosure: u, patchNodeFunctions: d } = i.store, { refuse: f, refuseLayer: p } = i.locks, { requireLayerIndex: m, assertSubtreeLayer: h } = i.layers, { record: g, edit: _ } = i.recorder, { noteArrival: v, noteDeparture: y, noteChange: b } = i.arrivals;
+	function x(r) {
+		let l = r.id ?? i.generateId();
+		if (a.has(l)) throw new n(`Scene: id collision on "${l}"`);
+		m(r.layer), p(r.layer, "add to");
+		let u = r.parent ?? null;
+		if (u !== null) {
+			let e = s(u);
+			if (e.kind !== "container") throw Error(`Scene: parent "${u}" is not a container`);
+			h(r.id, r.layer, u, e.layer), f(u, "add under");
+		}
+		return {
+			id: l,
+			kind: r.kind,
+			layer: r.layer,
+			pose: r.pose,
+			data: r.data,
+			parent: u,
+			index: r.index ?? c(u).length,
+			...r.dependsOn === void 0 ? {} : { dependsOn: r.dependsOn },
+			...t(r),
+			...e(o, {
+				...r,
+				id: l,
+				kind: r.kind
+			}, "opKey")
+		};
+	}
+	function S(e) {
+		if (e.length === 0) return;
+		let { ids: t, removing: n } = u(e);
+		for (let e of t) f(e, "remove");
+		let a = r(t, n, i.store, o), { detached: s } = a;
+		_("remove", s.some((e) => e.parent !== null), () => {
+			for (let e of s) y(e.id, e.parent, null);
+			g("kit:remove", a, "remove");
+		});
+	}
+	return {
+		construct(e) {
+			i.locks.lifted(() => {
+				for (let t of e) {
+					let e = x(t);
+					i.runOp("kit:add", e), d(t, e.id, null);
+				}
+			});
+		},
+		add(e) {
+			let t = x(e), n = `add ${e.kind}`;
+			return _(n, t.parent !== null, () => (v(t.id, t.parent, null), g("kit:add", t, n), d(e, t.id, t), t.id));
+		},
+		remove: (e) => S([e]),
+		removalClosure: (e) => u(e).ids,
+		removeMany: S,
+		move(e, t, n) {
+			let r = s(e);
+			if (f(e, "move"), t !== null) {
+				f(t, "move nodes into");
+				let n = s(t);
+				if (n.kind !== "container") throw Error(`Scene: parent "${t}" is not a container`);
+				if (h(e, r.layer, t, n.layer), t === e) throw Error("Scene: cannot parent a node to itself");
+				let i = [];
+				if (l(e, i), i.includes(t)) throw Error("Scene: cannot parent a node to its own descendant");
+			}
+			let i = r.parent;
+			_("move", t !== null || i !== null, () => {
+				let r = c(i).indexOf(e), a = n ?? c(t).length;
+				v(e, t, i), y(e, i, t), b(i), g("kit:move", {
+					id: e,
+					fromParent: i,
+					fromIndex: r,
+					toParent: t,
+					toIndex: a
+				}, "move");
+			});
+		},
+		reorder(e, t) {
+			let n = s(e);
+			f(e, "reorder");
+			let r = n.parent;
+			_("reorder", r !== null, () => {
+				b(r);
+				let n = c(r).indexOf(e);
+				g("kit:move", {
+					id: e,
+					fromParent: r,
+					fromIndex: n,
+					toParent: r,
+					toIndex: t
+				}, "reorder");
+			});
+		}
+	};
+}
+//#endregion
+export { i as createTreeEdits };
+
+//# sourceMappingURL=treeEdits.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeEdits.js","names":["removeSnapshot","nodes","ids","n","store","nid","detached","removing","l","r","fnKeys","keys","fnKeysOf","fnFields","createTreeEdits","env","addPayload","id","spec","SceneMembershipError","requireLayerIndex","refuseLayer","parent","p","requireNode","assertSubtreeLayer","refuse","siblingsOf","statedFields","removeMany","rootIds","removalClosure","payload","d","specs","patchNodeFunctions","label","edit","noteArrival","record","node","desc","descendants","fromParent","fromIndex","toIndex","index","noteDeparture","noteChange"],"sources":["../../../src/core/scene/treeEdits.ts"],"sourcesContent":["/**\n * The scene's edits to its tree: adding and removing nodes, reparenting, and\n * reordering siblings. Each checks its arguments, then records one kit op.\n */\nimport type { ArrivalWindow } from './arrivalWindow';\nimport type { RemoveSnapshot } from './kitOps';\nimport type { createLayerStack } from './layerStack';\nimport type { LockGuard } from './lockGuard';\nimport { fnKeysOf, type FnBearingNode, type NodeFnField } from './nodeFnFields';\nimport type { createNodeStore } from './nodeStore';\nimport type { Recorder } from './recorder';\nimport { SceneMembershipError } from './staleReplay';\nimport { statedFields } from './statedFields';\nimport type { AddNodeSpec, Node, NodeId, Scene } from './types';\n\nexport interface TreeEditsEnv<TData, TLayer extends string, TPose> {\n  nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;\n  generateId(): NodeId;\n  store: Pick<\n    ReturnType<typeof createNodeStore<TData, TLayer, TPose>>,\n    'requireNode' | 'siblingsOf' | 'descendants' | 'removalClosure' | 'patchNodeFunctions'\n  >;\n  locks: Pick<LockGuard<TLayer>, 'refuse' | 'refuseLayer' | 'lifted'>;\n  layers: Pick<ReturnType<typeof createLayerStack<TLayer>>, 'requireLayerIndex' | 'assertSubtreeLayer'>;\n  fnFields: readonly NodeFnField[];\n  /** Run a registered op without recording it. */\n  runOp(kind: string, payload: unknown): void;\n  recorder: Pick<Recorder, 'record' | 'edit'>;\n  arrivals: Pick<ArrivalWindow<TPose>, 'noteArrival' | 'noteDeparture' | 'noteChange'>;\n}\n\nexport interface TreeEdits<TData, TLayer extends string, TPose>\n  extends Pick<Scene<TData, TLayer, TPose>, 'add' | 'remove' | 'removalClosure' | 'removeMany' | 'move' | 'reorder'> {\n  /** Place nodes as the document a scene starts from, or is loaded with:\n   *  nothing is recorded, and no lock refuses. Specs list parents before\n   *  children, the order `toJSON()` emits. */\n  construct(specs: readonly AddNodeSpec<TData, TLayer, TPose>[]): void;\n}\n\n/** What `kit:remove` carries for the nodes `ids`, read before any of them\n *  goes. Throws on an id that is not in the scene. */\nfunction removeSnapshot<TData, TLayer extends string, TPose>(\n  ids: readonly NodeId[],\n  removing: ReadonlySet<NodeId>,\n  store: Pick<TreeEditsEnv<TData, TLayer, TPose>['store'], 'requireNode' | 'siblingsOf'>,\n  fnFields: readonly NodeFnField[],\n): RemoveSnapshot<TData, TLayer, TPose> {\n  const nodes: Node<TData, TLayer, TPose>[] = ids.map((nid) => {\n    const n = store.requireNode(nid);\n    return n.kind === 'container' ? { ...n, children: [...n.children] } : { ...n };\n  });\n  // The rest is reachable through a snapshotted parent's cloned `children`.\n  const detached = nodes\n    .filter((n) => n.parent === null || !removing.has(n.parent))\n    .map((n) => ({ id: n.id, parent: n.parent, index: store.siblingsOf(n.parent).indexOf(n.id) }))\n    .sort((l, r) => l.index - r.index);\n  const fnKeys = nodes.flatMap((n) => {\n    const keys = fnKeysOf(fnFields, n as unknown as FnBearingNode, 'opKey');\n    return Object.keys(keys).length === 0 ? [] : [{ id: n.id, ...keys }];\n  });\n  return { nodes, detached, ...(fnKeys.length > 0 ? { fnKeys } : {}) };\n}\n\nexport function createTreeEdits<TData, TLayer extends string, TPose>(\n  env: TreeEditsEnv<TData, TLayer, TPose>,\n): TreeEdits<TData, TLayer, TPose> {\n  const { nodes, fnFields } = env;\n  const { requireNode, siblingsOf, descendants, removalClosure, patchNodeFunctions } = env.store;\n  const { refuse, refuseLayer } = env.locks;\n  const { requireLayerIndex, assertSubtreeLayer } = env.layers;\n  const { record, edit } = env.recorder;\n  const { noteArrival, noteDeparture, noteChange } = env.arrivals;\n\n  /** Check that `spec` can be placed, and answer with the `kit:add` payload\n   *  that places it. Throws on an id collision, an unknown or locked layer,\n   *  a parent that is not a container or is locked, and a layer below the\n   *  parent's. */\n  function addPayload(spec: AddNodeSpec<TData, TLayer, TPose>) {\n    const id = spec.id ?? env.generateId();\n    if (nodes.has(id)) throw new SceneMembershipError(`Scene: id collision on \"${id}\"`);\n    requireLayerIndex(spec.layer);\n    refuseLayer(spec.layer, 'add to');\n    const parent = spec.parent ?? null;\n    if (parent !== null) {\n      const p = requireNode(parent);\n      if (p.kind !== 'container') {\n        throw new Error(`Scene: parent \"${parent}\" is not a container`);\n      }\n      assertSubtreeLayer(spec.id, spec.layer, parent, p.layer);\n      refuse(parent, 'add under');\n    }\n    return {\n      id, kind: spec.kind, layer: spec.layer, pose: spec.pose, data: spec.data,\n      parent, index: spec.index ?? siblingsOf(parent).length,\n      ...(spec.dependsOn !== undefined ? { dependsOn: spec.dependsOn } : {}),\n      ...statedFields(spec),\n      ...fnKeysOf(fnFields, { ...spec, id, kind: spec.kind } as unknown as FnBearingNode, 'opKey'),\n    };\n  }\n\n  function removeMany(rootIds: readonly NodeId[]): void {\n    if (rootIds.length === 0) return;\n    // Every id resolves against the pre-removal tree, so an id another one\n    // cascades away is absorbed rather than being a second, failing removal.\n    const { ids, removing } = removalClosure(rootIds);\n    for (const nid of ids) refuse(nid, 'remove');\n    const payload = removeSnapshot(ids, removing, env.store, fnFields);\n    const { detached } = payload;\n    edit('remove', detached.some((d) => d.parent !== null), () => {\n      for (const d of detached) noteDeparture(d.id, d.parent, null);\n      record('kit:remove', payload, 'remove');\n    });\n  }\n\n  return {\n    construct(specs) {\n      env.locks.lifted(() => {\n        for (const spec of specs) {\n          const payload = addPayload(spec);\n          env.runOp('kit:add', payload);\n          patchNodeFunctions(spec, payload.id, null);\n        }\n      });\n    },\n\n    add(spec) {\n      const payload = addPayload(spec);\n      const label = `add ${spec.kind}`;\n      return edit(label, payload.parent !== null, () => {\n        noteArrival(payload.id, payload.parent, null);\n        record('kit:add', payload, label);\n        patchNodeFunctions(spec, payload.id, payload);\n        return payload.id;\n      });\n    },\n\n    remove: (id) => removeMany([id]),\n\n    removalClosure: (rootIds) => removalClosure(rootIds).ids,\n\n    removeMany,\n\n    move(id, parent, index) {\n      const node = requireNode(id);\n      refuse(id, 'move');\n      if (parent !== null) {\n        refuse(parent, 'move nodes into');\n        const p = requireNode(parent);\n        if (p.kind !== 'container') {\n          throw new Error(`Scene: parent \"${parent}\" is not a container`);\n        }\n        assertSubtreeLayer(id, node.layer, parent, p.layer);\n        if (parent === id) throw new Error('Scene: cannot parent a node to itself');\n        const desc: NodeId[] = [];\n        descendants(id, desc);\n        if (desc.includes(parent)) {\n          throw new Error('Scene: cannot parent a node to its own descendant');\n        }\n      }\n      const fromParent = node.parent;\n      edit('move', parent !== null || fromParent !== null, () => {\n        const fromIndex = siblingsOf(fromParent).indexOf(id);\n        const toIndex = index ?? siblingsOf(parent).length;\n        noteArrival(id, parent, fromParent);\n        noteDeparture(id, fromParent, parent);\n        noteChange(fromParent);\n        record('kit:move', { id, fromParent, fromIndex, toParent: parent, toIndex }, 'move');\n      });\n    },\n\n    reorder(id, index) {\n      const node = requireNode(id);\n      refuse(id, 'reorder');\n      const parent = node.parent;\n      edit('reorder', parent !== null, () => {\n        noteChange(parent);\n        const fromIndex = siblingsOf(parent).indexOf(id);\n        record('kit:move', { id, fromParent: parent, fromIndex, toParent: parent, toIndex: index }, 'reorder');\n      });\n    },\n  };\n}\n"],"mappings":";;;;AAyCA,SAASA,EACP,GACA,GACA,GACA,GACsC;CACtC,IAAMC,IAAsCC,EAAI,KAAK,MAAQ;EAC3D,IAAMC,IAAIC,EAAM,YAAYC,CAAG;EAC/B,OAAOF,EAAE,SAAS,cAAc;GAAE,GAAGA;GAAG,UAAU,CAAC,GAAGA,EAAE,QAAQ;EAAE,IAAI,EAAE,GAAGA,EAAE;CAC/E,CAAC,GAEKG,IAAWL,EACd,QAAQ,MAAME,EAAE,WAAW,QAAQ,CAACI,EAAS,IAAIJ,EAAE,MAAM,CAAC,CAAC,CAC3D,KAAK,OAAO;EAAE,IAAIA,EAAE;EAAI,QAAQA,EAAE;EAAQ,OAAOC,EAAM,WAAWD,EAAE,MAAM,CAAC,CAAC,QAAQA,EAAE,EAAE;CAAE,EAAE,CAAC,CAC7F,MAAM,GAAG,MAAMK,EAAE,QAAQC,EAAE,KAAK,GAC7BC,IAAST,EAAM,SAAS,MAAM;EAClC,IAAMU,IAAOC,EAASC,GAAUV,GAA+B,OAAO;EACtE,OAAO,OAAO,KAAKQ,CAAI,CAAC,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC;GAAE,IAAIR,EAAE;GAAI,GAAGQ;EAAK,CAAC;CACrE,CAAC;CACD,OAAO;EAAE;EAAO;EAAU,GAAID,EAAO,SAAS,IAAI,EAAE,UAAO,IAAI,CAAC;CAAG;AACrE;AAEA,SAAgBI,EACd,GACiC;CACjC,IAAM,EAAE,UAAO,gBAAaC,GACtB,EAAE,gBAAa,eAAY,gBAAa,mBAAgB,0BAAuBA,EAAI,OACnF,EAAE,WAAQ,mBAAgBA,EAAI,OAC9B,EAAE,sBAAmB,0BAAuBA,EAAI,QAChD,EAAE,WAAQ,YAASA,EAAI,UACvB,EAAE,gBAAa,kBAAe,kBAAeA,EAAI;CAMvD,SAASC,EAAW,GAAyC;EAC3D,IAAMC,IAAKC,EAAK,MAAMH,EAAI,WAAW;EACrC,IAAId,EAAM,IAAIgB,CAAE,GAAG,MAAM,IAAIE,EAAqB,2BAA2BF,EAAG,EAAE;EAElF,AADAG,EAAkBF,EAAK,KAAK,GAC5BG,EAAYH,EAAK,OAAO,QAAQ;EAChC,IAAMI,IAASJ,EAAK,UAAU;EAC9B,IAAII,MAAW,MAAM;GACnB,IAAMC,IAAIC,EAAYF,CAAM;GAC5B,IAAIC,EAAE,SAAS,aACb,MAAU,MAAM,kBAAkBD,EAAO,qBAAqB;GAGhE,AADAG,EAAmBP,EAAK,IAAIA,EAAK,OAAOI,GAAQC,EAAE,KAAK,GACvDG,EAAOJ,GAAQ,WAAW;EAC5B;EACA,OAAO;GACL;GAAI,MAAMJ,EAAK;GAAM,OAAOA,EAAK;GAAO,MAAMA,EAAK;GAAM,MAAMA,EAAK;GACpE;GAAQ,OAAOA,EAAK,SAASS,EAAWL,CAAM,CAAC,CAAC;GAChD,GAAIJ,EAAK,cAAc,KAAA,IAA4C,CAAC,IAAjC,EAAE,WAAWA,EAAK,UAAU;GAC/D,GAAGU,EAAaV,CAAI;GACpB,GAAGN,EAASC,GAAU;IAAE,GAAGK;IAAM;IAAI,MAAMA,EAAK;GAAK,GAA+B,OAAO;EAC7F;CACF;CAEA,SAASW,EAAW,GAAkC;EACpD,IAAIC,EAAQ,WAAW,GAAG;EAG1B,IAAM,EAAE,QAAK,gBAAaC,EAAeD,CAAO;EAChD,KAAK,IAAMzB,KAAOH,GAAK,EAAOG,GAAK,QAAQ;EAC3C,IAAM2B,IAAUhC,EAAeE,GAAKK,GAAUQ,EAAI,OAAOF,CAAQ,GAC3D,EAAE,gBAAamB;EACrB,EAAK,UAAU1B,EAAS,MAAM,MAAM2B,EAAE,WAAW,IAAI,SAAS;GAC5D,KAAK,IAAMA,KAAK3B,GAAU,EAAc2B,EAAE,IAAIA,EAAE,QAAQ,IAAI;GAC5D,EAAO,cAAcD,GAAS,QAAQ;EACxC,CAAC;CACH;CAEA,OAAO;EACL,UAAU,GAAO;GACf,EAAI,MAAM,aAAa;IACrB,KAAK,IAAMd,KAAQgB,GAAO;KACxB,IAAMF,IAAUhB,EAAWE,CAAI;KAE/B,AADAH,EAAI,MAAM,WAAWiB,CAAO,GAC5BG,EAAmBjB,GAAMc,EAAQ,IAAI,IAAI;IAC3C;GACF,CAAC;EACH;EAEA,IAAI,GAAM;GACR,IAAMA,IAAUhB,EAAWE,CAAI,GACzBkB,IAAQ,OAAOlB,EAAK;GAC1B,OAAOmB,EAAKD,GAAOJ,EAAQ,WAAW,aACpCM,EAAYN,EAAQ,IAAIA,EAAQ,QAAQ,IAAI,GAC5CO,EAAO,WAAWP,GAASI,CAAK,GAChCD,EAAmBjB,GAAMc,EAAQ,IAAIA,CAAO,GACrCA,EAAQ,GAChB;EACH;EAEA,SAAS,MAAOH,EAAW,CAACZ,CAAE,CAAC;EAE/B,iBAAiB,MAAYc,EAAeD,CAAO,CAAC,CAAC;EAErD;EAEA,KAAK,GAAI,GAAQ,GAAO;GACtB,IAAMU,IAAOhB,EAAYP,CAAE;GAE3B,IADAS,EAAOT,GAAI,MAAM,GACbK,MAAW,MAAM;IACnB,EAAOA,GAAQ,iBAAiB;IAChC,IAAMC,IAAIC,EAAYF,CAAM;IAC5B,IAAIC,EAAE,SAAS,aACb,MAAU,MAAM,kBAAkBD,EAAO,qBAAqB;IAGhE,IADAG,EAAmBR,GAAIuB,EAAK,OAAOlB,GAAQC,EAAE,KAAK,GAC9CD,MAAWL,GAAI,MAAU,MAAM,uCAAuC;IAC1E,IAAMwB,IAAiB,CAAC;IAExB,IADAC,EAAYzB,GAAIwB,CAAI,GAChBA,EAAK,SAASnB,CAAM,GACtB,MAAU,MAAM,mDAAmD;GAEvE;GACA,IAAMqB,IAAaH,EAAK;GACxB,EAAK,QAAQlB,MAAW,QAAQqB,MAAe,YAAY;IACzD,IAAMC,IAAYjB,EAAWgB,CAAU,CAAC,CAAC,QAAQ1B,CAAE,GAC7C4B,IAAUC,KAASnB,EAAWL,CAAM,CAAC,CAAC;IAI5C,AAHAgB,EAAYrB,GAAIK,GAAQqB,CAAU,GAClCI,EAAc9B,GAAI0B,GAAYrB,CAAM,GACpC0B,EAAWL,CAAU,GACrBJ,EAAO,YAAY;KAAE;KAAI;KAAY;KAAW,UAAUjB;KAAQ;IAAQ,GAAG,MAAM;GACrF,CAAC;EACH;EAEA,QAAQ,GAAI,GAAO;GACjB,IAAMkB,IAAOhB,EAAYP,CAAE;GAC3B,EAAOA,GAAI,SAAS;GACpB,IAAMK,IAASkB,EAAK;GACpB,EAAK,WAAWlB,MAAW,YAAY;IACrC,EAAWA,CAAM;IACjB,IAAMsB,IAAYjB,EAAWL,CAAM,CAAC,CAAC,QAAQL,CAAE;IAC/C,EAAO,YAAY;KAAE;KAAI,YAAYK;KAAQ;KAAW,UAAUA;KAAQ,SAASwB;IAAM,GAAG,SAAS;GACvG,CAAC;EACH;CACF;AACF"}

package/dist/core/scene/treeReads.js

@@ -0,0 +1,26 @@
+//#region src/core/scene/treeReads.ts
+function e(e) {
+	let t = /* @__PURE__ */ new WeakMap(), n = 1;
+	return {
+		get: (t) => e.get(t),
+		incarnation(r) {
+			let i = e.get(r);
+			if (!i) return;
+			let a = t.get(i);
+			return a === void 0 && (a = n++, t.set(i, a)), a;
+		},
+		childrenOf(t) {
+			let n = e.get(t);
+			return n && n.kind === "container" ? n.children : [];
+		},
+		ancestorsOf(t) {
+			let n = [], r = e.get(t)?.parent ?? null;
+			for (; r !== null;) n.push(r), r = e.get(r)?.parent ?? null;
+			return n;
+		}
+	};
+}
+//#endregion
+export { e as createTreeReads };
+
+//# sourceMappingURL=treeReads.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeReads.js","names":["createTreeReads","incarnations","nextIncarnation","nodes","id","node","token","out","cur"],"sources":["../../../src/core/scene/treeReads.ts"],"sourcesContent":["/** The scene's reads of one node and its place in the tree. */\nimport type { Node, NodeId, Scene } from './types';\n\nexport function createTreeReads<TData, TLayer extends string, TPose>(\n  nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>,\n): Pick<Scene<TData, TLayer, TPose>, 'get' | 'incarnation' | 'childrenOf' | 'ancestorsOf'> {\n  // Keyed by node object: every entry into `nodes` is a fresh object and\n  // every edit mutates it in place, which is exactly an incarnation's lifetime.\n  const incarnations = new WeakMap<object, number>();\n  let nextIncarnation = 1;\n\n  return {\n    get: (id) => nodes.get(id),\n\n    incarnation(id) {\n      const node = nodes.get(id);\n      if (!node) return undefined;\n      let token = incarnations.get(node);\n      if (token === undefined) {\n        token = nextIncarnation++;\n        incarnations.set(node, token);\n      }\n      return token;\n    },\n\n    childrenOf(id) {\n      const n = nodes.get(id);\n      return n && n.kind === 'container' ? n.children : [];\n    },\n\n    ancestorsOf(id) {\n      const out: NodeId[] = [];\n      let cur = nodes.get(id)?.parent ?? null;\n      while (cur !== null) {\n        out.push(cur);\n        cur = nodes.get(cur)?.parent ?? null;\n      }\n      return out;\n    },\n  };\n}\n"],"mappings":";AAGA,SAAgBA,EACd,GACyF;CAGzF,IAAMC,oBAAe,IAAI,QAAwB,GAC7CC,IAAkB;CAEtB,OAAO;EACL,MAAM,MAAOC,EAAM,IAAIC,CAAE;EAEzB,YAAY,GAAI;GACd,IAAMC,IAAOF,EAAM,IAAIC,CAAE;GACzB,IAAI,CAACC,GAAM;GACX,IAAIC,IAAQL,EAAa,IAAII,CAAI;GAKjC,OAJIC,MAAU,KAAA,MACZ,IAAQ,KACRL,EAAa,IAAII,GAAMC,CAAK,IAEvBA;EACT;EAEA,WAAW,GAAI;GACb,IAAM,IAAIH,EAAM,IAAIC,CAAE;GACtB,OAAO,KAAK,EAAE,SAAS,cAAc,EAAE,WAAW,CAAC;EACrD;EAEA,YAAY,GAAI;GACd,IAAMG,IAAgB,CAAC,GACnBC,IAAML,EAAM,IAAIC,CAAE,CAAC,EAAE,UAAU;GACnC,OAAOI,MAAQ,OAEb,AADAD,EAAI,KAAKC,CAAG,GACZ,IAAML,EAAM,IAAIK,CAAG,CAAC,EAAE,UAAU;GAElC,OAAOD;EACT;CACF;AACF"}

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["asNodeId","s"],"sources":["../../../src/core/scene/types.ts"],"sourcesContent":["import type { Path } from '@weasel-js/geom';\nimport type { History, SerializedHistory } from '@weasel-js/history';\nimport type { ParallaxOpts } from '../viewport/parallax';\nimport type { ContainerBounds, LayoutStrategy } from '../../layout/types';\nimport type { PoseComposition } from './composeFrame';\nimport type { PoseLinear } from '../geometry/poseFrame';\n\n/**\n * Axis-aligned rectangle pose with optional rotation. The canonical pose\n * shape used by `composeRectPose` and the `unionBounds` helper. Rotation is\n * in radians, pivoted on the unrotated AABB center; absent === 0. Kit-side\n * code that consumes rotation already reads `pose.rotation ?? 0`\n * (`wrapNodeOutput`, `rotate/handle.ts`, `pathInWorld.ts`), so\n * the slot exists on every default scene whether or not the consumer\n * populates it.\n */\nexport interface RectPose {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n  /** Rotation in radians around the unrotated AABB center. Absent === 0. */\n  rotation?: number;\n  /** A skew or per-axis scale the box and rotation cannot hold; see\n   *  {@link PoseLinear}. Absent is the identity. */\n  transform?: PoseLinear;\n}\n\n/**\n * # SceneNode — the thing in the scene\n *\n * A `SceneNode` is the single canonical unit of a weasel scene. Everything\n * the user sees on the canvas — a shape, a group, an annotation, a tile —\n * is one of these. Containers and leaves are both nodes; the kit has no\n * other concept of \"scene element.\"\n *\n * ## Three orthogonal slots\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 *     Color, label, kind, glyph, sample-rate, whatever the app's domain\n *     calls for. Mutated via `Scene.update(id, { data })`.\n *\n *   - **`pose: TPose`** — local transform, relative to the node's direct\n *     parent (or world, for root nodes). Default `RectPose` is\n *     `{ x, y, width, height }`, but `TPose` is fully generic so apps can\n *     use rotated rects, paths, ellipses, etc. The kit composes world\n *     poses via `composeWorldPose` when rendering / hit-testing / snapping.\n *\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 * Tree position lives on the node itself: every node has a `parent` (or\n * `null` for roots), and `ContainerNode` adds an ordered `children: NodeId[]`.\n *\n * ## Identity is by `NodeId`, not by reference\n *\n * Nodes are addressed by `NodeId` everywhere outside the scene tree:\n * selection is `NodeId[]`, ops reference `NodeId`s, adapter methods accept\n * `string` ids and look up the node on demand. The `Node` object itself is\n * a snapshot of current state — don't hold references to it across scene\n * updates; look up by id when you need the latest.\n *\n * Picking helpers (`pickBest`, `pickEvery`) likewise return ids, not nodes —\n * they're hit-testing primitives that stay ignorant of node payload shape.\n *\n * ## Vocabulary\n *\n * The kit-internal name is `Node`; the public re-export is `SceneNode`\n * (avoids collision with DOM `Node` at call sites). Adapter methods speak\n * the same vocabulary: `getNode`, `getNodes`, `insertNode`, `removeNode`,\n * `cloneNode`, `addNode`. Older code, demos, and comments may still say\n * \"object\" or \"item\" — those are historical aliases for the same concept.\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\n/**\n * One dependency, as a derivation reads it: the node itself and the pose it is\n * painted at.\n *\n * The node comes along because a connector legitimately reads more than a box\n * — an edge that thickens with its endpoint's weight, or routes only to nodes\n * on a given layer, is answering off `data` and `layer`. The scene already\n * invalidates dependents on `kit:setData` and `kit:setLayer` for exactly that,\n * so handing over only the pose made the invalidation pay for a read nothing\n * could perform.\n */\nexport interface DerivedDep<TPose, TData = unknown, TLayer extends string = string> {\n  node: Node<TData, TLayer, TPose>;\n  /** Its override when it has one, else its own derived pose, else the pose\n   *  the document stores — `effectivePose`, the same answer the renderer uses. */\n  pose: TPose;\n  /** The path it derives, or `null` when it derives none. Read it to place\n   *  something *along* a dependency rather than beside it — a label on a\n   *  routed edge, a tick on a curve.\n   *\n   *  Resolved on first read and memoized on the dependency, so a route costs\n   *  the same whether one node reads it or five, and a dependency nobody asks\n   *  about costs nothing. */\n  readonly path: Path | null;\n}\n\n/** `F` with its parameters checked bivariantly, as a method's are, so that a\n *  `Scene<D, L, MyPose>` is a `Scene<unknown, string, unknown>`. A callback for\n *  an unrelated pose is still rejected; one for a narrower pose is not. */\ntype Bivariant<F extends (...args: never[]) => unknown> = {\n  method(...args: Parameters<F>): ReturnType<F>;\n}['method'];\n\n/** Computes a node's path from its dependencies: the type of a node's\n *  `derivePath` and of each entry in `SceneRegistry.derivePath`. */\nexport type DerivePathFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(\n  node: Node<TData, TLayer, TPose>,\n  deps: readonly (DerivedDep<TPose, TData, TLayer> | undefined)[],\n) => Path | null>;\n\n/** Computes a node's pose from its dependencies: the type of a node's\n *  `derivePose` and of each entry in `SceneRegistry.derivePose`. */\nexport type DerivePoseFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(\n  node: Node<TData, TLayer, TPose>,\n  deps: readonly (DerivedDep<TPose, TData, TLayer> | undefined)[],\n) => TPose | null>;\n\n/** A container's clip, from its pose: the type of `ContainerNode.clipFromPose`\n *  and of each entry in `SceneRegistry.clipFromPose`. */\nexport type ClipFromPoseFn<TPose> = Bivariant<(pose: TPose) => Path | null>;\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. Without it the innermost hit\n   *  wins, and dragging a labeled box moves the label out of the box. It does\n   *  not hide the node from anything else — it still paints, still clips, and\n   *  a consumer can still select it by id. */\n  pickable?: 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. Absolute-pose `Scene`\n   *  makes that the dependency's own pose, and an ancestor's move reaches it as\n   *  a `setPose` of its own from the container cascade. */\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   *  that is what lets a drag preview a node the document says is elsewhere.\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). When set, the\n   *  renderer rasterizes the returned path into the stencil buffer and\n   *  paints descendants only where it covers. */\n  clipFromPose?: ClipFromPoseFn<TPose>;\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}\n\n/** A pose a container's layout wrote — reported by {@link Scene.onReflow} —\n *  in the node's stored frame. */\nexport interface LayoutMove<TPose> {\n  id: NodeId;\n  from: TPose;\n  to: TPose;\n}\n\n/** How a scene reads a laid-out container's bounds and folds poses to the\n *  world frame a {@link LayoutStrategy} works in. */\nexport interface LayoutFrame<TPose> {\n  /** The container's bounds, from its world pose. Default: the pose's own\n   *  `x`/`y`/`width`/`height`; a pose without them is not laid out. */\n  bounds?(pose: TPose): ContainerBounds | null;\n  /** `pose` resized from bounds `from` to `to`, for a layout that grows its\n   *  container. Default: `to`'s fields written over the pose. */\n  remap?(pose: TPose, from: ContainerBounds, to: ContainerBounds): TPose;\n  /** Omit for the absolute-pose model. A scene whose canvas composes poses\n   *  (`<SceneCanvas poseComposition>`) passes the same strategy here. */\n  composition?: PoseComposition<TPose>;\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\ninterface LayerRecordBase<TLayer extends string> {\n  id: TLayer;\n  visible: boolean;\n  locked: boolean;\n  /** Draw this layer as a parallax plane: through a view derived from the\n   *  camera's (see `deriveParallaxView`), and picked through the same one.\n   *  Absent means the layer moves with the camera. */\n  parallax?: ParallaxOpts;\n}\n\n/** A layer declared when the scene was created. Fixed set, no display name —\n *  these are the kit's own render bands, not something a user manages. */\nexport interface SystemLayerRecord<TLayer extends string>\n  extends LayerRecordBase<TLayer> {\n  kind: 'system';\n}\n\n/** A layer the user created and can rename, reorder or delete. */\nexport interface UserLayerRecord<TLayer extends string>\n  extends LayerRecordBase<TLayer> {\n  kind: 'user';\n  name: string;\n}\n\n/** Per-layer metadata held by the scene: whether it is visible and locked,\n *  and where it sits in the render stack. Distinct from a node's `layer` tag,\n *  which merely names one of these. */\nexport type LayerRecord<TLayer extends string> =\n  | SystemLayerRecord<TLayer>\n  | UserLayerRecord<TLayer>;\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  /** 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 `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}\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/** One of the layers a scene is created with. */\nexport interface SystemLayerSpec<TLayer extends string> {\n  id: TLayer;\n  visible?: boolean;\n  locked?: boolean;\n  /** See `LayerRecord.parallax`. */\n  parallax?: ParallaxOpts;\n}\n\n/** Argument to `Scene.addLayer`. Always produces a `UserLayerRecord`\n *  (`kind: 'user'`). */\nexport interface AddLayerSpec<TLayer extends string> {\n  id: TLayer;\n  name: string;\n  /** Default `true`. */\n  visible?: boolean;\n  /** Default `false`. */\n  locked?: boolean;\n  /** See `LayerRecord.parallax`. */\n  parallax?: ParallaxOpts;\n  /** Render-stack position. Default: top of stack (highest render index). */\n  index?: number;\n}\n\n/** One layer as it appears in a snapshot. A snapshot written before layer\n *  kind was serialized carries neither field, and loads as a system layer —\n *  which is what every layer in such a snapshot was. */\nexport interface SerializedLayer<TLayer extends string>\n  extends SystemLayerSpec<TLayer> {\n  kind?: 'system' | 'user';\n  /** Present on a user layer, absent on a system one. */\n  name?: string;\n}\n\n/** JSON-serializable shape of a Scene's current state. Produced by\n *  `scene.toJSON()`; consumed by `sceneFromJSON()`. Function fields\n *  (e.g., `clipFromPose`) appear as string keys (`clipFromPoseKey`) and\n *  are resolved through `SceneRegistry` at load time. */\nexport interface SerializedScene<TData, TLayer extends string, TPose> {\n  version: 1;\n  /** The whole layer stack, system and user alike — the name predates user\n   *  layers and is kept so existing snapshots still parse. */\n  systemLayers: readonly SerializedLayer<TLayer>[];\n  nodes: readonly SerializedNode<TData, TLayer, TPose>[];\n}\n\n/** JSON-serializable shape of a single node. Mirrors `AddNodeSpec` but\n *  with function fields replaced by registry keys. */\nexport interface SerializedNode<TData, TLayer extends string, TPose> {\n  id: string;\n  kind: 'leaf' | 'container';\n  layer: TLayer;\n  pose: TPose;\n  data: TData;\n  /** Parent id; omitted for roots. */\n  parent?: string;\n  /** Registry key for the container's clip-path factory.\n   *  Containers only; omitted when the container has no clip. */\n  clipFromPoseKey?: string;\n  /** Ids this node's geometry derives from, or `'children'`. Omitted when it\n   *  derives from nothing. */\n  dependsOn?: readonly string[] | 'children';\n  /** Mirrors `SceneNode.pickable`. Omitted when the node is pickable. */\n  pickable?: boolean;\n  /** Registry key for the node's `derivePath` function. Omitted when it has none. */\n  derivePathKey?: string;\n  /** Registry key for the node's `derivePose` function. Omitted when it has none. */\n  derivePoseKey?: string;\n  /** Registry key for the container's layout strategy. Omitted when it has none. */\n  layoutKey?: string;\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 `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/** Options for `useScene` — the layers the scene has, what it starts out\n *  holding, and how its history behaves. */\nexport interface UseSceneOptions<TData, TLayer extends string, TPose = RectPose> {\n  systemLayers: readonly SystemLayerSpec<TLayer>[];\n  initial?: readonly AddNodeSpec<TData, TLayer, TPose>[];\n  ops?: Readonly<Record<string, RegisteredOp<unknown>>>;\n  historyLimit?: number;\n  /** Window (ms) within which consecutive same-shaped mutations merge into\n   *  the previous undo entry (matching per-op coalesce keys — e.g. repeated\n   *  `setPose` on the same node, or repeated `applyBatch` calls whose ops\n   *  carry matching `coalesceKey` multisets). `0` (default) disables\n   *  coalescing: every mutation is a discrete undo entry. Undo of a\n   *  coalesced entry returns to the state before the first merged mutation;\n   *  redo restores the latest. `scene.batch` entries never coalesce. */\n  coalesceWindowMs?: number;\n  generateId?: () => NodeId;\n  /** Per-scene registry for non-serializable function fields (clipFromPose, etc.).\n   *  Required only when serializing/deserializing scenes that use function fields. */\n  registry?: SceneRegistry<TPose, TData, TLayer>;\n  /** How laid-out containers are measured. See {@link LayoutFrame}. */\n  layoutFrame?: LayoutFrame<TPose>;\n  /** When supplied, `scene.applyOps(ops, label)` consults this on every call.\n   *  If it returns a non-null `Journal`, ops are routed to the journal's\n   *  `applyBatch` instead of recording a new parent-history entry. The journal\n   *  drives adapter mutation internally (via `op.apply(adapter)`), so the\n   *  scene state changes as normal; only the history tracking differs.\n   *\n   *  The accessor is called on every `applyOps` invocation so the caller can\n   *  swap the active journal in and out by updating the closure's reference\n   *  (e.g., an app's mode machine holds `let activeJournal: Journal | null`\n   *  and the accessor reads that variable).\n   *\n   *  When the accessor isn't known at scene-construction time (typical for\n   *  mode machines that depend on `scene.history`), pass nothing here and\n   *  wire it after construction via `scene.setActiveJournalAccessor(fn)`. */\n  getActiveJournal?: () => import('@weasel-js/history').Journal | null;\n  /** Re-render the host on every scene mutation. Default `true`. Set `false`\n   *  when the scene is read by a frame loop rather than by a render — a game\n   *  loop, a simulation — and nothing in the host's DOM derives from it.\n   *  Read by `useScene`; `createScene` ignores it. */\n  subscribe?: boolean;\n}\n\n/**\n * One node's ephemeral presentation override — what a frame loop wants to say\n * about a node without saying it about the document.\n *\n * Not document content: never recorded in history, never in `toJSON`, and\n * writing one does not bump `Scene.getVersion()`. Hoist one entry per node and\n * mutate it in place on a frame loop; `PoseOverrides.commit()` is what makes a\n * mutation visible.\n */\nexport interface PoseOverride<TPose> {\n  /** Replaces the node's document pose everywhere the render and hit-test\n   *  paths read one, including the clip a container derives from its pose, and\n   *  winning over a `derivePose`. Resolved by `effectivePose` — reading\n   *  `node.pose` directly is how those paths came to disagree about where a\n   *  node is. */\n  pose?: TPose;\n  /** Multiplied into the node's painted alpha, on top of any `alphaFor`. */\n  alpha?: number;\n}\n\n/**\n * The scene's ephemeral per-node overrides — see {@link PoseOverride}.\n *\n * The intended shape of a frame is: `set` each node once, mutate the entries\n * in place per frame, `commit()` once. `commit` is not optional bookkeeping —\n * the painter memo keys on pose *reference*, so a mutation without a commit\n * paints the previous frame with no error.\n *\n * To promote a frame to document state (dropping a drag, baking an animation),\n * write it once through `Scene.setPose` and `clear` the override.\n */\nexport interface PoseOverrides<TPose> {\n  /** Store `entry` for `id` **by reference**; the caller keeps mutating it. */\n  set(id: NodeId, entry: PoseOverride<TPose>): void;\n  /** The entry `set` stored, by reference — what a writer checks to know\n   *  whether its own entry is still installed. Painting reads `read`. */\n  get(id: NodeId): PoseOverride<TPose> | undefined;\n  /** What the node is drawn and picked with: every source of overrides for\n   *  it folded into one, as of the last write or `commit()`. `undefined` for\n   *  a node nothing overrides. The object is reused per node. */\n  read(id: NodeId): PoseOverride<TPose> | undefined;\n  has(id: NodeId): boolean;\n  /** The overridden ids, as a snapshot array. */\n  ids(): readonly NodeId[];\n  clear(id: NodeId): void;\n  clearAll(): void;\n  /** Publish this frame's in-place mutations: invalidate the painter memo for\n   *  every overridden node, then notify subscribers. */\n  commit(): void;\n  /** Notified after every write. The canvas uses this to repaint without a\n   *  scene version bump. */\n  subscribe(fn: () => void): () => void;\n  /** Monotonic write counter. A snapshot for observers that poll. */\n  getGeneration(): number;\n}\n\n/**\n * The kit-owned scene tree: nodes, layers, and the undo history over both.\n *\n * A scene is logical, not visual — it says what exists and where, and nothing\n * about how it is painted. Every mutating method is undoable, and reads are\n * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids\n * across mutations, not node objects.\n *\n * Three type parameters keep it domain-agnostic: `TData` is the app's payload,\n * which the kit never inspects; `TPose` is the transform shape, `RectPose` by\n * default; `TLayer` is the union of layer names.\n */\nexport interface Scene<TData, TLayer extends string, TPose = RectPose> {\n  // 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  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: the traversal already holds them, and re-looking each one\n   *  up was ~40% of the area hit-test's per-node cost. Cached until a\n   *  structural edit, so repeat calls hand back the same array — a snapshot,\n   *  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, so a caller that\n   *  only cares about one layer pays the tree walk once rather than once per\n   *  call. A snapshot, not a live view, and not yours to mutate. An unknown\n   *  layer id yields an 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. The authoritative answer — the cascade relations live here, and\n   *  a caller reconstructing them from `dependsOn` and `children` drifts the\n   *  moment a third one is added. 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  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` sits on a locked layer or under a container that does.\n   *  A container's 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  /** 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) the active-journal accessor after scene construction.\n   *  Useful when the journal source (typically a mode machine) is built\n   *  with `scene.history` as a dependency — a chicken-and-egg situation\n   *  where the accessor can't be passed in via `UseSceneOptions`.\n   *\n   *  Pass `null` to detach. Overrides any `getActiveJournal` set in\n   *  `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 with journal-aware routing.\n   *\n   *  - **Without active journal** (or no `getActiveJournal` in options):\n   *    the ops themselves are recorded as one undo entry on the scene's own\n   *    history, rebound to `adapter` — undo replays each op's `invert()`\n   *    against that same adapter. Consecutive `applyBatch` entries can\n   *    coalesce via matching op `coalesceKey`s when the scene opts into\n   *    `coalesceWindowMs`.\n   *  - **With active journal**: routes ops to `journal.applyBatch(ops, label)`.\n   *    The scene's history recording is suppressed for the duration so the\n   *    journal's inner history — not the scene's undo stack — tracks the batch.\n   *    Mutations still happen on `adapter` / scene state.\n   *\n   *  `adapter` must be the same adapter the ops expect (typically a\n   *  `SceneCanvasAdapter`). Pass `this` from `sceneToAdapter` or a compatible\n   *  adapter. */\n  applyBatch(ops: import('core/ops/types').Op[], label: string, adapter: unknown): void;\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. */\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   *  what the kit's `undo` / `redo` actions resolve their `history` dep to, and\n   *  what a mode machine opens journals against. 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  /** Called with the poses each live edit's layout pass wrote, after the\n   *  edit lands — never for an undo or redo, which restore poses rather than\n   *  arrange them. What a reflow animation glides from. */\n  onReflow(listener: (moves: readonly LayoutMove<TPose>[]) => void): () => 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 by calling undo/redo repeatedly.\n   *  Clamps to [0, total]. Returns true 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`). Entries containing any nameless op are\n   *  dropped (hand-rolled anonymous ops passed to `applyBatch`); kit and\n   *  consumer-registered ops always carry names. Payload JSON-safety\n   *  (e.g. typed arrays inside poses) is the caller's concern. Do not call\n   *  mid-`batch` — the open batch's ops are not yet recorded. */\n  serializeHistory(): SerializedHistory;\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. 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 (recorded via `applyBatch`, rebuilt from a\n   *  `restoreHistory` snapshot) apply against on undo/redo. Resolved lazily\n   *  at each apply, so wiring order relative to `restoreHistory` doesn't\n   *  matter. Live `applyBatch` entries are unaffected (they bind their\n   *  call-site adapter). If unset when a restored op applies, the op is a\n   *  debug-warned 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 `batch` or `untracked`, which revert to a state this\n   *  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":";AAkFA,IAAaA,KAAY,MAAsBC"}
+{"version":3,"file":"types.js","names":["asNodeId","s"],"sources":["../../../src/core/scene/types.ts"],"sourcesContent":["import type { Path } from '@weasel-js/geom';\nimport 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 { LayoutFrame, LayoutMove } from './layoutTypes';\nimport type { PoseComposition } from './composeFrame';\nimport type { PoseLinear } from '@weasel-js/geom';\nimport type { PoseHold, PoseOverride, PoseOverrides } from './poseOverrideTypes';\nimport type { SerializedLayer, SerializedNode, SerializedScene } from './serializedTypes';\n\nexport type { LayoutFrame, LayoutMove, PoseHold, PoseOverride, PoseOverrides, SerializedLayer, SerializedNode, SerializedScene };\n\n/**\n * Axis-aligned rectangle pose with optional rotation. Rotation is in\n * radians, pivoted on the unrotated AABB center; absent === 0.\n */\nexport interface RectPose {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n  /** Rotation in radians around the unrotated AABB center. Absent === 0. */\n  rotation?: number;\n  /** A skew or per-axis scale the box and rotation cannot hold; see\n   *  {@link PoseLinear}. Absent is the identity. */\n  transform?: PoseLinear;\n}\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\n/**\n * One dependency, as a derivation reads it: the node itself and the pose it is\n * painted at.\n *\n * The node comes along because a connector legitimately reads more than a box\n * — an edge that thickens with its endpoint's weight, or routes only to nodes\n * on a given layer, is answering off `data` and `layer`.\n */\nexport interface DerivedDep<TPose, TData = unknown, TLayer extends string = string> {\n  node: Node<TData, TLayer, TPose>;\n  /** Its override when it has one, else its own derived pose, else the pose\n   *  the document stores — `effectivePose`, the same answer the renderer uses. */\n  pose: TPose;\n  /** The path it derives, or `null` when it derives none. Read it to place\n   *  something *along* a dependency rather than beside it — a label on a\n   *  routed edge, a tick on a curve. Resolved on first read and memoized on\n   *  the dependency. */\n  readonly path: Path | null;\n}\n\n/** `F` with its parameters checked bivariantly, as a method's are, so that a\n *  `Scene<D, L, MyPose>` is a `Scene<unknown, string, unknown>`. A callback for\n *  an unrelated pose is still rejected; one for a narrower pose is not. */\nexport type Bivariant<F extends (...args: never[]) => unknown> = {\n  method(...args: Parameters<F>): ReturnType<F>;\n}['method'];\n\n/** Computes a node's path from its dependencies: the type of a node's\n *  `derivePath` and of each entry in `SceneRegistry.derivePath`. */\nexport type DerivePathFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(\n  node: Node<TData, TLayer, TPose>,\n  deps: readonly (DerivedDep<TPose, TData, TLayer> | undefined)[],\n) => Path | null>;\n\n/** Computes a node's pose from its dependencies: the type of a node's\n *  `derivePose` and of each entry in `SceneRegistry.derivePose`. */\nexport type DerivePoseFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(\n  node: Node<TData, TLayer, TPose>,\n  deps: readonly (DerivedDep<TPose, TData, TLayer> | undefined)[],\n) => TPose | null>;\n\n/** A container's clip, from its pose: the type of `ContainerNode.clipFromPose`\n *  and of each entry in `SceneRegistry.clipFromPose`. */\nexport type ClipFromPoseFn<TPose> = Bivariant<(pose: TPose) => Path | null>;\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  /** 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  /** 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\ninterface LayerRecordBase<TLayer extends string> {\n  id: TLayer;\n  visible: boolean;\n  locked: boolean;\n  /** Draw this layer as a parallax plane: through a view derived from the\n   *  camera's (see `deriveParallaxView`), and picked through the same one.\n   *  Absent means the layer moves with the camera. */\n  parallax?: ParallaxOpts;\n}\n\n/** A layer declared when the scene was created. Fixed set, no display name —\n *  these are the kit's own render bands, not something a user manages. */\nexport interface SystemLayerRecord<TLayer extends string>\n  extends LayerRecordBase<TLayer> {\n  kind: 'system';\n}\n\n/** A layer the user created and can rename, reorder or delete. */\nexport interface UserLayerRecord<TLayer extends string>\n  extends LayerRecordBase<TLayer> {\n  kind: 'user';\n  name: string;\n}\n\n/** Per-layer metadata held by the scene: whether it is visible and locked,\n *  and where it sits in the render stack. Distinct from a node's `layer` tag,\n *  which merely names one of these. */\nexport type LayerRecord<TLayer extends string> =\n  | SystemLayerRecord<TLayer>\n  | UserLayerRecord<TLayer>;\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  /** 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 `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/** One of the layers a scene is created with. */\nexport interface SystemLayerSpec<TLayer extends string> {\n  id: TLayer;\n  visible?: boolean;\n  locked?: boolean;\n  /** See `LayerRecord.parallax`. */\n  parallax?: ParallaxOpts;\n}\n\n/** Argument to `Scene.addLayer`. Always produces a `UserLayerRecord`\n *  (`kind: 'user'`). */\nexport interface AddLayerSpec<TLayer extends string> {\n  id: TLayer;\n  name: string;\n  /** Default `true`. */\n  visible?: boolean;\n  /** Default `false`. */\n  locked?: boolean;\n  /** See `LayerRecord.parallax`. */\n  parallax?: ParallaxOpts;\n  /** Render-stack position. Default: top of stack (highest render index). */\n  index?: number;\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 `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/** Options for `useScene` — the layers the scene has, what it starts out\n *  holding, and how its history behaves. */\nexport interface UseSceneOptions<TData, TLayer extends string, TPose = RectPose> {\n  systemLayers: readonly SystemLayerSpec<TLayer>[];\n  initial?: readonly AddNodeSpec<TData, TLayer, TPose>[];\n  ops?: Readonly<Record<string, RegisteredOp<unknown>>>;\n  historyLimit?: number;\n  /** Window (ms) within which consecutive same-shaped mutations merge into\n   *  the previous undo entry (matching per-op coalesce keys — e.g. repeated\n   *  `setPose` on the same node, or repeated `applyBatch` calls whose ops\n   *  carry matching `coalesceKey` multisets). `0` (default) disables\n   *  coalescing: every mutation is a discrete undo entry. Undo of a\n   *  coalesced entry returns to the state before the first merged mutation;\n   *  redo restores the latest. `scene.batch` entries never coalesce. */\n  coalesceWindowMs?: number;\n  generateId?: () => NodeId;\n  /** Per-scene registry for non-serializable function fields (clipFromPose, etc.).\n   *  Required only when serializing/deserializing scenes that use function fields. */\n  registry?: SceneRegistry<TPose, TData, TLayer>;\n  /** How a child's pose folds into its container's. Default: it does not, and every pose is world. */\n  composition?: PoseComposition<TPose>;\n  /** How laid-out containers are measured. See {@link LayoutFrame}. */\n  layoutFrame?: LayoutFrame<TPose>;\n  /** When supplied, `scene.applyBatch` consults this on every call. If it\n   *  returns a non-null `Journal`, ops are routed to the journal's\n   *  `applyBatch` instead of recording a new parent-history entry. The scene\n   *  state changes as normal; only the history tracking differs.\n   *\n   *  When the accessor isn't known at scene-construction time, wire it after\n   *  construction via `scene.setActiveJournalAccessor(fn)`. */\n  getActiveJournal?: () => import('@weasel-js/history').Journal | null;\n  /** Re-render the host on every scene mutation. Default `true`. Set `false`\n   *  when the scene is read by a frame loop rather than by a render — a game\n   *  loop, a simulation — and nothing in the host's DOM derives from it.\n   *  Read by `useScene`; `createScene` ignores it. */\n  subscribe?: boolean;\n}\n\n/**\n * The kit-owned scene tree: nodes, layers, and the undo history over both.\n *\n * A scene is logical, not visual — it says what exists and where, and nothing\n * about how it is painted. Every mutating method is undoable, and reads are\n * snapshots rather than live views. Nodes are addressed by `NodeId`; hold ids\n * across mutations, not node objects.\n *\n * Three type parameters keep it domain-agnostic: `TData` is the app's payload,\n * which the kit never inspects; `TPose` is the transform shape, `RectPose` by\n * default; `TLayer` is the union of layer names.\n */\nexport interface Scene<TData, TLayer extends string, TPose = RectPose> {\n  // 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  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` sits on a locked layer or under a container that does.\n   *  A container's 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  /** 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  /** Called with the poses each live edit's layout pass wrote, after the\n   *  edit lands — never for an undo or redo, which restore poses rather than\n   *  arrange them. What a reflow animation glides from. */\n  onReflow(listener: (moves: readonly LayoutMove<TPose>[]) => void): () => 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":";AA2DA,IAAaA,KAAY,MAAsBC"}

package/dist/{features/groups → core/scene}/unionOfChildren.js

@@ -1,6 +1,6 @@
-import { unionAABB as e } from "../../core/geometry/unionBounds.js";
-import { poseDescriptorForNode as t, visualBoundsViaDescriptor as n } from "../../core/geometry/poseDescriptor.js";
-//#region src/features/groups/unionOfChildren.ts
+import { unionAABB as e } from "../geometry/unionBounds.js";
+import { poseDescriptorForNode as t, visualBoundsViaDescriptor as n } from "../geometry/poseDescriptor.js";
+//#region src/core/scene/unionOfChildren.ts
 function r(r) {
 	return (i, a) => {
 		let o = [];

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

@@ -0,0 +1 @@
+{"version":3,"file":"unionOfChildren.js","names":["unionOfChildrenVia","boxes","d","deps","visualBoundsViaDescriptor","poseDescriptorForNode","descriptor","u","unionAABB","node"],"sources":["../../../src/core/scene/unionOfChildren.ts"],"sourcesContent":["import { unionAABB } from 'core/geometry/unionBounds';\nimport {\n  poseDescriptorForNode,\n  visualBoundsViaDescriptor,\n  type PoseDescriptor,\n} from 'core/geometry/poseDescriptor';\nimport type { DerivePoseFn } from 'core/scene/types';\n\n/**\n * A container's pose as the envelope of what it holds, read through\n * `descriptor` — a rotated member contributes the extent of its ink. Register\n * the result under `UNION_OF_CHILDREN` in `createScene`'s `registry` to teach\n * a scene how to size its groups around a pose shape the kit cannot read.\n *\n * Returns `null` for an emptied container, which falls back to its authored\n * pose rather than collapsing to a zero box at the origin.\n */\nexport function unionOfChildrenVia<TPose>(\n  descriptor: PoseDescriptor<TPose>,\n): DerivePoseFn<TPose> {\n  return (node, deps) => {\n    const boxes = [];\n    for (const d of deps) {\n      if (d !== undefined) {\n        boxes.push(visualBoundsViaDescriptor(d.pose, poseDescriptorForNode(descriptor, d)));\n      }\n    }\n    const u = unionAABB(boxes);\n    return u === null\n      ? null\n      : poseDescriptorForNode(descriptor, node).fromBounds(u, node.pose);\n  };\n}\n"],"mappings":";;;AAiBA,SAAgBA,EACd,GACqB;CACrB,QAAQ,GAAM,MAAS;EACrB,IAAMC,IAAQ,CAAC;EACf,KAAK,IAAMC,KAAKC,GACd,AAAID,MAAM,KAAA,KACRD,EAAM,KAAKG,EAA0BF,EAAE,MAAMG,EAAsBC,GAAYJ,CAAC,CAAC,CAAC;EAGtF,IAAMK,IAAIC,EAAUP,CAAK;EACzB,OAAOM,MAAM,OACT,OACAF,EAAsBC,GAAYG,CAAI,CAAC,CAAC,WAAWF,GAAGE,EAAK,IAAI;CACrE;AACF"}

package/dist/core/scene/unitScopes.js

@@ -0,0 +1,13 @@
+import { scopesOf as e } from "@weasel-js/quantity";
+//#region src/core/scene/unitScopes.ts
+function t(t, n, r, i = {}) {
+	return e(n, r, {
+		parentOf: (e) => t.get(e)?.parent,
+		scopeOf: (e) => t.get(e)?.units,
+		...i.inclusive ? { inclusive: !0 } : {}
+	});
+}
+//#endregion
+export { t as sceneUnitScopes };
+
+//# sourceMappingURL=unitScopes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unitScopes.js","names":["sceneUnitScopes","scopesOf","id","root","scene","at","opts"],"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,SAAgBA,EACd,GACA,GACA,GACA,IAAgC,CAAC,GACpB;CACb,OAAOC,EAASC,GAAIC,GAAM;EACxB,WAAW,MAAOC,EAAM,IAAIC,CAAE,CAAC,EAAE;EACjC,UAAU,MAAOD,EAAM,IAAIC,CAAE,CAAC,EAAE;EAChC,GAAIC,EAAK,YAAY,EAAE,WAAW,GAAK,IAAI,CAAC;CAC9C,CAAC;AACH"}

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

@@ -1 +1 @@
-{"version":3,"file":"useScene.js","names":["NEVER_SUBSCRIBE","DEFAULT_LAYER","isTrivialOptions","options","buildScene","createScene","item","asNodeId","useScene","sceneRef","useRef","scene","subscribed","useSyncExternalStore"],"sources":["../../../src/core/scene/useScene.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from 'react';\nimport { createScene } from './scene';\nimport type { NodeId, Scene, UseSceneOptions } from './types';\nimport { asNodeId } from './types';\n\n/** Trivial-form options: a flat list of items, no layers, no parenting. The\n *  full `useScene` form is reachable any time by adding `systemLayers`.\n *\n *  `historyLimit` and `generateId` are accepted because they're orthogonal to\n *  the \"what's in the scene\" question. `ops` is intentionally omitted — if\n *  you need custom ops, your app state already lives outside the \"flat list\n *  of rects\" frame and you should reach for the full `UseSceneOptions`. */\nexport interface UseSceneTrivialOptions<TItem extends { id: string }> {\n  items: readonly TItem[];\n  historyLimit?: number;\n  generateId?: () => NodeId;\n  /** Re-render the host on every scene mutation. Default `true`. See\n   *  {@link UseSceneOptions.subscribe}. */\n  subscribe?: boolean;\n}\n\n/** A subscribe function that never notifies. `useSyncExternalStore` still runs\n *  (hooks are unconditional) but the host is never re-rendered by the store. */\nconst NEVER_SUBSCRIBE = () => () => {};\n\nconst DEFAULT_LAYER = 'default' as const;\ntype DefaultLayer = typeof DEFAULT_LAYER;\n\nfunction isTrivialOptions<TItem extends { id: string }>(\n  options: unknown,\n): options is UseSceneTrivialOptions<TItem> {\n  return (\n    !!options\n    && typeof options === 'object'\n    && 'items' in (options as Record<string, unknown>)\n    && !('systemLayers' in (options as Record<string, unknown>))\n  );\n}\n\nfunction buildScene(options: unknown): Scene<unknown, string, unknown> {\n  if (!isTrivialOptions(options)) {\n    return createScene(options as UseSceneOptions<unknown, string, unknown>);\n  }\n  return createScene<unknown, DefaultLayer, unknown>({\n    systemLayers: [{ id: DEFAULT_LAYER }],\n    historyLimit: options.historyLimit,\n    generateId: options.generateId,\n    initial: options.items.map((item) => ({\n      kind: 'leaf',\n      layer: DEFAULT_LAYER,\n      pose: item,\n      data: item,\n      id: asNodeId(item.id),\n    })),\n  });\n}\n\n/** React hook returning a kit-owned `Scene`. The Scene is constructed once\n *  per host component and tracked via `useSyncExternalStore`, so React re-\n *  renders on every Scene mutation (including undo/redo) unless\n *  `subscribe: false` opts out.\n *\n *  Two call shapes:\n *  - **Trivial**: `useScene({ items })` — one auto-registered system layer\n *    named `'default'`, each item added as a leaf with `pose === data === item`.\n *    Cheapest path for \"a flat list of rects.\"\n *  - **Full**: `useScene({ systemLayers, initial?, ops?, ... })` — explicit\n *    layers, parenting, and custom op registration. */\nexport function useScene<TItem extends { id: string }>(\n  options: UseSceneTrivialOptions<TItem>,\n): Scene<TItem, DefaultLayer, TItem>;\n/** The full call shape: explicit layers, initial nodes, custom ops, and\n *  history configuration. */\nexport function useScene<TData, TLayer extends string, TPose = import('../../features/groups/composePose').RectPose>(\n  options: UseSceneOptions<TData, TLayer, TPose>,\n): Scene<TData, TLayer, TPose>;\n/** Create and subscribe to a scene. */\nexport function useScene(options: unknown): unknown {\n  const sceneRef = useRef<Scene<unknown, string, unknown> | null>(null);\n  if (sceneRef.current === null) sceneRef.current = buildScene(options);\n  const scene = sceneRef.current;\n  const subscribed = (options as { subscribe?: boolean } | null)?.subscribe !== false;\n  useSyncExternalStore(\n    subscribed ? scene.subscribe : NEVER_SUBSCRIBE,\n    scene.getVersion,\n    scene.getVersion,\n  );\n  return scene;\n}\n"],"mappings":";;;;AAuBA,IAAMA,gBAA8B,CAAC,GAE/BC,IAAgB;AAGtB,SAASC,EACP,GAC0C;CAC1C,OACE,CAAC,CAACC,KACC,OAAOA,KAAY,YACnB,WAAYA,KACZ,EAAE,kBAAmBA;AAE5B;AAEA,SAASC,EAAW,GAAmD;CAIrE,OAHKF,EAAiBC,CAAO,IAGtBE,EAA4C;EACjD,cAAc,CAAC,EAAE,IAAIJ,EAAc,CAAC;EACpC,cAAcE,EAAQ;EACtB,YAAYA,EAAQ;EACpB,SAASA,EAAQ,MAAM,KAAK,OAAU;GACpC,MAAM;GACN,OAAOF;GACP,MAAMK;GACN,MAAMA;GACN,IAAIC,EAASD,EAAK,EAAE;EACtB,EAAE;CACJ,CAAC,IAbQD,EAAYF,CAAoD;AAc3E;AAsBA,SAAgBK,EAAS,GAA2B;CAClD,IAAMC,IAAWC,EAA+C,IAAI;CACpE,AAAID,EAAS,YAAY,SAAM,EAAS,UAAUL,EAAWD,CAAO;CACpE,IAAMQ,IAAQF,EAAS,SACjBG,IAAcT,GAA4C,cAAc;CAM9E,OALAU,EACED,IAAaD,EAAM,YAAYX,GAC/BW,EAAM,YACNA,EAAM,UACR,GACOA;AACT"}
+{"version":3,"file":"useScene.js","names":["NEVER_SUBSCRIBE","DEFAULT_LAYER","isTrivialOptions","options","buildScene","createScene","item","asNodeId","useScene","sceneRef","useRef","scene","subscribed","useSyncExternalStore"],"sources":["../../../src/core/scene/useScene.ts"],"sourcesContent":["import { useRef, useSyncExternalStore } from 'react';\nimport { createScene } from './scene';\nimport type { NodeId, Scene, UseSceneOptions } from './types';\nimport { asNodeId } from './types';\n\n/** Trivial-form options: a flat list of items, no layers, no parenting. The\n *  full `useScene` form is reachable any time by adding `systemLayers`.\n *\n *  `historyLimit` and `generateId` are accepted because they're orthogonal to\n *  the \"what's in the scene\" question. `ops` is intentionally omitted — if\n *  you need custom ops, your app state already lives outside the \"flat list\n *  of rects\" frame and you should reach for the full `UseSceneOptions`. */\nexport interface UseSceneTrivialOptions<TItem extends { id: string }> {\n  items: readonly TItem[];\n  historyLimit?: number;\n  generateId?: () => NodeId;\n  /** Re-render the host on every scene mutation. Default `true`. See\n   *  {@link UseSceneOptions.subscribe}. */\n  subscribe?: boolean;\n}\n\n/** A subscribe function that never notifies. `useSyncExternalStore` still runs\n *  (hooks are unconditional) but the host is never re-rendered by the store. */\nconst NEVER_SUBSCRIBE = () => () => {};\n\nconst DEFAULT_LAYER = 'default' as const;\ntype DefaultLayer = typeof DEFAULT_LAYER;\n\nfunction isTrivialOptions<TItem extends { id: string }>(\n  options: unknown,\n): options is UseSceneTrivialOptions<TItem> {\n  return (\n    !!options\n    && typeof options === 'object'\n    && 'items' in (options as Record<string, unknown>)\n    && !('systemLayers' in (options as Record<string, unknown>))\n  );\n}\n\nfunction buildScene(options: unknown): Scene<unknown, string, unknown> {\n  if (!isTrivialOptions(options)) {\n    return createScene(options as UseSceneOptions<unknown, string, unknown>);\n  }\n  return createScene<unknown, DefaultLayer, unknown>({\n    systemLayers: [{ id: DEFAULT_LAYER }],\n    historyLimit: options.historyLimit,\n    generateId: options.generateId,\n    initial: options.items.map((item) => ({\n      kind: 'leaf',\n      layer: DEFAULT_LAYER,\n      pose: item,\n      data: item,\n      id: asNodeId(item.id),\n    })),\n  });\n}\n\n/** React hook returning a kit-owned `Scene`. The Scene is constructed once\n *  per host component and tracked via `useSyncExternalStore`, so React re-\n *  renders on every Scene mutation (including undo/redo) unless\n *  `subscribe: false` opts out.\n *\n *  Two call shapes:\n *  - **Trivial**: `useScene({ items })` — one auto-registered system layer\n *    named `'default'`, each item added as a leaf with `pose === data === item`.\n *    Cheapest path for \"a flat list of rects.\"\n *  - **Full**: `useScene({ systemLayers, initial?, ops?, ... })` — explicit\n *    layers, parenting, and custom op registration. */\nexport function useScene<TItem extends { id: string }>(\n  options: UseSceneTrivialOptions<TItem>,\n): Scene<TItem, DefaultLayer, TItem>;\n/** The full call shape: explicit layers, initial nodes, custom ops, and\n *  history configuration. */\nexport function useScene<TData, TLayer extends string, TPose = import('./composePose').RectPose>(\n  options: UseSceneOptions<TData, TLayer, TPose>,\n): Scene<TData, TLayer, TPose>;\n/** Create and subscribe to a scene. */\nexport function useScene(options: unknown): unknown {\n  const sceneRef = useRef<Scene<unknown, string, unknown> | null>(null);\n  if (sceneRef.current === null) sceneRef.current = buildScene(options);\n  const scene = sceneRef.current;\n  const subscribed = (options as { subscribe?: boolean } | null)?.subscribe !== false;\n  useSyncExternalStore(\n    subscribed ? scene.subscribe : NEVER_SUBSCRIBE,\n    scene.getVersion,\n    scene.getVersion,\n  );\n  return scene;\n}\n"],"mappings":";;;;AAuBA,IAAMA,gBAA8B,CAAC,GAE/BC,IAAgB;AAGtB,SAASC,EACP,GAC0C;CAC1C,OACE,CAAC,CAACC,KACC,OAAOA,KAAY,YACnB,WAAYA,KACZ,EAAE,kBAAmBA;AAE5B;AAEA,SAASC,EAAW,GAAmD;CAIrE,OAHKF,EAAiBC,CAAO,IAGtBE,EAA4C;EACjD,cAAc,CAAC,EAAE,IAAIJ,EAAc,CAAC;EACpC,cAAcE,EAAQ;EACtB,YAAYA,EAAQ;EACpB,SAASA,EAAQ,MAAM,KAAK,OAAU;GACpC,MAAM;GACN,OAAOF;GACP,MAAMK;GACN,MAAMA;GACN,IAAIC,EAASD,EAAK,EAAE;EACtB,EAAE;CACJ,CAAC,IAbQD,EAAYF,CAAoD;AAc3E;AAsBA,SAAgBK,EAAS,GAA2B;CAClD,IAAMC,IAAWC,EAA+C,IAAI;CACpE,AAAID,EAAS,YAAY,SAAM,EAAS,UAAUL,EAAWD,CAAO;CACpE,IAAMQ,IAAQF,EAAS,SACjBG,IAAcT,GAA4C,cAAc;CAM9E,OALAU,EACED,IAAaD,EAAM,YAAYX,GAC/BW,EAAM,YACNA,EAAM,UACR,GACOA;AACT"}

package/dist/core/selection/readOnlySelection.js

@@ -0,0 +1,32 @@
+//#region src/core/selection/readOnlySelection.ts
+var e = /* @__PURE__ */ new WeakMap(), t = /* @__PURE__ */ new WeakMap(), n = () => {};
+function r(t) {
+	let r = e.get(t);
+	return r || (r = {
+		getSelection: () => t.getSelection(),
+		setSelection: n
+	}, e.set(t, r)), r;
+}
+function i(e) {
+	let i = r(e.adapterMethods), a = t.get(e);
+	if (a && a.adapterMethods === i) return a;
+	let o = {
+		get current() {
+			return e.current;
+		},
+		get: e.get,
+		contains: e.contains,
+		set: n,
+		add: n,
+		remove: n,
+		toggle: n,
+		clear: n,
+		applyClick: n,
+		adapterMethods: i
+	};
+	return t.set(e, o), o;
+}
+//#endregion
+export { i as readOnlySelection };
+
+//# sourceMappingURL=readOnlySelection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"readOnlySelection.js","names":["methodViews","apiViews","ignore","readOnlyAdapterMethods","view","methods","readOnlySelection","adapterMethods","api","cached"],"sources":["../../../src/core/selection/readOnlySelection.ts"],"sourcesContent":["import type { SelectionApi } from './useSelection';\n\ntype AdapterMethods = SelectionApi['adapterMethods'];\n\nconst methodViews = new WeakMap<AdapterMethods, AdapterMethods>();\nconst apiViews = new WeakMap<SelectionApi, SelectionApi>();\n\nconst ignore = (): void => {};\n\nfunction readOnlyAdapterMethods(methods: AdapterMethods): AdapterMethods {\n  let view = methodViews.get(methods);\n  if (!view) {\n    view = { getSelection: () => methods.getSelection(), setSelection: ignore };\n    methodViews.set(methods, view);\n  }\n  return view;\n}\n\n/**\n * A view of `api` that reads the live selection and ignores every write.\n * `api` itself is untouched and still writes.\n *\n * One view per `api`, and one set of `adapterMethods` per `api.adapterMethods`,\n * so either is as stable a memo or effect dependency as the object it wraps.\n */\nexport function readOnlySelection(api: SelectionApi): SelectionApi {\n  const adapterMethods = readOnlyAdapterMethods(api.adapterMethods);\n  const cached = apiViews.get(api);\n  if (cached && cached.adapterMethods === adapterMethods) return cached;\n  const view: SelectionApi = {\n    get current() { return api.current; },\n    get: api.get,\n    contains: api.contains,\n    set: ignore,\n    add: ignore,\n    remove: ignore,\n    toggle: ignore,\n    clear: ignore,\n    applyClick: ignore,\n    adapterMethods,\n  };\n  apiViews.set(api, view);\n  return view;\n}\n"],"mappings":";AAIA,IAAMA,oBAAc,IAAI,QAAwC,GAC1DC,oBAAW,IAAI,QAAoC,GAEnDC,UAAqB,CAAC;AAE5B,SAASC,EAAuB,GAAyC;CACvE,IAAIC,IAAOJ,EAAY,IAAIK,CAAO;CAKlC,OAJKD,MACH,IAAO;EAAE,oBAAoBC,EAAQ,aAAa;EAAG,cAAcH;CAAO,GAC1EF,EAAY,IAAIK,GAASD,CAAI,IAExBA;AACT;AASA,SAAgBE,EAAkB,GAAiC;CACjE,IAAMC,IAAiBJ,EAAuBK,EAAI,cAAc,GAC1DC,IAASR,EAAS,IAAIO,CAAG;CAC/B,IAAIC,KAAUA,EAAO,mBAAmBF,GAAgB,OAAOE;CAC/D,IAAML,IAAqB;EACzB,IAAI,UAAU;GAAE,OAAOI,EAAI;EAAS;EACpC,KAAKA,EAAI;EACT,UAAUA,EAAI;EACd,KAAKN;EACL,KAAKA;EACL,QAAQA;EACR,QAAQA;EACR,OAAOA;EACP,YAAYA;EACZ;CACF;CAEA,OADAD,EAAS,IAAIO,GAAKJ,CAAI,GACfA;AACT"}