dirvi-lib 0.8.1 → 0.8.2

package/dist/trees/fold-node/fold-node.types.d.ts

@@ -0,0 +1,206 @@
+import type { SerializableKey } from '../tree-node/index.js';
+import type { FoldSlotModel, FoldsModel } from './fold-node.model.js';
+declare const foldsBrand: unique symbol;
+/**
+ * A slot index within Folds.
+ *
+ * Index 0 is always occupied by the required primary fold tree.
+ *
+ * Other valid indexes are non-negative safe integers. TypeScript cannot
+ * represent that restriction for number, so indexes must be validated at
+ * runtime at API boundaries.
+ */
+export type FoldIndex = number;
+/**
+ * Public user-facing metadata for a fold tree.
+ *
+ * Every fold tree has a name. `description: null` means that no description
+ * has been supplied. An empty string is distinct: it is a supplied
+ * description with no text.
+ */
+export type FoldInfo = Readonly<{
+    /**
+     * Durable user-facing name of the fold tree.
+     */
+    name: string;
+    /**
+     * User-facing description of the fold tree, or `null` when none exists.
+     */
+    description: string | null;
+}>;
+/**
+ * Immutable collection of fold-data slots for one source node tree.
+ *
+ * Every contained fold tree uses the same ID paths as the source TreeNode
+ * tree. Slot zero always contains a fold tree.
+ */
+export type Folds<Id extends SerializableKey> = {
+    readonly [foldsBrand]: {
+        readonly id: Id;
+    };
+};
+export type FoldsApi<Id extends SerializableKey> = Readonly<{
+    /**
+     * Creates Folds with its required primary fold tree in slot zero.
+     *
+     * The new fold tree initially contains no hidden entries and is active.
+     */
+    create(rootId: Id, initialPrimaryInfo: FoldInfo): Folds<Id>;
+    /**
+     * Returns metadata for the fold tree at an occupied slot.
+     *
+     * Index zero always returns FoldInfo for a valid Folds value.
+     */
+    getInfoAtIndex(folds: Folds<Id>, index: FoldIndex): FoldInfo | undefined;
+    /**
+     * Returns whether the fold tree at an occupied slot is active.
+     *
+     * Returns `undefined` when the slot is unoccupied.
+     */
+    isActiveAtIndex(folds: Folds<Id>, index: FoldIndex): boolean | undefined;
+    /**
+     * Returns whether a slot is occupied.
+     *
+     * For valid Folds values, `hasAtIndex(folds, 0)` is always true.
+     */
+    hasAtIndex(folds: Folds<Id>, index: FoldIndex): boolean;
+    /**
+     * Returns occupied slot indexes.
+     *
+     * The ordering is ascending slot order.
+     */
+    indexes(folds: Folds<Id>): Iterable<FoldIndex>;
+    /**
+     * Stores a serialized occupied fold slot at an index.
+     *
+     * Replaces any existing slot at that index. The supplied `Folds` value is not
+     * mutated.
+     *
+     * `foldData` is converted into the internal opaque fold-tree representation.
+     * This operation returns `undefined` when `index` is not a non-negative safe
+     * integer or when the slot's fold-tree model cannot be restored.
+     *
+     * This is a low-level operation. Most callers should use
+     * `setAdditionalFoldAtIndex`, `updateInfoAtIndex`, or the fold-state
+     * operations instead.
+     */
+    setAtIndex(folds: Folds<Id>, index: FoldIndex, foldData: FoldSlotModel<Id>): Folds<Id> | undefined;
+    /**
+     * Creates or replaces a non-primary fold tree at a slot.
+     *
+     * The new fold tree initially contains no hidden entries.
+     *
+     * This operation rejects index zero because the required primary fold tree
+     * must not be replaced accidentally.
+     */
+    setAdditionalFoldAtIndex(folds: Folds<Id>, index: FoldIndex, rootId: Id, info: FoldInfo): Folds<Id> | undefined;
+    /**
+     * Removes a non-primary fold tree from a slot.
+     *
+     * Returns `undefined` when `index` is zero because the primary fold tree may
+     * not be removed.
+     *
+     * Returns the original `Folds` reference when the non-primary slot is already
+     * unoccupied.
+     */
+    removeAdditionalFoldAtIndex(folds: Folds<Id>, index: FoldIndex): Folds<Id> | undefined;
+    /**
+     * Replaces supplied user-facing metadata while preserving the fold tree.
+     *
+     * Omitted properties are left unchanged.
+     *
+     * - `description: string` sets or replaces the description.
+     * - `description: null` clears the description.
+     */
+    updateInfoAtIndex(folds: Folds<Id>, index: FoldIndex, update: Readonly<{
+        name?: string;
+        description?: string | null;
+    }>): Folds<Id> | undefined;
+    /**
+     * Marks the fold tree at an occupied slot as active.
+     *
+     * An active fold tree contributes to hiding entries.
+     *
+     * Returns `undefined` when the slot is unoccupied. Returns the original
+     * Folds reference when the fold tree is already active.
+     */
+    activateAtIndex(folds: Folds<Id>, index: FoldIndex): Folds<Id> | undefined;
+    /**
+     * Marks the fold tree at an occupied slot as inactive.
+     *
+     * An inactive fold tree retains its definition but does not contribute to
+     * hiding entries.
+     *
+     * Returns `undefined` when the slot is unoccupied. Returns the original
+     * Folds reference when the fold tree is already inactive.
+     */
+    deactivateAtIndex(folds: Folds<Id>, index: FoldIndex): Folds<Id> | undefined;
+    /**
+     * Inverts whether the fold tree at an occupied slot is active.
+     *
+     * Returns `undefined` when the slot is unoccupied.
+     */
+    toggleActiveAtIndex(folds: Folds<Id>, index: FoldIndex): Folds<Id> | undefined;
+    /**
+     * Returns whether an entry is hidden by one fold tree at an occupied slot.
+     *
+     * This checks the fold definition regardless of whether that fold tree is
+     * currently active.
+     */
+    isEntryHiddenInFoldAtPath(folds: Folds<Id>, index: FoldIndex, path: readonly Id[], entryId: Id): boolean;
+    /**
+     * Returns whether an entry is hidden by at least one active fold tree.
+     *
+     * Inactive fold trees retain fold definitions but do not contribute to this
+     * result.
+     */
+    isEntryHiddenAtPath(folds: Folds<Id>, path: readonly Id[], entryId: Id): boolean;
+    /**
+     * Returns IDs hidden directly at a branch path in one fold tree.
+     */
+    hiddenEntryIdsAtPath(folds: Folds<Id>, index: FoldIndex, path: readonly Id[]): Iterable<Id> | undefined;
+    /**
+     * Marks an entry as hidden at a branch path in one fold tree.
+     */
+    hideEntryAtPath(folds: Folds<Id>, index: FoldIndex, path: readonly Id[], entryId: Id): Folds<Id> | undefined;
+    /**
+     * Removes hidden state for an entry at a branch path in one fold tree.
+     */
+    showEntryAtPath(folds: Folds<Id>, index: FoldIndex, path: readonly Id[], entryId: Id): Folds<Id> | undefined;
+    /**
+     * Shows every entry hidden directly at the branch addressed by `path`.
+     *
+     * This removes all hidden-entry IDs at that fold-tree node but retains
+     * descendant fold-tree nodes and their fold state.
+     *
+     * For example, given:
+     *
+     * root
+     * └── src
+     *     hiddenEntryIds: ["lib", "main.ts"]
+     *     └── lib
+     *         hiddenEntryIds: ["parser.ts"]
+     *
+     * showAllHiddenEntriesAtPath(folds, index, ["src"]) produces:
+     *
+     * root
+     * └── src
+     *     hiddenEntryIds: []
+     *     └── lib
+     *         hiddenEntryIds: ["parser.ts"]
+     */
+    showAllHiddenEntriesAtPath(folds: Folds<Id>, index: FoldIndex, path: readonly Id[]): Folds<Id> | undefined;
+    /**
+     * Converts opaque runtime folds into a serializable fold-state model.
+     */
+    toModel(folds: Folds<Id>): FoldsModel<Id>;
+    /**
+     * Restores opaque runtime folds from a validated serialized model.
+     *
+     * This validates fold-internal invariants, but does not validate that paths
+     * correspond to a specific source node tree.
+     */
+    fromModel(model: FoldsModel<Id>): Folds<Id> | undefined;
+}>;
+export {};
+//# sourceMappingURL=fold-node.types.d.ts.map

