concept-atlas-dense-explain 0.4.1 → 0.4.2

package/package.json

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

package/skill/SKILL.md

@@ -32,7 +32,7 @@ If the user only wants the prompt/methodology and not files, still choose a shel
 ## Carriers
 
 - `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, reading progress, and prev/next from section titles — do not hand-build navigation.
+- `scroll`: `ScrollDocument` → `ScrollHeader` + `ScrollSection` (+ `ScrollProse`, `ScrollGrid`). Shared components live inside sections. The shell auto-builds a a table of contents and reading progress from section titles — do not hand-build navigation.
 - Never make one MDX file both shells. When switching shells, convert only the outer structure.
 
 ## Component families

package/template/guides/atlas-guide.mdx

@@ -125,7 +125,7 @@
     </ConceptNode>
 
     <ConceptNode id="chart-demo" title="Chart：用同一数据切换三种图形" level="L2" parent="extension-family" summary="bar、line、pie 三种类型共享数据形状，按比较、趋势或占比选择。">
-      <Definition>Chart 接收 data（{label, value} 数组）或 series + labels，在 SVG 中绘制并跟随主题色。</Definition>
+      <Definition>Chart 接收 data（`{label, value}` 数组）或 series + labels，在 SVG 中绘制并跟随主题色。</Definition>
       <Chart title="各阶段耗时" type="bar" unit="小时" data={[{label:'收集',value:6},{label:'分析',value:14},{label:'验证',value:9},{label:'落地',value:4}]} />
       <Chart title="留存趋势" type="line" labels={['第1周','第2周','第3周','第4周']} series={[{name:'留存率',values:[100,72,58,49]}]} />
     </ConceptNode>

package/template/guides/scroll-guide.mdx

@@ -1,9 +1,6 @@
----
-title: scroll-guide
----
-
 <ScrollDocument spacing="comfortable" fontSize="normal">
   <ScrollHeader title="Concept Atlas 连续阅读指南" label="连续阅读 · 组件参考">同一套语义组件可以脱离图谱和节点面板，按传统文档流连续阅读。本页同时是一份可运行的组件参考：每一节演示一个组件家族，正文保持高信息密度，模型在需要比较、推导或收敛时占满可用宽度。</ScrollHeader>
+
   <ScrollSection title="先识别推理结构">
     <ScrollProse>模型不是内容的装饰。它们分别处理并列要素、二维定位、变量关系、论证层级和筛选过程。先确认关系形状，读者才能用最短路径验证结论。</ScrollProse>
     <LearningObjectives items={['按关系形状选择组件', '把结论与证据分开表达', '让每个区块承担不同的认知任务']} />

package/template/src/components/MDXComponents.jsx

@@ -563,32 +563,16 @@ export function ScrollDocument({ spacing = 'comfortable', fontSize = 'normal', s
     '--reading-line-height': String(lineHeight ?? preset.lineHeight),
   };
 
-  const activeIndex = items.findIndex(item => item.id === activeId);
-  const previous = activeIndex > 0 ? items[activeIndex - 1] : null;
-  const next = activeIndex >= 0 && activeIndex < items.length - 1 ? items[activeIndex + 1] : null;
+  const showToc = toc && items.length >= 2;
 
   return (
-    <article className={`continuous-document continuous-spacing-${safeSpacing}`} data-font-size={fontSize} style={style}>
+    <article className={`continuous-document continuous-spacing-${safeSpacing}${showToc ? ' has-toc' : ''}`} data-font-size={fontSize} style={style}>
       {progress && <ReadingProgress />}
       <ScrollOutlineContext.Provider value={outline}>
-        {toc && <ScrollToc items={items} activeId={activeId} />}
-        {children}
-        {activeIndex >= 0 && (previous || next) && (
-          <nav className="scroll-pager" aria-label="章节导航">
-            {previous ? (
-              <a className="pager-prev" href={`#${previous.id}`}>
-                <span>上一节</span>
-                <strong>{previous.title}</strong>
-              </a>
-            ) : <span className="pager-spacer" />}
-            {next ? (
-              <a className="pager-next" href={`#${next.id}`}>
-                <span>下一节</span>
-                <strong>{next.title}</strong>
-              </a>
-            ) : <span className="pager-spacer" />}
-          </nav>
-        )}
+        {showToc && <ScrollToc items={items} activeId={activeId} />}
+        <div className="continuous-content">
+          {children}
+        </div>
       </ScrollOutlineContext.Provider>
     </article>
   );
