concept-atlas-dense-explain 0.6.0 → 0.7.0

package/bin/cli.mjs

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { build } from 'vite';
 import { fileURLToPath } from 'node:url';
-import { validateMdxSource, countBySeverity, detectFeatures } from '../template/src/model/validate-content.js';
+import { validateMdxSource, countBySeverity, detectFeatures, extractPageTitle } from '../template/src/model/validate-content.js';
 import { SKINS, normalizeSkin, COMPONENT_STYLES, normalizeStyle } from '../template/src/model/skins.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.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] [--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) {
@@ -144,6 +145,7 @@ if (command === 'create' || command === 'new') {
   }
   await mkdir(path.dirname(output), { recursive: true });
   const template = mode === 'atlas' ? `\
+{/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ExplainPage id="topic-id" title="主题名称" summary="用一句话说明这个主题解决什么问题。">
   <ConceptGraph root="root-node">
     <ConceptNode id="root-node" title="核心概念" level="L0" summary="给读者建立整体认知。">
@@ -168,6 +170,7 @@ if (command === 'create' || command === 'new') {
   </ConceptGraph>
 </ExplainPage>
 ` : `\
+{/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ScrollDocument>
   <ScrollHeader title="主题名称">用一两句话说明主题、背景和读者应该带走的判断。</ScrollHeader>
 
@@ -201,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
@@ -300,7 +305,7 @@ const jobs = inputs.map((input, index) => {
   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 };
+  return { input, output: outputs[index], mode, title: extractPageTitle(sources[index]), features: detectFeatures(sources[index]), linkAssets };
 });
 
 const limit = clampConcurrency(parsed.values.get('--concurrency'), jobs.length);
@@ -316,7 +321,7 @@ if (failures.length) {
 }
 
 async function buildOne(job) {
-  const { input, output, mode, features, linkAssets: link } = job;
+  const { input, output, mode, title, 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
@@ -326,9 +331,14 @@ async function buildOne(job) {
   await mkdir(scratch, { recursive: true });
   const define = { __ATLAS_FEATURES__: JSON.stringify(features) };
   if (link) define.__ATLAS_INLINE_ASSETS__ = '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);
   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,
@@ -343,7 +353,7 @@ async function buildOne(job) {
     });
     await rm(output, { force: true });
     await rename(path.join(scratch, templateEntry), output);
-    console.log(`Built ${mode} HTML: ${output}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
+    console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
     return { ok: true, input, output };
   } catch (error) {
     return { ok: false, input, output, error };
@@ -354,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) {
@@ -365,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.0",
+  "version": "0.7.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -17,7 +17,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    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 demonstrating every component and its exact props. Search it for a component name to copy the correct prop shape instead of guessing. Delete it when done.
+   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.
 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:
@@ -26,15 +26,16 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    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). 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.
+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; use `--no-validate` only to force a knowingly broken build. Mermaid loads from a CDN at runtime by default (fast build, small HTML, needs network); pass `--inline-mermaid` when the user needs a fully offline single file.
+7. **Appearance (optional)**: pages ship with a reader-facing appearance menu — palette (`aurora` cool indigo, `ember` warm gold, `verdant` forest green, `sakura` pink-plum, `noir` achromatic 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. 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>` skips KaTeX (its ~1.4MB inlined fonts), and Mermaid is served from a CDN by default rather than bundled. 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.
 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.
 - `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.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families
@@ -42,8 +43,8 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 - Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
 - Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `LearningObjectives`, `KeyQuestion`
 - Information models: `Flow`, `Timeline`, `Compare`, `DecisionMatrix`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`
-- Reading and layout: `Insight`, `Callout`, `Details`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`
-- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `Figure`, `Cite`, `References`
+- 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`
 
 ## Authoring rules
 
@@ -61,7 +62,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 
 ## 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_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`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `GRAPH_MISSING_ROOT`, `ASSET_MISSING`.
+`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.
 
 ## Before you report
 

package/template/index.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E📃%3C/text%3E%3C/svg%3E" />
     <title>Concept Atlas · 概念缩放式知识图谱</title>
     <script>
       (function () {

package/template/scripts/build.mjs

@@ -3,11 +3,21 @@ import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
 import { normalizeSkin, normalizeStyle } from '../src/model/skins.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
@@ -24,15 +34,66 @@ function appearanceDefines() {
   return define;
 }
 
+/**
+ * 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 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 ? { 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'];
@@ -41,19 +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()) {
-      await build({
-        root: rootDir,
-        define,
-        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/scroll.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E📃%3C/text%3E%3C/svg%3E" />
     <title>Concept Atlas · 连续阅读示例</title>
     <script>
       (function () {

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(' ')}
               />

package/template/src/model/skins.js

@@ -13,6 +13,21 @@ export const SKINS = [
     id: 'ember',
     label: 'Ember · 炉火',
     swatch: { dark: '#1c1812', light: '#f6f1e7', accent: '#d99a4e' }
+  },
+  {
+    id: 'verdant',
+    label: 'Verdant · 苔原',
+    swatch: { dark: '#0f1813', light: '#f3f7f2', accent: '#10b981' }
+  },
+  {
+    id: 'sakura',
+    label: 'Sakura · 樱雾',
+    swatch: { dark: '#1e131d', light: '#fbf3f7', accent: '#ec4899' }
+  },
+  {
+    id: 'noir',
+    label: 'Noir · 墨白',
+    swatch: { dark: '#141416', light: '#f5f5f4', accent: '#e63946' }
   }
 ];
 
@@ -32,7 +47,9 @@ export function normalizeSkin(value) {
  */
 export const COMPONENT_STYLES = [
   { id: 'manuscript', label: 'Manuscript · 评注手稿' },
-  { id: 'classic', label: 'Classic · 经典卡片' }
+  { id: 'classic', label: 'Classic · 经典卡片' },
+  { id: 'shadcn', label: 'shadcn · 极简界面' },
+  { id: 'elastic', label: 'Elastic · 观测面板' }
 ];
 
 export const DEFAULT_STYLE = 'manuscript';

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

@@ -598,3 +598,28 @@ export function detectFeatures(source) {
     mermaid: used.has('Mermaid'),
   };
 }
+
+/** JSX string literals decode these five entities; a single pass avoids
+ * double-decoding sequences like `<`. */
+const ENTITY_MAP = { amp: '&', lt: '<', gt: '>', quot: '"', '#39': "'" };
+const decodeEntities = text => text.replace(/&(amp|lt|gt|quot|#39);/g, (_, entity) => ENTITY_MAP[entity]);
+
+/**
+ * Reads the browser-tab title from the MDX source without rendering: the atlas
+ * shell declares it on <ExplainPage title="...">, the scroll shell on
+ * <ScrollHeader title="...">. Only quoted string props count — a `{...}`
+ * expression title cannot be known at build time. Returns null when no static
+ * title exists, so the build keeps the carrier's default <title>.
+ */
+export function extractPageTitle(source) {
+  const tags = tokenize(maskIgnored(source));
+  for (const shell of ['ExplainPage', 'ScrollHeader']) {
+    const tag = tags.find(item => item.name === shell && item.kind !== 'close');
+    if (!tag) continue;
+    const attr = attrsToMap(tag.attrs).title;
+    if (attr && attr.hasValue && attr.quoted && attr.value.trim()) {
+      return decodeEntities(attr.value).trim();
+    }
+  }
+  return null;
+}