concept-atlas-dense-explain 3.0.0 → 3.0.2

package/package.json

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

package/packaged-skill/SKILL.md

@@ -65,7 +65,7 @@ This is the only runner — there is nothing to look for. Do not search for a lo
 - **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.
 - **Learning loop**: `WorkedExample` holds `Step` children; give each step a `reason` (the justification) so it teaches reasoning, not just the result. `Quiz question answer` reveals the answer on click with children as the explanation. `KeyTakeaways items={[...]}` closes a section.
-- **Provenance**: `Source kind="spec|rfc|implementation|experiment|experience" label href` marks one claim's origin inline; `Confidence level="high|medium|low" basis` wraps a claim with how strongly it is established; `Term name` (or children as the definition) gives an inline hover definition.
+- **Provenance**: `Source kind="spec|rfc|implementation|experiment|experience|reference" label href` marks one claim's origin inline (`reference` is the default); `Confidence level="high|medium|low" basis` wraps a claim with how strongly it is established; `Term name` (or children as the definition) gives an inline hover definition.
 - **Data and behaviour**: `DataTable headers={[...]} rows={[[...]]}` is the neutral table (no comparative stance). `Metric label value unit delta trend note` is one headline number — compose several with `Grid`/`ScrollGrid`. `StateMachine states={[{id,label,terminal}]} transitions={[{from,to,event,guard}]}` expresses cycles and guards. `DecisionTree branches={[{condition,outcome,tone,branches}]}` nests branches. `FeedbackLoop type="reinforcing|balancing" nodes={[{label,description}]}` closes a loop. `CodeDiff before after language` shows a change.
 - **Structure and code extensions**: `Quote author source href` attributes a quotation. `Checklist title items={[{text,status:'pass'|'fail'|'unknown'|'todo',note}]}` is a verification list. `PropertyList title items={[{name,value,note}]}` is a name/value spec ledger. `TreeView title items={[{label,description,children:[…]}]}` nests a hierarchy. `CodeTabs items={[{label,language,code}]} title caption lineNumbers` gives one collapsible listing per variant. `AnnotatedCode code language title notes={[{line,text}]}` numbers a listing and calls out specific lines. `LastReviewed date by note` is a review stamp.
 - **Figure**: a relative `src` (`./assets/diagram.png`) stays a relative link by default; compile with `--inline-assets` to bake every local image in as base64, or set `inline={true}` / `inline={false}` on one figure to override (precedence: per-figure prop > global flag > link). `http(s)` URLs stay links and warn (`ASSET_REMOTE`). Always set `alt`; 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.

package/template/src/app/App.jsx

@@ -67,6 +67,19 @@ export function App({ mdxContent, initialData }) {
     [globalQuery, graph.nodes]
   );
 
