mdzilla 0.1.0 → 0.2.0

package/dist/cli/main.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { a as DocsSourceFS, i as DocsSourceGit, n as DocsSourceNpm, r as DocsSourceHTTP, s as DocsManager, t as exportDocsToFS } from "../_chunks/exporter.mjs";
+import { l as extractSnippets, n as writeCollection, r as resolveSource, u as Collection } from "../_chunks/exporter.mjs";
+import { parseMeta, renderToAnsi, renderToText } from "md4x";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { parseMeta, renderToAnsi, renderToText } from "md4x";
 import { parseArgs } from "node:util";
 import { isAgent } from "std-env";
 import { highlightText } from "@speed-highlight/core/terminal";
@@ -11,33 +11,13 @@ import { exec, execFile } from "node:child_process";
 const noColor = !!(process.env.NO_COLOR || process.env.TERM === "dumb" || !process.stdout.isTTY || isAgent);
 const ESC = "\x1B[";
 const ANSI_RE = /\x1B(?:\[[0-9;]*[a-zA-Z]|\][^\x07\x1B]*(?:\x07|\x1B\\))/g;
-const clear = () => process.stdout.write(`${ESC}2J${ESC}3J${ESC}H`);
-const enterAltScreen = () => process.stdout.write(`${ESC}?1049h`);
-const leaveAltScreen = () => process.stdout.write(`${ESC}?1049l`);
-const hideCursor = () => process.stdout.write(`${ESC}?25l`);
-const showCursor = () => process.stdout.write(`${ESC}?25h`);
 const bold = (s) => noColor ? s : `${ESC}1m${s}${ESC}0m`;
 const dim = (s) => noColor ? s : `${ESC}2m${s}${ESC}0m`;
 const cyan = (s) => noColor ? s : `${ESC}36m${s}${ESC}0m`;
 const yellow = (s) => noColor ? s : `${ESC}33m${s}${ESC}0m`;
-const bgGray = (s) => {
-	if (noColor) return s;
-	const bg = `${ESC}48;5;237m`;
-	return `${bg}${s.replaceAll(`${ESC}0m`, `${ESC}0m${bg}`)}${ESC}0m`;
-};
 const stripAnsi = (s) => s.replace(ANSI_RE, "");
-const visibleLength = (s) => stripAnsi(s).length;
-function padTo(s, width) {
-	const visible = visibleLength(s);
-	if (visible >= width) return truncateTo(s, width);
-	return s + " ".repeat(width - visible);
-}
-function truncateTo(s, width) {
-	if (visibleLength(s) <= width) return s;
-	return wrapAnsi(s, width)[0] || "";
-}
 function wrapAnsi(s, width) {
-	if (width <= 0 || visibleLength(s) <= width) return [s];
+	if (width <= 0 || stripAnsi(s).length <= width) return [s];
 	const tokens = [];
 	let last = 0;
 	const re = new RegExp(ANSI_RE.source, "g");
@@ -83,74 +63,18 @@ function wrapAnsi(s, width) {
 	}
 	return lines;
 }