package/dist/trees/fold-node/fold-node.types.d.ts.map

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

package/dist/trees/fold-node/index.d.ts

@@ -0,0 +1,4 @@
+export * from './fold-node.impl.js';
+export * from './fold-node.model.js';
+export * from './fold-node.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/trees/fold-node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/trees/fold-node/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/trees/fold-node/index.js

@@ -0,0 +1,3 @@
+export * from './fold-node.impl.js';
+export * from './fold-node.model.js';
+export * from './fold-node.types.js';

package/dist/trees/index.d.ts

@@ -0,0 +1,9 @@
+export * from './fold-node/index.js';
+export * from './nav-node/nav-node.impl.js';
+export * from './nav-node/nav-node.types.js';
+export * from './tree-node/index.js';
+export * from './cursor.js';
+export * from './state/state.impl.js';
+export * from './state/state.schemas.js';
+export * from './state/state.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/trees/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trees/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AAErC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAE7C,cAAc,sBAAsB,CAAC;AAErC,cAAc,aAAa,CAAC;AAE5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC"}

package/dist/trees/index.js

@@ -0,0 +1,8 @@
+export * from './fold-node/index.js';
+export * from './nav-node/nav-node.impl.js';
+export * from './nav-node/nav-node.types.js';
+export * from './tree-node/index.js';
+export * from './cursor.js';
+export * from './state/state.impl.js';
+export * from './state/state.schemas.js';
+export * from './state/state.types.js';

