@laitszkin/apollo-toolkit 3.11.3 → 3.11.4

package/CHANGELOG.md

@@ -10,6 +10,20 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.4] - 2026-05-12
+
+### Added
+
+- Macro atlas: `measureEdgeLabel` wraps long edge labels (including CJK) with honest width/height for elkjs so orthogonal routes reserve space proportional to label size; `renderMacroSvg` paints wrapped labels as stacked `<tspan>` lines on one anchor.
+- Macro atlas: isolated feature clusters (no intra-feature edges and not an endpoint of a root-level cross-feature edge) use elk **rectpacking** with aspect-ratio hint for a grid-like pack instead of a tall vertical column of sub-modules.
+- Tests: CJK submodule sizing, edge-label wrapping, rectpacking vs layered cluster selection, compact rectpack geometry, `m-edge--cross` markup, and cross-edge CSS dim/hover rules.
+
+### Changed
+
+- Macro layout (`layout.js`): CJK-aware text width and visual-width wrapping for sub-module **role** lines; raised `SUB_WIDTH_MAX` / `SUB_HEIGHT_MAX` and `MAX_ROLE_LINES`; sub-module boxes prefer fewer wrapped lines when content allows.
+- Root ELK graph: `elk.aspectRatio` 16:9, tighter node/layer spacing and padding, `BALANCED` node placement, `EDGE_LENGTH` post-compaction; cluster padding and internal spacing reduced.
+- Cross-feature edges: root-level edges render with `m-edge--cross`; default lower opacity/thinner stroke, full strength on hover/focus so intra-feature flow reads first.
+
 ## [v3.11.3] - 2026-05-11
 
 ### Added

package/init-project-html/lib/atlas/assets/architecture.css

@@ -433,8 +433,23 @@ p { line-height: 1.6; color: var(--vellum-soft); }
   font-family: var(--font-mono);
   font-size: 11px;
   letter-spacing: 0.02em;
+  paint-order: stroke fill;
+  stroke: var(--ink);
+  stroke-width: 3.5;
+  stroke-linejoin: round;
+  pointer-events: none;
 }
 
+/* Cross-feature edges are routed across the entire atlas and tend to
+   be the loudest lines on screen. Dim them so intra-feature flow
+   reads first; restore full strength on hover/focus. */
+.m-edge--cross path { opacity: 0.5; stroke-width: 1.1; }
+.m-edge--cross .m-edge__label { opacity: 0.7; }
+.m-edge--cross:hover path,
+.m-edge--cross:focus-within path { opacity: 1; stroke-width: 1.8; }
+.m-edge--cross:hover .m-edge__label,
+.m-edge--cross:focus-within .m-edge__label { opacity: 1; }
+
 /* =================================================================
    feature page
    ================================================================= */

package/init-project-html/lib/atlas/layout.js

@@ -17,11 +17,15 @@ const ELK = require('elkjs');
 const SUB_WIDTH = 240;
 const SUB_HEIGHT = 92;
 
-// Box-sizing knobs (intrinsic SVG coordinates).
+// Box-sizing knobs (intrinsic SVG coordinates). The width/height caps
+// are intentionally generous so CJK roles — which paint at ~1em per
+// character instead of ~0.55em — can grow into a readable rectangle
+// without spilling outside the box (the original ~360×220 cap was
+// only honest for Latin text).
 const SUB_WIDTH_MIN = 220;
-const SUB_WIDTH_MAX = 360;
+const SUB_WIDTH_MAX = 520;
 const SUB_HEIGHT_MIN = 92;
-const SUB_HEIGHT_MAX = 220;
+const SUB_HEIGHT_MAX = 360;
 const SUB_SIDE_PAD = 16;
 const SUB_TOP_PAD = 14;
 const SUB_BOTTOM_PAD = 14;
@@ -30,12 +34,22 @@ const KIND_LINE = 16;      // kind chip line
 const ROLE_LINE = 16;      // each role line
 const KIND_GAP = 4;
 const ROLE_GAP = 8;
-const MAX_ROLE_LINES = 4;
+const MAX_ROLE_LINES = 6;
 
