dirvi-lib 0.8.1 → 0.8.2

package/dist/app/app-api.d.ts

@@ -0,0 +1,74 @@
+import type { ViewApi } from './view-api.js';
+import type { CursorApi, FoldsApi, NavNodeApi, SerializableKey, State, StateApi, TreeNode, TreeNodeApi } from '../trees/index.js';
+/**
+ * Application-specific tree dependencies and operations.
+ *
+ * This is currently migrated through the generic TreeNode and State APIs.
+ * Navigation-specific APIs remain outside this type until NavNodeApi has been
+ * migrated from the old structural TreeNode API.
+ *
+ * @typeParam Id - The sibling-unique tree-node ID type.
+ * @typeParam Value - Application-owned data stored in each tree node.
+ * @typeParam ViewKey - The key used to identify view implementations.
+ */
+export type AppApi<Id extends SerializableKey, Value, ViewKey = string> = Readonly<{
+    /**
+     * Name used to distinguish the application, for example `posix` for a
+     * POSIX-directory application.
+     */
+    appId: string;
+    /**
+     * Name used to distinguish a particular application instance.
+     */
+    name: string;
+    /**
+     * ID used for the application's root node.
+     */
+    rootId: Id;
+    /**
+     * Loads direct children for the branch addressed by `path`.
+     *
+     * Returned nodes must be opaque tree values created or decoded through this
+     * application's TreeNodeApi specialization.
+     */
+    loadBranches: (path: readonly Id[]) => Promise<readonly TreeNode<Id, Value>[]>;
+    /**
+     * Creates the application's root node.
+     *
+     * Invariant: the returned node is an open branch. That invariant is checked
+     * when an initial State is created.
+     */
+    createRoot: () => Promise<TreeNode<Id, Value>>;
+    /**
+     * Subscribes to external data changes that require tree state to be loaded
+     * again.
+     *
+     * Returns an unsubscribe function.
+     */
+    subscribeToResync: (listener: () => void) => () => void;
+    /**
+     * Generic structural operations for this application's buffer tree.
+     */
+    treeNodeApi: TreeNodeApi<Id, Value>;
+    /**
+     * Semantic fold-state operations.
+     *
+     * This remains temporarily available while FoldNode itself is migrated.
+     */
+    foldsApi: FoldsApi<Id>;
+    cursorApi: CursorApi<Id>;
+    stateApi: StateApi<Id, Value>;
+    /**
+     * UI navigation projection and cursor-navigation operations.
+     */
+    navNodeApi: NavNodeApi<Id, Value>;
+    viewKey: ViewKey;
+    viewApi: ViewApi<State<Id, Value>, ViewKey>;
+}>;
+export type AppStateApis<Id extends SerializableKey, Value> = Readonly<{
+    treeNodeApi: TreeNodeApi<Id, Value>;
+    cursorApi: CursorApi<Id>;
+    stateApi: StateApi<Id, Value>;
+}>;
+export declare function createAppStateApis<Id extends SerializableKey, Value>(): AppStateApis<Id, Value>;
+//# sourceMappingURL=app-api.d.ts.map

package/dist/app/app-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-api.d.ts","sourceRoot":"","sources":["../../src/app/app-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EACV,SAAS,EAAE,QAAQ,EAAE,UAAU,EAC/B,eAAe,EACf,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAO3B;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,IAAI,QAAQ,CAAC;IACjF;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,EAAE,CAAC;IAEX;;;;;OAKG;IACH,YAAY,EAAE,CACZ,IAAI,EAAE,SAAS,EAAE,EAAE,KAChB,OAAO,CAAC,SAAS,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IAExD;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAEvB,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;IAEzB,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAE9B;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAElC,OAAO,EAAE,OAAO,CAAC;IAEjB,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;CAC7C,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,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC;IACzB,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CAC/B,CAAC,CAAC;AAEH,wBAAgB,kBAAkB,CAChC,EAAE,SAAS,eAAe,EAC1B,KAAK,KACF,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,CAU3B"}

package/dist/app/app-api.js