-/** Highlight query matches inside an already-ANSI-styled string */
-function highlightAnsi(s, query) {
-	if (!query) return s;
-	const re = new RegExp(ANSI_RE.source, "g");
-	const visibleChars = [];
-	let last = 0;
-	let match;
-	while ((match = re.exec(s)) !== null) {
-		for (let i = last; i < match.index; i++) visibleChars.push({
-			char: s[i],
-			rawIdx: i
-		});
-		last = match.index + match[0].length;
-	}
-	for (let i = last; i < s.length; i++) visibleChars.push({
-		char: s[i],
-		rawIdx: i
-	});
-	const lowerVisible = visibleChars.map((c) => c.char).join("").toLowerCase();
+function highlight(text, query) {
+	if (!query) return text;
+	const lowerText = text.toLowerCase();
 	const lowerQuery = query.toLowerCase();
-	const matches = [];
-	let pos = 0;
-	while ((pos = lowerVisible.indexOf(lowerQuery, pos)) >= 0) {
-		matches.push([pos, pos + query.length]);
-		pos += 1;
-	}
-	if (matches.length === 0) return s;
-	const hlRanges = [];
-	for (const [start, end] of matches) {
-		const rawStart = visibleChars[start].rawIdx;
-		const rawEnd = end < visibleChars.length ? visibleChars[end].rawIdx : s.length;
-		hlRanges.push([rawStart, rawEnd]);
-	}
-	const hlOn = `${ESC}7m`;
-	const hlOff = `${ESC}27m`;
-	const resetSeq = `${ESC}0m`;
 	let result = "";
-	let inHighlight = false;
-	let rawIdx = 0;
-	const escRe = new RegExp(ANSI_RE.source, "g");
-	let escMatch;
-	const escapes = [];
-	while ((escMatch = escRe.exec(s)) !== null) escapes.push({
-		idx: escMatch.index,
-		seq: escMatch[0]
-	});
-	let escIdx = 0;
-	for (rawIdx = 0; rawIdx <= s.length; rawIdx++) {
-		const wasIn = inHighlight;
-		inHighlight = hlRanges.some(([a, b]) => rawIdx >= a && rawIdx < b);
-		if (inHighlight && !wasIn) result += hlOn;
-		if (!inHighlight && wasIn) result += hlOff;
-		if (rawIdx >= s.length) break;
-		if (escIdx < escapes.length && escapes[escIdx].idx === rawIdx) {
-			const esc = escapes[escIdx];
-			result += esc.seq;
-			if (inHighlight && esc.seq === resetSeq) result += hlOn;
-			rawIdx += esc.seq.length - 1;
-			escIdx++;
-		} else result += s[rawIdx];
+	let last = 0;
+	let pos = 0;
+	while ((pos = lowerText.indexOf(lowerQuery, last)) >= 0) {
+		result += text.slice(last, pos) + bold(yellow(text.slice(pos, pos + query.length)));
+		last = pos + query.length;
 	}
-	return result;
-}
-function highlight(text, query) {
-	if (!query) return text;
-	const idx = text.toLowerCase().indexOf(query.toLowerCase());
-	if (idx < 0) return text;
-	return text.slice(0, idx) + bold(yellow(text.slice(idx, idx + query.length))) + text.slice(idx + query.length);
+	return last === 0 ? text : result + text.slice(last);
 }
 //#endregion
 //#region src/cli/_usage.ts
@@ -175,31 +99,34 @@ function printUsage(hasInput) {
 		`  ${bold("mdzilla")} ${dim("— Markdown browser for humans and agents")}`,
 		"",
 		`${bold("Usage:")}`,
-		`  ${bin} ${cyan("<dir>")}                 ${dim("Browse local docs directory")}`,
-		`  ${bin} ${cyan("<file.md>")}             ${dim("Render a single markdown file")}`,
-		`  ${bin} ${cyan("gh:owner/repo")}         ${dim("Browse GitHub repo docs")}`,
-		`  ${bin} ${cyan("npm:package-name")}      ${dim("Browse npm package docs")}`,
-		`  ${bin} ${cyan("https://example.com")}   ${dim("Browse remote docs via HTTP")}`,
+		`  ${bin} ${cyan("<source>")}                           ${dim("Open docs in browser")}`,
+		`  ${bin} ${cyan("<source>")} ${cyan("<path>")}                    ${dim("Render a specific page")}`,
+		`  ${bin} ${cyan("<source>")} ${cyan("<query>")}                   ${dim("Search docs")}`,
+		`  ${bin} ${cyan("<file.md>")}                          ${dim("Render a single markdown file")}`,
+		"",
+		`${bold("Sources:")}`,
+		`  ${cyan("./docs")}                Local directory`,
+		`  ${cyan("gh:owner/repo")}         GitHub repo (looks for docs/ directory)`,
+		`  ${cyan("npm:package-name")}      npm package docs`,
+		`  ${cyan("https://example.com")}   Remote docs via HTTP / llms.txt`,
 		"",
 		`${bold("Options:")}`,
 		`  ${cyan("--export")} ${dim("<dir>")}   Export docs to flat .md files`,
-		`  ${cyan("--page")} ${dim("<path>")}    Print a single page and exit`,
-		`  ${cyan("--plain")}          Plain text output (no TUI)`,
-		`  ${cyan("--headless")}       Alias for --plain`,
+		`  ${cyan("--plain")}          Plain text output (auto-enabled for agents / non-TTY)`,
 		`  ${cyan("-h, --help")}       Show this help message`,
 		"",
-		`${bold("Remarks:")}`,
-		`  ${dim("Headless mode is auto-enabled when called by AI agents or when stdout is not a TTY.")}`,
-		`  ${dim("GitHub source (gh:) looks for a docs/ directory in the repository.")}`,
-		`  ${dim("HTTP source tries /llms.txt first, then fetches with Accept: text/markdown,")}`,
-		`  ${dim("and falls back to HTML-to-markdown conversion.")}`
+		`${bold("Examples:")}`,
+		`  ${bin} ${cyan("gh:unjs/h3")}                         ${dim("Open H3 docs in browser")}`,
+		`  ${bin} ${cyan("gh:unjs/h3 /guide/basics")}           ${dim("Render a specific page")}`,
+		`  ${bin} ${cyan("gh:unjs/h3 router")}                  ${dim("Search for 'router'")}`,
+		`  ${bin} ${cyan("gh:unjs/h3 --export ./h3-docs")}      ${dim("Export to flat files")}`
 	].join("\n"));
 	process.exit(hasInput ? 0 : 1);
 }
 //#endregion
 //#region src/cli/content.ts
-async function renderContent(content, entry, navWidth) {
-	const contentWidth = (process.stdout.columns || 80) - navWidth - 2;
+async function renderContent(content, entry) {
+	const cols = process.stdout.columns || 80;
 	const codeBlocks = [];
 	const codeRe = /```(\w+)[^\n]*\n([\s\S]*?)```/g;
 	let m;
@@ -230,18 +157,27 @@ async function renderContent(content, entry, navWidth) {
 				if (hl) {
 					const hlLines = hl.split("\n");
 					if (hlLines.length > 0 && hlLines[hlLines.length - 1] === "") hlLines.pop();
-					for (const hlLine of hlLines) for (const w of wrapAnsi("  " + hlLine, contentWidth)) lines.push(w + "\x1B[0m");
-				} else for (const dl of dimLines) for (const w of wrapAnsi(dl, contentWidth)) lines.push(w + "\x1B[0m");
+					for (const hlLine of hlLines) for (const w of wrapAnsi("  " + hlLine, cols)) lines.push(w + "\x1B[0m");
+				} else for (const dl of dimLines) for (const w of wrapAnsi(dl, cols)) lines.push(w + "\x1B[0m");
 				blockIdx++;
 				lines.push("");
 			} else dimLines.push(rawLine);
 			continue;
 		}
