concept-atlas-dense-explain 1.2.0 → 3.0.0

package/README.md

@@ -26,23 +26,26 @@ npx concept-atlas-dense-explain validate topic.mdx --mode atlas
 npx concept-atlas-dense-explain topic.mdx --mode atlas
 ```
 
-`guide` and `create` refuse to overwrite an existing file unless `--force` is
-passed. Use `-o` to choose the output path (a directory when passing several
-inputs). Validation errors abort the build; `--no-validate` forces a knowingly
+Existing outputs are overwritten; `--force` is accepted for compatibility and is
+a no-op. `--mode` defaults to `scroll`. Use `-o` to choose the output path (a
+directory when passing several inputs). Validation errors abort the build; `--no-validate` forces a knowingly
 broken build.
 
 Mermaid loads from a CDN at runtime by default (fast builds, needs network);
 `--inline-mermaid` bakes it into the HTML for a fully offline single file, and
 `--mermaid-cdn` overrides the CDN URL. Appearance defaults can be baked with
 `--skin`, `--default-mode` and `--style`; readers can still switch in the UI.
+Local figures link by default (small HTML, ship `assets/` beside the output);
+`--inline-assets` bakes them in as base64 for a self-contained file, and a
+per-figure `inline={true|false}` overrides that choice.
 
 Run `npx concept-atlas-dense-explain help` for the full flag list.
 
 ## Links
 
 - Repository: https://github.com/wurenrumian/concept-atlas
-- Framework guide: [`docs/FRAMEWORK.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/FRAMEWORK.md)
-- Usage recipes: [`docs/USAGE.md`](https://github.com/wurenrumian/concept-atlas/blob/main/docs/USAGE.md)
+- Framework guide: [`docs/FRAMEWORK.md`](https://github.com/wurenrumian/concept-atlas/blob/master/docs/FRAMEWORK.md)
+- Usage recipes: [`docs/USAGE.md`](https://github.com/wurenrumian/concept-atlas/blob/master/docs/USAGE.md)
 
 ## License
 

package/bin/cli.mjs

@@ -1,11 +1,31 @@
 #!/usr/bin/env node
-import { access, constants, copyFile, cp, mkdir, readFile, rm, rename, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import {
+  access,
+  constants,
+  copyFile,
+  cp,
+  mkdir,
+  readFile,
+  rm,
+  rename,
+  writeFile
+} from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { build } from 'vite';
 import { fileURLToPath } from 'node:url';
-import { validateMdxSource, countBySeverity, detectFeatures, extractPageTitle } from '../template/src/model/validate-content.js';
-import { SKINS, normalizeSkin, COMPONENT_STYLES, normalizeStyle } from '../template/src/model/skins.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');
@@ -14,21 +34,50 @@ 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] [--inline-mermaid] [--mermaid-cdn <url>] [--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] [--concurrency N] [--inline-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]');
-  console.log('  npx concept-atlas-dense-explain guide [--mode atlas|scroll] [-o output.mdx] [--force]');
+  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]');
+  console.log('  npx concept-atlas-dense-explain guide [--mode atlas|scroll] [-o output.mdx]');
   console.log('');
+  console.log(
+    '  --mode defaults to scroll. Existing outputs are overwritten; --force is accepted for compatibility and is a no-op.'
+  );
   console.log('  --help shows this text; --version prints the package version.');
-  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.`);
+  console.log(
+    '  Multiple inputs build in parallel (default 2 at a time, cap 4); -o is then a directory.'
+  );
+  console.log(
+    '  Figures are kept as relative links by default (small HTML; ship the assets/ dir beside it). --inline-assets bakes every local image into the HTML as base64 instead; a per-tag inline={true|false} on <Figure> overrides that for one image. --link-assets is kept as an explicit alias for the default.'
+  );
+  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.`
+  );
 }
 
 async function exists(filePath) {
-  try { await access(filePath, constants.F_OK); return true; } catch { return false; }
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Byte size of an asset, or null when it does not exist. */
+function assetByteSize(filePath) {
+  try {
+    return statSync(filePath).size;
+  } catch {
+    return null;
+  }
 }
 
 function flagValue(flags, names) {
@@ -45,8 +94,29 @@ function fail(message) {
   process.exit(1);
 }
 
-const VALUE_FLAGS = new Set(['--mode', '-o', '--output', '--concurrency', '--skin', '--default-mode', '--style', '--mermaid-cdn']);
-const BOOLEAN_FLAGS = new Set(['--force', '--json', '--strict', '--no-validate', '--link-assets', '--inline-mermaid', '--help', '-h', '--version', '-v']);
+const VALUE_FLAGS = new Set([
+  '--mode',
+  '-o',
+  '--output',
+  '--concurrency',
+  '--skin',
+  '--default-mode',
+  '--style',
+  '--mermaid-cdn'
+]);
+const BOOLEAN_FLAGS = new Set([
+  '--force',
+  '--json',
+  '--strict',
+  '--no-validate',
+  '--link-assets',
+  '--inline-assets',
+  '--inline-mermaid',
+  '--help',
+  '-h',
+  '--version',
+  '-v'
+]);
 const COMMAND_NAMES = ['help', 'create', 'new', 'render', 'validate', 'guide'];
 
 /** Splits argv into flags, flag values and positional arguments. */
@@ -77,7 +147,10 @@ function extractCommand(argv) {
   const rest = [...argv];
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
-    if (VALUE_FLAGS.has(arg)) { i += 1; continue; }
+    if (VALUE_FLAGS.has(arg)) {
+      i += 1;
+      continue;
+    }
     if (arg.startsWith('-') && arg.length > 1) continue;
     if (COMMAND_NAMES.includes(arg)) {
       rest.splice(i, 1);
@@ -100,7 +173,9 @@ function resolveOutputs(inputs, explicit) {
   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`));
+  return inputs.map(input =>
+    path.join(target, `${path.basename(input, path.extname(input))}.html`)
+  );
 }
 
 function printDiagnostics(source, options, { json, label = null, quiet = false }) {
@@ -118,7 +193,9 @@ function printDiagnostics(source, options, { json, label = null, quiet = false }
     console.error(`${severity} ${where}  ${item.code}  ${item.message}`);
   }
   const { error, warning } = countBySeverity(diagnostics);
-  const scope = carrier ? `${carrier} · ${stats.nodes} 节点 / ${stats.relations} 关系` : '未识别载体';
+  const scope = carrier
+    ? `${carrier} · ${stats.nodes} 节点 / ${stats.relations} 关系`
+    : '未识别载体';
   if (error) console.error(`校验失败：${error} 个错误，${warning} 个警告（${scope}）`);
   else if (warning) console.error(`校验通过：${warning} 个警告（${scope}）`);
   else console.error(`校验通过：无问题（${scope}）`);
@@ -128,7 +205,10 @@ function printDiagnostics(source, options, { json, label = null, quiet = false }
 const { command, rest } = extractCommand(args);
 args = rest;
 
-if (args.includes('--help') || args.includes('-h')) { usage(); process.exit(0); }
+if (args.includes('--help') || args.includes('-h')) {
+  usage();
+  process.exit(0);
+}
 if (args.includes('--version') || args.includes('-v')) {
   const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
   console.log(pkg.version);
@@ -150,16 +230,17 @@ for (let i = 0; i < args.length; i += 1) {
   }
 }
 
-if (command === 'help') { usage(); process.exit(0); }
+if (command === 'help') {
+  usage();
+  process.exit(0);
+}
 
 if (command === 'guide') {
-  const mode = flagValue(args, ['--mode']) || 'atlas';
+  const mode = flagValue(args, ['--mode']) || 'scroll';
   if (!['atlas', 'scroll'].includes(mode)) fail(`Unknown mode: ${mode}`);
-  const output = path.resolve(flagValue(args, ['-o', '--output']) || `concept-atlas-${mode}-guide.mdx`);
-  if (await exists(output) && !args.includes('--force')) {
-    console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
-    process.exit(1);
-  }
+  const output = path.resolve(
+    flagValue(args, ['-o', '--output']) || `concept-atlas-${mode}-guide.mdx`
+  );
   const source = path.join(templateRoot, 'references', `${mode}-guide.mdx`);
   if (!(await exists(source))) {
     console.error(`Guide for mode "${mode}" is missing from the package.`);
@@ -169,7 +250,7 @@ if (command === 'guide') {
   await copyFile(source, output);
   const assetsSource = path.join(templateRoot, 'references', 'assets');
   const assetsTarget = path.join(path.dirname(output), 'assets');
-  if (await exists(assetsSource) && path.resolve(assetsSource) !== path.resolve(assetsTarget) && (args.includes('--force') || !(await exists(assetsTarget)))) {
+  if ((await exists(assetsSource)) && path.resolve(assetsSource) !== path.resolve(assetsTarget)) {
     await cp(assetsSource, assetsTarget, { recursive: true, force: true });
     console.log(`Copied guide assets to ${assetsTarget}`);
   }
@@ -180,17 +261,19 @@ if (command === 'guide') {
 
 if (command === 'create' || command === 'new') {
   const output = args[0] ? path.resolve(args[0]) : null;
-  const mode = flagValue(args, ['--mode']) || 'atlas';
-  if (!output || path.extname(output).toLowerCase() !== '.mdx' || !['atlas', 'scroll'].includes(mode)) {
+  const mode = flagValue(args, ['--mode']) || 'scroll';
+  if (
+    !output ||
+    path.extname(output).toLowerCase() !== '.mdx' ||
+    !['atlas', 'scroll'].includes(mode)
+  ) {
     usage();
     process.exit(1);
   }
-  if (await exists(output) && !args.includes('--force')) {
-    console.error(`Refusing to overwrite ${output}; pass --force to replace it.`);
-    process.exit(1);
-  }
   await mkdir(path.dirname(output), { recursive: true });
-  const template = mode === 'atlas' ? `\
+  const template =
+    mode === 'atlas'
+      ? `\
 {/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ExplainPage id="topic-id" title="主题名称" summary="用一句话说明这个主题解决什么问题。">
   <ConceptGraph root="root-node">
@@ -216,7 +299,8 @@ if (command === 'create' || command === 'new') {
     <Relation from="first-branch" to="second-branch" type="depends-on" label="依赖" />
   </ConceptGraph>
 </ExplainPage>
-` : `\
+`
+      : `\
 {/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ScrollDocument>
   <ScrollHeader title="主题名称">用一两句话说明主题、背景和读者应该带走的判断。</ScrollHeader>
@@ -242,7 +326,9 @@ if (command === 'create' || command === 'new') {
 `;
   await writeFile(output, template, 'utf8');
   console.log(`Created ${mode} MDX template: ${output}`);
-  console.log(`Tip: run "npx concept-atlas-dense-explain guide --mode ${mode}" for a full component reference.`);
+  console.log(
+    `Tip: run "npx concept-atlas-dense-explain guide --mode ${mode}" for a full component reference.`
+  );
   process.exit(0);
 }
 
@@ -250,8 +336,11 @@ 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 inlineAssets = parsed.flags.has('--inline-assets');
+if (linkAssets && inlineAssets) {
+  fail('--link-assets and --inline-assets are mutually exclusive (linking is the default).');
+}
 const inlineMermaid = parsed.flags.has('--inline-mermaid');
 const mermaidCdn = parsed.values.get('--mermaid-cdn') || null;
 const modeFlag = parsed.values.get('--mode') || null;
@@ -261,18 +350,25 @@ const modeFlag = parsed.values.get('--mode') || null;
 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(', ')})`);
+  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)`);
+  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 (!styleFlag)
+    fail(
+      `Unknown component style: ${parsed.values.get('--style')} (available: ${COMPONENT_STYLES.map(style => style.id).join(', ')})`
+    );
 }
 
 if (command === 'validate') {
@@ -281,19 +377,26 @@ if (command === 'validate') {
     fail('Provide an existing .mdx file to validate.');
   }
   const source = await readFile(target, 'utf8');
-  const result = printDiagnostics(source, {
-    filePath: target,
-    mode: modeFlag,
-    strict,
-    assetExists: spec => existsSync(path.resolve(path.dirname(target), spec)),
-  }, { json });
+  const result = printDiagnostics(
+    source,
+    {
+      filePath: target,
+      mode: modeFlag,
+      strict,
+      inlineAssets,
+      assetExists: spec => existsSync(path.resolve(path.dirname(target), spec)),
+      assetSize: spec => assetByteSize(path.resolve(path.dirname(target), spec))
+    },
+    { json }
+  );
   process.exit(countBySeverity(result.diagnostics).error ? 1 : 0);
 }
 
 // `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 positional =
