dirvi-lib 0.11.0-beta.5 → 0.11.0-beta.7

package/dist/state-and-nav/tree/tree-node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.test.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree-node.test.ts"],"names":[],"mappings":""}

package/dist/state-and-nav/tree/tree-node.test.js

@@ -0,0 +1,234 @@
+import { describe, expect, it, vi } from 'vitest';
+import * as fc from 'fast-check';
+import { createTreeMethods } from './tree.impl.js';
+import { childrenStateModelArb, modelAndBranchPathArb, modelAndReachablePathArb, } from './tree-node.arb.js';
+const api = createTreeMethods();
+/**
+ * Fail rather than silently skipping assertions when an operation that should
+ * succeed returns undefined.
+ */
+function requireDefined(value) {
+    if (value === undefined) {
+        throw new Error('Expected a defined result');
+    }
+    return value;
+}
+function fromModel(model) {
+    return requireDefined(api.fromModel(model));
+}
+function loadedBranch(id, children) {
+    return requireDefined(api.createLoadedBranch(id, 0, children));
+}
+describe('findChildById', () => {
+    it('returns the existing matching direct child', () => {
+        const child = api.createLeaf('child', 1);
+        const root = loadedBranch('root', [child]);
+        expect(api.findChildById(root, 'child')).toBe(child);
+    });
+    it('does not search descendants', () => {
+        const descendant = api.createLeaf('descendant', 1);
+        const child = loadedBranch('child', [descendant]);
+        const root = loadedBranch('root', [child]);
+        expect(api.findChildById(root, 'descendant')).toBeUndefined();
+    });
+    it.each([
+        {
+            name: 'an empty loaded branch',
+            root: loadedBranch('root', []),
+        },
+        {
+            name: 'a leaf',
+            root: api.createLeaf('root', 0),
+        },
+        {
+            name: 'an unloaded branch',
+            root: api.createUnloadedBranch('root', 0),
+        },
+    ])('returns undefined for a missing child in $name', ({ root }) => {
+        expect(api.findChildById(root, 'missing')).toBeUndefined();
+    });
+});
+describe('findAtPath and selectAtPath', () => {
+    it('resolves generated reachable paths', () => {
+        fc.assert(fc.property(modelAndReachablePathArb, ({ root: rootModel, path, expected }) => {
+            const root = fromModel(rootModel);
+            const selected = requireDefined(api.findAtPath(root, path));
+            expect(api.toModel(selected)).toStrictEqual(expected);
+            expect(api.selectAtPath(root, path, (node) => node)).toBe(selected);
+            expect(api.selectAtPath(root, path, (node) => api.id(node))).toBe(expected.id);
+        }));
+    });
+    it('calls the selector once with the existing resolved node', () => {
+        const child = api.createLeaf('child', 1);
+        const root = loadedBranch('root', [child]);
+        const selector = vi.fn((node) => api.id(node));
+        expect(api.selectAtPath(root, ['child'], selector)).toBe('child');
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(child);
+    });
+    it('resolves the root for an empty path', () => {
+        const root = api.createLeaf('root', 0);
+        const selector = vi.fn((node) => node);
+        expect(api.findAtPath(root, [])).toBe(root);
+        expect(api.selectAtPath(root, [], selector)).toBe(root);
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(root);
+    });
+    it.each([
+        {
+            name: 'a missing child',
+            root: loadedBranch('root', []),
+            path: ['missing'],
+        },
+        {
+            name: 'a missing descendant',
+            root: loadedBranch('root', [loadedBranch('child', [])]),
+            path: ['child', 'missing'],
+        },
+        {
+            name: 'a path through a leaf',
+            root: loadedBranch('root', [api.createLeaf('child', 1)]),
+            path: ['child', 'descendant'],
+        },
+        {
+            name: 'a path through an unloaded branch',
+            root: loadedBranch('root', [api.createUnloadedBranch('child', 1)]),
+            path: ['child', 'descendant'],
+        },
+    ])('returns undefined for $name without calling the selector', ({ root, path }) => {
+        const selector = vi.fn((node) => node);
+        expect(api.findAtPath(root, path)).toBeUndefined();
+        expect(api.selectAtPath(root, path, selector)).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
+    });
+    it('returns undefined when the selector returns undefined', () => {
+        const root = api.createLeaf('root', 0);
+        const selector = vi.fn((_node) => undefined);
+        expect(api.selectAtPath(root, [], selector)).toBeUndefined();
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(root);
+    });
+});
+describe('updateAtPath', () => {
+    it('replaces a generated node without changing the original tree', () => {
+        fc.assert(fc.property(modelAndReachablePathArb, ({ root: rootModel, path, expected }) => {
+            const root = fromModel(rootModel);
+            const originalNode = requireDefined(api.findAtPath(root, path));
+            const replacement = api.createLeaf(expected.id, expected.value);
+            const updatedRoot = requireDefined(api.updateAtPath(root, path, () => replacement));
+            expect(api.findAtPath(updatedRoot, path)).toBe(replacement);
+            expect(api.findAtPath(root, path)).toBe(originalNode);
+            expect(api.toModel(root)).toStrictEqual(rootModel);
+        }));
+    });
+    it('replaces child loading state at a generated branch path', () => {
+        fc.assert(fc.property(modelAndBranchPathArb, childrenStateModelArb, ({ root: rootModel, path, expected }, newChildren) => {
+            const root = fromModel(rootModel);
+            const originalNode = requireDefined(api.findAtPath(root, path));
+            const updatedRoot = requireDefined(api.updateAtPath(root, path, (node) => newChildren === null
+                ? api.toUnloadedBranch(node)
+                : api.withLoadedChildren(node, newChildren.map(fromModel))));
+            const updatedNode = requireDefined(api.findAtPath(updatedRoot, path));
+            expect(updatedNode).not.toBe(originalNode);
+            expect(api.toModel(updatedNode)).toStrictEqual({
+                id: expected.id,
+                value: expected.value,
+                children: newChildren,
+            });
+            expect(api.findAtPath(root, path)).toBe(originalNode);
+            expect(api.toModel(root)).toStrictEqual(rootModel);
+        }));
+    });
+    it('calls the updater once and preserves position when the ID changes', () => {
+        const before = api.createLeaf('before', 1);
+        const child = api.createLeaf('child', 2);
+        const after = api.createLeaf('after', 3);
+        const root = loadedBranch('root', [before, child, after]);
+        const replacement = api.createLeaf('replacement', 4);
+        const update = vi.fn(() => replacement);
+        const updatedRoot = requireDefined(api.updateAtPath(root, ['child'], update));
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(child);
+        expect(api.findAtPath(updatedRoot, ['replacement'])).toBe(replacement);
+        expect(api.findAtPath(updatedRoot, ['child'])).toBeUndefined();
+        const children = [...requireDefined(api.getLoadedChildren(updatedRoot))];
+        expect(children.map((node) => api.id(node))).toStrictEqual([
+            'before',
+            'replacement',
+            'after',
+        ]);
+        expect(children[0]).toBe(before);
+        expect(children[1]).toBe(replacement);
+        expect(children[2]).toBe(after);
+        expect(api.findAtPath(root, ['child'])).toBe(child);
+    });
+    it('rejects a replacement ID that duplicates a sibling ID', () => {
+        const child = api.createLeaf('child', 1);
+        const sibling = api.createLeaf('sibling', 2);
+        const root = loadedBranch('root', [child, sibling]);
+        const replacement = api.createLeaf('sibling', 3);
+        const update = vi.fn(() => replacement);
+        expect(api.updateAtPath(root, ['child'], update)).toBeUndefined();
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(child);
+        expect(api.findAtPath(root, ['child'])).toBe(child);
+        expect(api.findAtPath(root, ['sibling'])).toBe(sibling);
+    });
+    it('rebuilds ancestors while preserving unrelated node identities', () => {
+        const target = api.createLeaf('target', 1);
+        const sibling = api.createLeaf('sibling', 2);
+        const branch = loadedBranch('branch', [target, sibling]);
+        const otherBranch = loadedBranch('other', []);
+        const root = loadedBranch('root', [branch, otherBranch]);
+        const replacement = api.createLeaf('target', 3);
+        const updatedRoot = requireDefined(api.updateAtPath(root, ['branch', 'target'], () => replacement));
+        expect(updatedRoot).not.toBe(root);
+        expect(api.findAtPath(updatedRoot, ['branch'])).not.toBe(branch);
+        expect(api.findAtPath(updatedRoot, ['branch', 'target'])).toBe(replacement);
+        expect(api.findAtPath(updatedRoot, ['branch', 'sibling'])).toBe(sibling);
+        expect(api.findAtPath(updatedRoot, ['other'])).toBe(otherBranch);
+        expect(api.findAtPath(root, ['branch', 'target'])).toBe(target);
+    });
+    it('replaces the root for an empty path', () => {
+        const root = api.createLeaf('root', 0);
+        const replacement = api.createLeaf('replacement', 1);
+        const update = vi.fn(() => replacement);
+        expect(api.updateAtPath(root, [], update)).toBe(replacement);
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(root);
+    });
+    it.each([
+        {
+            name: 'a missing child',
+            root: loadedBranch('root', []),
+            path: ['missing'],
+        },
+        {
+            name: 'a path through a leaf',
+            root: api.createLeaf('root', 0),
+            path: ['child'],
+        },
+        {
+            name: 'a path through an unloaded branch',
+            root: api.createUnloadedBranch('root', 0),
+            path: ['child'],
+        },
+    ])('returns undefined for $name without calling the updater', ({ root, path }) => {
+        const update = vi.fn((node) => node);
+        expect(api.updateAtPath(root, path, update)).toBeUndefined();
+        expect(update).not.toHaveBeenCalled();
+    });
+    it.each([
+        { name: 'the root', path: [] },
+        { name: 'a descendant', path: ['child'] },
+    ])('returns undefined when updating $name is aborted', ({ path }) => {
+        const child = api.createLeaf('child', 1);
+        const root = loadedBranch('root', [child]);
+        const selected = requireDefined(api.findAtPath(root, path));
+        const update = vi.fn(() => undefined);
+        expect(api.updateAtPath(root, path, update)).toBeUndefined();
+        expect(update).toHaveBeenCalledOnce();
+        expect(update).toHaveBeenCalledWith(selected);
+        expect(api.findAtPath(root, ['child'])).toBe(child);
+    });
+});

