concept-atlas-dense-explain 0.2.2 → 0.3.0

package/bin/cli.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { access, constants, mkdir, readFile, rm, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { build } from 'vite';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const templateRoot = path.join(packageRoot, 'template');
+const args = process.argv.slice(2);
+
+function usage() {
+  console.log('Usage:');
+  console.log('  npx concept-atlas-dense-explain <input.mdx> [--mode atlas|scroll] [-o output.html] [--force]');
+  console.log('  npx concept-atlas-dense-explain render <input.mdx> [--mode atlas|scroll] [-o output.html] [--force]');
+  console.log('  npx concept-atlas-dense-explain create <output.mdx> [--mode atlas|scroll] [--force]');
+}
+
+async function exists(filePath) {
+  try { await access(filePath, constants.F_OK); return true; } catch { return false; }
+}
+
+function flagValue(flags, names) {
+  for (const name of names) {
+    const index = flags.indexOf(name);
+    if (index >= 0) return flags[index + 1];
+  }
+  return null;
+}
+
+const command = ['help', 'create', 'new', 'render'].includes(args[0]) ? args.shift() : 'render';
+
+if (command === 'help') { usage(); process.exit(0); }
+
+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)) {
+    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' ? `\
+<ExplainPage id="topic-id" title="主题名称" summary="用一句话说明这个主题解决什么问题。">
+  <ConceptGraph root="root-node">
+    <ConceptNode id="root-node" title="核心概念" level="L0" summary="给读者建立整体认知。">
+      <Overview>先用直觉解释这个主题是什么，以及为什么值得理解。</Overview>
+      <Definition>给出准确、可检查的定义。</Definition>
+      <Mechanism>说明输入如何经过关键步骤，产生什么输出或结果。</Mechanism>
+      <Boundary>说明适用范围、限制条件和容易混淆的反例。</Boundary>
+      <Children><ConceptRef id="first-branch" /><ConceptRef id="second-branch" /></Children>
+    </ConceptNode>
+
+    <ConceptNode id="first-branch" title="第一条关键分支" level="L1" parent="root-node">
+      <Overview>解释第一个重要组成部分。</Overview>
+      <Example title="典型例子">填写一个具体例子，帮助读者验证理解。</Example>
+    </ConceptNode>
+
+    <ConceptNode id="second-branch" title="第二条关键分支" level="L1" parent="root-node">
+      <Overview>解释第二个重要组成部分。</Overview>
+      <Boundary>填写它的边界、代价或常见误区。</Boundary>
+    </ConceptNode>
+
+    <Relation from="first-branch" to="second-branch" type="depends-on" label="依赖" />
+  </ConceptGraph>
+</ExplainPage>
+` : `\
+<ScrollDocument>
+  <ScrollHeader title="主题名称">用一两句话说明主题、背景和读者应该带走的判断。</ScrollHeader>
+
+  <ScrollSection title="先建立整体认知">
+    <ScrollProse>先解释主题是什么、解决什么问题，以及它和相邻概念的区别。</ScrollProse>
+    <Insight title="核心判断">填写这篇文章最重要、最值得记住的一句话。</Insight>
+  </ScrollSection>
+
+  <ScrollSection title="解释关键机制">
+    <ScrollProse>按输入、步骤、输出的顺序解释过程，不要只罗列名词。</ScrollProse>
+    <Flow title="处理流程" steps={[{title:'输入',description:'原始条件或数据'},{title:'处理',description:'关键变化或判断'},{title:'输出',description:'结果与可观察证据'}]} />
+  </ScrollSection>
+
+  <ScrollSection title="边界与实践">
+    <ScrollGrid columns="2">
+      <Boundary>填写适用范围、限制条件和反例。</Boundary>
+      <Example title="典型案例">填写一个能验证前文解释的具体案例。</Example>
+    </ScrollGrid>
+  </ScrollSection>
+</ScrollDocument>
+`;
+  await writeFile(output, template, 'utf8');
+  console.log(`Created ${mode} MDX template: ${output}`);
+  process.exit(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');
+
+if (!input || path.extname(input).toLowerCase() !== '.mdx' || !(await exists(input))) {
+  console.error('Provide an existing .mdx input file.');
+  usage();
+  process.exit(1);
+}
+
+const source = await readFile(input, 'utf8');
+const mode = modeFlag || (/<ScrollDocument\b/.test(source) ? 'scroll' : /<ExplainPage\b|<ConceptGraph\b/.test(source) ? 'atlas' : null);
+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.`);
+  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) {
+    await rm(output, { force: true });
+    await rename(generatedEntry, output);
+  }
+  console.log(`Built ${mode} HTML: ${output}`);
+} catch (error) {
+  console.error('Build failed:', error);
+  process.exit(1);
+}

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "concept-atlas-dense-explain",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Portable dense-explanation skill and MDX concept atlas template",
   "type": "module",
   "bin": {
-    "concept-atlas-dense-explain": "bin/install.mjs"
+    "concept-atlas-dense-explain": "bin/cli.mjs"
   },
   "files": [
     "bin",
+    "template",
     "skill"
   ],
