@nbtca/prompt 1.3.1 → 1.4.1

package/dist/features/docs.js

@@ -2,13 +2,15 @@ import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import chalk from 'chalk';
 import open from 'open';
-import { select, isCancel, confirm, text } from '@clack/prompts';
-import { error, warning, success, createSpinner } from '../core/ui.js';
+import { runMenu, menuFooter } from '../core/components/menu.js';
+import { runTextInput } from '../core/components/text-input.js';
+import { runConfirm } from '../core/components/confirm.js';
+import { warning, createSpinner } from '../core/ui.js';
 import { pickIcon } from '../core/icons.js';
 import { spawn, execFileSync } from 'child_process';
 import { URLS } from '../config/data.js';
 import { t, fmt } from '../i18n/index.js';
-import { setVimKeysActive } from '../core/vim-keys.js';
+import { enterScreen, breadcrumb } from '../core/transitions.js';
 import { createDocsClient } from '@nbtca/docs';
 function detectTerminalType() {
     const term = (process.env['TERM'] || '').toLowerCase();
@@ -48,16 +50,56 @@ function hasGlow() {
         _hasGlow = commandExists('glow');
     return _hasGlow;
 }
+// nbtca/documents links internally with relative/root-relative paths
+// (`./what-is-nbtca`, `/concepts/school`) that only resolve in a browser --
+// a terminal pager can neither follow nor hover-preview them, so showing
+// the path is dead weight. Matches './x', '../x', and '/x' but not a bare
+// '/' (an internal href is never *just* a slash in this content).
+function isInternalHref(href) {
+    return /^\.{0,2}\/./.test(href);
+}
 let _markedConfigured = false;
-function ensureMarkedConfigured() {
+export function ensureMarkedConfigured() {
     if (_markedConfigured)
         return;
     _markedConfigured = true;
-    marked.use(markedTerminal(getRendererOptions(getTerminalType())));
+    const extension = markedTerminal(getRendererOptions(getTerminalType()));
+    const renderer = extension.renderer ?? (extension.renderer = {});
+    const renderExternalLink = renderer.link;
+    if (renderExternalLink) {
+        renderer.link = function (token) {
+            if (isInternalHref(token.href))
+                return chalk.cyan.underline(token.text);
+            return renderExternalLink.call(this, token);
+        };
+    }
+    // marked-terminal's own `text` renderer always uses the token's raw
+    // `.text` string, never `.tokens` -- fine for a plain text run, but a
+    // *tight* list item (nbtca/documents' convention throughout: no blank
+    // line between "- " entries) tokenizes its content as a `text` token
+    // with markdown links inside still sitting unparsed in `.tokens`, not
+    // resolved into `.text`. Result: every link inside every bullet list
+    // rendered as completely raw, un-clickable-looking `[text](url)` syntax
+    // (only paragraph-level links, which *do* go through inline-parsing,
+    // picked up the `link` override above at all). Recursing into
+    // `parser.parseInline` here when `.tokens` exists routes list-item links
+    // through the same override, matching how paragraph/heading already do.
+    const renderPlainText = renderer.text;
+    if (renderPlainText) {
+        renderer.text = function (token) {
+            const withTokens = token;
+            if (Array.isArray(withTokens.tokens) && withTokens.tokens.length > 0) {
+                return this
+                    .parser.parseInline(withTokens.tokens);
+            }
+            return renderPlainText.call(this, token);
+        };
+    }
+    marked.use(extension);
 }
 // ─── marked-terminal renderer ─────────────────────────────────────────────────
 function getRendererOptions(type) {
-    const width = Math.min(process.stdout.columns || 80, 80);
+    const width = 80;
     const unicodeTableChars = {
         top: '─', 'top-mid': '┬', 'top-left': '┌', 'top-right': '┐',
         bottom: '─', 'bottom-mid': '┴', 'bottom-left': '└', 'bottom-right': '┘',
@@ -74,6 +116,14 @@ function getRendererOptions(type) {
         width,
         emoji: true,
         unescape: true,
+        // marked-terminal defaults this to true, prefixing every heading with
+        // its literal '#'/'##'/etc. markdown syntax. displayWithLess() already
+        // prints its own clean title line above the content, and most docs'
+        // first line is an H1 matching that same title -- so the raw '#
+        // Title' immediately below just repeated it a second time, syntax
+        // marks and all. firstHeading/heading's bold+color already
+        // distinguishes heading levels without the extra prefix.
+        showSectionPrefix: false,
         firstHeading: chalk.bold.cyan,
         heading: chalk.bold.white,
         codespan: chalk.yellowBright,
@@ -122,16 +172,76 @@ async function fetchFileContent(path) {
     }
 }
 // ─── Content cleaning ─────────────────────────────────────────────────────────
+/**
+ * Line-by-line scanner that processes fenced code blocks before marked sees them:
+ * - mermaid blocks → styled blockquote placeholder with diagram type
+ * - other blocks with a language tag → prepend an inline-code label line
+ */
+function processFencedCodeBlocks(content) {
+    const trans = t();
+    const lines = content.split('\n');
+    const result = [];
+    let inBlock = false;
+    let fence = '';
+    let blockLang = '';
+    let blockBody = [];
+    for (const line of lines) {
+        if (!inBlock) {
+            // Accept VitePress code meta after language: ```js{1,3} or ```ts [file.ts] :line-numbers
+            const m = line.match(/^(`{3,})(\w+)?[^`\n]*$/);
+            if (m) {
+                inBlock = true;
+                fence = m[1];
+                blockLang = (m[2] ?? '').toLowerCase();
+                blockBody = [];
+            }
+            else {
+                result.push(line);
+            }
+        }
+        else {
+            if (line.startsWith(fence) && /^`+\s*$/.test(line)) {
+                inBlock = false;
+                const body = blockBody.join('\n');
+                if (blockLang === 'mermaid') {
+                    // Skip %%{ init: ... }%% config directives to find the actual diagram type
+                    const meaningfulLine = body.trim().split('\n')
+                        .find(l => !l.trimStart().startsWith('%%') && l.trim()) ?? '';
+                    const firstToken = meaningfulLine.trim().split(/\s+/)[0] ?? 'diagram';
+                    const icon = pickIcon('📊', '[diagram]');
+                    result.push(`> ${icon} **${firstToken}** — _${trans.docs.mermaidHint}_`);
+                }
+                else {
+                    if (blockLang)
+                        result.push(`\`${blockLang}\``);
+                    result.push(fence);
+                    result.push(...blockBody);
+                    result.push(fence);
+                }
+            }
+            else {
+                blockBody.push(line);
+            }
+        }
+    }
+    if (inBlock) {
+        result.push(`${fence}${blockLang}`);
+        result.push(...blockBody);
+    }
+    return result.join('\n');
+}
 const CONTAINER_ICONS_ASCII = {
     info: '[INFO]', tip: '[TIP]', warning: '[WARN]', danger: '[DANGER]', details: '[DETAIL]'
 };
 const CONTAINER_ICONS_UNICODE = {
     info: 'ℹ️', tip: '💡', warning: '⚠️', danger: '🚨', details: '▶️'
 };
-function cleanMarkdownContent(content, type = getTerminalType()) {
+export function cleanMarkdownContent(content, type = getTerminalType()) {
     let c = content;
     // 1. YAML frontmatter
     c = c.replace(/^---\n[\s\S]*?\n---\n?/m, '');
+    // 1.5. Fenced code blocks: mermaid → placeholder, other langs → label prefix
+    c = processFencedCodeBlocks(c);
     // 2. VitePress script / style blocks
     c = c.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
     c = c.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');
@@ -143,10 +253,22 @@ function cleanMarkdownContent(content, type = getTerminalType()) {
         return `> ${icon} **${label}**\n>\n${quoted}\n`;
     });
     c = c.replace(/^:::\s*\w*.*$/gm, '');
+    // Internal wiki links (./foo, /concepts/foo) are handled at the renderer
+    // level (ensureMarkedConfigured's link override below), not here -- an
+    // earlier version of this rewrote link syntax into pre-colored raw ANSI
+    // text before marked() ever saw it, which broke when marked-terminal's
+    // own text reflow/wrapping ran on top of already-escaped text, corrupting
+    // the escape sequences into literal visible "[36m...[24m" garbage.
+    // Overriding the renderer instead lets marked-terminal own all ANSI
+    // output, so nothing downstream can mangle it.
     // 4. GitHub / GitLab callout alerts  (> [!NOTE])
     c = c.replace(/^>\s*\[!(NOTE|TIP|WARNING|CAUTION|IMPORTANT)\]\s*$/gim, (_, type) => `> **${type.charAt(0) + type.slice(1).toLowerCase()}:**`);
     // 5. [[toc]] — no value in terminal
     c = c.replace(/\[\[toc\]\]/gi, '');
+    // 5.5. VitePress heading anchors {#custom-id} — no value in terminal
+    c = c.replace(/^(#{1,6}\s+[^\n]*?)\s*\{#[^}]+\}\s*$/gm, '$1');
+    // 5.6. ==highlight== → bold (VitePress extended syntax)
+    c = c.replace(/==([^=\n]+)==/g, '**$1**');
     // 6. Images — adapt to terminal capability
     if (type === 'basic') {
         c = c.replace(/!\[([^\]]*)\]\([^)]+\)/g, (_, alt) => `${pickIcon('📎', '[image]')} ${alt || 'image'}`);
@@ -160,8 +282,13 @@ function cleanMarkdownContent(content, type = getTerminalType()) {
     // 7. HTML comments
     c = c.replace(/<!--[\s\S]*?-->/g, '');
     // 8. Strip HTML tags, keep inner text
+    c = c.replace(/<br\s*\/?>/gi, '\n'); // void: line break
+    c = c.replace(/<(?:hr|input|link|meta)\b[^>]*\/?>/gi, ''); // void: discard
     c = c.replace(/<([a-z][a-z0-9]*)\b[^>]*>([\s\S]*?)<\/\1>/gi, '$2');
     c = c.replace(/<[a-z][a-z0-9]*\b[^>]*\/>/gi, '');
+    // 8.5. Task list checkboxes
+    c = c.replace(/^(\s*[-*+] )\[x\] /gim, '$1☑ ');
+    c = c.replace(/^(\s*[-*+] )\[ \] /gm, '$1☐ ');
     // 9. Collapse runs of 3+ blank lines
     c = c.replace(/\n{3,}/g, '\n\n');
     return c.trim();
@@ -195,18 +322,116 @@ function extractTOC(content) {
         return (level === 3 ? '  ' : '') + text;
     });
 }
-/** True if the markdown source contains a table (pipe-delimited with separator row). */
+/** True if the markdown source contains a pipe table. */
 function hasMarkdownTable(content) {
     return /^\|.+\|/m.test(content) && /^\|[-: |]+\|/m.test(content);
 }
+/** True if the markdown source contains a mermaid diagram block. */
+function hasMermaidBlock(content) {
+    return /^```mermaid\b/m.test(content);
+}
+/** Every internal ([text](href) where isInternalHref(href)) link in a
+ * document, in reading order, raw href not yet resolved to a real path. */
+function extractInternalLinks(markdown) {
+    const links = [];
+    const re = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(markdown))) {
+        const href = m[2] ?? '';
+        if (isInternalHref(href))
+            links.push({ text: m[1] ?? '', href });
+    }
+    return links;
+}
+/** Resolves a wiki-style href (relative to the *linking* document, VitePress
+ * conventions: no .md extension, trailing '/' means that dir's index) into
+ * a real repo-relative path matching DocItem.path -- e.g. './what-is-nbtca'
+ * from within 'about/index.md' -> 'about/what-is-nbtca.md'; '/concepts/'
+ * (root-relative, works from anywhere) -> 'concepts/index.md'. */
+function resolveInternalHref(href, fromPath) {
+    const fromDir = fromPath.includes('/') ? fromPath.slice(0, fromPath.lastIndexOf('/')) : '';
+    const combined = href.startsWith('/') ? href.slice(1) : (fromDir ? `${fromDir}/${href}` : href);
+    const stack = [];
+    for (const part of combined.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            stack.pop();
+            continue;
+        }
+        stack.push(part);
+    }
+    let target = stack.join('/');
+    if (target === '' || href.endsWith('/'))
+        target += (target ? '/' : '') + 'index';
+    if (!target.endsWith('.md'))
+        target += '.md';
+    return target;
+}
+/** Loads and renders a doc for the native in-app reader -- the same
+ * fetch/clean/render/cache pipeline viewMarkdownFile uses, minus the
+ * spinner/pager/post-read menu, which belong to the classic-pager
+ * presentation layer, not this one. */
+export async function loadDocForReader(filePath) {
+    ensureMarkedConfigured();
+    const rawContent = await fetchFileContent(filePath);
+    const fingerprint = contentFingerprint(rawContent);
+    const cached = getFreshRender(filePath);
+    let renderedDoc;
+    if (cached && cached.fingerprint === fingerprint) {
+        renderedDoc = cached;
+    }
+    else {
+        const cleaned = cleanMarkdownContent(rawContent, getTerminalType());
+        const title = extractDocTitle(rawContent, cleaned) || cleanFileName(filePath.split('/').pop() ?? filePath);
+        const readTime = estimateReadTime(cleaned);
+        const rendered = await marked(cleaned);
+        renderedDoc = { fingerprint, cleaned, rendered, title, readTime };
+        setRender(filePath, renderedDoc);
+    }
+    const seen = new Set();
+    const links = [];
+    for (const raw of extractInternalLinks(renderedDoc.cleaned)) {
+        const resolved = resolveInternalHref(raw.href, filePath);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        links.push({ text: raw.text, href: resolved });
+    }
+    return { path: filePath, title: renderedDoc.title, lines: renderedDoc.rendered.split('\n'), links };
+}
 // ─── Document tree ────────────────────────────────────────────────────────────
-const TOP_SECTION_ORDER = ['tutorial', 'process', 'repair', 'archived'];
+// Sourced from a live audit of nbtca/documents (2026-07-18): `about` and
+// `concepts` are two whole new top-level sections added in the repo's wiki
+// reconstruction (5abcc4d, 5beee27) -- omitted here, buildSections() below
+// silently drops every file under them, which is exactly what happened
+// before this fix caught up to the upstream restructuring. `about` leads
+// (org intro for newcomers) and `concepts` sits after the practical guide
+// as reference material.
+const TOP_SECTION_ORDER = ['about', 'guide', 'repair', 'concepts', 'archived'];
 const TOP_SECTION_SKIP = new Set(['docs', 'index.md', 'README.md']);
+// tutorial/ and process/ are two folders on disk but one section everywhere
+// a reader actually sees them: nbtca/documents' own site nav collapses both
+// under a single "指南/Guide" entry, and tutorial/sidebar.ts spells out why
+// ("「指南」= 教程（学技术）+流程（办社务）高内聚合并为一栏") -- presenting
+// them as two separate top-level categories in the terminal was true to the
+// folder layout but false to how the content is actually meant to be read.
+const SECTION_ALIAS = { tutorial: 'guide', process: 'guide' };
+export function localizeDocSections(sections, trans = t()) {
+    const labels = {
+        about: trans.docs.categoryAbout,
+        guide: trans.docs.categoryGuide,
+        repair: trans.docs.categoryRepair,
+        concepts: trans.docs.categoryConcepts,
+        archived: trans.docs.categoryArchived,
+    };
+    return sections.map((section) => ({ ...section, label: labels[section.key] ?? section.label }));
+}
 /**
  * Convert a kebab-case filename to a display-friendly title.
  * Preserves Chinese characters and date prefixes.
  */
-function cleanFileName(name) {
+export function cleanFileName(name) {
     const base = name.replace(/\.md$/, '');
     if (/^[\d.]/.test(base))
         return base;
@@ -214,40 +439,81 @@ function cleanFileName(name) {
         .replace(/[-_]/g, ' ')
         .replace(/\b([a-z])/g, (_, c) => c.toUpperCase());
 }
+/**
+ * Real titles (each document's own top-level `# heading`) for the
+ * curated tutorial/process/repair sections, keyed by repo-relative path.
+ * These are hand-authored English-filename docs with Chinese content —
+ * mechanically title-casing the filename ("Clean Drive C") reads as a
+ * different, lower-quality product than the document's own title ("C盘
+ * 清理标准化流程"). Deliberately scoped to these three sections only:
+ * `archived/`'s meeting notes are informal and often share the same
+ * generic real heading across many different dates (e.g. five different
+ * files all titled just "维修日") — there, the current filename-derived,
+ * date-prefixed label is more useful for telling entries apart than the
+ * real heading would be, so it is intentionally left as-is.
+ *
+ * Pulled from a live audit of the actual nbtca/documents content
+ * (2026-07-16). A doc added later without an entry here simply falls
+ * back to `cleanFileName` — never an error, never a blank label.
+ */
+const KNOWN_DOC_TITLES = {
+    'tutorial/2025/clean-drive-c.md': 'C盘清理标准化流程',
+    'tutorial/2025/edu-email.md': '教育邮箱用途',
+    'tutorial/2025/github-education-verification.md': 'Github Education 认证指南',
+    'tutorial/2025/github-workflow.md': '快速上手社团目前的Github工作流',
+    'tutorial/2025/google-calendar.md': '谷歌日历使用指南',
+    'tutorial/2025/nginx-usage.md': '快速上手你的nginx',
+    'tutorial/2025/tailscale-usage.md': '社团自建 Tailscale 使用指南',
+    'tutorial/manual/hardware-establish.md': '计算机硬件系统的搭建与维护',
+    'tutorial/manual/net-usage.md': '国际互联网的使用',
+    'tutorial/manual/os-skills.md': '基础操作系统的使用技术',
+    'tutorial/manual/windows-from-scratch.md': '从零开始安装 Windows',
+    'process/2025/apply-for-credits.md': '申请第二课堂学分',
+    'process/2025/borrow-classroom.md': '借教室',
+    'process/2025/event-organization.md': '活动举办文档(待完善)',
+    'process/2025/nbtca-post.md': '撰写并发布你的第一篇NBTCA博客',
+    'process/2025/reimbursement-process.md': '报销流程',
+    'repair/checklist.md': '维修日检查单',
+    'repair/guide.md': '维修操作指南',
+    'repair/repair-day.md': '维修日',
+    'repair/tools.md': '软件仓库（校内镜像站）',
+    'repair/weekend.md': '维修工单系统 (weekend)',
+};
+/** Display title for a tutorial/process/repair doc: the real, known title
+ * when we have one, otherwise the same filename-derived fallback used
+ * everywhere else (including for every archived/ doc, which never has a
+ * known-title entry by design). */
+export function displayDocTitle(path, name) {
+    return KNOWN_DOC_TITLES[path] ?? cleanFileName(name);
+}
 /** Group flat DocItem list into top-level sections. */
-function buildSections(all) {
-    const trans = t();
-    const labelMap = {
-        tutorial: trans.docs.categoryTutorial,
-        process: trans.docs.categoryProcess,
-        repair: trans.docs.categoryRepair,
-        archived: trans.docs.categoryArchived,
-    };
+export function buildSections(all) {
     const groups = new Map();
     for (const item of all) {
         const parts = item.path.split('/');
         if (parts.length < 2)
             continue;
-        const top = parts[0];
-        if (TOP_SECTION_SKIP.has(top))
+        const rawTop = parts[0];
+        if (TOP_SECTION_SKIP.has(rawTop))
             continue;
+        const top = SECTION_ALIAS[rawTop] ?? rawTop;
         if (!TOP_SECTION_ORDER.includes(top))
             continue;
         if (!groups.has(top))
             groups.set(top, []);
         groups.get(top).push(item);
     }
-    return TOP_SECTION_ORDER
+    return localizeDocSections(TOP_SECTION_ORDER
         .filter(k => groups.has(k))
         .map(k => ({
         key: k,
-        label: labelMap[k] ?? k,
+        label: k,
         count: groups.get(k).length,
         files: groups.get(k),
-    }));
+    })));
 }
 /** Group archived files by their second path component (year / manual / etc.). */
-function getArchivedGroups(files) {
+export function getArchivedGroups(files) {
     const groups = new Map();
     for (const item of files) {
         const group = item.path.split('/')[1] ?? 'other';
@@ -257,12 +523,19 @@ function getArchivedGroups(files) {
     }
     return groups;
 }
+/** Raw fetch, no spinner/UI — throws on failure. Shared by the classic and
+ * native-view loaders. */
+export async function fetchAllDocs() {
+    return docsClient.listAll();
+}
+export async function fetchSections() {
+    return buildSections(await fetchAllDocs());
+}
 async function loadSections() {
     const trans = t();
     const s = createSpinner(trans.docs.loading);
     try {
-        const all = await docsClient.listAll();
-        const sections = buildSections(all);
+        const sections = await fetchSections();
         s.stop();
         return sections;
     }
@@ -308,7 +581,7 @@ async function displayWithLess(rendered, title, filePath, readTime, toc) {
     const footer = [
         '',
         rule,
-        chalk.dim(`  ${trans.docs.endOfDocument}  ·  / to search`),
+        chalk.dim(`  ${trans.docs.endOfDocument}`),
         '',
     ].join('\n');
     const fullContent = header + rendered + footer;
@@ -344,18 +617,15 @@ async function showDocSection(section) {
     const files = section.files.filter(f => f.name !== 'index.md' && !f.name.startsWith('index.'));
     if (files.length === 0)
         return;
-    const selected = await select({
-        message: section.label,
+    const selected = await runMenu({
+        title: section.label,
         options: [
-            ...files.map(f => {
-                const parts = f.path.split('/');
-                const hint = parts.length > 2 ? parts.slice(1, -1).join('/') : '';
-                return { value: f.path, label: cleanFileName(f.name), hint };
-            }),
+            ...files.map(f => ({ value: f.path, label: cleanFileName(f.name) })),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(selected) || selected === '__back__')
+    if (selected === null || selected === '__back__')
         return;
     await viewMarkdownFile(selected);
 }
@@ -374,97 +644,91 @@ async function showArchivedSection(files) {
             return 1;
         return a.localeCompare(b);
     });
-    const groupKey = await select({
-        message: trans.docs.categoryArchived,
+    const groupKey = await runMenu({
+        title: trans.docs.categoryArchived,
         options: [
             ...sortedKeys.map(k => ({
                 value: k,
                 label: k,
-                hint: `${groups.get(k).length} docs`,
+                hint: String(groups.get(k).length),
             })),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(groupKey) || groupKey === '__back__')
+    if (groupKey === null || groupKey === '__back__')
         return;
     const groupFiles = groups.get(groupKey) ?? [];
-    const fileSelected = await select({
-        message: `${trans.docs.categoryArchived} / ${groupKey}`,
+    const subDirs = new Set(groupFiles.map(f => f.path.split('/')[2]).filter(Boolean));
+    const fileSelected = await runMenu({
+        title: `${trans.docs.categoryArchived} · ${groupKey}`,
         options: [
-            ...groupFiles.map(f => ({
-                value: f.path,
-                label: cleanFileName(f.name),
-                hint: f.path.split('/').slice(2, -1).join('/'),
-            })),
+            ...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,
+                };
+            }),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
+        footer: menuFooter(),
     });
-    if (isCancel(fileSelected) || fileSelected === '__back__')
+    if (fileSelected === null || fileSelected === '__back__')
         return;
     await viewMarkdownFile(fileSelected);
 }
 // ─── Document viewer ──────────────────────────────────────────────────────────
-async function viewMarkdownFile(filePath) {
+export async function viewMarkdownFile(filePath) {
     const trans = t();
-    while (true) {
-        try {
-            ensureMarkedConfigured();
-            const s = createSpinner(`${trans.docs.loadingFile}: ${filePath}`);
-            const rawContent = await fetchFileContent(filePath);
-            const fingerprint = contentFingerprint(rawContent);
-            const cachedRendered = getFreshRender(filePath);
-            let renderedDoc;
-            if (cachedRendered && cachedRendered.fingerprint === fingerprint) {
-                renderedDoc = cachedRendered;
-            }
-            else {
-                const cleaned = cleanMarkdownContent(rawContent, getTerminalType());
-                const title = extractDocTitle(rawContent, cleaned) || cleanFileName(filePath.split('/').pop() ?? filePath);
-                const readTime = estimateReadTime(cleaned);
-                const rendered = await marked(cleaned);
-                renderedDoc = { fingerprint, cleaned, rendered, title, readTime };
-                setRender(filePath, renderedDoc);
-            }
-            s.stop(`${chalk.bold(renderedDoc.title)}  ${chalk.dim(renderedDoc.readTime)}`);
-            const toc = extractTOC(renderedDoc.cleaned);
-            if (hasGlow()) {
-                await displayWithGlow(renderedDoc.cleaned);
-            }
-            else {
-                await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime, toc);
-            }
-            console.log();
-            success(trans.docs.docCompleted);
-            console.log();
-            const hasTable = hasMarkdownTable(rawContent);
-            const action = await select({
-                message: trans.docs.chooseAction,
-                options: [
-                    { value: 'back', label: trans.docs.backToList },
-                    { value: 'reread', label: trans.docs.reread },
-                    { value: 'browser', label: trans.docs.openBrowser,
-                        hint: hasTable ? trans.docs.tableHint : undefined },
-                ],
-            });
-            if (isCancel(action) || action === 'back')
-                return;
-            if (action === 'browser') {
-                await openDocsInBrowser(filePath);
-                return;
-            }
-            // 'reread' → loop
+    ensureMarkedConfigured();
+    const s = createSpinner(`${trans.docs.loadingFile}: ${filePath}`);
+    try {
+        const rawContent = await fetchFileContent(filePath);
+        const fingerprint = contentFingerprint(rawContent);
+        const cachedRendered = getFreshRender(filePath);
+        let renderedDoc;
+        if (cachedRendered && cachedRendered.fingerprint === fingerprint) {
+            renderedDoc = cachedRendered;
         }
-        catch (err) {
-            error(trans.docs.loadError);
-            const errMsg = err instanceof Error ? err.message : String(err);
-            console.log(chalk.gray(`  ${trans.docs.errorHint}: ${errMsg}`));
-            setVimKeysActive(false);
-            const openBrowser = await confirm({ message: trans.docs.openBrowserPrompt });
-            setVimKeysActive(true);
-            if (!isCancel(openBrowser) && openBrowser) {
-                await openDocsInBrowser(filePath);
-            }
-            return;
+        else {
+            const cleaned = cleanMarkdownContent(rawContent, getTerminalType());
+            const title = extractDocTitle(rawContent, cleaned) || cleanFileName(filePath.split('/').pop() ?? filePath);
+            const readTime = estimateReadTime(cleaned);
+            const rendered = await marked(cleaned);
+            renderedDoc = { fingerprint, cleaned, rendered, title, readTime };
+            setRender(filePath, renderedDoc);
+        }
+        s.stop(`${chalk.bold(renderedDoc.title)}  ${chalk.dim(renderedDoc.readTime)}`);
+        const toc = extractTOC(renderedDoc.cleaned);
+        if (hasGlow()) {
+            await displayWithGlow(renderedDoc.cleaned);
+        }
+        else {
+            await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime, toc);
+        }
+        const needsBrowser = hasMarkdownTable(rawContent) || hasMermaidBlock(rawContent);
+        const action = await runMenu({
+            title: trans.docs.chooseAction,
+            options: [
+                { value: 'back', label: trans.docs.backToList },
+                { value: 'browser', label: trans.docs.openBrowser,
+                    hint: needsBrowser ? trans.docs.tableHint : undefined },
+            ],
+            footer: menuFooter(),
+        });
+        if (action === 'browser') {
+            await openDocsInBrowser(filePath);
+        }
+    }
+    catch (err) {
+        s.error(trans.docs.loadError);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.log(chalk.gray(`  ${trans.docs.errorHint}: ${errMsg}`));
+        const openBrowser = await runConfirm({ message: trans.docs.openBrowserPrompt });
+        if (openBrowser === true) {
+            await openDocsInBrowser(filePath);
         }
     }
 }
@@ -488,13 +752,11 @@ export async function openDocsInBrowser(path) {
 // ─── Search ────────────────────────────────────────────────────────────────────
 async function searchDocs() {
     const trans = t();
-    setVimKeysActive(false);
-    const query = await text({
+    const query = await runTextInput({
         message: trans.docs.searchPrompt,
         placeholder: trans.docs.searchPlaceholder,
     });
-    setVimKeysActive(true);
-    if (isCancel(query) || !query.trim())
+    if (query === null || !query.trim())
         return;
     const keyword = query.trim().toLowerCase();
     const s = createSpinner(trans.docs.searching);
@@ -506,8 +768,8 @@ async function searchDocs() {
             warning(trans.docs.searchNoResults);
             return;
         }
-        const selected = await select({
-            message: trans.docs.chooseDoc,
+        const selected = await runMenu({
+            title: trans.docs.chooseDoc,
             options: [
                 ...results.map(r => ({
                     value: r.path,
@@ -516,8 +778,9 @@ async function searchDocs() {
                 })),
                 { value: '__back__', label: chalk.dim(trans.docs.returnToMenu) },
             ],
+            footer: menuFooter(),
         });
-        if (isCancel(selected) || selected === '__back__')
+        if (selected === null || selected === '__back__')
             return;
         await viewMarkdownFile(selected);
     }
@@ -527,35 +790,26 @@ async function searchDocs() {
 }
 // ─── Menu ─────────────────────────────────────────────────────────────────────
 export async function showDocsMenu() {
+    await enterScreen(breadcrumb(t().menu.docs));
     let sections = await loadSections();
     if (!sections)
         return;
     while (true) {
         const trans = t();
-        const action = await select({
-            message: trans.docs.chooseCategory,
+        const action = await runMenu({
+            title: trans.docs.chooseCategory,
             options: [
-                ...sections.map(sec => ({
-                    value: sec.key,
-                    label: sec.label,
-                    hint: `${sec.count} docs`,
-                })),
+                ...sections.map(sec => ({ value: sec.key, label: sec.label })),
                 { value: 'search', label: chalk.dim(trans.docs.searchPrompt.replace(':', '')) },
-                { value: 'refresh-cache', label: chalk.dim(trans.docs.refreshCache) },
                 { value: 'browser', label: chalk.dim(trans.docs.openBrowser) },
-                { value: 'back', label: chalk.dim(trans.docs.returnToMenu) },
             ],
+            footer: menuFooter(),
         });
-        if (isCancel(action) || action === 'back')
+        if (action === null)
             return;
         if (action === 'search') {
             await searchDocs();
         }
-        else if (action === 'refresh-cache') {
-            clearDocsCache();
-            sections = (await loadSections()) ?? sections;
-            success(trans.docs.cacheCleared);
-        }
         else if (action === 'browser') {
             await openDocsInBrowser();
         }