package/dist/trees/nav-node/nav-node.impl.d.ts

@@ -0,0 +1,29 @@
+import type { SerializableKey, TreeNodeApi } from '../tree-node/index.js';
+import type { FoldsApi } from '../fold-node/index.js';
+import type { CursorApi } from '../cursor.js';
+import type { NavNodeApi } from './nav-node.types.js';
+export type NavEntryComparator<Id extends SerializableKey, Value> = (left: Readonly<{
+    id: Id;
+    value: Value;
+}>, right: Readonly<{
+    id: Id;
+    value: Value;
+}>) => number;
+export type CreateNavNodeApiOptions<Id extends SerializableKey, Value> = Readonly<{
+    /**
+     * Defines display and cursor-navigation order among sibling entries.
+     *
+     * For deterministic navigation, this should define a total order for
+     * distinct sibling entries. If two entries compare equal, their order falls
+     * back to the source TreeNode child iteration order.
+     */
+    compareEntries: NavEntryComparator<Id, Value>;
+}>;
+/**
+ * Creates operations for projecting an opaque tree into a navigation model.
+ *
+ * Navigation ordering is intentionally a UI concern. The underlying TreeNode
+ * API need not promise a particular child-storage representation or ordering.
+ */
+export declare function createNavNodeApi<Id extends SerializableKey, Value>(treeNodeApi: TreeNodeApi<Id, Value>, foldsApi: FoldsApi<Id>, cursorApi: CursorApi<Id>, options: CreateNavNodeApiOptions<Id, Value>): NavNodeApi<Id, Value>;
+//# sourceMappingURL=nav-node.impl.d.ts.map

package/dist/trees/nav-node/nav-node.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-node.impl.d.ts","sourceRoot":"","sources":["../../../src/trees/nav-node/nav-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAY,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,KAAK,EAAS,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAIV,UAAU,EACX,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,kBAAkB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,CAClE,IAAI,EAAE,QAAQ,CAAC;IACb,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;CACd,CAAC,EACF,KAAK,EAAE,QAAQ,CAAC;IACd,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;CACd,CAAC,KACC,MAAM,CAAC;AAEZ,MAAM,MAAM,uBAAuB,CACjC,EAAE,SAAS,eAAe,EAC1B,KAAK,IACH,QAAQ,CAAC;IACX;;;;;;OAMG;IACH,cAAc,EAAE,kBAAkB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAChE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,EACxB,OAAO,EAAE,uBAAuB,CAAC,EAAE,EAAE,KAAK,CAAC,GAC1C,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CA8UvB"}

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

