doxum 0.1.21 → 0.1.23

package/README.md

@@ -60,10 +60,14 @@ Committed observer failures are returned in `observerErrors` without rollback.
 ## Read And Observe
 
 ```ts
-import { read, snapshot } from 'doxum';
+import { read, select, snapshot } from 'doxum';
 
 const title = read(document, state => state.title);
 const tasks = read(document, state => snapshot(state.tasks));
+const selectedTitle = select(document, state => state.title);
+const stop = selectedTitle.subscribe(() => {
+  console.log(selectedTitle.current());
+});
 document.subscribe(
   path => path.tasks.item('b').title,
   commit => {
@@ -81,6 +85,10 @@ supported types, while classes/functions need application-specific handling.
 Use ordinary properties for fine-grained reads. Data callbacks read real values;
 path callbacks describe symbolic schema locations, including missing entries.
 Subscription paths compile once during registration.
+`select(document, selector, equality?)` returns a standard `Readable`. Core
+tracks exactly the document locations read by the selector, rebinds dependencies
+when selector branches change, and preserves the previous selected reference and
+publication revision when `equality` reports no result change.
 
 React integration:
 
@@ -91,9 +99,10 @@ const title = useDocumentSelector(document, state => state.title);
 const history = useHistory(document.history);
 ```
 
-React tracks fields actually read and updates dependencies when the selector
-branches. The core has no React dependency. `asReadable(document)` removes write
-capabilities while retaining selection, subscription and projection support.
+Document dependency tracking belongs to Core's `select`; the React adapter only
+subscribes to the resulting `Readable`. The core has no React dependency.
+`asReadable(document)` removes write capabilities while retaining selection,
+subscription and projection support.
 
 ## Containers And Parsing
 
