@laitszkin/apollo-toolkit 3.11.2 → 3.11.4

package/init-project-html/lib/atlas/assets/viewer.client.js

@@ -69,10 +69,18 @@
       return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
     }
 
+    // The diagram viewport owns the wheel gesture entirely: ANY wheel
+    // event that lands inside the viewport is consumed so the host page
+    // never scrolls underneath the user. The wheel zooms the SVG around
+    // the cursor; trackpad pinch-zoom (which arrives as ctrlKey wheel
+    // on macOS) is treated the same way for a single predictable model.
     viewport.addEventListener('wheel', function (evt) {
-      if (!evt.ctrlKey && !evt.metaKey && Math.abs(evt.deltaY) < 4 && Math.abs(evt.deltaX) < 4) return;
       evt.preventDefault();
-      const factor = evt.deltaY > 0 ? 1.1 : 1 / 1.1;
+      evt.stopPropagation();
+      const absX = Math.abs(evt.deltaX);
+      const absY = Math.abs(evt.deltaY);
+      if (absX < 0.5 && absY < 0.5) return;
+      const factor = evt.deltaY > 0 ? 1.08 : 1 / 1.08;
       const pt = clientToSvg(evt);
       zoom(factor, pt.x, pt.y);
     }, { passive: false });

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

@@ -55,6 +55,10 @@ function head({ title, assetRel, pageKind }) {
     '  <meta charset="utf-8">',
     `  <title>${htmlEscape(title)}</title>`,
     '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+    '  <meta name="color-scheme" content="dark">',
+    '  <link rel="preconnect" href="https://fonts.googleapis.com">',
+    '  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>',
+    '  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..600;1,9..144,300..500&family=Geist:wght@300..700&family=JetBrains+Mono:wght@400..600&display=swap">',
     `  <link rel="stylesheet" href="${assetRel}/architecture.css">`,
     '</head>',
   ].join('\n');
@@ -77,24 +81,24 @@ 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) {
   if (layout.empty) {
-    return '<svg class="atlas-svg" viewBox="0 0 320 160" role="img" aria-label="Atlas is empty"><text x="160" y="80" text-anchor="middle" fill="currentColor">Atlas has no features yet</text></svg>';
+    return '<svg class="atlas-svg" viewBox="0 0 320 160" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Atlas is empty"><text x="160" y="80" text-anchor="middle" fill="currentColor">Atlas has no features yet</text></svg>';
   }
   const pad = 24;
   const vbW = Math.max(320, Math.ceil(layout.width + pad * 2));
   const vbH = Math.max(160, Math.ceil(layout.height + pad * 2));
   const parts = [];
-  parts.push(`<svg class="atlas-svg" viewBox="0 0 ${vbW} ${vbH}" role="img" aria-label="Project architecture atlas" data-atlas-svg="macro">`);
+  parts.push(`<svg class="atlas-svg" viewBox="0 0 ${vbW} ${vbH}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Project architecture atlas" data-atlas-svg="macro">`);
   parts.push('  <defs>');
   for (const kind of ['call', 'return', 'data-row', 'failure']) {
     parts.push(`    <marker id="arrow-${kind}" class="m-arrow m-arrow--${kind}" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>`);
@@ -140,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>');
   }
@@ -339,7 +355,7 @@ function renderInternalDataflowSvg(steps) {
   const totalW = padLeft + boxW + padRight;
 
   const parts = [];
-  parts.push(`<svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 ${totalW} ${totalH}" role="img" aria-label="Internal dataflow">`);
+  parts.push(`<svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 ${totalW} ${totalH}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Internal dataflow">`);
   parts.push('  <defs>');
   parts.push('    <marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>');
   parts.push('  </defs>');
@@ -539,9 +555,46 @@ async function renderAll({ outDir, state, scope = null, removedPaths = [] }) {
     if (fs.existsSync(file)) fs.rmSync(file);
   }
 
+  // Full base render (no scope): sweep stale HTML so `apltk architecture
+  // render` is a true refresh — old feature folders or renamed sub-modules
+  // do not linger with the previous (broken) markup or styling.
+  if (!scope) {
+    sweepOrphanFeaturePages(outDir, state);
+  }
+
   return { written, layout };
 }
 
+function sweepOrphanFeaturePages(outDir, state) {
+  const featuresRoot = path.join(outDir, 'features');
+  if (!fs.existsSync(featuresRoot)) return;
+  const validFeatures = new Map();
+  for (const f of state.features || []) {
+    validFeatures.set(f.slug, new Set((f.submodules || []).map((s) => s.slug)));
+  }
+  let entries;
+  try { entries = fs.readdirSync(featuresRoot, { withFileTypes: true }); } catch (_e) { return; }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const featDir = path.join(featuresRoot, entry.name);
+    if (!validFeatures.has(entry.name)) {
+      fs.rmSync(featDir, { recursive: true, force: true });
+      continue;
+    }
+    const wantedSubs = validFeatures.get(entry.name);
+    let files;
+    try { files = fs.readdirSync(featDir); } catch (_e) { continue; }
+    for (const file of files) {
+      if (!file.toLowerCase().endsWith('.html')) continue;
+      if (file === 'index.html') continue;
+      const slug = file.slice(0, -5);
+      if (!wantedSubs.has(slug)) {
+        fs.rmSync(path.join(featDir, file), { force: true });
+      }
+    }
+  }
+}
+
 function scopeFromDiff(diff) {
   const submodules = [];
   for (const item of diff.modifiedSubmodules || []) submodules.push(item);

package/package.json

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