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

package/dist/app/reducer/reducer.js

@@ -1,24 +1,76 @@
-function firstAvailableAdditionalFoldIndex(foldsApi, state) {
+function firstAvailableAdditionalFoldIndex(foldsApi, folds) {
     let index = 1;
-    while (foldsApi.hasAtIndex(state.folds, index)) {
+    while (foldsApi.hasAtIndex(folds, index)) {
         index += 1;
     }
     return index;
 }
-export function createReducer(treeNodeApi, foldsApi) {
+export function createReducer(stateApi, navNodeApi) {
+    const { treeNodeApi, foldsApi, cursorApi } = stateApi;
+    /**
+     * Preserve the cursor if its position remains navigable. Otherwise, move it
+     * to a fold marker containing its representative entry, or to the nearest
+     * visible ancestor.
+     */
+    function reconcileCursor(state) {
+        const navigation = navNodeApi.from(stateApi.getRoot(state), stateApi.getFolds(state));
+        if (navigation === undefined || navigation.children === null) {
+            // StateApi guarantees that the root is a loaded branch.
+            throw new Error('Cannot navigate state: root is not a loaded branch.');
+        }
+        const cursor = stateApi.getCursor(state);
+        const positions = [
+            { path: [] },
+            ...navNodeApi.cursors(navigation.children),
+        ];
+        if (positions.some((position) => cursorApi.equal(position, cursor))) {
+            return state;
+        }
+        const path = cursorApi.getPath(cursor);
+        while (path.length > 0) {
+            const entryId = path.at(-1);
+            if (entryId !== undefined) {
+                const parentPath = path.slice(0, -1);
+                const parent = navNodeApi.getNodeAtPath(navigation.children, parentPath);
+                const foldEntry = parent?.entries.find((entry) => navNodeApi.entryIsFold(entry) &&
+                    entry.folded.some((foldedEntry) => !navNodeApi.entryIsFold(foldedEntry) &&
+                        foldedEntry.id === entryId));
+                if (foldEntry !== undefined && navNodeApi.entryIsFold(foldEntry)) {
+                    const firstEntry = foldEntry.folded.find((entry) => !navNodeApi.entryIsFold(entry));
+                    if (firstEntry !== undefined && !navNodeApi.entryIsFold(firstEntry)) {
+                        const foldCursor = {
+                            parentPath,
+                            firstId: firstEntry.id,
+                        };
+                        if (positions.some((position) => cursorApi.equal(position, foldCursor))) {
+                            return stateApi.update(state, { cursor: foldCursor }) ?? state;
+                        }
+                    }
+                }
+                const nodeCursor = { path: [...path] };
+                if (positions.some((position) => cursorApi.equal(position, nodeCursor))) {
+                    return stateApi.update(state, { cursor: nodeCursor }) ?? state;
+                }
+            }
+            path.pop();
+        }
+        // The root cursor is always included in `positions`.
+        return stateApi.update(state, { cursor: { path: [] } }) ?? state;
+    }
+    function update(state, changes) {
+        const nextState = stateApi.update(state, changes);
+        return nextState === undefined ? state : reconcileCursor(nextState);
+    }
     return (state, action) => {
         switch (action.kind) {
             case 'changeCursor':
-                return {
-                    ...state,
-                    cursor: action.cursor,
-                };
+                return update(state, { cursor: action.cursor });
             case 'updateBranch': {
-                const root = treeNodeApi.updateAtPath(state.root, action.path, (node) => {
+                const root = treeNodeApi.updateAtPath(stateApi.getRoot(state), 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.
+                     * Loading/unloading is a branch-only operation. TreeMethods can
+                     * structurally convert any node, but the reducer must not turn a
+                     * leaf into a branch.
                      */
                     if (treeNodeApi.kind(node) === 'leaf') {
                         return undefined;
@@ -35,19 +87,14 @@ export function createReducer(treeNodeApi, foldsApi) {
                 if (root === undefined || treeNodeApi.kind(root) !== 'loaded-branch') {
                     return state;
                 }
-                return {
-                    ...state,
-                    root,
-                };
+                return update(state, { root });
             }
             case 'setState': {
                 // A newer update has already been applied.
                 if (state !== action.oldState) {
                     return state;
                 }
-                return {
-                    ...action.newState,
-                };
+                return reconcileCursor(action.newState);
             }
             case 'addToFoldTree': {
                 const entryId = action.path.at(-1);
@@ -55,82 +102,69 @@ export function createReducer(treeNodeApi, foldsApi) {
                     return state;
                 }
                 const parentPath = action.path.slice(0, -1);
-                const folds = foldsApi.hideEntryAtPath(state.folds, action.foldTreeIndex, parentPath, entryId);
+                const folds = foldsApi.hideEntryAtPath(stateApi.getFolds(state), action.foldTreeIndex, parentPath, entryId);
                 if (folds === undefined) {
                     return state;
                 }
-                return {
-                    ...state,
+                return update(state, {
                     folds,
                     cursor: action.cursor,
-                };
+                });
             }
             case 'removeFromFoldTree': {
-                // TODO: Change to show only entry at cursor. mirroring addToFoldTree
-                const folds = foldsApi.showAllHiddenEntriesAtPath(state.folds, action.foldTreeIndex, action.path);
-                if (folds === undefined) {
-                    return state;
+                let folds = stateApi.getFolds(state);
+                if (action.entryIds === null) {
+                    const nextFolds = foldsApi.showAllHiddenEntriesAtPath(folds, action.foldTreeIndex, action.path);
+                    if (nextFolds === undefined) {
+                        return state;
+                    }
+                    folds = nextFolds;
+                }
+                else {
+                    for (const entryId of action.entryIds) {
+                        const nextFolds = foldsApi.showEntryAtPath(folds, action.foldTreeIndex, action.path, entryId);
+                        if (nextFolds === undefined) {
+                            return state;
+                        }
+                        folds = nextFolds;
+                    }
                 }
-                return {
-                    ...state,
+                return update(state, {
                     folds,
                     cursor: action.cursor,
-                };
+                });
             }
             case 'fold': {
-                const folds = foldsApi.activateAtIndex(state.folds, action.foldTreeIndex);
-                return folds === undefined
-                    ? state
-                    : {
-                        ...state,
-                        folds,
-                    };
+                const folds = foldsApi.activateAtIndex(stateApi.getFolds(state), action.foldTreeIndex);
+                return folds === undefined ? state : update(state, { folds });
             }
             case 'unfold': {
-                const folds = foldsApi.deactivateAtIndex(state.folds, action.foldTreeIndex);
-                return folds === undefined
-                    ? state
-                    : {
-                        ...state,
-                        folds,
-                    };
+                const folds = foldsApi.deactivateAtIndex(stateApi.getFolds(state), action.foldTreeIndex);
+                return folds === undefined ? state : update(state, { folds });
             }
             case 'toggleFold': {
-                const folds = foldsApi.toggleActiveAtIndex(state.folds, action.foldTreeIndex);
-                return folds === undefined
-                    ? state
-                    : {
-                        ...state,
-                        folds,
-                    };
+                const folds = foldsApi.toggleActiveAtIndex(stateApi.getFolds(state), action.foldTreeIndex);
+                return folds === undefined ? state : update(state, { folds });
             }
             case 'createFoldTree': {
-                const index = firstAvailableAdditionalFoldIndex(foldsApi, state);
-                const folds = foldsApi.setAdditionalFoldAtIndex(state.folds, index, 
-                // Obtain this through the actual TreeNodeApi root-ID operation.
-                treeNodeApi.id(state.root), {
+                const currentFolds = stateApi.getFolds(state);
+                const index = firstAvailableAdditionalFoldIndex(foldsApi, currentFolds);
+                const folds = foldsApi.setAdditionalFoldAtIndex(currentFolds, index, 
+                // Obtain this through the actual TreeMethods root-ID operation.
+                treeNodeApi.id(stateApi.getRoot(state)), {
                     name: action.name,
                     description: null,
                 });
-                return folds === undefined
-                    ? state
-                    : {
-                        ...state,
-                        folds,
-                    };
+                return folds === undefined ? state : update(state, { folds });
             }
             case 'deleteFoldTree': {
-                const index = foldsApi.getIndexByName(state.folds, action.name);
+                const currentFolds = stateApi.getFolds(state);
+                const index = foldsApi.getIndexByName(currentFolds, action.name);
                 if (index === undefined || index === 0) {
                     return state;
                 }
-                const folds = foldsApi.removeAdditionalFoldAtIndex(state.folds, index);
-                return folds === undefined
-                    ? state
-                    : {
-                        ...state,
-                        folds,
-                    };
+                const folds = foldsApi.removeAdditionalFoldAtIndex(currentFolds, index);
+                return folds === undefined ? state : update(state, { folds });
             }
             default: {
                 const _exhaustive = action;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export * from './trees/index.js';
+export * from './state-and-nav/index.js';
 export * from './feedback/index.js';
 export * from './app/index.js';
 export * from './input/application/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AAEjC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,gBAAgB,CAAC;AAE/B,cAAc,8BAA8B,CAAC;AAE7C,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AAEzC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,gBAAgB,CAAC;AAE/B,cAAc,8BAA8B,CAAC;AAE7C,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export * from './trees/index.js';
+export * from './state-and-nav/index.js';
 export * from './feedback/index.js';
 export * from './app/index.js';
 export * from './input/application/index.js';

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

@@ -1,4 +1,4 @@
-import type { CursorApi, SerializableKey, State, StateApi, TreeNodeApi } from '../../trees/index.js';
+import type { SerializableKey, State, StateApi } from '../../state-and-nav/index.js';
 import type { Effect, Intent } from '../domain/index.js';
 /**
  * Converts a user intent and the current tree state into an effect.
@@ -10,5 +10,5 @@ import type { Effect, Intent } from '../domain/index.js';
  * @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>;
+export declare function createIntentToEffect<Id extends SerializableKey, Value>(registeredCommands: ReadonlySet<string>, stateApi: StateApi<Id, Value>): IntentToEffect<Id, Value>;
 //# sourceMappingURL=intent-to-effect.d.ts.map

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

@@ -1 +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;AAKvE;;;;;;;;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"}
+{"version":3,"file":"intent-to-effect.d.ts","sourceRoot":"","sources":["../../../src/input/application/intent-to-effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,KAAK,EACL,QAAQ,EACT,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAKvE;;;;;;;;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,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,EACvC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAC5B,cAAc,CAAC,EAAE,EAAE,KAAK,CAAC,CAgE3B"}

package/dist/input/application/intent-to-effect.js

@@ -1,14 +1,14 @@
 import { parseExCommand } from './parse-ex-command.js';
 import { parseNormalCommand } from './parse-normal-command.js';
-export function createIntentToEffect(stateApi, cursorApi, treeNodeApi) {
+export function createIntentToEffect(registeredCommands, stateApi) {
     return (intent, state) => {
         switch (intent.intentType) {
             case 'setNormalBuffer':
                 return normalBufferToEffectResult(intent.normalBuffer);
             case 'normalRight':
-                return normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi);
+                return normalInteractRightToEffect(state, stateApi);
             case 'normalLeft':
-                return normalInteractLeftToEffect(state, cursorApi);
+                return normalInteractLeftToEffect(state, stateApi);
             case 'normalDown':
                 return dispatchAction({
                     effectActionType: 'nextEntry',
@@ -42,7 +42,7 @@ export function createIntentToEffect(stateApi, cursorApi, treeNodeApi) {
                     },
                 };
             case 'executeCommandLine':
-                return (parseExCommand(intent.commandLine) ?? {
+                return (parseExCommand(intent.commandLine, registeredCommands) ?? {
                     effectType: 'setInputState',
                     inputState: {
                         inputMode: 'normal',
@@ -106,16 +106,16 @@ function normalBufferToEffectResult(updatedNormalBuffer) {
  * - An open branch dispatches an action that closes/unloads its children.
  * - A leaf has no right-interaction effect.
  */
-function normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi) {
+function normalInteractRightToEffect(state, stateApi) {
     const currentEntry = stateApi.getNodeAtCursor(state);
     if (currentEntry === undefined) {
         return undefined;
     }
-    const path = cursorApi.getPath(state.cursor);
+    const path = stateApi.cursorPath(state);
     if (path === undefined) {
         return undefined;
     }
-    switch (treeNodeApi.kind(currentEntry)) {
+    switch (stateApi.treeNodeApi.kind(currentEntry)) {
         case 'unloaded-branch':
             return {
                 effectType: 'loadBranchEntries',
@@ -137,9 +137,8 @@ function normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi) {
  * 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) {
+function normalInteractLeftToEffect(state, stateApi) {
+    if (stateApi.isCursorRoot(state)) {
         return undefined;
     }
     return dispatchAction({

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

@@ -1,22 +1,30 @@
-import type { SerializableKey } from '../../trees/index.js';
+import type { SerializableKey } from '../../state-and-nav/index.js';
 import type { Effect } from '../domain/index.js';
 /**
  * Parses a Vim-style Ex command line into an application effect.
  *
- * Leading and trailing whitespace is removed, and all consecutive leading `:`
- * characters are removed before parsing. The remaining text is split on one or
- * more whitespace characters:
+ * Leading and trailing whitespace is removed, followed by all consecutive
+ * leading `:` characters. The remaining text is split on one or more
+ * whitespace characters:
  *
  * - The first token is treated as the command name.
- * - All remaining tokens are passed to the command-specific parser as
- *   `commandArgs`.
+ * - All remaining tokens are treated as command arguments.
+ *
+ * Registered user commands are matched by exact name before built-in commands,
+ * allowing them to override built-ins. A match produces a `userExCommand`
+ * effect containing the registered name and argument tokens. This function
+ * neither looks up nor executes the registered callback.
+ *
+ * Otherwise, the command is interpreted as a built-in, with its arguments
+ * passed to the command-specific parser where applicable.
  *
  * Parsing is token-based and does not support quoted or escaped arguments.
  * Consequently, whitespace within an argument cannot currently be preserved.
- * Command-specific parsers are responsible for validating their arguments.
+ * Built-in argument validation is handled by the command-specific parsers;
+ * registered user-command arguments are forwarded without validation.
  *
- * An empty command line produces `undefined`. An unknown command produces an
- * `unrecognizedCommand` effect containing the original `commandLine`.
+ * An empty command produces `undefined`. An unknown command produces an
+ * `emitError` effect whose message includes the original `commandLine`.
  *
  * Command parsing is independent of the concrete tree-node value type, but the
  * generic parameters allow its result to compose with the application's
@@ -24,9 +32,11 @@ import type { Effect } from '../domain/index.js';
  *
  * @typeParam Id - The sibling-unique tree-node ID type.
  * @typeParam Value - Application-owned data stored in each tree node.
- * @param commandLine - The raw Ex command line, optionally prefixed with one
- * or more `:` characters.
+ * @param commandLine - The raw Ex command line, whitespace before or after,
+ * optionally prefixed with one or more `:` characters.
+ * @param registeredCommands - Registered user-command names that take
+ * precedence over built-in commands.
  * @returns The parsed application effect, or `undefined` for an empty command.
  */
-export declare function parseExCommand<Id extends SerializableKey, Value>(commandLine: string): Effect<Id, Value> | undefined;
+export declare function parseExCommand<Id extends SerializableKey, Value>(commandLine: string, registeredCommands: ReadonlySet<string>): Effect<Id, Value> | undefined;
 //# sourceMappingURL=parse-ex-command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parse-ex-command.d.ts","sourceRoot":"","sources":["../../../src/input/application/parse-ex-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAmKjD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC9D,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CA4D/B"}
+{"version":3,"file":"parse-ex-command.d.ts","sourceRoot":"","sources":["../../../src/input/application/parse-ex-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AA6IjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC9D,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,GACtC,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAoE/B"}

package/dist/input/application/parse-ex-command.js

@@ -1,25 +1,23 @@
-const DEFAULT_VIEW_NAME = 'default';
+// const DEFAULT_VIEW_NAME = 'default';
 const DEFAULT_FOLD_TREE_NAME = 'default';
 function parseAppCommand(commandArgs) {
     const [firstArgument, ...remainingArguments] = commandArgs;
+    const badArgs = {
+        effectType: 'emitError',
+        message: `Unrecognized command arguments: app ${commandArgs.join(' ')}`,
+    };
     switch (firstArgument) {
         case 'list':
             return commandArgs.length === 1
                 ? {
                     effectType: 'listApps',
                 }
-                : {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `app ${commandArgs.join(' ')}`,
-                };
+                : badArgs;
         case 'open':
         case 'switch': {
             const [appId, input] = remainingArguments;
             if (appId === undefined || remainingArguments.length > 2) {
-                return {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `app ${commandArgs.join(' ')}`,
-                };
+                return badArgs;
             }
             return {
                 effectType: 'switchApp',
@@ -29,10 +27,7 @@ function parseAppCommand(commandArgs) {
         }
         default: {
             if (firstArgument === undefined || remainingArguments.length > 1) {
-                return {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `app ${commandArgs.join(' ')}`,
-                };
+                return badArgs;
             }
             const input = remainingArguments[0];
             return {
@@ -45,22 +40,20 @@ function parseAppCommand(commandArgs) {
 }
 function parseFoldCommand(commandArgs) {
     const [subcommand, name] = commandArgs;
+    const badArgs = {
+        effectType: 'emitError',
+        message: `Unrecognized command arguments: fold ${commandArgs.join(' ')}`,
+    };
     switch (subcommand) {
         case 'list':
             return commandArgs.length === 1
                 ? {
                     effectType: 'listFolds',
                 }
-                : {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `fold ${commandArgs.join(' ')}`,
-                };
+                : badArgs;
         case 'create':
             return name === undefined || commandArgs.length !== 2
-                ? {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `fold ${commandArgs.join(' ')}`,
-                }
+                ? badArgs
                 : {
                     effectType: 'dispatchEffectAction',
                     action: {
@@ -70,10 +63,7 @@ function parseFoldCommand(commandArgs) {
                 };
         case 'delete':
             return name === undefined || commandArgs.length !== 2
-                ? {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `fold ${commandArgs.join(' ')}`,
-                }
+                ? badArgs
                 : {
                     effectType: 'dispatchEffectAction',
                     action: {
@@ -84,10 +74,7 @@ function parseFoldCommand(commandArgs) {
         case 'enable':
         case 'close':
             return commandArgs.length > 2
-                ? {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `fold ${commandArgs.join(' ')}`,
-                }
+                ? badArgs
                 : {
                     effectType: 'dispatchEffectAction',
                     action: {
@@ -101,10 +88,7 @@ function parseFoldCommand(commandArgs) {
         case 'disable':
         case 'open':
             return commandArgs.length > 2
-                ? {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `fold ${commandArgs.join(' ')}`,
-                }
+                ? badArgs
                 : {
                     effectType: 'dispatchEffectAction',
                     action: {
@@ -117,10 +101,7 @@ function parseFoldCommand(commandArgs) {
                 };
         case 'toggle':
             return commandArgs.length > 2
-                ? {
-                    effectType: 'unrecognizedCommand',
-                    commandLine: `fold ${commandArgs.join(' ')}`,
-                }
+                ? badArgs
                 : {
                     effectType: 'dispatchEffectAction',
                     action: {
@@ -132,29 +113,34 @@ function parseFoldCommand(commandArgs) {
                     },
                 };
         default:
-            return {
-                effectType: 'unrecognizedCommand',
-                commandLine: `fold ${commandArgs.join(' ')}`,
-            };
+            return badArgs;
     }
 }
 /**
  * Parses a Vim-style Ex command line into an application effect.
  *
- * Leading and trailing whitespace is removed, and all consecutive leading `:`
- * characters are removed before parsing. The remaining text is split on one or
- * more whitespace characters:
+ * Leading and trailing whitespace is removed, followed by all consecutive
+ * leading `:` characters. The remaining text is split on one or more
+ * whitespace characters:
  *
  * - The first token is treated as the command name.
- * - All remaining tokens are passed to the command-specific parser as
- *   `commandArgs`.
+ * - All remaining tokens are treated as command arguments.
+ *
+ * Registered user commands are matched by exact name before built-in commands,
+ * allowing them to override built-ins. A match produces a `userExCommand`
+ * effect containing the registered name and argument tokens. This function
+ * neither looks up nor executes the registered callback.
+ *
+ * Otherwise, the command is interpreted as a built-in, with its arguments
+ * passed to the command-specific parser where applicable.
  *
  * Parsing is token-based and does not support quoted or escaped arguments.
  * Consequently, whitespace within an argument cannot currently be preserved.
- * Command-specific parsers are responsible for validating their arguments.
+ * Built-in argument validation is handled by the command-specific parsers;
+ * registered user-command arguments are forwarded without validation.
  *
- * An empty command line produces `undefined`. An unknown command produces an
- * `unrecognizedCommand` effect containing the original `commandLine`.
+ * An empty command produces `undefined`. An unknown command produces an
+ * `emitError` effect whose message includes the original `commandLine`.
  *
  * Command parsing is independent of the concrete tree-node value type, but the
  * generic parameters allow its result to compose with the application's
@@ -162,16 +148,25 @@ function parseFoldCommand(commandArgs) {
  *
  * @typeParam Id - The sibling-unique tree-node ID type.
  * @typeParam Value - Application-owned data stored in each tree node.
- * @param commandLine - The raw Ex command line, optionally prefixed with one
- * or more `:` characters.
+ * @param commandLine - The raw Ex command line, whitespace before or after,
+ * optionally prefixed with one or more `:` characters.
+ * @param registeredCommands - Registered user-command names that take
+ * precedence over built-in commands.
  * @returns The parsed application effect, or `undefined` for an empty command.
  */
-export function parseExCommand(commandLine) {
+export function parseExCommand(commandLine, registeredCommands) {
     const command = commandLine.trim().replace(/^:+/, '');
     if (command === '') {
         return undefined;
     }
     const [commandName, ...commandArgs] = command.split(/\s+/);
+    if (commandName !== undefined && registeredCommands.has(commandName)) {
+        return {
+            effectType: 'userExCommand',
+            name: commandName,
+            args: commandArgs,
+        };
+    }
     switch (commandName) {
         case 'q':
             return {
@@ -186,21 +181,22 @@ export function parseExCommand(commandLine) {
             return {
                 effectType: 'emitVisibleLeavesPaths',
             };
-        case 'mkview!':
-            return {
-                effectType: 'saveView',
-                name: commandArgs[0] || DEFAULT_VIEW_NAME,
-                overwrite: true,
-            };
-        case 'loadview':
-            return {
-                effectType: 'loadView',
-                name: commandArgs[0] || DEFAULT_VIEW_NAME,
-            };
+        // case 'mkview!':
+        //   return {
+        //     effectType: 'saveView',
+        //     name: commandArgs[0] || DEFAULT_VIEW_NAME,
+        //     overwrite: true,
+        //   };
+        //
+        // case 'loadview':
+        //   return {
+        //     effectType: 'loadView',
+        //     name: commandArgs[0] || DEFAULT_VIEW_NAME,
+        //   };
         default:
             return {
-                effectType: 'unrecognizedCommand',
-                commandLine,
+                effectType: 'emitError',
+                message: `Unrecognized command: "${commandLine}"`,
             };
     }
     /*

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

@@ -1,4 +1,4 @@
-import type { SerializableKey } from '../../trees/index.js';
+import type { SerializableKey } from '../../state-and-nav/index.js';
 import type { EffectAction } from '../domain/index.js';
 export type ParseNormalCommandResult<Id extends SerializableKey, Value> = {
     kind: 'incomplete';

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

@@ -1 +1 @@
-{"version":3,"file":"parse-normal-command.d.ts","sourceRoot":"","sources":["../../../src/input/application/parse-normal-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOvD,MAAM,MAAM,wBAAwB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAClE;IACE,IAAI,EAAE,YAAY,CAAC;CACpB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CACjC,GACD;IACE,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEN,wBAAgB,kBAAkB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAClE,YAAY,EAAE,MAAM,GACnB,wBAAwB,CAAC,EAAE,EAAE,KAAK,CAAC,CAwCrC"}
+{"version":3,"file":"parse-normal-command.d.ts","sourceRoot":"","sources":["../../../src/input/application/parse-normal-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOvD,MAAM,MAAM,wBAAwB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAClE;IACE,IAAI,EAAE,YAAY,CAAC;CACpB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;CACjC,GACD;IACE,IAAI,EAAE,SAAS,CAAC;CACjB,CAAC;AAEN,wBAAgB,kBAAkB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAClE,YAAY,EAAE,MAAM,GACnB,wBAAwB,CAAC,EAAE,EAAE,KAAK,CAAC,CAwCrC"}