concept-atlas-dense-explain 0.6.0 → 0.6.1

package/bin/cli.mjs

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { build } from 'vite';
 import { fileURLToPath } from 'node:url';
-import { validateMdxSource, countBySeverity, detectFeatures } from '../template/src/model/validate-content.js';
+import { validateMdxSource, countBySeverity, detectFeatures, extractPageTitle } from '../template/src/model/validate-content.js';
 import { SKINS, normalizeSkin, COMPONENT_STYLES, normalizeStyle } from '../template/src/model/skins.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -144,6 +144,7 @@ if (command === 'create' || command === 'new') {
   }
   await mkdir(path.dirname(output), { recursive: true });
   const template = mode === 'atlas' ? `\
+{/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ExplainPage id="topic-id" title="主题名称" summary="用一句话说明这个主题解决什么问题。">
   <ConceptGraph root="root-node">
     <ConceptNode id="root-node" title="核心概念" level="L0" summary="给读者建立整体认知。">
@@ -168,6 +169,7 @@ if (command === 'create' || command === 'new') {
   </ConceptGraph>
 </ExplainPage>
 ` : `\
+{/* shell 的 title 会成为浏览器标签页标题；页面图标固定为 📃。请把“主题名称”改成真实标题。 */}
 <ScrollDocument>
   <ScrollHeader title="主题名称">用一两句话说明主题、背景和读者应该带走的判断。</ScrollHeader>
 
@@ -300,7 +302,7 @@ const jobs = inputs.map((input, index) => {
   if (linkAssets && path.resolve(path.dirname(outputs[index])) !== path.resolve(path.dirname(input))) {
     console.error(`警告：--link-assets 下 ${outputs[index]} 不在 ${path.dirname(input)} 内，相对图片路径会失效。`);
   }
-  return { input, output: outputs[index], mode, features: detectFeatures(sources[index]), linkAssets };
+  return { input, output: outputs[index], mode, title: extractPageTitle(sources[index]), features: detectFeatures(sources[index]), linkAssets };
 });
 
 const limit = clampConcurrency(parsed.values.get('--concurrency'), jobs.length);
@@ -316,7 +318,7 @@ if (failures.length) {
 }
 
 async function buildOne(job) {
-  const { input, output, mode, features, linkAssets: link } = job;
+  const { input, output, mode, title, features, linkAssets: link } = job;
   const templateEntry = mode === 'atlas' ? 'index.html' : 'scroll.html';
   // Each build gets its own scratch outDir: the template always writes
   // `index.html`/`scroll.html`, so concurrent builds sharing a directory would
@@ -326,6 +328,7 @@ async function buildOne(job) {
   await mkdir(scratch, { recursive: true });
   const define = { __ATLAS_FEATURES__: JSON.stringify(features) };
   if (link) define.__ATLAS_INLINE_ASSETS__ = 'false';
+  if (title) define.__ATLAS_PAGE_TITLE__ = JSON.stringify(title);
   if (skinFlag) define.__ATLAS_DEFAULT_SKIN__ = JSON.stringify(skinFlag);
   if (defaultModeFlag) define.__ATLAS_DEFAULT_MODE__ = JSON.stringify(defaultModeFlag);
   if (styleFlag) define.__ATLAS_DEFAULT_STYLE__ = JSON.stringify(styleFlag);
@@ -343,7 +346,7 @@ async function buildOne(job) {
     });
     await rm(output, { force: true });
     await rename(path.join(scratch, templateEntry), output);
-    console.log(`Built ${mode} HTML: ${output}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
+    console.log(`Built ${mode} HTML: ${output}${title ? `  [tab: ${title}]` : ''}${describeFeatures(features)}${link ? '  [figures linked]' : ''}`);
     return { ok: true, input, output };
   } catch (error) {
     return { ok: false, input, output, error };

package/package.json

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

package/skill/SKILL.md

@@ -17,7 +17,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    npx concept-atlas-dense-explain guide --mode atlas -o ./concept-atlas-atlas-guide.mdx
    npx concept-atlas-dense-explain guide --mode scroll -o ./concept-atlas-scroll-guide.mdx
    ```
-   It is a real, compilable MDX file demonstrating every component and its exact props. Search it for a component name to copy the correct prop shape instead of guessing. Delete it when done.
+   It is a real, compilable MDX file that demonstrates the components for that shell and their exact props. Search it for a component name to copy the correct prop shape instead of guessing. Delete it when done.
 3. Start from a skeleton when useful: `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll`. `create` and `guide` refuse to overwrite an existing file unless `--force` is passed.
 4. Write the semantic MDX into the user's `.mdx` file (see Authoring rules).
 5. Validate before rendering:
@@ -27,7 +27,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
    ```
    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). Bake a default only when the user asks for one. Content MDX never sets appearance — it is carrier/tooling territory, not content.
