dirvi-lib 0.11.0-beta.1 → 0.11.0-beta.13

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

@@ -0,0 +1,204 @@
+/**
+ * Shared navigation operations over both projection styles.
+ *
+ * Fold summaries exist in either projection, but only ordered navigation
+ * exposes them as cursor destinations.
+ */
+export function createNavTraversalMethods(cursorMethods, navigateFolds) {
+    function entryIsBranch(entry) {
+        return 'children' in entry;
+    }
+    function entryIsFold(entry) {
+        return 'folded' in entry;
+    }
+    function foldCursor(entry, parentPath) {
+        const firstEntry = entry.folded[0];
+        /*
+         * Projected folds are nonempty and contain direct source entries.
+         * Keep the guard because NavFold also permits richer future contents.
+         */
+        if (firstEntry === undefined || entryIsFold(firstEntry)) {
+            return undefined;
+        }
+        return {
+            parentPath: [...parentPath],
+            firstId: firstEntry.id,
+        };
+    }
+    function getNodeAtPath(navigation, path) {
+        let node = navigation;
+        for (const id of path) {
+            const entry = node.entries.find((candidate) => !entryIsFold(candidate) && candidate.id === id);
+            /*
+             * Paths cannot pass through leaves, folds, or unloaded branches.
+             * Hidden entries inside fold summaries are deliberately not searched.
+             */
+            if (entry === undefined ||
+                !entryIsBranch(entry) ||
+                entry.children === null) {
+                return undefined;
+            }
+            node = entry.children;
+        }
+        // An empty path identifies the current navigation node.
+        return node;
+    }
+    function getEntryAtPath(navigation, path) {
+        /*
+         * A NavNode does not itself correspond to a NavEntry. Therefore [] does
+         * not resolve to an entry.
+         */
+        if (path.length === 0) {
+            return undefined;
+        }
+        const parent = getNodeAtPath(navigation, path.slice(0, -1));
+        const id = path[path.length - 1];
+        return parent?.entries.find((candidate) => !entryIsFold(candidate) && candidate.id === id);
+    }
+    function cursors(navigation, parentPath = []) {
+        const positions = [];
+        for (const entry of navigation.entries) {
+            if (entryIsFold(entry)) {
+                if (navigateFolds) {
+                    const cursor = foldCursor(entry, parentPath);
+                    if (cursor !== undefined) {
+                        positions.push(cursor);
+                    }
+                }
+                // Hidden descendants are never separately navigable.
+                continue;
+            }
+            const entryPath = [...parentPath, entry.id];
+            positions.push({ path: entryPath });
+            if (entryIsBranch(entry) && entry.children !== null) {
+                positions.push(...cursors(entry.children, entryPath));
+            }
+        }
+        return positions;
+    }
+    function rootCursors(rootNode) {
+        return [
+            { path: [] },
+            ...(rootNode.children === null ? [] : cursors(rootNode.children)),
+        ];
+    }
+    function nextCursor(rootNode, cursor) {
+        const positions = rootCursors(rootNode);
+        const currentIndex = positions.findIndex((candidate) => cursorMethods.equal(candidate, cursor));
+        if (currentIndex === -1) {
+            return undefined;
+        }
+        return positions[currentIndex + 1];
+    }
+    function previousCursor(rootNode, cursor) {
+        const positions = rootCursors(rootNode);
+        const currentIndex = positions.findIndex((candidate) => cursorMethods.equal(candidate, cursor));
+        if (currentIndex <= 0) {
+            return undefined;
+        }
+        return positions[currentIndex - 1];
+    }
+    function cursorAfterFold(rootNode, cursor) {
+        if (!cursorMethods.isNodeCursor(cursor) ||
+            cursor.path.length === 0 ||
+            rootNode.children === null) {
+            // Folding root is disallowed. Fold markers are already folded.
+            return undefined;
+        }
+        if (navigateFolds) {
+            const parentPath = cursor.path.slice(0, -1);
+            const parent = getNodeAtPath(rootNode.children, parentPath);
+            const id = cursor.path[cursor.path.length - 1];
+            if (parent === undefined) {
+                return undefined;
+            }
+            const currentIndex = parent.entries.findIndex((entry) => !entryIsFold(entry) && entry.id === id);
+            if (currentIndex === -1) {
+                return undefined;
+            }
+            const entry = parent.entries[currentIndex];
+            if (entry === undefined || entryIsFold(entry)) {
+                return undefined;
+            }
+            const previousEntry = parent.entries[currentIndex - 1];
+            /*
+             * Folding next to an existing preceding run merges into that run.
+             * A following run also merges, but does not determine the first ID.
+             */
+            if (previousEntry !== undefined && entryIsFold(previousEntry)) {
+                const previousFoldCursor = foldCursor(previousEntry, parentPath);
+                if (previousFoldCursor !== undefined) {
+                    return previousFoldCursor;
+                }
+            }
+            return {
+                parentPath,
+                firstId: entry.id,
+            };
+        }
+        const positions = rootCursors(rootNode);
+        const currentIndex = positions.findIndex((candidate) => cursorMethods.equal(candidate, cursor));
+        if (currentIndex === -1) {
+            return undefined;
+        }
+        for (let index = currentIndex + 1; index < positions.length; index += 1) {
+            const candidate = positions[index];
+            if (candidate === undefined) {
+                continue;
+            }
+            // Skip entries that are children of the entry about to be folded.
+            if (cursorMethods.cursorBelongsToSubtree(candidate, cursor.path)) {
+                continue;
+            }
+            return candidate;
+        }
+        /*
+         * No following position survives the fold. Move before the subtree,
+         * rather than into one of its soon-to-be-hidden descendants.
+         */
+        return positions[currentIndex - 1];
+    }
+    function parentCursor(_navigation, cursor) {
+        if (cursorMethods.isFoldCursor(cursor)) {
+            return {
+                path: [...cursor.parentPath],
+            };
+        }
+        if (cursor.path.length === 0) {
+            return undefined;
+        }
+        return {
+            path: cursor.path.slice(0, -1),
+        };
+    }
+    function visiblePaths(navigation, parentPath = []) {
+        const paths = [];
+        for (const entry of navigation.entries) {
+            if (entryIsFold(entry)) {
+                continue;
+            }
+            const entryPath = [...parentPath, entry.id];
+            paths.push(entryPath);
+            /*
+             * A null value means the source branch is not loaded/opened. It has no
+             * currently visible descendants.
+             */
+            if (entryIsBranch(entry) && entry.children !== null) {
+                paths.push(...visiblePaths(entry.children, entryPath));
+            }
+        }
+        return paths;
+    }
+    return {
+        entryIsBranch,
+        entryIsFold,
+        getNodeAtPath,
+        getEntryAtPath,
+        nextCursor,
+        previousCursor,
+        cursorAfterFold,
+        parentCursor,
+        cursors,
+        visiblePaths,
+    };
+}

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