+  parsed.positional[0] && parsed.positional[0].toLowerCase() === 'render'
+    ? parsed.positional.slice(1)
+    : parsed.positional;
 const inputs = positional.map(entry => path.resolve(entry));
 
 if (!inputs.length) {
@@ -310,26 +413,25 @@ for (const input of inputs) {
 
 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(inputs[index]), spec)),
-}, json
-  ? { json: false, quiet: true }
-  : { json: false, label: multi ? inputs[index] : null }));
+const validations = sources.map((source, index) =>
+  printDiagnostics(
+    source,
+    {
+      filePath: inputs[index],
+      mode: modeFlag,
+      strict,
+      inlineAssets,
+      assetExists: spec => existsSync(path.resolve(path.dirname(inputs[index]), spec)),
+      assetSize: spec => assetByteSize(path.resolve(path.dirname(inputs[index]), spec))
+    },
+    json ? { json: false, quiet: true } : { json: false, label: multi ? inputs[index] : null }
+  )
+);
 
 if (json) {
   const payload = multi
@@ -338,7 +440,10 @@ if (json) {
   process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
 }
 
-const errorCount = validations.reduce((sum, result) => sum + countBySeverity(result.diagnostics).error, 0);
+const errorCount = validations.reduce(
+  (sum, result) => sum + countBySeverity(result.diagnostics).error,
+  0
+);
 if (errorCount && !skipValidate) {
   console.error('内容校验未通过，已停止构建。修复后重试，或用 --no-validate 强制构建。');
   process.exit(1);
@@ -347,38 +452,65 @@ if (errorCount && !skipValidate) {
 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.`);
+    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)} 内，相对图片路径会失效。`);
+  // Figures link by default. If the HTML is written outside the MDX's directory
+  // its relative image paths no longer resolve, so warn unless --inline-assets
+  // bakes them in.
+  if (
+    !inlineAssets &&
+    path.resolve(path.dirname(outputs[index])) !== path.resolve(path.dirname(input))
+  ) {
+    console.error(
+      `警告：默认外链图片，但 ${outputs[index]} 不在 ${path.dirname(input)} 内，相对图片路径会失效；请用 --inline-assets，或把 assets/ 一并放到输出目录。`
+    );
   }
-  return { input, output: outputs[index], mode, title: extractPageTitle(sources[index]), features: detectFeatures(sources[index]), linkAssets };
+  return {
+    input,
+    output: outputs[index],
+    mode,
+    title: extractPageTitle(sources[index]),
+    features: detectFeatures(sources[index]),
+    inlineAssets
+  };
 });
 
 const limit = clampConcurrency(parsed.values.get('--concurrency'), jobs.length);
 const started = Date.now();