@@ -116,6 +125,12 @@ Doxum; it does not detect validator mutation or conversion. `parse(model, unknow
 validates and copies schema structure while sharing readonly payloads. Strict parsing
 requires validators for atomic fields; typed in-memory fields can omit them.
 
+A tree may be empty, but payload presence follows the payload field schema exactly.
+`tree(field<T>())` requires every existing node to own a `value` property;
+`tree(optional(field<T>()))` is the explicit sparse-payload form. This is independent
+from `optional(tree(...))`, which controls whether the whole tree member may be absent.
+Missing and present-`undefined` payloads remain distinct when the payload field is optional.
+
 Ordered table/list drafts accept either one key or a key selection in
 `move(key | readonly key[], anchor?)`. A selection is moved as one block while
 preserving its current canonical relative order; the anchor is resolved after the
@@ -277,8 +292,21 @@ runtime.update(overrides, draft => {
 and eventful external sources. External sources declare `kind: 'value'` or
 `kind: 'collection'`; collection invalidation remains keyed internally. Schema
 `map`, `table`, and `list(field, { keyOf })` paths are all observed as keyed
-collection projections. A schema `list` uses its `keyOf` identity and publishes
-in document order; ordinary array-valued `field(...)` nodes remain scalar values.
+collection projections. Trees expose structural observation without a second
+projection protocol: `path.tree.rootId` is a scalar source,
+`path.tree.nodes` is a keyed collection source, and
+`path.tree.nodes.item(id)` is a single-node value source. A schema `list` uses its
+`keyOf` identity and publishes in document order; ordinary array-valued `field(...)`
+nodes remain scalar values.
+
+Document projection sources route committed groups directly to their observed
+targets, merge affected locations for the current projection batch, then combine the
+previously published snapshot with the canonical final value. A touched tree node
+replaces only that node structure and the necessary ancestor containers; unchanged
+tree-node snapshots keep their identity. Whole aggregate tree values still use the
+public `{ rootId?, nodes: Record }` shape, so changing a node may shallow-copy the
+`nodes` record, while native `tree.nodes` observation remains keyed and touches only
+changed nodes.
 
 For retained state, reverse indexes and keyed patches, use the isolated advanced
 entry point. Whole-value processors use `incremental(...)`; keyed collection
@@ -376,7 +404,7 @@ It also reports structural generation advances and distinguishes captured order
 baselines from final published order copies. Architecture workloads include order
 round trips and repeated tree edits to expose costs hidden by commit-only benchmarks.
 
-Builds produce root `dist` ESM/CJS/declarations for `doxum`, `doxum/integration`,
+Builds produce root `dist` ESM/CJS/declarations for `doxum`,
 `doxum/local-sync`, `doxum/react` and `doxum/advanced`. Source ownership is described in
 [architecture](docs/architecture.md) and [AGENTS.md](AGENTS.md).
 The runtime shares one transaction lifecycle; complete mutation operations are

package/dist/{advanced-FgdTwu5b.d.ts → advanced-CLJCWkHa.d.cts}

@@ -1,4 +1,4 @@
-import { J as Infer, L as CollectionId, R as CollectionNode, Z as ObjectNode, _ as Unsubscribe, et as PathValueOf, m as Synchronous, nt as SchemaPath, s as DocumentReadable, tt as ReadonlyValue, v as Readable, x as CollectionImpact, z as CollectionPath } from "./contract-KG5XnQZt.js";
+import { F as CollectionPath, K as ObjectNode, N as CollectionEntry, P as CollectionId, U as Infer, X as ReadonlyValue, Y as PathValueOf, Z as SchemaPath, _ as Unsubscribe, b as CollectionImpact, g as Readable, o as DocumentReadable, p as Synchronous } from "./contract-SYJFP0lM.cjs";
 
 //#region core/src/projection/contract.d.ts
 /** The one processor-facing collection transition protocol. */
@@ -98,7 +98,7 @@ declare function observe<S extends ObjectNode>(document: DocumentReadable<S>): P
 declare function observe<T>(source: ExternalValueSource<T>): Projection<T>;
 declare function observe<K extends string, V>(source: ExternalCollectionSource<K, V>): Projection<ReadonlyMap<K, V>, CollectionChange<K, V>>;
 declare function observe<T>(readable: Readable<T>): Projection<T>;
-declare function observe<S extends ObjectNode, P extends CollectionPath>(document: DocumentReadable<S>, selector: (path: SchemaPath<S['shape']>) => P): Projection<ReadonlyMap<CollectionId<P>, ReadonlyValue<Infer<CollectionNode<P>>>>, CollectionChange<CollectionId<P>, ReadonlyValue<Infer<CollectionNode<P>>>>>;
+declare function observe<S extends ObjectNode, P extends CollectionPath>(document: DocumentReadable<S>, selector: (path: SchemaPath<S['shape']>) => P): Projection<ReadonlyMap<CollectionId<P>, ReadonlyValue<CollectionEntry<P>>>, CollectionChange<CollectionId<P>, ReadonlyValue<CollectionEntry<P>>>>;
 declare function observe<S extends ObjectNode, P>(document: DocumentReadable<S>, selector: (path: SchemaPath<S['shape']>) => P): Projection<PathValueOf<P>>;
 declare function derive<const D extends readonly Projection<unknown, unknown>[], T>(dependencies: D, compute: (...values: ProjectionValues$1<D>) => Synchronous<T>, equality?: (previous: T, next: T) => boolean): Projection<T>;
 //#endregion
@@ -173,4 +173,4 @@ declare const incremental: typeof createIncrementalValue & {
 };
 //#endregion
 export { ProjectionError as C, ProjectionDisposedError as S, ExternalCollectionEvent as _, IncrementalGroupDefine as a, ExternalValueEvent as b, IncrementalValueContext as c, Input as d, Projection as f, CollectionChange as g, observe as h, IncrementalGroupContext as i, IncrementalValueProcessor as l, input as m, IncrementalCollectionContext as n, IncrementalGroupOutputTree as o, derive as p, IncrementalCollectionProcessor as r, IncrementalGroupProcessor as s, GroupProjections as t, incremental as u, ExternalCollectionRead as v, ExternalValueSource as x, ExternalCollectionSource as y };
-//# sourceMappingURL=advanced-FgdTwu5b.d.ts.map
+//# sourceMappingURL=advanced-CLJCWkHa.d.cts.map