concept-atlas-dense-explain 0.6.1 → 0.8.0

package/bin/cli.mjs

@@ -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] [--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] [--link-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,6 +22,7 @@ function usage() {
   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.');
+  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.`);
 }
 
@@ -43,7 +44,7 @@ function fail(message) {
   process.exit(1);
 }
 
-const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style']);
+const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style', '--mermaid-cdn']);
 
 /** Splits argv into flags, flag values and positional arguments. */
 function parseFlags(argv) {
@@ -203,6 +204,8 @@ 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 inlineMermaid = parsed.flags.has('--inline-mermaid');
+const mermaidCdn = parsed.values.get('--mermaid-cdn') || null;
 const modeFlag = parsed.values.get('--mode') || null;
 
 // Compile-time appearance defaults. Invalid values fail fast with the valid
@@ -332,6 +335,10 @@ async function buildOne(job) {
   if (skinFlag) define.__ATLAS_DEFAULT_SKIN__ = JSON.stringify(skinFlag);
   if (defaultModeFlag) define.__ATLAS_DEFAULT_MODE__ = JSON.stringify(defaultModeFlag);
   if (styleFlag) define.__ATLAS_DEFAULT_STYLE__ = JSON.stringify(styleFlag);
+  if (features.mermaid) {
+    define.__ATLAS_MERMAID_MODE__ = JSON.stringify(inlineMermaid ? 'inline' : 'cdn');
+    if (mermaidCdn) define.__ATLAS_MERMAID_CDN_URL__ = JSON.stringify(mermaidCdn);
+  }
   try {
     await build({
       root: templateRoot,
@@ -357,9 +364,10 @@ async function buildOne(job) {
 
 /** 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('/')}]`;
+  const tags = [];
+  if (features.mermaid) tags.push(inlineMermaid ? 'mermaid inline' : 'mermaid cdn');
+  if (features.math) tags.push('KaTeX');
+  return tags.length ? `  [${tags.join(', ')}]` : '';
 }
 
 function summarizeFeatures(jobs, results) {
@@ -368,7 +376,9 @@ function summarizeFeatures(jobs, results) {
   if (!pages.length) return '';
   const droppedMath = pages.filter(job => !job.features.math).length;
   const droppedMermaid = pages.filter(job => !job.features.mermaid).length;
+  const cdnMermaid = pages.filter(job => job.features.mermaid && !inlineMermaid).length;
   const parts = [];
+  if (cdnMermaid) parts.push(`Mermaid via CDN on ${cdnMermaid}/${pages.length}`);
   if (droppedMath) parts.push(`KaTeX dropped on ${droppedMath}/${pages.length}`);
   if (droppedMermaid) parts.push(`Mermaid dropped on ${droppedMermaid}/${pages.length}`);
   return parts.join(', ');

package/package.json

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

package/skill/SKILL.md

@@ -1,23 +1,21 @@
 ---
 name: concept-atlas-dense-explain
-description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Use the concept-atlas-dense-explain npm CLI to generate AI-editable MDX, validate its structure, and compile standalone HTML with concept nodes, relation graphs, math (KaTeX), charts, figures, citations, and reading aids. Use when a technical explanation, concept map, layered knowledge page, dense explainer, or interactive teaching page is requested.
+description: Turn a topic or an existing document into an interactive Concept Atlas explainer. Generate AI-editable MDX with the concept-atlas-dense-explain npm CLI, validate its structure, and compile standalone HTML with concept nodes, relation graphs, math (KaTeX), charts, figures, citations, and reading aids. Use when a technical explanation, concept map, layered knowledge page, dense explainer, or interactive teaching page is requested.
 ---
 
 # Concept Atlas Dense Explain
 
-Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill is intentionally lightweight: do not copy implementation files from the skill directory and do not recreate the React/Vite app. If a command name is unclear, run `npx concept-atlas-dense-explain help`.
-
-If the user only wants the prompt/methodology and not files, still choose a shell and emit valid MDX; the CLI is needed only to compile.
+Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill is intentionally lightweight: do not copy implementation files from the skill directory or recreate the React/Vite app. If a command name is unclear, run `npx concept-atlas-dense-explain help`. If the user only wants the prompt/methodology and not files, still choose a shell and emit valid MDX; the CLI is needed only to compile.
 
 ## Workflow
 
-1. Choose one page shell: `atlas` (concept graph with node navigation) or `scroll` (continuous document). Recommend `atlas` when the reader needs to drill into concepts or see relations; recommend `scroll` for linear argument, tutorials, and reports. The component library is shared. If the user already has an `.mdx` file, detect its shell and work with it.
-2. **Learn the components from the canonical guide before authoring.** Generate the guide for the chosen shell into a temporary path and read it:
+1. Choose one page shell: `atlas` (concept graph with node navigation) or `scroll` (continuous document). Recommend `atlas` when the reader drills into concepts or follows relations, `scroll` for linear argument, tutorials, and reports. The library is shared. If an `.mdx` already exists, detect its shell and work with it.
+2. **Learn the components from the canonical guide before authoring.** Generate it for the chosen shell and read it:
    ```bash
    npx concept-atlas-dense-explain guide --mode atlas -o ./concept-atlas-atlas-guide.mdx
    npx concept-atlas-dense-explain guide --mode scroll -o ./concept-atlas-scroll-guide.mdx
    ```
-   It is a real, compilable MDX file that demonstrates the components for that shell and their exact props. Search it for a component name to copy the correct prop shape instead of guessing. Delete it when done.
+   It is real, compilable MDX showing that shell's components and their exact props; search it for a component name instead of guessing. Delete it when done.
 3. Start from a skeleton when useful: `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll`. `create` and `guide` refuse to overwrite an existing file unless `--force` is passed.
 4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
 5. Validate before rendering:
@@ -25,17 +23,17 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    npx concept-atlas-dense-explain validate <file>.mdx --mode atlas|scroll
    npx concept-atlas-dense-explain validate <file>.mdx --json
    ```
-   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] [--skin <id>] [--default-mode dark|light|system] [--style <id>]`. 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. **Appearance (optional)**: pages ship with a reader-facing appearance menu — palette (`aurora` cool blue, `ember` warm gold), a dark/light toggle, and a component style pack (`manuscript` editorial marginalia, `classic` boxed cards). The shipped default is aurora × manuscript × light; choices persist in localStorage across both carriers. You can bake different compile-time defaults: `--skin ember --default-mode dark --style classic` (or env `CONCEPT_ATLAS_SKIN` / `CONCEPT_ATLAS_DEFAULT_MODE` / `CONCEPT_ATLAS_STYLE` on the repo build). `--default-mode` only honors `dark`/`light`; `system` is accepted by the CLI but resolves to the carrier default (`light`). Bake a default only when the user asks for one. Content MDX never sets appearance — it is carrier/tooling territory, not content.
-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. 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.
+   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.
+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.
 
 ## 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.
+- `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. `ConceptNode` also takes an optional `kind` (see Authoring rules) that labels a node's knowledge role independently of its level.
 - `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components live inside sections. The shell auto-builds a table of contents and reading progress from section titles — do not hand-build navigation.
-- The browser tab comes from the shell, not the build flags: `ExplainPage title="..."` (atlas) or `ScrollHeader title="..."` (scroll) becomes the `<title>`, so give it a real, specific document name — never leave a placeholder like "主题名称". The favicon is a fixed 📃 document emoji on every generated page.
+- The browser tab comes from the shell, not the build flags: `ExplainPage title` (atlas) or `ScrollHeader title` (scroll) becomes the `<title>`, so give it a real, specific name — never a placeholder like "主题名称". Every page uses a fixed 📃 favicon.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families
@@ -50,19 +48,19 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 
 - Keep MDX semantic. Never write CSS, coordinates, SVG, or replacement application code; never invent component names or props.
 - Give each important node a claim-like title, a one-sentence `summary`, and real substance (`Definition`, `Mechanism`, `Example`, `Boundary`, `Evidence`, a model, a chart, or math). Do not restate the same text across `Overview`, `Definition`, and `Insight`.
+- **`kind` (optional, atlas)**: tag a node's knowledge role independently of `level`. One of `system`, `stage`, `mechanism`, `artifact`, `failure`, `tool`, `boundary`, `decision`. It powers the graph's "知识类型" filter and a node badge, so use it where the role is clear rather than on every node. Two opt-in contracts fire once you declare one: `kind="mechanism"` should contain an `Invariant` or `Evidence`, and `kind="failure"` should contain a `FailureMode` (with `symptom`/`cause`/`evidence`/`remedy`).
 - Array props are arrays of objects: `Flow steps={[{title, description}]}`, `Timeline events={[{label, content}]}`, `MatrixModel cells={[{title, description, tone}]}`, `DecisionMatrix headers={[...]} rows={[[...]]}`, `Chart data={[{label, value}]}`, `References items={[{id, authors, year, title, url, source}]}`. The validator warns (`PROP_EXPECTS_ARRAY`) when an array prop gets a string or non-array.
 - `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. 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.
+- **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.
 - **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: 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
 
-`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_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` and `MULTIPLE_ROOT_LEVEL` 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`, `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
 

package/template/scripts/build.mjs

@@ -3,12 +3,21 @@ import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
 import { normalizeSkin, normalizeStyle } from '../src/model/skins.js';
-import { extractPageTitle } from '../src/model/validate-content.js';
+import { extractPageTitle, detectFeatures } from '../src/model/validate-content.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const rootDir = path.resolve(__dirname, '..');
 
+/**
+ * Mermaid is served from a CDN at runtime by default so its ~2100-module
+ * transform stays out of the build. Set CONCEPT_ATLAS_INLINE_MERMAID=1 to bake
+ * it back into the HTML for a fully offline single file; CONCEPT_ATLAS_MERMAID_CDN
+ * overrides the CDN URL.
+ */
+const INLINE_MERMAID = ['1', 'true', 'yes'].includes((process.env.CONCEPT_ATLAS_INLINE_MERMAID || '').toLowerCase());
+const MERMAID_CDN_URL = process.env.CONCEPT_ATLAS_MERMAID_CDN || '';
+
 /**
  * Optional compile-time appearance defaults, read from the environment and
  * forwarded as `define`s. The carrier HTML plugin replaces the placeholders
@@ -26,28 +35,65 @@ function appearanceDefines() {
 }
 
 /**
- * The tab title comes from the mounted demo document, not the carrier shell:
- * the repository mounts content/components-demo.mdx in index.html while the
- * npm template mounts content/compile-runtime.mdx, so both are probed and the
- * first existing file supplies its <ExplainPage>/<ScrollHeader> title.
+ * The demo document mounted by each carrier. Unlike the npm template (which
+ * aliases the user's MDX), the repository hardcodes its demos in main.jsx /
+ * scroll-main.jsx, so the build reads them to derive the tab title and the set
+ * of optional renderers actually needed.
  */
-function pageTitleFor(entry) {
+function demoSourceFor(entry) {
   const demos = entry === 'scroll.html'
     ? ['content/scroll-reading-demo.mdx']
     : ['content/components-demo.mdx', 'content/compile-runtime.mdx'];
   const demo = demos.map(name => path.resolve(rootDir, name)).find(file => fs.existsSync(file));
-  return demo ? extractPageTitle(fs.readFileSync(demo, 'utf8')) : null;
+  return demo ? { demo, source: fs.readFileSync(demo, 'utf8') } : null;
+}
+
+/**
+ * Builds one standalone carrier HTML. `__ATLAS_FEATURES__` mirrors the CLI's
+ * per-document stubbing so a demo that never uses <Math>/<Mermaid> skips the
+ * KaTeX fonts and Mermaid module graph instead of bundling them unconditionally.
+ */
+async function buildCarrier(entry, baseDefine) {
+  const define = { ...baseDefine };
+  const demo = demoSourceFor(entry);
+  if (demo) {
+    const title = extractPageTitle(demo.source);
+    if (title) {
+      define.__ATLAS_PAGE_TITLE__ = JSON.stringify(title);
+      console.log(`🔖 ${entry} 标签页标题：${title}`);
+    }
+    const features = detectFeatures(demo.source);
+    define.__ATLAS_FEATURES__ = JSON.stringify(features);
+    if (features.mermaid) {
+      define.__ATLAS_MERMAID_MODE__ = JSON.stringify(INLINE_MERMAID ? 'inline' : 'cdn');
+      if (MERMAID_CDN_URL) define.__ATLAS_MERMAID_CDN_URL__ = JSON.stringify(MERMAID_CDN_URL);
+      if (!INLINE_MERMAID) console.log(`🌐 ${entry} Mermaid 运行时从 CDN 加载（--inline-mermaid 可内联）`);
+    }
+    const dropped = [features.math ? null : 'KaTeX', features.mermaid ? null : 'Mermaid'].filter(Boolean);
+    if (dropped.length) console.log(`⚡ ${entry} 省略未使用的渲染器：${dropped.join('、')}`);
+  }
+
+  await build({
+    root: rootDir,
+    define,
+    build: {
+      outDir: 'dist',
+      // dist is cleared once up front; parallel carriers must not wipe each
+      // other's output mid-build.
+      emptyOutDir: false,
+      rollupOptions: { input: path.resolve(rootDir, entry) },
+    }
+  });
 }
 
 async function runBuild() {
   console.log('🚀 开始构建 Concept Atlas 知识讲解页面...');
 
   try {
-    // 确保 dist 目录存在
+    // Clear dist once, then let every carrier write into it concurrently.
     const distDir = path.resolve(rootDir, 'dist');
-    if (!fs.existsSync(distDir)) {
-      fs.mkdirSync(distDir, { recursive: true });
-    }
+    fs.rmSync(distDir, { recursive: true, force: true });
+    fs.mkdirSync(distDir, { recursive: true });
 
     const mode = process.env.CONCEPT_ATLAS_MODE;
     const carriers = mode === 'atlas' ? ['index.html'] : mode === 'scroll' ? ['scroll.html'] : ['index.html', 'scroll.html'];
@@ -56,22 +102,10 @@ async function runBuild() {
       console.log(`🎨 默认外观：skin=${define.__ATLAS_DEFAULT_SKIN__ || '(carrier 默认)'} mode=${define.__ATLAS_DEFAULT_MODE__ || '(carrier 默认)'}`);
     }
 
-    // vite-plugin-singlefile supports one HTML input per build. Build each
-    // requested carrier separately so every output remains a standalone file.
-    for (const [index, entry] of carriers.entries()) {
-      const title = pageTitleFor(entry);
-      const entryDefine = title ? { ...define, __ATLAS_PAGE_TITLE__: JSON.stringify(title) } : define;
-      if (title) console.log(`🔖 ${entry} 标签页标题：${title}`);
-      await build({
-        root: rootDir,
-        define: entryDefine,
-        build: {
-          outDir: 'dist',
-          emptyOutDir: index === 0,
-          rollupOptions: { input: path.resolve(rootDir, entry) },
-        }
-      });
-    }
+    // vite-plugin-singlefile supports one HTML input per build and emits no
+    // shared assets, so the carriers are independent and build in parallel
+    // instead of one full pass after another.
+    await Promise.all(carriers.map(entry => buildCarrier(entry, define)));
 
     console.log(`✅ 构建成功！产物已生成到 ${carriers.map(entry => `dist/${entry}`).join(' 和 ')}。`);
   } catch (err) {

package/template/src/app/App.jsx

@@ -3,11 +3,19 @@ import { Network, Compass, Sun, Moon, Search, X, Link as LinkIcon } from 'lucide
 import { buildGraphModel } from '../model/concept-schema.js';
 import { extractConceptData } from '../model/normalize-content.js';
 import { useAppearance } from './use-appearance.js';
+import { pushNode, stepHistory, syncFromLocation } from './navigation.js';
+import { searchNodes } from './search.js';
+import { NODE_KINDS } from '../model/node-kinds.js';
 import { SkinPicker } from '../components/SkinPicker.jsx';
 import { NodeExplorer } from '../views/NodeExplorer.jsx';
 import { RelationGraph } from '../views/RelationGraph.jsx';
 import '../styles/concept-explain.css';
 
+function readNodeFromHash() {
+  if (typeof window === 'undefined') return null;
+  return new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
+}
+
 export function App({ mdxContent, initialData }) {
   // Extract graph model from MDX JSX Element or raw data
   const [graph] = useState(() => {
@@ -28,54 +36,41 @@ export function App({ mdxContent, initialData }) {
 
   // Global shared state
   const [currentView, setCurrentView] = useState('explore'); // 'explore' | 'graph'
-  const [currentNodeId, setCurrentNodeId] = useState(() => {
-    const hashNode = new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
-    return hashNode && graph.nodes.has(hashNode) ? hashNode : (graph.meta.rootId || '');
-  });
+  const initialHashNode = (() => {
+    const hashNode = readNodeFromHash();
+    return hashNode && graph.nodes.has(hashNode) ? hashNode : null;
+  })();
+
+  const [currentNodeId, setCurrentNodeId] = useState(
+    () => initialHashNode || graph.meta.rootId || '',
+  );
   const [selectedLevel, setSelectedLevel] = useState(null);
-  const [history, setHistory] = useState(() => {
-    const initial = new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
-    return initial && graph.nodes.has(initial) ? [initial] : [graph.meta.rootId].filter(Boolean);
-  });
-  const [historyIndex, setHistoryIndex] = useState(0);
+  const [nav, setNav] = useState(() => ({
+    entries: (initialHashNode ? [initialHashNode] : [graph.meta.rootId]).filter(Boolean),
+    index: 0,
+  }));
   const [globalQuery, setGlobalQuery] = useState('');
   const [linkCopied, setLinkCopied] = useState(false);
 
-  const searchResults = useMemo(() => {
-    const query = globalQuery.trim().toLowerCase();
-    if (!query) return [];
-    return Array.from(graph.nodes.values()).map(node => {
-      const searchable = [
-        node.title, node.id, node.summary, node.definition, node.overview,
-        node.mechanism, node.input, node.output,
-        ...(node.examples || []).flatMap(item => [item.title, item.content]),
-        ...(node.glossary || []).flatMap(item => [item.term, item.definition]),
-        ...(node.boundaries || []).flatMap(item => [item.title, item.content]),
-      ].filter(value => typeof value === 'string').join(' ').toLowerCase();
-      return searchable.includes(query) ? node : null;
-    }).filter(Boolean).slice(0, 8);
-  }, [globalQuery, graph.nodes]);
+  const searchResults = useMemo(
+    () => searchNodes(Array.from(graph.nodes.values()), globalQuery),
+    [globalQuery, graph.nodes],
+  );
 
   const navigateToNode = (nodeId, { replace = false } = {}) => {
     if (!nodeId || !graph.nodes.has(nodeId)) return;
     setCurrentNodeId(nodeId);
-    setHistory(previous => {
-      const base = previous.slice(0, historyIndex + 1);
-      if (base[base.length - 1] === nodeId) return previous;
-      const next = [...base, nodeId];
-      setHistoryIndex(next.length - 1);
-      return next;
-    });
+    setNav(previous => pushNode(previous, nodeId));
     const nextHash = `#node=${encodeURIComponent(nodeId)}`;
     if (replace) window.history.replaceState({}, '', nextHash);
     else window.history.pushState({}, '', nextHash);
   };
 
   const moveHistory = (direction) => {
-    const nextIndex = Math.max(0, Math.min(history.length - 1, historyIndex + direction));
-    if (nextIndex === historyIndex) return;
-    setHistoryIndex(nextIndex);
-    const nodeId = history[nextIndex];
+    const next = stepHistory(nav, direction);
+    if (!next) return;
+    setNav(next);
+    const nodeId = next.entries[next.index];
     setCurrentNodeId(nodeId);
     window.history.pushState({}, '', `#node=${encodeURIComponent(nodeId)}`);
   };
@@ -83,10 +78,26 @@ export function App({ mdxContent, initialData }) {
   // Keyboard navigation shortcuts
   useEffect(() => {
     const handleKeyDown = (e) => {
-      // Toggle views with 1 and 2 or 'g' and 'e' if not focused on input
-      if (e.isComposing || e.metaKey || e.ctrlKey || e.altKey || ['INPUT', 'TEXTAREA', 'SELECT'].includes(document.activeElement?.tagName) || document.activeElement?.isContentEditable) {
+      if (e.isComposing) return;
+
+      // Alt + arrows move through browsing history. Handled before the modifier
+      // guard below, otherwise the altKey short-circuit makes them unreachable.
+      if (e.altKey && e.key === 'ArrowLeft') {
+        e.preventDefault();
+        moveHistory(-1);
         return;
       }
+      if (e.altKey && e.key === 'ArrowRight') {
+        e.preventDefault();
+        moveHistory(1);
+        return;
+      }
+
+      // Toggle views with 1 and 2 or 'g' and 'e' if not focused on input.
+      const target = document.activeElement;
+      const typing = ['INPUT', 'TEXTAREA', 'SELECT'].includes(target?.tagName) || target?.isContentEditable;
+      if (e.metaKey || e.ctrlKey || e.altKey || typing) return;
+
       const key = e.key.toLowerCase();
       if (e.key === '1' || key === 'e') {
         setCurrentView('explore');
@@ -95,18 +106,7 @@ export function App({ mdxContent, initialData }) {
       } else if (key === 't') {
         toggleTheme();
       } else if (e.key === 'Escape') {
-        // Alt + arrows move through browsing history.
-        if (e.altKey && e.key === 'ArrowLeft') {
-          e.preventDefault();
-          moveHistory(-1);
-          return;
-        }
-        if (e.altKey && e.key === 'ArrowRight') {
-          e.preventDefault();
-          moveHistory(1);
-          return;
-        }
-        // Return to root or parent
+        // Return to the parent node.
         const curr = graph.nodes.get(currentNodeId);
         if (curr && curr.parent) {
           navigateToNode(curr.parent);
@@ -116,23 +116,14 @@ export function App({ mdxContent, initialData }) {
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [graph, currentNodeId, historyIndex, history]);
+  }, [graph, currentNodeId, nav]);
 
   useEffect(() => {
     const handlePopState = () => {
-      const nodeId = new URLSearchParams(window.location.hash.replace(/^#/, '')).get('node');
+      const nodeId = readNodeFromHash();
       if (!nodeId || !graph.nodes.has(nodeId)) return;
       setCurrentNodeId(nodeId);
-      setHistory(previous => {
-        const index = previous.lastIndexOf(nodeId);
-        if (index >= 0) {
-          setHistoryIndex(index);
-          return previous;
-        }
-        const next = [...previous, nodeId];
-        setHistoryIndex(next.length - 1);
-        return next;
-      });
+      setNav(previous => syncFromLocation(previous, nodeId));
     };
     window.addEventListener('popstate', handlePopState);
     return () => window.removeEventListener('popstate', handlePopState);
@@ -176,7 +167,7 @@ export function App({ mdxContent, initialData }) {
               <div className="global-search-results" role="listbox">
                 {searchResults.map(node => (
                   <button type="button" key={node.id} onClick={() => { navigateToNode(node.id); setGlobalQuery(''); }} role="option">
-                    <span>{node.title}</span><small>{node.level} · {node.summary || node.id}</small>
+                    <span>{node.title}</span><small>{node.level}{node.kind && NODE_KINDS[node.kind] ? ` · ${NODE_KINDS[node.kind].label}` : ''} · {node.summary || node.id}</small>
                   </button>
                 ))}
               </div>

package/template/src/app/navigation.js

@@ -0,0 +1,41 @@
+/**
+ * Pure browsing-history helpers for the atlas carrier.
+ *
+ * History is a single `{ entries, index }` value instead of two separate
+ * `useState` calls. Keeping them together removes the side effect that used to
+ * live inside the `setHistory` updater (which React StrictMode can double
+ * invoke) and makes the whole navigation model trivially unit-testable.
+ */
+
+/**
+ * Push a node onto the history, truncating any forward entries.
+ * Returns the same object when `nodeId` is already the current entry so React
+ * can bail out of the state update.
+ */
+export function pushNode(state, nodeId) {
+  const base = state.entries.slice(0, state.index + 1);
+  if (base[base.length - 1] === nodeId) return state;
+  const entries = [...base, nodeId];
+  return { entries, index: entries.length - 1 };
+}
+
+/**
+ * Move one step through the history. Returns `null` when the move would leave
+ * the bounds, so the caller can avoid a redundant re-render.
+ */
+export function stepHistory(state, direction) {
+  const nextIndex = Math.max(0, Math.min(state.entries.length - 1, state.index + direction));
+  if (nextIndex === state.index) return null;
+  return { entries: state.entries, index: nextIndex };
+}
+
+/**
+ * Resolve a node id arriving from a `popstate` event (browser back/forward).
+ * Reuses an existing entry when present so the back stack stays consistent.
+ */
+export function syncFromLocation(state, nodeId) {
+  const existing = state.entries.lastIndexOf(nodeId);
+  if (existing >= 0) return { entries: state.entries, index: existing };
+  const entries = [...state.entries, nodeId];
+  return { entries, index: entries.length - 1 };
+}

package/template/src/app/search.js

@@ -0,0 +1,84 @@
+import React from 'react';
+import { NODE_KINDS } from '../model/node-kinds.js';
+
+const MAX_DEPTH = 6;
+const MAX_LENGTH = 4000;
+
+/**
+ * Flatten whatever an MDX component renders — strings, React elements, arrays
+ * and prop objects — into searchable plain text. Bounded in depth and length so
+ * a pathological tree cannot stall the search box.
+ */
+export function collectText(value, depth = 0) {
+  if (depth > MAX_DEPTH || value === null || value === undefined || typeof value === 'boolean') return '';
+  if (typeof value === 'string' || typeof value === 'number') return String(value);
+  if (Array.isArray(value)) {
+    return value.map(item => collectText(item, depth + 1)).join(' ');
+  }
+  if (React.isValidElement(value)) {
+    const props = value.props || {};
+    const parts = [];
+    for (const [key, prop] of Object.entries(props)) {
+      // `components` is the MDX component registry, never content.
+      if (key === 'children' || key === 'components') continue;
+      if (typeof prop === 'string' || typeof prop === 'number') parts.push(String(prop));
+      else if (prop && typeof prop === 'object') parts.push(collectText(prop, depth + 1));
+    }
+    parts.push(collectText(props.children, depth + 1));
+    return parts.join(' ');
+  }
+  if (typeof value === 'object') {
+    return Object.values(value).map(item => collectText(item, depth + 1)).join(' ');
+  }
+  return '';
+}
+
+/**
+ * Build one lowercase haystack per node. Includes the semantic content fields,
+ * the structured argument/evidence records (Evidence, Invariant, FailureMode,
+ * Tradeoff, …) and the free-form `customSections` that the same components also
+ * render through. The kind id and its label are indexed too, so "故障" finds
+ * `kind="failure"` nodes.
+ */
+export function nodeSearchText(node) {
+  if (!node) return '';
+  const kind = node.kind ? NODE_KINDS[node.kind] : null;
+  const parts = [
+    node.title,
+    node.id,
+    node.kind,
+    kind ? kind.label : '',
+    node.summary,
+    node.overview,
+    node.definition,
+    node.mechanism,
+    node.input,
+    node.output,
+    node.implementation,
+    node.prerequisites,
+    node.examples,
+    node.counterexamples,
+    node.boundaries,
+    node.glossary,
+    node.learningObjectives,
+    node.keyQuestions,
+    node.evidence,
+    node.invariants,
+    node.failureModes,
+    node.tradeoffs,
+    node.customSections,
+  ];
+  return parts.map(part => collectText(part)).join(' ').slice(0, MAX_LENGTH).toLowerCase();
+}
+
+/** Rank-free substring search returning at most `limit` nodes. */
+export function searchNodes(nodes, query, limit = 8) {
+  const needle = String(query || '').trim().toLowerCase();
+  if (!needle) return [];
+  const results = [];
+  for (const node of nodes) {
+    if (nodeSearchText(node).includes(needle)) results.push(node);
+    if (results.length >= limit) break;
+  }
+  return results;
+}

package/template/src/components/MDXComponents.jsx

@@ -70,7 +70,7 @@ function configureMermaid() {
       lineColor: read('--mermaid-line', MERMAID_FALLBACKS.lineColor),
       secondaryColor: nodeBg,
       tertiaryColor: read('--mermaid-canvas', MERMAID_FALLBACKS.tertiaryColor),
-      fontFamily: 'Plus Jakarta Sans, sans-serif',
+      fontFamily: read('--font-sans', "'Plus Jakarta Sans', sans-serif"),
     },
   });
 }
@@ -942,6 +942,7 @@ export function Chart({ title = '图表', type = 'bar', data = [], series = [],
             <g key={seriesIndex}>
               <polyline
                 className="chart-line"
+                pathLength="1"
                 style={chartColor(seriesIndex)}
                 points={entry.values.map((value, idx) => `${xFor(idx)},${yFor(value)}`).join(' ')}
               />