-		for (const w of wrapAnsi(rawLine, contentWidth)) lines.push(w + "\x1B[0m");
+		for (const w of wrapAnsi(rawLine, cols)) lines.push(w + "\x1B[0m");
 	}
 	return lines;
 }
 //#endregion
+//#region src/cli/_utils.ts
+function openInBrowser(url) {
+	const parsed = new URL(url);
+	if (parsed.hostname === "[::]" || parsed.hostname === "[::1]" || parsed.hostname === "127.0.0.1") parsed.hostname = "localhost";
+	url = parsed.href;
+	if (process.platform === "win32") exec(`start "" ${JSON.stringify(url)}`, () => {});
+	else execFile(process.platform === "darwin" ? "open" : "xdg-open", [url], () => {});
+}
+//#endregion
 //#region src/cli/render.ts
 async function singleFileMode(filePath, plain, isURL) {
 	const raw = isURL ? await fetch(filePath, { headers: { accept: "text/markdown, text/plain;q=0.9, text/html;q=0.8" } }).then((r) => r.text()) : await readFile(filePath, "utf8");
@@ -256,16 +192,16 @@ async function singleFileMode(filePath, plain, isURL) {
 		path: "/" + slug,
 		title: meta.title || slug,
 		order: 0
-	}, 0);
+	});
 	process.stdout.write(lines.join("\n") + "\n");
 }