-const CLUSTER_PAD_TOP = 60;
-const CLUSTER_PAD_SIDE = 24;
-const CLUSTER_PAD_BOTTOM = 28;
-const EDGE_LABEL_HEIGHT = 18;
+const CLUSTER_PAD_TOP = 44;
+const CLUSTER_PAD_SIDE = 16;
+const CLUSTER_PAD_BOTTOM = 18;
+
+// Font sizes mirror architecture.css so the layout math agrees with
+// what the SVG actually paints.
+const SLUG_FONT_PX = 15;
+const KIND_FONT_PX = 10;
+const ROLE_FONT_PX = 11.5;
+const EDGE_LABEL_FONT_PX = 11;
+const EDGE_LABEL_LINE_PX = 14;
+const EDGE_LABEL_LINE_WIDTH_MAX = 220;
+const EDGE_LABEL_PAD_X = 18;
+const EDGE_LABEL_PAD_Y = 8;
 
 const KIND_LABELS = {
   ui: 'UI',
@@ -47,30 +61,128 @@ const KIND_LABELS = {
   external: 'external',
 };
 
-function estimateLabelWidth(text) {
-  if (!text) return 0;
-  return Math.min(220, Math.max(40, String(text).length * 7 + 16));
+// East-Asian Wide / Full-width detection. The ranges follow the
+// canonical "wide" / "fullwidth" code blocks (Unicode TR11) — we use
+// them to switch between a ~0.55em-per-char Latin metric and a
+// ~1.0em-per-char CJK metric so layout matches paint.
+function isWideChar(ch) {
+  const code = ch.codePointAt(0);
+  return (
+    (code >= 0x1100 && code <= 0x115F) ||
+    (code >= 0x2E80 && code <= 0x9FFF) ||
+    (code >= 0xA000 && code <= 0xA4CF) ||
+    (code >= 0xAC00 && code <= 0xD7A3) ||
+    (code >= 0xF900 && code <= 0xFAFF) ||
+    (code >= 0xFE30 && code <= 0xFE4F) ||
+    (code >= 0xFF00 && code <= 0xFF60) ||
+    (code >= 0xFFE0 && code <= 0xFFE6) ||
+    (code >= 0x20000 && code <= 0x2FFFD)
+  );
+}
+
+function charWidthFactor(ch) {
+  if (isWideChar(ch)) return 1.0;
+  if (ch === ' ') return 0.30;
+  if (/[A-Za-z0-9]/.test(ch)) return 0.55;
+  return 0.50;
 }
 
-// Approximate render width of a string in the target font. The 0.6
-// factor is a deliberate over-estimate for our sans-serif stack so
-// the chosen width almost always leaves a little breathing room.
 function approxTextWidth(text, fontPx) {
-  return String(text || '').length * fontPx * 0.6;
+  if (!text) return 0;
+  let w = 0;
+  for (const ch of String(text)) w += fontPx * charWidthFactor(ch);
+  return w;
 }
 
-function wrapToLines(text, maxChars) {
+// Greedy wrap by *visual* width. CJK characters break between any
+// two characters; ASCII words stay whole; whitespace is a soft break.
+function wrapByVisualWidth(text, maxWidthPx, fontPx) {
   if (!text) return [];
-  const words = String(text).split(/\s+/).filter(Boolean);
+  const str = String(text);
   const lines = [];
-  let current = '';
-  for (const word of words) {
-    if (!current) { current = word; continue; }
-    if ((current.length + 1 + word.length) <= maxChars) current = `${current} ${word}`;
-    else { lines.push(current); current = word; }
+  let line = '';
+  let lineW = 0;
+
+  function flush() {
+    if (line.length > 0) lines.push(line.replace(/\s+$/, ''));
+    line = '';
+    lineW = 0;
   }
-  if (current) lines.push(current);
-  return lines;
+
+  let i = 0;
+  while (i < str.length) {
+    const cp = str.codePointAt(i);
+    const ch = String.fromCodePoint(cp);
+    const advance = ch.length;
+
+    if (ch === '\n') {
+      flush();
+      i += advance;
+    } else if (isWideChar(ch)) {
+      const w = fontPx * 1.0;
+      if (line && lineW + w > maxWidthPx) flush();
+      line += ch;
+      lineW += w;
+      i += advance;
+    } else if (/\s/.test(ch)) {
+      const w = fontPx * 0.30;
+      if (line) {
+        if (lineW + w > maxWidthPx) flush();
+        else { line += ch; lineW += w; }
+      }
+      i += advance;
+    } else {
+      let word = '';
+      let wordW = 0;
+      while (i < str.length) {
+        const cp2 = str.codePointAt(i);
+        const ch2 = String.fromCodePoint(cp2);
+        if (isWideChar(ch2) || /\s/.test(ch2)) break;
+        word += ch2;
+        wordW += fontPx * charWidthFactor(ch2);
+        i += ch2.length;
+      }
+      if (line && lineW + wordW > maxWidthPx) flush();
+      line += word;
+      lineW += wordW;
+    }
+  }
+  flush();
+  return lines.filter((l) => l.length > 0);
+}
+
+// Short labels (feature title, sub-module slug) — single-line width
+// only. Capped so very long ASCII slugs do not blow up the cluster
+// header band; CJK titles still get an honest visual width.
+function estimateLabelWidth(text) {
+  if (!text) return 0;
+  return Math.min(320, Math.max(40, Math.ceil(approxTextWidth(text, 13)) + 16));
+}
+
+// Edge labels — wrap into a tall enough rectangle so elkjs reserves
+// proportional edge length (longer text ⇒ longer arrow). The wrapped
+// text is stored with '\n' separators so render.js can paint each
+// line as its own <tspan> centered on the same anchor.
+function measureEdgeLabel(text) {
+  if (!text) return { text: '', lines: [], width: 0, height: 0 };
+  const raw = String(text);
+  const singleW = approxTextWidth(raw, EDGE_LABEL_FONT_PX);
+  if (singleW <= EDGE_LABEL_LINE_WIDTH_MAX) {
+    return {
+      text: raw,
+      lines: [raw],
+      width: Math.max(40, Math.ceil(singleW) + EDGE_LABEL_PAD_X),
+      height: EDGE_LABEL_LINE_PX + EDGE_LABEL_PAD_Y,
+    };
+  }
+  const lines = wrapByVisualWidth(raw, EDGE_LABEL_LINE_WIDTH_MAX, EDGE_LABEL_FONT_PX);
+  const widestLine = lines.reduce((m, l) => Math.max(m, approxTextWidth(l, EDGE_LABEL_FONT_PX)), 0);
+  return {
+    text: lines.join('\n'),
+    lines,
+    width: Math.ceil(widestLine) + EDGE_LABEL_PAD_X,
+    height: lines.length * EDGE_LABEL_LINE_PX + EDGE_LABEL_PAD_Y,
+  };
 }
 
 // measureSubmodule picks a width + height that fit the slug, the kind
@@ -83,26 +195,33 @@ function measureSubmodule(sub) {
   const kindLabel = KIND_LABELS[sub && sub.kind] || (sub && sub.kind) || 'service';
   const role = (sub && sub.role) || '';
 
-  const slugW = approxTextWidth(slug, 14);
-  const kindW = approxTextWidth(kindLabel, 11);
+  const slugW = approxTextWidth(slug, SLUG_FONT_PX);
+  // Kind chip is upper-cased + letter-spaced in CSS (0.22em); add ~30% slack.
+  const kindW = approxTextWidth(kindLabel.toUpperCase(), KIND_FONT_PX) * 1.3;
   const baseInner = Math.max(slugW, kindW);
 
-  // Aim to keep the role within ~3 lines: choose a width whose text
-  // area can hold ceil(roleLen / 3) characters, then clamp.
-  const roleLen = role.length;
+  // Auto-expand the box to fit the role with as few lines as
+  // possible: prefer 1 line if it fits inside SUB_WIDTH_MAX, else 2,
+  // else 3 — and only wrap further when even 3 lines would exceed
+  // the cap. This is what "boxes auto-expand to their content" means
+  // for CJK roles whose glyphs are ~2× wider than Latin.
+  const roleVisualW = approxTextWidth(role, ROLE_FONT_PX);
+  const maxInner = SUB_WIDTH_MAX - SUB_SIDE_PAD * 2;
   let chosenInner;
   if (!role) {
     chosenInner = baseInner;
   } else {
-    const targetCharsPerLine = Math.max(20, Math.ceil(roleLen / 3));
-    chosenInner = Math.max(baseInner, targetCharsPerLine * 11 * 0.55);
+    let target;
+    if (roleVisualW <= maxInner) target = roleVisualW;
+    else if (Math.ceil(roleVisualW / 2) <= maxInner) target = Math.ceil(roleVisualW / 2);
+    else target = Math.ceil(roleVisualW / 3);
+    chosenInner = Math.max(baseInner, Math.max(180, target));
   }
   const width = Math.max(SUB_WIDTH_MIN, Math.min(SUB_WIDTH_MAX, Math.ceil(chosenInner + SUB_SIDE_PAD * 2)));
 
   // With the chosen width fixed, wrap the role for real and count lines.
   const innerW = width - SUB_SIDE_PAD * 2;
-  const charsPerLine = Math.max(12, Math.floor(innerW / (11 * 0.55)));
-  let roleLines = role ? wrapToLines(role, charsPerLine) : [];
+  let roleLines = role ? wrapByVisualWidth(role, innerW, ROLE_FONT_PX) : [];
   if (roleLines.length > MAX_ROLE_LINES) {
     roleLines = roleLines.slice(0, MAX_ROLE_LINES);
     const last = roleLines[MAX_ROLE_LINES - 1];
@@ -129,7 +248,53 @@ function endpointId(endpoint, ownerFeature) {
   return null;
 }
 
+function clusterLayoutOptions(feature, isCrossEdgeEndpoint) {
+  // If the feature declares intra-feature flow edges OR is an
+  // endpoint of any root-level cross-feature edge, the cluster must
+  // use a hierarchy-friendly directional algorithm (layered) so elk
+  // can route edges into/out of its children. Mixing rectpacking
+  // with layered hierarchy edges raises UnsupportedGraphException.
+  //
+  // Otherwise (truly isolated leaf cluster) pack sub-modules into a
+  // roughly square grid so a 10-sub-module feature does not become a
+  // tall column that wastes the rest of the viewport.
+  const hasInternalEdges = Array.isArray(feature.edges) && feature.edges.length > 0;
+  const common = {
+    'elk.padding': `[top=${CLUSTER_PAD_TOP},left=${CLUSTER_PAD_SIDE},bottom=${CLUSTER_PAD_BOTTOM},right=${CLUSTER_PAD_SIDE}]`,
+    'elk.spacing.nodeNode': '16',
+    'elk.nodeLabels.placement': '[H_CENTER, V_TOP, INSIDE]',
+  };
+  if (hasInternalEdges || isCrossEdgeEndpoint) {
+    return {
+      ...common,
+      'elk.algorithm': 'layered',
+      'elk.direction': 'DOWN',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '28',
+      'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
+    };
+  }
+  return {
+    ...common,
+    'elk.algorithm': 'rectpacking',
+    'elk.aspectRatio': '1.4',
+    'elk.rectpacking.optimizationGoal': 'MAX_SCALE_DRIVEN',
+  };
+}
+
+function collectCrossEdgeFeatures(state) {
+  const set = new Set();
+  function note(endpoint) {
+    if (endpoint && typeof endpoint === 'object' && endpoint.feature) set.add(endpoint.feature);
+  }
+  for (const edge of state.edges || []) {
+    note(edge.from);
+    note(edge.to);
+  }
+  return set;
+}
+
 function buildGraph(state) {
+  const crossEndpoints = collectCrossEdgeFeatures(state);
   const children = (state.features || []).map((feature) => ({
     id: `feature::${feature.slug}`,
     labels: [{
@@ -138,14 +303,7 @@ function buildGraph(state) {
       width: estimateLabelWidth(feature.title || feature.slug),
       height: 24,
     }],
-    layoutOptions: {
-      'elk.padding': `[top=${CLUSTER_PAD_TOP},left=${CLUSTER_PAD_SIDE},bottom=${CLUSTER_PAD_BOTTOM},right=${CLUSTER_PAD_SIDE}]`,
-      'elk.spacing.nodeNode': '24',
-      'elk.algorithm': 'layered',
-      'elk.direction': 'DOWN',
-      'elk.layered.spacing.nodeNodeBetweenLayers': '36',
-      'elk.nodeLabels.placement': '[H_CENTER, V_TOP, INSIDE]',
-    },
+    layoutOptions: clusterLayoutOptions(feature, crossEndpoints.has(feature.slug)),
     children: (feature.submodules || []).map((sub) => {
       const box = measureSubmodule(sub);
       return {
@@ -168,17 +326,18 @@ function buildGraph(state) {
 
   function pushEdge(list, raw, sourceId, targetId) {
     if (!sourceId || !targetId) return;
-    list.push({
-      id: raw.id || `e-${nextEdgeId++}`,
-      sources: [sourceId],
-      targets: [targetId],
-      labels: raw.label ? [{
-        id: `${raw.id || `e-${nextEdgeId}`}::label`,
-        text: raw.label,
-        width: estimateLabelWidth(raw.label),
-        height: EDGE_LABEL_HEIGHT,
-      }] : [],
-    });
+    const id = raw.id || `e-${nextEdgeId++}`;
+    let labels = [];
+    if (raw.label) {
+      const m = measureEdgeLabel(raw.label);
+      labels = [{
+        id: `${id}::label`,
+        text: m.text,
+        width: m.width,
+        height: m.height,
+      }];
+    }
+    list.push({ id, sources: [sourceId], targets: [targetId], labels });
   }
 
   for (const feature of state.features || []) {
@@ -203,12 +362,20 @@ function buildGraph(state) {
       'elk.algorithm': 'layered',
       'elk.direction': 'RIGHT',
       'elk.hierarchyHandling': 'INCLUDE_CHILDREN',
-      'elk.spacing.nodeNode': '60',
-      'elk.layered.spacing.nodeNodeBetweenLayers': '100',
-      'elk.padding': '[top=40,left=40,bottom=40,right=40]',
+      // 16:9 hint so elk stops sprawling along one axis and leaving
+      // the other half of the viewport empty.
+      'elk.aspectRatio': '1.778',
+      'elk.spacing.nodeNode': '32',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '60',
+      'elk.padding': '[top=20,left=20,bottom=20,right=20]',
       'elk.edgeRouting': 'ORTHOGONAL',
       'elk.edgeLabels.inline': 'false',
       'elk.edgeLabels.placement': 'CENTER',
+      // Tighter post-layout placement: BALANCED keeps related nodes
+      // adjacent, EDGE_LENGTH compaction pulls disconnected
+      // sub-graphs in toward each other so unused columns collapse.
+      'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
+      'elk.layered.compaction.postCompaction.strategy': 'EDGE_LENGTH',
     },
     children,
     edges: rootEdges,
@@ -327,4 +494,7 @@ module.exports = {
   assertNoOverlap,
   buildGraph,
   measureSubmodule,
+  measureEdgeLabel,
+  approxTextWidth,
+  wrapByVisualWidth,
 };

package/init-project-html/lib/atlas/render.js

@@ -81,13 +81,13 @@ function edgeKindFor(stateEdge) {
 function findEdgeMeta(state, edgeId) {
   for (const feature of state.features || []) {
     for (const e of feature.edges || []) {
-      if (e.id === edgeId) return e;
+      if (e.id === edgeId) return { edge: e, scope: 'feature' };
     }
   }
   for (const e of state.edges || []) {
-    if (e.id === edgeId) return e;
+    if (e.id === edgeId) return { edge: e, scope: 'root' };
   }
-  return null;
+  return { edge: null, scope: 'feature' };
 }
 
 function renderMacroSvg(layout, state) {
@@ -144,17 +144,29 @@ function renderMacroSvg(layout, state) {
   }
 
   for (const edge of layout.edges) {
-    const meta = findEdgeMeta(state, edge.id);
+    const { edge: meta, scope } = findEdgeMeta(state, edge.id);
     const kind = edgeKindFor(meta);
     const d = renderEdgePath(edge);
     if (!d) continue;
-    parts.push(`    <g class="m-edge m-edge--${kind}" data-edge="${htmlEscape(edge.id)}">`);
+    const scopeClass = scope === 'root' ? ' m-edge--cross' : '';
+    parts.push(`    <g class="m-edge m-edge--${kind}${scopeClass}" data-edge="${htmlEscape(edge.id)}">`);
     parts.push(`      <path d="${d}" fill="none" marker-end="url(#arrow-${kind})" />`);
     for (const label of edge.labels || []) {
       if (!label.text) continue;
-      const lx = label.x + (label.width || 0) / 2;
-      const ly = label.y + (label.height || 0) / 2 + 4;
-      parts.push(`      <text class="m-edge__label" x="${lx.toFixed(2)}" y="${ly.toFixed(2)}" text-anchor="middle">${htmlEscape(label.text)}</text>`);
+      const lines = String(label.text).split('\n');
+      const cx = label.x + (label.width || 0) / 2;
+      const lineH = 14; // matches EDGE_LABEL_LINE_PX in layout.js
+      const blockH = lines.length * lineH;
+      const firstBaseline = label.y + ((label.height || 0) - blockH) / 2 + (lineH - 3);
+      parts.push(`      <text class="m-edge__label" x="${cx.toFixed(2)}" y="${firstBaseline.toFixed(2)}" text-anchor="middle">`);
+      lines.forEach((line, idx) => {
+        if (idx === 0) {
+          parts.push(`        <tspan x="${cx.toFixed(2)}">${htmlEscape(line)}</tspan>`);
+        } else {
+          parts.push(`        <tspan x="${cx.toFixed(2)}" dy="${lineH}">${htmlEscape(line)}</tspan>`);
+        }
+      });
+      parts.push('      </text>');
     }
     parts.push('    </g>');
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "3.11.3",
+  "version": "3.11.4",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",