-const results = await runPool(jobs.map(job => () => buildOne(job)), limit);
+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})` : ''}.`);
+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);
+  for (const failure of failures)
+    console.error(`Build failed for ${failure.input}:`, failure.error);
   process.exit(1);
 }
 
 async function buildOne(job) {
-  const { input, output, mode, title, features, linkAssets: link } = job;
+  const { input, output, mode, title, features, inlineAssets: inline } = 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)}`);
+  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';
+  // 'false' is the default (link); only --inline-assets sets 'true'.
+  define.__ATLAS_INLINE_ASSETS__ = inline ? 'true' : '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);
@@ -396,8 +528,8 @@ async function buildOne(job) {
       build: {
         outDir: scratch,
         emptyOutDir: false,
-        rollupOptions: { input: path.join(templateRoot, templateEntry) },
-      },
+        rollupOptions: { input: path.join(templateRoot, templateEntry) }
+      }
     });
     // Swap the new build in without a window where no output exists: on
     // POSIX rename replaces atomically; the fallback path (Windows can refuse
@@ -424,7 +556,9 @@ async function buildOne(job) {
       }
       if (hasBackup) await rm(backup, { force: true });
     }
-    console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
+    console.log(
+      `Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${inline ? '  [figures inlined]' : '  [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": "1.2.0",
+  "version": "3.0.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {

package/packaged-skill/SKILL.md

@@ -24,7 +24,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
    - `references/atlas-guide.mdx` (atlas) or `references/scroll-guide.mdx` (scroll)
    It is real, compilable MDX showing that shell's components and their exact props; search it for a component name instead of guessing, and do not look for component documentation anywhere else. Do not run `guide` for this.
    Run `npx concept-atlas-dense-explain guide --mode <mode> -o <file>` only when you specifically need a project-local copy to compile beside the page, and delete that copy 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.
+3. Start from a skeleton when useful: `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll` (`--mode` defaults to `scroll`). `create` and `guide` overwrite their output, so never point them at a file you want to keep.
 4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
 5. Validate before rendering:
    ```bash
@@ -32,9 +32,9 @@ This is the only runner — there is nothing to look for. Do not search for a lo
    npx concept-atlas-dense-explain validate <file>.mdx --json
    ```
    Diagnostics are `CODE line:column message`. Fix all `error`s and re-run; address warnings 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>] [--inline-mermaid] [--mermaid-cdn <url>]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build (`--no-validate` forces a knowingly broken build). Mermaid loads from a CDN at runtime by default (needs network); pass `--inline-mermaid` for a fully offline single file.
