@nbtca/prompt 1.4.2 → 1.5.1

package/dist/features/docs.js

@@ -1,7 +1,7 @@
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import chalk from 'chalk';
-import open from 'open';
+import { createHash } from 'node:crypto';
 import { runMenu, menuFooter } from '../core/components/menu.js';
 import { runTextInput } from '../core/components/text-input.js';
 import { runConfirm } from '../core/components/confirm.js';
@@ -9,25 +9,31 @@ 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 { t, fmt, getCurrentLanguage } from '../i18n/index.js';
 import { enterScreen, breadcrumb } from '../core/transitions.js';
-import { createDocsClient } from '@nbtca/docs';
+import { sanitizeTerminalLine, sanitizeTerminalText, stripAnsi, truncate } from '../core/text.js';
+import { clearDocsClients, runDocsClientOperation } from './docs-client.js';
+import { launchBrowserUrl } from './links.js';
 function detectTerminalType() {
-    const term = (process.env['TERM'] || '').toLowerCase();
-    const termProgram = (process.env['TERM_PROGRAM'] || '').toLowerCase();
-    const hasImages = termProgram.includes('iterm') || term.includes('kitty') ||
-        termProgram.includes('wezterm') || term.includes('sixel');
-    const hasColor = process.env['COLORTERM'] !== undefined || term.includes('color') ||
-        term.includes('256') || term.includes('ansi') || termProgram !== '';
-    const hasUnicode = (process.env['LANG'] || '').includes('UTF-8') ||
-        (process.env['LC_ALL'] || '').includes('UTF-8');
+    const term = (process.env['TERM'] ?? '').toLowerCase();
+    const termProgram = (process.env['TERM_PROGRAM'] ?? '').toLowerCase();
+    const hasImages = termProgram.includes('iterm') ||
+        term.includes('kitty') ||
+        termProgram.includes('wezterm') ||
+        term.includes('sixel');
+    const hasColor = process.env['COLORTERM'] !== undefined ||
+        term.includes('color') ||
+        term.includes('256') ||
+        term.includes('ansi') ||
+        termProgram !== '';
+    const hasUnicode = (process.env['LANG'] ?? '').includes('UTF-8') ||
+        (process.env['LC_ALL'] ?? '').includes('UTF-8');
     if (hasImages && hasColor && hasUnicode)
         return 'advanced';
     if (hasColor && hasUnicode)
         return 'enhanced';
     return 'basic';
 }
-/** Check whether an external command exists on PATH (once at startup). */
 function commandExists(cmd) {
     try {
         const check = process.platform === 'win32' ? 'where' : 'which';
@@ -40,21 +46,14 @@ function commandExists(cmd) {
 }
 let _terminalType = null;
 function getTerminalType() {
-    if (_terminalType === null)
-        _terminalType = detectTerminalType();
+    _terminalType ??= detectTerminalType();
     return _terminalType;
 }
 let _hasGlow = null;
 function hasGlow() {
-    if (_hasGlow === null)
-        _hasGlow = commandExists('glow');
+    _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);
 }
@@ -63,7 +62,8 @@ export function ensureMarkedConfigured() {
     if (_markedConfigured)
         return;
     _markedConfigured = true;
-    const extension = markedTerminal(getRendererOptions(getTerminalType()));
+    const terminalType = getTerminalType();
+    const extension = markedTerminal(getRendererOptions(terminalType));
     const renderer = extension.renderer ?? (extension.renderer = {});
     const renderExternalLink = renderer.link;
     if (renderExternalLink) {
@@ -73,56 +73,58 @@ export function ensureMarkedConfigured() {
             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 this.parser.parseInline(withTokens.tokens);
             }
             return renderPlainText.call(this, token);
         };
     }
     marked.use(extension);
 }
-// ─── marked-terminal renderer ─────────────────────────────────────────────────
 function getRendererOptions(type) {
     const width = 80;
     const unicodeTableChars = {
-        top: '─', 'top-mid': '┬', 'top-left': '┌', 'top-right': '┐',
-        bottom: '─', 'bottom-mid': '┴', 'bottom-left': '└', 'bottom-right': '┘',
-        left: '│', 'left-mid': '├', mid: '─', 'mid-mid': '┼',
-        right: '│', 'right-mid': '┤', middle: '│'
+        top: '─',
+        'top-mid': '┬',
+        'top-left': '┌',
+        'top-right': '┐',
+        bottom: '─',
+        'bottom-mid': '┴',
+        'bottom-left': '└',
+        'bottom-right': '┘',
+        left: '│',
+        'left-mid': '├',
+        mid: '─',
+        'mid-mid': '┼',
+        right: '│',
+        'right-mid': '┤',
+        middle: '│',
     };
     const asciiTableChars = {
-        top: '-', 'top-mid': '+', 'top-left': '+', 'top-right': '+',
-        bottom: '-', 'bottom-mid': '+', 'bottom-left': '+', 'bottom-right': '+',
-        left: '|', 'left-mid': '+', mid: '-', 'mid-mid': '+',
-        right: '|', 'right-mid': '+', middle: '|'
+        top: '-',
+        'top-mid': '+',
+        'top-left': '+',
+        'top-right': '+',
+        bottom: '-',
+        'bottom-mid': '+',
+        'bottom-left': '+',
+        'bottom-right': '+',
+        left: '|',
+        'left-mid': '+',
+        mid: '-',
+        'mid-mid': '+',
+        right: '|',
+        'right-mid': '+',
+        middle: '|',
     };
     return {
         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,
@@ -135,14 +137,18 @@ function getRendererOptions(type) {
         link: chalk.cyan,
         href: chalk.cyan.underline,
         tableOptions: {
-            chars: type === 'basic' ? asciiTableChars : unicodeTableChars
-        }
+            chars: type === 'basic' ? asciiTableChars : unicodeTableChars,
+        },
     };
 }
 const RENDER_CACHE_TTL_MS = 10 * 60 * 1000;
 const RENDER_CACHE_MAX = 50;
 const renderCache = new Map();
