concept-atlas-dense-explain 0.2.0 → 0.2.2

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

@@ -45,11 +45,20 @@
   --code-text: #34d399;
   --code-border: rgba(255, 255, 255, 0.1);
 
-  /* Shadows & Depth */
-  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
-  --shadow-md: 0 4px 16px -2px rgba(0, 0, 0, 0.5), 0 2px 6px -1px rgba(0, 0, 0, 0.4);
-  --shadow-lg: 0 10px 30px -4px rgba(0, 0, 0, 0.6), 0 4px 12px -2px rgba(0, 0, 0, 0.4);
-  --shadow-glow: 0 0 20px rgba(99, 102, 241, 0.2);
+  /* Shadows & Depth - restrained, hairline-first. Offset shadows read as
+     printed paper rather than floating SaaS cards. */
+  --shadow-sm: 0 1px 1px rgba(0, 0, 0, 0.35);
+  --shadow-md: 0 2px 8px -4px rgba(0, 0, 0, 0.55);
+  --shadow-lg: 0 8px 24px -12px rgba(0, 0, 0, 0.6);
+  --shadow-glow: none;
+  --shadow-card: 2px 3px 0 rgba(0, 0, 0, 0.45);
+  --shadow-pop: 3px 4px 0 rgba(0, 0, 0, 0.55);
+
+  /* Radius scale - differentiated by component weight, not one value everywhere */
+  --radius-1: 3px;
+  --radius-2: 4px;
+  --radius-3: 6px;
+  --radius-4: 8px;
 
   /* Knowledge Badge & Callouts */
   --callout-info-bg: rgba(56, 189, 248, 0.08);
@@ -106,10 +115,17 @@
   --code-border: rgba(0, 0, 0, 0.08);
 
   /* Shadows & Depth */
-  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.05);
-  --shadow-md: 0 4px 16px -2px rgba(15, 23, 42, 0.08), 0 2px 6px -1px rgba(15, 23, 42, 0.04);
-  --shadow-lg: 0 12px 32px -4px rgba(15, 23, 42, 0.12), 0 4px 12px -2px rgba(15, 23, 42, 0.06);
-  --shadow-glow: 0 0 20px rgba(79, 70, 229, 0.12);
+  --shadow-sm: 0 1px 1px rgba(15, 23, 42, 0.04);
+  --shadow-md: 0 2px 8px -4px rgba(15, 23, 42, 0.12);
+  --shadow-lg: 0 8px 24px -12px rgba(15, 23, 42, 0.14);
+  --shadow-glow: none;
+  --shadow-card: 2px 3px 0 rgba(15, 23, 42, 0.08);
+  --shadow-pop: 3px 4px 0 rgba(15, 23, 42, 0.12);
+
+  --radius-1: 3px;
+  --radius-2: 4px;
+  --radius-3: 6px;
+  --radius-4: 8px;
 
   /* Knowledge Badge & Callouts */
   --callout-info-bg: #eff6ff;
