@suzumiyaaoba/mdxr 0.12.0 → 0.14.0

package/README.md

@@ -10,6 +10,7 @@ Run directly with `npx` — no install required:
 npx @suzumiyaaoba/mdxr render plan.mdx     # writes plan.html
 npx @suzumiyaaoba/mdxr serve plan.mdx      # live preview at http://localhost:3737
 npx @suzumiyaaoba/mdxr catalog             # list available components
+npx @suzumiyaaoba/mdxr --version           # print the package version
 npx @suzumiyaaoba/mdxr init                # install mdxr instructions for Codex and Claude
 ```
 
@@ -76,6 +77,8 @@ mdxr init --skill                      # install the Agent Skill instead
 
 The global install creates `$CODEX_HOME/MDXR.md` (or `~/.codex/MDXR.md` when `CODEX_HOME` is unset) and its `mdxr/references/`, plus matching files under `~/.claude/`. It adds a read instruction to `$CODEX_HOME/AGENTS.md`; Claude's `~/.claude/CLAUDE.md` imports `@./MDXR.md`. Use `--local` to create `.codex/MDXR.md` and `.claude/MDXR.md` in the project, with references from the root `AGENTS.md` and `CLAUDE.md`. A local install also adds `.mdxr/` to `.gitignore` for agent-authored documents and rendered HTML. `--force` refreshes generated instruction files and references while preserving the rest of your config files.
 
+The bundled prompts tell the agent to compare their recorded version with `--version` from the CLI used for the task. If they differ, the agent reports both versions and recommends refreshing with `init --force` from that same CLI, preserving the original tool and install scope; Skill installs also keep `--skill`. See [Agent setup](docs/docs/agent-skill.mdx) for details.
+
 ## Wireframes
 
 Build screen mockups with the built-in `Wireframe*` components, adapted from [wireframe-ui](https://wireframe-ui.vercel.app/components). All 45 upstream UI families and nine blocks are included, with their compound parts and wireframe helpers. No imports or extra installation are needed in MDX:
@@ -107,7 +110,7 @@ Once the instructions or skill are installed, ask your agent, for example:
 
 > Write an implementation plan for the auth feature and render it to HTML with mdxr.
 
-Plans, reports, reviews, investigation summaries, release notes, and postmortems all work. By default, new documents use `.mdxr/yyyyMMddhhmmss-<name>.mdx`, with a zero-padded 14-digit local creation time in 24-hour format (for example, `.mdxr/20260929140530-auth-plan.mdx`). A filename or file path you provide takes priority. If you specify only a directory, the document gets a timestamped filename there.
+Plans, reports, reviews, investigation summaries, release notes, and postmortems all work. By default, new documents use `.mdxr/yyyyMMddhhmmss-<name>/index.mdx`, with a zero-padded 14-digit local creation time in 24-hour format (for example, `.mdxr/20260929140530-auth-plan/index.mdx`). Keep images and related MDX files in the document's directory. A file path you provide takes priority, and existing documents keep their current paths. If you specify only a directory, create a timestamped subdirectory there and save the document as `index.mdx`. Preview it with `mdxr serve .mdxr/20260929140530-auth-plan/index.mdx`.
 
 ## License
 

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { Bv as fenceLang, Dh as RESEARCH_CLAIM_SCHEMA, Dv as numOf, Eh as PERFORMANCE_TARGET_SCHEMA, Ev as attrTrue, Fv as DocContext, Gv as langForPath, Ha as shadcnModules, Hv as splitPathLines, Jv as nonEmpty, Kv as isComponent, Lv as parseProps, Nm as PlanHeader, Oh as performanceDetails, Pv as takeUsedIcons, Th as PERFORMANCE_LABELS, Uv as SKIP_LANGS, Vv as parseLineRange, Xv as safeHref, Yv as own, Zg as calculate, Zv as urlScheme, __ as numberValue, b_ as records, bm as plotModel, dp as dependencyMatrixModel, e_ as REPORT_SPECS, fp as queryPlanModel, g_ as isDataRecord, gv as textList, h_ as display, hv as numList, iv as isStatus, j_ as parseDiff, kh as performanceResult, m_ as columnsOf, mp as flameModel, n_ as comparisonModel, nv as STATUSES, pp as diagramModel, qv as isRecord, r_ as schemaRows, t as builtinComponents, t_ as reportModel, up as bundleModel, v_ as parseJson, wh as CLAIM_LABELS, x_ as tableRecords, y_ as readRecords, ym as PLOT_NAMES, zv as fenceFilename } from "./ui-DkizsCxS.mjs";
-import { a as loadUserModule, c as srcDir, i as importBundledCode, n as loadConfig, o as resolveModuleEntry, r as SHARED_PACKAGES, s as pkgRoot } from "./config-BeI2zo52.mjs";
+import { Bv as fenceFilename, Dv as attrTrue, Fv as takeUsedIcons, Ha as shadcnModules, Hv as parseLineRange, Iv as DocContext, Jf as dependencyMatrixModel, Jv as isRecord, Kv as langForPath, M_ as parseDiff, Mh as parseSyntaxLines, Ov as numOf, Qg as calculate, Qv as urlScheme, Rv as parseProps, S_ as tableRecords, Uv as splitPathLines, Vv as fenceLang, Wv as SKIP_LANGS, Xf as diagramModel, Xv as own, Yf as queryPlanModel, Yv as nonEmpty, Zf as flameModel, Zv as safeHref, __ as isDataRecord, _v as textList, av as isStatus, b_ as readRecords, ch as PERFORMANCE_LABELS, dh as performanceDetails, fh as performanceResult, g_ as display, gm as PlanHeader, gv as numList, h_ as columnsOf, i_ as schemaRows, lh as PERFORMANCE_TARGET_SCHEMA, n_ as reportModel, nm as PLOT_NAMES, qf as bundleModel, qv as isComponent, r_ as comparisonModel, rm as plotModel, rv as STATUSES, sh as CLAIM_LABELS, t as builtinComponents, t_ as REPORT_SPECS, uh as RESEARCH_CLAIM_SCHEMA, v_ as numberValue, x_ as records, y_ as parseJson } from "./ui-DuJK74P7.mjs";
+import { a as loadUserModule, c as srcDir, i as importBundledCode, n as loadConfig, o as resolveModuleEntry, r as SHARED_PACKAGES, s as pkgRoot } from "./config-DssZ4uXC.mjs";
 import module from "node:module";
-import fsp, { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import fsp, { access, mkdir, open, readFile, readdir, realpath, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { cac } from "cac";
 import { directiveToMarkdown } from "mdast-util-directive";
@@ -20,7 +20,7 @@ import { unified } from "unified";
 import { VFile } from "vfile";
 import { matter } from "vfile-matter";
 import { visit } from "unist-util-visit";
-import fs, { existsSync, readFileSync, realpathSync } from "node:fs";
+import fs, { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { visitParents } from "unist-util-visit-parents";
 import * as valibot from "valibot";
 import { Fragment, createElement } from "react";
@@ -45,6 +45,9 @@ import { query } from "@anthropic-ai/claude-agent-sdk";
 import { connect } from "node:net";
 import { WebSocket } from "ws";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
+//#region package.json
+var version = "0.14.0";
+//#endregion
 //#region src/format-error.ts
 /**
 * Validate the `--format` flag: omitted and "text" mean human-readable
@@ -5582,7 +5585,7 @@ const CONVENTIONS = [
 		syntax: "```lang title=\"file.ts\""
 	},
 	{
-		result: "FileRef chip (editor link when the file exists)",
+		result: "FileRef chip (local preview in serve; editor link in static HTML)",
 		syntax: "`src/x.ts` inline code naming a real file"
 	},
 	{
@@ -6110,19 +6113,21 @@ const iconSvg = (name) => {
 * `handleDocEvent`); THEME_JS restores the stored choice before paint.
 */
 const THEME_TOGGLE_HTML = `<button type="button" class="mdxr-theme" data-mdxr-theme data-mode="auto" title="Theme: auto" aria-label="Switch theme (current: auto)"><span class="mdxr-theme-i mdxr-theme-i-auto">${iconSvg("sun-moon")}</span><span class="mdxr-theme-i mdxr-theme-i-light">${iconSvg("sun")}</span><span class="mdxr-theme-i mdxr-theme-i-dark">${iconSvg("moon")}</span></button>`;
-const htmlDocument = (o) => `<!doctype html>
+const htmlDocument = (o) => {
+	const annotations = o.documentControls === false ? void 0 : o.annotations;
+	return `<!doctype html>
 <html lang="en"${o.initialTheme === void 0 ? "" : ` class="${o.initialTheme}" style="color-scheme: ${o.initialTheme}"`}>
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="generator" content="mdxr">
 <title>${escapeHtml(o.title)}</title>
-<script>${inlineScript(THEME_JS)}<\/script>
+${o.documentControls === false ? "" : `<script>${inlineScript(THEME_JS)}<\/script>`}
 ${o.needsKatex === true ? `<link rel="stylesheet" href="${KATEX_CDN_URL}">` : ""}
-<style>${inlineStyle(o.css)}${o.annotations === void 0 ? "" : ANNOTATION_HIGHLIGHT_CSS}</style>
+<style>${inlineStyle(o.css)}${annotations === void 0 ? "" : ANNOTATION_HIGHLIGHT_CSS}</style>
 </head>
 <body class="bg-white text-neutral-900 antialiased dark:bg-neutral-950 dark:text-neutral-100">
-${THEME_TOGGLE_HTML}
+${o.documentControls === false ? "" : `${THEME_TOGGLE_HTML}
 <div class="mdxr-view-controls" role="group" aria-label="Document view" hidden>
 <button type="button" data-mdxr-view="document" aria-pressed="true">${iconSvg("file-text")}<span>Document</span></button>
 <button type="button" data-mdxr-view="pages" aria-pressed="false">${iconSvg("panel-left")}<span>Pages</span></button>
@@ -6131,16 +6136,16 @@ ${THEME_TOGGLE_HTML}
 <p class="mdxr-pages-title">${escapeHtml(o.title)}</p>
 <p data-section-review-summary role="status" hidden></p>
 <div data-mdxr-page-tabs role="tablist" aria-label="Sections" aria-orientation="vertical"></div>
-</aside>
+</aside>`}
 <div id="mdxr-content">
 <main id="mdxr-root" class="prose prose-neutral dark:prose-invert mx-auto max-w-3xl px-6 py-10">${o.body}</main>
-<nav class="mdxr-page-navigation" aria-label="Section navigation" hidden>
+${o.documentControls === false ? "" : `<nav class="mdxr-page-navigation" aria-label="Section navigation" hidden>
 <button type="button" data-mdxr-page-previous>${iconSvg("chevron-left")}<span class="mdxr-page-navigation-labels"><span>Previous</span><span data-mdxr-page-previous-title hidden></span></span></button>
 <button type="button" data-mdxr-page-next><span class="mdxr-page-navigation-labels"><span>Next</span><span data-mdxr-page-next-title hidden></span></span>${iconSvg("chevron-right")}</button>
-</nav>
+</nav>`}
 </div>
-${o.annotations === void 0 ? "" : `${annotationHtml(iconSvg)}<script type="application/json" id="mdxr-annotation-document">${JSON.stringify(o.annotations).replaceAll("<", "\\u003c")}<\/script>`}
-${o.annotations === void 0 ? "" : sectionReviewHtml(iconSvg)}
+${annotations === void 0 ? "" : `${annotationHtml(iconSvg)}<script type="application/json" id="mdxr-annotation-document">${JSON.stringify(annotations).replaceAll("<", "\\u003c")}<\/script>`}
+${annotations === void 0 ? "" : sectionReviewHtml(iconSvg)}
 ${o.linkedDocuments === void 0 || Object.keys(o.linkedDocuments).length === 0 ? "" : `<script type="application/json" id="mdxr-linked-documents">${JSON.stringify(o.linkedDocuments).replaceAll("<", "\\u003c")}<\/script>`}
 <script>${inlineScript(o.clientJs)}<\/script>
 ${o.needsMermaid ? `<script type="module">${inlineScript(MERMAID_JS)}<\/script>` : ""}
@@ -6149,6 +6154,7 @@ ${o.hydrateJs === void 0 ? "" : `<script>${inlineScript(o.hydrateJs)}<\/script>`
 </body>
 </html>
 `;
+};
 //#endregion
 //#region src/hydrate/export-index.ts
 /**
@@ -6617,6 +6623,8 @@ ${mountDocument}({
   components: { ${entries.join(", ")} },
   doc: __mdxrDoc,
   fileLinks: ${JSON.stringify(spec.fileLinks)},
+  filePreviews: ${JSON.stringify(spec.filePreviews)},
+  filePreviewEnabled: ${JSON.stringify(spec.filePreviewEnabled)},
   headerProps: ${JSON.stringify(spec.header)},
   now: ${JSON.stringify(spec.now)},
   planHeader: ${planHeader},
@@ -6808,47 +6816,6 @@ const rehypeLinkedAssets = (opts = {}) => (tree, file) => {
 	});
 };
 //#endregion
-//#region src/workspace-syntax.ts
-const ALLOWED_STYLE_PROPERTIES = [
-	"--shiki-light",
-	"--shiki-dark",
-	"--shiki-light-font-style",
-	"--shiki-dark-font-style",
-	"--shiki-light-font-weight",
-	"--shiki-dark-font-weight",
-	"--shiki-light-text-decoration",
-	"--shiki-dark-text-decoration"
-];
-const parseToken = (value) => {
-	if (!isRecord(value) || typeof value.text !== "string" || !isRecord(value.style) || Array.isArray(value.style)) return;
-	const style = {};
-	for (const property of ALLOWED_STYLE_PROPERTIES) {
-		if (!Object.hasOwn(value.style, property)) continue;
-		const propertyValue = value.style[property];
-		if (typeof propertyValue === "string") style[property] = propertyValue;
-	}
-	return {
-		style,
-		text: value.text
-	};
-};
-/** Validate and narrow syntax tokens received through a workspace API. */
-const parseSyntaxLines = (value) => {
-	if (!Array.isArray(value)) return;
-	const lines = [];
-	for (const lineValue of value) {
-		if (!Array.isArray(lineValue)) return;
-		const line = [];
-		for (const tokenValue of lineValue) {
-			const token = parseToken(tokenValue);
-			if (token === void 0) return;
-			line.push(token);
-		}
-		lines.push(line);
-	}
-	return lines;
-};
-//#endregion
 //#region src/rehype/shiki.ts
 /**
 * Fenced code blocks are syntax-highlighted with shiki at render time.
@@ -6993,16 +6960,17 @@ const plainSyntaxLines = (source) => source.split("\n").map((text) => [{
 	style: {},
 	text
 }]);
-/** Tokenize a complete MDX document for the workspace source and diff views. */
-const highlightMdxSource = async (source) => {
+const isBundledLanguage = (highlighter, lang) => Object.hasOwn(highlighter.getBundledLanguages(), lang);
+/** Tokenize source without interpreting Shiki's code-fence annotations. */
+const highlightSource = async (source, lang) => {
 	const normalizedSource = source.replaceAll("\r\n", "\n");
 	if (normalizedSource.includes("\r")) return plainSyntaxLines(normalizedSource);
-	const highlighter = await readyHighlighter("mdx");
-	if (highlighter === void 0) return plainSyntaxLines(normalizedSource);
+	const highlighter = await readyHighlighter(lang);
+	if (highlighter === void 0 || !isBundledLanguage(highlighter, lang)) return plainSyntaxLines(normalizedSource);
 	try {
 		const result = highlighter.codeToTokens(normalizedSource, {
 			defaultColor: false,
-			lang: "mdx",
+			lang,
 			themes: THEMES
 		});
 		return parseSyntaxLines(result.tokens.map((line) => line.map((token) => ({
@@ -7013,6 +6981,8 @@ const highlightMdxSource = async (source) => {
 		return plainSyntaxLines(normalizedSource);
 	}
 };
+/** Tokenize a complete MDX document for the workspace source and diff views. */
+const highlightMdxSource = async (source) => await highlightSource(source, "mdx");
 /**
 * One side of a hunk, highlighted as the file's own language: `ctx`/`add`
 * rows read from the new side, `ctx`/`del` rows from the old side. Shiki's
@@ -7371,6 +7341,14 @@ const extractUsedComponents = (code, components) => {
 	if (catalogKeys.has("wrapper")) used.add("wrapper");
 	return [...used];
 };
+const createFilePreview = (dir, resolver, filePreviews) => {
+	if (resolver === void 0) return;
+	return (relPath) => {
+		const url = resolver(path.resolve(dir, relPath));
+		if (url !== void 0) filePreviews.set(relPath, url);
+		return url;
+	};
+};
 const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {}) => {
 	const file = new VFile({
 		path: filePath,
@@ -7382,12 +7360,14 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 	const editor = typeof frontmatter.editor === "string" && frontmatter.editor !== "" ? frontmatter.editor : opts.editor;
 	const dir = file.dirname ?? ".";
 	const fileLinks = /* @__PURE__ */ new Map();
+	const filePreviews = /* @__PURE__ */ new Map();
 	const fileLink = (rel, line) => {
 		const abs = path.resolve(dir, rel);
 		const url = existsSync(abs) ? editorUrl(editor, abs, line) : void 0;
 		if (url !== void 0) fileLinks.set(`${rel}\0${line ?? ""}`, url);
 		return url;
 	};
+	const filePreview = createFilePreview(dir, opts.filePreview, filePreviews);
 	const compiled = await compile(file, {
 		baseUrl: import.meta.url,
 		format: "mdx",
@@ -7426,6 +7406,7 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 	const renderedAt = /* @__PURE__ */ new Date();
 	const context = {
 		fileLink,
+		filePreview,
 		now: renderedAt
 	};
 	const hydrated = (opts.hydrate ?? true) && used.length > 0;
@@ -7444,6 +7425,7 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 		context,
 		dependencies: [...new Set(includeDependencies)],
 		fileLinks: Object.fromEntries(fileLinks),
+		filePreviews: Object.fromEntries(filePreviews),
 		frontmatter,
 		hydrated,
 		linkedDocuments,
@@ -7452,6 +7434,7 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 				const html = renderDocument(header);
 				return {
 					fileLinks: Object.fromEntries(fileLinks),
+					filePreviews: Object.fromEntries(filePreviews),
 					html,
 					usedIcons: takeUsedIcons()
 				};
@@ -8082,6 +8065,8 @@ const buildHydrateBundle = async (args) => {
 			code: args.code,
 			componentsPath: args.config.componentsPath === void 0 ? void 0 : resolveModuleEntry(args.config.componentsPath),
 			fileLinks: args.fileLinks,
+			filePreviewEnabled: args.filePreviewEnabled,
+			filePreviews: args.filePreviews,
 			header: args.headerProps,
 			now: args.now,
 			usedComponents: args.usedComponents,
@@ -8131,8 +8116,9 @@ const renderDocument = async (source, opts, include = {}) => {
 		...builtinComponents,
 		...user.components
 	};
-	const { annotationSources, body, code, dependencies: includeDependencies, fileLinks, frontmatter, linkedDocuments, renderedAt, renderWithHeader, usedComponents, usedIcons } = await mdxToHtml(source, components, filePath, {
+	const { annotationSources, body, code, dependencies: includeDependencies, fileLinks, filePreviews, frontmatter, linkedDocuments, renderedAt, renderWithHeader, usedComponents, usedIcons } = await mdxToHtml(source, components, filePath, {
 		editor: config.editor,
+		filePreview: opts.filePreview,
 		hydrate: opts.hydrate,
 		include
 	});
@@ -8148,11 +8134,13 @@ const renderDocument = async (source, opts, include = {}) => {
 	const headerProps = frontmatterHeader(fmStr, body);
 	let docBody = body;
 	let docFileLinks = fileLinks;
+	let docFilePreviews = filePreviews;
 	let docIcons = usedIcons;
 	if (headerProps !== void 0) {
 		const pass = renderWithHeader(createElement(PlanHeader, headerProps));
 		docBody = pass.html;
 		docFileLinks = pass.fileLinks;
+		docFilePreviews = pass.filePreviews;
 		docIcons = pass.usedIcons;
 	}
 	const themeCss = config.themePath === void 0 ? void 0 : await readFile(config.themePath, "utf-8");
@@ -8185,6 +8173,8 @@ const renderDocument = async (source, opts, include = {}) => {
 		code,
 		config,
 		fileLinks: docFileLinks,
+		filePreviewEnabled: opts.filePreview !== void 0,
+		filePreviews: docFilePreviews,
 		headerProps,
 		hydrate: opts.hydrate,
 		now: renderedAt,
@@ -8225,6 +8215,7 @@ const renderDocument = async (source, opts, include = {}) => {
 		body: docBody,
 		clientJs: js,
 		css,
+		documentControls: opts.documentControls,
 		hydrateJs,
 		initialTheme: opts.initialTheme,
 		linkedDocuments: documents,
@@ -8235,7 +8226,7 @@ const renderDocument = async (source, opts, include = {}) => {
 	});
 };
 /** Render MDX source text to a standalone HTML document. */
-const render = async (source, opts = {}) => await renderDocument(source, opts);
+const render = async (source, opts = {}) => await renderDocument(source, opts, { inlineAssets: opts.inlineAssets });
 /** Read `mdxPath` and render it to a standalone HTML document. */
 const renderFile = async (mdxPath, opts = {}) => {
 	const abs = path.resolve(mdxPath);
@@ -8322,7 +8313,7 @@ const reply = (res, status, body, headers = {}) => {
 	});
 	res.end(JSON.stringify(body));
 };
-const sameOrigin$2 = (req) => {
+const sameOrigin$3 = (req) => {
 	const port = req.socket.localPort;
 	const host = req.headers.host ?? "";
 	return (host === `localhost:${port}` || host === `127.0.0.1:${port}`) && (req.headers.origin === void 0 || req.headers.origin === `http://${host}`);
@@ -8358,7 +8349,7 @@ const handleAgentRequest = async (req, res, agent, notify, beforeSend) => {
 			reply(res, 404, { error: "Agent chat is disabled" });
 			return;
 		}
-		if (!sameOrigin$2(req)) {
+		if (!sameOrigin$3(req)) {
 			reply(res, 403, { error: "Request origin is not allowed" });
 			return;
 		}
@@ -9567,7 +9558,7 @@ const parsePreviewTheme = (value) => {
 	if (value === null) return;
 	return value === "light" || value === "dark" ? value : null;
 };
-const replyJson$1 = (response, status, body, headers = {}) => {
+const replyJson$2 = (response, status, body, headers = {}) => {
 	response.writeHead(status, {
 		"cache-control": "no-store",
 		"content-type": "application/json; charset=utf-8",
@@ -9576,7 +9567,7 @@ const replyJson$1 = (response, status, body, headers = {}) => {
 	});
 	response.end(JSON.stringify(body));
 };
-const sameOrigin$1 = (request) => {
+const sameOrigin$2 = (request) => {
 	const port = request.socket.localPort;
 	const host = request.headers.host ?? "";
 	return (host === `localhost:${port}` || host === `127.0.0.1:${port}`) && (request.headers.origin === void 0 || request.headers.origin === `http://${host}`);
@@ -9591,7 +9582,7 @@ const replyDiff = async (response, history, from, to) => {
 		if (line.type !== "remove") afterSource.push(line.text);
 	}
 	const [before, after] = await Promise.all([highlightMdxSource(beforeSource.join("\n")), highlightMdxSource(afterSource.join("\n"))]);
-	replyJson$1(response, 200, {
+	replyJson$2(response, 200, {
 		from,
 		lines,
 		syntax: {
@@ -9604,7 +9595,7 @@ const replyDiff = async (response, history, from, to) => {
 const replyPreview = async (response, history, filePath, id, requestedTheme) => {
 	const theme = parsePreviewTheme(requestedTheme);
 	if (theme === null) {
-		replyJson$1(response, 400, { error: "Invalid preview theme" });
+		replyJson$2(response, 400, { error: "Invalid preview theme" });
 		return;
 	}
 	const source = await history.read(id);
@@ -9624,14 +9615,14 @@ const replyPreview = async (response, history, filePath, id, requestedTheme) =>
 const replyHistoryView = async (response, history, filePath, params) => {
 	const view = params.get("view");
 	if (view === null) {
-		replyJson$1(response, 200, await history.list());
+		replyJson$2(response, 200, await history.list());
 		return;
 	}
 	const id = params.get("id");
 	if (view === "source" && id !== null) {
 		const source = await history.read(id);
 		const syntax = await highlightMdxSource(source);
-		replyJson$1(response, 200, {
+		replyJson$2(response, 200, {
 			id,
 			source,
 			syntax
@@ -9650,20 +9641,20 @@ const replyHistoryView = async (response, history, filePath, params) => {
 		await replyPreview(response, history, filePath, id, params.get("theme"));
 		return;
 	}
-	replyJson$1(response, 400, { error: "Invalid history view or version" });
+	replyJson$2(response, 400, { error: "Invalid history view or version" });
 };
 /** Read-only endpoints for the local, token-free MDX version store. */
 const handleDocumentHistoryRequest = async (request, response, history, filePath) => {
 	if (history === void 0 || filePath === void 0) {
-		replyJson$1(response, 404, { error: "Document history is unavailable" });
+		replyJson$2(response, 404, { error: "Document history is unavailable" });
 		return;
 	}
-	if (!sameOrigin$1(request)) {
-		replyJson$1(response, 403, { error: "Request origin is not allowed" });
+	if (!sameOrigin$2(request)) {
+		replyJson$2(response, 403, { error: "Request origin is not allowed" });
 		return;
 	}
 	if (request.method !== "GET") {
-		replyJson$1(response, 405, { error: "Method not allowed" }, { allow: "GET" });
+		replyJson$2(response, 405, { error: "Method not allowed" }, { allow: "GET" });
 		return;
 	}
 	const url = new URL(request.url ?? "", "http://localhost");
@@ -9672,10 +9663,157 @@ const handleDocumentHistoryRequest = async (request, response, history, filePath
 	} catch (error) {
 		const detail = formatError(error);
 		const missingVersion = error instanceof DocumentHistoryError && (error.kind === "invalid-version" || error.kind === "unknown-version");
-		replyJson$1(response, missingVersion ? 404 : 500, { error: detail });
+		replyJson$2(response, missingVersion ? 404 : 500, { error: detail });
 	}
 };
 //#endregion
+//#region src/file-preview-http.ts
+const MAX_TEXT_BYTES = 2097152;
+const MAX_IMAGE_BYTES = 33554432;
+const MARKDOWN_EXTENSIONS = /* @__PURE__ */ new Set([
+	".md",
+	".markdown",
+	".mdx",
+	".mdown"
+]);
+var FilePreviewError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.name = "FilePreviewError";
+		this.status = status;
+	}
+};
+const replyJson$1 = (response, status, body) => {
+	response.writeHead(status, {
+		"cache-control": "no-store",
+		"content-type": "application/json; charset=utf-8",
+		"x-content-type-options": "nosniff",
+		...status === 405 ? { allow: "GET" } : {}
+	});
+	response.end(JSON.stringify(body));
+};
+const sameOrigin$1 = (request) => {
+	const port = request.socket.localPort;
+	const host = request.headers.host ?? "";
+	return (host === `localhost:${port}` || host === `127.0.0.1:${port}`) && (request.headers.origin === void 0 || request.headers.origin === `http://${host}`) && request.headers["sec-fetch-site"] !== "cross-site";
+};
+const readPreviewFile = async (file, limit) => {
+	if (await realpath(file.path) !== file.canonical) throw new FilePreviewError(403, "The referenced file has changed location");
+	const handle = await open(file.canonical, "r");
+	try {
+		const stat = await handle.stat();
+		if (!stat.isFile()) throw new FilePreviewError(415, "Only regular files can be previewed");
+		if (stat.size > limit) throw new FilePreviewError(413, "This file is too large to preview. Open it in your editor.");
+		return await handle.readFile();
+	} finally {
+		await handle.close();
+	}
+};
+const decodeText = (contents) => {
+	try {
+		const source = new TextDecoder("utf-8", { fatal: true }).decode(contents);
+		if (source.includes("\0")) throw new Error("Binary content");
+		return source;
+	} catch {
+		throw new FilePreviewError(415, "This file is not UTF-8 text. Open it in your editor.");
+	}
+};
+const previewData = async (file, theme) => {
+	const extension = path.extname(file.path).toLowerCase();
+	const mime = IMAGE_MIME_TYPES[extension];
+	const contents = await readPreviewFile(file, mime === void 0 ? MAX_TEXT_BYTES : MAX_IMAGE_BYTES);
+	if (mime !== void 0) return {
+		kind: "image",
+		src: `data:${mime};base64,${contents.toString("base64")}`
+	};
+	const source = decodeText(contents);
+	const markdown = MARKDOWN_EXTENSIONS.has(extension);
+	const lang = extension === ".mdx" ? "mdx" : langForPath(file.path);
+	const syntax = await highlightSource(source, lang ?? (markdown ? "markdown" : "text"));
+	if (!markdown) return {
+		kind: "text",
+		source,
+		syntax
+	};
+	try {
+		return {
+			html: await render(source, {
+				dir: path.dirname(file.path),
+				documentControls: false,
+				filePath: file.path,
+				initialTheme: theme,
+				inlineAssets: true
+			}),
+			kind: "markdown",
+			source,
+			syntax
+		};
+	} catch (error) {
+		return {
+			kind: "markdown",
+			renderError: formatError(error),
+			source,
+			syntax
+		};
+	}
+};
+const replyError = (response, error) => {
+	if (isRecord(error) && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+		replyJson$1(response, 404, { error: "The referenced file no longer exists" });
+		return;
+	}
+	const status = error instanceof FilePreviewError ? error.status : 500;
+	replyJson$1(response, status, { error: formatError(error) });
+};
+/** Per-server capabilities, issued only for files a rendered FileRef uses. */
+const createFilePreviews = () => {
+	const paths = /* @__PURE__ */ new Map();
+	const files = /* @__PURE__ */ new Map();
+	return {
+		async handle(request, response) {
+			if (!sameOrigin$1(request)) {
+				replyJson$1(response, 403, { error: "Request origin is not allowed" });
+				return;
+			}
+			if (request.method !== "GET") {
+				replyJson$1(response, 405, { error: "Method not allowed" });
+				return;
+			}
+			const params = new URL(request.url ?? "", "http://localhost").searchParams;
+			const file = files.get(params.get("id") ?? "");
+			if (file === void 0) {
+				replyJson$1(response, 404, { error: "The referenced file is unavailable" });
+				return;
+			}
+			try {
+				replyJson$1(response, 200, await previewData(file, params.get("theme") === "dark" ? "dark" : "light"));
+			} catch (error) {
+				replyError(response, error);
+			}
+		},
+		register: (filePath) => {
+			try {
+				const canonical = realpathSync(filePath);
+				if (!statSync(canonical).isFile()) return;
+				let file = paths.get(filePath);
+				if (file === void 0 || file.canonical !== canonical) {
+					file = {
+						canonical,
+						id: randomUUID(),
+						path: filePath
+					};
+					paths.set(filePath, file);
+					files.set(file.id, file);
+				}
+				return `/__mdxr_file?id=${file.id}`;
+			} catch {
+				return;
+			}
+		}
+	};
+};
+//#endregion
 //#region src/workspace-export-data.ts
 /** Collect a complete, internally consistent archive of one served document. */
 const createWorkspaceExportData = async (filePath, history, agent) => {
@@ -9894,6 +10032,10 @@ const servePreview = async (target, port) => {
 	};
 	target.agent?.setOnUpdate(notifyAgent);
 	const server = http.createServer((req, res) => {
+		if (req.url?.split("?")[0] === "/__mdxr_file") {
+			target.filePreviews.handle(req, res);
+			return;
+		}
 		if (req.url === "/__mdxr_workspace.js") {
 			if (target.history === void 0) {
 				res.writeHead(404);
@@ -10051,13 +10193,16 @@ const serve = async (mdxPath, port, opts = {}) => {
 	if (opts.server !== void 0 && opts.agent !== "codex") throw new Error("--server requires --agent codex");
 	const abs = path.resolve(mdxPath);
 	const history = createDocumentHistory(abs);
+	const filePreviews = createFilePreviews();
 	const server = await servePreview({
 		agent: opts.agent === void 0 ? void 0 : createAgentSession(abs, opts.agent, opts.session, opts.server),
 		agentProvider: opts.agent,
+		filePreviews,
 		history,
 		historyFile: abs,
 		label: mdxPath,
 		...trackDeps(async (onDeps) => await renderFile(abs, {
+			filePreview: filePreviews.register,
 			liveReload: true,
 			onDependencies: onDeps
 		})),
@@ -10071,13 +10216,18 @@ const serve = async (mdxPath, port, opts = {}) => {
 const serveSource = async (source, port, opts = {}) => {
 	if (opts.agent !== void 0 || opts.session !== void 0 || opts.server !== void 0) throw new Error("Agent chat requires an MDX file");
 	const dir = path.resolve(opts.dir ?? process.cwd());
+	const filePreviews = createFilePreviews();
 	const server = await servePreview({
+		filePreviews,
 		label: opts.filePath ?? "stdin",
 		...trackDeps(async (onDeps) => await render(source, {
 			dir,
+			documentControls: opts.documentControls,
 			filePath: opts.filePath,
+			filePreview: filePreviews.register,
 			hydrate: opts.hydrate,
 			initialTheme: opts.initialTheme,
+			inlineAssets: opts.inlineAssets,
 			liveReload: true,
 			onDependencies: onDeps
 		})),
@@ -10124,7 +10274,7 @@ const validateAgentOptions = (agent, session, server) => {
 	if (session !== void 0 && session.trim() === "") throw new Error("--session requires a non-empty ID");
 	return agent;
 };
-const cli = cac("mdxr");
+const cli = cac("mdxr").version(version);
 cli.command("render [file]", "Render an .mdx document to a standalone HTML file").option("-o, --out <path>", "Output path (default: <file>.html; stdout for stdin input or '-')").option("--format <format>", "Error output: text | json").option("--no-hydrate", "Emit static HTML without the client hydration bundle").option("--open", "Open the rendered file in the default browser").action(async (file, opts) => {
 	const json = opts.format === "json";
 	try {