+  "dependencies": {
+    "@mdx-js/rollup": "^3.0.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "clsx": "^2.1.1",
+    "d3": "^7.9.0",
+    "lucide-react": "^0.475.0",
+    "mermaid": "^11.17.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vite": "^5.4.14",
+    "vite-plugin-singlefile": "^2.1.0"
+  },
   "keywords": [
     "codex",
     "skill",

package/skill/SKILL.md

@@ -1,98 +1,25 @@
----
-name: concept-atlas-dense-explain
-description: Build structured explanation webpages with the bundled React/Vite/MDX components. Use this skill whenever the user asks for a technical explanation, concept map, layered knowledge page, interactive explanation, component-based knowledge page, or webpage resembling the Concept Atlas exemplar. Before generating anything, ask whether the user wants (A) a scrollable long-form page assembled from semantic components or (B) the full Concept Atlas interactive framework with concept navigation and relation graph. Do not choose the output mode silently.
----
-
-# Concept Atlas Dense Explain
-
-This is an Agent Skills-compatible skill. Keep the instructions and generated content portable across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Cline, GitHub Copilot, and other agents that support `SKILL.md`.
-
-Use the bundled components and, when selected, the complete template to turn knowledge into a structured explanation. The required deliverable is a built webpage, normally `dist/index.html`; it may be a scrollable component page or a full interactive Concept Atlas.
+---
+name: concept-atlas-dense-explain
+description: Use the Concept Atlas npm CLI to generate AI-editable MDX starters and compile standalone HTML from semantic MDX when a technical explanation, concept map, layered knowledge page, or interactive explanation is requested.
+---
 
-## Mandatory mode selection
+# Concept Atlas Dense Explain
 
-Before writing content, determine the output mode. If the user has not already chosen one, ask exactly one concise clarification:
+Use the `concept-atlas-dense-explain` npm CLI. This skill is intentionally lightweight: do not copy implementation files from the skill directory or recreate the React/Vite application manually.
 
-> 你希望生成哪种形式？A. 使用语义组件组装的滚动型讲解网页；B. 使用完整 Concept Atlas 框架的交互式网页（概念树、节点下钻、关系图）。如果没有偏好，我推荐 B。
+## Workflow
 
-Do not start implementation until the user chooses A or B. If the user explicitly requests both, create separate outputs only when the workspace and scope support them.
+1. Choose the carrier before writing any MDX. A (continuous reading) uses a document-flow MDX structure; B (interactive Concept Atlas) uses a concept-graph MDX structure. Recommend B when the reader needs concept navigation or a relation graph; recommend A for a conventional HTML reading flow with denser horizontal component grids.
+2. When a starting point is useful, create a single MDX file with `npx concept-atlas-dense-explain create <file>.mdx --mode atlas|scroll`, then rewrite it with the AI.
+3. For B, write semantic MDX to the user-selected `.mdx` file. Include one `L0`, multiple `L1` branches, useful depth, `Children`/`ConceptRef`, and labeled `Relation`s. This content renders through the interactive atlas entry.
+4. For A, write semantic MDX to the user-selected `.mdx` file with `ScrollDocument`, `ScrollHeader`, `ScrollSection`, `ScrollProse`, and `ScrollGrid`. Do not wrap it in `ExplainPage`, `ConceptGraph`, or `ConceptNode`. This content renders through the continuous-reader entry.
+5. Do not try to make one MDX file serve both carriers. The template ships both sample entries for reference, but they represent distinct authoring formats.
+6. Compile directly with `npx concept-atlas-dense-explain <file>.mdx --mode atlas|scroll`. The output is a standalone `.html` beside the MDX unless `-o` is provided. The mode can be detected from the top-level carrier, but specify it when the file is ambiguous.
+7. Report the selected mode, output path, and limitations. Do not claim interactions that were not verified.
 
-### Mode A — Scrollable component page
+## Content rules
 
-Use the existing React/Vite shell and compose the page from supported semantic and presentation components. A natural vertical reading layout is valid in this mode. It does not require a 15–25 node concept graph or relation graph unless the user asks for those features. Keep content semantic and avoid handwritten CSS, SVG, or replacement app code.
-
-### Mode B — Interactive Concept Atlas
-
-Use the complete bundled template. The page must contain one `L0` root, multiple `L1` branches, lower-level nodes where useful, `Children` / `ConceptRef` navigation, and labeled cross-branch `Relation`s. The template provides the three-column node explorer, graph view, search, filters, URL node state, keyboard navigation, and responsive behavior.
-
-## Mandatory preflight and mode-specific fallback rule
-
-Before generating content, resolve the directory containing this `SKILL.md` and verify that these bundled files are readable:
-
-- `assets/template/content/compile-runtime.mdx`
-- `assets/template/src/app/App.jsx`
-- `assets/template/src/components/MDXComponents.jsx`
-- `assets/template/src/model/normalize-content.js`
-- `references/components.md`
-
-Read the component contract before writing. For Mode B, also read the exemplar and verify the complete template. If the bundled template is unavailable, report that Mode B cannot be completed and offer Mode A only after the user agrees. Never silently downgrade Mode B to a long page or custom mockup.
-
-For Mode B, the template is the implementation boundary: do not edit `src/`, styles, `index.html`, Vite configuration, or package dependencies for a content task; replace only the MDX content after copying the template. For Mode A, use the host project's existing shell and do not introduce a replacement application unless requested.
-
-## Step 0 — Read the exemplar before writing Mode B content
-
-For Mode B, read [assets/template/content/compile-runtime.mdx](assets/template/content/compile-runtime.mdx) in full first. It is the **reference standard**, not just a file to overwrite. Study its shape before generating anything:
-
-- 1 `L0` root, ~5 `L1` branches, 2–3 children per branch, descending to `L3`/`L4` where the topic deserves it.
-- Every `title` is a claim ("ABI 破坏：能链接，不等于能调用"), and every `summary` is a one-sentence judgment.
-- Important nodes carry 3–6 semantic components, not one lone paragraph.
-- Claims are backed by concrete commands, numbers, or named artifacts (`readelf -Ws`, `nm -C`, `objdump -dr`, `.bss`, ASLR).
-- Cross-branch meaning is encoded as labeled `Relation`s, not prose.
-
-## Workflow
-
-1. Ask for and record Mode A or Mode B before implementation.
-2. Read [references/components.md](references/components.md); for Mode B, resolve and copy the complete `assets/template` directory and read the exemplar first.
-3. Mode A: create the requested scrollable content using semantic components and the existing shell. Mode B: replace only the template content MDX, preserving React, CSS, graph, and build files.
-4. Mode B: model one `L0` root, then `L1` structure, `L2` mechanisms, and optional `L3/L4` boundaries or failures. Add `parent`/`Children` and labeled cross-branch `Relation`s.
-5. In either mode, keep content semantic: do not encode layout, coordinates, CSS, or SVG in MDX. Use supported model and presentation components where they clarify structure.
-6. Run the relevant validator, then `npm install` and `npm run build`. If validation or build fails, revise the content rather than returning an unverified substitute.
-7. Mode B: verify node switching, graph mode, search, URL `#node=...`, keyboard navigation, and responsive layout. Return the built output path and state which mode was used.
-
-## Delivery summary
-
-After generation, briefly explain:
-
-- which mode the user selected (`A` scrollable component page or `B` interactive Concept Atlas);
-- what the skill contributed (semantic components, concept tree, relations, or template interactions);
-- the output path and the main ways to inspect or continue editing it.
-
-Keep this summary concise. Do not merely list files or claim interactive features that were not built.
-
-## Content rules
-
-- Start with a one- or two-sentence core judgment.
-- Use tables/flows for comparison and causality; use short paragraphs only for explanation.
-- Every dense block should contain a conclusion, evidence, or limitation.
-- Prefer 2–4 columns on wide screens and natural stacking on narrow screens.
-- Do not invent unsupported components or relation types. Read [references/components.md](references/components.md) for the supported semantic API.
-- Mode B should aim for the exemplar's scale: roughly 1 root, 4–5 `L1` branches, ~15–25 nodes total. A thin graph is a failure in Mode B, but is not a requirement for Mode A.
-
-## Self-check before finishing
-
-Run this checklist and revise until every item passes. If an item fails, fix the content instead of adding decoration.
-
-- [ ] The user selected Mode A or Mode B before implementation.
-- [ ] Every key section or node has a claim, summary, or clear reading purpose.
-- [ ] Mode B has one `L0`, multiple `L1`s, useful depth, concrete evidence, and labeled whitelisted relations.
-- [ ] First screen shows the core claim plus 3–5 key facts; long detail lives in `Details` / `Tabs` when appropriate.
-- [ ] No CSS, coordinates, SVG, or layout instructions appear in the MDX.
-- [ ] Mode B changes only the template's MDX content; no replacement JSX or custom vertical article page was created.
-- [ ] The relevant validator passes before the build.
-- [ ] Mode B builds and node switching, graph mode, search, `#node=...`, and keyboard navigation all work.
-
-## Portable template
-
-The self-contained React/Vite/MDX implementation is in [assets/template](assets/template). It is required for Mode B and optional for Mode A when the host project already provides an equivalent shell. For Mode B, copy it into a project, replace `content/compile-runtime.mdx` **after studying it**, run `npm install`, then `npm run build`. The template has no dependency on the source repository's absolute paths.
-
-For the component contract, relation whitelist, and level semantics, read [references/components.md](references/components.md). For the exemplar breakdown, density targets, and prompt wording, read [references/prompting.md](references/prompting.md).
+- Keep MDX semantic; do not write CSS, coordinates, SVG, or replacement application code.
+- Give important nodes a claim-like title, a one-sentence summary, evidence, and meaningful components.
+- Use only components and relation types supported by the built-in renderer.
+- If the CLI or npm registry is unavailable, report the blocker instead of copying the implementation into the skill.

package/template/content/scroll-reading-demo.mdx

@@ -0,0 +1,31 @@
+<ScrollDocument>
+  <ScrollHeader title="用概念模型组织一次技术判断">同一套语义组件可以脱离图谱和节点面板，按传统文档流连续阅读。正文保持高信息密度，模型在需要比较、推导或收敛时占满可用宽度。</ScrollHeader>
+
+  <ScrollSection title="先识别推理结构">
+    <ScrollProse>模型不是内容的装饰。它们分别处理并列要素、二维定位、变量关系、论证层级和筛选过程。先确认关系形状，读者才能用最短路径验证结论。</ScrollProse>
+    <ScrollGrid columns="3">
+      <FrameworkModel title="对象" type="elements" elements={[{title:'系统',description:'明确正在判断什么'},{title:'边界',description:'确定讨论范围'}]} />
+      <FrameworkModel title="约束" type="elements" elements={[{title:'时间',description:'决策窗口与反馈周期'},{title:'资源',description:'人力、预算和技术限制'}]} />
+      <FrameworkModel title="证据" type="elements" elements={[{title:'行为',description:'真实使用与任务结果'},{title:'数据',description:'可重复检查的观察'}]} />
+    </ScrollGrid>
+  </ScrollSection>
+
+  <ScrollSection title="在二维关系中定位选择">
+    <ScrollProse>当候选方案同时受两个变量约束时，矩阵比线性列表更容易暴露优先级。</ScrollProse>
+    <ScrollGrid columns="2">
+      <MatrixModel title="影响 / 成本矩阵" xLabel="实施成本" yLabel="预期影响" cells={[{title:'优先投入',description:'高影响 / 低成本',tone:'success'},{title:'审慎评估',description:'高影响 / 高成本',tone:'warn'},{title:'快速验证',description:'低影响 / 低成本'},{title:'暂缓处理',description:'低影响 / 高成本',tone:'danger'}]} />
+      <Stack gap="md"><Insight title="先做什么">优先验证高影响、低成本的选择，再为高成本方案准备证据。</Insight><Callout title="阅读判断">矩阵只帮助定位，不替代成本估算或影响验证。</Callout><NoteGrid notes={[{title:'输入',content:'候选方案与约束'},{title:'输出',content:'下一轮验证顺序'}]} /></Stack>
+    </ScrollGrid>
+  </ScrollSection>
+
+  <ScrollSection title="把假设压缩为可讨论的关系" wide>
+    <ScrollGrid columns="3"><FormulaModel title="用户价值" formula="用户价值 = 新体验 - 旧体验 - 替换成本" variables={[{symbol:'新体验',description:'方案带来的增量收益'},{symbol:'旧体验',description:'现有替代方案的价值'},{symbol:'替换成本',description:'学习、迁移和风险'}]} /><DecisionMatrix title="需要确认" headers={['变量','检查']} rows={[['新体验','是否改善核心任务'],['旧体验','能否满足需求'],['替换成本','迁移是否可接受']]} /><FailureMode symptom="价值无法被感知" cause="只描述新功能，不解释替换路径" evidence="试用后仍回到旧方案" remedy="缩短迁移步骤并验证关键任务" /></ScrollGrid>
+  </ScrollSection>
+
+  <ScrollSection title="组织证据，再收敛到行动"><ScrollGrid columns="3"><PyramidModel title="论证层级" levels={[{title:'结论',description:'读者需要带走的判断'},{title:'理由',description:'支撑判断的关键分组'},{title:'证据',description:'事实、数据与案例'}]} /><FunnelModel title="决策过程" steps={[{title:'收集',description:'汇集候选信息'},{title:'筛选',description:'排除不满足约束的项'},{title:'验证',description:'检查关键假设'},{title:'行动',description:'形成下一步决策'}]} /><Tradeoff title="输出质量" options={[{name:'压缩结论',benefit:'阅读快',cost:'上下文少',when:'总览'},{name:'保留证据',benefit:'可追溯',cost:'阅读长',when:'关键决策'}]} /></ScrollGrid></ScrollSection>
+
+  <ScrollSection title="保留可追溯性">
+    <Evidence command="npm run validate" observes="确认内容结构完整，再把关键结论连接回原始证据。" />
+    <Insight title="核心原则">选择组件是为了让关系更容易被检验，不是为了把阅读页面做成一组不同样式的卡片。</Insight>
+  </ScrollSection>
+</ScrollDocument>

package/{skill/assets/template → template}/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "version": "0.1.0",
   "type": "module",
-  "scripts": { "dev": "vite", "validate": "node scripts/validate-content.mjs", "build": "npm run validate && node scripts/build.mjs", "clean:temp": "node scripts/clean-temp.mjs" },
+  "scripts": { "dev": "vite", "validate": "node scripts/validate-content.mjs", "build": "npm run validate && node scripts/build.mjs", "clean:temp": "node scripts/clean-temp.mjs" },
   "dependencies": {
     "@mdx-js/rollup": "^3.0.1",
     "clsx": "^2.1.1",

package/template/scripts/build.mjs

@@ -0,0 +1,43 @@
+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, '..');
+
+async function runBuild() {
+  console.log('🚀 开始构建 Concept Atlas 知识讲解页面...');
+
+  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'];
+
+    // 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,
+        build: {
+          outDir: 'dist',
+          emptyOutDir: index === 0,
+          rollupOptions: { input: path.resolve(rootDir, entry) },
+        }
+      });
+    }
+
+    console.log(`✅ 构建成功！产物已生成到 ${carriers.map(entry => `dist/${entry}`).join(' 和 ')}。`);
+  } catch (err) {
+    console.error('❌ 构建失败：', err);
+    process.exit(1);
+  }
+}
+
+runBuild();