-let docsClient = createDocsClient();
+const METADATA_CACHE_TTL_MS = 10 * 60 * 1000;
+const METADATA_CACHE_MAX = 200;
+const METADATA_CONCURRENCY = 4;
+const metadataCache = new Map();
+let cacheGeneration = 0;
 function getFreshRender(key) {
     const entry = renderCache.get(key);
     return entry && entry.expiresAt > Date.now() ? entry.value : null;
@@ -156,27 +162,108 @@ function setRender(key, value) {
     }
 }
 function contentFingerprint(content) {
-    return `${content.length}:${content.slice(0, 80)}:${content.slice(-80)}`;
+    return createHash('sha256').update(content).digest('base64url');
+}
+function renderCacheKey(filePath) {
+    return [
+        filePath,
+        getCurrentLanguage(),
+        getTerminalType(),
+        pickIcon('unicode', 'ascii'),
+        chalk.level,
+    ].join('\0');
 }
 export function clearDocsCache() {
-    docsClient.clear();
+    cacheGeneration += 1;
+    clearDocsClients();
     renderCache.clear();
+    metadataCache.clear();
 }
-async function fetchFileContent(path) {
+async function fetchDocument(path, signal) {
     try {
-        return await docsClient.getFile(path);
+        return await runDocsClientOperation(signal, (client) => client.getDocument(path));
     }
     catch (err) {
         const trans = t();
-        throw new Error(fmt(trans.docs.fetchFileFailed, { error: String(err) }));
+        throw new Error(fmt(trans.docs.fetchFileFailed, { error: sanitizeTerminalLine(String(err)) }));
     }
 }
-// ─── 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 metadataFromPage(page) {
+    return {
+        title: sanitizeTerminalLine(page.title),
+        summary: sanitizeTerminalLine(page.summary),
+        route: page.route,
+    };
+}
+function getFreshMetadata(path) {
+    const entry = metadataCache.get(path);
+    if (!entry)
+        return null;
+    if (entry.expiresAt <= Date.now()) {
+        metadataCache.delete(path);
+        return null;
+    }
+    metadataCache.delete(path);
+    metadataCache.set(path, entry);
+    return entry.value;
+}
+function setMetadata(path, value) {
+    metadataCache.delete(path);
+    metadataCache.set(path, { value, expiresAt: Date.now() + METADATA_CACHE_TTL_MS });
+    if (metadataCache.size > METADATA_CACHE_MAX) {
+        const oldest = metadataCache.keys().next().value;
+        if (oldest)
+            metadataCache.delete(oldest);
+    }
+}
+function loadDocMetadata(path, signal) {
+    const cached = getFreshMetadata(path);
+    if (cached)
+        return Promise.resolve(cached);
+    const generation = cacheGeneration;
+    return fetchDocument(path, signal).then((page) => {
+        const metadata = metadataFromPage(page);
+        if (generation === cacheGeneration)
+            setMetadata(path, metadata);
+        return metadata;
+    });
+}
+function normalizeRenderedTasks(content, type) {
+    if (type !== 'basic')
+        return content;
+    return content
+        .split('\n')
+        .map((line) => /^\s*(?:[-*+]|\d+[.)])\s+\[X\](?:\s|$)/.test(stripAnsi(line))
+        ? line.replace('[X]', '[x]')
+        : line)
+        .join('\n');
+}
+async function loadRenderedDoc(filePath, signal) {
+    const generation = cacheGeneration;
+    const page = await fetchDocument(filePath, signal);
+    if (generation === cacheGeneration)
+        setMetadata(filePath, metadataFromPage(page));
+    const rawContent = page.content;
+    const fingerprint = contentFingerprint(rawContent);
+    const cacheKey = renderCacheKey(filePath);
+    const cached = getFreshRender(cacheKey);
+    if (cached?.fingerprint === fingerprint)
+        return { rawContent, renderedDoc: cached };
+    const terminalType = getTerminalType();
+    const cleaned = cleanMarkdownContent(rawContent, terminalType);
+    const title = sanitizeTerminalLine(page.title) || cleanFileName(filePath.split('/').pop() ?? filePath);
+    const markedOutput = normalizeRenderedTasks(await marked(cleaned), terminalType);
+    const renderedDoc = {
+        fingerprint,
+        cleaned,
+        rendered: chalk.level === 0 ? sanitizeTerminalText(markedOutput) : markedOutput,
+        title,
+        readTime: estimateReadTime(cleaned),
+    };
+    if (generation === cacheGeneration)
+        setRender(cacheKey, renderedDoc);
+    return { rawContent, renderedDoc };
+}
 function processFencedCodeBlocks(content) {
     const trans = t();
     const lines = content.split('\n');
@@ -187,11 +274,15 @@ function processFencedCodeBlocks(content) {
     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]*$/);