@@ -1,17 +1,40 @@
-export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
+/**
+ * Creates operations for projecting an opaque tree into a navigation model.
+ *
+ * Navigation ordering is intentionally a UI concern. The underlying TreeNode
+ * API need not promise a particular child-storage representation or ordering.
+ */
+export function createNavNodeApi(treeNodeApi, foldsApi, cursorApi, options) {
     function entryIsBranch(entry) {
         return 'children' in entry;
     }
+    function compareTreeNodes(left, right) {
+        return options.compareEntries({
+            id: treeNodeApi.id(left),
+            value: treeNodeApi.value(left),
+        }, {
+            id: treeNodeApi.id(right),
+            value: treeNodeApi.value(right),
+        });
+    }
+    /**
+     * Projects loaded children into navigation entries.
+     *
+     * Folded source entries are omitted from `entries` and represented in the
+     * synthetic `folded` row instead.
+     */
     function createNavNode(entries, foldRoot, parentPath) {
         const visibleEntries = [];
         const foldedEntries = [];
-        const foldedEntryIds = foldRoot === undefined
-            ? undefined
-            : foldNodeService.foldedEntriesAtPath(foldRoot, parentPath);
-        for (const entry of entries) {
-            const entryPath = [...parentPath, entry.id];
-            const isFolded = foldRoot !== undefined &&
-                foldNodeService.getIfEntryFoldedAtPath(foldRoot, parentPath, entry.id);
+        /*
+         * Navigation owns presentation order, so materialize and sort the child
+         * iterable before projecting it.
+         */
+        const orderedEntries = [...entries].sort(compareTreeNodes);
+        for (const entry of orderedEntries) {
+            const entryId = treeNodeApi.id(entry);
+            const entryPath = [...parentPath, entryId];
+            const isFolded = foldsApi.isEntryHiddenAtPath(foldRoot, parentPath, entryId);
             const navigationEntry = createNavEntry(entry, foldRoot, entryPath);
             if (isFolded) {
                 foldedEntries.push(navigationEntry);
@@ -22,7 +45,11 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
         }
         return {
             entries: visibleEntries,
-            folded: foldedEntryIds === undefined || foldedEntryIds.length === 0
+            /*
+             * Fold state may contain entries that are not currently available in the
+             * loaded source tree. Do not render an empty synthetic row for them.
+             */
+            folded: foldedEntries.length === 0
                 ? null
                 : {
                     entries: foldedEntries,
@@ -30,23 +57,32 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
         };
     }
     function createNavEntry(entry, foldRoot, entryPath) {
-        if (treeNodeApi.isLeaf(entry)) {
-            return {
-                id: entry.id,
-            };
-        }
-        return createNavBranch(entry, foldRoot, entryPath);
+        return treeNodeApi.match(entry, {
+            leaf: ({ id }) => ({
+                id,
+            }),
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, entryPath),
+            }),
+        });
     }
-    function createNavBranch(entry, foldRoot, entryPath) {
-        if (!treeNodeApi.isBranch(entry)) {
-            throw new Error('Navigation root must be a branch');
-        }
-        return {
-            id: entry.id,
-            children: entry.children === null
-                ? null
-                : createNavNode(entry.children, foldRoot, entryPath),
-        };
+    function createRootNavBranch(root, foldRoot) {
+        return treeNodeApi.match(root, {
+            leaf: () => undefined,
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, []),
+            }),
+        });
     }
     function rootCursors(rootNode) {
         if (rootNode.children === null) {
@@ -68,24 +104,24 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
     }
     const navNodeApi = {
         entryIsBranch,
-        // Return a nav node from the TreeNode and FoldNode trees.
         from(root, foldRoot) {
-            return createNavBranch(root, foldRoot, []);
+            return createRootNavBranch(root, foldRoot);
         },
         getNodeAtPath(navigation, path) {
             const [currentId, ...remainingPath] = path;
-            // An empty path identifies the current node.
+            /*
+             * An empty path identifies the current navigation node.
+             */
             if (currentId === undefined) {
                 return navigation;
             }
             const entry = navigation.entries.find((candidate) => candidate.id === currentId);
-            if (entry === undefined) {
-                return undefined;
-            }
-            if (!entryIsBranch(entry)) {
+            if (entry === undefined || !entryIsBranch(entry)) {
                 return undefined;
             }
-            // The directory has not been loaded/opened.
+            /*
+             * A null value represents a source branch whose children are not loaded.
+             */
             if (entry.children === null) {
                 return undefined;
             }
@@ -93,6 +129,10 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
         },
         getEntryAtPath(navigation, path) {
             const [currentId, ...remainingPath] = path;
+            /*
+             * A NavNode does not itself correspond to a NavEntry. Therefore [] does
+             * not resolve to an entry.
+             */
             if (currentId === undefined) {
                 return undefined;
             }
@@ -125,6 +165,7 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
             return cursors[currentIndex - 1];
         },
         cursorAfterFold(rootNode, cursor) {
+            // Folding root disallowed
             if (cursor.length === 0) {
                 return undefined;
             }
@@ -133,18 +174,22 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
             if (currentIndex === -1) {
                 return undefined;
             }
+            // If the last entry, then cursor should go to previous entry
+            // This works to go to the root when the last entry in the root is folded.
+            if (currentIndex + 1 === cursors.length) {
+                return cursors[currentIndex - 1];
+            }
             for (let index = currentIndex + 1; index < cursors.length; index += 1) {
                 const candidate = cursors[index];
                 if (candidate === undefined) {
                     continue;
                 }
+                // Skip any entries that are children of the entry about to be folded
                 if (cursorApi.cursorBelongsToSubtree(candidate, cursor)) {
                     continue;
                 }
                 return candidate;
             }
-            // The fold row will be created at the end of this directory.
-            return [...cursor];
         },
         parentCursor(_navigation, cursor) {
             if (cursor.length === 0) {
@@ -159,15 +204,17 @@ export function createNavNodeApi(treeNodeApi, foldNodeService, cursorApi) {
             const paths = [];
             for (const entry of navigation.entries) {
                 const entryPath = [...parentPath, entry.id];
-                if (entryIsBranch(entry)) {
-                    // A null children value means that the directory has not been
-                    // loaded/opened, so there are no visible descendant files.
-                    if (entry.children !== null) {
-                        paths.push(...navNodeApi.visibleLeavesPaths(entry.children, entryPath));
-                    }
+                if (!entryIsBranch(entry)) {
+                    paths.push(entryPath);
                     continue;
                 }
-                paths.push(entryPath);
+                /*
+                 * A null value means the source branch is not loaded/opened. It has no
+                 * currently visible descendants.
+                 */
+                if (entry.children !== null) {
+                    paths.push(...navNodeApi.visibleLeavesPaths(entry.children, entryPath));
+                }
             }
             return paths;
         },

package/dist/trees/nav-node/nav-node.types.d.ts

@@ -0,0 +1,103 @@
+import type { SerializableKey, TreeNode } from '../tree-node/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.
+     *
+     * 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.
+     *
+     * Their order is the sibling iteration order supplied by the TreeNode API.
+     */
+    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 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.
+     */
+    children: NavNode<Id> | null;
+};
+/**
+ * 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> = {
+    /**
+     * Tests whether a navigation entry represents a branch.
+     *
+     * A branch is an entry with a `children` property. Its `children` value is
+     * `null` when the corresponding source-tree branch has not been loaded or
+     * opened.
+     */
+    entryIsBranch(entry: NavEntry<Id>): entry is NavBranch<Id>;
+    /**
+     * Creates a navigation projection rooted at `root`.
+     *
+     * The source TreeNode is authoritative for:
+     *
+     * - entry identity;
+     * - whether an entry is a leaf, closed branch, or open branch;
+     * - the loaded direct child entries; and
+     * - sibling iteration order, where guaranteed by TreeNodeApi.
+     *
+     * `foldRoot` is authoritative for folding. It contains multiple independently
+     * active fold trees. An entry is folded in the projection when at least one
+     * active fold tree hides that entry at its parent path.
+     *
+     * A folded entry is omitted from its parent's navigable entries and is
+     * represented by that parent's synthetic `folded` entry instead.
+     *
+     * The root must be a branch node. Since TreeNode is opaque, callers cannot
+     * express that fact statically. This method returns `undefined` if `root`
+     * is a leaf.
+     *
+     * A closed root 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
+     * trees contribute to whether a source entry is represented by its parent’s
+     * synthetic `folded` entry.
+     * @returns The projected root branch, or `undefined` when `root` is a leaf.
+     */
+    from(root: TreeNode<Id, Value>, folds: Folds<Id>): NavBranch<Id> | undefined;
+    /**
+     * Finds the navigation node represented by a path relative to `navigation`.
+     *
+     * An empty path selects `navigation` itself. Paths cannot pass through leaf
+     * entries or branches whose children are currently `null`.
+     */
+    getNodeAtPath(navigation: NavNode<Id>, path: readonly Id[]): NavNode<Id> | undefined;
+    /**
+     * Finds the navigation entry represented by a path relative to `navigation`.
+     *
+     * An empty path does not identify an entry and returns `undefined`.
+     */
+    getEntryAtPath(navigation: NavNode<Id>, path: readonly Id[]): NavEntry<Id> | undefined;
+    nextCursor(rootNode: NavBranch<Id>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    previousCursor(rootNode: NavBranch<Id>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    cursorAfterFold(rootNode: NavBranch<Id>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    parentCursor(navigation: NavNode<Id>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    cursors(navigation: NavNode<Id>, parentPath?: readonly Id[]): Cursor<Id>[];
+    visibleLeavesPaths(navigation: NavNode<Id>, parentPath?: readonly Id[]): Id[][];
+};
+//# sourceMappingURL=nav-node.types.d.ts.map

package/dist/trees/nav-node/nav-node.types.d.ts.map

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

package/dist/trees/state/state.impl.d.ts

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

package/dist/trees/state/state.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.impl.d.ts","sourceRoot":"","sources":["../../../src/trees/state/state.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAY,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpF,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAS,MAAM,kBAAkB,CAAC;AAMxD;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC9D,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,GACvB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAuLrB"}