@@ -1,47 +1,47 @@
-import type { SerializableKey, TreeNode } from '../tree-node/index.js';
+import type { SerializableKey, TreeNode } from '../tree/index.js';
 import type { Cursor } from '../cursor.js';
 import type { Folds } from '../fold-node/index.js';
 export type NavNode<Id extends SerializableKey> = {
     /**
-     * Synthetic UI entry representing folded children.
+     * Projected direct children, including fold summaries.
      *
-     * It is absent when this directory has no folded children.
-     */
-    folded: NavFoldEntry<Id> | null;
-    /**
-     * Loaded entries that are not folded at this directory, corresponding to
-     * navigable rows.
+     * Ordered navigation preserves source sibling order and inserts inline folds.
+     * Unordered navigation uses presentation order and places its optional fold
+     * summary first.
      *
-     * Their order is the sibling iteration order supplied by the TreeNode API.
+     * Not every entry is therefore necessarily a cursor destination: in ordered
+     * trees, the fold summary is not navigable and the NavMethod implementation
+     * should skip it.
      */
     entries: NavEntry<Id>[];
 };
-export type NavFoldEntry<Id extends SerializableKey> = {
-    /**
-     * Folded entries that are present in the loaded TreeNode.
-     *
-     * This is information for rendering the folded row.
-     */
-    entries: NavEntry<Id>[];
-};
-export type NavEntry<Id extends SerializableKey> = NavLeaf<Id> | NavBranch<Id>;
+export type NavEntry<Id extends SerializableKey> = NavLeaf<Id> | NavBranch<Id> | NavFold<Id>;
 export type NavLeaf<Id extends SerializableKey> = {
     id: Id;
 };
 export type NavBranch<Id extends SerializableKey> = {
     id: Id;
     /**
-     * `null` means this branch's children have not been loaded or opened.
+     * `null` means this branch's children have not been loaded.
      */
     children: NavNode<Id> | null;
 };