package/dist/{trees/tree-node/tree-node.impl.d.ts → state-and-nav/tree/tree.impl.d.ts}

@@ -1,4 +1,4 @@
-import type { TreeNodeApi } from './tree-node.types.js';
+import type { TreeMethods } from './tree.types.js';
 import type { SerializableKey } from './tree-node.model.js';
 /**
  * Creates an API for constructing, inspecting, and immutably updating opaque
@@ -11,5 +11,5 @@ import type { SerializableKey } from './tree-node.model.js';
  * Tree updates preserve object identity for unrelated nodes. New ancestor
  * nodes and child collections are created only along an updated path.
  */
-export declare function createTreeNodeApi<Id extends SerializableKey, Value>(): TreeNodeApi<Id, Value>;
-//# sourceMappingURL=tree-node.impl.d.ts.map
+export declare function createTreeMethods<Id extends SerializableKey, Value>(): TreeMethods<Id, Value>;
+//# sourceMappingURL=tree.impl.d.ts.map

package/dist/state-and-nav/tree/tree.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EAGZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,sBAAsB,CAAC;AA2J3E;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,SAAS,eAAe,EAC1B,KAAK,KACF,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAgR1B"}

package/dist/{trees/tree-node/tree-node.impl.js → state-and-nav/tree/tree.impl.js}