+6. Compile: `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll [-o out.html] [--skin <id>] [--default-mode dark|light|system] [--style <id>] [--mermaid-cdn <url>]`. Output is a standalone HTML beside the MDX unless `-o` is given. Validation errors abort the build (`--no-validate` forces a knowingly broken build). **Mermaid stays on its runtime CDN by default — do not pass `--inline-mermaid` on your own.** Only add `--inline-mermaid` when the user explicitly asks for a fully offline single file, since it bloats the HTML with the whole Mermaid bundle.
 7. **Appearance (optional)**: pages ship a reader-facing appearance menu — palette (`aurora` indigo, `ember` gold, `verdant` forest, `sakura` pink-plum, `noir` 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. Bake different compile-time defaults with `--skin ember --default-mode dark --style classic` (or `CONCEPT_ATLAS_SKIN` / `CONCEPT_ATLAS_DEFAULT_MODE` / `CONCEPT_ATLAS_STYLE` on the repo build); `--default-mode` honors `dark`/`light` and resolves `system` to the carrier default (`light`). Bake a default only when the user asks for one — content MDX never sets appearance.
-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; everything validates first, then builds in parallel). Builds bundle only the heavy renderers the content uses: no `<Math>` skips KaTeX's ~1.4MB inlined fonts, and Mermaid stays on a CDN. Never add dummy `<Math>`/`<Mermaid>` nodes to "enable" them.
+8. For several documents, pass them all in one call: `npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist [--concurrency 3]` (`-o` is then a directory; everything validates first, then builds in parallel). Builds bundle only the heavy renderers the content uses: no `<Math>` skips KaTeX's ~1.4MB inlined fonts, and Mermaid stays on a CDN. Never add dummy `<Math>`/`<Mermaid>` nodes to "enable" them.
 9. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
 
 ## Carriers