@@ -0,0 +1,11 @@
+import { createCursorApi, createStateApi, createTreeNodeApi, } from '../trees/index.js';
+export function createAppStateApis() {
+    const treeNodeApi = createTreeNodeApi();
+    const cursorApi = createCursorApi();
+    const stateApi = createStateApi(treeNodeApi, cursorApi);
+    return {
+        treeNodeApi,
+        cursorApi,
+        stateApi,
+    };
+}

package/dist/app/effect-to-action.d.ts

@@ -0,0 +1,6 @@
+import type { CursorApi, NavBranch, NavNodeApi, SerializableKey, State } from '../trees/index.js';
+import type { EffectAction } from '../input/domain/index.js';
+import type { ReducerAction } from './reducer-action.js';
+export type EffectToAction<Id extends SerializableKey, Value> = (effectAction: EffectAction<Id, Value>, navigation: NavBranch<Id>, state: State<Id, Value>) => ReducerAction<Id, Value> | undefined;
+export declare function createEffectToAction<Id extends SerializableKey, Value>(cursorApi: CursorApi<Id>, navNodeApi: NavNodeApi<Id, Value>): EffectToAction<Id, Value>;
+//# sourceMappingURL=effect-to-action.d.ts.map

package/dist/app/effect-to-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-to-action.d.ts","sourceRoot":"","sources":["../../src/app/effect-to-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,EACf,KAAK,EACN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,CAC9D,YAAY,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,EACrC,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC,EACzB,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,KACpB,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;AAE1C,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACpE,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,EACxB,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,GAChC,cAAc,CAAC,EAAE,EAAE,KAAK,CAAC,CA+F3B"}

package/dist/app/effect-to-action.js

@@ -0,0 +1,74 @@
+export function createEffectToAction(cursorApi, navNodeApi) {
+    function effectToAction(effectAction, navigation, state) {
+        switch (effectAction.effectActionType) {
+            case 'nextEntry': {
+                const cursor = navNodeApi.nextCursor(navigation, state.cursor);
+                return cursor === undefined
+                    ? undefined
+                    : {
+                        kind: 'changeCursor',
+                        cursor,
+                    };
+            }
+            case 'prevEntry': {
+                const cursor = navNodeApi.previousCursor(navigation, state.cursor);
+                return cursor === undefined
+                    ? undefined
+                    : {
+                        kind: 'changeCursor',
+                        cursor,
+                    };
+            }
+            case 'setBranchEntries':
+                return {
+                    kind: 'updateBranch',
+                    path: effectAction.path,
+                    entries: effectAction.entries,
+                };
+            case 'navigateToParent': {
+                const navNode = navigation.children;
+                if (navNode === null) {
+                    return undefined;
+                }
+                const cursor = navNodeApi.parentCursor(navNode, state.cursor);
+                return cursor === undefined
+                    ? undefined
+                    : {
+                        kind: 'changeCursor',
+                        cursor,
+                    };
+            }
+            case 'fold': {
+                if (state.cursor.length === 0) {
+                    return undefined;
+                }
+                const cursor = navNodeApi.cursorAfterFold(navigation, state.cursor);
+                if (cursor === undefined) {
+                    return undefined;
+                }
+                return {
+                    kind: 'fold',
+                    path: state.cursor,
+                    cursor,
+                };
+            }
+            case 'unfold': {
+                const currentPath = cursorApi.getPath(state.cursor);
+                const navNode = navigation.children;
+                if (navNode === null) {
+                    return undefined;
+                }
+                const node = navNodeApi.getNodeAtPath(navNode, currentPath);
+                if (node === undefined || node.folded?.entries.length === 0) {
+                    return undefined;
+                }
+                return {
+                    kind: 'unfold',
+                    path: currentPath,
+                    cursor: state.cursor,
+                };
+            }
+        }
+    }
+    return effectToAction;
+}

package/dist/app/index.d.ts

@@ -0,0 +1,6 @@
+export * from './app-api.js';
+export * from './effect-to-action.js';
+export * from './reducer.js';
+export * from './reducer-action.js';
+export * from './view-api.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC"}

package/dist/app/index.js

@@ -0,0 +1,5 @@
+export * from './app-api.js';
+export * from './effect-to-action.js';
+export * from './reducer.js';
+export * from './reducer-action.js';
+export * from './view-api.js';

