concept-atlas-dense-explain 0.4.1 → 0.5.0

package/bin/cli.mjs

@@ -4,19 +4,23 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { build } from 'vite';
 import { fileURLToPath } from 'node:url';
-import { validateMdxSource, countBySeverity } from '../template/src/model/validate-content.js';
+import { validateMdxSource, countBySeverity, detectFeatures } from '../template/src/model/validate-content.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const templateRoot = path.join(packageRoot, 'template');
 const args = process.argv.slice(2);
+let buildCounter = 0;
 
 function usage() {
   console.log('Usage:');
-  console.log('  npx concept-atlas-dense-explain <input.mdx> [--mode atlas|scroll] [-o output.html] [--force] [--json] [--no-validate]');
-  console.log('  npx concept-atlas-dense-explain render <input.mdx> [--mode atlas|scroll] [-o output.html] [--force]');
+  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [-o output.html|dir] [--force] [--concurrency N] [--link-assets] [--json] [--no-validate]');
+  console.log('  npx concept-atlas-dense-explain render <input.mdx>... [-o output.html|dir]');
   console.log('  npx concept-atlas-dense-explain validate <input.mdx> [--mode atlas|scroll] [--strict] [--json]');
   console.log('  npx concept-atlas-dense-explain create <output.mdx> [--mode atlas|scroll] [--force]');
   console.log('  npx concept-atlas-dense-explain guide [--mode atlas|scroll] [-o output.mdx] [--force]');
+  console.log('');
+  console.log('  Multiple inputs build in parallel (default 2 at a time, cap 4); -o is then a directory.');
+  console.log('  --link-assets keeps figures as relative links instead of inlining them as base64.');
 }
 
 async function exists(filePath) {
@@ -37,17 +41,55 @@ function fail(message) {
   process.exit(1);
 }
 
-function printDiagnostics(source, options, { json }) {
+const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency']);
+
+/** Splits argv into flags, flag values and positional arguments. */
+function parseFlags(argv) {
+  const flags = new Set();
+  const values = new Map();
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (VALUE_FLAGS.has(arg)) {
+      values.set(arg, argv[i + 1]);
+      i += 1;
+    } else if (arg.startsWith('-') && arg.length > 1) {
+      flags.add(arg);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, values, positional };
+}
+
+/**
+ * A single input may name an output file; a batch needs a directory, because the
+ * per-target file names come from the inputs.
+ */
+function resolveOutputs(inputs, explicit) {
+  const defaults = inputs.map(input => input.replace(/\.mdx$/i, '.html'));
+  if (!explicit) return defaults;
+  const target = path.resolve(explicit);
+  if (inputs.length === 1) return [target];
+  if (path.extname(target).toLowerCase() === '.html') {
+    fail('`-o` must be a directory when building more than one input.');
+  }
+  return inputs.map(input => path.join(target, `${path.basename(input, path.extname(input))}.html`));
+}
+
+function printDiagnostics(source, options, { json, label = null, quiet = false }) {
   const result = validateMdxSource(source, options);
+  if (quiet) return result;
   if (json) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return result;
   }
+  if (label) console.error(`\n${label}`);
   const { diagnostics, carrier, stats } = result;
   for (const item of diagnostics) {
-    const label = item.severity === 'error' ? 'error' : 'warn ';
+    const severity = item.severity === 'error' ? 'error' : 'warn ';
     const where = `${item.line}:${item.column}`;
-    console.error(`${label} ${where}  ${item.code}  ${item.message}`);
+    console.error(`${severity} ${where}  ${item.code}  ${item.message}`);
   }
   const { error, warning } = countBySeverity(diagnostics);
   const scope = carrier ? `${carrier} · ${stats.nodes} 节点 / ${stats.relations} 关系` : '未识别载体';
@@ -151,83 +193,179 @@ if (command === 'create' || command === 'new') {
   process.exit(0);
 }
 
-const json = args.includes('--json');
-const strict = args.includes('--strict');
-const skipValidate = args.includes('--no-validate');
+const parsed = parseFlags(args);
+const json = parsed.flags.has('--json');
+const strict = parsed.flags.has('--strict');
+const skipValidate = parsed.flags.has('--no-validate');
+const force = parsed.flags.has('--force');
+const linkAssets = parsed.flags.has('--link-assets');
+const modeFlag = parsed.values.get('--mode') || null;
 
 if (command === 'validate') {
-  const target = args[0] ? path.resolve(args[0]) : null;
+  const target = parsed.positional[0] ? path.resolve(parsed.positional[0]) : null;
   if (!target || path.extname(target).toLowerCase() !== '.mdx' || !(await exists(target))) {
     fail('Provide an existing .mdx file to validate.');
   }
   const source = await readFile(target, 'utf8');
-  const modeFlag = flagValue(args, ['--mode']);
   const result = printDiagnostics(source, {
     filePath: target,
-    mode: modeFlag || null,
+    mode: modeFlag,
     strict,
     assetExists: spec => existsSync(path.resolve(path.dirname(target), spec)),
   }, { json });
   process.exit(countBySeverity(result.diagnostics).error ? 1 : 0);
 }
 
-if (args[0] && args[0].toLowerCase() === 'render') args.shift();
-const input = args[0] ? path.resolve(args[0]) : null;
-const modeFlag = flagValue(args, ['--mode']);
-const output = path.resolve(flagValue(args, ['-o', '--output']) || (input ? input.replace(/\.mdx$/i, '.html') : ''));
-const force = args.includes('--force');
+// `render` is the default command, so it may still appear as a leading token.
+const positional = parsed.positional[0] && parsed.positional[0].toLowerCase() === 'render'
+  ? parsed.positional.slice(1)
+  : parsed.positional;
+const inputs = positional.map(entry => path.resolve(entry));
 
-if (!input || path.extname(input).toLowerCase() !== '.mdx' || !(await exists(input))) {
-  console.error('Provide an existing .mdx input file.');
+if (!inputs.length) {
+  console.error('Provide at least one existing .mdx input file.');
   usage();
   process.exit(1);
 }
+for (const input of inputs) {
+  if (path.extname(input).toLowerCase() !== '.mdx' || !(await exists(input))) {
+    console.error(`Not an existing .mdx input: ${input}`);
+    process.exit(1);
+  }
+}
 
-const source = await readFile(input, 'utf8');
-const validation = printDiagnostics(source, {
-  filePath: input,
-  mode: modeFlag || null,
+const outputs = resolveOutputs(inputs, parsed.values.get('-o') || parsed.values.get('--output'));
+
+for (const output of outputs) {
+  if (await exists(output) && !force) {
+    console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
+    process.exit(1);
+  }
+}
+
+const multi = inputs.length > 1;
+const sources = await Promise.all(inputs.map(input => readFile(input, 'utf8')));
+
+// Validate every document before building any of them: a batch should fail as a
+// batch rather than leaving half the targets rendered.
+const validations = sources.map((source, index) => printDiagnostics(source, {
+  filePath: inputs[index],
+  mode: modeFlag,
   strict,
-  assetExists: spec => existsSync(path.resolve(path.dirname(input), spec)),
-}, { json });
-const { error: errorCount } = countBySeverity(validation.diagnostics);
+  assetExists: spec => existsSync(path.resolve(path.dirname(inputs[index]), spec)),
+}, json
+  ? { json: false, quiet: true }
+  : { json: false, label: multi ? inputs[index] : null }));
 
+if (json) {
+  const payload = multi
+    ? validations.map((result, index) => ({ file: inputs[index], ...result }))
+    : validations[0];
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+const errorCount = validations.reduce((sum, result) => sum + countBySeverity(result.diagnostics).error, 0);
 if (errorCount && !skipValidate) {
   console.error('内容校验未通过，已停止构建。修复后重试，或用 --no-validate 强制构建。');
   process.exit(1);
 }
 
-const mode = modeFlag || validation.carrier;
-if (!mode || !['atlas', 'scroll'].includes(mode)) {
-  console.error('Could not detect the MDX carrier; choose --mode atlas or --mode scroll.');
-  process.exit(1);
-}
-if (await exists(output) && !force) {
-  console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
+const jobs = inputs.map((input, index) => {
+  const mode = modeFlag || validations[index].carrier;
+  if (!mode || !['atlas', 'scroll'].includes(mode)) {
+    console.error(`Could not detect the MDX carrier for ${input}; choose --mode atlas or --mode scroll.`);
+    process.exit(1);
+  }
+  if (linkAssets && path.resolve(path.dirname(outputs[index])) !== path.resolve(path.dirname(input))) {
+    console.error(`警告：--link-assets 下 ${outputs[index]} 不在 ${path.dirname(input)} 内，相对图片路径会失效。`);
+  }
+  return { input, output: outputs[index], mode, features: detectFeatures(sources[index]), linkAssets };
+});
+
+const limit = clampConcurrency(parsed.values.get('--concurrency'), jobs.length);
+const started = Date.now();
+const results = await runPool(jobs.map(job => () => buildOne(job)), limit);
+
+const failures = results.filter(result => !result.ok);
+const saved = summarizeFeatures(jobs, results);
+console.log(`Built ${results.length - failures.length}/${results.length} page(s) with concurrency ${limit} in ${((Date.now() - started) / 1000).toFixed(1)}s${saved ? ` (${saved})` : ''}.`);
+if (failures.length) {
+  for (const failure of failures) console.error(`Build failed for ${failure.input}:`, failure.error);
   process.exit(1);
 }
-await mkdir(path.dirname(output), { recursive: true });
-
-const templateEntry = mode === 'atlas' ? 'index.html' : 'scroll.html';
-const generatedEntry = path.join(path.dirname(output), templateEntry);
-
-try {
-  await build({
-    root: templateRoot,
-    configFile: path.join(templateRoot, 'vite.config.js'),
-    resolve: { alias: { '@concept-atlas/content': input } },
-    build: {
-      outDir: path.dirname(output),
-      emptyOutDir: false,
-      rollupOptions: { input: path.join(templateRoot, templateEntry) },
-    },
-  });
-  if (generatedEntry !== output) {
+
+async function buildOne(job) {
+  const { input, output, mode, features, linkAssets: link } = job;
+  const templateEntry = mode === 'atlas' ? 'index.html' : 'scroll.html';
+  // Each build gets its own scratch outDir: the template always writes
+  // `index.html`/`scroll.html`, so concurrent builds sharing a directory would
+  // overwrite each other before the rename.
+  const scratch = path.join(path.dirname(output), `.concept-atlas-${process.pid}-${(buildCounter += 1)}`);
+  await mkdir(path.dirname(output), { recursive: true });
+  await mkdir(scratch, { recursive: true });
+  const define = { __ATLAS_FEATURES__: JSON.stringify(features) };
+  if (link) define.__ATLAS_INLINE_ASSETS__ = 'false';
+  try {
+    await build({
+      root: templateRoot,
+      configFile: path.join(templateRoot, 'vite.config.js'),
+      resolve: { alias: { '@concept-atlas/content': input } },
+      define,
+      build: {
+        outDir: scratch,
+        emptyOutDir: false,
+        rollupOptions: { input: path.join(templateRoot, templateEntry) },
+      },
+    });
     await rm(output, { force: true });
-    await rename(generatedEntry, output);
+    await rename(path.join(scratch, templateEntry), output);
+    console.log(`Built ${mode} HTML: ${output}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
+    return { ok: true, input, output };
+  } catch (error) {
+    return { ok: false, input, output, error };
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
   }
-  console.log(`Built ${mode} HTML: ${output}`);
-} catch (error) {
-  console.error('Build failed:', error);
-  process.exit(1);
+}
+
+/** Saves the mermaid/KaTeX payload when a document never renders them. */
+function describeFeatures(features) {
+  if (features.math && features.mermaid) return '';
+  const dropped = [features.math ? null : 'KaTeX', features.mermaid ? null : 'Mermaid'].filter(Boolean);
+  return `  [no ${dropped.join('/')}]`;
+}
+
+function summarizeFeatures(jobs, results) {
+  const built = new Set(results.filter(result => result.ok).map(result => result.input));
+  const pages = jobs.filter(job => built.has(job.input));
+  if (!pages.length) return '';
+  const droppedMath = pages.filter(job => !job.features.math).length;
+  const droppedMermaid = pages.filter(job => !job.features.mermaid).length;
+  const parts = [];
+  if (droppedMath) parts.push(`KaTeX dropped on ${droppedMath}/${pages.length}`);
+  if (droppedMermaid) parts.push(`Mermaid dropped on ${droppedMermaid}/${pages.length}`);
+  return parts.join(', ');
+}
+
+function clampConcurrency(raw, count) {
+  const parsedValue = Number.parseInt(raw ?? '', 10);
+  const fallback = Math.min(2, count);
+  if (!Number.isFinite(parsedValue)) return Math.max(1, fallback);
+  return Math.max(1, Math.min(4, parsedValue));
+}
+
+/** Runs `tasks` with at most `limit` in flight, preserving result order. */
+async function runPool(tasks, limit) {
+  const results = new Array(tasks.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, async () => {
+    for (;;) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= tasks.length) return;
+      results[index] = await tasks[index]();
+    }
+  });
+  await Promise.all(workers);
+  return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -27,12 +27,13 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    ```
    Every diagnostic is `CODE line:column message`. Fix all `error`s and re-run; warnings are quality signals you should also address when cheap.
 6. Compile: `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build; use `--no-validate` only to force a knowingly broken build.
-7. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
+7. For several documents, pass them all in one call: `npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist --force [--concurrency 3]`. `-o` is then a directory. The batch validates everything first and builds in parallel. Builds only bundle the heavy renderers the content uses: a page with no `<Math>`/`<Mermaid>` skips KaTeX (its ~1.4MB inlined fonts) and Mermaid, shrinking a typical scroll article from ~5MB to ~250KB. Do not add dummy `<Math>`/`<Mermaid>` nodes to "enable" them — write the components only when the content needs them. Add `--link-assets` when the page carries many screenshots and size matters.
+8. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
 
 ## Carriers
 
 - `atlas`: `ExplainPage` → `ConceptGraph` → `ConceptNode`, plus `Children`/`ConceptRef` and cross-branch `Relation`s. Exactly one `L0` root, several `L1` branches, depth to `L3`/`L4`. Shared components live inside nodes.
-- `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components live inside sections. The shell auto-builds a table of contents, reading progress, and prev/next from section titles — do not hand-build navigation.
+- `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components live inside sections. The shell auto-builds a a table of contents and reading progress from section titles — do not hand-build navigation.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families
@@ -51,10 +52,11 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 - `Relation type` must be one of `prerequisite`, `causes`, `produces`, `uses`, `implements`, `contrasts`, `depends-on`, `exception-of`, `precedes`, and each `Relation` needs a `label`. Parent/child hierarchy is implicit (via `parent` and `Children`/`ConceptRef`) — do not express it with a `Relation`.
 - **Math**: MDX parses `{ ... }` in children as expressions, so pass LaTeX with braces or backslashes through `formula`: `<Math formula="r_{\text{ann}} = (1 + r)^{12} - 1" />`, `<MathBlock formula="I(x) = -\log_2 p(x)" variables={[{symbol, description}]} />`. Brace-free children such as `<Math>\log_2 N</Math>` are fine. The validator warns (`MATH_CHILDREN_BRACES`).
 - **Chart**: `type` is `bar` | `line` | `pie`; use `data` for bar/pie and `labels` + `series={[{name, values}]}` for line. Charts follow theme colors.
-- **Figure**: a relative `src` (`./assets/diagram.png`) is inlined as base64 at build time so the HTML stays standalone; `http(s)` URLs stay links. Always set `alt`; add `label` and `caption` for a numbered caption. A missing relative file produces an `ASSET_MISSING` warning and a placeholder.
+- **Figure**: a relative `src` (`./assets/diagram.png`) is inlined as base64 at build time so the HTML stays standalone; `http(s)` URLs stay links. Always set `alt`; add `label` and `caption` for a numbered caption. A missing relative file produces an `ASSET_MISSING` warning and a placeholder. Readers can click any figure to open it full-screen (wheel/`+`/`−` zoom, drag to pan, double-click for 1x/2x, `Esc` to close) — mention this when a page carries dense diagrams.
+- **Figure size**: inlining is what makes a screenshot-heavy page large. When a document carries many images and the user cares about size, compile with `--link-assets` to keep them as relative links (measured: 1.51MB → 270KB on one page). The output then has to live beside the MDX's `assets/` directory, and the CLI warns if `-o` points elsewhere — tell the user that trade-off instead of choosing silently.
 - **Cite/References**: `<Cite id="..." />` renders `[n]` from the matching item's position in `<References items={...} />`. In `scroll`, `References` can sit anywhere. In `atlas`, keep the cites and the `References` block in the same node, because node content only renders when that node is open.
 - Continuous reading is configured on the shell, not with manual CSS: `spacing="compact|comfortable|airy"` for rhythm, `fontSize="compact|normal|large|xlarge"` (or numeric `scale`/`lineHeight`) for text size.
-- Be brief about cost: KaTeX fonts and Mermaid roughly double the single-file output (~5 MB), which is normal for an offline explainer. Mention it if the user cares about file size.
+- Be brief about cost: the build only bundles the heavy optional renderers the document actually uses, so a page with no `<Math>`/`<Mermaid>` comes out around 250KB. Inlined figures are usually the largest remaining cost — a page with a dozen screenshots lands near 1–2MB, which is normal for an offline explainer. Mention it if the user cares about file size.
 
 ## Validation diagnostics
 

package/template/guides/atlas-guide.mdx

@@ -125,7 +125,7 @@
     </ConceptNode>
 
     <ConceptNode id="chart-demo" title="Chart：用同一数据切换三种图形" level="L2" parent="extension-family" summary="bar、line、pie 三种类型共享数据形状，按比较、趋势或占比选择。">
-      <Definition>Chart 接收 data（{label, value} 数组）或 series + labels，在 SVG 中绘制并跟随主题色。</Definition>
+      <Definition>Chart 接收 data（`{label, value}` 数组）或 series + labels，在 SVG 中绘制并跟随主题色。</Definition>
       <Chart title="各阶段耗时" type="bar" unit="小时" data={[{label:'收集',value:6},{label:'分析',value:14},{label:'验证',value:9},{label:'落地',value:4}]} />
       <Chart title="留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]}]} />
     </ConceptNode>

package/template/guides/scroll-guide.mdx

@@ -1,9 +1,6 @@
----
-title: scroll-guide
----
-
 <ScrollDocument spacing="comfortable" fontSize="normal">
   <ScrollHeader title="Concept Atlas 连续阅读指南" label="连续阅读 · 组件参考">同一套语义组件可以脱离图谱和节点面板，按传统文档流连续阅读。本页同时是一份可运行的组件参考：每一节演示一个组件家族，正文保持高信息密度，模型在需要比较、推导或收敛时占满可用宽度。</ScrollHeader>
+
   <ScrollSection title="先识别推理结构">
     <ScrollProse>模型不是内容的装饰。它们分别处理并列要素、二维定位、变量关系、论证层级和筛选过程。先确认关系形状，读者才能用最短路径验证结论。</ScrollProse>
     <LearningObjectives items={['按关系形状选择组件', '把结论与证据分开表达', '让每个区块承担不同的认知任务']} />

package/template/src/components/MDXComponents.jsx

@@ -1,6 +1,8 @@
 import React from 'react';
+import { createPortal } from 'react-dom';
 import mermaid from 'mermaid';
 import katex from 'katex';
+import { ZoomIn } from 'lucide-react';
 import 'katex/dist/katex.min.css';
 import { registerReferences, subscribeReferences, getReferenceIndex } from '../model/citations.js';
 
@@ -563,32 +565,16 @@ export function ScrollDocument({ spacing = 'comfortable', fontSize = 'normal', s
     '--reading-line-height': String(lineHeight ?? preset.lineHeight),
   };
 
-  const activeIndex = items.findIndex(item => item.id === activeId);
-  const previous = activeIndex > 0 ? items[activeIndex - 1] : null;
-  const next = activeIndex >= 0 && activeIndex < items.length - 1 ? items[activeIndex + 1] : null;
+  const showToc = toc && items.length >= 2;
 
   return (
-    <article className={`continuous-document continuous-spacing-${safeSpacing}`} data-font-size={fontSize} style={style}>
+    <article className={`continuous-document continuous-spacing-${safeSpacing}${showToc ? ' has-toc' : ''}`} data-font-size={fontSize} style={style}>
       {progress && <ReadingProgress />}
       <ScrollOutlineContext.Provider value={outline}>
-        {toc && <ScrollToc items={items} activeId={activeId} />}
-        {children}
-        {activeIndex >= 0 && (previous || next) && (
-          <nav className="scroll-pager" aria-label="章节导航">
-            {previous ? (
-              <a className="pager-prev" href={`#${previous.id}`}>
-                <span>上一节</span>
-                <strong>{previous.title}</strong>
-              </a>
-            ) : <span className="pager-spacer" />}
-            {next ? (
-              <a className="pager-next" href={`#${next.id}`}>
-                <span>下一节</span>
-                <strong>{next.title}</strong>
-              </a>
-            ) : <span className="pager-spacer" />}
-          </nav>
-        )}
+        {showToc && <ScrollToc items={items} activeId={activeId} />}
+        <div className="continuous-content">
+          {children}
+        </div>
       </ScrollOutlineContext.Provider>
     </article>
   );
@@ -768,12 +754,16 @@ NoteGrid.displayName = 'NoteGrid';
 
 // Math ----------------------------------------------------------------------
 
-export function Math({ formula, children }) {
+// Named MathInline internally: exporting a function literally called `Math`
+// would shadow the global Math object for the whole module and break Math.max
+// and friends. It is exported as `Math` so MDX can use <Math>.
+function MathInline({ formula, children }) {
   const tex = (formula || childrenToText(children)).trim();
   if (!tex) return null;
   return <span className="semantic-math" dangerouslySetInnerHTML={{ __html: renderTex(tex, false) }} />;
 }
-Math.displayName = 'Math';
+MathInline.displayName = 'Math';
+export { MathInline as Math };
 
 export function MathBlock({ title = '公式', formula, variables = [], children }) {
   const tex = (formula || childrenToText(children)).trim();
@@ -966,18 +956,153 @@ Chart.displayName = 'Chart';
 
 // Figures -------------------------------------------------------------------
 
+const ZOOM_MIN = 0.5;
+const ZOOM_MAX = 6;
+
+/**
+ * Full-viewport image viewer. Rendered through a portal so it escapes the
+ * transformed/rotated ancestor surfaces (`position: fixed` would otherwise be
+ * contained by them). Supports wheel zoom, drag to pan, double-click to toggle
+ * 1x/2x, and Escape to close.
+ */
+function ImageZoom({ src, alt, caption, label, onClose }) {
+  const [scale, setScale] = React.useState(1);
+  const [offset, setOffset] = React.useState({ x: 0, y: 0 });
+  const [dragging, setDragging] = React.useState(false);
+  const stageRef = React.useRef(null);
+  const closeRef = React.useRef(null);
+  const dragRef = React.useRef(null);
+  const movedRef = React.useRef(false);
+  const scaleRef = React.useRef(scale);
+  scaleRef.current = scale;
+
+  const clampScale = value => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, +value.toFixed(3)));
+  const zoomBy = delta => setScale(value => clampScale(value + delta));
+  const reset = () => { setScale(1); setOffset({ x: 0, y: 0 }); };
+  // Cursor-anchored zoom feels wrong at 1x; recentre whenever we return to it.
+  const settle = value => { if (value <= 1) setOffset({ x: 0, y: 0 }); };
+
+  React.useEffect(() => {
+    const stage = stageRef.current;
+    if (!stage) return undefined;
+    // React binds `wheel` passively, so preventDefault needs a native listener.
+    const onWheel = event => {
+      event.preventDefault();
+      const next = clampScale(scaleRef.current * Math.exp(-event.deltaY * 0.0015));
+      setScale(next);
+      settle(next);
+    };
+    stage.addEventListener('wheel', onWheel, { passive: false });
+    return () => stage.removeEventListener('wheel', onWheel);
+  }, []);
+
+  React.useEffect(() => {
+    const onKeyDown = event => {
+      if (event.key === 'Escape') { event.stopPropagation(); onClose(); }
+      else if (event.key === '+' || event.key === '=') zoomBy(0.25);
+      else if (event.key === '-' || event.key === '_') zoomBy(-0.25);
+      else if (event.key === '0') reset();
+    };
+    window.addEventListener('keydown', onKeyDown, true);
+    const { overflow } = document.body.style;
+    document.body.style.overflow = 'hidden';
+    closeRef.current?.focus();
+    return () => {
+      window.removeEventListener('keydown', onKeyDown, true);
+      document.body.style.overflow = overflow;
+    };
+  }, [onClose]);
+
+  const onPointerDown = event => {
+    if (event.target.closest('button')) return;
+    dragRef.current = { id: event.pointerId, x: event.clientX, y: event.clientY, ox: offset.x, oy: offset.y };
+    movedRef.current = false;
+    setDragging(true);
+    event.currentTarget.setPointerCapture(event.pointerId);
+  };
+
+  const onPointerMove = event => {
+    const drag = dragRef.current;
+    if (!drag || drag.id !== event.pointerId) return;
+    const dx = event.clientX - drag.x;
+    const dy = event.clientY - drag.y;
+    if (!movedRef.current && Math.hypot(dx, dy) < 6) return;
+    movedRef.current = true;
+    setOffset({ x: drag.ox + dx, y: drag.oy + dy });
+  };
+
+  const onPointerUp = event => {
+    if (dragRef.current?.id === event.pointerId) {
+      dragRef.current = null;
+      setDragging(false);
+      event.currentTarget.releasePointerCapture?.(event.pointerId);
+    }
+  };
+
+  const title = alt || caption || '图片';
+
+  return createPortal(
+    <div
+      className="image-zoom-overlay"
+      role="dialog"
+      aria-modal="true"
+      aria-label={`放大查看：${title}`}
+      onClick={event => { if (event.target === event.currentTarget && !movedRef.current) onClose(); }}
+    >
+      <div
+        ref={stageRef}
+        className={`image-zoom-stage${dragging ? ' is-dragging' : ''}`}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={onPointerUp}
+        onPointerCancel={onPointerUp}
+        onDoubleClick={() => { const next = scaleRef.current > 1 ? 1 : 2; setScale(next); settle(next); }}
+        onClick={event => { if (movedRef.current) { event.stopPropagation(); movedRef.current = false; } }}
+      >
+        <img
+          src={src}
+          alt={alt || ''}
+          draggable="false"
+          style={{ transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})` }}
+        />
+      </div>
+      {title && <p className="image-zoom-caption">{label && <b>{label}</b>}{caption || alt}</p>}
+      <div className="image-zoom-toolbar">
+        <button type="button" onClick={() => zoomBy(-0.25)} aria-label="缩小" title="缩小（−）">−</button>
+        <span aria-live="polite">{Math.round(scale * 100)}%</span>
+        <button type="button" onClick={() => zoomBy(0.25)} aria-label="放大" title="放大（＋）">＋</button>
+        <button type="button" onClick={reset} aria-label="重置缩放" title="重置（0）">↺</button>
+        <button type="button" ref={closeRef} onClick={onClose} aria-label="关闭" title="关闭（Esc）">✕</button>
+      </div>
+    </div>,
+    document.body,
+  );
+}
+
 export function Figure({ src, alt = '', caption, label, width = 'auto', height = 'auto', x = 0, y = 0, position = 'flow' }) {
+  const [zoomed, setZoomed] = React.useState(false);
+  const title = alt || caption || '图片';
+
   return (
     <figure className={`semantic-figure ${widgetClass(position)}`} style={widgetStyle({ width, height, x, y, position })}>
-      {src
-        ? <img src={src} alt={alt} loading="lazy" />
-        : <div className="figure-placeholder">缺少图片 src</div>}
+      {src ? (
+        <button
+          type="button"
+          className="figure-zoom-trigger"
+          onClick={() => setZoomed(true)}
+          aria-label={`放大查看：${title}`}
+        >
+          <img src={src} alt={alt} loading="lazy" />
+          <span className="figure-zoom-hint" aria-hidden="true"><ZoomIn size={12} />点击放大</span>
+        </button>
+      ) : <div className="figure-placeholder">缺少图片 src</div>}
       {(caption || label) && (
         <figcaption>
           {label && <span className="figure-label">{label}</span>}
           {caption}
         </figcaption>
       )}
+      {zoomed && <ImageZoom src={src} alt={alt} caption={caption} label={label} onClose={() => setZoomed(false)} />}
     </figure>
   );
 }

package/template/src/model/validate-content.js

@@ -286,6 +286,23 @@ function tokenize(source) {
   return tags;
 }
 
+/** Blank out tag ranges, preserving offsets and newlines, so only text remains. */
+function textRegions(source, tags) {
+  const ranges = tags
+    .map(tag => [tag.start, tag.end])
+    .sort((a, b) => a[0] - b[0]);
+  const pieces = [];
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    if (start < cursor) continue;
+    pieces.push(source.slice(cursor, start));
+    pieces.push(source.slice(start, end).replace(/[^\n]/g, ' '));
+    cursor = end;
+  }
+  pieces.push(source.slice(cursor));
+  return pieces.join('');
+}
+
 function attrsToMap(attrs) {
   const map = {};
   for (const attr of attrs) map[attr.name] = attr;
@@ -421,6 +438,24 @@ export function validateMdxSource(source, options = {}) {
     }
   }
 
+  // MDX evaluates `{ ... }` in prose as a JavaScript expression. Authors often
+  // write data shapes like `{label, value}` in a sentence, which crashes the
+  // page with "label is not defined".
+  const text = textRegions(masked, tags);
+  for (const match of text.matchAll(/\{([^{}]*)\}/g)) {
+    const expression = match[1].trim();
+    if (!expression || expression.startsWith('/*')) continue;
+    if (/^[A-Za-z_$][\w$]*\s*(,[\s\S]*)?$/.test(expression)) {
+      add('warning', 'PROSE_EXPRESSION', `正文中的 {${expression}} 会被 MDX 当作表达式并导致运行时报错；请改成行内代码 \`{${expression}}\``, match.index, expression);
+    }
+  }
+
+  // MDX has no frontmatter support by default: a leading `---` block renders as
+  // a stray rule and text at the top of the page.
+  if (/^---\r?\n[\s\S]*?\r?\n---(\r?\n|$)/.test(source)) {
+    add('warning', 'FRONTMATTER_UNSUPPORTED', '文件以 --- 开头，但 MDX 不解析 frontmatter，它会被渲染成正文；请删除', 0, null);
+  }
+
   const carrier = usedComponents.has('ScrollDocument') ? 'scroll'
     : (usedComponents.has('ExplainPage') || usedComponents.has('ConceptGraph')) ? 'atlas'
       : null;
@@ -541,3 +576,25 @@ export function countBySeverity(diagnostics) {
     return acc;
   }, { error: 0, warning: 0 });
 }
+
+/**
+ * Optional renderers a document actually instantiates.
+ *
+ * Mermaid and KaTeX (plus the ~1.4 MB of woff2 fonts its stylesheet inlines) are
+ * heavy enough that bundling them into a page which never renders a diagram or a
+ * formula dominates both build time and output size. The build reads these flags
+ * and swaps unused renderers for stubs.
+ *
+ * Detection runs on the masked source, so `<Math>` inside a fenced block or an
+ * inline code span does not count as usage.
+ */
+export function detectFeatures(source) {
+  const used = new Set();
+  for (const tag of tokenize(maskIgnored(source))) {
+    if (tag.kind !== 'close') used.add(tag.name);
+  }
+  return {
+    math: used.has('Math') || used.has('MathBlock'),
+    mermaid: used.has('Mermaid'),
+  };
+}

package/template/src/styles/concept-explain.css

@@ -25,8 +25,8 @@
   /* Typography Colors */
   --text-primary: #f8fafc;
   --text-secondary: #cbd5e1;
-  --text-muted: #94a3b8;
-  --text-dim: #64748b;
+  --text-muted: #a7b5c7;
+  --text-dim: #8494a9;
   --text-accent: #38bdf8;
 
   /* Accent & Category Semantic Tones */
@@ -93,9 +93,9 @@
 
   /* Typography Colors */
   --text-primary: #0f172a;
-  --text-secondary: #334155;
-  --text-muted: #64748b;
-  --text-dim: #94a3b8;
+  --text-secondary: #2b3a4f;
+  --text-muted: #4a5a70;
+  --text-dim: #5f6f83;
   --text-accent: #2563eb;
 
   /* Accent & Category Semantic Tones */
@@ -187,14 +187,14 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   outline-offset: 3px;
 }
 
-.global-search { position: relative; display: flex; align-items: center; gap: 7px; min-width: 220px; margin-left: auto; color: var(--text-muted, #94a3b8); }
-.global-search input { width: 100%; border: 1px solid var(--line-subtle, rgba(148,163,184,.24)); border-radius: 8px; background: var(--surface-soft, rgba(15,23,42,.3)); color: inherit; padding: 7px 28px 7px 28px; }
+.global-search { position: relative; display: flex; align-items: center; gap: 7px; min-width: 220px; margin-left: auto; color: var(--text-muted); }
+.global-search input { width: 100%; border: 1px solid var(--border-medium); border-radius: 8px; background: var(--bg-canvas); color: inherit; padding: 7px 28px 7px 28px; }
 .global-search > svg { position: absolute; left: 9px; pointer-events: none; }
 .global-search > button { position: absolute; right: 5px; border: 0; background: transparent; color: inherit; padding: 3px; }
-.global-search-results { position: absolute; z-index: 20; top: calc(100% + 6px); left: 0; right: 0; padding: 5px; border: 1px solid var(--line-subtle, rgba(148,163,184,.24)); border-radius: 10px; background: var(--surface-strong, #111827); box-shadow: 0 12px 30px rgba(0,0,0,.24); }
-.global-search-results button { display: grid; gap: 2px; width: 100%; border: 0; border-radius: 7px; background: transparent; color: var(--text-primary, #e2e8f0); text-align: left; padding: 8px; }
-.global-search-results button:hover { background: rgba(148,163,184,.12); }
-.global-search-results small { color: var(--text-muted, #94a3b8); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.global-search-results { position: absolute; z-index: 20; top: calc(100% + 6px); left: 0; right: 0; padding: 5px; border: 1px solid var(--border-medium); border-radius: 10px; background: var(--bg-surface); box-shadow: var(--shadow-lg); }
+.global-search-results button { display: grid; gap: 2px; width: 100%; border: 0; border-radius: 7px; background: transparent; color: var(--text-primary); text-align: left; padding: 8px; }
+.global-search-results button:hover { background: var(--bg-subtle); }
+.global-search-results small { color: var(--text-muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 
 /* Optional semantic layout primitives */
 .semantic-stack { display: flex; flex-direction: column; }
@@ -1884,7 +1884,7 @@ button.flow-box {
 
 .inline-inspector-grid {
   display: grid;
-  grid-template-columns: repeat(4, minmax(180px, 1fr));
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
   gap: 14px;
 }
 
@@ -2339,31 +2339,31 @@ button.flow-box {
 .semantic-evidence,
 .semantic-invariant,
 .semantic-failure-mode {
-  border: 1px solid var(--line-subtle, rgba(148, 163, 184, .24));
+  border: 1px solid var(--border-subtle);
   border-radius: 12px;
   padding: 12px 14px;
-  background: var(--surface-soft, rgba(15, 23, 42, .28));
+  background: var(--bg-surface);
 }
 
 .semantic-learning-objectives ul { margin: 8px 0 0; padding-left: 20px; }
 .semantic-learning-objectives li { margin: 4px 0; }
 .semantic-key-question { display: flex; align-items: baseline; gap: 10px; border-color: rgba(56, 189, 248, .35); }
-.semantic-key-question strong { color: var(--text-primary, #e2e8f0); }
+.semantic-key-question strong { color: var(--text-primary); }
 .semantic-evidence { display: grid; gap: 7px; border-color: rgba(52, 211, 153, .3); }
-.evidence-command { overflow-x: auto; color: #a7f3d0; }
-.evidence-observes { color: var(--text-secondary, #cbd5e1); }
+.evidence-command { overflow-x: auto; color: var(--text-primary); }
+.evidence-observes { color: var(--text-secondary); }
 .semantic-invariant { border-color: rgba(129, 140, 248, .35); }
 .semantic-invariant > div:last-child { margin-top: 6px; }
 .semantic-failure-mode { border-color: rgba(251, 146, 60, .38); }
 .semantic-failure-mode dl { display: grid; grid-template-columns: auto 1fr; gap: 5px 12px; margin: 8px 0 0; }
-.semantic-failure-mode dt { color: var(--text-muted, #94a3b8); font-size: .8rem; }
-.semantic-failure-mode dd { margin: 0; }
+.semantic-failure-mode dt { color: var(--text-primary); font-size: .82rem; font-weight: 700; }
+.semantic-failure-mode dd { margin: 0; color: var(--text-secondary); }
 .failure-details { margin-top: 10px; }
-.semantic-tradeoff { border: 1px solid rgba(250, 204, 21, .3); border-radius: 12px; padding: 12px 14px; background: var(--surface-soft, rgba(15,23,42,.24)); }
+.semantic-tradeoff { border: 1px solid rgba(250, 204, 21, .3); border-radius: 12px; padding: 12px 14px; background: var(--bg-surface); }
 .tradeoff-options { display: grid; grid-template-columns: repeat(auto-fit, minmax(170px, 1fr)); gap: 10px; margin-top: 8px; }
-.tradeoff-option { display: grid; gap: 4px; padding: 9px; border-radius: 8px; background: rgba(148,163,184,.08); }
-.tradeoff-option span { color: var(--text-secondary, #cbd5e1); font-size: .86rem; }
-.tradeoff-option b { color: var(--text-muted, #94a3b8); font-size: .72rem; margin-right: 5px; }
+.tradeoff-option { display: grid; gap: 4px; padding: 9px; border-radius: 8px; background: var(--bg-subtle); }
+.tradeoff-option span { color: var(--text-secondary); font-size: .86rem; }
+.tradeoff-option b { color: var(--text-primary); font-size: .72rem; margin-right: 5px; }
 
 .semantic-callout {
   padding: 16px 20px;
@@ -2906,7 +2906,7 @@ button.flow-box {
 
 .semantic-callout.has-callout-title {
   display: grid;
-  grid-template-columns: minmax(8rem, 11rem) minmax(0, 1fr);
+  grid-template-columns: minmax(0, 1fr) minmax(0, 2fr);
   gap: 16px;
   align-items: start;
 }
@@ -3176,11 +3176,11 @@ html[data-carrier='scroll'] #root {
   justify-content: space-between;
 }
 
-.continuous-document > .semantic-framework-model,
-.continuous-document > .semantic-model-matrix,
-.continuous-document > .semantic-model-formula,
-.continuous-document > .semantic-model-pyramid,
-.continuous-document > .semantic-model-funnel,
+.continuous-content > .semantic-framework-model,
+.continuous-content > .semantic-model-matrix,
+.continuous-content > .semantic-model-formula,
+.continuous-content > .semantic-model-pyramid,
+.continuous-content > .semantic-model-funnel,
 .continuous-section > .semantic-framework-model,
 .continuous-section > .semantic-model-matrix,
 .continuous-section > .semantic-model-formula,
@@ -3237,6 +3237,13 @@ html[data-carrier='scroll'] #root {
   width: 100%;
 }
 
+/* The drill-down entrance is the primary navigation affordance; give it the
+   full board width so its child cards can form a proper grid instead of being
+   stacked inside one third of a row. */
+.draft-board .drill-down-section {
+  grid-column: 1 / -1;
+}
+
 @media (max-width: 1120px) {
   .continuous-model-pair { grid-template-columns: 1fr; }
   .continuous-model-pair .semantic-model-pyramid,
@@ -3339,29 +3346,44 @@ html[data-carrier='scroll'] #root {
   transition: transform 80ms linear;
 }
 
-/* ---- Table of contents ---- */
+/* ---- Table of contents (sticky sidebar) ---- */
+
+.continuous-content {
+  min-width: 0;
+}
 
 .scroll-toc {
   display: none;
 }
 
-@media (min-width: 1400px) {
-  .scroll-toc {
-    position: fixed;
-    top: 104px;
-    left: max(16px, calc(50% - 560px - 220px));
-    z-index: 30;
+@media (min-width: 1080px) {
+  .continuous-document.has-toc {
+    display: grid;
+    grid-template-columns: 208px minmax(0, 1fr);
+    column-gap: 44px;
+    align-items: start;
+  }
+
+  .continuous-document.has-toc > .scroll-toc {
+    position: sticky;
+    top: 24px;
     display: block;
-    width: 190px;
-    max-height: calc(100vh - 160px);
-    overflow: auto;
-    padding-right: 10px;
-    border-right: 1px solid var(--border-subtle);
+    grid-column: 1;
+    align-self: start;
+    max-height: calc(100vh - 48px);
+    overflow-y: auto;
+    padding-right: 6px;
+  }
+
+  .continuous-document.has-toc > .continuous-content {
+    grid-column: 2;
   }
 }
 
 .scroll-toc-title {
-  margin-bottom: 10px;
+  margin: 0 0 10px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border-subtle);
   color: var(--text-dim);
   font-size: 11px;
   font-weight: 700;
@@ -3373,90 +3395,54 @@ html[data-carrier='scroll'] #root {
   margin: 0;
   padding: 0;
   list-style: none;
+  border-left: 1px solid var(--border-subtle);
   counter-reset: toc;
 }
 
 .scroll-toc-list li {
-  margin: 0 0 2px;
   counter-increment: toc;
 }
 
 .scroll-toc-list a {
-  display: block;
-  padding: 5px 8px 5px 22px;
+  display: grid;
+  grid-template-columns: 24px minmax(0, 1fr);
+  gap: 6px;
+  align-items: baseline;
+  margin-left: -1px;
+  padding: 6px 8px 6px 0;
   border-left: 2px solid transparent;
-  border-radius: var(--radius-1);
   color: var(--text-muted);
   font-size: 12.5px;
-  line-height: 1.4;
+  line-height: 1.45;
   text-decoration: none;
-  position: relative;
-  transition: color 0.15s ease, border-color 0.15s ease, background 0.15s ease;
+  transition: color 0.15s ease, border-color 0.15s ease;
 }
 
 .scroll-toc-list a::before {
   content: counter(toc, decimal-leading-zero);
-  position: absolute;
-  left: 4px;
   color: var(--text-dim);
   font-size: 10px;
   font-variant-numeric: tabular-nums;
+  text-align: center;
+  transition: color 0.15s ease;
 }
 
 .scroll-toc-list a:hover {
   color: var(--text-primary);
-  background: var(--bg-highlight);
-}
-
-.scroll-toc-list li.active a {
-  border-left-color: var(--primary);
-  color: var(--text-primary);
-  font-weight: 600;
-}
-
-/* ---- Section pager ---- */
-
-.scroll-pager {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 12px;
-  margin-top: 8px;
-  padding-top: 16px;
-  border-top: 1px solid var(--border-subtle);
 }
 
-.scroll-pager a {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 10px 12px;
-  border: 1px solid var(--border-medium);
-  border-radius: var(--radius-2);
-  background: var(--bg-surface);
-  text-decoration: none;
-  transition: border-color 0.15s ease, background 0.15s ease;
-}
-
-.scroll-pager a:hover {
-  border-color: var(--border-strong);
-  background: var(--bg-card-hover);
-}
-
-.scroll-pager a span {
-  color: var(--text-dim);
-  font-size: 11px;
-  font-weight: 600;
+.scroll-toc-list a:hover::before {
+  color: var(--text-secondary);
 }
 
-.scroll-pager a strong {
+.scroll-toc-list li.active a {
+  border-left-color: var(--primary);
   color: var(--text-primary);
-  font-size: 13px;
   font-weight: 600;
-  line-height: 1.4;
 }
 
-.scroll-pager .pager-next {
-  text-align: right;
+.scroll-toc-list li.active a::before {
+  color: var(--primary-light);
 }
 
 /* ===========================================================================
@@ -3573,6 +3559,156 @@ html[data-carrier='scroll'] #root {
   background: var(--bg-subtle);
 }
 
+/* Click-to-zoom trigger. The wrapper is a button so the affordance is reachable
+   by keyboard, but it must read as the image itself rather than as chrome. */
+.figure-zoom-trigger {
+  position: relative;
+  display: block;
+  width: 100%;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-2);
+  background: none;
+  line-height: 0;
+  cursor: zoom-in;
+}
+
+.figure-zoom-trigger:focus-visible {
+  outline: 2px solid var(--accent-cyan);
+  outline-offset: 2px;
+}
+
+.figure-zoom-hint {
+  position: absolute;
+  right: 8px;
+  bottom: 8px;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 3px 8px;
+  border: 1px solid var(--border-medium);
+  border-radius: var(--radius-2);
+  background: color-mix(in srgb, var(--bg-surface) 88%, transparent);
+  color: var(--text-secondary);
+  font-size: 11px;
+  line-height: 1.5;
+  opacity: 0.7;
+  transition: opacity 0.15s ease, color 0.15s ease;
+}
+
+.figure-zoom-trigger:hover .figure-zoom-hint,
+.figure-zoom-trigger:focus-visible .figure-zoom-hint {
+  color: var(--text-primary);
+  opacity: 1;
+}
+
+/* ---- Image zoom overlay ---- */
+
+.image-zoom-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: grid;
+  place-items: center;
+  padding: 28px;
+  background: color-mix(in srgb, #05080f 84%, transparent);
+}
+
+.image-zoom-stage {
+  display: grid;
+  place-items: center;
+  max-width: 100%;
+  max-height: 100%;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: none;
+}
+
+.image-zoom-stage.is-dragging { cursor: grabbing; }
+
+.image-zoom-stage img {
+  display: block;
+  width: auto;
+  height: auto;
+  max-width: min(94vw, 1800px);
+  max-height: 84vh;
+  border-radius: var(--radius-2);
+  background: var(--bg-surface);
+  box-shadow: 0 24px 60px -22px rgba(0, 0, 0, 0.75);
+  transition: transform 0.12s ease-out;
+  will-change: transform;
+  user-select: none;
+}
+
+.image-zoom-stage.is-dragging img { transition: none; }
+
+.image-zoom-caption {
+  position: absolute;
+  top: 18px;
+  left: 50%;
+  max-width: min(90vw, 900px);
+  transform: translateX(-50%);
+  color: var(--text-secondary);
+  font-size: 12.5px;
+  line-height: 1.6;
+  text-align: center;
+}
+
+.image-zoom-caption b {
+  margin-right: 8px;
+  color: var(--text-accent);
+}
+
+.image-zoom-toolbar {
+  position: absolute;
+  bottom: 22px;
+  left: 50%;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 5px;
+  transform: translateX(-50%);
+  border: 1px solid var(--border-medium);
+  border-radius: var(--radius-3);
+  background: var(--bg-surface);
+  box-shadow: var(--shadow-pop);
+  color: var(--text-secondary);
+}
+
+.image-zoom-toolbar button {
+  display: grid;
+  place-items: center;
+  width: 30px;
+  height: 30px;
+  border-radius: var(--radius-1);
+  color: inherit;
+  font-size: 14px;
+}
+
+.image-zoom-toolbar button:hover {
+  background: var(--bg-card-hover);
+  color: var(--text-primary);
+}
+
+.image-zoom-toolbar span {
+  min-width: 46px;
+  text-align: center;
+  font-size: 12px;
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .image-zoom-stage img { transition: none; }
+}
+
+@media (max-width: 760px) {
+  .image-zoom-overlay { padding: 12px; }
+  .image-zoom-stage img { max-height: 74vh; }
+  .image-zoom-caption { top: 10px; font-size: 12px; }
+  .image-zoom-hint { opacity: 0.9; }
+}
+
 .semantic-figure figcaption {
   margin-top: 10px;
   color: var(--text-secondary);

package/template/vite.config.js

@@ -22,13 +22,21 @@ const MIME_TYPES = {
  * into base64 data URIs at build time. Keeps the single-file HTML self-contained
  * and offline-openable without a runtime asset loader. Remote (http/data) and
  * absolute paths are left untouched.
+ *
+ * `--link-assets` (the `__ATLAS_INLINE_ASSETS__` define) turns this off so figures
+ * stay relative links. That keeps the output small at the cost of the page no
+ * longer being self-contained: the HTML must sit beside the MDX's `assets/` dir.
  */
 function inlineMdxAssets() {
+  const state = { enabled: true };
   return {
     name: 'concept-atlas-inline-assets',
     enforce: 'pre',
+    configResolved(config) {
+      state.enabled = (config.define || {}).__ATLAS_INLINE_ASSETS__ !== 'false';
+    },
     transform(code, id) {
-      if (!id.endsWith('.mdx')) return null;
+      if (!state.enabled || !id.endsWith('.mdx')) return null;
       const dir = path.dirname(id.split('?')[0]);
       let changed = false;
       const output = code.replace(/(<[A-Za-z][\w.]*\b[^>]*?\bsrc=)(["'])([^"']+)\2/g, (match, prefix, quote, src) => {
@@ -44,6 +52,73 @@ function inlineMdxAssets() {
   };
 }
 
+/**
+ * Swaps optional renderers for stubs when the document never uses them.
+ *
+ * Mermaid and KaTeX are the two dependencies whose transform cost and payload
+ * dominate a build: KaTeX alone contributes ~60 woff2 files that
+ * vite-plugin-singlefile base64-inlines into every page (~1.4 MB), and Mermaid
+ * is a large share of the JS bundle. A page with no <Mermaid> or <Math> should
+ * not pay for either.
+ *
+ * The CLI computes `detectFeatures(source)` and passes the result as the
+ * `__ATLAS_FEATURES__` define; without it (e.g. the repository's own build) every
+ * feature stays enabled and behaviour is unchanged.
+ */
+const OPTIONAL_FEATURES = {
+  mermaid: { feature: 'mermaid', stub: 'mermaid' },
+  katex: { feature: 'math', stub: 'katex' },
+  'katex/dist/katex.min.css': { feature: 'math', stub: 'katex-css' },
+};
+
+const FEATURE_STUBS = {
+  mermaid: `const mermaid = {
+  initialize() {},
+  render() {
+    throw new Error('Mermaid is not bundled in this build: the document has no <Mermaid>.');
+  },
+};
+export default mermaid;
+`,
+  katex: `const katex = {
+  renderToString() {
+    throw new Error('KaTeX is not bundled in this build: the document has no <Math>.');
+  },
+};
+export default katex;
+`,
+  // The stylesheet stub is intentionally empty: dropping it is what removes the
+  // base64-inlined KaTeX woff2 payload from the page.
+  'katex-css': '',
+};
+
+function optionalFeatures() {
+  let enabled = { math: true, mermaid: true };
+  return {
+    name: 'concept-atlas-optional-features',
+    enforce: 'pre',
+    configResolved(config) {
+      const raw = config.define && config.define.__ATLAS_FEATURES__;
+      if (typeof raw !== 'string') return;
+      try {
+        enabled = { math: true, mermaid: true, ...JSON.parse(raw) };
+      } catch {
+        enabled = { math: true, mermaid: true };
+      }
+    },
+    resolveId(source) {
+      const entry = OPTIONAL_FEATURES[source];
+      if (!entry || enabled[entry.feature] !== false) return null;
+      return `\0atlas-stub:${entry.stub}`;
+    },
+    load(id) {
+      if (!id.startsWith('\0atlas-stub:')) return null;
+      const stub = id.slice('\0atlas-stub:'.length);
+      return Object.hasOwn(FEATURE_STUBS, stub) ? FEATURE_STUBS[stub] : null;
+    },
+  };
+}
+
 export default defineConfig({
   plugins: [
     inlineMdxAssets(),
@@ -54,6 +129,7 @@ export default defineConfig({
       }),
     },
     react(),
+    optionalFeatures(),
     viteSingleFile(),
   ],
   build: {