@@ -47,12 +47,12 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 ## Component families
 
 - Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `CodeBlock`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
-- Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `LearningObjectives`, `KeyQuestion`
-- Learning loop and provenance: `WorkedExample` + `Step`, `Quiz`, `KeyTakeaways`, `Source`, `Confidence`, `Term`
+- Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `Checklist`, `LearningObjectives`, `KeyQuestion`
+- Learning loop and provenance: `WorkedExample` + `Step`, `Quiz`, `KeyTakeaways`, `Source`, `Confidence`, `LastReviewed`, `Term`
 - Information models: `Flow`, `Timeline`, `Compare`, `DecisionMatrix`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`
-- Data and behaviour: `DataTable`, `Metric`, `StateMachine`, `DecisionTree`, `FeedbackLoop`, `CodeDiff`
-- 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`
+- Data and behaviour: `DataTable`, `Metric`, `PropertyList`, `TreeView`, `StateMachine`, `DecisionTree`, `FeedbackLoop`, `CodeDiff`
+- Reading and layout: `Insight`, `Callout`, `Details`, `Quote`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`, `ScrollPair`, `ScrollToc`
+- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `CodeTabs`, `AnnotatedCode`, `Figure` (alias `Image`), `FigureRef`, `Cite`, `References`
 
 ## Authoring rules
 
@@ -67,20 +67,23 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 - **Learning loop**: `WorkedExample` holds `Step` children; give each step a `reason` (the justification) so it teaches reasoning, not just the result. `Quiz question answer` reveals the answer on click with children as the explanation. `KeyTakeaways items={[...]}` closes a section.
 - **Provenance**: `Source kind="spec|rfc|implementation|experiment|experience" label href` marks one claim's origin inline; `Confidence level="high|medium|low" basis` wraps a claim with how strongly it is established; `Term name` (or children as the definition) gives an inline hover definition.
 - **Data and behaviour**: `DataTable headers={[...]} rows={[[...]]}` is the neutral table (no comparative stance). `Metric label value unit delta trend note` is one headline number — compose several with `Grid`/`ScrollGrid`. `StateMachine states={[{id,label,terminal}]} transitions={[{from,to,event,guard}]}` expresses cycles and guards. `DecisionTree branches={[{condition,outcome,tone,branches}]}` nests branches. `FeedbackLoop type="reinforcing|balancing" nodes={[{label,description}]}` closes a loop. `CodeDiff before after language` shows a change.
-- **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 warns (`ASSET_MISSING`) and shows a placeholder. Readers can click a figure to open it full-screen (zoom, drag, `Esc`) — mention it for diagram-heavy pages.
-- **Figure size & cost**: inlining images is what makes a screenshot-heavy page large; a page with no heavy renderers otherwise lands near 250KB. When the user cares, compile with `--link-assets` to keep images as relative links (measured 1.51MB → 270KB); the output must then sit beside the MDX's `assets/`, and the CLI warns if `-o` points elsewhere — tell the user that trade-off instead of choosing silently.
+- **Structure and code extensions**: `Quote author source href` attributes a quotation. `Checklist title items={[{text,status:'pass'|'fail'|'unknown'|'todo',note}]}` is a verification list. `PropertyList title items={[{name,value,note}]}` is a name/value spec ledger. `TreeView title items={[{label,description,children:[…]}]}` nests a hierarchy. `CodeTabs items={[{label,language,code}]} title caption lineNumbers` gives one collapsible listing per variant. `AnnotatedCode code language title notes={[{line,text}]}` numbers a listing and calls out specific lines. `LastReviewed date by note` is a review stamp.
+- **Figure**: a relative `src` (`./assets/diagram.png`) stays a relative link by default; compile with `--inline-assets` to bake every local image in as base64, or set `inline={true}` / `inline={false}` on one figure to override (precedence: per-figure prop > global flag > link). `http(s)` URLs stay links and warn (`ASSET_REMOTE`). Always set `alt`; a missing relative file warns (`ASSET_MISSING`) and shows a placeholder. Readers can click a figure to open it full-screen (zoom, drag, `Esc`) — mention it for diagram-heavy pages.
+- **Figure numbering**: give a figure an `id` and reference it with `<FigureRef id="..." />` to render "图 N". Numbering follows document order (per node in `atlas`, whole document in `scroll`) and reflows automatically, so never hand-write "图 1"; an explicit `label` still wins. A ref with no matching `id` warns (`FIGURE_REF_UNRESOLVED`).
+- **Figure size & cost**: linking keeps the HTML small but requires the output to sit beside the MDX's `assets/` (the CLI warns when `-o` points elsewhere). Inlining is what makes a screenshot-heavy page large (a page with no heavy renderers otherwise lands near 250KB), and an inlined asset over 512KB warns (`ASSET_LARGE`). Decide the trade-off with the user 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.
 
 ## 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_MISSING_ID`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_KIND`, `MECHANISM_KIND_UNVERIFIED`, `FAILURE_KIND_UNSTRUCTURED`, `FAILURE_MODE_EMPTY`, `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`, `MULTIPLE_ROOT_LEVEL`, `MECHANISM_KIND_UNVERIFIED` and `FAILURE_KIND_UNSTRUCTURED` are warnings that `--strict` promotes to errors.
+`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_KIND`, `MECHANISM_KIND_UNVERIFIED`, `FAILURE_KIND_UNSTRUCTURED`, `FAILURE_MODE_EMPTY`, `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`, `ASSET_REMOTE`, `ASSET_LARGE`, `FIGURE_REF_UNRESOLVED`, `FIGURE_REF_MISSING_ID`, `FIGURE_DUPLICATE_ID`, `REF_SELF`; `NO_ROOT_LEVEL`, `MULTIPLE_ROOT_LEVEL`, `MECHANISM_KIND_UNVERIFIED` and `FAILURE_KIND_UNSTRUCTURED` are warnings that `--strict` promotes to errors.
 
 ## Before you report
 
 - All `error` diagnostics resolved (or `--no-validate` explicitly justified).
 - All `ConceptRef`, `Relation` endpoints, and `ConceptGraph root` point at existing node ids.
 - Every node has `title` + `summary`; every `Relation` has a `label`.
+- You left Mermaid on its CDN default and did not pass `--inline-mermaid` unless the user explicitly asked for a fully offline single file.
 - The HTML file exists at the reported path.
 
 If `npx` cannot reach the registry, report the blocker. Never copy implementation files into the skill directory.

package/packaged-skill/references/atlas-guide.mdx

@@ -132,10 +132,11 @@
       <Chart title="留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]}]} />
     </ConceptNode>
 
-    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定，构建时把本地图片内联进单文件。">
-      <Definition>相对路径的图片会在构建时转成 base64 内联，远程 URL 保持不变；label 提供“图 1”这样的编号。</Definition>
-      <Figure src="./assets/sample-diagram.svg" alt="概念缩放示意" label="图 1" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
-      <Boundary>大图会显著增大单文件 HTML；截图类内容建议控制尺寸。</Boundary>
+    <ConceptNode id="figure-demo" title="Figure：图片与题注一起出现" level="L2" parent="extension-family" summary="Figure 把图片、题注编号和说明绑定；默认外链，按需内联。">
+      <Definition>相对路径的图片默认保持外链，构建时用 --inline-assets 可全部内联，单张图也可用 `inline={true}` 或 `inline={false}` 覆盖；远程 URL 保持不变。给图一个 id，正文就能用 FigureRef 自动引用“图 N”。</Definition>
+      <Figure id="zoom-scale" src="./assets/sample-diagram.svg" alt="概念缩放示意" caption="概念缩放：同一主题可以从 L0 全局逐层下钻到 L4 边界反例。" />
+      <Example title="自动图号">正文写“见 <FigureRef id="zoom-scale" />”，编号会随插图自动重排，不必手写“图 1”。</Example>
+      <Boundary>内联大图会显著增大 HTML；截图类内容建议控制尺寸，或对单张图设 `inline={false}`。</Boundary>
     </ConceptNode>
 
     <ConceptNode id="code-demo" title="CodeBlock：把命令、配置或伪代码放进正文" level="L2" parent="extension-family" summary="与绑定节点的 Implementation 不同，CodeBlock 可以出现在任何位置，并支持标题、题注、换行和行号。">