package/dist/app/reducer-action.d.ts

@@ -0,0 +1,22 @@
+import type { Cursor, SerializableKey, State, TreeNode } from '../trees/index.js';
+export type ReducerAction<Id extends SerializableKey, Value> = {
+    kind: 'changeCursor';
+    cursor: Cursor<Id>;
+} | {
+    kind: 'updateBranch';
+    path: readonly Id[];
+    entries: readonly TreeNode<Id, Value>[] | null;
+} | {
+    kind: 'setState';
+    oldState: State<Id, Value>;
+    newState: State<Id, Value>;
+} | {
+    kind: 'fold';
+    path: readonly Id[];
+    cursor: Cursor<Id>;
+} | {
+    kind: 'unfold';
+    path: readonly Id[];
+    cursor: Cursor<Id>;
+};
+//# sourceMappingURL=reducer-action.d.ts.map

package/dist/app/reducer-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer-action.d.ts","sourceRoot":"","sources":["../../src/app/reducer-action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElF,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IACvD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;CACpB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;IACpB,OAAO,EAAE,SAAS,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC;CAChD,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC3B,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CAC5B,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;CACpB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;CACpB,CAAC"}

package/dist/app/reducer.d.ts

@@ -0,0 +1,5 @@
+import type { FoldsApi, SerializableKey, State, TreeNodeApi } from '../trees/index.js';
+import type { ReducerAction } from './reducer-action.js';
+export type Reducer<Id extends SerializableKey, Value> = (state: State<Id, Value>, action: ReducerAction<Id, Value>) => State<Id, Value>;
+export declare function createReducer<Id extends SerializableKey, Value>(treeNodeApi: TreeNodeApi<Id, Value>, foldsApi: FoldsApi<Id>): Reducer<Id, Value>;
+//# sourceMappingURL=reducer.d.ts.map

package/dist/app/reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer.d.ts","sourceRoot":"","sources":["../../src/app/reducer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,KAAK,EACL,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,CACvD,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EACvB,MAAM,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,KAC7B,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AAEtB,wBAAgB,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC7D,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,GACrB,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CA2GpB"}

package/dist/app/reducer.js

@@ -0,0 +1,79 @@
+export function createReducer(treeNodeApi, foldsApi) {
+    /*
+     * The current zc/zo input actions operate on the required primary fold tree.
+     * Indexed fold-tree commands can add an index to ReducerAction later.
+     */
+    const primaryFoldIndex = 0;
+    return (state, action) => {
+        switch (action.kind) {
+            case 'changeCursor':
+                return {
+                    ...state,
+                    cursor: action.cursor,
+                };
+            case 'updateBranch': {
+                const root = treeNodeApi.updateAtPath(state.root, action.path, (node) => {
+                    /*
+                     * Loading/unloading is a branch-only operation. TreeNodeApi can
+                     * structurally convert any node, but the application reducer must
+                     * not turn a leaf into a branch.
+                     */
+                    if (treeNodeApi.kind(node) === 'leaf') {
+                        return undefined;
+                    }
+                    if (action.entries === null) {
+                        return treeNodeApi.toUnloadedBranch(node);
+                    }
+                    return treeNodeApi.withLoadedChildren(node, action.entries);
+                });
+                /*
+                 * State requires its root to remain a loaded branch. In particular,
+                 * refuse an accidental updateBranch with path [] and entries null.
+                 */
+                if (root === undefined || treeNodeApi.kind(root) !== 'loaded-branch') {
+                    return state;
+                }
+                return {
+                    ...state,
+                    root,
+                };
+            }
+            case 'setState': {
+                // A newer update has already been applied.
+                if (state !== action.oldState) {
+                    return state;
+                }
+                return {
+                    ...action.newState,
+                };
+            }
+            case 'fold': {
+                const entryId = action.path.at(-1);
+                if (entryId === undefined) {
+                    return state;
+                }
+                const parentPath = action.path.slice(0, -1);
+                const folds = foldsApi.hideEntryAtPath(state.folds, primaryFoldIndex, parentPath, entryId);
+                if (folds === undefined) {
+                    return state;
+                }
+                return {
+                    ...state,
+                    folds,
+                    cursor: action.cursor,
+                };
+            }
+            case 'unfold': {
+                const folds = foldsApi.showAllHiddenEntriesAtPath(state.folds, primaryFoldIndex, action.path);
+                if (folds === undefined) {
+                    return state;
+                }
+                return {
+                    ...state,
+                    folds,
+                    cursor: action.cursor,
+                };
+            }
+        }
+    };
+}

