concept-atlas-dense-explain 1.2.0 → 2.0.0

package/README.md

@@ -35,14 +35,17 @@ Mermaid loads from a CDN at runtime by default (fast builds, needs network);
 `--inline-mermaid` bakes it into the HTML for a fully offline single file, and
 `--mermaid-cdn` overrides the CDN URL. Appearance defaults can be baked with
 `--skin`, `--default-mode` and `--style`; readers can still switch in the UI.
+Local figures link by default (small HTML, ship `assets/` beside the output);
+`--inline-assets` bakes them in as base64 for a self-contained file, and a
+per-figure `inline={true|false}` overrides that choice.
 
 Run `npx concept-atlas-dense-explain help` for the full flag list.
 
 ## Links
 
 - Repository: https://github.com/wurenrumian/concept-atlas
-- Framework guide: [`docs/FRAMEWORK.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/FRAMEWORK.md)
-- Usage recipes: [`docs/USAGE.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/USAGE.md)
+- Framework guide: [`docs/FRAMEWORK.md`](https://github.com/wurenrumian/concept-atlas/blob/master/docs/FRAMEWORK.md)
+- Usage recipes: [`docs/USAGE.md`](https://github.com/wurenrumian/concept-atlas/blob/master/docs/USAGE.md)
 
 ## License
 

package/bin/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { access, constants, copyFile, cp, mkdir, readFile, rm, rename, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { build } from 'vite';
 import { fileURLToPath } from 'node:url';
@@ -14,7 +14,7 @@ let buildCounter = 0;
 
 function usage() {
   console.log('Usage:');
-  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [-o output.html|dir] [--force] [--concurrency N] [--link-assets] [--inline-mermaid] [--mermaid-cdn <url>] [--json] [--no-validate]');
+  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [-o output.html|dir] [--force] [--concurrency N] [--inline-assets] [--inline-mermaid] [--mermaid-cdn <url>] [--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]');
@@ -22,7 +22,7 @@ function usage() {
   console.log('');
   console.log('  --help shows this text; --version prints the package version.');
   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.');
+  console.log('  Figures are kept as relative links by default (small HTML; ship the assets/ dir beside it). --inline-assets bakes every local image into the HTML as base64 instead; a per-tag inline={true|false} on <Figure> overrides that for one image. --link-assets is kept as an explicit alias for the default.');
   console.log('  Mermaid diagrams load from a CDN at runtime by default (fast builds, needs network); --inline-mermaid bakes Mermaid into the HTML for a fully offline single file; --mermaid-cdn overrides the CDN URL.');
   console.log(`  --skin bakes a default palette (${SKINS.map(skin => skin.id).join(', ')}); --default-mode bakes a default dark/light mode; --style bakes a default component style (${COMPONENT_STYLES.map(style => style.id).join(', ')}). Readers can still switch in the UI.`);
 }
@@ -31,6 +31,11 @@ async function exists(filePath) {
   try { await access(filePath, constants.F_OK); return true; } catch { return false; }
 }
 
+/** Byte size of an asset, or null when it does not exist. */
+function assetByteSize(filePath) {
+  try { return statSync(filePath).size; } catch { return null; }
+}
+
 function flagValue(flags, names) {
   for (const name of names) {
     const index = flags.indexOf(name);
@@ -46,7 +51,7 @@ function fail(message) {
 }
 
 const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style', '--mermaid-cdn']);
-const BOOLEAN_FLAGS = new Set(['--force', '--json', '--strict', '--no-validate', '--link-assets', '--inline-mermaid', '--help', '-h', '--version', '-v']);
+const BOOLEAN_FLAGS = new Set(['--force', '--json', '--strict', '--no-validate', '--link-assets', '--inline-assets', '--inline-mermaid', '--help', '-h', '--version', '-v']);
 const COMMAND_NAMES = ['help', 'create', 'new', 'render', 'validate', 'guide'];
 
 /** Splits argv into flags, flag values and positional arguments. */
@@ -252,6 +257,10 @@ 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 inlineAssets = parsed.flags.has('--inline-assets');
+if (linkAssets && inlineAssets) {
+  fail('--link-assets and --inline-assets are mutually exclusive (linking is the default).');
+}
 const inlineMermaid = parsed.flags.has('--inline-mermaid');
 const mermaidCdn = parsed.values.get('--mermaid-cdn') || null;
 const modeFlag = parsed.values.get('--mode') || null;
@@ -285,7 +294,9 @@ if (command === 'validate') {
     filePath: target,
     mode: modeFlag,
     strict,
+    inlineAssets,
     assetExists: spec => existsSync(path.resolve(path.dirname(target), spec)),
+    assetSize: spec => assetByteSize(path.resolve(path.dirname(target), spec)),
   }, { json });
   process.exit(countBySeverity(result.diagnostics).error ? 1 : 0);
 }
@@ -326,7 +337,9 @@ const validations = sources.map((source, index) => printDiagnostics(source, {
   filePath: inputs[index],
   mode: modeFlag,
   strict,
+  inlineAssets,
   assetExists: spec => existsSync(path.resolve(path.dirname(inputs[index]), spec)),
+  assetSize: spec => assetByteSize(path.resolve(path.dirname(inputs[index]), spec)),
 }, json
   ? { json: false, quiet: true }
   : { json: false, label: multi ? inputs[index] : null }));
@@ -350,10 +363,13 @@ const jobs = inputs.map((input, index) => {
     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)} 内，相对图片路径会失效。`);
+  // Figures link by default. If the HTML is written outside the MDX's directory
+  // its relative image paths no longer resolve, so warn unless --inline-assets
+  // bakes them in.
+  if (!inlineAssets && path.resolve(path.dirname(outputs[index])) !== path.resolve(path.dirname(input))) {
+    console.error(`警告：默认外链图片，但 ${outputs[index]} 不在 ${path.dirname(input)} 内，相对图片路径会失效；请用 --inline-assets，或把 assets/ 一并放到输出目录。`);
   }
-  return { input, output: outputs[index], mode, title: extractPageTitle(sources[index]), features: detectFeatures(sources[index]), linkAssets };
+  return { input, output: outputs[index], mode, title: extractPageTitle(sources[index]), features: detectFeatures(sources[index]), inlineAssets };
 });
 
 const limit = clampConcurrency(parsed.values.get('--concurrency'), jobs.length);
@@ -369,7 +385,7 @@ if (failures.length) {
 }
 
 async function buildOne(job) {
-  const { input, output, mode, title, features, linkAssets: link } = job;
+  const { input, output, mode, title, features, inlineAssets: inline } = 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
@@ -378,7 +394,8 @@ async function buildOne(job) {
   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';
+  // 'false' is the default (link); only --inline-assets sets 'true'.
+  define.__ATLAS_INLINE_ASSETS__ = inline ? 'true' : 'false';
   if (title) define.__ATLAS_PAGE_TITLE__ = JSON.stringify(title);
   if (skinFlag) define.__ATLAS_DEFAULT_SKIN__ = JSON.stringify(skinFlag);
   if (defaultModeFlag) define.__ATLAS_DEFAULT_MODE__ = JSON.stringify(defaultModeFlag);
@@ -424,7 +441,7 @@ async function buildOne(job) {
       }
       if (hasBackup) await rm(backup, { force: true });
     }
-    console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
+    console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${inline ? '  [figures inlined]' : '  [figures linked]'}`);
     return { ok: true, input, output };
   } catch (error) {
     return { ok: false, input, output, error };

package/package.json

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

package/packaged-skill/SKILL.md

@@ -32,7 +32,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
    npx concept-atlas-dense-explain validate <file>.mdx --json
    ```
    Diagnostics are `CODE line:column message`. Fix all `error`s and re-run; address warnings when cheap.
-6. Compile: `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [--inline-mermaid] [--mermaid-cdn <url>]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build (`--no-validate` forces a knowingly broken build). Mermaid loads from a CDN at runtime by default (needs network); pass `--inline-mermaid` for a fully offline single file.
+6. Compile: `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [--mermaid-cdn <url>]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build (`--no-validate` forces a knowingly broken build). **Mermaid stays on its runtime CDN by default — do not pass `--inline-mermaid` on your own.** Only add `--inline-mermaid` when the user explicitly asks for a fully offline single file, since it bloats the HTML with the whole Mermaid bundle.
 7. **Appearance (optional)**: pages ship a reader-facing appearance menu — palette (`aurora` indigo, `ember` gold, `verdant` forest, `sakura` pink-plum, `noir` ink), a dark/light toggle, and a component style pack (`manuscript` editorial marginalia, `classic` boxed cards, `shadcn` hairline-bordered minimal UI, `elastic` bordered observability panels). The shipped default is aurora × manuscript × light; choices persist in localStorage across both carriers. Bake different compile-time defaults with `--skin ember --default-mode dark --style classic` (or `CONCEPT_ATLAS_SKIN` / `CONCEPT_ATLAS_DEFAULT_MODE` / `CONCEPT_ATLAS_STYLE` on the repo build); `--default-mode` honors `dark`/`light` and resolves `system` to the carrier default (`light`). Bake a default only when the user asks for one — content MDX never sets appearance.
 8. 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; everything validates first, then builds in parallel). Builds bundle only the heavy renderers the content uses: no `<Math>` skips KaTeX's ~1.4MB inlined fonts, and Mermaid stays on a CDN. Never add dummy `<Math>`/`<Mermaid>` nodes to "enable" them.
 9. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
@@ -52,7 +52,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 - Information models: `Flow`, `Timeline`, `Compare`, `DecisionMatrix`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`
 - Data and behaviour: `DataTable`, `Metric`, `StateMachine`, `DecisionTree`, `FeedbackLoop`, `CodeDiff`
 - Reading and layout: `Insight`, `Callout`, `Details`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`, `ScrollPair`, `ScrollToc`
-- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `Figure` (alias `Image`), `Cite`, `References`
+- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `Figure` (alias `Image`), `FigureRef`, `Cite`, `References`
 
 ## Authoring rules
 
@@ -67,20 +67,22 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 - **Learning loop**: `WorkedExample` holds `Step` children; give each step a `reason` (the justification) so it teaches reasoning, not just the result. `Quiz question answer` reveals the answer on click with children as the explanation. `KeyTakeaways items={[...]}` closes a section.
 - **Provenance**: `Source kind="spec|rfc|implementation|experiment|experience" label href` marks one claim's origin inline; `Confidence level="high|medium|low" basis` wraps a claim with how strongly it is established; `Term name` (or children as the definition) gives an inline hover definition.
 - **Data and behaviour**: `DataTable headers={[...]} rows={[[...]]}` is the neutral table (no comparative stance). `Metric label value unit delta trend note` is one headline number — compose several with `Grid`/`ScrollGrid`. `StateMachine states={[{id,label,terminal}]} transitions={[{from,to,event,guard}]}` expresses cycles and guards. `DecisionTree branches={[{condition,outcome,tone,branches}]}` nests branches. `FeedbackLoop type="reinforcing|balancing" nodes={[{label,description}]}` closes a loop. `CodeDiff before after language` shows a change.
-- **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 warns (`ASSET_MISSING`) and shows a placeholder. Readers can click a figure to open it full-screen (zoom, drag, `Esc`) — mention it for diagram-heavy pages.
-- **Figure size & cost**: inlining images is what makes a screenshot-heavy page large; a page with no heavy renderers otherwise lands near 250KB. When the user cares, compile with `--link-assets` to keep images as relative links (measured 1.51MB → 270KB); the output must then sit beside the MDX's `assets/`, and the CLI warns if `-o` points elsewhere — tell the user that trade-off instead of choosing silently.
+- **Figure**: a relative `src` (`./assets/diagram.png`) stays a relative link by default; compile with `--inline-assets` to bake every local image in as base64, or set `inline={true}` / `inline={false}` on one figure to override (precedence: per-figure prop > global flag > link). `http(s)` URLs stay links and warn (`ASSET_REMOTE`). Always set `alt`; a missing relative file warns (`ASSET_MISSING`) and shows a placeholder. Readers can click a figure to open it full-screen (zoom, drag, `Esc`) — mention it for diagram-heavy pages.
+- **Figure numbering**: give a figure an `id` and reference it with `<FigureRef id="..." />` to render "图 N". Numbering follows document order (per node in `atlas`, whole document in `scroll`) and reflows automatically, so never hand-write "图 1"; an explicit `label` still wins. A ref with no matching `id` warns (`FIGURE_REF_UNRESOLVED`).
+- **Figure size & cost**: linking keeps the HTML small but requires the output to sit beside the MDX's `assets/` (the CLI warns when `-o` points elsewhere). Inlining is what makes a screenshot-heavy page large (a page with no heavy renderers otherwise lands near 250KB), and an inlined asset over 512KB warns (`ASSET_LARGE`). Decide the trade-off with the user 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.
 
 ## Validation diagnostics
 
-`validate` and the build print `CODE line:column message`. Fix these `error`s before building: `UNKNOWN_COMPONENT`, `CARRIER_MISSING`, `CARRIER_CONFLICT`, `CARRIER_MODE_MISMATCH`, `NODE_MISSING_ID`, `DUPLICATE_NODE_ID`, `NODE_MISSING_TITLE`, `MISSING_PARENT`, `GRAPH_ROOT_UNRESOLVED`, `REF_MISSING_ID`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_KIND`, `MECHANISM_KIND_UNVERIFIED`, `FAILURE_KIND_UNSTRUCTURED`, `FAILURE_MODE_EMPTY`, `UNKNOWN_RELATION_TYPE`, `RELATION_MISSING_LABEL`, `RELATION_SELF`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `PROSE_EXPRESSION`, `FRONTMATTER_UNSUPPORTED`, `GRAPH_MISSING_ROOT`, `FIGURE_MISSING_SRC`, `ASSET_MISSING`, `REF_SELF`; `NO_ROOT_LEVEL`, `MULTIPLE_ROOT_LEVEL`, `MECHANISM_KIND_UNVERIFIED` and `FAILURE_KIND_UNSTRUCTURED` are warnings that `--strict` promotes to errors.
+`validate` and the build print `CODE line:column message`. Fix these `error`s before building: `UNKNOWN_COMPONENT`, `CARRIER_MISSING`, `CARRIER_CONFLICT`, `CARRIER_MODE_MISMATCH`, `NODE_MISSING_ID`, `DUPLICATE_NODE_ID`, `NODE_MISSING_TITLE`, `MISSING_PARENT`, `GRAPH_ROOT_UNRESOLVED`, `REF_MISSING_ID`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_KIND`, `MECHANISM_KIND_UNVERIFIED`, `FAILURE_KIND_UNSTRUCTURED`, `FAILURE_MODE_EMPTY`, `UNKNOWN_RELATION_TYPE`, `RELATION_MISSING_LABEL`, `RELATION_SELF`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `PROSE_EXPRESSION`, `FRONTMATTER_UNSUPPORTED`, `GRAPH_MISSING_ROOT`, `FIGURE_MISSING_SRC`, `ASSET_MISSING`, `ASSET_REMOTE`, `ASSET_LARGE`, `FIGURE_REF_UNRESOLVED`, `FIGURE_REF_MISSING_ID`, `FIGURE_DUPLICATE_ID`, `REF_SELF`; `NO_ROOT_LEVEL`, `MULTIPLE_ROOT_LEVEL`, `MECHANISM_KIND_UNVERIFIED` and `FAILURE_KIND_UNSTRUCTURED` are warnings that `--strict` promotes to errors.
 
 ## Before you report
 
 - All `error` diagnostics resolved (or `--no-validate` explicitly justified).
 - All `ConceptRef`, `Relation` endpoints, and `ConceptGraph root` point at existing node ids.
 - Every node has `title` + `summary`; every `Relation` has a `label`.
+- You left Mermaid on its CDN default and did not pass `--inline-mermaid` unless the user explicitly asked for a fully offline single file.
 - The HTML file exists at the reported path.
 
 If `npx` cannot reach the registry, report the blocker. Never copy implementation files into the skill directory.

package/packaged-skill/references/atlas-guide.mdx

@@ -132,10 +132,11 @@
       <Chart title="留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]}]} />
     </ConceptNode>
 
-    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定，构建时把本地图片内联进单文件。">
-      <Definition>相对路径的图片会在构建时转成 base64 内联，远程 URL 保持不变；label 提供“图 1”这样的编号。</Definition>
-      <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
-      <Boundary>大图会显著增大单文件 HTML；截图类内容建议控制尺寸。</Boundary>
+    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定；默认外链，按需内联。">
+      <Definition>相对路径的图片默认保持外链，构建时用 --inline-assets 可全部内联，单张图也可用 `inline={true}` 或 `inline={false}` 覆盖；远程 URL 保持不变。给图一个 id，正文就能用 FigureRef 自动引用“图 N”。</Definition>
+      <Figure id="zoom-scale" src="./assets/sample-diagram.svg" alt="概念缩放示意" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
+      <Example title="自动图号">正文写“见 <FigureRef id="zoom-scale" />”，编号会随插图自动重排，不必手写“图 1”。</Example>
+      <Boundary>内联大图会显著增大 HTML；截图类内容建议控制尺寸，或对单张图设 `inline={false}`。</Boundary>
     </ConceptNode>
 
     <ConceptNode id="code-demo" title="CodeBlock：把命令、配置或伪代码放进正文" level="L2" parent="extension-family" summary="与绑定节点的 Implementation 不同，CodeBlock 可以出现在任何位置，并支持标题、题注、换行和行号。">

package/packaged-skill/references/scroll-guide.mdx

@@ -102,8 +102,8 @@ npm run dev`}</CodeBlock>
   </ScrollSection>
 
   <ScrollSection title="补充配图与出处">
-    <ScrollProse>配图和引用让讲解从断言变成可追溯的论述<Cite id="tufte1983" />。相对路径的图片会在构建时内联，输出仍是可离线打开的单文件。</ScrollProse>
-    <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
+    <ScrollProse>配图和引用让讲解从断言变成可追溯的论述<Cite id="tufte1983" />。图片默认保持外链（`--inline-assets` 可全部内联），给图一个 id 后正文可用 <FigureRef id="zoom-scale" /> 自动引用编号。</ScrollProse>
+    <Figure id="zoom-scale" src="./assets/sample-diagram.svg" alt="概念缩放示意" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
     <ScrollGrid columns="2">
       <DecisionMatrix title="需要确认" headers={['变量','检查']} rows={[['新体验','是否改善核心任务'],['旧体验','能否满足需求'],['替换成本','迁移是否可接受']]} />
       <Compare items={[{label:'连续阅读',rows:['信息密度','适用场景'],values:['高','按章节论证']},{label:'概念图谱',rows:['信息密度','适用场景'],values:['中','概念下钻']}]} />

package/template/references/atlas-guide.mdx

@@ -132,10 +132,11 @@
       <Chart title="留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]}]} />
     </ConceptNode>
 
-    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定，构建时把本地图片内联进单文件。">
-      <Definition>相对路径的图片会在构建时转成 base64 内联，远程 URL 保持不变；label 提供“图 1”这样的编号。</Definition>
-      <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
-      <Boundary>大图会显著增大单文件 HTML；截图类内容建议控制尺寸。</Boundary>
+    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定；默认外链，按需内联。">
+      <Definition>相对路径的图片默认保持外链，构建时用 --inline-assets 可全部内联，单张图也可用 `inline={true}` 或 `inline={false}` 覆盖；远程 URL 保持不变。给图一个 id，正文就能用 FigureRef 自动引用“图 N”。</Definition>
+      <Figure id="zoom-scale" src="./assets/sample-diagram.svg" alt="概念缩放示意" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
+      <Example title="自动图号">正文写“见 <FigureRef id="zoom-scale" />”，编号会随插图自动重排，不必手写“图 1”。</Example>
+      <Boundary>内联大图会显著增大 HTML；截图类内容建议控制尺寸，或对单张图设 `inline={false}`。</Boundary>
     </ConceptNode>
 
     <ConceptNode id="code-demo" title="CodeBlock：把命令、配置或伪代码放进正文" level="L2" parent="extension-family" summary="与绑定节点的 Implementation 不同，CodeBlock 可以出现在任何位置，并支持标题、题注、换行和行号。">

package/template/references/scroll-guide.mdx

@@ -102,8 +102,8 @@ npm run dev`}</CodeBlock>
   </ScrollSection>
 
   <ScrollSection title="补充配图与出处">
-    <ScrollProse>配图和引用让讲解从断言变成可追溯的论述<Cite id="tufte1983" />。相对路径的图片会在构建时内联，输出仍是可离线打开的单文件。</ScrollProse>
-    <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
+    <ScrollProse>配图和引用让讲解从断言变成可追溯的论述<Cite id="tufte1983" />。图片默认保持外链（`--inline-assets` 可全部内联），给图一个 id 后正文可用 <FigureRef id="zoom-scale" /> 自动引用编号。</ScrollProse>
+    <Figure id="zoom-scale" src="./assets/sample-diagram.svg" alt="概念缩放示意" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
     <ScrollGrid columns="2">
       <DecisionMatrix title="需要确认" headers={['变量','检查']} rows={[['新体验','是否改善核心任务'],['旧体验','能否满足需求'],['替换成本','迁移是否可接受']]} />
       <Compare items={[{label:'连续阅读',rows:['信息密度','适用场景'],values:['高','按章节论证']},{label:'概念图谱',rows:['信息密度','适用场景'],values:['中','概念下钻']}]} />

package/template/src/app/App.jsx

@@ -44,7 +44,6 @@ export function App({ mdxContent, initialData }) {
   const [currentNodeId, setCurrentNodeId] = useState(
     () => initialHashNode || graph.meta.rootId || '',
   );
-  const [selectedLevel, setSelectedLevel] = useState(null);
   const [nav, setNav] = useState(() => ({
     entries: (initialHashNode ? [initialHashNode] : [graph.meta.rootId]).filter(Boolean),
     index: 0,
@@ -239,8 +238,6 @@ export function App({ mdxContent, initialData }) {
             currentNodeId={currentNodeId}
             onSelectNode={navigateToNode}
             onSwitchView={setCurrentView}
-            selectedLevel={selectedLevel}
-            onSelectLevel={setSelectedLevel}
           />
         ) : (
           <RelationGraph

package/template/src/components/FigureScope.jsx

@@ -0,0 +1,17 @@
+import React from 'react';
+
+/**
+ * Numbering scope for figures. `App`'s atlas view provides the current node id
+ * so each node numbers its own figures; the scroll carrier keeps the default
+ * `document` scope so the whole article shares one sequence. Kept out of the
+ * component barrel on purpose: it is renderer plumbing, not an MDX component.
+ */
+export const FigureScope = React.createContext('document');
+
+export function FigureScopeProvider({ scope, children }) {
+  return <FigureScope.Provider value={scope || 'document'}>{children}</FigureScope.Provider>;
+}
+
+export function useFigureScope() {
+  return React.useContext(FigureScope);
+}

package/template/src/components/MDXComponents.jsx

@@ -5,6 +5,8 @@ import katex from 'katex';
 import { ZoomIn } from 'lucide-react';
 import 'katex/dist/katex.min.css';
 import { registerReferences, subscribeReferences, getReferenceIndex } from '../model/citations.js';
+import { registerFigure, subscribeFigures, getFigureNumber } from '../model/figures.js';
+import { useFigureScope } from './FigureScope.jsx';
 
 // Mermaid reads the active skin/mode from CSS variables so diagrams follow
 // the current appearance. A MutationObserver re-renders charts when the
@@ -1568,12 +1570,28 @@ function ImageZoom({ src, alt, caption, label, onClose }) {
   );
 }
 
-export function Figure({ src, alt = '', caption, label, width = 'auto', height = 'auto', x = 0, y = 0, position = 'flow' }) {
+export function Figure({ id, src, alt = '', caption, label, inline, width = 'auto', height = 'auto', x = 0, y = 0, position = 'flow' }) {
+  const scope = useFigureScope();
+  // `inline` is a build-time hint consumed by vite's asset plugin; binding it
+  // here keeps it out of the DOM and documents that the component accepts it.
+  void inline;
+  const number = React.useSyncExternalStore(
+    subscribeFigures,
+    () => getFigureNumber(scope, id),
+    () => getFigureNumber(scope, id),
+  );
+  React.useEffect(() => { registerFigure(scope, id); }, [scope, id]);
   const [zoomed, setZoomed] = React.useState(false);
   const title = alt || caption || '图片';
+  // An explicit `label` wins; otherwise a named figure numbers itself.
+  const displayLabel = label || (id && number ? `图 ${number}` : undefined);
 
   return (
-    <figure className={`semantic-figure ${widgetClass(position)}`} style={widgetStyle({ width, height, x, y, position })}>
+    <figure
+      id={id ? `fig-${id}` : undefined}
+      className={`semantic-figure ${widgetClass(position)}`}
+      style={widgetStyle({ width, height, x, y, position })}
+    >
       {src ? (
         <button
           type="button"
@@ -1585,19 +1603,38 @@ export function Figure({ src, alt = '', caption, label, width = 'auto', height =
           <span className="figure-zoom-hint" aria-hidden="true"><ZoomIn size={12} />点击放大</span>
         </button>
       ) : <div className="figure-placeholder">缺少图片 src</div>}
-      {(caption || label) && (
+      {(caption || displayLabel) && (
         <figcaption>
-          {label && <span className="figure-label">{label}</span>}
+          {displayLabel && <span className="figure-label">{displayLabel}</span>}
           {caption}
         </figcaption>
       )}
-      {zoomed && <ImageZoom src={src} alt={alt} caption={caption} label={label} onClose={() => setZoomed(false)} />}
+      {zoomed && <ImageZoom src={src} alt={alt} caption={caption} label={displayLabel} onClose={() => setZoomed(false)} />}
     </figure>
   );
 }
 Figure.displayName = 'Figure';
 export const Image = Figure;
 
+/**
+ * In-text reference to a numbered figure. `<Figure id="arch" />` numbers itself
+ * in document order and `<FigureRef id="arch" />` renders "图 N", so inserting a
+ * figure never requires renumbering the prose by hand. Links to the figure.
+ */
+export function FigureRef({ id, children }) {
+  const scope = useFigureScope();
+  const number = React.useSyncExternalStore(
+    subscribeFigures,
+    () => getFigureNumber(scope, id),
+    () => getFigureNumber(scope, id),
+  );
+  const text = children ?? (number ? `图 ${number}` : '图 ?');
+  return id
+    ? <a className="semantic-figure-ref" href={`#fig-${id}`}>{text}</a>
+    : <span className="semantic-figure-ref" data-missing="true">{text}</span>;
+}
+FigureRef.displayName = 'FigureRef';
+
 // Citations -----------------------------------------------------------------
 
 export function Cite({ id, children }) {

package/template/src/model/figures.js

@@ -0,0 +1,61 @@
+/**
+ * Figure numbering registry shared by <Figure> and <FigureRef>.
+ *
+ * Numbers are assigned per *scope*: a scroll document numbers its figures in
+ * document order, while an atlas node numbers only the figures it shows. The
+ * <FigureScope> context supplies that key, so browsing from one node to another
+ * does not leak a running count between them. Registration is idempotent, so a
+ * figure that re-renders (or remounts under React StrictMode) keeps its number.
+ *
+ * The store is module-level for the same reason as citations.js: a <FigureRef>
+ * may appear before the <Figure> it points at, so the reference subscribes and
+ * resolves once the target registers.
+ */
+const scopes = new Map();
+let version = 0;
+const listeners = new Set();
+
+function emit() {
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+function scopeKey(scope) {
+  return scope || 'document';
+}
+
+/** Registers `id` at the next free position in `scope` (no-op if already there). */
+export function registerFigure(scope, id) {
+  if (!id) return;
+  const key = scopeKey(scope);
+  const order = scopes.get(key) || [];
+  if (order.includes(id)) return;
+  order.push(id);
+  scopes.set(key, order);
+  emit();
+}
+
+/** Clears one scope, or every scope when called without arguments. */
+export function resetFigures(scope) {
+  if (scope === undefined) scopes.clear();
+  else scopes.delete(scopeKey(scope));
+  emit();
+}
+
+export function subscribeFigures(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function getFiguresVersion() {
+  return version;
+}
+
+/** 1-based document position of `id` in `scope`, or null when unregistered. */
+export function getFigureNumber(scope, id) {
+  if (!id) return null;
+  const order = scopes.get(scopeKey(scope));
+  if (!order) return null;
+  const index = order.indexOf(id);
+  return index < 0 ? null : index + 1;
+}

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

@@ -87,6 +87,7 @@ export const KNOWN_COMPONENTS = [
   'Chart',
   'Figure',
   'Image',
+  'FigureRef',
   'Cite',
   'References',
 ];
@@ -101,6 +102,9 @@ export const RELATION_TYPE_SET = new Set(RELATION_TYPE_NAMES);
 export const LEVEL_NAMES = Object.keys(LEVEL_DEFS);
 export const LEVEL_SET = new Set(LEVEL_NAMES);
 
+/** Inlined images above this size are reported: base64 inflates the HTML ~33%. */
+export const LARGE_ASSET_BYTES = 512 * 1024;
+
 /** Props that must be arrays, mapped to the component that owns them. */
 export const ARRAY_PROPS = {
   Flow: ['steps'],
@@ -358,10 +362,12 @@ function attrValue(map, name) {
  * @param {'atlas'|'scroll'|null} [options.mode] Expected carrier
  * @param {boolean} [options.strict] Promote structural warnings to errors
  * @param {(file:string)=>boolean} [options.assetExists] Asset existence probe
+ * @param {(file:string)=>number|null} [options.assetSize] Asset size probe (bytes)
+ * @param {boolean} [options.inlineAssets] Whether the build inlines local images
  * @returns {{diagnostics:object[], stats:object, carrier:string|null}}
  */
 export function validateMdxSource(source, options = {}) {
-  const { filePath = null, mode = null, strict = false, assetExists = null } = options;
+  const { filePath = null, mode = null, strict = false, assetExists = null, assetSize = null, inlineAssets = false } = options;
   const lineStarts = computeLineStarts(source);
   const masked = maskIgnored(source);
   const tags = tokenize(masked);
@@ -376,6 +382,8 @@ export function validateMdxSource(source, options = {}) {
   const graphRoots = [];
   const relations = [];
   const refs = [];
+  const figureIds = new Map();
+  const figureRefs = [];
   const usedComponents = new Map();
   const stack = [];
 
@@ -434,15 +442,31 @@ export function validateMdxSource(source, options = {}) {
       const map = attrsToMap(tag.attrs);
       const src = attrValue(map, 'src');
       const quoted = map.src ? map.src.quoted : false;
+      const figureId = attrValue(map, 'id');
+      if (figureId) {
+        if (figureIds.has(figureId)) add('warning', 'FIGURE_DUPLICATE_ID', `重复的图片 id：${figureId}`, tag.start, figureId);
+        else figureIds.set(figureId, tag.start);
+      }
       if (!src) add('warning', 'FIGURE_MISSING_SRC', 'Figure 缺少 src', tag.start, tag.name);
-      else if (quoted && !/^(https?:|data:|\/)/i.test(src) && filePath && assetExists) {
+      else if (quoted && /^https?:/i.test(src)) {
+        add('warning', 'ASSET_REMOTE', `远程图片需要联网，离线打开时不可见：${src}`, tag.start, src);
+      } else if (quoted && !/^(data:|\/)/i.test(src) && filePath && assetExists) {
         const resolved = src.startsWith('.') ? src : `./${src}`;
         if (!assetExists(resolved)) {
           add('warning', 'ASSET_MISSING', `找不到图片文件：${src}（将显示占位符）`, tag.start, src);
+        } else if (inlineAssets && assetSize) {
+          const bytes = assetSize(resolved);
+          if (typeof bytes === 'number' && bytes > LARGE_ASSET_BYTES) {
+            add('warning', 'ASSET_LARGE', `图片约 ${Math.round(bytes / 1024)}KB，内联会显著增大 HTML；可用 inline={false} 或改为外链：${src}`, tag.start, src);
+          }
         }
       }
     }
 
+    if (tag.name === 'FigureRef' && tag.kind !== 'close') {
+      figureRefs.push({ id: attrValue(attrsToMap(tag.attrs), 'id'), offset: tag.start });
+    }
+
     if (tag.kind === 'close') {
       for (let i = stack.length - 1; i >= 0; i -= 1) {
         if (stack[i].tag.name === tag.name) {
@@ -465,6 +489,12 @@ export function validateMdxSource(source, options = {}) {
     }
   }
 
+  // <FigureRef> must point at a <Figure id="..."> in the same document.
+  for (const ref of figureRefs) {
+    if (!ref.id) add('warning', 'FIGURE_REF_MISSING_ID', 'FigureRef 缺少 id', ref.offset, 'FigureRef');
+    else if (!figureIds.has(ref.id)) add('warning', 'FIGURE_REF_UNRESOLVED', `FigureRef 指向不存在的图片 id：${ref.id}`, ref.offset, ref.id);
+  }
+
   // `{` inside <Math> children is parsed by MDX as an expression, not LaTeX.
   for (const match of masked.matchAll(/<Math(?![^>]*\/>)[^>]*>([\s\S]*?)<\/Math>/g)) {
     if (match[1].includes('{')) {

package/template/src/scroll-main.jsx

@@ -5,6 +5,7 @@ import * as Components from './components/index.js';
 import UserDocument from '@concept-atlas/content';
 import { useAppearance } from './app/use-appearance.js';
 import { SkinPicker } from './components/SkinPicker.jsx';
+import { FigureScopeProvider } from './components/FigureScope.jsx';
 import './styles/concept-explain.css';
 
 const rootElement = document.getElementById('root');
@@ -27,7 +28,9 @@ function ScrollApp() {
           {theme === 'dark' ? <Sun size={16} /> : <Moon size={16} />}
         </button>
       </div>
-      <UserDocument components={Components} />
+      <FigureScopeProvider scope="document">
+        <UserDocument components={Components} />
+      </FigureScopeProvider>
     </main>
   );
 }

package/template/src/styles/core.css

@@ -348,12 +348,14 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 }
 
 /* ==========================================================================
-   NODE EXPLORER (3-COLUMN EDITORIAL KNOWLEDGE LAYOUT)
+   NODE EXPLORER (2-COLUMN EDITORIAL KNOWLEDGE LAYOUT)
    ========================================================================== */
 
 .node-explorer-layout {
   display: grid;
-  grid-template-columns: 280px 1fr 340px;
+  /* Left sidebar + the scrollable center. The floating app toolbar overlays the
+     top-right; app-main reserves its height so nothing sits underneath. */
+  grid-template-columns: 220px minmax(0, 1fr);
   height: 100%;
   min-height: 0;
 }
@@ -620,44 +622,6 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   margin: 0 auto;
 }
 
-/* Toolbar */
-.center-toolbar {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  margin-bottom: 24px;
-  padding-bottom: 14px;
-  border-bottom: 1px solid var(--border-medium);
-}
-
-.level-indicators {
-  display: flex;
-  gap: 5px;
-}
-
-.level-pill {
-  padding: 4px 9px;
-  border-radius: 6px;
-  font-size: 11px;
-  font-weight: 700;
-  background: var(--bg-surface);
-  color: var(--text-dim);
-  border: 1px solid var(--border-medium);
-  transition: all 0.2s ease;
-}
-
-.level-pill:hover {
-  border-color: var(--text-muted);
-  color: var(--text-primary);
-}
-
-.level-pill.active {
-  background: var(--primary);
-  color: var(--on-accent);
-  border-color: var(--primary);
-  box-shadow: var(--shadow-sm);
-}
-
 .view-graph-btn {
   display: flex;
   align-items: center;
@@ -1298,15 +1262,6 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   flex-direction: column;
 }
 
-.center-toolbar {
-  flex: 0 0 auto;
-  gap: 10px;
-  min-height: 24px;
-  margin-bottom: 4px;
-  padding-bottom: 4px;
-  border-bottom: 0;
-}
-
 .draft-floating-tools {
   position: fixed;
   right: 10px;
@@ -1501,6 +1456,9 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 
 .hierarchy-strip-children {
   padding-left: 0;
+  /* The floating app toolbar hangs into the strip's top-right. Nudge the
+     drill-down row below its bottom edge so its buttons are never covered. */
+  padding-top: 16px;
 }
 
 .hierarchy-child-scroll { display: flex; gap: 5px; overflow-x: auto; min-width: 0; }
@@ -1552,10 +1510,6 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   box-shadow: none;
 }
 
-.node-explorer-layout {
-  grid-template-columns: 220px minmax(0, 1fr);
-}
-
 .inline-inspector {
   margin-top: 18px;
   padding: 18px 20px;
@@ -2787,7 +2741,6 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 .meta-chip,
 .insp-pill,
 .inline-relation,
-.level-pill,
 .view-graph-btn,
 .framework-model-element,
 .model-pyramid-level,
@@ -3485,7 +3438,7 @@ html[data-carrier='scroll'] #root {
   display: block;
   width: 100%;
   height: 100%;
-  background: linear-gradient(90deg, var(--primary), var(--text-accent));
+  background: var(--progress-gradient);
   transform: scaleX(0);
   transform-origin: left center;
   transition: transform 80ms linear;
@@ -3891,6 +3844,22 @@ html[data-carrier='scroll'] #root {
   font-weight: 700;
 }
 
+/* In-text reference to a numbered figure; mirrors the citation affordance. */
+.semantic-figure-ref {
+  color: var(--text-accent);
+  font-weight: 600;
+  text-decoration: none;
+  border-bottom: 1px dashed currentColor;
+}
+
+.semantic-figure-ref:hover {
+  border-bottom-style: solid;
+}
+
+.semantic-figure-ref[data-missing="true"] {
+  color: var(--text-dim);
+}
+
 .figure-placeholder {
   padding: 32px;
   border: 1px dashed var(--border-medium);
@@ -4025,7 +3994,6 @@ a.reference-title:hover { color: var(--text-accent); }
 
 /* Index chips pop in a beat after the surface they sit on. */
 .step-num,
-.level-pill,
 .model-pyramid-level .framework-model-index,
 .framework-model-element .framework-model-index {
   animation: ca-pop var(--motion-base) var(--ease-out) backwards;

package/template/src/styles/packs/elastic.css

@@ -372,10 +372,6 @@
   border-bottom: 1px solid var(--border-subtle);
 }
 
-[data-style='elastic'] .reading-progress-bar {
-  background: var(--primary);
-}
-
 [data-style='elastic'] .scroll-toc-title {
   color: var(--text-muted);
   font-weight: 600;

package/template/src/styles/packs/shadcn.css

@@ -366,10 +366,6 @@
   border-bottom: 1px solid var(--border-subtle);
 }
 
-[data-style='shadcn'] .reading-progress-bar {
-  background: var(--primary);
-}
-
 [data-style='shadcn'] .scroll-toc-title {
   color: var(--text-muted);
   font-weight: 600;

package/template/src/views/NodeExplorer.jsx

@@ -3,14 +3,13 @@ import { ChevronRight, ArrowUpRight, CornerDownRight, ArrowLeft, Network, Corner
 import { getAncestorPath, getSiblingNodes } from '../model/concept-schema.js';
 import { LEVEL_DEFS } from '../model/relation-types.js';
 import { NODE_KINDS } from '../model/node-kinds.js';
+import { FigureScopeProvider } from '../components/FigureScope.jsx';
 
 export function NodeExplorer({
   graph,
   currentNodeId,
   onSelectNode,
   onSwitchView,
-  selectedLevel,
-  onSelectLevel
 }) {
   const { nodes, relations } = graph;
   const [canvasScale, setCanvasScale] = React.useState(1);
@@ -125,8 +124,6 @@ export function NodeExplorer({
   const childNodes = currentNode.children
     .filter(id => nodes.has(id))
     .map(id => nodes.get(id));
-  const visibleChildNodes = selectedLevel ? childNodes.filter(node => node.level === selectedLevel) : childNodes;
-  const visibleSiblings = selectedLevel ? siblings.filter(node => node.level === selectedLevel) : siblings;
 
   // Node-specific relations
   const outgoingRelations = relations.filter(r => r.from === currentNode.id);
@@ -168,8 +165,8 @@ export function NodeExplorer({
         <div className="side-section">
           <div className="side-label">同层节点</div>
           <div className="sibling-list">
-            {visibleSiblings.length > 0 ? (
-              visibleSiblings.map(sib => (
+            {siblings.length > 0 ? (
+              siblings.map(sib => (
                 <button
                   key={sib.id}
                   className="sibling-btn"
@@ -195,6 +192,7 @@ export function NodeExplorer({
       </aside>
 
       {/* 2. Middle Column: Current Node Explanation Card */}
+      <FigureScopeProvider scope={currentNode.id}>
       <main className="explorer-center">
         <HierarchyStrip
           ancestorPath={ancestorPath}
@@ -203,23 +201,6 @@ export function NodeExplorer({
           onSelectNode={onSelectNode}
         />
         <div className="center-scrollable">
-          {/* Header toolbar */}
-          <div className="center-toolbar">
-            <div className="level-indicators">
-              {Object.keys(LEVEL_DEFS).map(lvl => (
-                <button
-                  key={lvl}
-                  className={`level-pill ${(selectedLevel === lvl || (!selectedLevel && currentNode.level === lvl)) ? 'active' : ''}`}
-                  onClick={() => onSelectLevel && onSelectLevel(selectedLevel === lvl ? null : lvl)}
-                  title={LEVEL_DEFS[lvl].desc}
-                >
-                  {lvl}
-                </button>
-              ))}
-              {selectedLevel && <button className="level-pill level-pill-clear" onClick={() => onSelectLevel && onSelectLevel(null)}>全部</button>}
-            </div>
-          </div>
-
           <div
             ref={viewportRef}
             className={`draft-viewport ${isDragging ? 'is-dragging' : ''}`}
@@ -419,14 +400,14 @@ export function NodeExplorer({
             ))}
 
             {/* Sub-node Exploration Cards (Drill Down Entrance) */}
-            {visibleChildNodes.length > 0 && (
+            {childNodes.length > 0 && (
               <section className="node-block drill-down-section">
                 <div className="block-head">
                   <h2>深入下钻：子概念节点</h2>
                   <small>点击卡片探索更深机制</small>
                 </div>
                 <div className="subnodes-grid">
-                  {visibleChildNodes.map(child => (
+                  {childNodes.map(child => (
                     <button
                       key={child.id}
                       className="subnode-card"
@@ -457,6 +438,7 @@ export function NodeExplorer({
           </div>
         </div>
       </main>
+      </FigureScopeProvider>
     </div>
   );
 }

package/template/vite.config.js

@@ -18,37 +18,111 @@ const MIME_TYPES = {
   '.bmp': 'image/bmp',
 };
 
+// An opening/self-closing JSX tag. Quoted attribute values may contain `>`, so
+// the attribute body is matched as a sequence of quoted strings or bare chars.
+const JSX_TAG_RE = /<([A-Za-z][\w.]*)((?:"[^"]*"|'[^']*'|[^>"'])*)\/?>/g;
+// A markdown image: ![alt](src) or ![alt](src "title"). Base64 has no spaces or
+// parens, so it survives the round trip.
+const MARKDOWN_IMAGE_RE = /!\[([^\]]*)\]\(([^)\s]+)(\s+["'][^"']*["'])?\)/g;
+
+/**
+ * Reads a tag's per-image `inline` prop. Returns `true`/`false` when it is set
+ * (bare `inline`, `inline={true}`, `inline={false}`) and `null` when absent.
+ * Quoted attribute values are blanked first so a value like "inline" cannot be
+ * mistaken for the prop itself.
+ */
+function readInlineProp(tag) {
+  const stripped = tag.replace(/"[^"]*"|'[^']*'/g, '""');
+  const match = stripped.match(/\binline\b(?:\s*=\s*(\{[^}]*\}|[^\s/>]+))?/);
+  if (!match) return null;
+  if (match[1] === undefined) return true;
+  return match[1].replace(/^\{|\}$/g, '').trim() !== 'false';
+}
+
 /**
- * Rewrites relative image paths in MDX component props (e.g. <Figure src="./x.png" />)
- * 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.
+ * Reversibly hides fenced code blocks and inline code spans so documented
+ * samples (`<Figure src="./x.png" />` inside a fence) are not rewritten into
+ * giant data URIs.
+ */
+function maskCode(code) {
+  const blocks = [];
+  const token = index => `\u0000atlas-mask-${index}\u0000`;
+  const hide = (text) => { const key = token(blocks.length); blocks.push(text); return key; };
+  let fence = null;
+  const lines = code.split('\n').map((line) => {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length) fence = null;
+      return hide(line);
+    }
+    if (marker) { fence = marker[1]; return hide(line); }
+    // Keep the character before the span so we never eat a JSX opening brace.
+    return line.replace(/([^{])`[^`\n]*`/g, match => match[0] + hide(match.slice(1)));
+  });
+  return {
+    masked: lines.join('\n'),
+    restore: text => blocks.reduce((acc, block, index) => acc.split(token(index)).join(block), text),
+  };
+}
+
+/**
+ * Resolves relative image paths on MDX components and markdown images, or leaves
+ * them alone. The default is to LEAVE them as relative links: the HTML stays
+ * small and the assets travel beside it. Inlining (a self-contained single file)
+ * is opt-in because it is the expensive choice, and it composes in one order:
+ *
+ *   per-tag `inline` prop  >  `--inline-assets` global flag  >  default (link)
  *
- * `--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.
+ * `--inline-assets` (define `__ATLAS_INLINE_ASSETS__ === 'true'`) inlines every
+ * local image; a per-tag `inline={true|false}` overrides that choice for one
+ * image. Remote (http/https), data URIs and absolute paths are never touched.
  */
 function inlineMdxAssets() {
-  const state = { enabled: true };
+  const state = { defaultInline: false };
   return {
     name: 'concept-atlas-inline-assets',
     enforce: 'pre',
     configResolved(config) {
-      state.enabled = (config.define || {}).__ATLAS_INLINE_ASSETS__ !== 'false';
+      const raw = (config.define || {}).__ATLAS_INLINE_ASSETS__;
+      const value = typeof raw === 'string' ? raw.replace(/^"([\s\S]*)"$/, '$1') : raw;
+      state.defaultInline = value === 'true' || value === true;
     },
     transform(code, id) {
-      if (!state.enabled || !id.endsWith('.mdx')) return null;
+      if (!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) => {
-        if (/^(https?:|data:|\/|#)/i.test(src)) return match;
+      const resolveLocal = (src) => {
+        if (/^(https?:|data:|\/|#)/i.test(src)) return null;
         const file = path.resolve(dir, src);
         const mime = MIME_TYPES[path.extname(file).toLowerCase()];
-        if (!mime || !fs.existsSync(file)) return match;
+        if (!mime || !fs.existsSync(file)) return null;
+        return `data:${mime};base64,${fs.readFileSync(file).toString('base64')}`;
+      };
+
+      const { masked, restore } = maskCode(code);
+      let changed = false;
+      let output = masked.replace(JSX_TAG_RE, (tag) => {
+        const srcMatch = tag.match(/\bsrc=(["'])([^"']+)\1/);
+        if (!srcMatch) return tag;
+        const prop = readInlineProp(tag);
+        const effective = prop === null ? state.defaultInline : prop;
+        if (!effective) return tag;
+        const uri = resolveLocal(srcMatch[2]);
+        if (!uri) return tag;
         changed = true;
-        return `${prefix}${quote}data:${mime};base64,${fs.readFileSync(file).toString('base64')}${quote}`;
+        return tag.replace(srcMatch[0], `src=${srcMatch[1]}${uri}${srcMatch[1]}`);
       });
-      return changed ? { code: output, map: null } : null;
+
+      // Markdown images have no prop slot, so they follow the global flag only.
+      if (state.defaultInline) {
+        output = output.replace(MARKDOWN_IMAGE_RE, (match, alt, src, title = '') => {
+          const uri = resolveLocal(src);
+          if (!uri) return match;
+          changed = true;
+          return `![${alt}](${uri}${title})`;
+        });
+      }
+
+      return changed ? { code: restore(output), map: null } : null;
     },
   };
 }