concept-atlas-dense-explain 0.5.0 → 0.6.0

package/bin/cli.mjs

@@ -5,6 +5,7 @@ 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 { 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) {
@@ -201,6 +203,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))) {
@@ -305,6 +326,9 @@ async function buildOne(job) {
   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,

package/package.json

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

package/skill/SKILL.md

@@ -26,14 +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. 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). 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

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>