concept-atlas-dense-explain 0.6.1 → 0.7.0

package/bin/cli.mjs

@@ -14,7 +14,7 @@ let buildCounter = 0;
 
 function usage() {
   console.log('Usage:');
-  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [-o output.html|dir] [--force] [--concurrency N] [--link-assets] [--json] [--no-validate]');
+  console.log('  npx concept-atlas-dense-explain <input.mdx>... [--mode atlas|scroll] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [-o output.html|dir] [--force] [--concurrency N] [--link-assets] [--inline-mermaid] [--mermaid-cdn <url>] [--json] [--no-validate]');
   console.log('  npx concept-atlas-dense-explain render <input.mdx>... [-o output.html|dir]');
   console.log('  npx concept-atlas-dense-explain validate <input.mdx> [--mode atlas|scroll] [--strict] [--json]');
   console.log('  npx concept-atlas-dense-explain create <output.mdx> [--mode atlas|scroll] [--force]');
@@ -22,6 +22,7 @@ function usage() {
   console.log('');
   console.log('  Multiple inputs build in parallel (default 2 at a time, cap 4); -o is then a directory.');
   console.log('  --link-assets keeps figures as relative links instead of inlining them as base64.');
+  console.log('  Mermaid diagrams load from a CDN at runtime by default (fast builds, needs network); --inline-mermaid bakes Mermaid into the HTML for a fully offline single file; --mermaid-cdn overrides the CDN URL.');
   console.log(`  --skin bakes a default palette (${SKINS.map(skin => skin.id).join(', ')}); --default-mode bakes a default dark/light mode; --style bakes a default component style (${COMPONENT_STYLES.map(style => style.id).join(', ')}). Readers can still switch in the UI.`);
 }
 
@@ -43,7 +44,7 @@ function fail(message) {
   process.exit(1);
 }
 
-const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style']);
+const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style', '--mermaid-cdn']);
 
 /** Splits argv into flags, flag values and positional arguments. */
 function parseFlags(argv) {
@@ -203,6 +204,8 @@ const strict = parsed.flags.has('--strict');
 const skipValidate = parsed.flags.has('--no-validate');
 const force = parsed.flags.has('--force');
 const linkAssets = parsed.flags.has('--link-assets');
+const inlineMermaid = parsed.flags.has('--inline-mermaid');
+const mermaidCdn = parsed.values.get('--mermaid-cdn') || null;
 const modeFlag = parsed.values.get('--mode') || null;
 
 // Compile-time appearance defaults. Invalid values fail fast with the valid
@@ -332,6 +335,10 @@ async function buildOne(job) {
   if (skinFlag) define.__ATLAS_DEFAULT_SKIN__ = JSON.stringify(skinFlag);
   if (defaultModeFlag) define.__ATLAS_DEFAULT_MODE__ = JSON.stringify(defaultModeFlag);
   if (styleFlag) define.__ATLAS_DEFAULT_STYLE__ = JSON.stringify(styleFlag);
+  if (features.mermaid) {
+    define.__ATLAS_MERMAID_MODE__ = JSON.stringify(inlineMermaid ? 'inline' : 'cdn');
+    if (mermaidCdn) define.__ATLAS_MERMAID_CDN_URL__ = JSON.stringify(mermaidCdn);
+  }
   try {
     await build({
       root: templateRoot,
@@ -357,9 +364,10 @@ async function buildOne(job) {
 
 /** Saves the mermaid/KaTeX payload when a document never renders them. */
 function describeFeatures(features) {
-  if (features.math && features.mermaid) return '';
-  const dropped = [features.math ? null : 'KaTeX', features.mermaid ? null : 'Mermaid'].filter(Boolean);
-  return `  [no ${dropped.join('/')}]`;
+  const tags = [];
+  if (features.mermaid) tags.push(inlineMermaid ? 'mermaid inline' : 'mermaid cdn');
+  if (features.math) tags.push('KaTeX');
+  return tags.length ? `  [${tags.join(', ')}]` : '';
 }
 
 function summarizeFeatures(jobs, results) {
@@ -368,7 +376,9 @@ function summarizeFeatures(jobs, results) {
   if (!pages.length) return '';
   const droppedMath = pages.filter(job => !job.features.math).length;
   const droppedMermaid = pages.filter(job => !job.features.mermaid).length;
+  const cdnMermaid = pages.filter(job => job.features.mermaid && !inlineMermaid).length;
   const parts = [];
+  if (cdnMermaid) parts.push(`Mermaid via CDN on ${cdnMermaid}/${pages.length}`);
   if (droppedMath) parts.push(`KaTeX dropped on ${droppedMath}/${pages.length}`);
   if (droppedMermaid) parts.push(`Mermaid dropped on ${droppedMermaid}/${pages.length}`);
   return parts.join(', ');

package/package.json

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

package/skill/SKILL.md

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

package/template/scripts/build.mjs

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

package/template/src/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';