+7. **Appearance (optional)**: pages ship with a reader-facing appearance menu — palette (`aurora` cool blue, `ember` warm gold), a dark/light toggle, and a component style pack (`manuscript` editorial marginalia, `classic` boxed cards). The shipped default is aurora × manuscript × light; choices persist in localStorage across both carriers. You can bake different compile-time defaults: `--skin ember --default-mode dark --style classic` (or env `CONCEPT_ATLAS_SKIN` / `CONCEPT_ATLAS_DEFAULT_MODE` / `CONCEPT_ATLAS_STYLE` on the repo build). `--default-mode` only honors `dark`/`light`; `system` is accepted by the CLI but resolves to the carrier default (`light`). Bake a default only when the user asks for one. Content MDX never sets appearance — it is carrier/tooling territory, not content.
 8. For several documents, pass them all in one call: `npx concept-atlas-dense-explain a.mdx b.mdx c.mdx -o dist --force [--concurrency 3]`. `-o` is then a directory. The batch validates everything first and builds in parallel. Builds only bundle the heavy renderers the content uses: a page with no `<Math>`/`<Mermaid>` skips KaTeX (its ~1.4MB inlined fonts) and Mermaid, shrinking a typical scroll article from ~5MB to ~250KB. Do not add dummy `<Math>`/`<Mermaid>` nodes to "enable" them — write the components only when the content needs them. Add `--link-assets` when the page carries many screenshots and size matters.
 9. Report the shell, output path, validation result (errors/warnings), and limitations. Do not claim interactions you did not verify.
 
@@ -35,6 +35,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 
 - `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 table of contents and reading progress from section titles — do not hand-build navigation.
+- The browser tab comes from the shell, not the build flags: `ExplainPage title="..."` (atlas) or `ScrollHeader title="..."` (scroll) becomes the `<title>`, so give it a real, specific document name — never leave a placeholder like "主题名称". The favicon is a fixed 📃 document emoji on every generated page.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families
@@ -42,8 +43,8 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 - Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
 - Argument and evidence: `Evidence`, `Invariant`, `FailureMode`, `Tradeoff`, `LearningObjectives`, `KeyQuestion`
 - Information models: `Flow`, `Timeline`, `Compare`, `DecisionMatrix`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`
-- Reading and layout: `Insight`, `Callout`, `Details`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`
-- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `Figure`, `Cite`, `References`
+- Reading and layout: `Insight`, `Callout`, `Details`, `NoteGrid`, `Tabs`, `Columns`, `Stack`, `Grid`, `Split`, `ScrollGrid`, `ScrollPair`, `ScrollToc`
+- Graphics and extensions: `Mermaid`, `RelationMap`, `RelationPath`, `Math`, `MathBlock`, `Chart`, `Figure` (alias `Image`), `Cite`, `References`
 
 ## Authoring rules
 
@@ -61,7 +62,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 
 ## Validation diagnostics
 
-`validate` and the build print `CODE line:column message`. Fix these `error`s before building: `UNKNOWN_COMPONENT`, `CARRIER_MISSING`, `CARRIER_CONFLICT`, `CARRIER_MODE_MISMATCH`, `NODE_MISSING_ID`, `DUPLICATE_NODE_ID`, `NODE_MISSING_TITLE`, `MISSING_PARENT`, `GRAPH_ROOT_UNRESOLVED`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_RELATION_TYPE`, `RELATION_MISSING_LABEL`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `GRAPH_MISSING_ROOT`, `ASSET_MISSING`.
+`validate` and the build print `CODE line:column message`. Fix these `error`s before building: `UNKNOWN_COMPONENT`, `CARRIER_MISSING`, `CARRIER_CONFLICT`, `CARRIER_MODE_MISMATCH`, `NODE_MISSING_ID`, `DUPLICATE_NODE_ID`, `NODE_MISSING_TITLE`, `MISSING_PARENT`, `GRAPH_ROOT_UNRESOLVED`, `REF_MISSING_ID`, `REF_UNRESOLVED`, `RELATION_FROM_UNRESOLVED`, `RELATION_TO_UNRESOLVED`. Warnings worth fixing: `NODE_MISSING_SUMMARY`, `NODE_NO_CORE_CONTENT`, `UNKNOWN_LEVEL`, `UNKNOWN_RELATION_TYPE`, `RELATION_MISSING_LABEL`, `RELATION_SELF`, `PROP_EXPECTS_ARRAY`, `MATH_CHILDREN_BRACES`, `PROSE_EXPRESSION`, `FRONTMATTER_UNSUPPORTED`, `GRAPH_MISSING_ROOT`, `FIGURE_MISSING_SRC`, `ASSET_MISSING`, `REF_SELF`; `NO_ROOT_LEVEL` and `MULTIPLE_ROOT_LEVEL` are warnings that `--strict` promotes to errors.
 
 ## Before you report
 