+            const m = /^(`{3,})(\w+)?[^`\n]*$/.exec(line);
             if (m) {
+                const matchedFence = m[1];
+                if (!matchedFence) {
+                    result.push(line);
+                    continue;
+                }
                 inBlock = true;
-                fence = m[1];
+                fence = matchedFence;
                 blockLang = (m[2] ?? '').toLowerCase();
                 blockBody = [];
             }
@@ -204,9 +295,10 @@ function processFencedCodeBlocks(content) {
                 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 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}_`);
@@ -231,107 +323,245 @@ function processFencedCodeBlocks(content) {
     return result.join('\n');
 }
 const CONTAINER_ICONS_ASCII = {
-    info: '[INFO]', tip: '[TIP]', warning: '[WARN]', danger: '[DANGER]', details: '[DETAIL]'
+    info: '[INFO]',
+    tip: '[TIP]',
+    warning: '[WARN]',
+    danger: '[DANGER]',
+    details: '[DETAIL]',
 };
 const CONTAINER_ICONS_UNICODE = {
-    info: 'ℹ️', tip: '💡', warning: '⚠️', danger: '🚨', details: '▶️'
+    info: 'ℹ️',
+    tip: '💡',
+    warning: '⚠️',
+    danger: '🚨',
+    details: '▶️',
 };
-export function cleanMarkdownContent(content, type = getTerminalType()) {
+function componentAttributes(source) {
+    const attributes = new Map();
+    const pattern = /(?:^|\s)([:@\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+    for (const match of source.matchAll(pattern)) {
+        const name = match[1];
+        const value = match[2] ?? match[3];
+        if (name && value !== undefined)
+            attributes.set(name, sanitizeTerminalLine(value));
+    }
+    return attributes;
+}
+function replaceDocumentComponents(content) {
+    let result = content;
+    result = result.replace(/<PageHero\b([\s\S]*?)\/>/gi, (_match, source) => {
+        const attributes = componentAttributes(source);
+        const title = attributes.get('title');
+        const lede = attributes.get('lede');
+        return [title ? `# ${title}` : '', lede ?? ''].filter(Boolean).join('\n\n');
+    });
+    result = result.replace(/<LinkCard\b([\s\S]*?)\/>/gi, (_match, source) => {
+        const attributes = componentAttributes(source);
+        const href = attributes.get('href');
+        const title = attributes.get('title');
+        if (!href || !title)
+            return '';
+        const description = attributes.get('desc');
+        return `- [${title}](${href})${description ? ` — ${description}` : ''}`;
+    });
+    result = result.replace(/<(?:Figure|Band)\b([\s\S]*?)\/>/gi, (_match, source) => {
+        const attributes = componentAttributes(source);
+        const src = attributes.get('src');
+        if (!src)
+            return '';
+        const label = attributes.get('caption') ?? attributes.get('alt') ?? 'image';
+        const details = [attributes.get('date'), attributes.get('source')].filter(Boolean).join(' · ');
+        return `![${label}](${src})${details ? `\n\n_${details}_` : ''}`;
+    });
+    result = result.replace(/<Split\b([^>]*)>/gi, (_match, source) => {
+        const heading = componentAttributes(source).get('heading');
+        return heading ? `### ${heading}\n\n` : '';
+    });
+    result = result.replace(/<TimelineEntry\b([^>]*)>/gi, (_match, source) => {
+        const attributes = componentAttributes(source);
+        const heading = [attributes.get('year'), attributes.get('title')].filter(Boolean).join(' · ');
+        return heading ? `### ${heading}\n\n` : '';
+    });
+    result = result.replace(/<FactStrip\b([\s\S]*?)\/>/gi, (_match, source) => {
+        const facts = componentAttributes(source).get(':facts');
+        if (!facts)
+            return '';
+        return [...facts.matchAll(/\{\s*label:\s*'([^']*)'\s*,\s*value:\s*'([^']*)'\s*\}/g)]
+            .map((match) => `- **${match[1]}:** ${match[2]}`)
+            .join('\n');
+    });
+    return result;
+}
+function replaceHtmlCheckboxes(content, type) {
+    return content.replace(/<input\b([^>]*)\/?\s*>/gi, (tag, attributes) => {
+        const typeMatch = /(?:^|\s)type\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>/]+))/i.exec(attributes);
+        const inputType = (typeMatch?.[1] ?? typeMatch?.[2] ?? typeMatch?.[3] ?? '')
+            .trim()
+            .toLowerCase();
+        if (inputType !== 'checkbox')
+            return tag;
+        const checked = /(?:^|\s)checked(?=\s|=|\/|$)/i.test(attributes);
+        if (type === 'basic')
+            return checked ? '[x]' : '[ ]';
+        return checked ? '☑' : '☐';
+    });
+}
+function expandHtmlDetails(content) {
+    return content
+        .replace(/<summary\b[^>]*>([\s\S]*?)<\/summary\s*>/gi, (_match, label) => {
+        const summary = sanitizeTerminalLine(label);
+        return summary ? `\n\n### ${summary}\n\n` : '\n';
+    })
+        .replace(/<\/?(?:details|summary)\b[^>]*>/gi, '');
+}
+function transformOutsideFencedCodeBlocks(content, transform) {
+    const output = [];
+    let plain = [];
+    let fenceCharacter = '';
+    let fenceWidth = 0;
+    let listIndent = 0;
+    let listQuoteDepth = 0;
+    const flushPlain = () => {
+        if (plain.length === 0)
+            return;
+        output.push(transform(plain.join('\n')));
+        plain = [];
+    };
+    const lineContext = (line) => {
+        let rest = line;
+        let quoteDepth = 0;
+        for (;;) {
+            const quote = /^[ \t]{0,3}>[ \t]?/.exec(rest)?.[0];
+            if (!quote)
+                break;
+            quoteDepth += 1;
+            rest = rest.slice(quote.length);
+        }
+        return { quoteDepth, rest };
+    };
+    const fenceMarker = (line) => {
+        let { rest } = lineContext(line);
+        const list = /^[ \t]*(?:[-+*]|\d+[.)])[ \t]+/.exec(rest)?.[0];
+        if (list)
+            rest = rest.slice(list.length);
+        else if (listIndent > 0 && rest.startsWith(' '.repeat(listIndent))) {
+            rest = rest.slice(listIndent);
+        }
+        return /^ {0,3}(`{3,}|~{3,})/.exec(rest)?.[1];
+    };
+    for (const line of content.split('\n')) {
+        if (fenceWidth === 0) {
+            const { quoteDepth, rest } = lineContext(line);
+            const list = /^([ ]*)(?:[-+*]|\d+[.)])([ \t]+)/.exec(rest);
+            if (list) {
+                listIndent = list[0].length;
+                listQuoteDepth = quoteDepth;
+            }
+            else if (rest.trim() && (quoteDepth !== listQuoteDepth || rest.search(/\S/) < listIndent)) {
+                listIndent = 0;
+                listQuoteDepth = quoteDepth;
+            }
+            const opening = fenceMarker(line);
+            if (!opening) {
+                plain.push(line);
+                continue;
+            }
+            flushPlain();
+            fenceCharacter = opening[0] ?? '';
+            fenceWidth = opening.length;
+            output.push(line);
+            continue;
+        }
+        output.push(line);
+        const closing = fenceMarker(line);
+        const closingSuffix = closing ? line.slice(line.lastIndexOf(closing) + closing.length) : line;
+        if (closing?.[0] === fenceCharacter &&
+            closing.length >= fenceWidth &&
+            closingSuffix.trim() === '') {
+            fenceCharacter = '';
+            fenceWidth = 0;
+        }
+    }
+    flushPlain();
+    return output.join('\n');
+}
+function cleanMarkdownOutsideFences(content, terminalType) {
     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, '');
-    // 3. VitePress containers → blockquote with icon
+    c = replaceDocumentComponents(c);
     c = c.replace(/^:::\s*(info|tip|warning|danger|details)\s*(.*?)\n([\s\S]*?)^:::\s*$/gm, (_m, type, title, body) => {
-        const label = (title.trim() || type.charAt(0).toUpperCase() + type.slice(1));
+        const label = title.trim() || type.charAt(0).toUpperCase() + type.slice(1);
         const icon = pickIcon(CONTAINER_ICONS_UNICODE[type] ?? '', CONTAINER_ICONS_ASCII[type] ?? '');
-        const quoted = body.trimEnd().split('\n').map(l => `> ${l}`).join('\n');
+        const quoted = body
+            .trimEnd()
+            .split('\n')
+            .map((l) => `> ${l}`)
+            .join('\n');
         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'}`);
+    if (terminalType === 'basic') {
+        c = c.replace(/!\[([^\]]*)\]\([^)]+\)/g, (_match, alt) => `${pickIcon('📎', '[image]')} ${alt.length > 0 ? alt : 'image'}`);
     }
     else {
-        c = c.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_, alt, url) => {
-            const filename = url.split('/').pop() || url;
-            return `${pickIcon('🖼️', '[image]')} **${alt || 'image'}** _(${filename})_`;
+        c = c.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_match, alt, url) => {
+            const basename = url.split('/').pop();
+            const filename = basename?.length ? basename : url;
+            return `${pickIcon('🖼️', '[image]')} **${alt.length > 0 ? alt : 'image'}** _(${filename})_`;
         });
     }