+export type NavFold<Id extends SerializableKey> = {
+    /**
+     * Folded entries that are present in the loaded TreeNode.
+     *
+     * For unordered trees, there is at most one folded entry, and it is the first
+     * in nav node's `entries`.
+     */
+    folded: NavEntry<Id>[];
+};
 /**
  * Operations for creating and navigating a UI-oriented projection of a tree.
  *
  * @typeParam Id - The type identifying a node among its direct siblings.
  * @typeParam Value - Application-owned data stored in each source TreeNode.
  */
-export type NavNodeApi<Id extends SerializableKey, Value> = {
+export type NavMethods<Id extends SerializableKey, Value> = {
     /**
      * Tests whether a navigation entry represents a branch.
      *
@@ -50,6 +50,10 @@ export type NavNodeApi<Id extends SerializableKey, Value> = {
      * opened.
      */
     entryIsBranch(entry: NavEntry<Id>): entry is NavBranch<Id>;
+    /**
+     * Tests whether a navigation entry represents a branch.
+     */
+    entryIsFold(entry: NavEntry<Id>): entry is NavFold<Id>;
     /**
      * Creates a navigation projection rooted at `root`.
      *
@@ -71,7 +75,7 @@ export type NavNodeApi<Id extends SerializableKey, Value> = {
      * express that fact statically. This method returns `undefined` if `root`
      * is a leaf.
      *
-     * A closed root branch produces a NavBranch whose `children` is `null`.
+     * An unloaded branch produces a NavBranch whose `children` is `null`.
      *
      * @param root - Source tree node from which to create navigation.
      * @param folds - Fold definitions corresponding to `root`. All active fold
@@ -102,7 +106,17 @@ export type NavNodeApi<Id extends SerializableKey, Value> = {
      * @param cursor
      */
     parentCursor(navigation: NavNode<Id>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    /**
+     * Enumerates navigable positions in depth-first display order.
+     *
+     * Unordered navigation skips fold summaries.
+     * Ordered navigation includes inline folds as fold cursors.
+     */
     cursors(navigation: NavNode<Id>, parentPath?: readonly Id[]): Cursor<Id>[];
-    visibleLeavesPaths(navigation: NavNode<Id>, parentPath?: readonly Id[]): Id[][];
+    /**
+     * Returns visible node paths in depth-first display order, excluding the
+     * root and folded entries. Includes both leaves and branches.
+     */
+    visiblePaths(navigation: NavNode<Id>, parentPath?: readonly Id[]): Id[][];
 };
-//# sourceMappingURL=nav-node.types.d.ts.map
+//# sourceMappingURL=nav.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nav.types.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/nav/nav.types.ts"],"names":[],"mappings":"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"}

package/dist/state-and-nav/nav/nav.unordered.impl.d.ts

@@ -0,0 +1,13 @@
+import type { SerializableKey, TreeMethods } from '../tree/index.js';
+import type { FoldMethods } from '../fold-node/index.js';
+import type { CursorMethods } from '../cursor.js';
+import type { NavMethods } from './nav.types.js';
+/**
+ * Creates operations for projecting an opaque tree into a navigation model.
+ *
+ * Sibling order has no semantic meaning in this navigation system.
+ * This projection preserves source sibling order among visible entries and
+ * collects hidden entries into one leading, non-navigable fold summary.
+ */
+export declare function createUnorderedNavMethods<Id extends SerializableKey, Value>(treeMethods: TreeMethods<Id, Value>, foldMethods: FoldMethods<Id>, cursorMethods: CursorMethods<Id>): NavMethods<Id, Value>;
+//# sourceMappingURL=nav.unordered.impl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nav.unordered.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/nav/nav.unordered.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAY,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAKV,UAAU,EACX,MAAM,gBAAgB,CAAC;AAGxB;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACzE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,EAC5B,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC,GAC/B,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CA+FvB"}

package/dist/state-and-nav/nav/nav.unordered.impl.js

@@ -0,0 +1,77 @@
+import { createNavTraversalMethods } from './nav.traversal.js';
+/**
+ * Creates operations for projecting an opaque tree into a navigation model.
+ *
+ * Sibling order has no semantic meaning in this navigation system.
+ * This projection preserves source sibling order among visible entries and
+ * collects hidden entries into one leading, non-navigable fold summary.
+ */
+export function createUnorderedNavMethods(treeMethods, foldMethods, cursorMethods) {
+    /**
+     * Projects loaded children into navigation entries.
+     *
+     * Folded source entries are collected into one leading, non-navigable
+     * fold summary. Their complete projections are retained inside it.
+     */
+    function createNavNode(entries, foldRoot, parentPath) {
+        const visibleEntries = [];
+        const foldedEntries = [];
+        for (const entry of entries) {
+            const entryId = treeMethods.id(entry);
+            const entryPath = [...parentPath, entryId];
+            const isFolded = foldMethods.isEntryHiddenAtPath(foldRoot, parentPath, entryId);
+            const navigationEntry = createNavEntry(entry, foldRoot, entryPath);
+            if (isFolded) {
+                /*
+                 * Retain the complete projection for later fold inspection.
+                 * Ordinary traversal never descends into this hidden projection.
+                 */
+                foldedEntries.push(navigationEntry);
+            }
+            else {
+                visibleEntries.push(navigationEntry);
+            }
+        }
+        return {
+            /*
+             * Fold state may contain entries that are not currently available in the
+             * loaded source tree. Do not render an empty synthetic row for them.
+             */
+            entries: foldedEntries.length === 0
+                ? visibleEntries
+                : [{ folded: foldedEntries }, ...visibleEntries],
+        };
+    }
+    function createNavEntry(entry, foldRoot, entryPath) {
+        return treeMethods.matchByKind(entry, {
+            leaf: ({ id }) => ({
+                id,
+            }),
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, entryPath),
+            }),
+        });
+    }
+    function createRootNavBranch(root, foldRoot) {
+        return treeMethods.matchByKind(root, {
+            leaf: () => undefined,
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, []),
+            }),
+        });
+    }
+    return {
+        ...createNavTraversalMethods(cursorMethods, false),
+        from: createRootNavBranch,
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { SerializableKey, TreeMethods } from '../tree/index.js';
+import type { FoldMethods } from '../fold-node/index.js';
+import type { CursorMethods } from '../cursor.js';
+import type { StateMethods } from './state.types.js';
+/**
+ * Creates operations for navigating and resynchronizing tree-surfer state.
+ */
+export declare function createStateApi<Id extends SerializableKey, Value>(treeNodeApi: TreeMethods<Id, Value>, foldsApi: FoldMethods<Id>, cursorApi: CursorMethods<Id>): StateMethods<Id, Value>;
+//# sourceMappingURL=state.impl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/state/state.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEf,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAU,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAS,MAAM,kBAAkB,CAAC;AA4C5D;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC9D,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC,EACzB,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,GAC3B,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,CA2PzB"}

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 {
+        treeMethods: treeNodeApi,
+        foldMethods: foldsApi,
+        cursorMethods: 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 StateMethods<Id extends SerializableKey, Value> = Readonly<{
+    treeMethods: TreeMethods<Id, Value>;
+    foldMethods: FoldMethods<Id>;
+    cursorMethods: 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,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IACrE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACpC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;IAEjC;;;;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"}