-async function pageMode(docs, pagePath, plain) {
-	const normalized = pagePath.startsWith("/") ? pagePath : "/" + pagePath;
-	const { entry, raw } = await docs.resolvePage(normalized);
+async function renderPage(docs, resolved, pagePath, plain) {
+	const { entry, raw } = resolved;
 	if (!raw) {
-		console.error(`Page not found: ${pagePath}`);
+		printNotFound(docs, pagePath);
 		process.exit(1);
 	}
+	const normalized = pagePath.startsWith("/") ? pagePath : "/" + pagePath;
 	const slug = (entry?.entry.path || normalized).split("/").pop() || "";
 	const navEntry = entry?.entry || {
 		slug,
@@ -277,38 +213,81 @@ async function pageMode(docs, pagePath, plain) {
 		process.stdout.write(renderToText(raw) + "\n");
 		if (isAgent) process.stdout.write(agentTrailer(docs, normalized));
 	} else {
-		const lines = await renderContent(raw, navEntry, 0);
+		const lines = await renderContent(raw, navEntry);
 		process.stdout.write(lines.join("\n") + "\n");
 	}
 }
-async function plainMode(docs, pagePath) {
+async function searchMode(docs, query, plain) {
+	let count = 0;
+	const matchedPaths = [];
+	const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+	for await (const { flat: f, titleMatch, heading } of docs.search(query)) {
+		if (count === 0) process.stdout.write(bold(`Search results for "${query}":\n\n`));
+		count++;
+		matchedPaths.push(f.entry.path);
+		const raw = await docs.getContent(f);
+		const plainText = raw ? renderToText(raw) : "";
+		const snippets = plainText ? extractSnippets(plainText, terms) : [];
+		if (plain) {
+			const desc = f.entry.description ? ` — ${f.entry.description}` : "";
+			const badge = titleMatch && snippets.length > 0 ? " (title + content)" : titleMatch ? " (title)" : heading ? ` (heading: ${heading})` : ` (${snippets.length} match${snippets.length !== 1 ? "es" : ""})`;
+			process.stdout.write(`- **${f.entry.title}** \`${f.entry.path}\`${desc}${badge}\n`);
+			for (const s of snippets) process.stdout.write(`  > ${s}\n`);
+		} else {
+			const subtitle = heading ? ` › ${cyan(heading)}` : "";
+			process.stdout.write(`${bold(cyan(f.entry.title))}${subtitle} ${dim(f.entry.path)}\n`);
+			for (const s of snippets) process.stdout.write(`  ${highlight(s, query)}\n`);
+		}
+	}
+	if (count === 0) {
+		console.log(`No results for "${query}".`);
+		const suggestions = docs.suggest(query);
+		if (suggestions.length > 0) {
+			console.log("");
+			console.log(plain ? "Related pages:" : bold("Related pages:"));
+			for (const s of suggestions) if (plain) console.log(`  - [${s.entry.title}](${s.entry.path})`);
+			else console.log(`  ${bold(cyan(s.entry.title))} ${dim(s.entry.path)}`);
+			if (isAgent) {
+				console.log("");
+				console.log("To read a specific page, run this command again with the page path as second argument.");
+			}
+		}
+	} else if (isAgent) process.stdout.write([
+		"",
+		"---",
+		"",
+		`Found ${count} page${count > 1 ? "s" : ""} matching "${query}".`,
+		"To read a specific page, run this command again with the page path as second argument, for example:",
+		...[...new Set(matchedPaths)].slice(0, 3).map((p) => `  mdzilla <source> ${p}`),
+		""
+	].join("\n"));
+}
+async function tocMode(docs) {
 	const navigable = docs.pages;
 	if (navigable.length === 0) {
 		console.log("No pages found.");
 		return;
 	}
-	if (isAgent && pagePath) {
-		const normalized = pagePath.startsWith("/") ? pagePath : "/" + pagePath;
-		const resolved = await docs.resolvePage(normalized);
-		if (resolved.raw) process.stdout.write(renderToText(resolved.raw) + "\n");
-		else process.stdout.write(`Page not found: ${pagePath}\n`);
-		process.stdout.write(agentTrailer(docs, normalized));
-		return;
-	}
 	const tocLines = ["Table of Contents", ""];
 	for (const f of navigable) {
 		const indent = "  ".repeat(f.depth);
 		tocLines.push(`${indent}- [${f.entry.title}](${f.entry.path})`);
 	}
 	process.stdout.write(tocLines.join("\n") + "\n");
-	if (pagePath) {
-		const resolved = await docs.resolvePage(pagePath);
-		if (resolved.raw) process.stdout.write(renderToText(resolved.raw) + "\n\n");
-	} else {
-		const raw = await docs.getContent(navigable[0]);
-		if (raw) process.stdout.write(renderToText(raw) + "\n\n");
-	}
-	if (isAgent && navigable.length > 1) process.stdout.write("\n---\n\nTo read a specific page from the table of contents above, run this command again with `--page <path>`.\n");
+	const raw = await docs.getContent(navigable[0]);
+	if (raw) process.stdout.write("\n" + renderToText(raw) + "\n");
+	if (isAgent && navigable.length > 1) process.stdout.write("\n---\n\nTo read a specific page, run this command again with the page path as second argument.\nTo search within pages, pass a search query as second argument.\n");
+}
+async function serverMode(source, _docs) {
+	const { serve } = await import("srvx");
+	const { createDocsServer } = await import("../_chunks/server.mjs");
+	const server = serve({
+		fetch: (await createDocsServer({ source })).fetch,
+		gracefulShutdown: false
+	});
+	await server.ready();
+	await server.fetch(new Request(new URL("/api/meta", server.url)));
+	openInBrowser(server.url);
 }
 function agentTrailer(docs, currentPath) {
 	const pages = docs.pages;
@@ -322,446 +301,19 @@ function agentTrailer(docs, currentPath) {
 		"Other available pages:",
 		...otherPages.map((p) => `  - [${p.entry.title}](${p.entry.path})`),
 		"",
-		"To read a specific page, run this command again with `--page <path>`.",
-		"To view the full table of contents, run this command without `--page`.",
+		"To read a specific page, run this command again with the page path as second argument.",
+		"To search within pages, pass a search query as second argument.",
 		""
 	].join("\n");
 }
-//#endregion
-//#region src/cli/_utils.ts
-function openInBrowser(url) {
-	const parsed = new URL(url);
-	if (parsed.hostname === "[::]" || parsed.hostname === "[::1]" || parsed.hostname === "127.0.0.1") parsed.hostname = "localhost";
-	url = parsed.href;
-	if (process.platform === "win32") exec(`start "" ${JSON.stringify(url)}`, () => {});
-	else execFile(process.platform === "darwin" ? "open" : "xdg-open", [url], () => {});
-}
-//#endregion
-//#region src/cli/interactive/nav.ts
-function calcNavWidth(flat) {
-	const cols = process.stdout.columns || 80;
-	let max = 6;
-	for (const { entry, depth } of flat) {
-		const w = depth === 0 ? 3 + entry.title.length : 2 + 2 * depth + entry.title.length;
-		if (w > max) max = w;
-	}
-	return Math.min(max + 2, Math.floor(cols * .2), 56);
-}
-function renderNavPanel(flat, cursor, maxRows, width, search, searchMatches) {
-	const lines = [];
-	lines.push(search !== void 0 ? bold(" mdzilla") + "  " + dim("/") + search + "▌" : bold(" mdzilla"));
-	lines.push("");
-	const listRows = maxRows - 2;
-	let start = 0;
-	if (flat.length > listRows) start = Math.max(0, Math.min(cursor - Math.floor(listRows / 2), flat.length - listRows));
-	const end = Math.min(start + listRows, flat.length);
-	const treePrefixes = computeTreePrefixes(flat, computeIsLastChild(flat));
-	for (let i = start; i < end; i++) {
-		const { entry, depth } = flat[i];
-		const isPage = entry.page !== false;
-		const active = i === cursor;
-		const maxTitle = width - (depth === 0 ? 3 : 2 + 2 * depth) - 1;
-		let displayTitle = entry.title;
-		if (displayTitle.length > maxTitle && maxTitle > 1) displayTitle = displayTitle.slice(0, maxTitle - 1) + "…";
-		const isMatch = searchMatches ? searchMatches.has(i) : false;
-		const title = search ? highlight(displayTitle, search) : displayTitle;
-		let label;
-		if (depth === 0) label = `${isPage ? dim("◆") : dim("◇")} ${search ? isMatch ? title : dim(displayTitle) : active || isPage ? title : dim(title)}`;
-		else label = ` ${dim(treePrefixes[i])}${search ? isMatch ? title : dim(displayTitle) : active || isPage ? title : dim(title)}`;
-		lines.push(active ? bgGray(padTo(label, width)) : label);
-	}
-	if (flat.length > listRows) lines.push(dim(` ${start > 0 ? "↑" : " "} ${end < flat.length ? "↓" : " "} ${cursor + 1}/${flat.length}`));
-	return lines;
-}
-function computeIsLastChild(flat) {
-	const result = Array.from({ length: flat.length });
-	for (let i = 0; i < flat.length; i++) {
-		const d = flat[i].depth;
-		let last = true;
-		for (let j = i + 1; j < flat.length; j++) {
-			if (flat[j].depth < d) break;
-			if (flat[j].depth === d) {
-				last = false;
-				break;
-			}
-		}
-		result[i] = last;
-	}
-	return result;
-}
-function computeTreePrefixes(flat, isLast) {
-	const prefixes = Array.from({ length: flat.length });
-	const continues = [];
-	for (let i = 0; i < flat.length; i++) {
-		const d = flat[i].depth;
-		if (d === 0) {
-			prefixes[i] = "";
-			continues.length = 1;
-			continues[0] = !isLast[i];
-			continue;
-		}
-		let prefix = "";
-		for (let level = 1; level < d; level++) prefix += continues[level] ? "│ " : "  ";
-		prefix += isLast[i] ? "╰─" : "├─";
-		prefixes[i] = prefix;
-		continues[d] = !isLast[i];
-		continues.length = d + 1;
-	}
-	return prefixes;
-}
-//#endregion
-//#region src/cli/interactive/render.ts
-function renderSplit(flat, cursor, contentLines, contentScroll, search, focus, contentSearch, searchMatches, sidebarVisible = true) {
-	const rows = process.stdout.rows || 24;
-	const navWidth = sidebarVisible ? calcNavWidth(flat) : 0;
-	const bodyRows = rows - 1;
-	const navLines = sidebarVisible ? renderNavPanel(flat, cursor, bodyRows, navWidth, search, searchMatches) : [];
-	const rawRight = contentLines.slice(contentScroll, contentScroll + bodyRows);
-	const rightLines = contentSearch ? rawRight.map((l) => highlightAnsi(l, contentSearch)) : rawRight;
-	const cols = process.stdout.columns || 80;
-	const contentWidth = sidebarVisible ? cols - navWidth - 3 : cols - 2;
-	const isFocusContent = focus === "content" || focus === "content-search";
-	const reset = "\x1B[0m";
-	const output = [];
-	for (let i = 0; i < bodyRows; i++) {
-		const right = rightLines[i] || "";
-		if (sidebarVisible) output.push(reset + padTo(navLines[i] || "", navWidth) + reset + (isFocusContent ? cyan("│") : dim("│")) + reset + " " + truncateTo(right, contentWidth) + reset);
-		else output.push(reset + " " + truncateTo(right, contentWidth) + reset);
-	}
-	output.push(search !== void 0 ? dim("  esc") + " cancel  " + dim("enter") + " go" : focus === "content-search" ? dim("  /") + contentSearch + "▌  " + dim("esc") + " cancel  " + dim("enter") + " confirm" : focus === "content" ? dim("  ↑↓") + " scroll  " + dim("tab") + " links  " + dim("⏎") + " open  " + dim("/") + " search" + (contentSearch ? "  " + dim("n") + "/" + dim("N") + " next/prev" : "") + "  " + dim("t") + " sidebar  " + dim("⌫") + " back  " + dim("q") + " quit" : dim("  ↑↓") + " navigate  " + dim("⏎") + " read  " + dim("space") + " page ↓  " + dim("/") + " search  " + dim("t") + " sidebar  " + dim("q") + " quit");
-	const eol = "\x1B[K";
-	return output.map((l) => l + eol).join("\n");
-}
-//#endregion
-//#region src/cli/interactive/index.ts
-async function interactiveMode(docs) {
-	const flat = docs.flat;
-	if (flat.length === 0) {
-		console.log("No pages found.");
-		process.exit(0);
-	}
-	const isNavigable = (list, i) => list[i]?.entry.page !== false;
-	const nextNavigable = (list, from, dir) => {
-		let i = from + dir;
-		while (i >= 0 && i < list.length) {
-			if (isNavigable(list, i)) return i;
-			i += dir;
-		}
-		return from;
-	};
-	const firstNavigable = (list) => {
-		for (let i = 0; i < list.length; i++) if (isNavigable(list, i)) return i;
-		return 0;
-	};
-	let cursor = firstNavigable(flat);
-	let searching = false;
-	let searchQuery = "";
-	let searchMatches = [];
-	let contentScroll = 0;
-	let contentLines = [];
-	let loadedPath = "";
-	let focusContent = false;
-	let contentSearching = false;
-	let contentSearchQuery = "";
-	let contentMatches = [];
-	let contentMatchIdx = 0;
-	let sidebarVisible = true;
-	let contentLinks = [];
-	let linkIdx = -1;
-	const extractLinks = (lines) => {
-		const links = [];
-		const re = /\x1B\]8;;([^\x07\x1B]+?)(?:\x07|\x1B\\)/g;
-		for (let i = 0; i < lines.length; i++) {
-			re.lastIndex = 0;
-			let m;
-			let occ = 0;
-			while ((m = re.exec(lines[i])) !== null) links.push({
-				line: i,
-				url: m[1],
-				occurrence: occ++
-			});
-		}
-		return links;
-	};
-	const highlightLinkOnLine = (line, occurrence) => {
-		const oscRe = /\x1B\]8;;([^\x07\x1B]*?)(?:\x07|\x1B\\)/g;
-		let occ = 0;
-		let m;
-		while ((m = oscRe.exec(line)) !== null) {
-			if (!m[1]) continue;
-			if (occ === occurrence) {
-				const openerEnd = m.index + m[0].length;
-				const closer = oscRe.exec(line);
-				if (!closer) break;
-				return line.slice(0, openerEnd) + "\x1B[7m" + line.slice(openerEnd, closer.index) + "\x1B[27m" + line.slice(closer.index);
-			}
-			occ++;
-		}
-		return line;
-	};
-	const findContentMatches = (query) => {
-		if (!query) return [];
-		const lower = query.toLowerCase();
-		const matches = [];
-		for (let i = 0; i < contentLines.length; i++) if (stripAnsi(contentLines[i]).toLowerCase().includes(lower)) matches.push(i);
-		return matches;
-	};
-	const scrollToMatch = () => {
-		if (contentMatches.length === 0) return;
-		const rows = process.stdout.rows || 24;
-		const line = contentMatches[contentMatchIdx];
-		contentScroll = Math.max(0, Math.min(line - Math.floor(rows / 2), contentLines.length - rows + 2));
-	};
-	process.stdin.setRawMode(true);
-	process.stdin.resume();
-	enterAltScreen();
-	hideCursor();
-	const draw = () => {
-		let displayLines = contentLines;
-		if (linkIdx >= 0 && linkIdx < contentLinks.length) {
-			const link = contentLinks[linkIdx];
-			displayLines = [...contentLines];
-			displayLines[link.line] = highlightLinkOnLine(displayLines[link.line], link.occurrence);
-		}
-		const frame = renderSplit(flat, cursor, displayLines, contentScroll, searching ? searchQuery : void 0, contentSearching ? "content-search" : focusContent ? "content" : "nav", contentSearching ? contentSearchQuery : contentSearchQuery || void 0, searching ? new Set(searchMatches) : void 0, sidebarVisible);
-		process.stdout.write(`\x1B[H${frame}`);
-	};
-	const loadContent = (entry) => {
-		if (!entry?.filePath || entry.entry.page === false) {
-			if (loadedPath !== "") {
-				contentLines = [];
-				contentScroll = 0;
-				loadedPath = "";
-				draw();
-			}
-			return;
-		}
-		if (entry.filePath === loadedPath) return;
-		const targetPath = entry.filePath;
-		docs.getContent(entry).then(async (raw) => {
-			if (!raw || flat[cursor]?.filePath !== targetPath) return;
-			contentLines = await renderContent(raw, entry.entry, sidebarVisible ? calcNavWidth(flat) : 0);
-			contentScroll = 0;
-			contentSearchQuery = "";
-			contentMatches = [];
-			contentLinks = extractLinks(contentLines);
-			linkIdx = -1;
-			loadedPath = targetPath;
-			draw();
-		});
-	};
-	let cleaned = false;
-	const cleanup = (code = 0) => {
-		if (cleaned) return;
-		cleaned = true;
-		showCursor();
-		leaveAltScreen();
-		process.exit(code);
-	};
-	const reloadContent = () => {
-		const entry = flat[cursor];
-		if (!entry?.filePath || entry.entry.page === false) return;
-		docs.invalidate(entry.filePath);
-		loadedPath = "";
-		loadContent(entry);
-	};
-	process.on("SIGINT", () => cleanup());
-	process.on("SIGTERM", () => cleanup());
-	process.on("uncaughtException", (err) => {
-		if (cleaned) return;
-		cleaned = true;
-		showCursor();
-		leaveAltScreen();
-		console.error(err);
-		process.exit(1);
-	});
-	process.on("unhandledRejection", (err) => {
-		if (cleaned) return;
-		cleaned = true;
-		showCursor();
-		leaveAltScreen();
-		console.error(err);
-		process.exit(1);
-	});
-	process.stdout.on("resize", () => {
-		reloadContent();
-		draw();
-	});
-	clear();
-	draw();
-	loadContent(flat[cursor]);
-	process.stdin.on("data", (data) => {
-		const key = data.toString();
-		if (key === "") return cleanup();
-		if (searching) handleSearch(key);
-		else if (contentSearching) handleContentSearch(key);
-		else if (focusContent) handleContent(key);
-		else handleNav(key);
-		draw();
-	});
-	function handleNav(key) {
-		const rows = process.stdout.rows || 24;
-		const maxScroll = Math.max(0, contentLines.length - rows + 2);
-		if (key === "q") return cleanup();
-		if (key === "/") {
-			searching = true;
-			searchQuery = "";
-			searchMatches = [];
-			showCursor();
-		} else if (key === "\x1B[A" || key === "k") {
-			cursor = nextNavigable(flat, cursor, -1);
-			loadContent(flat[cursor]);
-		} else if (key === "\x1B[B" || key === "j") {
-			cursor = nextNavigable(flat, cursor, 1);
-			loadContent(flat[cursor]);
-		} else if (key === "\r" || key === "\n" || key === "	" || key === "\x1B[C") {
-			if (contentLines.length > 0) focusContent = true;
-		} else if (key === " " || key === "\x1B[6~") contentScroll = Math.min(maxScroll, contentScroll + rows - 2);
-		else if (key === "b" || key === "\x1B[5~") contentScroll = Math.max(0, contentScroll - rows + 2);
-		else if (key === "g") {
-			cursor = firstNavigable(flat);
-			loadContent(flat[cursor]);
-		} else if (key === "G") {
-			for (let i = flat.length - 1; i >= 0; i--) if (isNavigable(flat, i)) {
-				cursor = i;
-				break;
-			}
-			loadContent(flat[cursor]);
-		} else if (key === "t") {
-			sidebarVisible = !sidebarVisible;
-			reloadContent();
-		}
-	}
-	const scrollToLink = () => {
-		if (linkIdx < 0 || linkIdx >= contentLinks.length) return;
-		const rows = process.stdout.rows || 24;
-		const line = contentLinks[linkIdx].line;
-		if (line < contentScroll || line >= contentScroll + rows - 2) contentScroll = Math.max(0, Math.min(line - Math.floor(rows / 3), contentLines.length - rows + 2));
-	};
-	const activateLink = (url) => {
-		if (url.startsWith("http://") || url.startsWith("https://")) openInBrowser(url);
-		else {
-			const target = url.replace(/^\.\//, "/").replace(/\/$/, "");
-			const idx = flat.indexOf(docs.findByPath(target));
-			if (idx >= 0) {
-				cursor = idx;
-				focusContent = false;
-				linkIdx = -1;
-				loadContent(flat[cursor]);
-			}
-		}
-	};
-	function handleContent(key) {
-		const rows = process.stdout.rows || 24;
-		const maxScroll = Math.max(0, contentLines.length - rows + 2);
-		if (key === "" || key === "\b" || key === "\x1B[D" || key === "\x1B") {
-			focusContent = false;
-			linkIdx = -1;
-			contentSearchQuery = "";
-			contentMatches = [];
-		} else if (key === "	") {
-			if (contentLinks.length > 0) {
-				linkIdx = linkIdx < contentLinks.length - 1 ? linkIdx + 1 : 0;
-				scrollToLink();
-			}
-		} else if (key === "\x1B[Z") {
-			if (contentLinks.length > 0) {
-				linkIdx = linkIdx > 0 ? linkIdx - 1 : contentLinks.length - 1;
-				scrollToLink();
-			}
-		} else if ((key === "\r" || key === "\n") && linkIdx >= 0 && linkIdx < contentLinks.length) activateLink(contentLinks[linkIdx].url);
-		else if (key === "\x1B[A" || key === "k") contentScroll = Math.max(0, contentScroll - 1);
-		else if (key === "\x1B[B" || key === "j") contentScroll = Math.min(maxScroll, contentScroll + 1);
-		else if (key === " " || key === "\x1B[6~") contentScroll = Math.min(maxScroll, contentScroll + rows - 2);
-		else if (key === "b" || key === "\x1B[5~") contentScroll = Math.max(0, contentScroll - rows + 2);
-		else if (key === "/") {
-			contentSearching = true;
-			contentSearchQuery = "";
-			contentMatches = [];
-			contentMatchIdx = 0;
-			showCursor();
-		} else if (key === "n" && contentMatches.length > 0) {
-			contentMatchIdx = (contentMatchIdx + 1) % contentMatches.length;
-			scrollToMatch();
-		} else if (key === "N" && contentMatches.length > 0) {
-			contentMatchIdx = (contentMatchIdx - 1 + contentMatches.length) % contentMatches.length;
-			scrollToMatch();
-		} else if (key === "g") contentScroll = 0;
-		else if (key === "G") contentScroll = maxScroll;
-		else if (key === "t") {
-			sidebarVisible = !sidebarVisible;
-			reloadContent();
-		} else if (key === "q") return cleanup();
-	}
-	function handleContentSearch(key) {
-		if (key === "\x1B") {
-			contentSearching = false;
-			contentSearchQuery = "";
-			contentMatches = [];
-			hideCursor();
-		} else if (key === "\r" || key === "\n") {
-			contentSearching = false;
-			hideCursor();
-		} else if (key === "" || key === "\b") {
-			contentSearchQuery = contentSearchQuery.slice(0, -1);
-			contentMatches = findContentMatches(contentSearchQuery);
-			contentMatchIdx = 0;
-			scrollToMatch();
-		} else if (key === "\x1B[A") {
-			if (contentMatches.length > 0) {
-				contentMatchIdx = (contentMatchIdx - 1 + contentMatches.length) % contentMatches.length;
-				scrollToMatch();
-			}
-		} else if (key === "\x1B[B") {
-			if (contentMatches.length > 0) {
-				contentMatchIdx = (contentMatchIdx + 1) % contentMatches.length;
-				scrollToMatch();
-			}
-		} else if (key.length === 1 && key >= " ") {
-			contentSearchQuery += key;
-			contentMatches = findContentMatches(contentSearchQuery);
-			contentMatchIdx = 0;
-			scrollToMatch();
-		}
-	}
-	function updateSearchMatches() {
-		searchMatches = docs.matchIndices(searchQuery);
-		if (searchMatches.length > 0) cursor = searchMatches[0];
-		else if (!searchQuery) cursor = firstNavigable(flat);
-		loadContent(flat[cursor]);
-	}
-	function nextSearchMatch(dir) {
-		if (searchMatches.length === 0) return;
-		const curIdx = searchMatches.indexOf(cursor);
-		if (curIdx < 0) cursor = searchMatches[0];
-		else {
-			const next = curIdx + dir;
-			cursor = searchMatches[(next + searchMatches.length) % searchMatches.length];
-		}
-		loadContent(flat[cursor]);
-	}
-	function handleSearch(key) {
-		if (key === "\x1B" || key === "\x1B[D") {
-			searching = false;
-			searchMatches = [];
-			cursor = firstNavigable(flat);
-			hideCursor();
-			loadContent(flat[cursor]);
-		} else if (key === "\r" || key === "\n") {
-			searching = false;
-			searchMatches = [];
-			hideCursor();
-			loadContent(flat[cursor]);
-		} else if (key === "" || key === "\b") {
-			searchQuery = searchQuery.slice(0, -1);
-			updateSearchMatches();
-		} else if (key === "\x1B[A") nextSearchMatch(-1);
-		else if (key === "\x1B[B") nextSearchMatch(1);
-		else if (key.length === 1 && key >= " ") {
-			searchQuery += key;
-			updateSearchMatches();
-		}
+function printNotFound(docs, pagePath) {
+	process.stderr.write(`Page not found: ${pagePath}\n`);
+	const suggestions = docs.suggest(pagePath);
+	if (suggestions.length > 0) {
+		process.stderr.write("\nDid you mean:\n");
+		for (const s of suggestions) process.stderr.write(`  - ${s.entry.title} (${s.entry.path})\n`);
 	}
+	process.stderr.write("\nTo search within pages, pass a search query as second argument.\n");
 }
 //#endregion
 //#region src/cli/main.ts
@@ -772,62 +324,55 @@ async function main() {
 	});
 	const { values, positionals } = parseArgs({
 		args: process.argv.slice(2),
+		allowPositionals: true,
 		options: {
 			help: {
 				type: "boolean",
 				short: "h"
 			},
 			export: { type: "string" },
-			page: {
-				type: "string",
-				short: "p"
-			},
 			plain: {
 				type: "boolean",
 				default: isAgent || !process.stdout.isTTY
-			},
-			headless: { type: "boolean" },
-			tui: { type: "boolean" }
-		},
-		allowPositionals: true
+			}
+		}
 	});
-	const exportDir = values.export;
-	const docsDir = positionals[0];
-	const plain = values.plain || values.headless || docsDir?.startsWith("npm:") || false;
-	if (values.help || !docsDir) return printUsage(!!docsDir);
-	const isURL = docsDir.startsWith("http://") || docsDir.startsWith("https://");
-	if (docsDir.endsWith(".md")) return singleFileMode(docsDir, plain, isURL);
-	const source = isURL ? new DocsSourceHTTP(docsDir) : docsDir.startsWith("gh:") ? new DocsSourceGit(docsDir) : docsDir.startsWith("npm:") ? new DocsSourceNpm(docsDir) : new DocsSourceFS(docsDir);
-	const docs = new DocsManager(source);
+	const input = positionals[0];
+	const query = positionals[1];
+	const plain = values.plain || input?.startsWith("npm:") || false;
+	if (values.help || !input) return printUsage(!!input);
+	const isURL = input.startsWith("http://") || input.startsWith("https://");
+	if (input.endsWith(".md")) return singleFileMode(input, plain, isURL);
+	const source = resolveSource(input);
+	const docs = new Collection(source);
 	await docs.load();
-	if (exportDir) {
-		await exportDocsToFS(docs, exportDir, { plainText: plain });
-		console.log(`Exported ${docs.pages.length} pages to ${exportDir}`);
+	if (values.export) {
+		await writeCollection(docs, values.export, { plainText: plain });
+		console.log(`Exported ${docs.pages.length} pages to ${values.export}`);
 		return;
 	}
-	let pagePath = values.page;
-	if (!pagePath && isURL) {
-		const urlPath = new URL(docsDir).pathname.replace(/\/+$/, "");
-		if (urlPath && urlPath !== "/") pagePath = urlPath;
+	let resolvedQuery = query;
+	if (!resolvedQuery && isURL) {
+		const urlPath = new URL(input).pathname.replace(/\/+$/, "");
+		if (urlPath && urlPath !== "/") resolvedQuery = urlPath;
 	}
-	if (pagePath && !plain) return pageMode(docs, pagePath, plain);
-	if (plain) return plainMode(docs, pagePath);
-	if (values.tui) interactiveMode(docs);
-	else {
-		const { serve } = await import("srvx");
-		const { createDocsServer } = await import("../_chunks/server.mjs");
-		const server = serve({
-			fetch: (await createDocsServer({ source })).fetch,
-			gracefulShutdown: false
-		});
-		await server.ready();
-		await server.fetch(new Request(new URL("/api/meta", server.url)));
-		openInBrowser(server.url);
+	if (resolvedQuery) return smartResolve(docs, resolvedQuery, plain);
+	if (plain) return tocMode(docs);
+	return serverMode(source, docs);
+}
+async function smartResolve(docs, query, plain) {
+	const normalized = query.startsWith("/") ? query : "/" + query;
+	const resolved = await docs.resolvePage(normalized);
+	if (resolved.raw) return renderPage(docs, resolved, normalized, plain);
+	const fuzzy = docs.filter(query);
+	if (fuzzy.length === 1 && fuzzy[0].entry.page !== false) {
+		const match = fuzzy[0];
+		const page = await docs.resolvePage(match.entry.path);
+		if (page.raw) return renderPage(docs, page, match.entry.path, plain);
 	}
+	return searchMode(docs, query, plain);
 }
 main().catch((err) => {
-	showCursor();
-	leaveAltScreen();
 	console.error(err);
 	process.exit(1);
 });