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

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

@@ -1,7 +1,13 @@
+function getStateData(state) {
+    return state;
+}
+function createState(data) {
+    return data;
+}
 /**
  * Creates operations for navigating and resynchronizing tree-surfer state.
  */
-export function createStateApi(treeNodeApi, cursorApi) {
+export function createStateApi(treeNodeApi, foldsApi, cursorApi) {
     /**
      * Reloads one node's direct children and recursively reloads descendant
      * branches that were open in the old state.
@@ -102,27 +108,74 @@ export function createStateApi(treeNodeApi, cursorApi) {
      * 5. If no entry cursor exists, use the root cursor.
      */
     function resyncCursor(_oldState, _newRoot, _newFolds) {
-        return [];
+        return { path: [] };
     }
     return {
+        treeNodeApi,
+        foldsApi,
+        cursorApi,
+        create(root, folds, cursor) {
+            return treeNodeApi.kind(root) === 'loaded-branch'
+                ? createState({ root, folds, cursor })
+                : undefined;
+        },
+        getRoot(state) {
+            return getStateData(state).root;
+        },
+        getFolds(state) {
+            return getStateData(state).folds;
+        },
+        getCursor(state) {
+            return getStateData(state).cursor;
+        },
+        update(state, changes) {
+            const data = getStateData(state);
+            const root = changes.root ?? data.root;
+            const folds = changes.folds ?? data.folds;
+            const cursor = changes.cursor ?? data.cursor;
+            if (treeNodeApi.kind(root) !== 'loaded-branch') {
+                return undefined;
+            }
+            if (root === data.root &&
+                folds === data.folds &&
+                cursor === data.cursor) {
+                return state;
+            }
+            return createState({ root, folds, cursor });
+        },
         getNodeAtCursor(state) {
-            const path = cursorApi.getPath(state.cursor);
-            return treeNodeApi.selectAtPath(state.root, path, (node) => node);
+            const { root, cursor } = getStateData(state);
+            /*
+             * A fold cursor identifies a display item, not a single source node.
+             * Its representative path must not silently select its first child.
+             */
+            if (!cursorApi.isNodeCursor(cursor)) {
+                return undefined;
+            }
+            return treeNodeApi.selectAtPath(root, cursor.path, (node) => node);
+        },
+        isCursorRoot(state) {
+            const { cursor } = getStateData(state);
+            return cursorApi.isNodeCursor(cursor) && cursor.path.length === 0;
+        },
+        cursorPath(state) {
+            const { cursor } = getStateData(state);
+            return cursorApi.getPath(cursor);
         },
         async resync(oldState, loadBranches) {
-            const reloaded = await reload(oldState.root, [], loadBranches);
+            const oldStateData = getStateData(oldState);
+            const reloaded = await reload(oldStateData.root, [], loadBranches);
             /*
              * Fold-state resynchronization is not implemented yet. Keep the existing
              * fold definitions while the source tree is reloaded.
              */
-            const folds = oldState.folds;
+            const folds = oldStateData.folds;
             const root = reloaded.root;
-            return {
-                ...oldState,
+            return createState({
                 root,
                 folds,
                 cursor: resyncCursor(oldState, root, folds),
-            };
+            });
         },
     };
 }

package/dist/state-and-nav/state/state.schemas.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state.schemas.d.ts.map

package/dist/state-and-nav/state/state.schemas.d.ts.map

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

package/dist/state-and-nav/state/state.schemas.js

@@ -0,0 +1,39 @@
+export {};
+// import { z } from 'zod';
+// import type { Cursor } from './unordered-nav/cursor.js';
+// import type { FoldsModel } from './fold-node/index.js';
+// import type { SerializableKey, TreeNodeModel } from './tree/index.js';
+//
+// /**
+//  * Serializable persistence/interchange model for tree-surfer state.
+//  *
+//  * This is intentionally distinct from runtime `State`: its root and folds use
+//  * public structural models, while runtime state holds opaque TreeNode and
+//  * Folds values.
+//  */
+// export type StateModel<Id extends SerializableKey, Value> = Readonly<{
+//   root: TreeNodeModel<Id, Value>;
+//   folds: FoldsModel<Id>;
+//   cursor: Cursor<Id>;
+// }>;
+//
+// /**
+//  * Creates a schema for the serializable StateModel DTO.
+//  *
+//  * This validates only the persistence representation. Applications must decode
+//  * the validated root and folds models through their specialized TreeNodeApi and
+//  * FoldsApi before constructing opaque runtime State.
+//  */
+// export function createStateModelSchema<Id extends SerializableKey, Value>(
+//   rootSchema: z.ZodType<TreeNodeModel<Id, Value>>,
+//   foldsSchema: z.ZodType<FoldsModel<Id>>,
+//   cursorSchema: z.ZodType<Cursor<Id>>,
+// ): z.ZodType<StateModel<Id, Value>> {
+//   return z
+//     .object({
+//       root: rootSchema,
+//       folds: foldsSchema,
+//       cursor: cursorSchema,
+//     })
+//     .strict();
+// }

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

@@ -0,0 +1,72 @@
+import type { SerializableKey, TreeNode, TreeMethods } from '../tree/index.js';
+import type { FoldMethods, Folds } from '../fold-node/index.js';
+import type { Cursor, CursorMethods } from '../cursor.js';
+declare const stateBrand: unique symbol;
+/**
+ * Opaque type for state of the tree, folds, and cursor.
+ *
+ * Used by consumers as React State.
+ */
+export type State<Id extends SerializableKey, Value> = Readonly<{
+    [stateBrand]: Readonly<{
+        id: Id;
+        value: Value;
+    }>;
+}>;
+export type StateApi<Id extends SerializableKey, Value> = Readonly<{
+    treeNodeApi: TreeMethods<Id, Value>;
+    foldsApi: FoldMethods<Id>;
+    cursorApi: CursorMethods<Id>;
+    /**
+     * Creates state whose root is a loaded branch.
+     *
+     * Returns undefined when root is a leaf or an unloaded branch.
+     */
+    create(root: TreeNode<Id, Value>, folds: Folds<Id>, cursor: Cursor<Id>): State<Id, Value> | undefined;
+    getRoot(state: State<Id, Value>): TreeNode<Id, Value>;
+    getFolds(state: State<Id, Value>): Folds<Id>;
+    getCursor(state: State<Id, Value>): Cursor<Id>;
+    /**
+     * Immutably replaces supplied state components.
+     *
+     * Returns undefined when the replacement root is not a loaded branch.
+     * Returns the original state when all components retain their references.
+     */
+    update(state: State<Id, Value>, changes: Readonly<{
+        root?: TreeNode<Id, Value>;
+        folds?: Folds<Id>;
+        cursor?: Cursor<Id>;
+    }>): State<Id, Value> | undefined;
+    /**
+     * Returns a mutable root-relative path.
+     *
+     * For a fold cursor, returns the path of its first hidden child.
+     * This representative path does not identify the fold marker itself.
+     */
+    cursorPath(state: State<Id, Value>): Id[];
+    /**
+     * Tests whether the cursor is the root node cursor: { path: [] }.
+     */
+    isCursorRoot(state: State<Id, Value>): boolean;
+    /**
+     * Resolves a node cursor against the source tree.
+     *
+     * Returns undefined for fold cursors or paths absent from the loaded tree.
+     * This does not check visibility in a navigation projection.
+     */
+    getNodeAtCursor(state: State<Id, Value>): TreeNode<Id, Value> | undefined;
+    /**
+     * Reloads the root's children and all descendant branches that were loaded
+     * in the previous state.
+     *
+     * `loadBranches([])` loads the root's direct children.
+     * `loadBranches(['src'])` loads the children of `src`, where `src` is the
+     * ID of a root child.
+     *
+     * Returned nodes must be valid TreeNode values created or decoded through
+     * the specialized TreeNodeApi for `Id` and `Value`.
+     */
+    resync(oldState: State<Id, Value>, loadBranches: (path: readonly Id[]) => Promise<readonly TreeNode<Id, Value>[]>): Promise<State<Id, Value>>;
+}>;
+export {};
+//# sourceMappingURL=state.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.types.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/state/state.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,CAAC,MAAM,UAAU,EAAE,OAAO,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IAC9D,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;QACrB,EAAE,EAAE,EAAE,CAAC;QACP,KAAK,EAAE,KAAK,CAAC;KACd,CAAC,CAAC;CACJ,CAAC,CAAC;AAEH,MAAM,MAAM,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IACjE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACpC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;IAE7B;;;;OAIG;IACH,MAAM,CACJ,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EACzB,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,EAChB,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GACjB,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEhC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,MAAM,CACJ,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EACvB,OAAO,EAAE,QAAQ,CAAC;QAChB,IAAI,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;KACrB,CAAC,GACD,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAEhC;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC;IAC1C;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;IAC/C;;;;;OAKG;IACH,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAE1E;;;;;;;;;;OAUG;IACH,MAAM,CACJ,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EAC1B,YAAY,EAAE,CACZ,IAAI,EAAE,SAAS,EAAE,EAAE,KAChB,OAAO,CAAC,SAAS,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,GAC3C,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;CAC9B,CAAC,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.arb.d.ts","sourceRoot":"","sources":["../../../../src/state-and-nav/tree/deprecated/tree-node.arb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;GAIG;AACH,KAAK,UAAU,GAAG,MAAM,CAAC;AAOzB;;;GAGG;AACH,eAAO,MAAM,SAAS,sBAIpB,CAAC;AAEH;;GAEG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AAC1D,KAAK,IAAI,GAAG,UAAU,EAAE,CAAC;AAEzB,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,UAAU,EAAE,CAAC;CAC9B,CAAC;AAuEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,sCAEhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,sCAExC,CAAC;AAaF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,SAAS,CAAC,sBAAsB,CA0C5D,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,wCAIjC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;EAK3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;EAQnC,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;EAYpC,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,qBAE1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,4BAA8C,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.impl.d.ts","sourceRoot":"","sources":["../../../../src/state-and-nav/tree/deprecated/tree-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,eAAe,EACf,QAAQ,EACR,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,KAC5B,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAqGzB"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.schemas.d.ts","sourceRoot":"","sources":["../../../../src/state-and-nav/tree/deprecated/tree-node.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,iDAA6C,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;;;;;;;;;;;;EAoBrD"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.types.d.ts","sourceRoot":"","sources":["../../../../src/state-and-nav/tree/deprecated/tree-node.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,QAAQ,CAClB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B,YAAY,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AAEhD,+BAA+B;AAC/B,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,eAAe,IAAI;IACrD,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,cAAc,CACxB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,oBAAoB,CAAC,EAAE,CAAC,CAAC;AAE5D,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,CAC5B,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B;IACF,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,EAAE,IAAI,EAAE,CAAC;CAClB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,CAAC,EAAE,SAAS,eAAe,IAAI;IAC7D,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CACrB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B;IACF,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9D,cAAc,CACZ,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,GAC7B,IAAI,IAAI,oBAAoB,CAAC,EAAE,CAAC,CAAC;IACpC,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,GAC7B,IAAI,IAAI,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAExC;;;;;;;;OAQG;IACH,WAAW,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IAE3E;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EACd,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,GAC/B,MAAM,GAAG,SAAS,CAAC;IAEtB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CACV,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,GAAG,SAAS,GACzC,IAAI,GAAG,SAAS,CAAC;CACrB,CAAC"}

package/dist/state-and-nav/tree/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * To be used as the dependencies of State and Navigation.
+ */
+export type { SerializableKey } from './tree-node.model.js';
+export type * from './tree.types.js';
+export { createTreeMethods } from './tree.impl.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1 @@
+export { createTreeMethods } from './tree.impl.js';

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

@@ -0,0 +1,94 @@
+import * as fc from 'fast-check';
+import { TreeNodeModel } from './tree-node.model.js';
+/**
+ * The ID and Values types used for the generated test trees.
+ *
+ * Short strings keep generated counterexamples readable. Values just have to
+ * be something easily checked for equality.
+ */
+type Id = string;
+type Value = number;
+type ModelAndPath = {
+    model: TreeNodeModel<Id, Value>;
+    path: Id[];
+};
+/**
+ * A model and a pair of a model and its path for every reachable path in the
+ * model
+ *
+ * Includes this model at `[]` and every descendant reachable through loaded
+ * branches. Descendants behind unloaded branches are intentionally absent.
+ */
+type ModelWithReachableModels = {
+    model: TreeNodeModel<Id, Value>;
+    reachableModels: ModelAndPath[];
+};
+/**
+ * Generates valid string IDs for test nodes. Note that the API just does
+ * comparisons on the IDs so we can safely restrict to any subset.
+ */
+export declare const idArb: fc.Arbitrary<string>;
+/**
+ * Generates serializable application values for test nodes.
+ */
+export declare const valueArb: fc.Arbitrary<number>;
+/**
+ * Generates a leaf model.
+ */
+export declare const leafModelWRMArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates an unloaded-branch model.
+ */
+export declare const unloadedBranchModelWRMArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates a leaf, an unloaded branch, or a loaded branch.
+ *
+ * Loaded branches have unique child IDs. Root IDs are made unique separately
+ * when generating a forest.
+ *
+ * The weighted choice gives recursive loaded branches a geometric drop off.
+ */
+export declare const modelWithReachableModelsArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates an array of generated models with unique sibling IDs.
+ *
+ * The result is suitable for use as the loaded children of a loaded branch.
+ */
+export declare const siblingModelsWRMArb: fc.Arbitrary<ModelWithReachableModels[]>;
+/**
+ * Generates root-level models and a path to one of their reachable models.
+ *
+ * Every generated path is valid for `getAtPath`; unreachable paths are not
+ * included.
+ */
+export declare const modelAndReachablePathArb: fc.Arbitrary<{
+    root: TreeNodeModel<string, number>;
+    path: string[];
+    expected: TreeNodeModel<string, number>;
+}>;
+/**
+ * Generates a root model and a path to one of its reachable branch models.
+ *
+ * Both loaded and unloaded branches are included.
+ */
+export declare const modelAndBranchPathArb: fc.Arbitrary<{
+    root: TreeNodeModel<string, number>;
+    path: string[];
+    expected: TreeNodeModel<string, number>;
+}>;
+/**
+ * Generates a new array of loaded child models.
+ *
+ * The generated models have unique IDs, making the result suitable for use as
+ * the children of a loaded branch.
+ */
+export declare const childrenModelsArb: fc.Arbitrary<TreeNodeModel<string, number>[]>;
+/**
+ * Generates either a new array of loaded child models or `null`.
+ *
+ * An array represents a loaded branch, including a loaded branch with no
+ * children. `null` represents an unloaded branch.
+ */
+export declare const childrenStateModelArb: fc.Arbitrary<TreeNodeModel<string, number>[] | null>;
+export {};
+//# sourceMappingURL=tree-node.arb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.arb.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree-node.arb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,KAAK,EAAE,GAAG,MAAM,CAAC;AACjB,KAAK,KAAK,GAAG,MAAM,CAAC;AAEpB,KAAK,YAAY,GAAG;IAClB,KAAK,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAChC,IAAI,EAAE,EAAE,EAAE,CAAC;CACZ,CAAC;AAEF;;;;;;GAMG;AACH,KAAK,wBAAwB,GAAG;IAC9B,KAAK,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAChC,eAAe,EAAE,YAAY,EAAE,CAAC;CACjC,CAAC;AAWF;;;GAGG;AACH,eAAO,MAAM,KAAK,sBAIhB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ,sBAGnB,CAAC;AAyEH;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAEhB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAGd,CAAC;AAUhE;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAyCtE,CAAC;AASV;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,0CAI9B,CAAC;AAIH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;EAOpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;EAc/B,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,+CAE7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,sDAAiD,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tree-node.arb.debug.test.d.ts.map

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

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

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

@@ -0,0 +1,54 @@
+import { describe, it } from 'vitest';
+import * as fc from 'fast-check';
+import { modelWithReachableModelsArb, siblingModelsWRMArb } from './tree-node.arb.js';
+/**
+ * Manual inspection of generated models and their reachable paths.
+ *
+ * Remove `.skip` temporarily to run these inspections.
+ * These are debugging aids, not assertions about the arbitraries.
+ */
+describe.skip('inspect tree-node arbitraries', () => {
+    const seed = 12345;
+    it('prints generated models and reachable paths', () => {
+        const samples = fc.sample(modelWithReachableModelsArb, {
+            numRuns: 10,
+            seed,
+        });
+        for (const [index, generated] of samples.entries()) {
+            console.log(`\n--- model ${index + 1} ---`);
+            console.dir(generated.model, {
+                depth: Infinity,
+                colors: false,
+            });
+            console.log(`reachable nodes: ${generated.reachableModels.length}`, `maximum depth: ${Math.max(...generated.reachableModels.map(({ path }) => path.length))}`);
+            console.log('reachable paths:');
+            console.dir(generated.reachableModels.map(({ path, model }) => ({
+                path,
+                id: model.id,
+                kind: !('children' in model)
+                    ? 'leaf'
+                    : model.children === null
+                        ? 'unloaded-branch'
+                        : 'loaded-branch',
+            })), {
+                depth: Infinity,
+                colors: false,
+            });
+        }
+    });
+    it('prints generated sibling collections', () => {
+        const samples = fc.sample(siblingModelsWRMArb, {
+            numRuns: 5,
+            seed,
+        });
+        for (const [index, generatedNodes] of samples.entries()) {
+            console.log(`\n--- sibling collection ${index + 1} ---`);
+            console.dir(generatedNodes.map(({ model }) => model), {
+                depth: Infinity,
+                colors: false,
+            });
+            console.log('sibling IDs:', generatedNodes.map(({ model }) => model.id));
+            console.log('total reachable nodes:', generatedNodes.reduce((count, generated) => count + generated.reachableModels.length, 0));
+        }
+    });
+});

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

@@ -0,0 +1,188 @@
+import * as fc from 'fast-check';
+// =============================================================================
+// ID and Value Arbitraries
+// =============================================================================
+/**
+ * Characters used for readable generated node IDs.
+ */
+const smallLetterCharacters = Array.from('abcdefghijklmnopqrstuvwxyz');
+/**
+ * Generates valid string IDs for test nodes. Note that the API just does
+ * comparisons on the IDs so we can safely restrict to any subset.
+ */
+export const idArb = fc.string({
+    unit: fc.constantFrom(...smallLetterCharacters),
+    minLength: 1,
+    maxLength: 8,
+});
+/**
+ * Generates serializable application values for test nodes.
+ */
+export const valueArb = fc.integer({
+    min: -10_000,
+    max: 10_000,
+});
+// =============================================================================
+// Generating Models with Reachable Models
+// =============================================================================
+// Helpers
+const createLeafModel = (id, value) => {
+    const model = {
+        id,
+        value,
+    };
+    return {
+        model,
+        reachableModels: [{ path: [], model }],
+    };
+};
+function createUnloadedBranchModel(id, value) {
+    const model = {
+        id,
+        value,
+        children: null,
+    };
+    return {
+        model,
+        reachableModels: [{ path: [], model }],
+    };
+}
+/**
+ * Creates the metadata for a loaded branch and all descendants reachable
+ * through its loaded child collection.
+ *
+ * Child-array order is preserved, both in the model and in the enumeration
+ * of reachable descendants.
+ */
+function createLoadedBranchModel(id, value, children) {
+    const model = {
+        id,
+        value,
+        children: children.map(({ model: child }) => child),
+    };
+    const reachableDescendants = children.flatMap(({ model: childModel, reachableModels }) => reachableModels.map(({ path, model: reachableModel }) => ({
+        path: [childModel.id, ...path],
+        model: reachableModel,
+    })));
+    return {
+        model,
+        reachableModels: [{ path: [], model }, ...reachableDescendants],
+    };
+}
+// Arbs
+/**
+ * Generates a leaf model.
+ */
+export const leafModelWRMArb = fc
+    .tuple(idArb, valueArb)
+    .map(([id, value]) => createLeafModel(id, value));
+/**
+ * Generates an unloaded-branch model.
+ */
+export const unloadedBranchModelWRMArb = fc
+    .tuple(idArb, valueArb)
+    .map(([id, value]) => createUnloadedBranchModel(id, value));
+/**
+ * Generates either kind of 'terminal' model.
+ *
+ * Both leaves and unloaded branches terminate path traversal.
+ */
+const terminalModelWRMArb = fc.oneof(leafModelWRMArb, unloadedBranchModelWRMArb);
+/**
+ * Generates a leaf, an unloaded branch, or a loaded branch.
+ *
+ * Loaded branches have unique child IDs. Root IDs are made unique separately
+ * when generating a forest.
+ *
+ * The weighted choice gives recursive loaded branches a geometric drop off.
+ */
+export const modelWithReachableModelsArb = fc.letrec((tie) => {
+    const generatedChildModelArb = tie('node');
+    /**
+     * Generates the loaded children of a loaded branch.
+     *
+     * Sibling IDs must be unique so that child lookup is unambiguous. The
+     * maximum length also limits the branching factor of recursive examples.
+     */
+    const generatedLoadedChildrenArb = fc.uniqueArray(generatedChildModelArb, {
+        minLength: 0,
+        maxLength: 4,
+        size: 'medium',
+        selector: ({ model }) => model.id,
+    });
+    /**
+     * Generates a loaded branch and its reachable descendants.
+     */
+    const generatedLoadedBranchModelArb = fc
+        .tuple(idArb, valueArb, generatedLoadedChildrenArb)
+        .map(([id, value, children]) => createLoadedBranchModel(id, value, children));
+    return {
+        node: fc
+            .integer({
+            min: 0,
+            max: 9999,
+        })
+            .chain((choice) => 
+        // 5046 works for getAtPath tests, but too heavy for modifyAtPath tests
+        choice >= 5050
+            ? generatedLoadedBranchModelArb
+            : terminalModelWRMArb),
+    };
+}).node;
+// =============================================================================
+// Generating Models
+// =============================================================================
+// Prepares inputs for particular tests.
+// Generating Replacement Child State
+/**
+ * Generates an array of generated models with unique sibling IDs.
+ *
+ * The result is suitable for use as the loaded children of a loaded branch.
+ */
+export const siblingModelsWRMArb = fc.uniqueArray(modelWithReachableModelsArb, {
+    minLength: 0,
+    size: 'small',
+    selector: (generated) => generated.model.id,
+});
+// Generating Models with a Selected Reachable Target
+/**
+ * Generates root-level models and a path to one of their reachable models.
+ *
+ * Every generated path is valid for `getAtPath`; unreachable paths are not
+ * included.
+ */
+export const modelAndReachablePathArb = modelWithReachableModelsArb.chain(({ model: root, reachableModels }) => fc.constantFrom(...reachableModels).map(({ path, model }) => ({
+    root,
+    path,
+    expected: model,
+})));
+/**
+ * Generates a root model and a path to one of its reachable branch models.
+ *
+ * Both loaded and unloaded branches are included.
+ */
+export const modelAndBranchPathArb = modelWithReachableModelsArb
+    .map(({ model: root, reachableModels }) => ({
+    root,
+    branchPathEntries: reachableModels.filter(({ model }) => 'children' in model),
+}))
+    .filter(({ branchPathEntries }) => branchPathEntries.length > 0)
+    .chain(({ root, branchPathEntries }) => fc.constantFrom(...branchPathEntries).map(({ path, model }) => ({
+    root,
+    path,
+    expected: model,
+})));
+/**
+ * Generates a new array of loaded child models.
+ *
+ * The generated models have unique IDs, making the result suitable for use as
+ * the children of a loaded branch.
+ */
+export const childrenModelsArb = siblingModelsWRMArb.map((generatedNodes) => generatedNodes.map(({ model }) => model));
+/**
+ * Generates either a new array of loaded child models or `null`.
+ *
+ * An array represents a loaded branch, including a loaded branch with no
+ * children. `null` represents an unloaded branch.
+ */
+export const childrenStateModelArb = fc.oneof(childrenModelsArb, fc.constant(null));