@@ -768,12 +752,16 @@ NoteGrid.displayName = 'NoteGrid';
 
 // Math ----------------------------------------------------------------------
 
-export function Math({ formula, children }) {
+// Named MathInline internally: exporting a function literally called `Math`
+// would shadow the global Math object for the whole module and break Math.max
+// and friends. It is exported as `Math` so MDX can use <Math>.
+function MathInline({ formula, children }) {
   const tex = (formula || childrenToText(children)).trim();
   if (!tex) return null;
   return <span className="semantic-math" dangerouslySetInnerHTML={{ __html: renderTex(tex, false) }} />;
 }
-Math.displayName = 'Math';
+MathInline.displayName = 'Math';
+export { MathInline as Math };
 
 export function MathBlock({ title = '公式', formula, variables = [], children }) {
   const tex = (formula || childrenToText(children)).trim();

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

@@ -286,6 +286,23 @@ function tokenize(source) {
   return tags;
 }
 
+/** Blank out tag ranges, preserving offsets and newlines, so only text remains. */
+function textRegions(source, tags) {
+  const ranges = tags
+    .map(tag => [tag.start, tag.end])
+    .sort((a, b) => a[0] - b[0]);
+  const pieces = [];
+  let cursor = 0;
+  for (const [start, end] of ranges) {
+    if (start < cursor) continue;
+    pieces.push(source.slice(cursor, start));
+    pieces.push(source.slice(start, end).replace(/[^\n]/g, ' '));
+    cursor = end;
+  }
+  pieces.push(source.slice(cursor));
+  return pieces.join('');
+}
+
 function attrsToMap(attrs) {
   const map = {};
   for (const attr of attrs) map[attr.name] = attr;
@@ -421,6 +438,24 @@ export function validateMdxSource(source, options = {}) {
     }
   }
 
+  // MDX evaluates `{ ... }` in prose as a JavaScript expression. Authors often
+  // write data shapes like `{label, value}` in a sentence, which crashes the
+  // page with "label is not defined".
+  const text = textRegions(masked, tags);
+  for (const match of text.matchAll(/\{([^{}]*)\}/g)) {
+    const expression = match[1].trim();
+    if (!expression || expression.startsWith('/*')) continue;
+    if (/^[A-Za-z_$][\w$]*\s*(,[\s\S]*)?$/.test(expression)) {
+      add('warning', 'PROSE_EXPRESSION', `正文中的 {${expression}} 会被 MDX 当作表达式并导致运行时报错；请改成行内代码 \`{${expression}}\``, match.index, expression);
+    }
+  }
+
+  // MDX has no frontmatter support by default: a leading `---` block renders as
+  // a stray rule and text at the top of the page.
+  if (/^---\r?\n[\s\S]*?\r?\n---(\r?\n|$)/.test(source)) {
+    add('warning', 'FRONTMATTER_UNSUPPORTED', '文件以 --- 开头，但 MDX 不解析 frontmatter，它会被渲染成正文；请删除', 0, null);
+  }
+
   const carrier = usedComponents.has('ScrollDocument') ? 'scroll'
     : (usedComponents.has('ExplainPage') || usedComponents.has('ConceptGraph')) ? 'atlas'
       : null;

package/template/src/styles/concept-explain.css

@@ -3176,11 +3176,11 @@ html[data-carrier='scroll'] #root {
   justify-content: space-between;
 }
 
-.continuous-document > .semantic-framework-model,
-.continuous-document > .semantic-model-matrix,
-.continuous-document > .semantic-model-formula,
-.continuous-document > .semantic-model-pyramid,
-.continuous-document > .semantic-model-funnel,
+.continuous-content > .semantic-framework-model,
+.continuous-content > .semantic-model-matrix,
+.continuous-content > .semantic-model-formula,
+.continuous-content > .semantic-model-pyramid,
+.continuous-content > .semantic-model-funnel,
 .continuous-section > .semantic-framework-model,
 .continuous-section > .semantic-model-matrix,
 .continuous-section > .semantic-model-formula,
@@ -3339,29 +3339,44 @@ html[data-carrier='scroll'] #root {
   transition: transform 80ms linear;
 }
 