+  // Combobox state for the global search. The highlight resets whenever the
+  // query changes so the first arrow key lands on the first result.
+  const [activeResultIndex, setActiveResultIndex] = useState(-1);
+  const searchOpen = globalQuery.trim().length > 0 && searchResults.length > 0;
+  const activeResultId =
+    searchOpen && activeResultIndex >= 0 && searchResults[activeResultIndex]
+      ? `global-search-option-${searchResults[activeResultIndex].id}`
+      : undefined;
+
+  useEffect(() => {
+    setActiveResultIndex(-1);
+  }, [globalQuery]);
+
   const navigateToNode = useCallback(
     (nodeId, { replace = false } = {}) => {
       if (!nodeId || !graph.nodes.has(nodeId)) return;
@@ -84,6 +97,16 @@ export function App({ mdxContent, initialData }) {
     [nav, graph.nodes]
   );
 
+  const selectSearchResult = useCallback(
+    node => {
+      if (!node) return;
+      navigateToNode(node.id);
+      setGlobalQuery('');
+      setActiveResultIndex(-1);
+    },
+    [navigateToNode]
+  );
+
   const moveHistory = useCallback(
     direction => {
       // Browser history mirrors the in-app entries one-for-one (every navigation
@@ -205,28 +228,57 @@ export function App({ mdxContent, initialData }) {
               value={globalQuery}
               onChange={event => setGlobalQuery(event.target.value)}
               onKeyDown={event => {
-                if (event.key === 'Escape') setGlobalQuery('');
+                if (event.key === 'Escape') {
+                  setGlobalQuery('');
+                  setActiveResultIndex(-1);
+                  return;
+                }
+                if (!searchOpen) return;
+                if (event.key === 'ArrowDown') {
+                  event.preventDefault();
+                  setActiveResultIndex(index => (index + 1) % searchResults.length);
+                } else if (event.key === 'ArrowUp') {
+                  event.preventDefault();
+                  setActiveResultIndex(index =>
+                    index <= 0 ? searchResults.length - 1 : index - 1
+                  );
+                } else if (event.key === 'Enter' && activeResultIndex >= 0) {
+                  event.preventDefault();
+                  selectSearchResult(searchResults[activeResultIndex]);
+                }
               }}
               placeholder="搜索所有节点…"
               aria-label="搜索所有节点"
+              role="combobox"
+              aria-expanded={searchOpen}
+              aria-controls="global-search-results"
+              aria-autocomplete="list"
+              aria-activedescendant={activeResultId}
             />
             {globalQuery && (
-              <button type="button" onClick={() => setGlobalQuery('')} aria-label="清除搜索">
+              <button
+                type="button"
+                onClick={() => {
+                  setGlobalQuery('');
+                  setActiveResultIndex(-1);
+                }}
+                aria-label="清除搜索"
+              >
                 <X size={13} />
               </button>
             )}
-            {searchResults.length > 0 && (
-              <div className="global-search-results" role="listbox">
-                {searchResults.map(node => (
+            {searchOpen && (
+              <div id="global-search-results" className="global-search-results" role="listbox">
+                {searchResults.map((node, index) => (
                   <button
                     type="button"
                     key={node.id}
-                    onClick={() => {
-                      navigateToNode(node.id);
-                      setGlobalQuery('');
-                    }}
+                    id={`global-search-option-${node.id}`}
+                    className={index === activeResultIndex ? 'active' : ''}
+                    onMouseEnter={() => setActiveResultIndex(index)}
+                    onClick={() => selectSearchResult(node)}
                     role="option"
-                    aria-selected={false}
+                    aria-selected={index === activeResultIndex}
                   >
                     <span>{node.title}</span>
                     <small>

package/template/src/styles/core.css

@@ -85,6 +85,8 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 .global-search-results { position: absolute; z-index: 20; top: calc(100% + 6px); left: 0; right: 0; padding: 5px; border: 1px solid var(--border-medium); border-radius: 10px; background: var(--bg-surface); box-shadow: var(--shadow-lg); }
 .global-search-results button { display: grid; gap: 2px; width: 100%; border: 0; border-radius: 7px; background: transparent; color: var(--text-primary); text-align: left; padding: 8px; }
 .global-search-results button:hover { background: var(--bg-subtle); }
+.global-search-results button.active,
+.global-search-results button[aria-selected="true"] { background: var(--bg-highlight); }
 .global-search-results small { color: var(--text-muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 
 /* Optional semantic layout primitives */
@@ -1298,6 +1300,36 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   }
 }
 
+/* Narrow screens: the toolbar becomes a two-row header — controls on the first
+   line, the global search on its own full-width second line — so no label is
+   ever squeezed into a wrapped stub. Content offsets below clear its height. */
+@media (max-width: 760px) {
+  .app-toolbar {
+    top: 8px;
+    left: 10px;
+    right: 10px;
+    flex-wrap: wrap;
+    gap: 6px;
+  }
+
+  .app-toolbar .view-tabs {
+    flex: 1 1 auto;
+  }
+
+  .app-toolbar .view-tab {
+    flex: 1 1 auto;
+    justify-content: center;
+    white-space: nowrap;
+  }
+
+  .app-toolbar .global-search {
+    order: 2;
+    flex: 1 1 100%;
+    min-width: 0;
+    margin-left: 0;
+  }
+}
+
 .draft-floating-tools .view-graph-btn {
   margin: 0;
   padding: 5px 9px;
@@ -1408,7 +1440,7 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 
 .hierarchy-strip-main, .hierarchy-strip-children { display: flex; align-items: center; gap: 8px; min-width: 0; }
 .hierarchy-strip-main { min-height: 30px; }
-.hierarchy-strip-label { flex: 0 0 auto; color: var(--text-dim); font-size: 10px; font-weight: 700; letter-spacing: .04em; }
+.hierarchy-strip-label { flex: 0 0 auto; color: var(--text-muted); font-size: 11px; font-weight: 700; letter-spacing: .04em; }
 
 .hierarchy-strip-path,
 .hierarchy-strip-children {
@@ -1445,7 +1477,7 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 .hierarchy-strip-path span {
   color: var(--text-dim);
   font-family: var(--font-data);
-  font-size: 9px;
+  font-size: 10px;
 }
 
 .hierarchy-strip-path strong {
@@ -1461,7 +1493,34 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   padding-top: 16px;
 }
 
-.hierarchy-child-scroll { display: flex; gap: 5px; overflow-x: auto; min-width: 0; }
+.hierarchy-child-scroll {
+  display: flex;
+  gap: 5px;
+  overflow-x: auto;
+  min-width: 0;
+  overscroll-behavior-x: contain;
+  /* The rail is a chip row: scroll it silently so a desktop layout does not
+     trade a wrapped label for a chunky scrollbar. */
+  scrollbar-width: none;
+  scroll-padding-inline: 2px;
+}
+
+.hierarchy-child-scroll::-webkit-scrollbar { display: none; }
+
+/* The drill-down rail scrolls; its items must never be compressed into a
+   one-character-wide column on a narrow screen. */
+.hierarchy-child-scroll > * {
+  flex: 0 0 auto;
+  white-space: nowrap;
+}
+
+/* Same rule for the breadcrumb: long paths clip at the container edge instead
+   of wrapping each crumb onto its own line. */
+.hierarchy-strip-path button,
+.hierarchy-strip-path strong {
+  flex: 0 0 auto;
+  white-space: nowrap;
+}
 
 .hierarchy-strip-children button {
   border: 1px solid var(--border-subtle);
@@ -1606,7 +1665,7 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
 .inline-relation-type {
   display: block;
   margin-bottom: 2px;
-  font-size: 10px;
+  font-size: 11px;
   font-weight: 800;
 }
 
@@ -1623,7 +1682,7 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   display: block;
   margin-top: 3px;
   color: var(--text-dim);
-  font-size: 10px;
+  font-size: 11px;
   line-height: 1.45;
 }
 
@@ -1825,7 +1884,8 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   .node-explorer-layout { display: block; overflow-y: auto; }
   .explorer-side { max-height: none; border: 0; }
   .left-side { display: none; }
-  .explorer-center { padding: 16px 12px 18px; }
+  /* Clear the two-row app toolbar so the hierarchy strip is never beneath it. */
+  .explorer-center { padding: 100px 12px 18px; }
   .hierarchy-strip { width: 100%; top: 4px; }
   .draft-board { min-width: 0; }
   .semantic-split { grid-template-columns: 1fr; }
@@ -1839,9 +1899,41 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   .relation-graph-layout { display: flex; flex-direction: column; }
   .graph-main { min-height: 62vh; }
   .graph-side-panel { max-height: 38vh; border-left: 0; border-top: 1px solid var(--border-medium); padding: 16px; }
-  .graph-control-bar { left: 10px; right: 10px; top: 10px; flex-wrap: wrap; gap: 6px; }
-  .graph-control-bar .filter-group { display: none; }
-  .graph-legend-ribbon { display: none; }
+
+  /* Clear the two-row app toolbar, then keep every control reachable: the bar
+     and the legend scroll horizontally instead of hiding filters/legend. */
+  .graph-control-bar {
+    left: 10px;
+    right: 10px;
+    top: 100px;
+    flex-wrap: nowrap;
+    gap: 8px;
+    overflow-x: auto;
+    overscroll-behavior-x: contain;
+    scrollbar-width: none;
+  }
+  .graph-control-bar::-webkit-scrollbar { display: none; }
+  .graph-control-bar .graph-mode-switch,
+  .graph-control-bar .search-box,
+  .graph-control-bar .filter-group { flex: 0 0 auto; }
+  .graph-control-bar .filter-group { display: flex; }
+
+  .graph-legend-ribbon {
+    left: 10px;
+    right: 10px;
+    bottom: 10px;
+    max-width: none;
+    flex-wrap: nowrap;
+    overflow-x: auto;
+    overscroll-behavior-x: contain;
+    scrollbar-width: none;
+  }
+  .graph-legend-ribbon::-webkit-scrollbar { display: none; }
+  /* Same rule as the hierarchy rail: never let a label be squeezed into a
+     one-character-wide column while the ribbon scrolls. */
+  .graph-legend-ribbon > * { flex: 0 0 auto; }
+  .graph-legend-ribbon .legend-title,
+  .graph-legend-ribbon .legend-item { white-space: nowrap; }
 }
 
 .graph-side-panel {
@@ -1963,7 +2055,7 @@ button:focus-visible, a:focus-visible, [role="button"]:focus-visible {
   display: flex;
   justify-content: space-between;
   align-items: center;
-  font-size: 10px;
+  font-size: 11px;
   margin-bottom: 4px;
 }
 
@@ -3519,7 +3611,7 @@ html[data-carrier='scroll'] #root {
 .scroll-toc-list a::before {
   content: counter(toc, decimal-leading-zero);
   color: var(--text-dim);
-  font-size: 10px;
+  font-size: 11px;
   font-variant-numeric: tabular-nums;
   text-align: center;
   transition: color 0.15s ease;
@@ -3619,7 +3711,7 @@ html[data-carrier='scroll'] #root {
 .chart-axis-value,
 .chart-axis-label {
   fill: var(--text-dim);
-  font-size: 10px;
+  font-size: 11px;
   font-family: var(--font-body);
   font-variant-numeric: var(--numeric-variant);
 }

package/template/src/views/RelationGraph.jsx

@@ -42,6 +42,12 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
   // a ref so a new `onSelectNode` identity never tears the graph down.
   onSelectNodeRef.current = onSelectNode;
 
+  // Distinguishes a user selection from a layout rebuild: a rebuild re-frames
+  // the whole graph, a selection re-centres on one node. Filtering/searching
+  // rebuilds the layout but must not move the camera.
+  const prevSelectedRef = useRef(selectedNodeId);
+  const framedModeRef = useRef(null);
+
   // Convert nodes map to array
   const allNodes = useMemo(() => Array.from(nodes.values()), [nodes]);
 
@@ -234,6 +240,7 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
     const positionedNodes = isConceptMode
       ? graphNodes.map((node, index) => ({
           ...node,
+          ...labelMetrics(node),
           x: width / 2 + ((index % 4) - 1.5) * 80,
           y: height / 2 + (Math.floor(index / 4) - 1) * 80
         }))
@@ -272,7 +279,14 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
             })
           )
           .force('center', forceCenter(width / 2, height / 2))
-          .force('collision', forceCollide().radius(34).strength(0.35))
+          // Radius follows the label extent, not just the node disc, so long
+          // Chinese titles keep their own horizontal room.
+          .force(
+            'collision',
+            forceCollide()
+              .radius(d => Math.max(34, (d.labelHalf || 0) + 12))
+              .strength(0.6)
+          )
       : null;
 
     // Resolve the shared label stack once; SVG presentation attributes cannot
@@ -307,7 +321,7 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
       .append('text')
       .attr('class', 'graph-edge-label')
       .style('fill', d => d.typeInfo?.color || 'var(--rel-default)')
-      .attr('font-size', '10px')
+      .attr('font-size', '11px')
       .attr('text-anchor', 'middle')
       .attr('dy', -5)
       // Parent-child is visually self-explanatory and its repeated label
@@ -375,16 +389,26 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
       .attr('r', d => (d.level === 'L0' ? 10 : d.level === 'L1' ? 7 : 5))
       .style('fill', d => LEVEL_DEFS[d.level]?.color || 'var(--level-l0)');
 
-    // Node Title Label
+    // Node Title Label — wrapped to at most two lines so wide trees stay legible.
     nodeLabelRef.current = nodesSelection
       .append('text')
-      .attr('dy', d => (d.level === 'L0' ? 38 : 30))
       .attr('text-anchor', 'middle')
       .style('fill', 'var(--text-primary)')
-      .attr('font-size', '12px')
+      .attr('font-size', `${LABEL_FONT_SIZE}px`)
       .attr('font-family', labelFont)
-      .attr('font-weight', d => (d.id === selectedNodeIdRef.current ? '700' : '500'))
-      .text(d => d.title);
+      .attr('font-weight', d => (d.id === selectedNodeIdRef.current ? '700' : '500'));
+
+    nodeLabelRef.current.each(function renderNodeTitle(d) {
+      const firstDy = d.level === 'L0' ? 34 : d.level === 'L1' ? 28 : 24;
+      const text = select(this);
+      wrapLabel(d.title).forEach((line, index) => {
+        text
+          .append('tspan')
+          .attr('x', 0)
+          .attr('dy', index === 0 ? firstDy : LABEL_LINE_HEIGHT)
+          .text(line);
+      });
+    });
 
     // Node Level Pill
     nodesSelection
@@ -392,7 +416,7 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
       .attr('dy', -22)
       .attr('text-anchor', 'middle')
       .style('fill', d => LEVEL_DEFS[d.level]?.color || 'var(--rel-default)')
-      .attr('font-size', '9px')
+      .attr('font-size', '10px')
       .text(d => d.level);
 
     const renderPositions = () => {
@@ -411,6 +435,24 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
       renderPositions();
     }
 
+    // Frame the whole graph on the first build and on every mode switch so
+    // nothing starts off-screen. Filter/search rebuilds deliberately leave the
+    // camera where the reader put it.
+    const shouldFrame = framedModeRef.current !== graphMode;
+    framedModeRef.current = graphMode;
+    let framed = false;
+    const frameGraph = () => {
+      if (framed) return;
+      framed = true;
+      fitGraphToViewport(svg, zoomBehavior, positionedNodes, width, height);
+    };
+    if (shouldFrame) {
+      // Hierarchy layout is deterministic; the concept force map is framed once
+      // it settles so the transform is not stale.
+      if (simulation) simulation.on('end.framing', frameGraph);
+      else frameGraph();
+    }
+
     return () => {
       simulation?.stop();
       svg.on('wheel.pan', null);
@@ -429,7 +471,13 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
     nodeHaloRef.current?.attr('stroke-width', d => (d.id === selectedNodeId ? 3 : 1.5));
     nodeLabelRef.current?.attr('font-weight', d => (d.id === selectedNodeId ? '700' : '500'));
 
+    // Only a genuine selection change re-centres; a layout rebuild (filter,
+    // search, mode switch) keeps the framing set by the layout effect.
+    const selectionChanged = prevSelectedRef.current !== selectedNodeId;
+    prevSelectedRef.current = selectedNodeId;
+
     if (
+      !selectionChanged ||
       graphMode === 'concept' ||
       !selectedNodeId ||
       !svgRef.current ||
@@ -688,6 +736,128 @@ export function RelationGraph({ graph, currentNodeId, onSelectNode, onSwitchView
   );
 }
 
+/* --------------------------------------------------------------------------
+   Graph label metrics & viewport framing
+   -------------------------------------------------------------------------- */
+
+const LABEL_FONT_SIZE = 12;
+const LABEL_LINE_HEIGHT = 14;
+const LABEL_LINE_CHARS = 8;
+const MAX_LABEL_LINES = 2;
+const TREE_BASE_GAP = 120;
+const TREE_LEVEL_GAP = 155;
+
+/**
+ * Split a long node title across at most two lines. A two-line label halves the
+ * horizontal footprint of a wide tree, which keeps the framed view legible. The
+ * full, untruncated title stays available in the node tooltip.
+ */
+function wrapLabel(text, maxChars = LABEL_LINE_CHARS, maxLines = MAX_LABEL_LINES) {
+  const value = String(text ?? '').trim();
+  if (!value) return [''];
+  const lines = [];
+  let rest = value;
+  while (rest && lines.length < maxLines) {
+    if (rest.length <= maxChars) {
+      lines.push(rest);
+      rest = '';
+    } else if (lines.length === maxLines - 1) {
+      lines.push(`${rest.slice(0, maxChars - 1)}…`);
+      rest = '';
+    } else {
+      lines.push(rest.slice(0, maxChars));
+      rest = rest.slice(maxChars);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Estimate a title's rendered width without a DOM measurement: CJK glyphs are
+ * roughly square at the label font size, Latin/digits about 0.55 of it.
+ */
+function estimateLabelWidth(text) {
+  let width = 0;
+  for (const char of String(text ?? '')) {
+    width += /[\u2e80-\u9fff\uff00-\uffef]/.test(char) ? LABEL_FONT_SIZE : LABEL_FONT_SIZE * 0.55;
+  }
+  return width;
+}
+
+/** Per-node label geometry, shared by the layout, the renderer and framing. */
+function labelMetrics(node) {
+  const lines = wrapLabel(node?.title);
+  const width = Math.max(...lines.map(estimateLabelWidth));
+  return { labelHalf: Math.max(18, width / 2), labelLines: lines.length };
+}
+
+function nodeLabelHalf(node) {
+  return labelMetrics(node).labelHalf;
+}
+
+function prefersReducedMotion() {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  );
+}
+
+/**
+ * Fit every node (plus its title) into the viewport once. Insets keep the
+ * floating control bar and legend from covering the graph on small screens.
+ */
+function fitGraphToViewport(svg, zoomBehavior, nodes, width, height) {
+  if (!nodes.length || !zoomBehavior) return;
+
+  const narrow = width < 760;
+  const insetTop = narrow ? 150 : 96;
+  const insetBottom = narrow ? 72 : 64;
+  const insetSide = narrow ? 24 : 56;
+
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+
+  nodes.forEach(node => {
+    const half = node.labelHalf || nodeLabelHalf(node);
+    const ring = node.level === 'L0' ? 26 : node.level === 'L1' ? 22 : 18;
+    const firstDy = node.level === 'L0' ? 34 : node.level === 'L1' ? 28 : 24;
+    const lines = node.labelLines || 1;
+    minX = Math.min(minX, node.x - half);
+    maxX = Math.max(maxX, node.x + half);
+    minY = Math.min(minY, node.y - ring - 14);
+    maxY = Math.max(maxY, node.y + firstDy + lines * LABEL_LINE_HEIGHT);
+  });
+
+  const boxWidth = Math.max(maxX - minX, 1);
+  const boxHeight = Math.max(maxY - minY, 1);
+  const availableWidth = Math.max(width - insetSide * 2, 1);
+  const availableHeight = Math.max(height - insetTop - insetBottom, 1);
+  // A floor keeps labels legible on a very wide tree; the reader can pan the
+  // overflow rather than squinting at five-pixel text.
+  const scaleFloor = narrow ? 0.55 : 0.68;
+  const scale = Math.min(
+    1.15,
+    Math.max(scaleFloor, Math.min(availableWidth / boxWidth, availableHeight / boxHeight))
+  );
+  const centerX = (minX + maxX) / 2;
+  const centerY = (minY + maxY) / 2;
+  const translateX = insetSide + availableWidth / 2 - scale * centerX;
+  // Centre vertically when the tree fits; otherwise anchor the root's level to
+  // the top edge so the reading order starts where it should.
+  const translateY =
+    boxHeight * scale <= availableHeight
+      ? insetTop + availableHeight / 2 - scale * centerY
+      : insetTop - scale * minY + 8;
+
+  svg
+    .transition()
+    .duration(prefersReducedMotion() ? 0 : 420)
+    .call(zoomBehavior.transform, zoomIdentity.translate(translateX, translateY).scale(scale));
+}
+
 function layoutTree(nodes, width, _height) {
   if (nodes.length === 0) return [];
 
@@ -703,7 +873,15 @@ function layoutTree(nodes, width, _height) {
   );
   const treeData = { id: '__atlas-root__', children: roots };
   const root = hierarchy(treeData);
-  const tree = treeLayout().nodeSize([110, 155]);
+  // Reserve horizontal room per sibling pair from the estimated label width so
+  // long titles never share a column. Siblings sit one base gap apart; separate
+  // subtrees keep the doubled default separation.
+  const tree = treeLayout()
+    .nodeSize([TREE_BASE_GAP, TREE_LEVEL_GAP])
+    .separation((a, b) => {
+      const gap = nodeLabelHalf(a.data) + nodeLabelHalf(b.data) + 26;
+      return (a.parent === b.parent ? 1 : 2) * Math.max(1, gap / TREE_BASE_GAP);
+    });
   tree(root);
 
   const visible = root.descendants().filter(node => node.data.id !== '__atlas-root__');
@@ -715,8 +893,9 @@ function layoutTree(nodes, width, _height) {
 
   return visible.map(node => ({
     ...node.data,
+    ...labelMetrics(node.data),
     x: node.x + offsetX,
-    y: node.depth * 155 + offsetY
+    y: node.depth * TREE_LEVEL_GAP + offsetY
   }));
 }
 
@@ -823,12 +1002,20 @@ function linkPath(link) {
 
 function positionEdgeLabels(links, nodes, width, height) {
   const occupied = [];
-  const nodeBoxes = nodes.map(node => ({
-    left: node.x - 28,
-    right: node.x + 28,
-    top: node.y - 28,
-    bottom: node.y + 28
-  }));
+  const nodeBoxes = nodes.map(node => {
+    const half = Math.max(28, node.labelHalf || 0);
+    const titleBlock =
+      (node.level === 'L0' ? 34 : node.level === 'L1' ? 28 : 24) +
+      (node.labelLines || 1) * LABEL_LINE_HEIGHT;
+    return {
+      left: node.x - half,
+      right: node.x + half,
+      top: node.y - 28,
+      // Cover the ring *and* the wrapped title beneath it so an edge label
+      // never lands on top of a node name.
+      bottom: node.y + titleBlock
+    };
+  });
 
   links.forEach(link => {
     link.labelVisible = false;