@@ -13,6 +13,9 @@ function toData(node) {
 function fromData(data) {
     return data;
 }
+// =============================================================================
+// Helpers
+// =============================================================================
 function isLeafData(node) {
     return !('children' in node);
 }
@@ -23,11 +26,8 @@ function isLoadedBranchData(node) {
     return 'children' in node && node.children !== null;
 }
 /**
- * Returns a reusable iterable over child nodes without exposing the internal
- * child-array representation.
- *
- * The implementation currently stores children in an array, but callers only
- * receive an `Iterable` and must not rely on iteration order.
+ * Returns a reusable iterable over child nodes in their stored order without
+ * exposing the internal child array.
  */
 function asChildrenIterable(children) {
     return Object.freeze({
@@ -45,14 +45,15 @@ function asChildrenIterable(children) {
  * for `createLoadedBranch` and `withLoadedChildren`.
  */
 function copyUniqueChildren(children, getId) {
-    const copiedChildren = [...children];
+    const copiedChildren = [];
     const seenIds = new Set();
-    for (const child of copiedChildren) {
+    for (const child of children) {
         const id = getId(child);
         if (seenIds.has(id)) {
             return undefined;
         }
         seenIds.add(id);
+        copiedChildren.push(child);
     }
     return Object.freeze(copiedChildren);
 }
@@ -76,6 +77,9 @@ function createLoadedBranchData(id, value, children) {
         children,
     });
 }
+// =============================================================================
+// Generic Tree Methods Init
+// =============================================================================
 /**
  * Creates an API for constructing, inspecting, and immutably updating opaque
  * tree nodes.
@@ -87,8 +91,8 @@ function createLoadedBranchData(id, value, children) {
  * Tree updates preserve object identity for unrelated nodes. New ancestor
  * nodes and child collections are created only along an updated path.
  */
-export function createTreeNodeApi() {
-    function getOpenChildren(node) {
+export function createTreeMethods() {
+    function getLoadedChildrenData(node) {
         const data = toData(node);
         return isLoadedBranchData(data) ? data.children : undefined;
     }
@@ -143,11 +147,11 @@ export function createTreeNodeApi() {
             });
         },
         getLoadedChildren(node) {
-            const children = getOpenChildren(node);
+            const children = getLoadedChildrenData(node);
             return children === undefined ? undefined : asChildrenIterable(children);
         },
         findChildById(node, id) {
-            const children = getOpenChildren(node);
+            const children = getLoadedChildrenData(node);
             if (children === undefined) {
                 return undefined;
             }
@@ -245,7 +249,7 @@ export function createTreeNodeApi() {
     };
     function modifyChildAtPath(node, path, modifier) {
         const childId = path[0];
-        const children = getOpenChildren(node);
+        const children = getLoadedChildrenData(node);
         if (childId === undefined || children === undefined) {
             return undefined;
         }
@@ -270,14 +274,13 @@ export function createTreeNodeApi() {
             return undefined;
         }
         /*
-         * The current representation happens to use an array, so replacing one
-         * child is efficient internally. The public API makes no ordering promise:
-         * this is solely an implementation detail.
+         * Replace the child at its existing position, preserving sibling order even
+         * when the replacement has a different ID.
          */
         const updatedChildren = [...children];
         updatedChildren[childIndex] = updatedChild;
         /*
-         * `withChildren` revalidates sibling-ID uniqueness. This matters when
+         * `withLoadedChildren` revalidates sibling-ID uniqueness. This matters when
          * `modifier` replaces a node with another node having a different ID.
          */
         return api.withLoadedChildren(node, updatedChildren);

package/dist/{trees/tree-node/tree-node.types.d.ts → state-and-nav/tree/tree.types.d.ts}

@@ -25,7 +25,7 @@ declare const treeNodeBrand: unique symbol;
  * @remarks
  *
  * `TreeNode` is intentionally opaque. Callers may hold, compare by reference,
- * pass, store, and return nodes, but should use {@link TreeNodeApi} operations
+ * pass, store, and return nodes, but should use {@link TreeMethods} operations
  * to create, inspect, and update them.
  *
  * In particular, callers do not depend on:
@@ -111,14 +111,14 @@ export type TreeNodeKind = 'leaf' | 'unloaded-branch' | 'loaded-branch';
  *
  * @remarks
  *
- * `TreeNodeMatch` provides exhaustive pattern matching over the semantic state
- * of a node. It is the preferred operation when behavior differs between
- * leaves, unloaded branches, and loaded branches:
+ * `MatchByKind` provides exhaustive pattern matching over the node's semantic
+ * state. It is the preferred operation when behavior differs between leaves,
+ * unloaded branches, and loaded branches:
  *
  * - `leaf` receives no `children`, because a leaf cannot have children;
  * - `unloadedBranch` receives no `children`, because its children are not loaded;
- * - `loadedBranch` receives an iterable of loaded direct child nodes. No
- *   iteration-order guarantee is made.
+ * - `loadedBranch` receives an iterable of loaded direct child nodes in
+ *    child order.
  *
  * Every handler must return the same `Result` type.
  *
@@ -168,12 +168,16 @@ export type MatchByKind<Id extends SerializableKey, Value, Result> = Readonly<{
  *
  * A `TreeNodeApi` is specialized to one ID type and one application-value
  * type. It owns the structural tree rules: leaf/branch state, child loading
- * state, sibling-ID uniqueness, and immutable ancestor reconstruction.
+ * state, child order, sibling-ID uniqueness, and immutable ancestor
+ * reconstruction.
  *
- * Child collections are unordered. Although operations expose children as
- * `Iterable` values, callers must not rely on iteration order being stable,
- * meaningful, or related to insertion order. The implementation may use an
- * array, map, set, indexed store, or another representation internally.
+ * Loaded children form an ordered sequence. Construction and child-replacement
+ * operations preserve the supplied iterable's iteration order. Inspection
+ * operations expose children in that order, and model conversion preserves it.
+ * Replacing a descendant retains its position among siblings.
+ *
+ * The backing representation is private; these ordering guarantees do not
+ * require callers to depend on a particular storage structure.
  *
  * Tree nodes are plain immutable values at runtime. Update operations do not
  * mutate supplied nodes or their loaded child collections. When an update
@@ -191,19 +195,19 @@ export type MatchByKind<Id extends SerializableKey, Value, Result> = Readonly<{
  *
  * the root is addressed by `[]`, and `child` is addressed by `['child']`.
  *
- * Paths cannot pass through leaves or closed branches. A closed branch may be
- * selected as the final node in a path, but its unloaded descendants cannot be
- * addressed.
+ * Paths cannot pass through leaves or unloaded branches. An unloaded branch may
+ * be selected as the final node in a path, but its unloaded descendants cannot
+ * be addressed.
  *
  * @typeParam Id - The type used to identify nodes among siblings.
  * @typeParam Value - The application-specific value stored at each node.
  */
-export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
+export type TreeMethods<Id extends SerializableKey, Value> = Readonly<{
     /**
      * Creates a leaf node.
      *
      * A leaf cannot contain children. To convert an existing node to a leaf while
-     * retaining its ID and value, use {@link TreeNodeApi.toLeaf}.
+     * retaining its ID and value, use {@link TreeMethods.toLeaf}.
      *
      * @param id - The ID that identifies this node among its siblings.
      * @param value - Application-owned data stored on the node.
@@ -219,7 +223,13 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
      */
     createUnloadedBranch(id: Id, value: Value): TreeNode<Id, Value>;
     /**
-     * Creates a branch with a loaded child collection.
+     * Creates a branch with an ordered, loaded child collection.
+     *
+     * Children are copied in the supplied iterable's iteration order. Subsequent
+     * changes to the supplied collection do not affect the created branch.
+     *
+     * Direct siblings must have unique IDs. Returns `undefined` if the supplied
+     * children contain duplicate sibling IDs.
      *
      * An empty child collection creates a loaded branch with no current children;
      * it does not create a leaf.
@@ -245,7 +255,7 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
     /**
      * Returns the semantic kind of a node.
      *
-     * Prefer {@link TreeNodeApi.match} when behavior differs by node kind and all
+     * Prefer {@link TreeMethods.matchByKind} when behavior differs by node kind and all
      * three variants must be handled.
      *
      * @param node - The node to inspect.
@@ -256,24 +266,24 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
      * Inspects a node by handling its semantic state exhaustively.
      *
      * @param node - The node to inspect.
-     * @param handlers - Case handlers for leaf, closed-branch, and open-branch
+     * @param handlers - Case handlers for leaf, and unloaded/loaded branch
      * states.
      * @returns The value returned by the selected case handler.
      */
     matchByKind<Result>(node: TreeNode<Id, Value>, handlers: MatchByKind<Id, Value, Result>): Result;
     /**
-     * Returns the loaded direct children of a loaded branch.
+     * Returns the loaded direct children of a loaded branch in child order.
      *
-     * The returned child nodes are existing values, not defensive clones. No
-     * iteration-order guarantee is made.
+     * The returned iterable is reusable. Its child nodes are existing values,
+     * not defensive clones.
      *
      * Returns `undefined` when `node` is a leaf or an unloaded branch. Use
-     * {@link TreeNodeApi.kind} or {@link TreeNodeApi.match} when those cases need
+     * {@link TreeMethods.kind} or {@link TreeMethods.matchByKind} when those cases need
      * to be distinguished.
      *
      * @param node - The node whose direct children to inspect.
      * @returns An iterable of loaded direct children, or `undefined` when children
-     * are unavailable because `node` is a leaf or closed branch.
+     * are unavailable because `node` is a leaf or unloaded branch.
      */
     getLoadedChildren(node: TreeNode<Id, Value>): Iterable<TreeNode<Id, Value>> | undefined;
     /**
@@ -284,16 +294,16 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
      *
      * @param node - The node whose loaded direct children to search.
      * @param id - The sibling ID to find.
-     * @returns The existing matching child, or `undefined` when `node` is not an
-     * open branch or does not have a direct child with `id`.
+     * @returns The existing matching child, or `undefined` when `node` is not a
+     * loaded branch or does not have a direct child with `id`.
      */
     findChildById(node: TreeNode<Id, Value>, id: Id): TreeNode<Id, Value> | undefined;
     /**
      * Returns an equivalent node with replacement application data.
      *
      * The returned node retains the original node's ID, semantic child state,
-     * and when applicable, existing child-node references. The supplied node is
-     * not mutated.
+     * and when applicable, child order and existing child-node references.
+     * The supplied node is not mutated.
      *
      * @param node - The node to update.
      * @param value - Replacement application-owned data.
@@ -317,17 +327,18 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
      * Any currently loaded child collection is discarded.
      *
      * @param node - The node to convert.
-     * @returns A closed branch with the source node's ID and value.
+     * @returns An unloaded branch with the source node's ID and value.
      */
     toUnloadedBranch(node: TreeNode<Id, Value>): TreeNode<Id, Value>;
     /**
-     * Converts a node to an open branch with replacement loaded children.
+     * Converts a node to a loaded branch with replacement children.
      *
      * The returned node retains the source node's ID and application value.
      * Any previous child state is replaced.
      *
-     * Child collections are unordered. Callers must not rely on the iteration order
-     * of the supplied children being retained or exposed by the resulting node.
+     * Children are copied in the supplied iterable's iteration order. That order
+     * becomes the replacement child order. Subsequent changes to the supplied
+     * collection do not affect the returned node.
      *
      * Direct siblings must have unique IDs. If two or more supplied children have
      * the same ID, no replacement node is created and this method returns
@@ -338,8 +349,8 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
      * @param node - The node to convert or update.
      * @param children - Replacement loaded direct children. Their IDs must be
      * unique among direct siblings.
-     * @returns An open branch with the source node's ID and value, or `undefined`
-     * when `children` contains duplicate sibling IDs.
+     * @returns A loaded branch with the source node's ID and value, or
+     * `undefined` when `children` contains duplicate sibling IDs.
      */
     withLoadedChildren(node: TreeNode<Id, Value>, children: Iterable<TreeNode<Id, Value>>): TreeNode<Id, Value> | undefined;
     /**
@@ -361,7 +372,7 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
      * selected node is supplied as the existing node value and is not cloned.
      *
      * An empty path selects `root`. Resolution fails when a path refers to a
-     * missing child or attempts to pass through a leaf or a closed branch.
+     * missing child or attempts to pass through a leaf or an unloaded branch.
      *
      * @param root - The root node relative to which `path` is interpreted.
      * @param path - A sibling-ID path relative to `root`.
@@ -373,40 +384,49 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
     /**
      * Immutably replaces the node addressed by a path relative to `root`.
      *
-     * The modifier runs only after the complete path has been resolved. Returning
-     * `undefined` aborts the operation and causes this method to return
+     * The update callback runs only after the complete path has been resolved.
+     * Returning `undefined` aborts the operation and causes this method to return
      * `undefined`.
      *
      * An empty path selects `root`. When a descendant is replaced, replacement
      * nodes are created only along the path from `root` to that descendant. Nodes
      * outside that path retain their original object identity.
      *
-     * The modifier may return a node with a different ID. If it does, the
+     * The `update` may return a node with a different ID. If it does, the
      * replacement is subsequently addressed by its new ID rather than the old
-     * path segment.
+     * path segment. The replacement retains the original node's position among
+     * siblings, and all other siblings retain their relative order.
      *
      * The update also fails when the replacement node's ID duplicates the ID of
-     * one of its new siblings. This can occur when `modifier` returns a node with
+     * one of its new siblings. This can occur when `update` returns a node with
      * a different ID.
      *
      * @param root - The root node relative to which `path` is interpreted.
      * @param path - A sibling-ID path relative to `root`.
      * @param update - Produces a replacement node, or `undefined` to abort.
      * @returns A replacement root, or `undefined` when the path cannot be
-     *  resolved, `modifier` aborts, or the replacement would create duplicate
+     *  resolved, `update` aborts, or the replacement would create duplicate
      *  sibling IDs.
      */
     updateAtPath(root: TreeNode<Id, Value>, path: readonly Id[], update: (node: TreeNode<Id, Value>) => TreeNode<Id, Value> | undefined): TreeNode<Id, Value> | undefined;
     /**
      * Converts an opaque runtime node into a public structural model.
      *
-     * The returned model is a fresh recursive snapshot. It is suitable for
-     * serialization when `Id` and `Value` are serializable.
+     * Creates fresh model objects and child arrays recursively, preserving child
+     * order at every loaded branch. Application-owned values are retained by
+     * reference, not cloned; callers must treat those values as immutable.
+     *
+     * The model is suitable for JSON serialization when `Id` and `Value` are
+     * JSON-serializable.
      */
     toModel(node: TreeNode<Id, Value>): TreeNodeModel<Id, Value>;
     /**
      * Constructs an opaque tree from a public structural model.
      *
+     * Creates new runtime nodes and child collections, preserving child order
+     * at every loaded branch. Application-owned values are retained by reference,
+     * not cloned.
+     *
      * Returns `undefined` if any loaded child collection contains duplicate
      * sibling IDs.
      *
@@ -416,4 +436,4 @@ export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
     fromModel(model: TreeNodeModel<Id, Value>): TreeNode<Id, Value> | undefined;
 }>;
 export {};
-//# sourceMappingURL=tree-node.types.d.ts.map
+//# sourceMappingURL=tree.types.d.ts.map

package/dist/state-and-nav/tree/tree.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.types.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,MAAM,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI;IACxD;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE;QACxB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;QAChB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;KACvB,CAAC;CACH,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,MAAM,WAAW,CACrB,EAAE,SAAS,eAAe,EAC1B,KAAK,EACL,MAAM,IACJ,QAAQ,CAAC;IACX,IAAI,EAAE,CACJ,IAAI,EAAE,QAAQ,CAAC;QACb,EAAE,EAAE,EAAE,CAAC;QACP,KAAK,EAAE,KAAK,CAAC;KACd,CAAC,KACC,MAAM,CAAC;IAEZ,cAAc,EAAE,CACd,IAAI,EAAE,QAAQ,CAAC;QACb,EAAE,EAAE,EAAE,CAAC;QACP,KAAK,EAAE,KAAK,CAAC;KACd,CAAC,KACC,MAAM,CAAC;IAEZ,YAAY,EAAE,CACZ,IAAI,EAAE,QAAQ,CAAC;QACb,EAAE,EAAE,EAAE,CAAC;QACP,KAAK,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;KACzC,CAAC,KACC,MAAM,CAAC;CACb,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IACpE;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAEtD;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAEhE;;;;;;;;;;;OAWG;IACH,kBAAkB,CAChB,EAAE,EAAE,EAAE,EACN,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,GACtC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEnC;;;;;OAKG;IACH,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;IAElC;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAExC;;;;;;;;OAQG;IACH,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,YAAY,CAAC;IAE9C;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAChB,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,QAAQ,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GACvC,MAAM,CAAC;IAEV;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CACf,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,aAAa,CACX,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,EAAE,EAAE,EAAE,GACL,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAExE;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAEvD;;;;;;;;OAQG;IACH,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAEjE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,kBAAkB,CAChB,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,GACtC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,UAAU,CACR,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,IAAI,EAAE,SAAS,EAAE,EAAE,GAClB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEnC;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,MAAM,EACjB,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,MAAM,GAC9C,MAAM,GAAG,SAAS,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,YAAY,CACV,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,GACrE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEnC;;;;;;;;;OASG;IACH,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAE7D;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;CAC7E,CAAC,CAAC"}

package/dist/state-and-nav/tree/tree.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirvi-lib",
-  "version": "0.11.0-beta.5",
+  "version": "0.11.0-beta.7",
   "description": "Dependency for dirvi.",
   "license": "LGPL-3.0-or-later",
   "type": "module",