package/dist/app/view-api.d.ts

@@ -0,0 +1,11 @@
+export type ViewSummary = {
+    name: string;
+    updatedAt: string;
+};
+export type ViewApi<State, Key> = {
+    save: (key: Key, name: string, state: State) => Promise<void>;
+    load: (key: Key, name: string) => Promise<State | undefined>;
+    list: (key: Key) => Promise<readonly ViewSummary[]>;
+    remove: (key: Key, name: string) => Promise<void>;
+};
+//# sourceMappingURL=view-api.d.ts.map

package/dist/app/view-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-api.d.ts","sourceRoot":"","sources":["../../src/app/view-api.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI;IAChC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IAC7D,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IACpD,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,5 @@
-export * from './tree-surfer-ui/application/user-input-to-intent.js';
-export * from './tree-surfer-ui/application/intent-to-effect.js';
-export * from './tree-surfer-ui/domain/effect.js';
-export * from './tree-surfer-ui/domain/input-mode-state.js';
-export * from './tree-surfer-ui/domain/intent.js';
-export * from './tree-surfer-ui/domain/user-input.js';
-export * from './tree-surfer/index.js';
+export * from './app/index.js';
+export * from './input/application/index.js';
+export * from './input/domain/index.js';
+export * from './trees/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sDAAsD,CAAC;AACrE,cAAc,kDAAkD,CAAC;AAEjE,cAAc,mCAAmC,CAAC;AAClD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AAEtD,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAE/B,cAAc,8BAA8B,CAAC;AAE7C,cAAc,yBAAyB,CAAC;AAExC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -1,7 +1,4 @@
-export * from './tree-surfer-ui/application/user-input-to-intent.js';
-export * from './tree-surfer-ui/application/intent-to-effect.js';
-export * from './tree-surfer-ui/domain/effect.js';
-export * from './tree-surfer-ui/domain/input-mode-state.js';
-export * from './tree-surfer-ui/domain/intent.js';
-export * from './tree-surfer-ui/domain/user-input.js';
-export * from './tree-surfer/index.js';
+export * from './app/index.js';
+export * from './input/application/index.js';
+export * from './input/domain/index.js';
+export * from './trees/index.js';

package/dist/input/application/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/input/application/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC"}

package/dist/input/application/intent-to-effect-no-state.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-to-effect-no-state.test.d.ts","sourceRoot":"","sources":["../../../src/input/application/intent-to-effect-no-state.test.ts"],"names":[],"mappings":""}

package/dist/input/application/intent-to-effect.d.ts

@@ -0,0 +1,14 @@
+import type { CursorApi, SerializableKey, State, StateApi, TreeNodeApi } from '../../trees/index.js';
+import type { Effect, Intent } from '../domain/index.js';
+/**
+ * Converts a user intent and the current tree state into an effect.
+ *
+ * By design, "effect = intent + state": whether an effect should be executed
+ * depends on both the received intent and the current state.
+ *
+ * @typeParam Id - The sibling-unique tree-node ID type.
+ * @typeParam Value - Application-owned data stored in each tree node.
+ */
+export type IntentToEffect<Id extends SerializableKey, Value> = (intent: Intent, state: State<Id, Value>) => Effect<Id, Value> | undefined;
+export declare function createIntentToEffect<Id extends SerializableKey, Value>(stateApi: StateApi<Id, Value>, cursorApi: CursorApi<Id>, treeNodeApi: TreeNodeApi<Id, Value>): IntentToEffect<Id, Value>;
+//# sourceMappingURL=intent-to-effect.d.ts.map

package/dist/input/application/intent-to-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-to-effect.d.ts","sourceRoot":"","sources":["../../../src/input/application/intent-to-effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,KAAK,EACL,QAAQ,EACR,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAIvE;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,CAC9D,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,KACpB,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;AAEnC,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACpE,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAC7B,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,EACxB,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,GAClC,cAAc,CAAC,EAAE,EAAE,KAAK,CAAC,CAkE3B"}

