@nbtca/prompt 1.4.1 → 1.5.0

package/dist/app/fields/text-field.js

@@ -1,9 +1,4 @@
 import { renderInput, applyInputEvent, parseInputData } from '../../core/components/text-input.js';
-/** Non-blocking equivalent of `runTextInput`/`runSecretInput`: a view holds
- * one of these and drives it via `handleKey` from the app loop's single
- * stdin listener. Does not touch vim-key activation — the owning view is
- * responsible for `setVimKeysActive(false)` while a TextField is focused
- * (mirrors what `runTextInput` already does for the blocking widget). */
 export class TextField {
     config;
     value = '';
@@ -17,9 +12,9 @@ export class TextField {
         return renderInput({
             message: this.config.message,
             value: this.value,
-            placeholder: this.config.placeholder,
-            secret: this.config.secret,
-            mask: this.config.mask,
+            ...(this.config.placeholder === undefined ? {} : { placeholder: this.config.placeholder }),
+            ...(this.config.secret === undefined ? {} : { secret: this.config.secret }),
+            ...(this.config.mask === undefined ? {} : { mask: this.config.mask }),
             cols,
         }).split('\n');
     }

package/dist/app/frame.js

@@ -1,27 +1,8 @@
-import { visualWidth } from '../core/text.js';
+import { clipAnsiToVisualWidth, visualWidth } from '../core/text.js';
 export function clipToWidth(line, cols) {
     if (visualWidth(line) <= cols)
         return line;
-    let out = '';
-    let w = 0;
-    let i = 0;
-    while (i < line.length) {
-        const esc = line.slice(i).match(/^\x1b\[[0-9;]*m/);
-        if (esc) {
-            out += esc[0];
-            i += esc[0].length;
-            continue;
-        }
-        const cp = line.codePointAt(i);
-        const ch = String.fromCodePoint(cp);
-        const cw = visualWidth(ch);
-        if (w + cw > cols)
-            break;
-        out += ch;
-        w += cw;
-        i += ch.length;
-    }
-    return out + '\x1b[0m';
+    return clipAnsiToVisualWidth(line, cols) + '\x1b[0m';
 }
 export function fitLine(line, cols) {
     const clipped = visualWidth(line) > cols ? clipToWidth(line, cols) : line;

package/dist/app/keys.js

@@ -1,3 +1,6 @@
+function switchResult(target) {
+    return target === undefined ? { handled: true } : { switchTo: target, handled: true };
+}
 export function routeGlobalKey(key, viewIds, current) {
     if (key === 'q' || key === '\x03')
         return { quit: true, handled: true };
@@ -5,7 +8,12 @@ export function routeGlobalKey(key, viewIds, current) {
         return current === 'home' ? { quit: true, handled: true } : { back: true, handled: true };
     if (key === '\t') {
         const i = viewIds.indexOf(current);
-        return { switchTo: viewIds[(i + 1) % viewIds.length], handled: true };
+        return switchResult(viewIds[(i + 1) % viewIds.length]);
+    }
+    if (key === '\x1b[Z') {
+        const i = viewIds.indexOf(current);
+        const previous = i < 0 ? viewIds.length - 1 : (i - 1 + viewIds.length) % viewIds.length;
+        return switchResult(viewIds[previous]);
     }
     if (key === '\x1b[5~')
         return { scrollBy: -1, handled: true };
@@ -14,7 +22,7 @@ export function routeGlobalKey(key, viewIds, current) {
     if (/^[1-9]$/.test(key)) {
         const idx = Number(key) - 1;
         if (idx < viewIds.length)
-            return { switchTo: viewIds[idx], handled: true };
+            return switchResult(viewIds[idx]);
     }
     return { handled: false };
 }

package/dist/app/views/docs-render.js

@@ -1,32 +1,34 @@
 import { type, space } from '../../core/theme.js';
 import { t } from '../../i18n/index.js';
 import { renderListFieldWithContext } from '../fields/list-field.js';
-import { visualWidth, wrapAnsiToVisualWidth } from '../../core/text.js';
+import { visualWidth, wrapAnsiToVisualWidth, wrapAnsiWithIndent } from '../../core/text.js';
 function hintLines(label, cols) {
-    const width = Number.isFinite(cols) ? Math.max(1, Math.floor(cols)) : Number.POSITIVE_INFINITY;
-    const styled = type.hint(label);
-    const preferredIndent = visualWidth(space.indent) < width ? space.indent : '';
-    const indent = preferredIndent
-        && visualWidth(styled) > width - visualWidth(preferredIndent)
-        && visualWidth(styled) <= width
-        ? ''
-        : preferredIndent;
-    const contentWidth = Math.max(1, width - visualWidth(indent));
-    return wrapAnsiToVisualWidth(styled, contentWidth).map((line) => `${indent}${line}`);
+    return wrapAnsiWithIndent(type.hint(label), cols, space.indent);
 }
 function renderReader(lines, cols) {
     const contentWidth = Math.max(1, Math.min(80, cols - visualWidth(space.indent)));
-    return lines.flatMap((line) => (wrapAnsiToVisualWidth(line, contentWidth).map((part) => `${space.indent}${part}`)));
+    return lines.flatMap((line) => wrapAnsiToVisualWidth(line, contentWidth).map((part) => `${space.indent}${part}`));
 }
 function listFieldForState(state) {
     switch (state.mode) {
-        case 'sections': return state.sectionsField;
-        case 'files': return state.filesField;
-        case 'archivedGroups': return state.archivedGroupsField;
-        case 'archivedFiles': return state.archivedFilesField;
-        case 'searchResults': return state.searchResultsField;
-        case 'reader': return state.readerLinksField;
-        default: return undefined;
+        case 'sections':
+            return state.sectionsField;
+        case 'files':
+            return state.filesField;
+        case 'archivedGroups':
+            return state.archivedGroupsField;
+        case 'archivedFiles':
+            return state.archivedFilesField;
+        case 'searchResults':
+            return state.searchResultsField;
+        case 'reader':
+            return state.readerLinksField;
+        case 'error':
+        case 'loading':
+        case 'readerLoading':
+        case 'search':
+        case 'searchLoading':
+            return undefined;
     }
 }
 export function renderDocs(state, cols = 80, bodyRows = Number.POSITIVE_INFINITY) {
@@ -51,10 +53,17 @@ export function renderDocs(state, cols = 80, bodyRows = Number.POSITIVE_INFINITY
         case 'search':
             lines = state.searchField?.render(cols) ?? [];
             break;
+        case 'searchLoading':
+            lines = hintLines(trans.docs.searching, cols);
+            break;
         case 'searchResults':
-            lines = state.searchResultsField ? renderListFieldWithContext([
-                ...(state.searchResultsEmpty ? [...hintLines(trans.docs.searchNoResults, cols), ''] : []),
-            ], state.searchResultsField, bodyRows, cols) : [];
+            lines = state.searchResultsField
+                ? renderListFieldWithContext([
+                    ...(state.searchResultsEmpty
+                        ? [...hintLines(trans.docs.searchNoResults, cols), '']
+                        : []),
+                ], state.searchResultsField, bodyRows, cols)
+                : [];
             break;
         case 'readerLoading':
             lines = hintLines(trans.docs.loadingFile, cols);
@@ -66,8 +75,6 @@ export function renderDocs(state, cols = 80, bodyRows = Number.POSITIVE_INFINITY
             break;
         case 'error':
             return hintLines(state.errorMessage ?? trans.docs.loadError, cols);
-        default:
-            lines = [];
     }
     if (!state.errorMessage)
         return lines;

package/dist/app/views/docs.js

@@ -5,7 +5,8 @@ import { renderDocs } from './docs-render.js';
 import { setVimKeysActive } from '../../core/vim-keys.js';
 import { pickIcon } from '../../core/icons.js';
 import { getCurrentLanguage, t } from '../../i18n/index.js';
-import { localizeDocSections, fetchSections, fetchAllDocs, getArchivedGroups, cleanFileName, displayDocTitle, loadDocForReader, openDocsInBrowser, clearDocsCache, } from '../../features/docs.js';
+import { sanitizeTerminalLine, truncate } from '../../core/text.js';
+import { localizeDocSections, fetchSections, fetchDocMetadata, fetchSectionMetadata, searchDocuments, getArchivedGroups, displayDocTitle, loadDocForReader, openDocsInBrowser, clearDocsCache, } from '../../features/docs.js';
 let state = { mode: 'loading' };
 let sections = [];
 let archivedGroups = new Map();
@@ -14,19 +15,34 @@ let loadedLanguage = null;
 let currentSectionKey = null;
 let currentArchivedGroupKey = null;
 let currentSearchResults = [];
-// In-app reader navigation: readerCurrentPath is the doc on screen right
-// now; readerNavStack holds the paths of docs visited before it (pushed
-// only when following a link forward, popped on Esc); readerPrevState is
-// whichever file-listing state (files/archivedFiles/searchResults) the
-// reader was entered from, restored once the nav stack empties.
+let sectionsRequestId = 0;
+let metadataRequestId = 0;
+let searchRequestId = 0;
 let readerCurrentPath = null;
 let readerNavStack = [];
 let readerPrevState = null;
 let readerLoadingPrevState = null;
 let readerRequestId = 0;
+const DOC_HINT_WIDTH = 44;
 function backLabel() {
     return t().common.back;
 }
+function optionalHint(hint) {
+    return hint === undefined ? {} : { hint };
+}
+function docHint(value) {
+    return value ? truncate(value, DOC_HINT_WIDTH) : undefined;
+}
+function withoutReaderLinksField(value) {
+    const next = { ...value };
+    delete next.readerLinksField;
+    return next;
+}
+function withoutErrorMessage(value) {
+    const next = { ...value };
+    delete next.errorMessage;
+    return next;
+}
 function buildSectionsField() {
     const trans = t();
     const options = [
@@ -39,19 +55,16 @@ function buildSectionsField() {
 }
 function buildFilesField(section, maxVisible, initialIndex = 0) {
     const trans = t();
-    const isIndex = (f) => f.name === 'index.md' || f.name.startsWith('index.');
-    // nbtca/documents' repair/ and concepts/ sections are explicitly built
-    // "hub + inline-link + search, no full sidebar" (.vitepress/config.mts) --
-    // each has a hand-curated index.md landing page (concepts/index.md groups
-    // all 21 entries by topic with one-line definitions; nothing like that
-    // exists in a flat alphabetical list). It used to be filtered out
-    // entirely here, making it unreachable from the Docs tab -- now it's
-    // pinned to the top as a distinctly-labeled entry instead.
+    const isIndex = (file) => file.name === 'index.md' || file.name.startsWith('index.');
     const index = section.files.find(isIndex);
     const files = section.files.filter((f) => !isIndex(f));
     const options = [
         ...(index ? [{ value: index.path, label: trans.docs.overviewLabel }] : []),
-        ...files.map((f) => ({ value: f.path, label: displayDocTitle(f.path, f.name) })),
+        ...files.map((file) => ({
+            value: file.path,
+            label: displayDocTitle(file.name, file.title),
+            ...optionalHint(docHint(file.summary)),
+        })),
         { value: '__back__', label: backLabel() },
     ];
     return new ListField({ title: section.label, options, maxVisible, initialIndex });
@@ -70,7 +83,7 @@ function buildArchivedGroupsField(groups, maxVisible, initialIndex = 0) {
         return a.localeCompare(b);
     });
     const options = [
-        ...sortedKeys.map((k) => ({ value: k, label: k, hint: String(groups.get(k).length) })),
+        ...sortedKeys.map((k) => ({ value: k, label: k, hint: String(groups.get(k)?.length ?? 0) })),
         { value: '__back__', label: backLabel() },
     ];
     return new ListField({ title: trans.docs.categoryArchived, options, maxVisible, initialIndex });
@@ -81,11 +94,22 @@ function buildArchivedFilesField(groupKey, groupFiles, maxVisible, initialIndex
     const options = [
         ...groupFiles.map((f) => {
             const sub = f.path.split('/').slice(2, -1).join('/');
-            return { value: f.path, label: cleanFileName(f.name), hint: subDirs.size > 1 ? sub : undefined };
+            return {
+                value: f.path,
+                label: displayDocTitle(f.name, f.title),
+                ...optionalHint(docHint(subDirs.size > 1
+                    ? [sanitizeTerminalLine(sub), f.summary].filter(Boolean).join(' · ')
+                    : f.summary)),
+            };
         }),
         { value: '__back__', label: backLabel() },
     ];
-    return new ListField({ title: `${trans.docs.categoryArchived} · ${groupKey}`, options, maxVisible, initialIndex });
+    return new ListField({
+        title: `${trans.docs.categoryArchived} · ${groupKey}`,
+        options,
+        maxVisible,
+        initialIndex,
+    });
 }
 function buildReaderLinksField(links, maxVisible, initialIndex = 0) {
     const trans = t();
@@ -100,8 +124,12 @@ function buildSearchResultsField(matches, maxVisible, initialIndex = 0) {
     const options = [
         ...matches.map((result) => ({
             value: result.path,
-            label: displayDocTitle(result.path, result.name),
-            hint: result.path.includes('/') ? result.path.split('/').slice(0, -1).join('/') : undefined,
+            label: displayDocTitle(result.name, result.title),
+            ...optionalHint(docHint(result.excerpt ||
+                result.summary ||
+                (result.path.includes('/')
+                    ? sanitizeTerminalLine(result.path.split('/').slice(0, -1).join('/'))
+                    : undefined))),
         })),
         { value: '__back__', label: backLabel() },
     ];
@@ -114,7 +142,10 @@ function relocalizeStateFields(value, maxVisible) {
     if (value.mode === 'files' && currentSectionKey) {
         const section = sections.find((candidate) => candidate.key === currentSectionKey);
         return section
-            ? { ...value, filesField: buildFilesField(section, maxVisible, value.filesField?.selectedIndex) }
+            ? {
+                ...value,
+                filesField: buildFilesField(section, maxVisible, value.filesField?.selectedIndex),
+            }
             : value;
     }
     if (value.mode === 'archivedGroups') {
@@ -149,10 +180,95 @@ function goToSections() {
     currentSearchResults = [];
     state = { mode: 'sections', sectionsField: buildSectionsField() };
 }
-/** Enters (or re-enters) the reader on `path`. `pushCurrent` distinguishes
- * following a link forward (push readerCurrentPath so Esc can return to it)
- * from navigating backward or entering fresh from a file list (nothing to
- * push -- the caller has already saved/cleared readerPrevState itself). */
+function replaceSection(section) {
+    sections = sections.map((current) => (current.key === section.key ? section : current));
+}
+async function openSectionFiles(ctx, section) {
+    const requestId = ++metadataRequestId;
+    currentSectionKey = section.key;
+    state = {
+        mode: 'files',
+        filesField: buildFilesField(section, computeMaxVisible(ctx.bodyRows)),
+    };
+    ctx.rerender();
+    try {
+        const hydrated = await fetchSectionMetadata(section);
+        if (requestId !== metadataRequestId ||
+            state.mode !== 'files' ||
+            currentSectionKey !== section.key)
+            return;
+        const localized = localizeDocSections([hydrated], t())[0] ?? hydrated;
+        replaceSection(localized);
+        state = {
+            mode: 'files',
+            filesField: buildFilesField(localized, computeMaxVisible(ctx.bodyRows), state.filesField?.selectedIndex),
+        };
+    }
+    catch {
+        if (requestId !== metadataRequestId ||
+            state.mode !== 'files' ||
+            currentSectionKey !== section.key)
+            return;
+        state = { ...state, errorMessage: t().docs.loadError };
+    }
+    ctx.rerender();
+}
+async function openArchivedFiles(ctx, groupKey, groupFiles) {
+    const requestId = ++metadataRequestId;
+    currentArchivedGroupKey = groupKey;
+    state = {
+        mode: 'archivedFiles',
+        archivedFilesField: buildArchivedFilesField(groupKey, groupFiles, computeMaxVisible(ctx.bodyRows)),
+    };
+    ctx.rerender();
+    try {
+        const hydrated = await fetchDocMetadata(groupFiles);
+        if (requestId !== metadataRequestId ||
+            state.mode !== 'archivedFiles' ||
+            currentArchivedGroupKey !== groupKey)
+            return;
+        archivedGroups.set(groupKey, hydrated);
+        state = {
+            mode: 'archivedFiles',
+            archivedFilesField: buildArchivedFilesField(groupKey, hydrated, computeMaxVisible(ctx.bodyRows), state.archivedFilesField?.selectedIndex),
+        };
+    }
+    catch {
+        if (requestId !== metadataRequestId ||
+            state.mode !== 'archivedFiles' ||
+            currentArchivedGroupKey !== groupKey)
+            return;
+        state = {
+            ...state,
+            errorMessage: t().docs.loadError,
+        };
+    }
+    ctx.rerender();
+}
+async function runSearch(ctx, query) {
+    const requestId = ++searchRequestId;
+    state = { mode: 'searchLoading' };
+    ctx.rerender();
+    try {
+        const matches = await searchDocuments(query);
+        if (requestId !== searchRequestId)
+            return;
+        currentSearchResults = matches;
+        state = {
+            mode: 'searchResults',
+            searchResultsEmpty: matches.length === 0,
+            searchResultsField: buildSearchResultsField(matches, computeMaxVisible(ctx.bodyRows)),
+        };
+    }
+    catch {
+        if (requestId !== searchRequestId)
+            return;
+        currentSearchResults = [];
+        goToSections();
+        state = { ...state, errorMessage: t().docs.loadError };
+    }
+    ctx.rerender();
+}
 async function openInReader(ctx, path, pushCurrent) {
     const requestId = ++readerRequestId;
     const previousState = state;
@@ -168,7 +284,12 @@ async function openInReader(ctx, path, pushCurrent) {
             readerNavStack.push(previousPath);
         readerCurrentPath = path;
         readerLoadingPrevState = null;
-        state = { mode: 'reader', readerTitle: doc.title, readerLines: doc.lines, readerLinks: doc.links };
+        state = {
+            mode: 'reader',
+            readerTitle: doc.title,
+            readerLines: doc.lines,
+            readerLinks: doc.links,
+        };
         ctx.resetScroll();
     }
     catch {
@@ -176,15 +297,12 @@ async function openInReader(ctx, path, pushCurrent) {
             return;
         readerLoadingPrevState = null;
         const fallbackState = pushCurrent && previousState.mode === 'reader'
-            ? { ...previousState, readerLinksField: undefined }
+            ? withoutReaderLinksField(previousState)
             : previousState;
         state = { ...fallbackState, errorMessage: t().docs.loadError };
     }
     ctx.rerender();
 }
-/** Enters the reader from a file-listing mode (files/archivedFiles/
- * searchResults) -- saves that listing so Esc can restore it once the nav
- * stack (built by following links from here) empties back out. */
 function enterReaderFrom(ctx, path) {
     readerPrevState = state;
     readerNavStack = [];
@@ -208,23 +326,26 @@ export const docsView = {
             }
             return;
         }
+        const requestId = ++sectionsRequestId;
         state = { mode: 'loading' };
         ctx.rerender();
         try {
-            sections = await fetchSections();
+            const nextSections = await fetchSections();
+            if (requestId !== sectionsRequestId)
+                return;
+            sections = nextSections;
             loaded = true;
             loadedLanguage = getCurrentLanguage();
             goToSections();
         }
         catch {
+            if (requestId !== sectionsRequestId)
+                return;
             state = { mode: 'error', errorMessage: t().docs.loadError };
         }
         ctx.rerender();
     },
     render(ctx) {
-        // Sync every visible field's scroll window to the *current* terminal
-        // size on every frame (not just construction time) — this is what
-        // keeps a long list correctly windowed across a live resize.
         const maxVisible = computeMaxVisible(ctx.bodyRows);
         state.filesField?.setMaxVisible(maxVisible);
         state.archivedGroupsField?.setMaxVisible(maxVisible);
@@ -236,10 +357,18 @@ export const docsView = {
     capturesInput() {
         return state.mode === 'search';
     },
+    capturesPageKeys() {
+        return (state.mode === 'sections' ||
+            state.mode === 'files' ||
+            state.mode === 'archivedGroups' ||
+            state.mode === 'archivedFiles' ||
+            state.mode === 'searchResults' ||
+            (state.mode === 'reader' && state.readerLinksField !== undefined));
+    },
     footerHint(tabCount, cols = Number.POSITIVE_INFINITY) {
         if (state.mode === 'search')
             return captureFooterHint(cols);
-        if (state.mode === 'loading' || state.mode === 'error')
+        if (state.mode === 'loading' || state.mode === 'searchLoading' || state.mode === 'error')
             return passiveFooterHint(tabCount, cols);
         if (state.mode === 'readerLoading') {
             return fitFooterHint(cols, `${digitTabHint(tabCount)}q ${t().menu.hintQuit}`, `${digitTabHint(tabCount)}q`, 'q');
@@ -257,6 +386,11 @@ export const docsView = {
         return undefined;
     },
     handleBack(ctx) {
+        if (state.mode === 'searchLoading') {
+            searchRequestId++;
+            goToSections();
+            return true;
+        }
         if (state.mode === 'reader' || state.mode === 'readerLoading') {
             if (state.mode === 'readerLoading') {
                 const previousState = readerLoadingPrevState;
@@ -268,7 +402,7 @@ export const docsView = {
                 return true;
             }
             if (state.readerLinksField) {
-                state = { ...state, readerLinksField: undefined };
+                state = withoutReaderLinksField(state);
                 return true;
             }
             const prevPath = readerNavStack.pop();
@@ -285,7 +419,10 @@ export const docsView = {
             return false;
         }
         if (state.mode === 'archivedFiles') {
-            state = { mode: 'archivedGroups', archivedGroupsField: buildArchivedGroupsField(archivedGroups, computeMaxVisible(ctx.bodyRows)) };
+            state = {
+                mode: 'archivedGroups',
+                archivedGroupsField: buildArchivedGroupsField(archivedGroups, computeMaxVisible(ctx.bodyRows)),
+            };
             return true;
         }
         if (state.mode === 'search') {
@@ -293,7 +430,9 @@ export const docsView = {
             goToSections();
             return true;
         }
-        if (state.mode === 'files' || state.mode === 'archivedGroups' || state.mode === 'searchResults') {
+        if (state.mode === 'files' ||
+            state.mode === 'archivedGroups' ||
+            state.mode === 'searchResults') {
             goToSections();
             return true;
         }
@@ -301,7 +440,7 @@ export const docsView = {
     },
     handleKey(key, ctx) {
         if (state.mode !== 'error' && state.errorMessage)
-            state = { ...state, errorMessage: undefined };
+            state = withoutErrorMessage(state);
         switch (state.mode) {
             case 'sections': {
                 const result = state.sectionsField?.handleKey(key);
@@ -309,11 +448,21 @@ export const docsView = {
                     return;
                 if (result.selected === '__search__') {
                     setVimKeysActive(false);
-                    state = { mode: 'search', searchField: new TextField({ message: t().docs.searchPrompt, placeholder: t().docs.searchPlaceholder, allowEmpty: true }) };
+                    state = {
+                        mode: 'search',
+                        searchField: new TextField({
+                            message: t().docs.searchPrompt,
+                            placeholder: t().docs.searchPlaceholder,
+                            allowEmpty: true,
+                        }),
+                    };
                     return;
                 }
                 if (result.selected === '__refresh__') {
                     clearDocsCache();
+                    sectionsRequestId++;
+                    metadataRequestId++;
+                    searchRequestId++;
                     loaded = false;
                     loadedLanguage = null;
                     sections = [];
@@ -326,7 +475,7 @@ export const docsView = {
                     readerPrevState = null;
                     readerLoadingPrevState = null;
                     readerRequestId++;
-                    void docsView.load?.(ctx);
+                    void docsView.load(ctx);
                     return;
                 }
                 if (result.selected === '__browser__') {
@@ -337,14 +486,17 @@ export const docsView = {
                 if (!section)
                     return;
                 if (section.key === 'archived') {
+                    metadataRequestId++;
                     currentSectionKey = null;
                     currentArchivedGroupKey = null;
                     archivedGroups = getArchivedGroups(section.files);
-                    state = { mode: 'archivedGroups', archivedGroupsField: buildArchivedGroupsField(archivedGroups, computeMaxVisible(ctx.bodyRows)) };
+                    state = {
+                        mode: 'archivedGroups',
+                        archivedGroupsField: buildArchivedGroupsField(archivedGroups, computeMaxVisible(ctx.bodyRows)),
+                    };
                 }
                 else {
-                    currentSectionKey = section.key;
-                    state = { mode: 'files', filesField: buildFilesField(section, computeMaxVisible(ctx.bodyRows)) };
+                    void openSectionFiles(ctx, section);
                 }
                 return;
             }
@@ -367,9 +519,8 @@ export const docsView = {
                     goToSections();
                     return;
                 }
-                currentArchivedGroupKey = result.selected;
                 const groupFiles = archivedGroups.get(result.selected) ?? [];
-                state = { mode: 'archivedFiles', archivedFilesField: buildArchivedFilesField(result.selected, groupFiles, computeMaxVisible(ctx.bodyRows)) };
+                void openArchivedFiles(ctx, result.selected, groupFiles);
                 return;
             }
             case 'archivedFiles': {
@@ -378,7 +529,10 @@ export const docsView = {
                     return;
                 if (result.selected === '__back__') {
                     currentArchivedGroupKey = null;
-                    state = { mode: 'archivedGroups', archivedGroupsField: buildArchivedGroupsField(archivedGroups, computeMaxVisible(ctx.bodyRows)) };
+                    state = {
+                        mode: 'archivedGroups',
+                        archivedGroupsField: buildArchivedGroupsField(archivedGroups, computeMaxVisible(ctx.bodyRows)),
+                    };
                     return;
                 }
                 enterReaderFrom(ctx, result.selected);
@@ -398,19 +552,7 @@ export const docsView = {
                         goToSections();
                         return;
                     }
-                    void fetchAllDocs().then((all) => {
-                        const matches = all.filter((item) => item.path.toLowerCase().includes(query));
-                        currentSearchResults = matches;
-                        state = {
-                            mode: 'searchResults',
-                            searchResultsEmpty: matches.length === 0,
-                            searchResultsField: buildSearchResultsField(matches, computeMaxVisible(ctx.bodyRows)),
-                        };
-                        ctx.rerender();
-                    }).catch(() => {
-                        state = { mode: 'error', errorMessage: t().docs.loadError };
-                        ctx.rerender();
-                    });
+                    void runSearch(ctx, query);
                 }
                 return;
             }
@@ -429,19 +571,18 @@ export const docsView = {
                 if (state.readerLinksField) {
                     const result = state.readerLinksField.handleKey(key);
                     if (result.cancelled || result.selected === '__back__') {
-                        state = { ...state, readerLinksField: undefined };
+                        state = withoutReaderLinksField(state);
                         return;
                     }
                     if (result.selected)
                         void openInReader(ctx, result.selected, true);
                     return;
                 }
-                // 'f' (Vimium/vim-browser-extension convention: "follow a link"),
-                // not 'l' -- core/vim-keys.ts already reserves 'l' globally,
-                // ranger-style, as an alias for Enter/confirm (vimActive defaults
-                // to true), so a literal 'l' keypress never even reaches here.
                 if (key === 'f' && (state.readerLinks?.length ?? 0) > 0) {
-                    state = { ...state, readerLinksField: buildReaderLinksField(state.readerLinks ?? [], computeMaxVisible(ctx.bodyRows)) };
+                    state = {
+                        ...state,
+                        readerLinksField: buildReaderLinksField(state.readerLinks ?? [], computeMaxVisible(ctx.bodyRows)),
+                    };
                     return;
                 }
                 if (key === 'b') {
@@ -450,7 +591,10 @@ export const docsView = {
                 }
                 return;
             }
-            default:
+            case 'error':
+            case 'loading':
+            case 'readerLoading':
+            case 'searchLoading':
                 return;
         }
     },