concept-atlas-dense-explain 0.4.2 → 0.6.0

package/bin/cli.mjs

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

package/package.json

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

package/skill/SKILL.md

@@ -26,13 +26,15 @@ 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. 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). 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.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families
@@ -51,10 +53,11 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 - `Relation type` must be one of `prerequisite`, `causes`, `produces`, `uses`, `implements`, `contrasts`, `depends-on`, `exception-of`, `precedes`, and each `Relation` needs a `label`. Parent/child hierarchy is implicit (via `parent` and `Children`/`ConceptRef`) — do not express it with a `Relation`.
 - **Math**: MDX parses `{ ... }` in children as expressions, so pass LaTeX with braces or backslashes through `formula`: `<Math formula="r_{\text{ann}} = (1 + r)^{12} - 1" />`, `<MathBlock formula="I(x) = -\log_2 p(x)" variables={[{symbol, description}]} />`. Brace-free children such as `<Math>\log_2 N</Math>` are fine. The validator warns (`MATH_CHILDREN_BRACES`).
 - **Chart**: `type` is `bar` | `line` | `pie`; use `data` for bar/pie and `labels` + `series={[{name, values}]}` for line. Charts follow theme colors.
-- **Figure**: a relative `src` (`./assets/diagram.png`) is inlined as base64 at build time so the HTML stays standalone; `http(s)` URLs stay links. Always set `alt`; add `label` and `caption` for a numbered caption. A missing relative file produces an `ASSET_MISSING` warning and a placeholder.
+- **Figure**: a relative `src` (`./assets/diagram.png`) is inlined as base64 at build time so the HTML stays standalone; `http(s)` URLs stay links. Always set `alt`; add `label` and `caption` for a numbered caption. A missing relative file produces an `ASSET_MISSING` warning and a placeholder. Readers can click any figure to open it full-screen (wheel/`+`/`−` zoom, drag to pan, double-click for 1x/2x, `Esc` to close) — mention this when a page carries dense diagrams.
+- **Figure size**: inlining is what makes a screenshot-heavy page large. When a document carries many images and the user cares about size, compile with `--link-assets` to keep them as relative links (measured: 1.51MB → 270KB on one page). The output then has to live beside the MDX's `assets/` directory, and the CLI warns if `-o` points elsewhere — tell the user that trade-off instead of choosing silently.
 - **Cite/References**: `<Cite id="..." />` renders `[n]` from the matching item's position in `<References items={...} />`. In `scroll`, `References` can sit anywhere. In `atlas`, keep the cites and the `References` block in the same node, because node content only renders when that node is open.
 - Continuous reading is configured on the shell, not with manual CSS: `spacing="compact|comfortable|airy"` for rhythm, `fontSize="compact|normal|large|xlarge"` (or numeric `scale`/`lineHeight`) for text size.
-- Be brief about cost: KaTeX fonts and Mermaid roughly double the single-file output (~5 MB), which is normal for an offline explainer. Mention it if the user cares about file size.
+- Be brief about cost: the build only bundles the heavy optional renderers the document actually uses, so a page with no `<Math>`/`<Mermaid>` comes out around 250KB. Inlined figures are usually the largest remaining cost — a page with a dozen screenshots lands near 1–2MB, which is normal for an offline explainer. Mention it if the user cares about file size.
 
 ## Validation diagnostics
 

package/template/guides/atlas-guide.mdx

@@ -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,41 @@
-<!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" />
+    <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,52 @@
-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';
+
+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;
+}
+
 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()) {
       await build({
         root: rootDir,
+        define,
         build: {
           outDir: 'dist',
           emptyOutDir: index === 0,
@@ -34,10 +56,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

@@ -4,6 +4,31 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <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>