-/* ---- Table of contents ---- */
+/* ---- Table of contents (sticky sidebar) ---- */
+
+.continuous-content {
+  min-width: 0;
+}
 
 .scroll-toc {
   display: none;
 }
 
-@media (min-width: 1400px) {
-  .scroll-toc {
-    position: fixed;
-    top: 104px;
-    left: max(16px, calc(50% - 560px - 220px));
-    z-index: 30;
+@media (min-width: 1080px) {
+  .continuous-document.has-toc {
+    display: grid;
+    grid-template-columns: 208px minmax(0, 1fr);
+    column-gap: 44px;
+    align-items: start;
+  }
+
+  .continuous-document.has-toc > .scroll-toc {
+    position: sticky;
+    top: 24px;
     display: block;
-    width: 190px;
-    max-height: calc(100vh - 160px);
-    overflow: auto;
-    padding-right: 10px;
-    border-right: 1px solid var(--border-subtle);
+    grid-column: 1;
+    align-self: start;
+    max-height: calc(100vh - 48px);
+    overflow-y: auto;
+    padding-right: 6px;
+  }
+
+  .continuous-document.has-toc > .continuous-content {
+    grid-column: 2;
   }
 }
 
 .scroll-toc-title {
-  margin-bottom: 10px;
+  margin: 0 0 10px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border-subtle);
   color: var(--text-dim);
   font-size: 11px;
   font-weight: 700;
@@ -3373,90 +3388,54 @@ html[data-carrier='scroll'] #root {
   margin: 0;
   padding: 0;
   list-style: none;
+  border-left: 1px solid var(--border-subtle);
   counter-reset: toc;
 }
 
 .scroll-toc-list li {
-  margin: 0 0 2px;
   counter-increment: toc;
 }
 
 .scroll-toc-list a {
-  display: block;
-  padding: 5px 8px 5px 22px;
+  display: grid;
+  grid-template-columns: 24px minmax(0, 1fr);
+  gap: 6px;
+  align-items: baseline;
+  margin-left: -1px;
+  padding: 6px 8px 6px 0;
   border-left: 2px solid transparent;
-  border-radius: var(--radius-1);
   color: var(--text-muted);
   font-size: 12.5px;
-  line-height: 1.4;
+  line-height: 1.45;
   text-decoration: none;
-  position: relative;
-  transition: color 0.15s ease, border-color 0.15s ease, background 0.15s ease;
+  transition: color 0.15s ease, border-color 0.15s ease;
 }
 
 .scroll-toc-list a::before {
   content: counter(toc, decimal-leading-zero);
-  position: absolute;
-  left: 4px;
   color: var(--text-dim);
   font-size: 10px;
   font-variant-numeric: tabular-nums;
+  text-align: center;
+  transition: color 0.15s ease;
 }
 
 .scroll-toc-list a:hover {
   color: var(--text-primary);
-  background: var(--bg-highlight);
 }
 
-.scroll-toc-list li.active a {
-  border-left-color: var(--primary);
-  color: var(--text-primary);
-  font-weight: 600;
-}
-
-/* ---- Section pager ---- */
-
-.scroll-pager {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 12px;
-  margin-top: 8px;
-  padding-top: 16px;
-  border-top: 1px solid var(--border-subtle);
-}
-
-.scroll-pager a {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 10px 12px;
-  border: 1px solid var(--border-medium);
-  border-radius: var(--radius-2);
-  background: var(--bg-surface);
-  text-decoration: none;
-  transition: border-color 0.15s ease, background 0.15s ease;
-}
-
-.scroll-pager a:hover {
-  border-color: var(--border-strong);
-  background: var(--bg-card-hover);
-}
-
-.scroll-pager a span {
-  color: var(--text-dim);
-  font-size: 11px;
-  font-weight: 600;
+.scroll-toc-list a:hover::before {
+  color: var(--text-secondary);
 }
 
-.scroll-pager a strong {
+.scroll-toc-list li.active a {
+  border-left-color: var(--primary);
   color: var(--text-primary);
-  font-size: 13px;
   font-weight: 600;
-  line-height: 1.4;
 }
 
-.scroll-pager .pager-next {
-  text-align: right;
+.scroll-toc-list li.active a::before {
+  color: var(--primary-light);
 }
 
 /* ===========================================================================