package/template/index.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E📃%3C/text%3E%3C/svg%3E" />
     <title>Concept Atlas · 概念缩放式知识图谱</title>
     <script>
       (function () {

package/template/scripts/build.mjs

@@ -3,6 +3,7 @@ import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
 import { normalizeSkin, normalizeStyle } from '../src/model/skins.js';
+import { extractPageTitle } from '../src/model/validate-content.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -24,6 +25,20 @@ function appearanceDefines() {
   return define;
 }
 
+/**
+ * The tab title comes from the mounted demo document, not the carrier shell:
+ * the repository mounts content/components-demo.mdx in index.html while the
+ * npm template mounts content/compile-runtime.mdx, so both are probed and the
+ * first existing file supplies its <ExplainPage>/<ScrollHeader> title.
+ */
+function pageTitleFor(entry) {
+  const demos = entry === 'scroll.html'
+    ? ['content/scroll-reading-demo.mdx']
+    : ['content/components-demo.mdx', 'content/compile-runtime.mdx'];
+  const demo = demos.map(name => path.resolve(rootDir, name)).find(file => fs.existsSync(file));
+  return demo ? extractPageTitle(fs.readFileSync(demo, 'utf8')) : null;
+}
+
 async function runBuild() {
   console.log('🚀 开始构建 Concept Atlas 知识讲解页面...');
 
@@ -44,9 +59,12 @@ async function runBuild() {
     // 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,
+        define: entryDefine,
         build: {
           outDir: 'dist',
           emptyOutDir: index === 0,

package/template/scroll.html

@@ -3,6 +3,7 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'%3E%3Ctext y='.9em' font-size='90'%3E📃%3C/text%3E%3C/svg%3E" />
     <title>Concept Atlas · 连续阅读示例</title>
     <script>
       (function () {

package/template/src/model/validate-content.js

@@ -598,3 +598,28 @@ export function detectFeatures(source) {
     mermaid: used.has('Mermaid'),
   };
 }
+
+/** JSX string literals decode these five entities; a single pass avoids
+ * double-decoding sequences like `<`. */
+const ENTITY_MAP = { amp: '&', lt: '<', gt: '>', quot: '"', '#39': "'" };
+const decodeEntities = text => text.replace(/&(amp|lt|gt|quot|#39);/g, (_, entity) => ENTITY_MAP[entity]);
+
+/**
+ * Reads the browser-tab title from the MDX source without rendering: the atlas
+ * shell declares it on <ExplainPage title="...">, the scroll shell on
+ * <ScrollHeader title="...">. Only quoted string props count — a `{...}`
+ * expression title cannot be known at build time. Returns null when no static
+ * title exists, so the build keeps the carrier's default <title>.
+ */
+export function extractPageTitle(source) {
+  const tags = tokenize(maskIgnored(source));
+  for (const shell of ['ExplainPage', 'ScrollHeader']) {
+    const tag = tags.find(item => item.name === shell && item.kind !== 'close');
+    if (!tag) continue;
+    const attr = attrsToMap(tag.attrs).title;
+    if (attr && attr.hasValue && attr.quoted && attr.value.trim()) {
+      return decodeEntities(attr.value).trim();
+    }
+  }
+  return null;
+}

package/template/vite.config.js

@@ -161,6 +161,31 @@ function resolveToken(raw, validate) {
   return validate(value);
 }
 
+/**
+ * Bakes the per-document <title> into the carrier HTML.
+ *
+ * The CLI (and the repository's demo build) extract the title from the MDX
+ * source — <ExplainPage title="..."> for the atlas carrier, <ScrollHeader
+ * title="..."> for scroll — and forward it as the `__ATLAS_PAGE_TITLE__`
+ * define. When present, the carrier's default <title> is replaced so the
+ * browser tab names the actual document instead of the demo placeholder.
+ * Without the define the default title survives unchanged.
+ */
+function pageTitle() {
+  let title = null;
+  return {
+    name: 'concept-atlas-page-title',
+    configResolved(config) {
+      title = resolveToken(config.define && config.define.__ATLAS_PAGE_TITLE__, value => value.trim() || null);
+    },
+    transformIndexHtml(html) {
+      if (!title) return html;
+      const escaped = title.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+      return html.replace(/<title>[\s\S]*?<\/title>/, `<title>${escaped}</title>`);
+    },
+  };
+}
+
 export default defineConfig({
   plugins: [
     inlineMdxAssets(),
@@ -173,6 +198,7 @@ export default defineConfig({
     react(),
     optionalFeatures(),
     appearanceDefaults(),
+    pageTitle(),
     viteSingleFile(),
   ],
   build: {