package/{skill/assets/template → template}/scripts/validate-content.mjs

@@ -1,48 +1,48 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url));
-const rootDir = path.resolve(scriptDir, '..');
-const contentPath = path.join(rootDir, 'content', 'compile-runtime.mdx');
-const source = fs.readFileSync(contentPath, 'utf8');
-const failures = [];
-const nodePattern = /<ConceptNode\b([^>]*)>([\s\S]*?)<\/ConceptNode>/g;
-const relationPattern = /<Relation\b([^>]*)\/>/g;
-const attributes = text => Object.fromEntries([...text.matchAll(/([\w-]+)=(?:"([^"]*)"|'([^']*)')/g)].map(match => [match[1], match[2] ?? match[3] ?? '']));
-const nodes = [...source.matchAll(nodePattern)].map(match => ({ ...attributes(match[1]), body: match[2] }));
-const relations = [...source.matchAll(relationPattern)].map(match => attributes(match[1]));
-const ids = new Set(nodes.map(node => node.id));
-const allowedRelations = new Set(['prerequisite', 'causes', 'produces', 'uses', 'implements', 'contrasts', 'depends-on', 'exception-of', 'precedes']);
-
-if (!source.includes('<ExplainPage')) failures.push('missing ExplainPage');
-if (!source.includes('<ConceptGraph')) failures.push('missing ConceptGraph');
-if (nodes.filter(node => node.level === 'L0').length !== 1) failures.push('expected exactly one L0 root');
-if (nodes.filter(node => node.level === 'L1').length < 4) failures.push('expected at least four L1 branches');
-if (nodes.length < 15) failures.push(`expected at least 15 nodes, found ${nodes.length}`);
-if (!nodes.some(node => ['L3', 'L4'].includes(node.level))) failures.push('expected L3 or L4 depth');
-if (relations.length < 8) failures.push(`expected at least 8 relations, found ${relations.length}`);
-
-for (const node of nodes) {
-  if (!node.id) failures.push('node is missing id');
-  if (!node.title) failures.push(`${node.id || '<unknown>'} is missing title`);
-  if (!node.summary) failures.push(`${node.id || '<unknown>'} is missing summary`);
-  if (node.parent && !ids.has(node.parent)) failures.push(`${node.id} references missing parent ${node.parent}`);
-  if (!/(<(Definition|Mechanism|Example|Evidence|Boundary|Details|Callout|Counterexample|Glossary|Input|Output)\b)/.test(node.body)) {
-    failures.push(`${node.id} lacks a core semantic component`);
-  }
-}
-
-for (const relation of relations) {
-  if (!ids.has(relation.from) || !ids.has(relation.to)) failures.push(`relation references missing node: ${relation.from} -> ${relation.to}`);
-  if (!allowedRelations.has(relation.type)) failures.push(`unsupported relation type: ${relation.type}`);
-  if (!relation.label) failures.push(`relation ${relation.from} -> ${relation.to} is missing label`);
-}
-
-if (failures.length) {
-  console.error('Concept Atlas content validation failed:');
-  for (const failure of failures) console.error(`- ${failure}`);
-  process.exit(1);
-}
-
-console.log(`Concept Atlas content validation passed (${nodes.length} nodes, ${relations.length} relations).`);
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(scriptDir, '..');
+const contentPath = path.join(rootDir, 'content', 'compile-runtime.mdx');
+const source = fs.readFileSync(contentPath, 'utf8');
+const failures = [];
+const nodePattern = /<ConceptNode\b([^>]*)>([\s\S]*?)<\/ConceptNode>/g;
+const relationPattern = /<Relation\b([^>]*)\/>/g;
+const attributes = text => Object.fromEntries([...text.matchAll(/([\w-]+)=(?:"([^"]*)"|'([^']*)')/g)].map(match => [match[1], match[2] ?? match[3] ?? '']));
+const nodes = [...source.matchAll(nodePattern)].map(match => ({ ...attributes(match[1]), body: match[2] }));
+const relations = [...source.matchAll(relationPattern)].map(match => attributes(match[1]));
+const ids = new Set(nodes.map(node => node.id));
+const allowedRelations = new Set(['prerequisite', 'causes', 'produces', 'uses', 'implements', 'contrasts', 'depends-on', 'exception-of', 'precedes']);
+
+if (!source.includes('<ExplainPage')) failures.push('missing ExplainPage');
+if (!source.includes('<ConceptGraph')) failures.push('missing ConceptGraph');
+if (nodes.filter(node => node.level === 'L0').length !== 1) failures.push('expected exactly one L0 root');
+if (nodes.filter(node => node.level === 'L1').length < 4) failures.push('expected at least four L1 branches');
+if (nodes.length < 15) failures.push(`expected at least 15 nodes, found ${nodes.length}`);
+if (!nodes.some(node => ['L3', 'L4'].includes(node.level))) failures.push('expected L3 or L4 depth');
+if (relations.length < 8) failures.push(`expected at least 8 relations, found ${relations.length}`);
+
+for (const node of nodes) {
+  if (!node.id) failures.push('node is missing id');
+  if (!node.title) failures.push(`${node.id || '<unknown>'} is missing title`);
+  if (!node.summary) failures.push(`${node.id || '<unknown>'} is missing summary`);
+  if (node.parent && !ids.has(node.parent)) failures.push(`${node.id} references missing parent ${node.parent}`);
+  if (!/(<(Definition|Mechanism|Example|Evidence|Boundary|Details|Callout|Counterexample|Glossary|Input|Output)\b)/.test(node.body)) {
+    failures.push(`${node.id} lacks a core semantic component`);
+  }
+}
+
+for (const relation of relations) {
+  if (!ids.has(relation.from) || !ids.has(relation.to)) failures.push(`relation references missing node: ${relation.from} -> ${relation.to}`);
+  if (!allowedRelations.has(relation.type)) failures.push(`unsupported relation type: ${relation.type}`);
+  if (!relation.label) failures.push(`relation ${relation.from} -> ${relation.to} is missing label`);
+}
+
+if (failures.length) {
+  console.error('Concept Atlas content validation failed:');
+  for (const failure of failures) console.error(`- ${failure}`);
+  process.exit(1);
+}
+
+console.log(`Concept Atlas content validation passed (${nodes.length} nodes, ${relations.length} relations).`);

package/template/scroll.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN" data-carrier="scroll">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Concept Atlas · 连续阅读示例</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/scroll-main.jsx"></script>
+  </body>
+</html>