doxum 0.1.21 → 0.1.23

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import * as _$react from "react";
 import { DocumentReadable, DocumentSelector, HistoryState, Input, LocalHistory, ObjectNode, OperationResult, Projection, ProjectionRuntime, ProjectionScope, Readable } from "doxum";
+import * as _$react from "react";
 
 //#region react/src/hooks.d.ts
 declare const ProjectionProvider: _$react.Provider<ProjectionRuntime | ProjectionScope | undefined>;
@@ -8,7 +8,6 @@ declare function useProjection<T, R>(projection: Projection<T, unknown>, selecto
 declare function useInput<T>(input: Input<T>): readonly [T, (value: T) => void];
 type DocumentSelectorOptions<TResult> = {
   readonly isEqual?: (previous: TResult, next: TResult) => boolean;
-  readonly server?: () => TResult;
 };
 declare function useDocumentSelector<TSchema extends ObjectNode, TResult>(runtime: DocumentReadable<TSchema>, selector: DocumentSelector<TSchema, TResult>, options?: DocumentSelectorOptions<TResult>): TResult;
 declare function useReadable<T>(readable: Readable<T>): T;

package/dist/react.js

@@ -1,6 +1,5 @@
-import { c as subscribeDependencies, p as same } from "./notification-Bkjau6B6.js";
-import { t as track } from "./integration-C4Isp8lJ.js";
-import { createContext, useCallback, useContext, useMemo, useRef, useSyncExternalStore } from "react";
+import { select } from "doxum";
+import { createContext, useCallback, useContext, useMemo, useSyncExternalStore } from "react";
 //#region react/src/hooks.ts
 const ProjectionContext = createContext(void 0);
 const ProjectionProvider = ProjectionContext.Provider;
@@ -22,78 +21,12 @@ function useInput(input) {
 	return useMemo(() => [value, set], [set, value]);
 }
 const objectIs = (previous, next) => Object.is(previous, next);
-const sameTargets = (left, right) => {
-	if (left.length !== right.length) return false;
-	for (let index = 0; index < left.length; index += 1) if (!same(left[index], right[index])) return false;
-	return true;
-};
 function useDocumentSelector(runtime, selector, options) {
 	const equality = options?.isEqual ?? objectIs;
-	const cache = useRef(void 0);
-	const serverCache = useRef(void 0);
-	const read = useMemo(() => {
-		let snapshot;
-		return () => {
-			const revision = runtime.revision();
-			if (snapshot?.revision === revision) return snapshot.value;
-			const selection = track(runtime, selector);
-			const previous = cache.current;
-			const value = previous && previous.runtime === runtime && equality(previous.value, selection.value) ? previous.value : selection.value;
-			cache.current = {
-				runtime,
-				value,
-				targets: selection.targets
-			};
-			snapshot = {
-				revision,
-				value
-			};
-			return value;
-		};
-	}, [
+	return useReadable(useMemo(() => select(runtime, selector, equality), [
 		equality,
 		runtime,
 		selector
-	]);
-	const subscribe = useCallback((listener) => {
-		read();
-		let targets = cache.current?.targets ?? [];
-		let unsubscribe = () => void 0;
-		const install = () => {
-			if (targets.length === 0) return () => void 0;
-			return subscribeDependencies(runtime, targets, onCommit);
-		};
-		const onCommit = () => {
-			const previous = cache.current;
-			const next = read();
-			const nextTargets = cache.current?.targets ?? [];
-			if (!sameTargets(targets, nextTargets)) {
-				unsubscribe();
-				targets = nextTargets;
-				unsubscribe = install();
-			}
-			if (previous && !Object.is(previous.value, next)) listener();
-		};
-		unsubscribe = install();
-		return () => unsubscribe();
-	}, [read, runtime]);
-	const server = options?.server;
-	return useSyncExternalStore(subscribe, read, useCallback(() => {
-		const previous = serverCache.current;
-		if (previous && previous.source === server && previous.runtime === runtime && previous.selector === selector) return previous.value;
-		const value = server ? server() : read();
-		serverCache.current = {
-			runtime,
-			selector,
-			source: server,
-			value
-		};
-		return value;
-	}, [
-		read,
-		server,
-		runtime,
-		selector
 	]));
 }
 function useReadable(readable) {

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","names":["sameTarget"],"sources":["../react/src/hooks.ts"],"sourcesContent":["import type {\n  DocumentReadable,\n  ObjectNode,\n  DocumentSelector,\n  HistoryState,\n  LocalHistory,\n  OperationResult,\n  Readable,\n  ProjectionRuntime,\n  ProjectionScope,\n  Projection,\n  Input,\n} from 'doxum';\nimport { track, subscribeDependencies, sameTarget, type ImpactTarget } from 'doxum/integration';\nimport {\n  createContext,\n  useCallback,\n  useContext,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n} from 'react';\n\nconst ProjectionContext = createContext<ProjectionRuntime | ProjectionScope | undefined>(undefined);\nexport const ProjectionProvider = ProjectionContext.Provider;\n\nexport function useProjection<T>(projection: Projection<T, unknown>): T;\nexport function useProjection<T, R>(\n  projection: Projection<T, unknown>,\n  selector: (value: T) => R,\n  equality?: (previous: R, next: R) => boolean\n): R;\nexport function useProjection<T, R>(\n  projection: Projection<T, unknown>,\n  selector?: (value: T) => R,\n  equality: (previous: R, next: R) => boolean = Object.is\n): T | R {\n  const context = useContext(ProjectionContext);\n  const owner = context;\n  if (!owner) throw new Error('ProjectionRuntime is required.');\n  const readable = useMemo(\n    () => (selector ? owner.readable(projection, selector, equality) : owner.readable(projection)),\n    [equality, owner, projection, selector]\n  );\n  return useReadable(readable as Readable<T | R>);\n}\n\nexport function useInput<T>(input: Input<T>): readonly [T, (value: T) => void] {\n  const context = useContext(ProjectionContext);\n  const owner = context;\n  if (!owner) throw new Error('ProjectionRuntime is required.');\n  const value = useProjection(input);\n  const set = useCallback((next: T) => owner.set(input, next), [input, owner]);\n  return useMemo(() => [value, set] as const, [set, value]);\n}\n\nexport type DocumentSelectorOptions<TResult> = {\n  readonly isEqual?: (previous: TResult, next: TResult) => boolean;\n  readonly server?: () => TResult;\n};\n\ntype SelectorCache<TSchema extends ObjectNode, TResult> = {\n  readonly runtime: DocumentReadable<TSchema>;\n  readonly value: TResult;\n  readonly targets: readonly ImpactTarget<unknown>[];\n};\n\nconst objectIs = <T>(previous: T, next: T): boolean => Object.is(previous, next);\nconst sameTargets = (\n  left: readonly ImpactTarget<unknown>[],\n  right: readonly ImpactTarget<unknown>[]\n): boolean => {\n  if (left.length !== right.length) return false;\n  for (let index = 0; index < left.length; index += 1)\n    if (!sameTarget(left[index], right[index])) return false;\n  return true;\n};\n\nexport function useDocumentSelector<TSchema extends ObjectNode, TResult>(\n  runtime: DocumentReadable<TSchema>,\n  selector: DocumentSelector<TSchema, TResult>,\n  options?: DocumentSelectorOptions<TResult>\n): TResult {\n  const equality = options?.isEqual ?? objectIs;\n  const cache = useRef<SelectorCache<TSchema, TResult> | undefined>(undefined);\n  const serverCache = useRef<\n    | {\n        readonly runtime: DocumentReadable<TSchema>;\n        readonly selector: DocumentSelector<TSchema, TResult>;\n        readonly source: (() => TResult) | undefined;\n        readonly value: TResult;\n      }\n    | undefined\n  >(undefined);\n\n  const read = useMemo(() => {\n    // Each selector closure owns its revision cache, including inline selectors\n    // that allocate arrays or objects. Equality only compares distinct snapshots.\n    let snapshot: { readonly revision: number; readonly value: TResult } | undefined;\n    return (): TResult => {\n      const revision = runtime.revision();\n      if (snapshot?.revision === revision) return snapshot.value;\n      const selection = track(runtime, selector);\n      const previous = cache.current;\n      const value =\n        previous && previous.runtime === runtime && equality(previous.value, selection.value)\n          ? previous.value\n          : selection.value;\n      cache.current = { runtime, value, targets: selection.targets };\n      snapshot = { revision, value };\n      return value;\n    };\n  }, [equality, runtime, selector]);\n\n  const subscribe = useCallback(\n    (listener: () => void) => {\n      read();\n      let targets = cache.current?.targets ?? [];\n      let unsubscribe: () => void = () => undefined;\n      const install = () => {\n        if (targets.length === 0) return () => undefined;\n        return subscribeDependencies(runtime, targets, onCommit);\n      };\n      const onCommit = () => {\n        const previous = cache.current;\n        const next = read();\n        const nextTargets = cache.current?.targets ?? [];\n        if (!sameTargets(targets, nextTargets)) {\n          unsubscribe();\n          targets = nextTargets;\n          unsubscribe = install();\n        }\n        if (previous && !Object.is(previous.value, next)) listener();\n      };\n      unsubscribe = install();\n      return () => unsubscribe();\n    },\n    [read, runtime]\n  );\n\n  const server = options?.server;\n  const readServer = useCallback((): TResult => {\n    const previous = serverCache.current;\n    if (\n      previous &&\n      previous.source === server &&\n      previous.runtime === runtime &&\n      previous.selector === selector\n    )\n      return previous.value;\n    const value = server ? server() : read();\n    serverCache.current = { runtime, selector, source: server, value };\n    return value;\n  }, [read, server, runtime, selector]);\n\n  return useSyncExternalStore(subscribe, read, readServer);\n}\n\nexport function useReadable<T>(readable: Readable<T>): T {\n  const subscribe = useCallback((listener: () => void) => readable.subscribe(listener), [readable]);\n  const read = useCallback(() => readable.current(), [readable]);\n  return useSyncExternalStore(subscribe, read, read);\n}\n\nexport function useHistory<TCommit>(history: LocalHistory<TCommit>): HistoryState & {\n  undo(): OperationResult<TCommit>;\n  redo(): OperationResult<TCommit>;\n} {\n  const subscribe = useCallback((listener: () => void) => history.subscribe(listener), [history]);\n  const read = useCallback(() => history.current(), [history]);\n  const state = useSyncExternalStore(subscribe, read, read);\n  const undo = useCallback(() => history.undo(), [history]);\n  const redo = useCallback(() => history.redo(), [history]);\n\n  return useMemo(() => ({ ...state, undo, redo }), [redo, state, undo]);\n}\n"],"mappings":"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"}
+{"version":3,"file":"react.js","names":[],"sources":["../react/src/hooks.ts"],"sourcesContent":["import type {\n  DocumentReadable,\n  ObjectNode,\n  DocumentSelector,\n  HistoryState,\n  LocalHistory,\n  OperationResult,\n  Readable,\n  ProjectionRuntime,\n  ProjectionScope,\n  Projection,\n  Input,\n} from 'doxum';\nimport { select } from 'doxum';\nimport { createContext, useCallback, useContext, useMemo, useSyncExternalStore } from 'react';\n\nconst ProjectionContext = createContext<ProjectionRuntime | ProjectionScope | undefined>(undefined);\nexport const ProjectionProvider = ProjectionContext.Provider;\n\nexport function useProjection<T>(projection: Projection<T, unknown>): T;\nexport function useProjection<T, R>(\n  projection: Projection<T, unknown>,\n  selector: (value: T) => R,\n  equality?: (previous: R, next: R) => boolean\n): R;\nexport function useProjection<T, R>(\n  projection: Projection<T, unknown>,\n  selector?: (value: T) => R,\n  equality: (previous: R, next: R) => boolean = Object.is\n): T | R {\n  const context = useContext(ProjectionContext);\n  const owner = context;\n  if (!owner) throw new Error('ProjectionRuntime is required.');\n  const readable = useMemo(\n    () => (selector ? owner.readable(projection, selector, equality) : owner.readable(projection)),\n    [equality, owner, projection, selector]\n  );\n  return useReadable(readable as Readable<T | R>);\n}\n\nexport function useInput<T>(input: Input<T>): readonly [T, (value: T) => void] {\n  const context = useContext(ProjectionContext);\n  const owner = context;\n  if (!owner) throw new Error('ProjectionRuntime is required.');\n  const value = useProjection(input);\n  const set = useCallback((next: T) => owner.set(input, next), [input, owner]);\n  return useMemo(() => [value, set] as const, [set, value]);\n}\n\nexport type DocumentSelectorOptions<TResult> = {\n  readonly isEqual?: (previous: TResult, next: TResult) => boolean;\n};\n\nconst objectIs = <T>(previous: T, next: T): boolean => Object.is(previous, next);\n\nexport function useDocumentSelector<TSchema extends ObjectNode, TResult>(\n  runtime: DocumentReadable<TSchema>,\n  selector: DocumentSelector<TSchema, TResult>,\n  options?: DocumentSelectorOptions<TResult>\n): TResult {\n  const equality = options?.isEqual ?? objectIs;\n  const readable = useMemo(\n    () => select(runtime, selector, equality),\n    [equality, runtime, selector]\n  );\n  return useReadable(readable);\n}\n\nexport function useReadable<T>(readable: Readable<T>): T {\n  const subscribe = useCallback((listener: () => void) => readable.subscribe(listener), [readable]);\n  const read = useCallback(() => readable.current(), [readable]);\n  return useSyncExternalStore(subscribe, read, read);\n}\n\nexport function useHistory<TCommit>(history: LocalHistory<TCommit>): HistoryState & {\n  undo(): OperationResult<TCommit>;\n  redo(): OperationResult<TCommit>;\n} {\n  const subscribe = useCallback((listener: () => void) => history.subscribe(listener), [history]);\n  const read = useCallback(() => history.current(), [history]);\n  const state = useSyncExternalStore(subscribe, read, read);\n  const undo = useCallback(() => history.undo(), [history]);\n  const redo = useCallback(() => history.redo(), [history]);\n\n  return useMemo(() => ({ ...state, undo, redo }), [redo, state, undo]);\n}\n"],"mappings":";;;AAgBA,MAAM,oBAAoB,cAA+D,KAAA,EAAU;AACnG,MAAa,qBAAqB,kBAAkB;AAQpD,SAAgB,cACd,YACA,UACA,WAA8C,OAAO,IAC9C;CAEP,MAAM,QADU,WAAW,kBACN;AACrB,KAAI,CAAC,MAAO,OAAM,IAAI,MAAM,iCAAiC;AAK7D,QAAO,YAJU,cACR,WAAW,MAAM,SAAS,YAAY,UAAU,SAAS,GAAG,MAAM,SAAS,WAAW,EAC7F;EAAC;EAAU;EAAO;EAAY;EAAS,CAEd,CAAoB;;AAGjD,SAAgB,SAAY,OAAmD;CAE7E,MAAM,QADU,WAAW,kBACN;AACrB,KAAI,CAAC,MAAO,OAAM,IAAI,MAAM,iCAAiC;CAC7D,MAAM,QAAQ,cAAc,MAAM;CAClC,MAAM,MAAM,aAAa,SAAY,MAAM,IAAI,OAAO,KAAK,EAAE,CAAC,OAAO,MAAM,CAAC;AAC5E,QAAO,cAAc,CAAC,OAAO,IAAI,EAAW,CAAC,KAAK,MAAM,CAAC;;AAO3D,MAAM,YAAe,UAAa,SAAqB,OAAO,GAAG,UAAU,KAAK;AAEhF,SAAgB,oBACd,SACA,UACA,SACS;CACT,MAAM,WAAW,SAAS,WAAW;AAKrC,QAAO,YAJU,cACT,OAAO,SAAS,UAAU,SAAS,EACzC;EAAC;EAAU;EAAS;EAAS,CAEJ,CAAC;;AAG9B,SAAgB,YAAe,UAA0B;CACvD,MAAM,YAAY,aAAa,aAAyB,SAAS,UAAU,SAAS,EAAE,CAAC,SAAS,CAAC;CACjG,MAAM,OAAO,kBAAkB,SAAS,SAAS,EAAE,CAAC,SAAS,CAAC;AAC9D,QAAO,qBAAqB,WAAW,MAAM,KAAK;;AAGpD,SAAgB,WAAoB,SAGlC;CACA,MAAM,YAAY,aAAa,aAAyB,QAAQ,UAAU,SAAS,EAAE,CAAC,QAAQ,CAAC;CAC/F,MAAM,OAAO,kBAAkB,QAAQ,SAAS,EAAE,CAAC,QAAQ,CAAC;CAC5D,MAAM,QAAQ,qBAAqB,WAAW,MAAM,KAAK;CACzD,MAAM,OAAO,kBAAkB,QAAQ,MAAM,EAAE,CAAC,QAAQ,CAAC;CACzD,MAAM,OAAO,kBAAkB,QAAQ,MAAM,EAAE,CAAC,QAAQ,CAAC;AAEzD,QAAO,eAAe;EAAE,GAAG;EAAO;EAAM;EAAM,GAAG;EAAC;EAAM;EAAO;EAAK,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",
@@ -31,11 +31,6 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./integration": {
-      "types": "./dist/integration.d.ts",
-      "import": "./dist/integration.js",
-      "require": "./dist/integration.cjs"
-    },
     "./local-sync": {
       "types": "./dist/local-sync.d.ts",
       "import": "./dist/local-sync.js",

package/skills/doxum-runtime/SKILL.md

@@ -24,6 +24,11 @@ Before runtime changes read [invariants](references/invariants.en.md) or
   object or variant members whose Draft type contains collection tools.
 - Ordered table/list Drafts use move(key | readonly key[], anchor?) for relative
   movement and reorder(keys) for an exact full-membership permutation.
+- Trees may be empty. `tree(field(...))` requires every existing node to own `value`;
+  use `tree(optional(field(...)))` only when node payload absence is part of the model.
+  `optional(tree(...))` controls whole-tree presence independently.
+- Tree projection paths reuse ordinary source protocols: `tree.rootId` is scalar,
+  `tree.nodes` is keyed, and `tree.nodes.item(id)` is a single-node value.
 - Expected business failure throws TransactionRejected. Other exceptions roll back
   and rethrow unchanged. Callback returns carry business values and notices.
 - Commits contain final reversible ChangeSets. History and impact share those facts.
@@ -39,7 +44,8 @@ Before runtime changes read [invariants](references/invariants.en.md) or
   automatically; React selectors do through `ProjectionProvider` and
   `useProjection(projection, selector)`.
 - Observer errors leave commits accepted. Do not retry as if they rolled back.
-- Core stays framework-neutral; adapters use integration capabilities.
+- Core stays framework-neutral; adapters consume standard `Readable`,
+  document `select`, and projection readables without internal target/address protocols.
 - Local sync owns browser persistence/leadership. Network conflict policy and
   collaborative undo belong at a separate boundary.
 

package/skills/doxum-runtime/references/guide.en.md

@@ -3,7 +3,7 @@
 ## Define, Update And Read
 
 ```ts
-import { createDocument, field, map, object, select, snapshot, type Infer } from 'doxum';
+import { createDocument, field, map, object, read, snapshot, type Infer } from 'doxum';
 
 const task = object({ title: field<string>(), done: field<boolean>() });
 const model = object({ tasks: map(task) });
@@ -18,8 +18,8 @@ document.update(draft => {
   draft.tasks.put('b', { title: 'Review', done: false });
   return { warnings: [] };
 });
-const done = select(document, state => state.tasks.get('a')?.done);
-const tasks = select(document, state => snapshot(state.tasks));
+const done = read(document, state => state.tasks.get('a')?.done);
+const tasks = read(document, state => snapshot(state.tasks));
 document.subscribe(
   path => path.tasks.item('a').done,
   commit => console.log(commit.changes)
@@ -27,8 +27,8 @@ document.subscribe(
 ```
 
 Root object is definition identity; runtime owns its data/revision. Updates are
-synchronous and atomic. Reads see preceding writes. Draft and trusted internal
-readWith scopes are borrowed for the synchronous callback and must not escape.
+synchronous and atomic. Reads see preceding writes. Draft and the Read passed to a
+`read` selector are borrowed for the synchronous callback and must not escape.
 Throw TransactionRejected for expected rejection; ordinary throws
 restore all work and rethrow unchanged. False/undefined returns are business values.
 
@@ -66,6 +66,9 @@ present undefined. Variant tags are readonly; change branch by whole replacement
 For table/list, `move(key | readonly key[], anchor?)` preserves a moved selection's
 current relative order and resolves the anchor after removal. `reorder(keys)` requires
 an exact permutation of current membership and changes only order.
+Trees may be empty. `tree(field(...))` requires an own `value` on every existing
+node; `tree(optional(field(...)))` explicitly permits missing node payloads, while
+`optional(tree(...))` independently permits the whole tree member to be absent.
 
 Pure synchronous functions and Standard Schema v1 validators receive original input.
 They must not mutate it; successful output is ignored, with no copy or deep conversion
@@ -73,7 +76,9 @@ check. Transform values before entering Doxum. parse(model, unknown) copies vali
 structure and shares readonly payloads; strict parse requires atomic validators.
 Branded map/table keys flow through methods, symbolic paths and impact.
 Path callbacks describe locations, including absent entries, and compile at registration.
-React useDocumentSelector tracks actual reads and changes dependencies when branching.
+Core `select(document, selector, equality?)` tracks actual reads, changes dependencies
+when branching, and returns a standard `Readable`. React `useDocumentSelector`
+only adapts that Core readable to React.
 
 ## Changes And Consumers
 
@@ -97,6 +102,12 @@ remain explicit. Retained state, reverse indexes and keyed output patches belong
 the isolated `doxum/advanced` incremental entry points. See the [projection
 reference](projections.en.md) for lifecycle, draft semantics, selector tracking,
 batching and recovery.
+Tree structure uses the same projection source protocols: observe `path.tree.rootId`
+as a scalar, `path.tree.nodes` as a keyed collection, or
+`path.tree.nodes.item(id)` as a single node. Committed tree-node groups route directly
+to affected keyed entries and the existing `CollectionOutput` publishes ordinary
+`CollectionChange` entries; unrelated nodes keep stable snapshot references instead
+of being resnapshotted.
 `input` and `observe(source)` connect external boundary values, including
 eventful value and collection sources. Dispose the
 Runtime with the owning service. `runtime.batch` defers projection settlement and

package/skills/doxum-runtime/references/guide.zh-CN.md

@@ -3,7 +3,7 @@
 ## 定义、修改与读取
 
 ```ts
-import { createDocument, field, map, object, select, snapshot, type Infer } from 'doxum';
+import { createDocument, field, map, object, read, snapshot, type Infer } from 'doxum';
 
 const task = object({ title: field<string>(), done: field<boolean>() });
 const model = object({ tasks: map(task) });
@@ -18,8 +18,8 @@ document.update(draft => {
   draft.tasks.put('b', { title: 'Review', done: false });
   return { warnings: [] };
 });
-const done = select(document, state => state.tasks.get('a')?.done);
-const tasks = select(document, state => snapshot(state.tasks));
+const done = read(document, state => state.tasks.get('a')?.done);
+const tasks = read(document, state => snapshot(state.tasks));
 document.subscribe(
   path => path.tasks.item('a').done,
   commit => console.log(commit.changes)
@@ -27,7 +27,7 @@ document.subscribe(
 ```
 
 根 object 是定义身份，runtime 拥有状态与 revision。事务同步且原子，修改立即可读。
-Draft 和内部 readWith 是同步回调内的借用视图，不得逃逸。预期拒绝抛 TransactionRejected；普通异常完整恢复后
+Draft 和 `read` selector 接收的 Read 是同步回调内的借用视图，不得逃逸。预期拒绝抛 TransactionRejected；普通异常完整恢复后
 原样抛出。正常返回 false/undefined 是业务结果，不表示拒绝。
 
 object 暴露可编辑成员；field 是原子值，包括对象和数组。Infer 与作用域内原子值深只读；
@@ -58,12 +58,17 @@ table/list/tree 的 `replace(id, value)` 只替换已存在成员，保持 table
 table/list 的 `move(key | readonly key[], anchor?)` 会保持 moved selection 当前的相对顺序，
 并在移除 selection 后解析 anchor；`reorder(keys)` 要求与当前 membership 完全一致的排列，
 只改变顺序而不改变成员值。
+tree 可以为空。`tree(field(...))` 要求每个已存在节点都拥有自己的 `value`；只有
+`tree(optional(field(...)))` 才允许节点缺失 payload，而 `optional(tree(...))` 独立控制整棵
+tree 成员是否可以缺失。
 
 校验器是纯同步函数或 Standard Schema v1，直接接收原始引用且不得修改它。
 成功返回值被忽略，不复制输入，也不深度检查转换；数据转换在进入 Doxum 前完成。
 parse(model, unknown) 复制校验后的结构并共享只读 payload；严格解析要求原子字段具备校验器。品牌键贯穿 map/table 方法、
 符号路径和 impact。路径回调描述地址，包括缺失键，订阅注册时解析。
-React useDocumentSelector 追踪实际读取，并在选择分支改变时更新依赖。
+Core 的 `select(document, selector, equality?)` 追踪实际读取，在选择分支改变时更新
+依赖，并返回标准 `Readable`；React 的 `useDocumentSelector` 只负责把这个 Core
+readable 接到 React。
 
 ## 变化与消费者
 
@@ -83,6 +88,11 @@ observerErrors 属于已提交结果。
 `createProjectionRuntime({ onError })` owner 物化和管理。保留状态、反向索引和
 keyed patch 放在隔离的 `doxum/advanced` incremental 入口。生命周期、draft、
 selector 追踪、batch 与故障恢复见 [Projection 参考](projections.zh-CN.md)。
+tree 结构复用同一套 projection source 协议：`path.tree.rootId` 是 scalar，
+`path.tree.nodes` 是 keyed collection，`path.tree.nodes.item(id)` 是单节点 value。
+committed tree node group 直接路由到受影响的 keyed entry，由现有
+`CollectionOutput` 发布普通 `CollectionChange`；未变化节点保持稳定的 snapshot
+引用，不再因单节点变化而全部重新 snapshot。
 `input` 与 `observe(source)` 接入外部边界值，包括带事件的 value 和 collection
 source。随所属服务 dispose Runtime。
 `runtime.batch` 推迟投影结算与通知，但不推迟文档提交和文档通知；内部读取上次发布值，

package/skills/doxum-runtime/references/invariants.en.md

@@ -24,9 +24,11 @@
    original inputs and must be pure; successful output is ignored.
 6. List identity is a stable key; replacement retains it. Anchor owns ordering.
    Tree owns reciprocal, connected, acyclic, empty-or-single-root topology.
-7. ObjectNode owns schema identity; runtime owns instance identity. Shared path compiler
-   and impact-target own addressing/identity/equality/bucketing and exact matching, including React.
-   Notification matches grouped changes directly without building commit impact indexes.
+7. ObjectNode owns schema identity; one RuntimeContext owns instance identity for the
+   runtime, history and read-only aliases. The shared path compiler and Core impact target
+   algorithms own addressing/identity/equality/bucketing and exact matching. React sees
+   only Readable/select contracts. Notification matches grouped changes directly without
+   building commit impact indexes.
 8. Apply requires expectedRevision and captures actual local old state. Local reset is
    reversible; remote commits invalidate history. Groups travel in one session.
 9. Projections declare sources and settle before listeners. Notification failures leave

package/skills/doxum-runtime/references/invariants.zh-CN.md

@@ -18,9 +18,10 @@
    校验器直接读取原始输入，必须纯同步，成功返回值被忽略。
 6. list 以稳定键标记身份，替换值必须保留键。anchor 拥有排序语义；
    tree 拥有双向一致、连通、无环、空树或单根的拓扑约束。
-7. ObjectNode 拥有定义身份，runtime 拥有实例身份；共享路径 compiler 和
-   impact-target 拥有寻址、身份、相等、分桶和精确匹配，React 也遵守此边界。
-   通知直接匹配分组变化，不构建 commit impact 索引。
+7. ObjectNode 拥有定义身份；runtime、history 和只读 alias 共享唯一 RuntimeContext
+   实例身份。共享路径 compiler 与 Core impact target 算法拥有寻址、身份、相等、
+   分桶和精确匹配；React 只消费 Readable/select 契约。通知直接匹配分组变化，
+   不构建 commit impact 索引。
 8. apply 要求 expectedRevision，记录本地真实旧状态。本地 reset 可撤销，
    remote commit 使 history 失效；group 在单个 session 中旅行。
 9. projection 显式声明 source，先于监听结算。通知失败不撤销提交；

package/skills/doxum-runtime/references/projections.en.md

@@ -25,6 +25,11 @@ sources use `kind: 'value'` or `kind: 'collection'`; the caller still uses only
 Schema maps, tables, and `list(field, { keyOf })` nodes are all keyed collection
 paths. A list uses its schema `keyOf` identity and preserves document order in
 iteration; array-valued fields remain scalar value observations.
+Tree structure reuses the same source kinds: `path.tree.rootId` is a scalar,
+`path.tree.nodes` is a keyed collection, and `path.tree.nodes.item(id)` is a
+single-node value. Committed tree-node groups route directly to affected keyed
+entries, and the existing `CollectionOutput` publishes ordinary `CollectionChange`
+entries, so unrelated node snapshots keep their identity.
 
 External events are smaller than Runtime contexts. A value event carries the new
 `value` and `revision`; a collection event carries a stable `previous` read,

package/skills/doxum-runtime/references/projections.zh-CN.md

@@ -23,6 +23,11 @@ source 通过 `kind: 'value'` 或 `kind: 'collection'` 区分语义，但调用
 schema map、table 和 `list(field, { keyOf })` 都是 keyed collection path。list
 直接使用 schema 的 `keyOf` 作为稳定 identity，并按文档顺序迭代；数组类型的普通
 `field(...)` 仍然是 scalar value observation。
+tree 结构复用相同的 source 类型：`path.tree.rootId` 是 scalar，
+`path.tree.nodes` 是 keyed collection，`path.tree.nodes.item(id)` 是单节点 value。
+tree 的 committed node group 直接路由到受影响的 keyed entry，由现有
+`CollectionOutput` 生成普通 `CollectionChange`；未变化节点的 snapshot identity
+保持稳定。
 
 External event 不再复用 Runtime context：value event 提供新 `value` 和
 `revision`；collection event 提供稳定的 `previous` read、`revision` 和可选的