@@ -2423,3 +2439,268 @@ button.flow-box {
 .semantic-decision-matrix tr:last-child td, .semantic-compare-table tr:last-child td {
   border-bottom: none;
 }
+
+.semantic-framework-model, .semantic-model-matrix, .semantic-model-formula {
+  margin-top: 14px;
+  padding: 14px;
+  border: 1px solid var(--border-medium);
+  border-radius: 10px;
+  background: var(--bg-canvas);
+}
+
+.framework-model-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 10px;
+}
+
+.framework-model-type {
+  color: var(--text-muted);
+  font-size: 11px;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+}
+
+.framework-model-question {
+  margin-bottom: 10px;
+  color: var(--text-secondary);
+  font-size: 12px;
+}
+
+.framework-model-elements {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 8px;
+}
+
+.framework-model-element {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 3px 8px;
+  padding: 10px;
+  border: 1px solid var(--border-subtle);
+  border-radius: 8px;
+  background: var(--bg-surface);
+}
+
+.framework-model-element strong { color: var(--text-primary); font-size: 13px; }
+.framework-model-element span:last-child { grid-column: 2; color: var(--text-secondary); font-size: 12px; line-height: 1.5; }
+.framework-model-index { color: var(--accent-cyan); font: 700 11px/1.4 ui-monospace, monospace; }
+.model-stages .framework-model-elements, .model-cycle .framework-model-elements { grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); }
+.model-stages .framework-model-element:not(:last-child)::after { content: '→'; position: absolute; }
+
+.model-matrix-grid {
+  display: grid;
+  grid-template-columns: 30px repeat(2, minmax(110px, 1fr));
+  grid-template-rows: 24px repeat(2, minmax(70px, 1fr));
+  gap: 5px;
+}
+
+.model-matrix-axis { color: var(--text-muted); font-size: 11px; text-align: center; }
+.model-matrix-x { grid-column: 2 / 4; }
+.model-matrix-y { grid-row: 2 / 4; writing-mode: vertical-rl; transform: rotate(180deg); align-self: center; }
+.model-matrix-cell { display: flex; flex-direction: column; gap: 4px; padding: 9px; border: 1px solid var(--border-subtle); border-radius: 7px; background: var(--bg-surface); }
+.model-matrix-cell strong { color: var(--text-primary); font-size: 12px; }
+.model-matrix-cell span { color: var(--text-secondary); font-size: 11px; line-height: 1.4; }
+.tone-success { border-color: rgba(52, 211, 153, .45); }
+.tone-warn { border-color: rgba(251, 191, 36, .45); }
+.tone-danger { border-color: rgba(248, 113, 113, .45); }
+
+.model-formula-expression { padding: 12px; border-radius: 8px; background: var(--bg-surface); color: var(--accent-cyan); text-align: center; font-size: 16px; }
+.model-formula-variables { display: grid; grid-template-columns: auto 1fr; gap: 5px 12px; margin: 10px 0 0; font-size: 12px; }
+.model-formula-variables dt { color: var(--accent-cyan); font-family: ui-monospace, monospace; }
+.model-formula-variables dd { margin: 0; color: var(--text-secondary); }
+
+.semantic-model-pyramid, .semantic-model-funnel {
+  margin-top: 14px;
+  padding: 14px;
+  border: 1px solid var(--border-medium);
+  border-radius: 10px;
+  background: var(--bg-canvas);
+}
+
+.model-pyramid-levels, .model-funnel-steps { display: flex; flex-direction: column; align-items: center; gap: 5px; }
+.model-pyramid-level, .model-funnel-step {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  width: var(--pyramid-width, var(--funnel-width));
+  padding: 9px 12px;
+  border: 1px solid var(--border-subtle);
+  border-radius: 7px;
+  background: var(--bg-surface);
+  text-align: center;
+}
+.model-pyramid-level strong, .model-funnel-step strong { color: var(--text-primary); font-size: 12px; }
+.model-pyramid-level span, .model-funnel-step span { color: var(--text-secondary); font-size: 11px; line-height: 1.4; }
+
+/* ==========================================================================
+   DESIGN REFINEMENT — remove the generic "SaaS card kit" defaults.
+   Oversized uniform radii, a soft grey shadow on every surface, glass blur,
+   gradient decoration and tracked all-caps labels are the tells this pass
+   removes. Surfaces are separated by hairlines and a single print-like
+   offset shadow; radii follow the 3/4/6/8 scale so weight maps to hierarchy.
+   ========================================================================== */
+
+/* Chrome: solid surfaces instead of glass blur */
+.app-toolbar,
+.graph-legend-ribbon,
+.draft-floating-tools {
+  background: var(--bg-surface);
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+  box-shadow: var(--shadow-card);
+}
+
+.app-toolbar,
+.graph-legend-ribbon,
+.draft-floating-tools { border-radius: var(--radius-3); }
+
+.draft-floating-tools:hover,
+.draft-floating-tools:focus-within { transform: none; }
+
+.view-tabs { border-radius: var(--radius-2); }
+.view-tab { border-radius: var(--radius-1); }
+.view-tab.active { box-shadow: none; border-color: var(--border-strong); }
+.theme-toggle-btn { border-radius: var(--radius-2); box-shadow: none; }
+
+/* Hover shows state through color and rules, not nudged cards */
+.theme-toggle-btn:hover,
+.view-graph-btn:hover,
+.subnode-card:hover,
+.relation-link-card:hover,
+.panel-rel-card:hover,
+.sibling-btn:hover,
+.flow-box.clickable:hover,
+.jump-explorer-btn:hover { transform: none; }
+.subnode-card:hover .sn-arrow { transform: none; }
+
+.brand-logo-badge {
+  background: var(--primary);
+  border-radius: var(--radius-2);
+  box-shadow: none;
+}
+
+/* Graph controls */
+.graph-mode-switch,
+.search-box,
+.filter-group {
+  border-radius: var(--radius-3);
+  box-shadow: none;
+}
+.graph-mode-switch button { border-radius: var(--radius-1); }
+.graph-legend-ribbon { border-radius: var(--radius-3); }
+.graph-side-panel { box-shadow: none; }
+
+/* Labels: sentence case instead of tracked all-caps eyebrows */
+.side-label,
+.insp-label,
+.legend-title,
+.box-type,
+.chip-label,
+.impl-lang,
+.hierarchy-nav-label,
+.panel-badge,
+.panel-section .section-title,
+.framework-model-type {
+  text-transform: none;
+  letter-spacing: 0.01em;
+}
+.side-label { color: var(--text-secondary); }
+.side-label::before { width: 2px; height: 11px; border-radius: 1px; }
+
+/* Navigation */
+.breadcrumb-node,
+.sibling-btn,
+.tree-node-btn,
+.hierarchy-nav-node,
+.hierarchy-nav-current,
+.hierarchy-nav-children { border-radius: var(--radius-2); }
+.tree-node-btn.active::before { border-radius: 0; }
+
+/* Cards: radius hierarchy + hairline separation */
+.concept-hero-card {
+  border-radius: var(--radius-4);
+  box-shadow: var(--shadow-pop);
+}
+.concept-hero-card::after { display: none; }
+
+.node-block,
+.draft-board .node-block {
+  border-radius: var(--radius-3);
+  box-shadow: var(--shadow-card);
+}
+
+.example-item,
+.counterexample-item,
+.subnode-card,
+.relation-link-card,
+.boundary-card,
+.panel-rel-card,
+.io-capsule,
+.local-flow-ribbon,
+.code-block,
+.inline-inspector,
+.semantic-learning-objectives,
+.semantic-key-question,
+.semantic-evidence,
+.semantic-invariant,
+.semantic-failure-mode,
+.semantic-tradeoff,
+.semantic-framework-model,
+.semantic-model-matrix,
+.semantic-model-formula,
+.semantic-model-pyramid,
+.semantic-model-funnel,
+.semantic-relation-path,
+.relation-path-node,
+.model-matrix-cell,
+.model-formula-expression,
+.semantic-decision-matrix,
+.semantic-compare-table,
+.semantic-callout,
+.hierarchy-navigator { border-radius: var(--radius-3); }
+
+.draft-board .semantic-grid > .semantic-mermaid,
+.draft-board .semantic-grid > .semantic-relation-map { border-radius: var(--radius-3); }
+
+.meta-chip,
+.flow-box,
+.insp-pill,
+.inline-relation,
+.level-pill,
+.view-graph-btn,
+.framework-model-element,
+.model-pyramid-level,
+.model-funnel-step,
+.semantic-note { border-radius: var(--radius-2); }
+
+.rel-type-tag,
+.bc-level-pill { border-radius: var(--radius-1); }
+
+/* Depth: only note-like surfaces keep an offset shadow, nothing floats */
+.code-block { box-shadow: none; }
+.semantic-note { box-shadow: var(--shadow-card); }
+.subnode-card:hover { box-shadow: var(--shadow-card); }
+.flow-box.current-focus,
+.jump-explorer-btn { box-shadow: none; }
+
+.inline-inspector {
+  border-style: solid;
+  border-color: var(--border-medium);
+  box-shadow: var(--shadow-card);
+}
+
+/* Widget chrome: the type tag becomes a quiet rule, not monospace data */
+.semantic-widget-head code {
+  padding: 1px 5px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-1);
+  color: var(--text-dim);
+  font-family: inherit;
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+}