-    // 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 = replaceHtmlCheckboxes(c, terminalType);
+    c = expandHtmlDetails(c);
+    c = c.replace(/<br\s*\/?>/gi, '\n');
+    c = c.replace(/<(?:hr|input|link|meta)\b[^>]*\/?>/gi, '');
     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();
-}
-function extractDocTitle(rawContent, cleanedContent) {
-    const fmMatch = rawContent.match(/^---\n[\s\S]*?\n---/m);
-    if (fmMatch) {
-        const titleMatch = fmMatch[0].match(/^title:\s*['"]?(.+?)['"]?\s*$/m);
-        if (titleMatch?.[1])
-            return titleMatch[1].trim();
+    c = c.replace(/<\/(?:Split|TimelineEntry)>/gi, '');
+    if (terminalType === 'basic') {
+        c = c.replace(/^(\s*(?:[-*+]|\d+[.)]) )\[x\]/gim, '$1[x]');
     }
-    const h1Match = cleanedContent.match(/^#\s+(.+)$/m);
-    return h1Match?.[1]?.trim() ?? null;
+    else {
+        c = c.replace(/^(\s*(?:[-*+]|\d+[.)]) )\[x\] /gim, '$1☑ ');
+        c = c.replace(/^(\s*(?:[-*+]|\d+[.)]) )\[ \] /gm, '$1☐ ');
+    }
+    return c.replace(/\n{3,}/g, '\n\n');
+}
+export function cleanMarkdownContent(content, type = getTerminalType()) {
+    let c = sanitizeTerminalText(content);
+    c = c.replace(/^---\n[\s\S]*?\n---(?:\n|$)/, '');
+    c = processFencedCodeBlocks(c);
+    c = transformOutsideFencedCodeBlocks(c, (value) => cleanMarkdownOutsideFences(value, type));
+    return c.trim();
 }
-/** Approximate reading time: ~200 words/min for technical Chinese/English prose. */
 function estimateReadTime(text) {
-    const cjkChars = (text.match(/[㐀-鿿]/g) || []).length;
+    const cjkChars = [...text.matchAll(/[㐀-鿿]/g)].length;
     const nonCjk = text.replace(/[㐀-鿿]/g, ' ');
     const words = nonCjk.trim().split(/\s+/).filter(Boolean).length;
     const units = words + cjkChars / 2;
     const mins = Math.max(1, Math.ceil(units / 220));
     return mins === 1 ? '~1 min' : `~${mins} min`;
 }
-/** Extract h2/h3 headings for TOC display (skips the h1 title). */
 function extractTOC(content) {
-    const lines = content.split('\n').filter(l => /^#{2,3}\s/.test(l));
-    return lines.map(l => {
-        const m = l.match(/^(#+)/);
+    const lines = content.split('\n').filter((l) => /^#{2,3}\s/.test(l));
+    return lines.map((l) => {
+        const m = /^(#+)/.exec(l);
         const level = m?.[1]?.length ?? 2;
         const text = l.replace(/^#+\s+/, '').trim();
         return (level === 3 ? '  ' : '') + text;
     });
 }
-/** 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;
@@ -343,14 +573,14 @@ function extractInternalLinks(markdown) {
     }
     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) {
+export function resolveInternalHref(href, fromPath) {
+    const normalizedHref = href.split(/[?#]/, 1)[0] ?? '';
     const fromDir = fromPath.includes('/') ? fromPath.slice(0, fromPath.lastIndexOf('/')) : '';
-    const combined = href.startsWith('/') ? href.slice(1) : (fromDir ? `${fromDir}/${href}` : href);
+    const combined = normalizedHref.startsWith('/')
+        ? normalizedHref.slice(1)
+        : fromDir
+            ? `${fromDir}/${normalizedHref}`
+            : normalizedHref;
     const stack = [];
     for (const part of combined.split('/')) {
         if (part === '' || part === '.')
@@ -362,33 +592,15 @@ function resolveInternalHref(href, fromPath) {
         stack.push(part);
     }
     let target = stack.join('/');
-    if (target === '' || href.endsWith('/'))
+    if (target === '' || normalizedHref.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) {
+export async function loadDocForReader(filePath, signal) {
     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 { renderedDoc } = await loadRenderedDoc(filePath, signal);
     const seen = new Set();
     const links = [];
     for (const raw of extractInternalLinks(renderedDoc.cleaned)) {
@@ -396,11 +608,15 @@ export async function loadDocForReader(filePath) {
         if (seen.has(resolved))
             continue;
         seen.add(resolved);
-        links.push({ text: raw.text, href: resolved });
+        links.push({ text: sanitizeTerminalLine(raw.text), href: resolved });
     }
-    return { path: filePath, title: renderedDoc.title, lines: renderedDoc.rendered.split('\n'), links };
+    return {
+        path: filePath,
+        title: renderedDoc.title,
+        lines: renderedDoc.rendered.split('\n'),
+        links,
+    };
 }
-// ─── Document tree ────────────────────────────────────────────────────────────
 const TOP_SECTION_ORDER = ['about', 'guide', 'repair', 'concepts', 'archived'];
 const TOP_SECTION_SKIP = new Set(['docs', 'index.md', 'README.md']);
 const SECTION_ALIAS = { tutorial: 'guide', process: 'guide' };
@@ -415,38 +631,73 @@ export function localizeDocSections(sections, trans = t()) {
     return sections.map((section) => ({ ...section, label: labels[section.key] ?? section.label }));
 }
 export function cleanFileName(name) {
-    const base = name.replace(/\.md$/, '');
+    const base = sanitizeTerminalLine(name).replace(/\.md$/, '');
     if (/^[\d.]/.test(base))
         return base;
-    return base
-        .replace(/[-_]/g, ' ')
-        .replace(/\b([a-z])/g, (_, c) => c.toUpperCase());
-}
-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)',
-};
-export function displayDocTitle(path, name) {
-    return KNOWN_DOC_TITLES[path] ?? cleanFileName(name);
+    return base.replace(/[-_]/g, ' ').replace(/\b([a-z])/g, (_, c) => c.toUpperCase());
+}
+export function displayDocTitle(name, title) {
+    const candidate = title?.trim();
+    return sanitizeTerminalLine(candidate?.length ? candidate : cleanFileName(name));
+}
+function listedDoc(item, metadata) {
+    return {
+        ...item,
+        name: sanitizeTerminalLine(item.name),
+        title: displayDocTitle(item.name, metadata?.title),
+        summary: sanitizeTerminalLine(metadata?.summary ?? ''),
+    };
+}
+export async function fetchDocMetadata(items, signal) {
+    const results = items.map((item) => listedDoc(item));
+    let nextIndex = 0;
+    async function worker() {
+        for (;;) {
+            const index = nextIndex;
+            nextIndex += 1;
+            if (index >= items.length)
+                return;
+            const item = items[index];
+            if (!item)
+                continue;
+            if (signal?.aborted) {
+                throw signal.reason instanceof Error
+                    ? signal.reason
+                    : new DOMException('Aborted', 'AbortError');
+            }
+            try {
+                results[index] = listedDoc(item, await loadDocMetadata(item.path, signal));
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+                results[index] = listedDoc(item);
+            }
+        }
+    }
+    const workerCount = Math.min(METADATA_CONCURRENCY, items.length);
+    await Promise.all(Array.from({ length: workerCount }, worker));
+    return results;
+}
+export async function fetchSectionMetadata(section, signal) {
+    const files = await fetchDocMetadata(section.files, signal);
+    return { ...section, count: files.length, files };
+}
+function searchDoc(result) {
+    return {
+        name: sanitizeTerminalLine(result.name),
+        path: result.path,
+        type: 'file',
+        title: displayDocTitle(result.name, result.title),
+        summary: sanitizeTerminalLine(result.summary),
+        excerpt: sanitizeTerminalLine(result.excerpt),
+        route: result.route,
+        score: result.score,
+        section: result.section,
+    };
+}
+export async function searchDocuments(query, signal) {
+    return (await runDocsClientOperation(signal, (client) => client.search(query, { limit: 20 }))).map(searchDoc);
 }
 export function buildSections(all) {
     const groups = new Map();
@@ -455,39 +706,43 @@ export function buildSections(all) {
         if (parts.length < 2)
             continue;
         const rawTop = parts[0];
+        if (!rawTop)
+            continue;
         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 localizeDocSections(TOP_SECTION_ORDER
-        .filter(k => groups.has(k))
-        .map(k => ({
-        key: k,
-        label: k,
-        count: groups.get(k).length,
-        files: groups.get(k),
-    })));
+        const items = groups.get(top);
+        const file = listedDoc(item);
+        if (items)
+            items.push(file);
+        else
+            groups.set(top, [file]);
+    }
+    const orderedGroups = TOP_SECTION_ORDER.flatMap((key) => {
+        const files = groups.get(key);
+        return files ? [{ key, label: key, count: files.length, files }] : [];
+    });
+    return localizeDocSections(orderedGroups);
 }
 export function getArchivedGroups(files) {
     const groups = new Map();
     for (const item of files) {
         const group = item.path.split('/')[1] ?? 'other';
-        if (!groups.has(group))
-            groups.set(group, []);
-        groups.get(group).push(item);
+        const items = groups.get(group);
+        if (items)
+            items.push(item);
+        else
+            groups.set(group, [item]);
     }
     return groups;
 }
-export async function fetchAllDocs() {
-    return docsClient.listAll();
+export async function fetchAllDocs(signal) {
+    return runDocsClientOperation(signal, (client) => client.listAll());
 }
-export async function fetchSections() {
-    return buildSections(await fetchAllDocs());
+export async function fetchSections(signal) {
+    return buildSections(await fetchAllDocs(signal));
 }
 async function loadSections() {
     const trans = t();
@@ -502,19 +757,49 @@ async function loadSections() {
         return null;
     }
 }
-// ─── Pager layer ──────────────────────────────────────────────────────────────
-async function displayWithGlow(cleanedMarkdown) {
-    const cols = String(Math.min(process.stdout.columns || 80, 80));
-    return new Promise(resolve => {
-        const child = spawn('glow', ['--pager', '--width', cols, '-'], {
-            stdio: ['pipe', 'inherit', 'inherit']
+function pipeToPager(command, args, content, plain = false) {
+    return new Promise((resolve) => {
+        const env = { ...process.env };
+        if (plain) {
+            delete env['FORCE_COLOR'];
+            env['NO_COLOR'] = '1';
+            env['CLICOLOR'] = '0';
+            env['CLICOLOR_FORCE'] = '0';
+        }
+        const child = spawn(command, args, {
+            stdio: ['pipe', 'inherit', 'inherit'],
+            ...(plain ? { env } : {}),
         });
-        child.stdin.write(cleanedMarkdown, 'utf-8');
-        child.stdin.end();
-        child.on('close', resolve);
-        child.on('error', resolve);
+        let settled = false;
+        const finish = (started) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(started);
+        };
+        child.once('close', () => {
+            finish(true);
+        });
+        child.once('error', () => {
+            finish(false);
+        });
+        child.stdin.once('error', () => {
+            finish(true);
+        });
+        try {
+            child.stdin.end(content, 'utf8');
+        }
+        catch {
+            finish(false);
+        }
     });
 }
+export async function displayWithGlow(cleanedMarkdown) {
+    if (chalk.level === 0)
+        return false;
+    const cols = String(Math.min(process.stdout.columns || 80, 80));
+    return pipeToPager('glow', ['--pager', '--width', cols, '-'], cleanedMarkdown);
+}
 async function displayWithLess(rendered, title, filePath, readTime, toc) {
     const trans = t();
     const cols = Math.min(process.stdout.columns || 80, 80);
@@ -523,7 +808,7 @@ async function displayWithLess(rendered, title, filePath, readTime, toc) {
         ? [
             chalk.dim(`  ${trans.docs.tocTitle}`),
             chalk.dim(`  ${'─'.repeat(36)}`),
-            ...toc.map(h => chalk.dim(`  ${h}`)),
+            ...toc.map((h) => chalk.dim(`  ${h}`)),
             chalk.dim(`  ${'─'.repeat(36)}`),
             '',
         ].join('\n')
@@ -536,49 +821,44 @@ async function displayWithLess(rendered, title, filePath, readTime, toc) {
         ...(tocBlock ? [tocBlock] : []),
         '',
     ].join('\n');
-    const footer = [
-        '',
-        rule,
-        chalk.dim(`  ${trans.docs.endOfDocument}`),
-        '',
-    ].join('\n');
-    const fullContent = header + rendered + footer;
-    const pagerSetting = (process.env['PAGER'] || 'less').trim();
+    const footer = ['', rule, chalk.dim(`  ${trans.docs.endOfDocument}`), ''].join('\n');
+    const plain = chalk.level === 0;
+    const fullContent = plain
+        ? sanitizeTerminalText(header + rendered + footer)
+        : header + rendered + footer;
+    const pagerSetting = (process.env['PAGER'] ?? 'less').trim();
     const [pagerCommand = 'less', ...pagerArgs] = pagerSetting.split(/\s+/).filter(Boolean);
-    const args = [...pagerArgs, '-R', '-F', '-X', '-i', '-j4'];
+    const isLess = /(?:^|[\\/])less(?:\.exe)?$/i.test(pagerCommand);
+    const args = isLess
+        ? [...pagerArgs, ...(plain ? [] : ['-R']), '-F', '-X', '-i', '-j4']
+        : pagerArgs;
     if (!commandExists(pagerCommand)) {
         console.log(fullContent);
         return;
     }
-    return new Promise(resolve => {
-        try {
-            const child = spawn(pagerCommand, args, { stdio: ['pipe', 'inherit', 'inherit'] });
-            child.stdin.write(fullContent, 'utf-8');
-            child.stdin.end();
-            child.on('close', resolve);
-            child.on('error', () => { console.log(fullContent); resolve(); });
-        }
-        catch {
-            console.log(fullContent);
-            resolve();
-        }
-    });
+    if (!(await pipeToPager(pagerCommand, args, fullContent, plain)))
+        console.log(fullContent);
 }
-// ─── Section browsers ─────────────────────────────────────────────────────────
-/** Show a flat file list for tutorial / process / repair. */
 async function showDocSection(section) {
     const trans = t();
     if (section.key === 'archived') {
         await showArchivedSection(section.files);
         return;
     }
-    const files = section.files.filter(f => f.name !== 'index.md' && !f.name.startsWith('index.'));
+    const spinner = createSpinner(trans.docs.loading);
+    const hydrated = await fetchSectionMetadata(section);
+    spinner.stop();
+    const files = hydrated.files.filter((file) => file.name !== 'index.md' && !file.name.startsWith('index.'));
     if (files.length === 0)
         return;
     const selected = await runMenu({
-        title: section.label,
+        title: hydrated.label,
         options: [
-            ...files.map(f => ({ value: f.path, label: cleanFileName(f.name) })),
+            ...files.map((file) => ({
+                value: file.path,
+                label: displayDocTitle(file.name, file.title),
+                ...(!file.summary ? {} : { hint: file.summary }),
+            })),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
         footer: menuFooter(),
@@ -587,7 +867,6 @@ async function showDocSection(section) {
         return;
     await viewMarkdownFile(selected);
 }
-/** Show archived docs grouped by year, then files within the year. */
 async function showArchivedSection(files) {
     const trans = t();
     const groups = getArchivedGroups(files);
@@ -605,10 +884,10 @@ async function showArchivedSection(files) {
     const groupKey = await runMenu({
         title: trans.docs.categoryArchived,
         options: [
-            ...sortedKeys.map(k => ({
+            ...sortedKeys.map((k) => ({
                 value: k,
                 label: k,
-                hint: String(groups.get(k).length),
+                hint: String(groups.get(k)?.length ?? 0),
             })),
             { value: '__back__', label: chalk.dim(trans.common.back) },
         ],
@@ -616,17 +895,19 @@ async function showArchivedSection(files) {
     });
     if (groupKey === null || groupKey === '__back__')
         return;
-    const groupFiles = groups.get(groupKey) ?? [];
-    const subDirs = new Set(groupFiles.map(f => f.path.split('/')[2]).filter(Boolean));
+    const spinner = createSpinner(trans.docs.loading);
+    const groupFiles = await fetchDocMetadata(groups.get(groupKey) ?? []);
+    spinner.stop();
+    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 => {
+            ...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,
+                    label: displayDocTitle(f.name, f.title),
+                    ...(subDirs.size > 1 ? { hint: sanitizeTerminalLine(sub) } : {}),
                 };
             }),
             { value: '__back__', label: chalk.dim(trans.common.back) },
@@ -637,31 +918,18 @@ async function showArchivedSection(files) {
         return;
     await viewMarkdownFile(fileSelected);
 }
-// ─── Document viewer ──────────────────────────────────────────────────────────
-export async function viewMarkdownFile(filePath) {
+async function viewMarkdownFile(filePath) {
     const trans = t();
     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;
-        }
-        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 { rawContent, renderedDoc } = await loadRenderedDoc(filePath);
         s.stop(`${chalk.bold(renderedDoc.title)}  ${chalk.dim(renderedDoc.readTime)}`);
         const toc = extractTOC(renderedDoc.cleaned);
-        if (hasGlow()) {
-            await displayWithGlow(renderedDoc.cleaned);
+        if (chalk.level > 0 && hasGlow()) {
+            if (!(await displayWithGlow(renderedDoc.cleaned))) {
+                await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime, toc);
+            }
         }
         else {
             await displayWithLess(renderedDoc.rendered, renderedDoc.title, filePath, renderedDoc.readTime, toc);
@@ -671,8 +939,11 @@ export async function viewMarkdownFile(filePath) {
             title: trans.docs.chooseAction,
             options: [
                 { value: 'back', label: trans.docs.backToList },
-                { value: 'browser', label: trans.docs.openBrowser,
-                    hint: needsBrowser ? trans.docs.tableHint : undefined },
+                {
+                    value: 'browser',
+                    label: trans.docs.openBrowser,
+                    ...(needsBrowser ? { hint: trans.docs.tableHint } : {}),
+                },
             ],
             footer: menuFooter(),
         });
@@ -682,7 +953,7 @@ export async function viewMarkdownFile(filePath) {
     }
     catch (err) {
         s.error(trans.docs.loadError);
-        const errMsg = err instanceof Error ? err.message : String(err);
+        const errMsg = sanitizeTerminalLine(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) {
@@ -690,37 +961,80 @@ export async function viewMarkdownFile(filePath) {
         }
     }
 }
-// ─── Browser fallback ─────────────────────────────────────────────────────────
-export async function openDocsInBrowser(path) {
+export async function openDocsInBrowser(path, signal) {
     const trans = t();
     const s = createSpinner(trans.docs.opening);
+    let url = docsUrlFromPath(path);
     try {
-        const url = path
-            ? `${URLS.docs}/${path.replace(/\.md$/, '')}`
-            : URLS.docs;
-        await open(url);
+        if (path) {
+            try {
+                url = docsUrlFromRoute((await loadDocMetadata(path, signal)).route);
+            }
+            catch {
+                if (signal?.aborted) {
+                    s.stop();
+                    return false;
+                }
+                url = docsUrlFromPath(path);
+            }
+        }
+        if (signal?.aborted) {
+            s.stop();
+            return false;
+        }
+        if (!(await launchBrowserUrl(url)))
+            throw new Error('Browser launcher failed');
+        if (signal?.aborted) {
+            s.stop();
+            return false;
+        }
         s.stop(trans.docs.browserOpened);
+        console.log();
+        return true;
     }
     catch {
+        if (signal?.aborted) {
+            s.stop();
+            return false;
+        }
         s.error(trans.docs.browserError);
-        console.log(chalk.gray(`  ${trans.docs.browserErrorHint}`));
+        console.log(chalk.gray(`  ${fmt(t().links.openManually, { url })}`));
+        console.log();
+        return false;
     }
-    console.log();
 }
-// ─── Search ────────────────────────────────────────────────────────────────────
+function docsUrlFromRoute(route) {
+    const safeRoute = sanitizeTerminalLine(route);
+    if (!safeRoute)
+        return URLS.docs;
+    const encodedRoute = safeRoute
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+    return `${URLS.docs}${encodedRoute}`;
+}
+export function docsUrlFromPath(path) {
+    return path ? docsUrlFromRoute(docsRouteFromPath(sanitizeTerminalLine(path))) : URLS.docs;
+}
+export function docsRouteFromPath(path) {
+    const withoutExtension = path.replace(/\.md$/i, '');
+    if (withoutExtension === 'index')
+        return '/';
+    if (withoutExtension.endsWith('/index'))
+        return `/${withoutExtension.slice(0, -5)}`;
+    return `/${withoutExtension}`;
+}
 async function searchDocs() {
     const trans = t();
     const query = await runTextInput({
         message: trans.docs.searchPrompt,
         placeholder: trans.docs.searchPlaceholder,
     });
-    if (query === null || !query.trim())
+    if (!query?.trim())
         return;
-    const keyword = query.trim().toLowerCase();
     const s = createSpinner(trans.docs.searching);
     try {
-        const all = await docsClient.listAll();
-        const results = all.filter(item => item.path.toLowerCase().includes(keyword));
+        const results = await searchDocuments(query.trim());
         s.stop(`${results.length} ${trans.docs.searchResults}`);
         if (results.length === 0) {
             warning(trans.docs.searchNoResults);
@@ -729,10 +1043,14 @@ async function searchDocs() {
         const selected = await runMenu({
             title: trans.docs.chooseDoc,
             options: [
-                ...results.map(r => ({
+                ...results.map((r) => ({
                     value: r.path,
-                    label: cleanFileName(r.name),
-                    hint: r.path.includes('/') ? r.path.split('/').slice(0, -1).join('/') : '',
+                    label: r.title,
+                    hint: truncate(r.excerpt ||
+                        r.summary ||
+                        (r.path.includes('/')
+                            ? sanitizeTerminalLine(r.path.split('/').slice(0, -1).join('/'))
+                            : ''), 44),
                 })),
                 { value: '__back__', label: chalk.dim(trans.docs.returnToMenu) },
             ],
@@ -746,18 +1064,17 @@ async function searchDocs() {
         s.error(trans.docs.loadError);
     }
 }
-// ─── Menu ─────────────────────────────────────────────────────────────────────
 export async function showDocsMenu() {
     await enterScreen(breadcrumb(t().menu.docs));
-    let sections = await loadSections();
+    const sections = await loadSections();
     if (!sections)
         return;
-    while (true) {
+    for (;;) {
         const trans = t();
         const action = await runMenu({
             title: trans.docs.chooseCategory,
             options: [
-                ...sections.map(sec => ({ value: sec.key, label: sec.label })),
+                ...sections.map((sec) => ({ value: sec.key, label: sec.label })),
                 { value: 'search', label: chalk.dim(trans.docs.searchPrompt.replace(':', '')) },
                 { value: 'browser', label: chalk.dim(trans.docs.openBrowser) },
             ],
@@ -772,7 +1089,7 @@ export async function showDocsMenu() {
             await openDocsInBrowser();
         }
         else {
-            const section = sections.find(s => s.key === action);
+            const section = sections.find((s) => s.key === action);
             if (section)
                 await showDocSection(section);
         }