concept-atlas-dense-explain 0.5.0 → 0.6.1

package/bin/cli.mjs

@@ -4,7 +4,8 @@ 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)), '..');
 const templateRoot = path.join(packageRoot, 'template');
@@ -13,7 +14,7 @@ let buildCounter = 0;
 
 function usage() {
   console.log('Usage:');
-  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [-o output.html|dir] [--force] [--concurrency N] [--link-assets] [--json] [--no-validate]');
+  console.log('  npx concept-atlas-dense-explain <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 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]');
@@ -21,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(`  --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.`);
 }
 
 async function exists(filePath) {
@@ -41,7 +43,7 @@ function fail(message) {
   process.exit(1);
 }
 
-const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency']);
+const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style']);
 
 /** Splits argv into flags, flag values and positional arguments. */
 function parseFlags(argv) {
@@ -142,6 +144,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="给读者建立整体认知。">
@@ -166,6 +169,7 @@ if (command === 'create' || command === 'new') {
   </ConceptGraph>
 </ExplainPage>
 ` : `\
+{/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ScrollDocument>
   <ScrollHeader title="主题名称">用一两句话说明主题、背景和读者应该带走的判断。</ScrollHeader>
 
@@ -201,6 +205,25 @@ const force = parsed.flags.has('--force');
 const linkAssets = parsed.flags.has('--link-assets');
 const modeFlag = parsed.values.get('--mode') || null;
 
+// Compile-time appearance defaults. Invalid values fail fast with the valid
+// options instead of silently baking a broken default into every page.
+let skinFlag = null;
+if (parsed.values.has('--skin')) {
+  skinFlag = normalizeSkin(parsed.values.get('--skin'));
+  if (!skinFlag) fail(`Unknown skin: ${parsed.values.get('--skin')} (available: ${SKINS.map(skin => skin.id).join(', ')})`);
+}
+let defaultModeFlag = null;
+if (parsed.values.has('--default-mode')) {
+  const raw = parsed.values.get('--default-mode');
+  if (!['dark', 'light', 'system'].includes(raw)) fail(`Invalid --default-mode: ${raw} (use dark, light or system)`);
+  defaultModeFlag = raw;
+}
+let styleFlag = null;
+if (parsed.values.has('--style')) {
+  styleFlag = normalizeStyle(parsed.values.get('--style'));
+  if (!styleFlag) fail(`Unknown component style: ${parsed.values.get('--style')} (available: ${COMPONENT_STYLES.map(style => style.id).join(', ')})`);
+}
+
 if (command === 'validate') {
   const target = parsed.positional[0] ? path.resolve(parsed.positional[0]) : null;
   if (!target || path.extname(target).toLowerCase() !== '.mdx' || !(await exists(target))) {
@@ -279,7 +302,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);
@@ -295,7 +318,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
@@ -305,6 +328,10 @@ 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);
   try {
     await build({
       root: templateRoot,
@@ -319,7 +346,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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,14 +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]`. 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. For several documents, pass them all in one call: `npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist --force [--concurrency 3]`. `-o` is then a directory. The batch validates everything first and builds in parallel. Builds only bundle the heavy renderers the content uses: a page with no `<Math>`/`<Mermaid>` skips KaTeX (its ~1.4MB inlined fonts) and Mermaid, shrinking a typical scroll article from ~5MB to ~250KB. Do not add dummy `<Math>`/`<Mermaid>` nodes to "enable" them — write the components only when the content needs them. Add `--link-assets` when the page carries many screenshots and size matters.
-8. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
+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.
+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 a table of contents and reading progress from section titles — do not hand-build navigation.
+- `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
@@ -41,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
 
@@ -60,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/guides/atlas-guide.mdx

@@ -89,10 +89,12 @@
       <Children><ConceptRef id="layout-demo" /><ConceptRef id="compact-demo" /></Children>
     </ConceptNode>
     <ConceptNode id="layout-demo" title="布局原语：Stack、Grid、Split、Columns 让信息有秩序" level="L2" parent="presentation-family" summary="布局组件只表达空间意图，具体样式由模板统一接管。">
+      <Definition>布局原语表达信息之间的空间关系；它们负责组织内容，不负责改变内容本身的语义。</Definition>
       <Columns><Split ratio="1fr 1fr"><Callout title="左列">结论与定义。</Callout><Callout title="右列">证据与边界。</Callout></Split></Columns>
       <Grid columns="auto" gap="sm"><Insight title="局部判断">Grid 中的短信息。</Insight><Insight title="另一判断" tone="warn">不要混用职责。</Insight></Grid>
     </ConceptNode>
     <ConceptNode id="compact-demo" title="压缩阅读：Tabs、Details、Callout、Insight、NoteGrid" level="L2" parent="presentation-family" summary="这些组件适合把结论、提示、细节和短信息压缩在首屏。">
+      <Definition>压缩组件通过折叠、分组和短提示降低首屏负担，同时保留继续阅读所需的上下文。</Definition>
       <Tabs items={[{label:'结论',content:'先展示最重要的判断。'},{label:'证据',content:'再展开可验证依据。'}]} />
       <Details summary="展开更多">Details 将次要信息收起，避免首屏过载。</Details>
       <Insight title="关键判断" tone="success">一个组件只承担一种信息组织方式。</Insight>

package/template/index.html

@@ -1,16 +1,42 @@
-<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Concept Atlas · 概念缩放式知识图谱</title>
-    <!-- Google Fonts for Academic / Editorial Knowledge style -->
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=Lora:ital,wght@0,500;0,600;0,700;1,400&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Noto+Serif+SC:wght@500;600;700;900&display=swap" rel="stylesheet">
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.jsx"></script>
-  </body>
-</html>
+<!doctype html>
+<html lang="zh-CN">
+  <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 () {
+        var doc = document.documentElement;
+        var stored = null;
+        try { stored = JSON.parse(localStorage.getItem('concept_atlas_appearance') || 'null'); } catch (e) {}
+        var legacy = localStorage.getItem('concept_atlas_theme');
+        // Placeholders are replaced at build time when --skin/--default-mode
+        // (or CONCEPT_ATLAS_* env vars) are configured; otherwise the runtime
+        // fallbacks below keep the carrier defaults.
+        var skin = '__ATLAS_DEFAULT_SKIN__';
+        if (/^__.+__$/.test(skin)) skin = 'aurora';
+        var mode = '__ATLAS_DEFAULT_MODE__';
+        if (/^__.+__$/.test(mode)) mode = 'light';
+        var style = '__ATLAS_DEFAULT_STYLE__';
+        if (/^__.+__$/.test(style)) style = 'manuscript';
+        if (stored && (stored.mode === 'light' || stored.mode === 'dark')) {
+          mode = stored.mode;
+        } else if (mode !== 'light' && mode !== 'dark') {
+          mode = legacy === 'light' || legacy === 'dark' ? legacy : 'light';
+        }
+        doc.setAttribute('data-skin', stored && stored.skin ? stored.skin : skin);
+        doc.setAttribute('data-theme', mode);
+        doc.setAttribute('data-style', stored && stored.style ? stored.style : style);
+      })();
+    </script>
+    <!-- Google Fonts for Academic / Editorial Knowledge style -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=Lora:ital,wght@0,500;0,600;0,700;1,400&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Noto+Serif+SC:wght@500;600;700;900&display=swap" rel="stylesheet">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/template/scripts/build.mjs

@@ -1,30 +1,70 @@
-import { build } from 'vite';
-import path from 'path';
-import fs from 'fs';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const rootDir = path.resolve(__dirname, '..');
-
+import { build } from 'vite';
+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';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+
+/**
+ * Optional compile-time appearance defaults, read from the environment and
+ * forwarded as `define`s. The carrier HTML plugin replaces the placeholders
+ * inside the anti-flash inline script only when these are configured.
+ */
+function appearanceDefines() {
+  const define = {};
+  const skin = normalizeSkin(process.env.CONCEPT_ATLAS_SKIN || '');
+  const mode = process.env.CONCEPT_ATLAS_DEFAULT_MODE;
+  const style = normalizeStyle(process.env.CONCEPT_ATLAS_STYLE || '');
+  if (skin) define.__ATLAS_DEFAULT_SKIN__ = JSON.stringify(skin);
+  if (['dark', 'light', 'system'].includes(mode)) define.__ATLAS_DEFAULT_MODE__ = JSON.stringify(mode);
+  if (style) define.__ATLAS_DEFAULT_STYLE__ = JSON.stringify(style);
+  return define;
+}
+
+/**
+ * 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.
+ */
+function pageTitleFor(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;
+}
+
 async function runBuild() {
   console.log('🚀 开始构建 Concept Atlas 知识讲解页面...');
-
-  try {
-    // 确保 dist 目录存在
-    const distDir = path.resolve(rootDir, 'dist');
-    if (!fs.existsSync(distDir)) {
-      fs.mkdirSync(distDir, { recursive: true });
-    }
-
+
+  try {
+    // 确保 dist 目录存在
+    const distDir = path.resolve(rootDir, 'dist');
+    if (!fs.existsSync(distDir)) {
+      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'];
+    const define = appearanceDefines();
+    if (define.__ATLAS_DEFAULT_SKIN__ || define.__ATLAS_DEFAULT_MODE__) {
+      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,
@@ -34,10 +74,10 @@ async function runBuild() {
     }
 
     console.log(`✅ 构建成功！产物已生成到 ${carriers.map(entry => `dist/${entry}`).join(' 和 ')}。`);
-  } catch (err) {
-    console.error('❌ 构建失败：', err);
-    process.exit(1);
-  }
-}
-
-runBuild();
+  } catch (err) {
+    console.error('❌ 构建失败：', err);
+    process.exit(1);
+  }
+}
+
+runBuild();

package/template/scroll.html

@@ -3,7 +3,33 @@
   <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 () {
+        var doc = document.documentElement;
+        var stored = null;
+        try { stored = JSON.parse(localStorage.getItem('concept_atlas_appearance') || 'null'); } catch (e) {}
+        var legacy = localStorage.getItem('concept_atlas_scroll_theme');
+        // Placeholders are replaced at build time when --skin/--default-mode
+        // (or CONCEPT_ATLAS_* env vars) are configured; otherwise the runtime
+        // fallbacks below keep the carrier defaults.
+        var skin = '__ATLAS_DEFAULT_SKIN__';
+        if (/^__.+__$/.test(skin)) skin = 'aurora';
+        var mode = '__ATLAS_DEFAULT_MODE__';
+        if (/^__.+__$/.test(mode)) mode = 'light';
+        var style = '__ATLAS_DEFAULT_STYLE__';
+        if (/^__.+__$/.test(style)) style = 'manuscript';
+        if (stored && (stored.mode === 'light' || stored.mode === 'dark')) {
+          mode = stored.mode;
+        } else if (mode !== 'light' && mode !== 'dark') {
+          mode = legacy === 'light' || legacy === 'dark' ? legacy : 'light';
+        }
+        doc.setAttribute('data-skin', stored && stored.skin ? stored.skin : skin);
+        doc.setAttribute('data-theme', mode);
+        doc.setAttribute('data-style', stored && stored.style ? stored.style : style);
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>