package/dist/{tree-surfer-ui → input}/application/intent-to-effect.js

@@ -7,7 +7,7 @@ export function createIntentToEffect(stateApi, cursorApi, treeNodeApi) {
             case 'normalRight':
                 return normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi);
             case 'normalLeft':
-                return normalInteractLeftToEffect(state);
+                return normalInteractLeftToEffect(state, cursorApi);
             case 'normalDown':
                 return dispatchAction({
                     effectActionType: 'nextEntry',
@@ -57,11 +57,15 @@ function dispatchAction(action) {
         action,
     };
 }
-// Sets the buffer. Three possibilities:
-// - New command buffer is recognized as a motion, this dispatches the
-// "effect action". Consumer will know to reset the input state.
-// - Prefix of a possible motion, updates normal buffer.
-// - Not a prefix, clears the buffer.
+/**
+ * Sets the normal-mode command buffer.
+ *
+ * Three possibilities:
+ *
+ * - The buffer is a recognized motion: dispatch its effect action.
+ * - The buffer is a prefix of a possible motion: retain it.
+ * - The buffer is not a valid prefix: clear it.
+ */
 function normalBufferToEffectResult(updatedNormalBuffer) {
     switch (updatedNormalBuffer) {
         case 'z':
@@ -90,6 +94,13 @@ function normalBufferToEffectResult(updatedNormalBuffer) {
             };
     }
 }
+/**
+ * Handles normal-mode right interaction.
+ *
+ * - A closed branch requests loading its children.
+ * - An open branch dispatches an action that closes/unloads its children.
+ * - A leaf has no right-interaction effect.
+ */
 function normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi) {
     const currentEntry = stateApi.getNodeAtCursor(state);
     if (currentEntry === undefined) {
@@ -99,23 +110,31 @@ function normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi) {
     if (path === undefined) {
         return undefined;
     }
-    if (treeNodeApi.isBranch(currentEntry)) {
-        if (currentEntry.children === null) {
+    switch (treeNodeApi.kind(currentEntry)) {
+        case 'unloaded-branch':
             return {
                 effectType: 'loadBranchEntries',
                 path,
             };
-        }
-        return dispatchAction({
-            effectActionType: 'setBranchEntries',
-            path,
-            entries: null,
-        });
+        case 'loaded-branch':
+            return dispatchAction({
+                effectActionType: 'setBranchEntries',
+                path,
+                entries: null,
+            });
+        case 'leaf':
+            return undefined;
     }
-    return;
 }
-function normalInteractLeftToEffect(state) {
-    if (state.cursor.length === 0) {
+/**
+ * Handles normal-mode left interaction.
+ *
+ * Left from the root has no effect. Otherwise dispatch navigation to the
+ * parent entry.
+ */
+function normalInteractLeftToEffect(state, cursorApi) {
+    const path = cursorApi.getPath(state.cursor);
+    if (path === undefined || path.length === 0) {
         return undefined;
     }
     return dispatchAction({

package/dist/input/application/parse-command.d.ts

@@ -0,0 +1,14 @@
+import type { SerializableKey } from '../../trees/index.js';
+import type { Effect } from '../domain/index.js';
+/**
+ * Parses a command-line command into an application effect.
+ *
+ * Command parsing is independent of the concrete tree-node value type, but the
+ * generic parameters allow its result to compose with the application's
+ * Effect<Id, Value> pipeline.
+ *
+ * @typeParam Id - The sibling-unique tree-node ID type.
+ * @typeParam Value - Application-owned data stored in each tree node.
+ */
+export declare function parseCommand<Id extends SerializableKey, Value>(commandLine: string): Effect<Id, Value> | undefined;
+//# sourceMappingURL=parse-command.d.ts.map

package/dist/input/application/parse-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-command.d.ts","sourceRoot":"","sources":["../../../src/input/application/parse-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAIjD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC5D,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAwD/B"}

package/dist/{tree-surfer-ui → input}/application/parse-command.js

@@ -1,4 +1,14 @@
 const DEFAULT_VIEW_NAME = 'default';
+/**
+ * Parses a command-line command into an application effect.
+ *
+ * Command parsing is independent of the concrete tree-node value type, but the
+ * generic parameters allow its result to compose with the application's
+ * Effect<Id, Value> pipeline.
+ *
+ * @typeParam Id - The sibling-unique tree-node ID type.
+ * @typeParam Value - Application-owned data stored in each tree node.
+ */
 export function parseCommand(commandLine) {
     const command = commandLine.trim();
     switch (command) {
@@ -23,7 +33,7 @@ export function parseCommand(commandLine) {
      * The name may contain spaces, so capture the remainder of the command
      * instead of splitting on whitespace.
      *
-     * TODO Later: mkview that checks if same named view already saved
+     * TODO Later: mkview that checks if a same-named view already exists.
      */
     const viewCommand = command.match(/^:(mkview!|loadview)(?:\s+(.+?))?$/);
     if (viewCommand === null) {
@@ -44,5 +54,7 @@ export function parseCommand(commandLine) {
                 effectType: 'loadView',
                 name,
             };
+        default:
+            return undefined;
     }
 }

package/dist/input/application/user-input-to-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-input-to-intent.d.ts","sourceRoot":"","sources":["../../../src/input/application/user-input-to-intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,cAAc,GAC7B,MAAM,GAAG,SAAS,CAQpB"}

package/dist/input/application/user-input-to-intent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-input-to-intent.test.d.ts","sourceRoot":"","sources":["../../../src/input/application/user-input-to-intent.test.ts"],"names":[],"mappings":""}

package/dist/input/domain/effect.d.ts

@@ -0,0 +1,55 @@
+import type { InputModeState } from './input-mode-state.js';
+import type { SerializableKey, TreeNode } from '../../trees/index.js';
+/**
+ * An effect produced by interpreting an intent against the current state.
+ *
+ * @typeParam Id - The sibling-unique tree-node ID type.
+ * @typeParam Value - Application-owned data stored in each tree node.
+ */
+export type Effect<Id extends SerializableKey, Value> = Readonly<{
+    effectType: 'dispatchEffectAction';
+    action: EffectAction<Id, Value>;
+}> | Readonly<{
+    effectType: 'loadBranchEntries';
+    path: readonly Id[];
+}> | Readonly<{
+    effectType: 'peekFold';
+    parentPath: readonly Id[];
+}> | Readonly<{
+    effectType: 'saveView';
+    name: string;
+    overwrite: boolean;
+}> | Readonly<{
+    effectType: 'loadView';
+    name: string;
+}> | Readonly<{
+    effectType: 'emitVisibleLeavesPaths';
+}> | Readonly<{
+    effectType: 'quit';
+    exitMessage: string;
+}> | Readonly<{
+    effectType: 'setInputState';
+    inputState: InputModeState;
+}>;
+/**
+ * An action interpreted by the state reducer.
+ *
+ * @typeParam Id - The sibling-unique tree-node ID type.
+ * @typeParam Value - Application-owned data stored in each tree node.
+ */
+export type EffectAction<Id extends SerializableKey, Value> = Readonly<{
+    effectActionType: 'nextEntry';
+}> | Readonly<{
+    effectActionType: 'prevEntry';
+}> | Readonly<{
+    effectActionType: 'setBranchEntries';
+    path: readonly Id[];
+    entries: readonly TreeNode<Id, Value>[] | null;
+}> | Readonly<{
+    effectActionType: 'navigateToParent';
+}> | Readonly<{
+    effectActionType: 'fold';
+}> | Readonly<{
+    effectActionType: 'unfold';
+}>;
+//# sourceMappingURL=effect.d.ts.map

package/dist/input/domain/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../../../src/input/domain/effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAChD,QAAQ,CAAC;IACP,UAAU,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CACjC,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,mBAAmB,CAAC;IAChC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;CACrB,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,SAAS,EAAE,EAAE,CAAC;CAC3B,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,wBAAwB,CAAC;CACtC,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,GACF,QAAQ,CAAC;IACP,UAAU,EAAE,eAAe,CAAC;IAC5B,UAAU,EAAE,cAAc,CAAC;CAC5B,CAAC,CAAC;AAEP;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IACtD,QAAQ,CAAC;IACP,gBAAgB,EAAE,WAAW,CAAC;CAC/B,CAAC,GACF,QAAQ,CAAC;IACP,gBAAgB,EAAE,WAAW,CAAC;CAC/B,CAAC,GACF,QAAQ,CAAC;IACP,gBAAgB,EAAE,kBAAkB,CAAC;IACrC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC;IACpB,OAAO,EAAE,SAAS,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC;CAChD,CAAC,GACF,QAAQ,CAAC;IACP,gBAAgB,EAAE,kBAAkB,CAAC;CACtC,CAAC,GACF,QAAQ,CAAC;IACP,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC,GACF,QAAQ,CAAC;IACP,gBAAgB,EAAE,QAAQ,CAAC;CAC5B,CAAC,CAAC"}

package/dist/input/domain/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/input/domain/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/dist/input/domain/input-mode-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-mode-state.d.ts","sourceRoot":"","sources":["../../../src/input/domain/input-mode-state.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GACtB;IACE,SAAS,EAAE,QAAQ,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,GACD;IACE,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC"}

package/dist/input/domain/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../../src/input/domain/intent.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GACxB;IACE,UAAU,EAAE,aAAa,CAAC;CAC3B,GACD;IACE,UAAU,EAAE,YAAY,CAAC;CAC1B,GACD;IACE,UAAU,EAAE,YAAY,CAAC;CAC1B,GACD;IACE,UAAU,EAAE,UAAU,CAAC;CACxB,GACD;IACE,UAAU,EAAE,iBAAiB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,MAAM,MAAM,iBAAiB,GACzB;IACE,UAAU,EAAE,sBAAsB,CAAC;CACpC,GACD;IACE,UAAU,EAAE,gBAAgB,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,UAAU,EAAE,oBAAoB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;CACrB,GACD;IACE,UAAU,EAAE,qBAAqB,CAAC;CACnC,CAAC"}

package/dist/input/domain/user-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-input.d.ts","sourceRoot":"","sources":["../../../src/input/domain/user-input.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB;IACE,aAAa,EAAE,WAAW,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,aAAa,EAAE,OAAO,CAAC;CACxB,GACD;IACE,aAAa,EAAE,WAAW,CAAC;CAC5B,GACD;IACE,aAAa,EAAE,KAAK,CAAC;CACtB,GACD;IACE,aAAa,EAAE,YAAY,CAAC;CAC7B,GACD;IACE,aAAa,EAAE,WAAW,CAAC;CAC5B,GACD;IACE,aAAa,EAAE,WAAW,CAAC;CAC5B,GACD;IACE,aAAa,EAAE,SAAS,CAAC;CAC1B,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/trees/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,MAAM,CAAC,EAAE,IAAI,SAAS,EAAE,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,CAAC,CAAC,UAAU,EAC9D,QAAQ,EAAE,QAAQ,wBAGnB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,EAAE,IAAI;IAC1B;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;IAEpD;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;IAElC;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,GAAG,OAAO,CAAC;CAC/E,CAAC;AAEF,wBAAgB,eAAe,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,CAAC,CAcnD"}

package/dist/trees/fold-node/deprecated/fold-node.impl.d.ts

@@ -0,0 +1,10 @@
+import type { FoldNodeApi, FoldNodeService } from './fold-node.types.js';
+import type { SerializableKey } from '../../tree-node/index.js';
+/**
+ * Creates semantic operations for a fold-state tree.
+ *
+ * Structural children are owned by `FoldNodeApi`; folded children are
+ * application-owned FoldNode values stored in `FoldNodeValue`.
+ */
+export declare function createFoldNodeService<Id extends SerializableKey>(foldNodeApi: FoldNodeApi<Id>): FoldNodeService<Id>;
+//# sourceMappingURL=fold-node.impl.d.ts.map

package/dist/trees/fold-node/deprecated/fold-node.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-node.impl.d.ts","sourceRoot":"","sources":["../../../../src/trees/fold-node/deprecated/fold-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EACX,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,SAAS,eAAe,EAC9D,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,GAC3B,eAAe,CAAC,EAAE,CAAC,CA0WrB"}