@suzumiyaaoba/mdxr 0.10.0 → 0.12.0

package/README.md

@@ -35,7 +35,7 @@ mdxr render plan.mdx --format json   # machine-readable errors
 
 ### `mdxr serve [file]`
 
-Preview a document in the browser with live reload (`-p, --port`, default `3737`; `--open` to launch the browser once serving).
+Preview a document in the browser with live reload (`-p, --port`, default `3737`; if taken, the next free port is used; `--open` to launch the browser once serving).
 
 ### Review the rendered document
 
@@ -107,7 +107,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. Documents go in `.mdxr/` unless you specify another location.
+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.
 
 ## License
 

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { $g as REPORT_SPECS, A_ as parseDiff, Bv as parseLineRange, Dh as RESEARCH_CLAIM_SCHEMA, Eh as PERFORMANCE_TARGET_SCHEMA, Ev as numOf, Gv as isComponent, Ha as shadcnModules, Hv as SKIP_LANGS, Iv as parseProps, Jv as own, Kv as isRecord, Nm as PlanHeader, Nv as takeUsedIcons, Oh as performanceDetails, Pv as DocContext, Rv as fenceFilename, Th as PERFORMANCE_LABELS, Tv as attrTrue, Vv as splitPathLines, Wv as langForPath, Xg as calculate, Xv as urlScheme, Yv as safeHref, __ as parseJson, b_ as tableRecords, bm as plotModel, dp as dependencyMatrixModel, e_ as reportModel, fp as queryPlanModel, g_ as numberValue, h_ as isDataRecord, hv as textList, kh as performanceResult, m_ as display, mp as flameModel, mv as numList, n_ as schemaRows, p_ as columnsOf, pp as diagramModel, qv as nonEmpty, rv as isStatus, t as builtinComponents, t_ as comparisonModel, tv as STATUSES, up as bundleModel, v_ as readRecords, wh as CLAIM_LABELS, y_ as records, ym as PLOT_NAMES, zv as fenceLang } from "./ui-4uP9HfXd.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-C8uMevwJ.mjs";
+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 module from "node:module";
 import fsp, { access, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -29,8 +29,9 @@ import { icons as icons$1 } from "@iconify-json/vscode-icons";
 import { differenceInCalendarDays, isValid, parseISO } from "date-fns";
 import { createHash, randomUUID } from "node:crypto";
 import { build } from "esbuild";
+import { execFile, spawn } from "node:child_process";
 import os, { homedir } from "node:os";
-import { spawn } from "node:child_process";
+import { promisify } from "node:util";
 import { once } from "node:events";
 import { compile } from "@mdx-js/mdx";
 import { renderToStaticMarkup, renderToString } from "react-dom/server";
@@ -290,7 +291,7 @@ const EXTENDED_FEATURES = [
 	},
 	{
 		category: "evidence",
-		components: ["Include"],
+		components: ["Include", "DocumentLink"],
 		name: "Include",
 		number: 9
 	},
@@ -1255,7 +1256,7 @@ const remarkNoJs = () => (tree, file) => {
 //#region src/remark/include.ts
 const parser = unified().use(remarkParse).use(remarkMdx).use(remarkFrontmatter).use(remarkGfm).use(remarkMath).use(remarkDirective);
 const REMOTE = /^(?:[a-z][a-z\d+.-]*:|#|\/)/iu;
-const isInclude = (node) => (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && "name" in node && node.name === "Include";
+const isDocumentReference = (node) => (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && "name" in node && (node.name === "Include" || node.name === "DocumentLink");
 const sectionNodes = (nodes, section) => {
 	const slugFor = createHeadingSlugger();
 	const slugs = /* @__PURE__ */ new Map();
@@ -1299,52 +1300,90 @@ const rebase = (node, origin, root) => {
 		"href"
 	].includes(String(attr.name)) && typeof attr.value === "string") attr.value = relative(attr.value);
 };
-const includedDocument = (target, origin, chain, file) => {
-	if (target.type === "mdxJsxTextElement") file.fail("Include must be used as a block element", target, "mdxr:include");
+const includePath = (target, origin, chain, file) => {
 	const source = jsxAttr(target, "path");
-	if (source === void 0 || source === "") file.fail("Include requires path", target);
+	if (source === void 0 || source === "") file.fail(`${target.name} requires path`, target);
+	if (target.name === "DocumentLink" && ![".md", ".mdx"].includes(path.extname(source).toLowerCase())) file.fail("DocumentLink requires an .md or .mdx file", target, "mdxr:include");
 	const abs = realpathSync(path.resolve(path.dirname(origin), source));
 	if (new Set(chain).has(abs)) file.fail(`Include cycle: ${[...chain, abs].join(" → ")}`, target);
-	const included = parser.parse(readFileSync(abs, "utf-8"));
+	file.data.includeDependencies ??= [];
+	file.data.includeDependencies.push(abs);
+	return abs;
+};
+const includedDocument = (target, abs, parentFile) => {
+	const file = new VFile({
+		path: abs,
+		value: readFileSync(abs, "utf-8")
+	});
+	const included = parser.parse(file);
 	remarkNoJs()(included, file);
 	remarkMdxrDirectives()(included, file);
+	parentFile.messages.push(...file.messages);
 	const section = jsxAttr(target, "section");
 	const nodes = included.children.filter((node) => node.type !== "yaml");
-	const tree = {
+	return {
 		children: section === void 0 || section === "" ? nodes : sectionNodes(nodes, section),
 		type: "root"
 	};
+};
+const linkDocument = (target, abs, chain, file) => {
+	file.data.linkedDocuments ??= [];
+	const documents = file.data.linkedDocuments;
+	const section = jsxAttr(target, "section");
+	const id = `mdxr-document-${documents.length + 1}`;
+	documents.push({
+		ancestors: chain,
+		id,
+		path: abs,
+		section
+	});
 	target.attributes = jsxAttrs({
-		path: source,
+		document: id,
+		label: jsxAttr(target, "label"),
+		path: jsxAttr(target, "path"),
 		section
 	});
-	return {
-		abs,
-		tree
-	};
+	target.children = [];
 };
-const remarkInclude = () => (tree, file) => {
+const remarkInclude = (opts = {}) => (tree, file) => {
 	remarkNoJs()(tree, file);
-	const rootFile = path.resolve(file.path || "document.mdx");
-	const root = path.dirname(rootFile);
+	const filename = path.resolve(file.path || "document.mdx");
+	const rootFile = existsSync(filename) ? realpathSync(filename) : filename;
+	const directory = path.dirname(filename);
+	const root = existsSync(directory) ? realpathSync(directory) : directory;
 	const expand = (parent, origin, chain) => {
 		if (chain.length > 32) file.fail("Include: nesting exceeds 32 files");
+		const originDirectory = origin === filename ? root : path.dirname(origin);
 		for (const child of parent.children) {
 			child.data = {
 				...child.data,
 				mdxrSourceFile: origin
 			};
-			if (isInclude(child)) {
-				const included = includedDocument(child, origin, chain, file);
-				expand(included.tree, included.abs, [...chain, included.abs]);
-				child.children = included.tree.children;
+			if (isDocumentReference(child)) {
+				if (child.name === "Include" && child.type === "mdxJsxTextElement") file.fail("Include must be used as a block element", child, "mdxr:include");
+				const abs = includePath(child, origin, chain, file);
+				if (child.name === "DocumentLink") {
+					linkDocument(child, abs, chain, file);
+					rebase(child, originDirectory, root);
+					continue;
+				}
+				const included = includedDocument(child, abs, file);
+				expand(included, abs, [...chain, abs]);
+				child.attributes = jsxAttrs({
+					path: jsxAttr(child, "path"),
+					section: jsxAttr(child, "section")
+				});
+				child.children = included.children;
 				continue;
 			}
-			rebase(child, path.dirname(origin), root);
+			rebase(child, originDirectory, root);
 			if (isParent(child)) expand(child, origin, chain);
 		}
 	};
-	if (isParent(tree)) expand(tree, rootFile, [rootFile]);
+	if (isParent(tree)) {
+		if (opts.section !== void 0) tree.children = [...tree.children.filter((node) => node.type === "yaml"), ...sectionNodes(tree.children.filter((node) => node.type !== "yaml"), opts.section)];
+		expand(tree, filename, [...opts.ancestors ?? [], rootFile]);
+	}
 };
 //#endregion
 //#region src/remark/references.ts
@@ -2530,6 +2569,18 @@ Object.assign(extendedRenderers, {
 	Cite: { text: (node) => [link(attr(node, "href") ?? `#${attr(node, "source")}`, [txt(attr(node, "label") ?? attr(node, "source") ?? "")])] },
 	CrossRef: { text: (node, ctx) => [link(attr(node, "href") ?? `#${attr(node, "target")}`, (node.children?.length ?? 0) > 0 ? ctx.inline(node) : [txt(attr(node, "label") ?? attr(node, "target") ?? "")])] },
 	DependencyMatrix: { flow: (node) => recordsTable(dependencyMatrixModel(nodeRows(node)).rows) },
+	DocumentLink: {
+		flow: (node) => {
+			const path = attr(node, "path") ?? "";
+			const section = attr(node, "section");
+			return [para([link(section === void 0 ? path : `${path}#${section}`, [txt(attr(node, "label") ?? path)])])];
+		},
+		text: (node) => {
+			const path = attr(node, "path") ?? "";
+			const section = attr(node, "section");
+			return [link(section === void 0 ? path : `${path}#${section}`, [txt(attr(node, "label") ?? path)])];
+		}
+	},
 	DocumentSearch: { flow: () => [para([txt("Search this document using your viewer’s Find command.")])] },
 	EntityRelations: { flow: dataBlock },
 	Flamegraph: { flow: (node) => {
@@ -5556,7 +5607,11 @@ const CONVENTIONS = [
 	}
 ];
 const formatCatalog = (entries) => {
-	const lines = ["Components:", ""];
+	const lines = [
+		"Components:",
+		"  Pick the most specific component for the job: a dedicated semantic component (<Steps>, <Tests>, <Endpoints>, <Findings>, …) beats a generic Card/Table/bullet list, which loses its badges, counts, and file links. shadcn/ui and Wireframe* entries are generic building blocks for content with no dedicated component.",
+		""
+	];
 	for (const e of entries) {
 		const props = Object.entries(e.props).map(([k, p]) => `${k}${p.required ? "" : "?"}: ${p.type}`).join(", ");
 		lines.push(`  <${e.name}${props === "" ? "" : ` ${props}`}>`);
@@ -5599,11 +5654,32 @@ const docsDirIsIgnored = (source) => {
 	}
 	return ignored;
 };
+const execFileAsync = promisify(execFile);
+/** `git config --get core.excludesFile`, or git's default global ignore. */
+const globalExcludesFile = async () => {
+	const fallback = path.join(os.homedir(), ".config", "git", "ignore");
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"config",
+			"--get",
+			"core.excludesFile"
+		]);
+		const configured = stdout.trim();
+		if (configured === "") return fallback;
+		return configured.startsWith("~/") ? path.join(os.homedir(), configured.slice(2)) : configured;
+	} catch {
+		return fallback;
+	}
+};
 /**
 * Ensures the project's .gitignore covers `.mdxr/` — created or appended
-* as needed. Returns "present" when an existing rule already covers it.
+* as needed. Returns "present" when an existing project rule covers it,
+* "global" when the user's global excludes file already does (nothing is
+* written — the project file would just duplicate it).
 */
 const ensureDocsDirIgnored = async (base) => {
+	const globalIgnore = await fsp.readFile(await globalExcludesFile(), "utf-8").catch(() => null);
+	if (globalIgnore !== null && docsDirIsIgnored(globalIgnore)) return "global";
 	const file = path.join(base, ".gitignore");
 	const existing = await fsp.readFile(file, "utf-8").catch(() => null);
 	if (existing !== null && docsDirIsIgnored(existing)) return "present";
@@ -6065,6 +6141,7 @@ ${THEME_TOGGLE_HTML}
 </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)}
+${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>` : ""}
 ${o.liveReload === true ? `<script>${inlineScript(LIVE_RELOAD_JS)}<\/script>` : ""}
@@ -6641,6 +6718,96 @@ const editorUrl = (editor, absPath, line) => {
 	return scheme !== void 0 && SCRIPTABLE.has(scheme) ? void 0 : url;
 };
 //#endregion
+//#region src/rehype/linked-assets.ts
+const IMAGE_MIME_TYPES = {
+	".apng": "image/apng",
+	".avif": "image/avif",
+	".bmp": "image/bmp",
+	".gif": "image/gif",
+	".heic": "image/heic",
+	".heif": "image/heif",
+	".ico": "image/x-icon",
+	".jpeg": "image/jpeg",
+	".jpg": "image/jpeg",
+	".jxl": "image/jxl",
+	".png": "image/png",
+	".svg": "image/svg+xml",
+	".tif": "image/tiff",
+	".tiff": "image/tiff",
+	".webp": "image/webp"
+};
+const JSX_IMAGE_ATTRIBUTES = {
+	Figure: ["src"],
+	img: ["src"],
+	video: ["poster"]
+};
+const REMOTE_OR_ROOTED = /^(?:[a-z][a-z\d+.-]*:|\/|#)/iu;
+const localAssetPath = (source) => {
+	const query = source.indexOf("?");
+	const hash = source.indexOf("#");
+	let suffixStart = source.length;
+	for (const index of [query, hash]) if (index >= 0) suffixStart = Math.min(suffixStart, index);
+	const sourcePath = source.slice(0, suffixStart);
+	try {
+		return decodeURIComponent(sourcePath);
+	} catch {
+		return sourcePath;
+	}
+};
+const withFragment = (source) => {
+	const hash = source.indexOf("#");
+	return hash === -1 ? "" : source.slice(hash);
+};
+const dataUrl = (source, node, file, root) => {
+	if (source === "" || REMOTE_OR_ROOTED.test(source)) return;
+	const assetPath = localAssetPath(source);
+	const mime = IMAGE_MIME_TYPES[path.extname(assetPath).toLowerCase()];
+	if (mime === void 0) return;
+	let canonicalPath;
+	let contents;
+	try {
+		canonicalPath = realpathSync(path.resolve(root, assetPath));
+		contents = readFileSync(canonicalPath);
+	} catch (error) {
+		const code = isRecord(error) ? error.code : void 0;
+		if (code === "ENOENT" || code === "ENOTDIR") file.fail(`Linked image not found: ${source}`, node, "mdxr:linked-assets");
+		throw error;
+	}
+	file.data.includeDependencies ??= [];
+	if (!file.data.includeDependencies.includes(canonicalPath)) file.data.includeDependencies.push(canonicalPath);
+	return `data:${mime};base64,${contents.toString("base64")}${withFragment(source)}`;
+};
+const inlineHastMedia = (node, file, root) => {
+	if (!isRecord(node)) return;
+	const { properties, tagName, type } = node;
+	if (type !== "element" || !isRecord(properties)) return;
+	if (tagName !== "img" && tagName !== "video") return;
+	const attribute = tagName === "img" ? "src" : "poster";
+	const source = properties[attribute];
+	if (typeof source !== "string") return;
+	const inline = dataUrl(source, node, file, root);
+	if (inline !== void 0) properties[attribute] = inline;
+};
+const inlineMdxMedia = (node, file, root) => {
+	if (!isRecord(node) || node.type !== "mdxJsxFlowElement" && node.type !== "mdxJsxTextElement" || typeof node.name !== "string" || !Array.isArray(node.attributes)) return;
+	const imageAttributes = own(JSX_IMAGE_ATTRIBUTES, node.name);
+	if (imageAttributes === void 0) return;
+	for (const attribute of node.attributes) {
+		if (!isRecord(attribute) || typeof attribute.name !== "string" || !imageAttributes.includes(attribute.name) || typeof attribute.value !== "string") continue;
+		const inline = dataUrl(attribute.value, node, file, root);
+		if (inline !== void 0) attribute.value = inline;
+	}
+};
+/** Inline local image assets used by a linked document's standalone HTML. */
+const rehypeLinkedAssets = (opts = {}) => (tree, file) => {
+	if (opts.enabled !== true) return;
+	const root = file.dirname ?? process.cwd();
+	visit(tree, (node) => {
+		inlineHastMedia(node, file, root);
+		inlineMdxMedia(node, file, root);
+	});
+};
+//#endregion
 //#region src/workspace-syntax.ts
 const ALLOWED_STYLE_PROPERTIES = [
 	"--shiki-light",
@@ -7224,14 +7391,18 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 	const compiled = await compile(file, {
 		baseUrl: import.meta.url,
 		format: "mdx",
-		rehypePlugins: [rehypeKatex, rehypeShiki],
+		rehypePlugins: [
+			rehypeKatex,
+			rehypeShiki,
+			[rehypeLinkedAssets, { enabled: opts.include?.inlineAssets }]
+		],
 		remarkPlugins: [
 			remarkFrontmatter,
 			remarkGfm,
 			remarkMath,
 			remarkDirective,
 			remarkMdxrDirectives,
-			remarkInclude,
+			[remarkInclude, opts.include ?? {}],
 			remarkMdxrAlerts,
 			remarkNoJs,
 			remarkMdxrHeadings,
@@ -7244,6 +7415,7 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 			remarkSectionReviews
 		]
 	});
+	const { includeDependencies, linkedDocuments = [] } = compiled.data;
 	for (const m of compiled.messages) process.stderr.write(`mdxr: warning: ${formatError(m)}\n`);
 	const code = String(compiled);
 	const mod = await importBundledCode(code, "doc");
@@ -7270,9 +7442,11 @@ const mdxToHtml = async (source, components, filePath = "document.mdx", opts = {
 		body,
 		code,
 		context,
+		dependencies: [...new Set(includeDependencies)],
 		fileLinks: Object.fromEntries(fileLinks),
 		frontmatter,
 		hydrated,
+		linkedDocuments,
 		renderWithHeader: (header) => {
 			try {
 				const html = renderDocument(header);
@@ -7306,8 +7480,54 @@ ul.contains-task-list { padding-left: 1.25rem; }
   max-width: none !important;
 }
 .mdxr-graph-tools:focus-within { outline: 2px solid rgb(14 165 233); outline-offset: -2px; }
+/* Navigation is a progressive enhancement: no-JS documents keep native sizing
+ * and scrolling. Transform only the outer SVG, never its icons/edge layers. */
+.mdxr-diagram-tools { display: none; }
+.mdxr-diagrams-ready .mdxr-graph-tools { display: none; }
+.mdxr-diagrams-ready .mdxr-diagram:has(.mdxr-diagram-canvas svg) > .mdxr-diagram-tools {
+  display: flex; align-items: center; justify-content: flex-end; gap: 0.25rem;
+  flex-wrap: wrap; padding: 0.375rem 0.75rem; color: rgb(82 82 82);
+  border-bottom: 1px solid rgb(229 229 229); font-size: 0.75rem;
+}
+.mdxr-diagram-hint { flex: 1 1 12rem; }
+.mdxr-diagram-actions {
+  display: flex; align-items: center; gap: 0.25rem; flex-shrink: 0;
+  min-width: 0; margin: 0; padding: 0; border: 0;
+}
+.mdxr-diagram-tools button {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 2rem; height: 2rem; padding: 0; border-radius: 0.375rem;
+  background: transparent; color: inherit; cursor: pointer;
+}
+.mdxr-diagram-tools button:hover { background: rgb(229 229 229); }
+.mdxr-diagram-tools button:disabled { opacity: 0.35; cursor: default; }
+.mdxr-diagram-tools button:focus-visible, .mdxr-diagram-canvas:focus-visible {
+  outline: 2px solid rgb(14 165 233); outline-offset: -2px;
+}
+.mdxr-diagram-tools svg { width: 1rem; height: 1rem; }
+.mdxr-diagram-tools output { min-width: 3rem; text-align: center; font-variant-numeric: tabular-nums; }
+.dark .mdxr-diagram-tools { color: rgb(163 163 163) !important; border-color: rgb(64 64 64) !important; }
+.dark .mdxr-diagram-tools button:hover { background: rgb(64 64 64); }
+.mdxr-diagrams-ready .mdxr-diagram-canvas:has(svg) {
+  display: flex; align-items: safe center; justify-content: safe center;
+  overflow: hidden; min-height: 12rem; max-height: 70vh;
+  cursor: grab; touch-action: none;
+}
+.mdxr-diagram-canvas > svg, .mdxr-diagram-canvas > .mermaid { flex: none; }
+.mdxr-diagram-canvas > .mermaid { width: 100%; }
+.mdxr-diagrams-ready .mdxr-diagram-canvas[data-dragging] { cursor: grabbing; user-select: none; }
+.mdxr-diagram-canvas > svg, .mdxr-diagram-canvas > .mermaid > svg {
+  transform: var(--mdxr-diagram-transform, none); transform-origin: 0 0;
+}
+.mdxr-diagram-canvas > .mermaid:has(svg) { overflow: visible; padding: 0; background: transparent; }
 @media print {
-  .mdxr-graph-tools { display: none; }
+  .mdxr-graph-tools, .mdxr-diagram-tools { display: none !important; }
+  .mdxr-diagram-canvas {
+    overflow: visible !important; min-height: 0 !important; max-height: none !important;
+  }
+  .mdxr-diagram-canvas > svg, .mdxr-diagram-canvas > .mermaid > svg {
+    transform: none !important; min-width: 0 !important; max-width: 100% !important;
+  }
   .mdxr-graph-scroll { overflow: visible; }
   .mdxr-graph-view:has(.mdxr-graph-actual:checked) .mdxr-graph-image,
   .mdxr-graph-view .mdxr-graph-image {
@@ -7900,8 +8120,7 @@ const frontmatterHeader = (fm, body) => {
 		version: fm("version")
 	};
 };
-/** Render MDX source text to a standalone HTML document. */
-const render = async (source, opts = {}) => {
+const renderDocument = async (source, opts, include = {}) => {
 	const dir = path.resolve(opts.dir ?? process.cwd());
 	const filePath = path.resolve(dir, opts.filePath ?? "document.mdx");
 	const config = await loadConfig(dir);
@@ -7912,9 +8131,10 @@ const render = async (source, opts = {}) => {
 		...builtinComponents,
 		...user.components
 	};
-	const { annotationSources, body, code, fileLinks, frontmatter, renderedAt, renderWithHeader, usedComponents, usedIcons } = await mdxToHtml(source, components, filePath, {
+	const { annotationSources, body, code, dependencies: includeDependencies, fileLinks, frontmatter, linkedDocuments, renderedAt, renderWithHeader, usedComponents, usedIcons } = await mdxToHtml(source, components, filePath, {
 		editor: config.editor,
-		hydrate: opts.hydrate
+		hydrate: opts.hydrate,
+		include
 	});
 	const fmStr = (key) => {
 		const val = frontmatter[key];
@@ -7960,7 +8180,7 @@ const render = async (source, opts = {}) => {
 		}]
 	];
 	const { css, dependencies } = await buildCss(sources, config.themePath);
-	opts.onDependencies?.(dependencies);
+	const documentDependencies = /* @__PURE__ */ new Set([...dependencies, ...includeDependencies]);
 	const [js, hydrateJs] = await Promise.all([clientJs(), buildHydrateBundle({
 		code,
 		config,
@@ -7971,6 +8191,30 @@ const render = async (source, opts = {}) => {
 		usedComponents,
 		usedIcons: docIcons
 	})]);
+	const documents = {};
+	const sourceDirectory = path.dirname(filePath);
+	const documentBase = existsSync(sourceDirectory) ? realpathSync(sourceDirectory) : sourceDirectory;
+	for (const linked of linkedDocuments) {
+		const linkedSource = await readFile(linked.path, "utf-8");
+		const html = await renderDocument(linkedSource, {
+			...opts,
+			dir,
+			filePath: linked.path,
+			liveReload: false,
+			onDependencies: (paths) => {
+				for (const dependency of paths) documentDependencies.add(dependency);
+			}
+		}, {
+			ancestors: linked.ancestors,
+			inlineAssets: true,
+			section: linked.section
+		});
+		documents[linked.id] = {
+			html,
+			path: path.relative(documentBase, linked.path).split(path.sep).map(encodeURIComponent).join("/")
+		};
+	}
+	opts.onDependencies?.([...documentDependencies]);
 	return htmlDocument({
 		annotations: {
 			file: filePath,
@@ -7983,12 +8227,15 @@ const render = async (source, opts = {}) => {
 		css,
 		hydrateJs,
 		initialTheme: opts.initialTheme,
+		linkedDocuments: documents,
 		liveReload: opts.liveReload,
 		needsKatex: /class="[^"]*katex/u.test(docBody),
 		needsMermaid: /class="[^"]*mermaid/u.test(docBody),
 		title
 	});
 };
+/** Render MDX source text to a standalone HTML document. */
+const render = async (source, opts = {}) => await renderDocument(source, opts);
 /** Read `mdxPath` and render it to a standalone HTML document. */
 const renderFile = async (mdxPath, opts = {}) => {
 	const abs = path.resolve(mdxPath);
@@ -9526,6 +9773,26 @@ const SKIP_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
 	"storybook-static"
 ]);
+/** Upper bound on consecutive EADDRINUSE retries before give-up. */
+const MAX_PORT_ATTEMPTS = 100;
+/**
+* Bind `server` on loopback to `port`, or to the next free port after it —
+* a probe-then-bind helper would just race the real listen. Port 0 already
+* asks the OS for a port, so it binds once and never retries.
+*/
+const listenOnFreePort = async (server, port) => {
+	for (let attempt = 0;; attempt += 1) {
+		const candidate = port + attempt;
+		try {
+			server.listen(candidate, "127.0.0.1");
+			await once(server, "listening");
+			if (attempt > 0) console.log(`mdxr: port ${port} is taken, using ${candidate}`);
+			return;
+		} catch (error) {
+			if (!(error instanceof Error && error.code === "EADDRINUSE") || port === 0 || attempt >= MAX_PORT_ATTEMPTS || candidate >= 65535) throw error;
+		}
+	}
+};
 const handleDocumentResponse = (req, res, target, html) => {
 	if (req.url?.startsWith("/__mdxr_history") === true) {
 		handleDocumentHistoryRequest(req, res, target.history, target.historyFile);
@@ -9741,8 +10008,7 @@ const servePreview = async (target, port) => {
 	reloading = rebuild(notify);
 	await reloading;
 	try {
-		server.listen(port, "127.0.0.1");
-		await once(server, "listening");
+		await listenOnFreePort(server, port);
 	} catch (error) {
 		server.close();
 		throw error;
@@ -9887,7 +10153,7 @@ cli.command("render [file]", "Render an .mdx document to a standalone HTML file"
 		fail(error, json);
 	}
 });
-cli.command("serve [file]", "Preview a document in the browser with live reload").option("-p, --port <port>", "Port", { default: 3737 }).option("--open", "Open the preview in the default browser once serving").option("--agent <agent>", "Chat with codex or claude in the preview").option("--session <id>", "Send to an existing Codex thread").option("--server <url>", "Codex App Server ws:// or unix:// endpoint").action(async (file, opts) => {
+cli.command("serve [file]", "Preview a document in the browser with live reload").option("-p, --port <port>", "Preferred port; if taken, the next free port is used", { default: 3737 }).option("--open", "Open the preview in the default browser once serving").option("--agent <agent>", "Chat with codex or claude in the preview").option("--session <id>", "Send to an existing Codex thread").option("--server <url>", "Codex App Server ws:// or unix:// endpoint").action(async (file, opts) => {
 	try {
 		const port = Number(opts.port);
 		if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`invalid --port: ${opts.port}`);
@@ -9966,7 +10232,11 @@ cli.command("init", "Install mdxr instructions for Codex and Claude").option("--
 		}
 		if (!global) {
 			const status = await ensureDocsDirIgnored(process.cwd());
-			console.log(status === "added" ? "mdxr: added .mdxr/ to .gitignore" : "mdxr: .gitignore already covers .mdxr/");
+			console.log({
+				added: "mdxr: added .mdxr/ to .gitignore",
+				global: "mdxr: .mdxr/ is already covered by your global git excludes",
+				present: "mdxr: .gitignore already covers .mdxr/"
+			}[status]);
 		}
 	} catch (error) {
 		fail(error, false);