package/skill/assets/template/src/views/NodeExplorer.jsx

@@ -17,24 +17,66 @@ export function NodeExplorer({
   const [isDragging, setIsDragging] = React.useState(false);
   const dragRef = React.useRef(null);
   const suppressClickRef = React.useRef(false);
+  const viewportRef = React.useRef(null);
+  const boardRef = React.useRef(null);
+  const canvasScaleRef = React.useRef(canvasScale);
+  const canvasPanRef = React.useRef(canvasPan);
+  canvasScaleRef.current = canvasScale;
+  canvasPanRef.current = canvasPan;
 
   const updateScale = (nextScale) => {
     const scale = Math.max(0.65, Math.min(1.6, +nextScale.toFixed(2)));
     setCanvasScale(scale);
   };
 
-  const updateScaleAtPoint = (event) => {
-    const rect = event.currentTarget.getBoundingClientRect();
-    const factor = Math.exp(-event.deltaY * 0.002);
-    const nextScale = Math.max(0.65, Math.min(1.6, +(canvasScale * factor).toFixed(3)));
-    const focusX = event.clientX - rect.left;
-    const focusY = event.clientY - rect.top;
-    const contentX = (focusX - canvasPan.x) / canvasScale;
-    const contentY = (focusY - canvasPan.y) / canvasScale;
-    setCanvasScale(nextScale);
-    setCanvasPan({ x: focusX - contentX * nextScale, y: focusY - contentY * nextScale });
+  // Keep the board from being scrolled entirely out of view.
+  const clampCanvasPan = (x, y, scale = canvasScale) => {
+    const viewport = viewportRef.current;
+    const board = boardRef.current;
+    if (!viewport || !board) return { x, y };
+    const margin = 64;
+    const clampAxis = (value, content, view) =>
+      Math.max(Math.min(view - content, 0) - margin, Math.min(margin, value));
+    return {
+      x: clampAxis(x, board.offsetWidth * scale, viewport.clientWidth),
+      y: clampAxis(y, board.offsetHeight * scale, viewport.clientHeight),
+    };
   };
 
+  // Wheel scrolls the canvas vertically; Ctrl/Cmd + wheel zooms around the
+  // pointer. React's onWheel is passive, so bind a native listener instead.
+  React.useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) return undefined;
+
+    const handleWheel = (event) => {
+      if (event.ctrlKey || event.metaKey) {
+        event.preventDefault();
+        const scale = canvasScaleRef.current;
+        const pan = canvasPanRef.current;
+        const rect = viewport.getBoundingClientRect();
+        const factor = Math.exp(-event.deltaY * 0.002);
+        const nextScale = Math.max(0.65, Math.min(1.6, +(scale * factor).toFixed(3)));
+        const focusX = event.clientX - rect.left;
+        const focusY = event.clientY - rect.top;
+        const contentX = (focusX - pan.x) / scale;
+        const contentY = (focusY - pan.y) / scale;
+        setCanvasScale(nextScale);
+        setCanvasPan(clampCanvasPan(focusX - contentX * nextScale, focusY - contentY * nextScale, nextScale));
+        return;
+      }
+
+      event.preventDefault();
+      const stepX = event.shiftKey ? event.deltaY : event.deltaX;
+      const stepY = event.shiftKey ? 0 : event.deltaY;
+      const pan = canvasPanRef.current;
+      setCanvasPan(clampCanvasPan(pan.x - stepX, pan.y - stepY, canvasScaleRef.current));
+    };
+
+    viewport.addEventListener('wheel', handleWheel, { passive: false });
+    return () => viewport.removeEventListener('wheel', handleWheel);
+  }, []);
+
   const handleCanvasPointerDown = (event) => {
     if (event.target.closest('button, a, input, select, textarea')) return;
     dragRef.current = {
@@ -55,10 +97,11 @@ export function NodeExplorer({
     const distance = Math.hypot(event.clientX - dragRef.current.startX, event.clientY - dragRef.current.startY);
     if (distance < 6) return;
     dragRef.current.moved = true;
-    setCanvasPan({
-      x: dragRef.current.panX + event.clientX - dragRef.current.startX,
-      y: dragRef.current.panY + event.clientY - dragRef.current.startY,
-    });
+    setCanvasPan(clampCanvasPan(
+      dragRef.current.panX + event.clientX - dragRef.current.startX,
+      dragRef.current.panY + event.clientY - dragRef.current.startY,
+      canvasScale
+    ));
   };
 
   const handleCanvasPointerUp = (event) => {
@@ -174,6 +217,7 @@ export function NodeExplorer({
           </div>
 
           <div
+            ref={viewportRef}
             className={`draft-viewport ${isDragging ? 'is-dragging' : ''}`}
             onPointerDown={handleCanvasPointerDown}
             onPointerMove={handleCanvasPointerMove}
@@ -185,12 +229,6 @@ export function NodeExplorer({
               event.stopPropagation();
               suppressClickRef.current = false;
             }}
-            onWheel={(event) => {
-              // Two-finger trackpad scrolling remains document scrolling. Hold Ctrl/Cmd to zoom.
-              if (!event.ctrlKey && !event.metaKey) return;
-              event.preventDefault();
-              updateScaleAtPoint(event);
-            }}
           >
             <div className="draft-floating-tools">
               <button
@@ -215,6 +253,7 @@ export function NodeExplorer({
               </div>
             </div>
             <div
+              ref={boardRef}
               className="draft-board"
               style={{
                 transform: `translate(${canvasPan.x}px, ${canvasPan.y}px) scale(${canvasScale})`,

package/skill/assets/template/src/views/RelationGraph.jsx

@@ -165,7 +165,7 @@ export function RelationGraph({
       .filter((event) => event.type !== 'wheel' || event.ctrlKey || event.metaKey)
       .wheelDelta((event) => {
         const delta = event.deltaMode === 1 ? event.deltaY * 16 : event.deltaY;
-        return -delta * 0.0015;
+        return -delta * 0.003;
       })
       .on('zoom', (event) => {
         g.attr('transform', event.transform);
@@ -173,6 +173,20 @@ export function RelationGraph({
 
     svg.call(zoomBehavior);
 
+    // Plain wheel scrolls the canvas vertically; Ctrl/Cmd + wheel zooms.
+    const handleWheelPan = (event) => {
+      if (event.ctrlKey || event.metaKey) return;
+      event.preventDefault();
+      const current = d3.zoomTransform(svgRef.current);
+      const stepX = event.shiftKey ? event.deltaY : event.deltaX;
+      const stepY = event.shiftKey ? 0 : event.deltaY;
+      const nextTransform = d3.zoomIdentity
+        .translate(current.x - stepX, current.y - stepY)
+        .scale(current.k);
+      svg.call(zoomBehavior.transform, nextTransform);
+    };
+    svg.on('wheel.pan', handleWheelPan);
+
     const isConceptMode = graphMode === 'concept';
     const visibleGraphLinks = isConceptMode
       ? graphLinks.filter(link => link.type !== 'parent-child')
@@ -334,6 +348,7 @@ export function RelationGraph({
 
     return () => {
       simulation?.stop();
+      svg.on('wheel.pan', null);
       svg.on('.zoom', null);
     };
   }, [graphNodes, graphLinks, selectedNodeId, theme, graphMode]);

package/skill/assets/template/vite.config.js

@@ -1,21 +1,21 @@
-import { defineConfig } from 'vite';
-import react from '@vitejs/plugin-react';
-import mdx from '@mdx-js/rollup';
-import { viteSingleFile } from 'vite-plugin-singlefile';
-
-export default defineConfig({
-  plugins: [
-    {
-      enforce: 'pre',
-      ...mdx({
-        providerImportSource: null,
-      }),
-    },
-    react(),
-    viteSingleFile(),
-  ],
-  build: {
-    outDir: 'dist',
-    emptyOutDir: true,
-  },
-});
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import mdx from '@mdx-js/rollup';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+
+export default defineConfig({
+  plugins: [
+    {
+      enforce: 'pre',
+      ...mdx({
+        providerImportSource: null,
+      }),
+    },
+    react(),
+    viteSingleFile(),
+  ],
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true,
+  },
+});

package/skill/references/components.md

@@ -1,64 +1,74 @@
-# Component contract
-
-## Structure
-
-```mdx
-<ExplainPage id="topic" title="..." summary="...">
-  <ConceptGraph root="root">
-    <ConceptNode id="root" title="..." level="L0" summary="...">
-      <Definition>...</Definition>
-      <Input>...</Input><Output>...</Output>
-      <Children><ConceptRef id="child" /></Children>
-    </ConceptNode>
-    <ConceptNode id="child" title="..." level="L1" parent="root">...</ConceptNode>
-    <Relation from="child" to="other" type="depends-on" label="依赖" />
-  </ConceptGraph>
-</ExplainPage>
-```
-
-Supported semantic content includes `Overview`, `Definition`, `Mechanism`, `Implementation`, `Example`, `Counterexample`, `Boundary`, `Prerequisite`, `Input`, `Output`, and `Glossary`.
-
-High-value verification components: `LearningObjectives`, `KeyQuestion`, `Evidence(command, observes)`, `Invariant(title)`, `FailureMode(symptom, cause, evidence, remedy)`, and `Tradeoff(options)`.
-
-Presentation components: `Stack`, `Grid`, `Split`, `Tabs`, `Flow`, `Compare`, `DecisionMatrix`, `Timeline`, `Callout`, `Details`, `RelationMap`, `RelationPath`, `Insight`, and `NoteGrid`.
-
-## Relation types (whitelist — only these render)
-
-Write cross-branch `Relation`s with `type` from this exact list. Any other value renders no styled edge.
-
-| type | label | use for |
-| --- | --- | --- |
-| `prerequisite` | 前置知识 | knowledge required before this concept |
-| `causes` | 因果推动 | one concept triggers a state change in another |
-| `produces` | 产出生成 | a stage outputs an artifact or entity |
-| `uses` | 消费使用 | a concept consumes or calls another |
-| `implements` | 实现关系 | a concrete mechanism implements an abstraction |
-| `contrasts` | 对比关系 | side-by-side contrast (no arrowhead) |
-| `depends-on` | 依赖关系 | runtime/effect depends on an external condition |
-| `exception-of` | 异常/反例 | a boundary case, counterexample, or broken assumption |
-| `precedes` | 时序先后 | pipeline or temporal ordering |
-
-Do **not** write `parent-child` as a `Relation`; the tree edge is generated automatically from `parent` / `Children`. Add a short `label` to every relation so the graph edge is readable.
-
-## Levels L0–L4
-
-| Level | name | role | typical components |
-| --- | --- | --- | --- |
-| `L0` | 全局概览 | system-wide framing and the root claim | `Definition`, `Prerequisite`, `LearningObjectives`, `KeyQuestion`, `Input`/`Output`, `Callout`, `Tabs` |
-| `L1` | 主要阶段 / 子系统 | major lifecycle stage or subsystem | `Definition`, `Input`/`Output`, `Example`, `Children` |
-| `L2` | 局部机制 | concrete mechanism and flow | `Definition`, `Mechanism`, `Details`, `Evidence`, `Invariant`, `Tradeoff`, `FailureMode` |
-| `L3` | 实现细节 | algorithm, data structure, or code | `Definition`, `Example`, `Glossary` |
-| `L4` | 边界与反例 | boundary, exception, or counterexample | `Callout(danger/warn)`, `Example`, `FailureMode` |
-
-## Density targets
-
-Match the exemplar (`assets/template/content/compile-runtime.mdx`):
-
-- 1 `L0` root, 4–5 `L1` branches, 2–3 children per branch, ~15–25 nodes total.
-- Every key node: 3–6 semantic components; `L3`/`L4` nodes may be leaner but still concrete.
-- At least a few nodes per document carry `Evidence`, `Invariant`, or `FailureMode` with a real command/observation.
-- ~8–15 cross-branch `Relation`s, each with a `label`.
-
-## Request priorities
-
-The portable template covers the core `req.md` contract, node exploration, graph view, semantic relations, search, level/relation filters, URL node state, browsing history, keyboard shortcuts, Mermaid zoom, and responsive rendering. Evidence-oriented components and compact tradeoffs cover the highest-value `request.md` enhancements without adding permanent side panels.
+# Component contract
+
+## Structure
+
+```mdx
+<ExplainPage id="topic" title="..." summary="...">
+  <ConceptGraph root="root">
+    <ConceptNode id="root" title="..." level="L0" summary="...">
+      <Definition>...</Definition>
+      <Input>...</Input><Output>...</Output>
+      <Children><ConceptRef id="child" /></Children>
+    </ConceptNode>
+    <ConceptNode id="child" title="..." level="L1" parent="root">...</ConceptNode>
+    <Relation from="child" to="other" type="depends-on" label="依赖" />
+  </ConceptGraph>
+</ExplainPage>
+```
+
+Supported semantic content includes `Overview`, `Definition`, `Mechanism`, `Implementation`, `Example`, `Counterexample`, `Boundary`, `Prerequisite`, `Input`, `Output`, and `Glossary`.
+
+High-value verification components: `LearningObjectives`, `KeyQuestion`, `Evidence(command, observes)`, `Invariant(title)`, `FailureMode(symptom, cause, evidence, remedy)`, and `Tradeoff(options)`.
+
+Presentation components: `Stack`, `Grid`, `Split`, `Tabs`, `Flow`, `Compare`, `DecisionMatrix`, `Timeline`, `FrameworkModel`, `MatrixModel`, `FormulaModel`, `PyramidModel`, `FunnelModel`, `Callout`, `Details`, `RelationMap`, `RelationPath`, `Insight`, and `NoteGrid`.
+
+经典结构模型建议按问题选择，避免重复堆叠：
+
+- `FrameworkModel`：一分为几、多因素并列、阶段、分层或循环；用 `type="elements|stages|layers|cycle"` 区分结构。
+- `MatrixModel`：两个关键元素组成的二维象限，例如重要/紧急、增长率/市场份额。
+- `FormulaModel`：用公式表达变量之间的乘加减关系，例如业绩、价值或行为模型。
+- `PyramidModel`：从基础到顶层的分层归纳，例如学习目标、需求层次或论证结构。
+- `FunnelModel`：从输入到筛选、转化、结果的逐步收敛，例如 AIDA 或销售漏斗。
+
+原有 `Flow`、`DecisionMatrix`、`Compare`、`Timeline` 继续保留，用于兼容已有内容；新内容优先使用上面的模型组件表达“关键元素与结构”的关系。
+
+## Relation types (whitelist — only these render)
+
+Write cross-branch `Relation`s with `type` from this exact list. Any other value renders no styled edge.
+
+| type | label | use for |
+| --- | --- | --- |
+| `prerequisite` | 前置知识 | knowledge required before this concept |
+| `causes` | 因果推动 | one concept triggers a state change in another |
+| `produces` | 产出生成 | a stage outputs an artifact or entity |
+| `uses` | 消费使用 | a concept consumes or calls another |
+| `implements` | 实现关系 | a concrete mechanism implements an abstraction |
+| `contrasts` | 对比关系 | side-by-side contrast (no arrowhead) |
+| `depends-on` | 依赖关系 | runtime/effect depends on an external condition |
+| `exception-of` | 异常/反例 | a boundary case, counterexample, or broken assumption |
+| `precedes` | 时序先后 | pipeline or temporal ordering |
+
+Do **not** write `parent-child` as a `Relation`; the tree edge is generated automatically from `parent` / `Children`. Add a short `label` to every relation so the graph edge is readable.
+
+## Levels L0–L4
+
+| Level | name | role | typical components |
+| --- | --- | --- | --- |
+| `L0` | 全局概览 | system-wide framing and the root claim | `Definition`, `Prerequisite`, `LearningObjectives`, `KeyQuestion`, `Input`/`Output`, `Callout`, `Tabs` |
+| `L1` | 主要阶段 / 子系统 | major lifecycle stage or subsystem | `Definition`, `Input`/`Output`, `Example`, `Children` |
+| `L2` | 局部机制 | concrete mechanism and flow | `Definition`, `Mechanism`, `Details`, `Evidence`, `Invariant`, `Tradeoff`, `FailureMode` |
+| `L3` | 实现细节 | algorithm, data structure, or code | `Definition`, `Example`, `Glossary` |
+| `L4` | 边界与反例 | boundary, exception, or counterexample | `Callout(danger/warn)`, `Example`, `FailureMode` |
+
+## Density targets
+
+Match the exemplar (`assets/template/content/compile-runtime.mdx`):
+
+- 1 `L0` root, 4–5 `L1` branches, 2–3 children per branch, ~15–25 nodes total.
+- Every key node: 3–6 semantic components; `L3`/`L4` nodes may be leaner but still concrete.
+- At least a few nodes per document carry `Evidence`, `Invariant`, or `FailureMode` with a real command/observation.
+- ~8–15 cross-branch `Relation`s, each with a `label`.
+
+## Request priorities
+
+The portable template covers the core `req.md` contract, node exploration, graph view, semantic relations, search, level/relation filters, URL node state, browsing history, keyboard shortcuts, Mermaid zoom, and responsive rendering. Evidence-oriented components and compact tradeoffs cover the highest-value `request.md` enhancements without adding permanent side panels.