concept-atlas-dense-explain 0.8.0 → 0.9.0

package/bin/cli.mjs

@@ -156,12 +156,13 @@ if (command === 'create' || command === 'new') {
       <Children><ConceptRef id="first-branch" /><ConceptRef id="second-branch" /></Children>
     </ConceptNode>
 
-    <ConceptNode id="first-branch" title="第一条关键分支" level="L1" parent="root-node">
+    <ConceptNode id="first-branch" title="第一条关键分支" level="L1" parent="root-node" summary="第一条关键分支解决什么问题，以及它为什么值得先理解。">
       <Overview>解释第一个重要组成部分。</Overview>
       <Example title="典型例子">填写一个具体例子，帮助读者验证理解。</Example>
+      <CodeBlock language="bash" title="验证方式" code="npm run validate" lineNumbers />
     </ConceptNode>
 
-    <ConceptNode id="second-branch" title="第二条关键分支" level="L1" parent="root-node">
+    <ConceptNode id="second-branch" title="第二条关键分支" level="L1" parent="root-node" summary="第二条关键分支解决什么问题，以及它和第一条分支如何配合。">
       <Overview>解释第二个重要组成部分。</Overview>
       <Boundary>填写它的边界、代价或常见误区。</Boundary>
     </ConceptNode>
@@ -182,6 +183,7 @@ if (command === 'create' || command === 'new') {
   <ScrollSection title="解释关键机制">
     <ScrollProse>按输入、步骤、输出的顺序解释过程，不要只罗列名词。</ScrollProse>
     <Flow title="处理流程" steps={[{title:'输入',description:'原始条件或数据'},{title:'处理',description:'关键变化或判断'},{title:'输出',description:'结果与可观察证据'}]} />
+    <CodeBlock language="bash" title="实践命令" code="npm run validate" caption="通用代码块可以放在任意章节；需要逐行讲解时加 lineNumbers。" />
   </ScrollSection>
 
   <ScrollSection title="边界与实践">

package/package.json

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

package/skill/SKILL.md

@@ -38,7 +38,7 @@ Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill i
 
 ## Component families
 
-- Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `Boundary`, `Example`, `Counterexample`, `Prerequisite`, `Input`, `Output`, `Glossary`
+- Node semantics: `Overview`, `Definition`, `Mechanism`, `Implementation`, `CodeBlock`, `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`, `ScrollPair`, `ScrollToc`
@@ -52,6 +52,7 @@ Drive everything through the `concept-atlas-dense-explain` npm CLI. This skill i
 - Array props are arrays of objects: `Flow steps={[{title, description}]}`, `Timeline events={[{label, content}]}`, `MatrixModel cells={[{title, description, tone}]}`, `DecisionMatrix headers={[...]} rows={[[...]]}`, `Chart data={[{label, value}]}`, `References items={[{id, authors, year, title, url, source}]}`. The validator warns (`PROP_EXPECTS_ARRAY`) when an array prop gets a string or non-array.
 - `Relation type` must be one of `prerequisite`, `causes`, `produces`, `uses`, `implements`, `contrasts`, `depends-on`, `exception-of`, `precedes`, and each `Relation` needs a `label`. Parent/child hierarchy is implicit (via `parent` and `Children`/`ConceptRef`) — do not express it with a `Relation`.
 - **Math**: MDX parses `{ ... }` in children as expressions, so pass LaTeX with braces or backslashes through `formula`: `<Math formula="r_{\text{ann}} = (1 + r)^{12} - 1" />`, `<MathBlock formula="I(x) = -\log_2 p(x)" variables={[{symbol, description}]} />`. Brace-free children such as `<Math>\log_2 N</Math>` are fine. The validator warns (`MATH_CHILDREN_BRACES`).
+- **CodeBlock**: a general code block usable anywhere; `Implementation` is the node-bound variant. Pass the code as a string via `code` (or as children) wrapped in a template literal so MDX does not read it as expressions: `<CodeBlock language="bash" title="..." lineNumbers>{`npm run validate`}</CodeBlock>`. `language` adds the badge, `title`/`caption` add labels, `lineNumbers` and `wrap` are booleans.
 - **Chart**: `type` is `bar` | `line` | `pie`; use `data` for bar/pie and `labels` + `series={[{name, values}]}` for line. Charts follow theme colors.
 - **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.

package/template/guides/atlas-guide.mdx

@@ -114,9 +114,9 @@
       <RelationMap title="可视化摘要" items={[{from:'MDX',type:'produces',to:'Graph',note:'生成关系图'},{from:'Node',type:'uses',to:'Mermaid',note:'展示局部流程'}]} />
     </ConceptNode>
 
-    <ConceptNode id="extension-family" title="扩展能力：公式、图表、图片与引用" level="L1" parent="showroom" summary="数学公式、数据图表、配图题注和参考文献四项能力，让讲解可以带上推导、数据与出处。">
-      <Definition>扩展组件把文本之外的证据接进页面：Math/MathBlock 渲染数学、Chart 绘制数据、Figure 承载配图、Cite/References 保留出处。</Definition>
-      <Children><ConceptRef id="math-demo" /><ConceptRef id="chart-demo" /><ConceptRef id="figure-demo" /><ConceptRef id="citation-demo" /></Children>
+    <ConceptNode id="extension-family" title="扩展能力：公式、图表、图片、代码与引用" level="L1" parent="showroom" summary="数学公式、数据图表、配图题注、代码块和参考文献五项能力，让讲解可以带上推导、数据、实现与出处。">
+      <Definition>扩展组件把文本之外的证据接进页面：Math/MathBlock 渲染数学、Chart 绘制数据、Figure 承载配图、CodeBlock 展示代码或命令、Cite/References 保留出处。</Definition>
+      <Children><ConceptRef id="math-demo" /><ConceptRef id="chart-demo" /><ConceptRef id="figure-demo" /><ConceptRef id="code-demo" /><ConceptRef id="citation-demo" /></Children>
     </ConceptNode>
 
     <ConceptNode id="math-demo" title="Math 与 MathBlock：把推导写进正文" level="L2" parent="extension-family" summary="Math 用于行内符号，MathBlock 用于独立公式并支持变量说明。">
@@ -138,6 +138,15 @@
       <Boundary>大图会显著增大单文件 HTML；截图类内容建议控制尺寸。</Boundary>
     </ConceptNode>
 
+    <ConceptNode id="code-demo" title="CodeBlock：把命令、配置或伪代码放进正文" level="L2" parent="extension-family" summary="与绑定节点的 Implementation 不同，CodeBlock 可以出现在任何位置，并支持标题、题注、换行和行号。">
+      <Definition>CodeBlock 通过 code（或子内容）接收字符串，language 决定语言标记，title 与 caption 提供说明，lineNumbers 和 wrap 控制逐行讲解与长行折行。</Definition>
+      <CodeBlock language="bash" title="校验与构建" caption="命令行、伪代码或配置都可以用它承载，不依附于某个概念节点。" lineNumbers>{`npm run validate
+npm run sync
+npm run build`}</CodeBlock>
+      <CodeBlock language="javascript" title="语义优先" wrap>{`const explain = concept => concept.mechanism ?? concept.definition ?? concept.overview;`}</CodeBlock>
+      <Boundary>代码里的反引号、花括号请放在模板字符串中传入，避免被 MDX 当作表达式解析。</Boundary>
+    </ConceptNode>
+
     <ConceptNode id="citation-demo" title="Cite 与 References：让结论可以追溯" level="L2" parent="extension-family" summary="行内用 Cite 标记引用，文末用 References 列出完整出处，编号自动对应。">
       <Definition>Cite 的 id 与 References 条目的 id 对应，渲染时显示条目在列表中的序号，并链接到该条目。</Definition>
       <Overview>信息密度的价值在于可验证性<Cite id="shannon1948" />，而可验证性依赖清晰的出处<Cite id="tufte1983" />。</Overview>

package/template/guides/scroll-guide.mdx

@@ -42,6 +42,14 @@
     <Chart title="四周留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]},{name:'活跃度',values:[100,64,52,40]}]} />
   </ScrollSection>
 
+  <ScrollSection title="把命令与代码放进正文">
+    <ScrollProse>CodeBlock 承载命令行、配置或伪代码。它不依附于某个概念节点，可以出现在任何章节；需要逐行讲解时打开行号，长行过多时可以折行。</ScrollProse>
+    <CodeBlock language="bash" title="本地校验与预览" caption="CodeBlock 复用模板的代码表面，因此自动跟随当前皮肤与组件风格。" lineNumbers>{`npm run validate
+npm run sync
+npm run dev`}</CodeBlock>
+    <CodeBlock language="javascript" title="语义优先" wrap>{`const explain = concept => concept.mechanism ?? concept.definition ?? concept.overview;`}</CodeBlock>
+  </ScrollSection>
+
   <ScrollSection title="组织证据，再收敛到行动">
     <ScrollGrid columns="3">
       <PyramidModel title="论证层级" levels={[{title:'结论',description:'读者需要带走的判断'},{title:'理由',description:'支撑判断的关键分组'},{title:'证据',description:'事实、数据与案例'}]} />

package/template/src/components/MDXComponents.jsx

@@ -180,6 +180,38 @@ export function Implementation({ language = 'text', title = '实现代码', chil
 }
 Implementation.displayName = 'Implementation';
 
+/**
+ * Generic code block for any carrier. `Implementation` is bound to a node's
+ * implementation section; `CodeBlock` is meant for shell commands, config,
+ * output, prompts and pseudocode that live anywhere in a document.
+ * Pass the code as a string through `code` (or as children) so MDX parsing and
+ * the validator never confuse code with markup.
+ */
+export function CodeBlock({ code, language = 'text', title, caption, lineNumbers = false, wrap = false, children }) {
+  const raw = typeof code === 'string' ? code : childrenToText(children);
+  const text = typeof raw === 'string' ? raw.replace(/^\n+|\s+$/g, '') : '';
+  if (!text) return null;
+  const showLanguage = Boolean(language) && language !== 'text';
+  const showHead = Boolean(title) || showLanguage;
+  return (
+    <figure className="semantic-code" data-language={language}>
+      {showHead && (
+        <div className="semantic-code-head">
+          {title && <span className="semantic-code-title">{title}</span>}
+          {showLanguage && <span className="lang-badge">{language}</span>}
+        </div>
+      )}
+      <pre className={`code-block${lineNumbers ? ' code-block-numbered' : ''}${wrap ? ' code-block-wrap' : ''}`}>
+        {lineNumbers
+          ? <code>{text.split('\n').map((line, index) => <span className="code-line" key={index}>{line}</span>)}</code>
+          : <code>{text}</code>}
+      </pre>
+      {caption && <figcaption className="semantic-code-caption">{caption}</figcaption>}
+    </figure>
+  );
+}
+CodeBlock.displayName = 'CodeBlock';
+
 export function Boundary({ title = '边界与约束', children }) {
   return (
     <div className="semantic-boundary">

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

@@ -27,6 +27,7 @@ export const KNOWN_COMPONENTS = [
   'Definition',
   'Mechanism',
   'Implementation',
+  'CodeBlock',
   'Boundary',
   'Example',
   'Counterexample',
@@ -110,6 +111,7 @@ const CORE_CONTENT_COMPONENTS = new Set([
   'Definition',
   'Mechanism',
   'Implementation',
+  'CodeBlock',
   'Boundary',
   'Example',
   'Counterexample',

package/template/src/styles/core.css

@@ -1033,6 +1033,66 @@ button.flow-box {
   box-shadow: var(--shadow-inset);
 }
 
+/* Generic CodeBlock. It reuses `.code-block` so every skin and style pack
+   keeps one code surface, and only adds an optional title bar, wrap and
+   line numbers on top. */
+.semantic-code {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.semantic-code-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.semantic-code-title {
+  font-family: var(--font-heading);
+  font-weight: 700;
+  font-size: 13px;
+  color: var(--text-secondary);
+}
+
+.semantic-code-caption {
+  font-size: 12px;
+  color: var(--text-muted);
+}
+
+.code-block-wrap {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.code-block-numbered {
+  counter-reset: code-line;
+}
+
+.code-block-numbered code {
+  display: block;
+}
+
+.code-block-numbered .code-line {
+  position: relative;
+  display: block;
+  min-height: 1.6em;
+  padding-left: 3em;
+  counter-increment: code-line;
+}
+
+.code-block-numbered .code-line::before {
+  content: counter(code-line);
+  position: absolute;
+  left: 0;
+  width: 2em;
+  text-align: right;
+  color: rgba(148, 163, 184, 0.55);
+  user-select: none;
+}
+
 .example-item, .counterexample-item {
   margin-top: 12px;
   padding: 14px 18px;