crewforth 3.1.0 → 3.2.0-rc.1

package/kit/studio/web/graph-plan.js

@@ -52,7 +52,13 @@ export const AUTO = {
   readable: 0.75,
   // Same-type siblings fold into one card from this many, once the picture is too tall.
   stackAt: 3,
+  // How far past what fits a picture may run and still be drawn as cards: the rest is a pan away, at a zoom the
+  // cards are read at (the canvas's own fit does not go under `readable` then). A long column of agent types beside
+  // an empty half of the pane turned to chips at 1.0; 1.5 is a starting point, not a measured one.
+  overflow: 1.5,
 };
+/** The height past which Auto gives cards up: what fits, and the overflow it allows on top. */
+const overLimit = (h, tallest) => h > tallest * AUTO.overflow;
 
 export const GROUPINGS = ['run', 'type', 'parent', 'order', 'none'];
 export const DENSITIES = ['auto', 'comfortable', 'compact'];
@@ -422,12 +428,12 @@ export function plan(nodes, opts = {}) {
   let compact = asked === 'compact';
   let stacked = false;
   let box = lay(pass.shown, compact);
-  if (asked === 'auto' && box.height > tallest) {
+  if (asked === 'auto' && overLimit(box.height, tallest)) {
     if (group !== 'none' && group !== 'type') {
       const folded = drawFrom(itemsOf(nodes, { group, density: asked, seq, stack: true, aside }));
       if (folded.shown.some((it) => it.kind === 'group' && it.type === 'type')) { pass = folded; stacked = true; box = lay(pass.shown, false); }
     }
-    if (box.height > tallest) { compact = true; box = lay(pass.shown, true); }
+    if (overLimit(box.height, tallest)) { compact = true; box = lay(pass.shown, true); }
   }
   const drawnItems = pass.shown;
   const drawn = pass.count;
@@ -523,7 +529,7 @@ function planOrder(nodes, asked, opts, tallest = AUTO.tallest) {
   };
   let compact = asked === 'compact';
   let box = lay(compact);
-  if (asked === 'auto' && box.height > tallest) { compact = true; box = lay(true); }
+  if (asked === 'auto' && overLimit(box.height, tallest)) { compact = true; box = lay(true); }
   const { items } = box;
   let { height } = box;
 
@@ -586,7 +592,7 @@ export function crowdFolds(nodes, opts = {}) {
   const folds = [];
   for (let guard = 0; guard < 64; guard += 1) {
     const p = plan(nodes, { ...opts, open, pinned: new Map(), sessionY: null });
-    if (p.height <= Math.max(AUTO.tallest, opts.tallest ?? 0)) break;
+    if (!overLimit(p.height, Math.max(AUTO.tallest, opts.tallest ?? 0))) break;
     const next = p.items.filter((it) => it.kind === 'group' && it.open && it.members.length > 1)
       .sort((a, b) => b.members.length - a.members.length || String(a.id).localeCompare(String(b.id)))[0];
     if (!next) break;

package/kit/studio/web/index.html

@@ -25,6 +25,7 @@
   <span class="bar-fill"></span>
   <div id="graph-summary" class="chips" role="group" aria-label="Session summary"></div>
   <span class="bar-sep" aria-hidden="true"></span>
+  <span id="role" class="badge" title="This link reads the panel and changes nothing" hidden>Read-only</span>
   <span id="pulse" class="live" role="status" data-state="connecting"><span class="dot"></span><strong>Connecting</strong><span class="live-detail"></span></span>
   <button id="theme" class="btn icon ghost" type="button" aria-label="Switch theme">
     <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M13 9.5A5.5 5.5 0 0 1 6.5 3a5.5 5.5 0 1 0 6.5 6.5z"/></svg>
@@ -95,6 +96,9 @@
         <button id="view-models" class="seg-btn" type="button" role="tab" aria-label="Models view" aria-selected="false" aria-controls="models">
           <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 13V8M8 13V3M13 13V6"/></svg><span class="tb-words">Models</span>
         </button>
+        <button id="view-map" class="seg-btn" type="button" role="tab" aria-label="Map view" aria-selected="false" aria-controls="map">
+          <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><rect x="2" y="2.5" width="5" height="3.5" rx="1"/><rect x="9" y="2.5" width="5" height="3.5" rx="1"/><rect x="5.5" y="10" width="5" height="3.5" rx="1"/><path d="M4.5 6v2h7V6M8 8v2"/></svg><span class="tb-words">Map</span>
+        </button>
       </div>
       <button id="tb-group" data-view="graph timeline" class="btn sm ghost tb-menu" type="button" aria-haspopup="menu">Group <span>Workflow run</span><svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M4 6l4 4 4-4"/></svg></button>
       <button id="tb-density" data-view="graph" class="btn sm ghost tb-menu" type="button" aria-haspopup="menu">Density <span>Auto</span><svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M4 6l4 4 4-4"/></svg></button>
@@ -119,17 +123,17 @@
       <button id="tb-fold" data-view="graph timeline list" class="btn sm" type="button" aria-label="Fold all groups">
         <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M6 3l5 5-5 5"/></svg><span class="tb-words">Fold all</span>
       </button>
-      <button id="tb-zoom-out" data-view="graph" class="btn icon sm ghost" type="button" aria-label="Zoom out">
+      <button id="tb-zoom-out" data-view="graph map" class="btn icon sm ghost" type="button" aria-label="Zoom out">
         <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 8h10"/></svg>
       </button>
-      <button id="tb-zoom" data-view="graph" class="tb-zoom" type="button" title="Back to 100%" aria-label="Zoom 100%. Back to 100%">100%</button>
-      <button id="tb-zoom-in" data-view="graph" class="btn icon sm ghost" type="button" aria-label="Zoom in">
+      <button id="tb-zoom" data-view="graph map" class="tb-zoom" type="button" title="Back to 100%" aria-label="Zoom 100%. Back to 100%">100%</button>
+      <button id="tb-zoom-in" data-view="graph map" class="btn icon sm ghost" type="button" aria-label="Zoom in">
         <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 3v10M3 8h10"/></svg>
       </button>
-      <button id="tb-reset" data-view="graph" class="btn sm" type="button" title="Reset layout (r)" aria-label="Reset layout: put the cards moved by hand back where they belong" disabled>
+      <button id="tb-reset" data-view="graph map" class="btn sm" type="button" title="Reset layout (r)" aria-label="Reset layout: put the cards moved by hand back where they belong" disabled>
         <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M3 8a5 5 0 1 0 1.6-3.7M3 3v3h3"/></svg><span class="tb-words">Reset layout</span>
       </button>
-      <button id="tb-fit" data-view="graph" class="btn sm" type="button" aria-label="Fit the graph to the view">
+      <button id="tb-fit" data-view="graph map" class="btn sm" type="button" aria-label="Fit the graph to the view">
         <svg class="ic" viewBox="0 0 16 16" aria-hidden="true"><path d="M2.5 5.5v-3h3M10.5 2.5h3v3M13.5 10.5v3h-3M5.5 13.5h-3v-3"/></svg><span class="tb-words">Fit</span>
       </button>
     </div>
@@ -139,6 +143,7 @@
     <div id="timeline" role="tabpanel" aria-labelledby="view-timeline" hidden></div>
     <div id="list" role="tabpanel" aria-labelledby="view-list" hidden></div>
     <div id="models" role="tabpanel" aria-labelledby="view-models" hidden></div>
+    <div id="map" role="tabpanel" aria-labelledby="view-map" hidden></div>
     <div id="first-run" class="first-run" hidden></div>
     <div id="terminal-wait" class="terminal-wait" role="status" hidden></div>
     <div id="dock" role="region" aria-label="Waiting for approval" hidden></div>

package/kit/studio/web/map-plan.js

@@ -0,0 +1,341 @@
+// What the Map view draws, worked out from a crew map. No page in it.
+//
+// The map is Crewforth's (server/lib/crew-map.js reads it). This file puts each node in a band, says which lines
+// a selection lights, orders the findings and words them. It invents no layer: a module whose place the map does
+// not show goes to "Unplaced", and a finding the scanner hides by default stays hidden until asked for.
+
+export const BANDS = [
+  ['clients', 'Clients'],
+  ['entry', 'Entry points'],
+  ['core', 'Core'],
+  ['infra', 'Infrastructure'],
+  ['external', 'External'],
+  ['unplaced', 'Unplaced'],
+];
+
+const RESOURCE = { db: 'db', cache: 'cache', queue: 'queue', auth: 'auth', 'http-api': 'api' };
+export const resourceWord = (r) => RESOURCE[r] ?? String(r ?? 'external');
+
+/** The modules a finding is about: named in its data, or the module whose folder holds its first cited file. */
+export function findingModules(f, modules) {
+  const named = [f?.data?.module, ...(Array.isArray(f?.data?.modules) ? f.data.modules : [])].filter((x) => typeof x === 'string');
+  if (named.length) return [...new Set(named)];
+  const file = f?.evidence?.[0]?.file;
+  if (typeof file !== 'string') return [];
+  let best = null;
+  for (const m of modules) {
+    const dir = m.path === '.' || m.path === '' ? '' : `${m.path}/`;
+    if ((dir === '' || file.startsWith(dir)) && (!best || dir.length > best.dir.length)) best = { id: m.id, dir };
+  }
+  return best ? [best.id] : [];
+}
+
+/**
+ * Each node's band, from what the map shows of it:
+ *   external resource → External · container service → Infrastructure · a module of a compared project → Clients
+ *   a module that provides an endpoint, or that a container service builds → Entry points
+ *   one that only calls endpoints → Clients
+ *   one another module of this project references → Core · one with an entry point and nothing above → Entry points
+ *   anything else → Unplaced, so a guess is never drawn as a fact.
+ */
+export function bandOf(node, doc) {
+  if (node.kind === 'external') return 'external';
+  if (node.kind === 'service') return 'infra';
+  if (node.kind === 'client') return 'clients';
+  if ((doc.provides?.endpoints ?? []).some((e) => e.module === node.id)) return 'entry';
+  if ((doc.edges ?? []).some((e) => e.to === node.id && e.kind === 'builds')) return 'entry';
+  if ((doc.consumes?.endpoints ?? []).some((e) => e.module === node.id)) return 'clients';
+  if ((doc.edges ?? []).some((e) => e.to === node.id && e.from !== node.id && e.from.startsWith('mod:'))) return 'core';
+  if (node.entry) return 'entry';
+  return 'unplaced';
+}
+
+/**
+ * The nodes the view draws, each with its band, and the clients of a compared project as nodes of their own.
+ * @param compare  the server's `compare` ({ label, clients }) or null
+ */
+export function nodesOf(doc, compare = null) {
+  const own = (doc.nodes ?? []).map((n) => ({ ...n, band: bandOf(n, doc) }));
+  const clients = (compare?.clients ?? []).map((c) => ({
+    id: `cmp:${c.id}`, kind: 'client', name: c.name, tech: c.tech ?? [], from: compare.label, calls: c.calls, missing: c.missing, band: 'clients',
+  }));
+  return [...clients, ...own];
+}
+
+/** The edges between drawn nodes; a compared client gets one edge to each module of this project it calls. */
+export function edgesOf(doc, compare = null) {
+  const own = (doc.edges ?? []).map((e) => ({ ...e, solid: e.confidence !== 'inferred', line: lineOf(e) }));
+  const extra = [];
+  for (const c of compare?.clients ?? []) {
+    // The module each call lands on is the server's match (`to`), never a guess made here.
+    const to = new Map();
+    for (const call of c.calls) if (call.to) to.set(call.to, (to.get(call.to) ?? 0) + 1);
+    for (const [m, n] of to) extra.push({ from: `cmp:${c.id}`, to: m, kind: 'calls', confidence: 'evidence', solid: true, line: 'evidence', calls: n, missing: c.missing.length });
+  }
+  return [...extra, ...own];
+}
+
+export const edgeKey = (e) => `${e.from}>${e.to}>${e.kind}`;
+
+/**
+ * How a line is drawn: `evidence` (solid, a file proves it), `inferred` (dotted) or `model` (a line the model
+ * proposed: dashed with its own mark, never drawn as if a file showed it).
+ */
+export function lineOf(e) {
+  if (e?.source === 'model') return 'model';
+  return e?.confidence === 'inferred' ? 'inferred' : 'evidence';
+}
+
+/** An external resource every line of which is inferred is itself only inferred, and its card says so. */
+export function inferredOnly(node, edges) {
+  if (node.kind !== 'external') return false;
+  const into = edges.filter((e) => e.to === node.id || e.from === node.id);
+  return into.length > 0 && into.every((e) => lineOf(e) !== 'evidence');
+}
+
+/**
+ * The folders that hold two or more modules of one band: a group the view can fold into one card. A module at the
+ * project's root, or alone in its folder, is in no group. { groupId: { id, band, folder, members: [ids] } }
+ */
+export function groupsOf(nodes) {
+  const by = new Map();
+  for (const n of nodes) {
+    if (n.kind !== 'module' || typeof n.path !== 'string' || !n.path.includes('/')) continue;
+    const folder = n.path.slice(0, n.path.lastIndexOf('/'));
+    const id = `grp:${n.band}:${folder}`;
+    const g = by.get(id) ?? by.set(id, { id, band: n.band, folder, members: [] }).get(id);
+    g.members.push(n.id);
+  }
+  return Object.fromEntries([...by].filter(([, g]) => g.members.length > 1));
+}
+
+/**
+ * The nodes and edges with the folded groups folded: each folded group is one card in place of its members, and
+ * the members' lines are its lines, one per (from, to, kind), drawn solid when any of them is.
+ */
+export function foldView(nodes, edges, groups, folded) {
+  const into = new Map();
+  for (const g of Object.values(groups)) if (folded.has(g.id)) for (const m of g.members) into.set(m, g.id);
+  if (!into.size) return { nodes, edges };
+  const out = [];
+  const seen = new Set();
+  for (const n of nodes) {
+    const gid = into.get(n.id);
+    if (!gid) { out.push(n); continue; }
+    if (seen.has(gid)) continue;
+    seen.add(gid);
+    const g = groups[gid];
+    out.push({ id: gid, kind: 'group', band: g.band, name: `${g.folder}/`, folder: g.folder, members: g.members });
+  }
+  const em = new Map();
+  for (const e of edges) {
+    const from = into.get(e.from) ?? e.from;
+    const to = into.get(e.to) ?? e.to;
+    if (from === to) continue;
+    const k = `${from}>${to}>${e.kind}`;
+    const was = em.get(k);
+    if (!was) em.set(k, { ...e, from, to });
+    else if (lineOf(e) === 'evidence' && was.line !== 'evidence') em.set(k, { ...was, solid: true, line: 'evidence' });
+  }
+  return { nodes: out, edges: [...em.values()] };
+}
+
+/** The layout with the viewer's own placings over it: a card placed by hand stays where it was put. */
+export function placed(lay, pins) {
+  const pos = { ...lay.pos };
+  for (const [id, p] of Object.entries(pins ?? {})) if (pos[id]) pos[id] = { ...pos[id], x: p.x, y: p.y };
+  const right = Object.values(pos).reduce((m, p) => Math.max(m, p.x + p.w), lay.width);
+  const bottom = Object.values(pos).reduce((m, p) => Math.max(m, p.y + p.h), lay.height);
+  return { ...lay, pos, width: right, height: bottom };
+}
+
+/** Which lines a selection lights: the selected node's own, in and out. With nothing selected, none is lit. */
+export function litEdges(edges, selected) {
+  if (!selected) return new Set();
+  return new Set(edges.filter((e) => e.from === selected || e.to === selected).map(edgeKey));
+}
+
+/**
+ * The findings the list shows, proven first, then by title. Hidden by default: the scanner's own mark
+ * (`data.defaultHidden`, for rules too often wrong to show unasked); shown when `showHidden`. A compared client's
+ * calls this project does not provide are findings too, marked as coming from the comparison.
+ */
+export function findingsOf(doc, { showHidden = false, compare = null } = {}) {
+  const modules = (doc.nodes ?? []).filter((n) => n.kind === 'module');
+  const all = (doc.findings ?? []).map((f) => ({
+    id: f.id, rule: f.rule, title: f.title, proven: f.confidence === 'proven', hidden: Boolean(f.data?.defaultHidden),
+    hiddenReason: f.data?.hiddenReason ?? null, where: whereOf(f), modules: findingModules(f, modules), evidence: f.evidence ?? [], from: null,
+  }));
+  for (const c of compare?.clients ?? []) {
+    for (const m of c.missing) {
+      all.push({
+        id: `cmp:${c.id}:${m.method} ${m.path}`, rule: 'compare-missing', title: `${m.method} ${m.path} is called by ${c.name} and not provided here`,
+        proven: true, hidden: false, hiddenReason: null, where: m.evidence?.[0] ? `${m.evidence[0].file}:${m.evidence[0].line}` : '', modules: [`cmp:${c.id}`],
+        evidence: m.evidence ?? [], from: compare.label,
+      });
+    }
+  }
+  const shown = all.filter((f) => showHidden || !f.hidden);
+  shown.sort((a, b) => Number(b.proven) - Number(a.proven) || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0));
+  return { shown, hidden: all.filter((f) => f.hidden).length, proven: shown.filter((f) => f.proven).length, total: all.length };
+}
+
+function whereOf(f) {
+  const e = f.evidence?.[0];
+  return e ? `${e.file}:${e.line}` : '';
+}
+
+/** How many findings each drawn node carries, of those the list shows. */
+export function findingCounts(findings) {
+  const out = {};
+  for (const f of findings) for (const m of f.modules) out[m] = (out[m] ?? 0) + 1;
+  return out;
+}
+
+/** What a card says under its name. */
+export function cardSub(node, doc) {
+  if (node.kind === 'client') return `${node.from} · ${node.calls.length} ${node.calls.length === 1 ? 'call' : 'calls'} here`;
+  if (node.kind === 'service') return node.image ? `container · ${node.image}` : 'container';
+  const provided = (doc.provides?.endpoints ?? []).filter((e) => e.module === node.id).length;
+  const tech = (node.tech ?? []).slice(0, 2).map((t) => t.replace(/@.*$/, '')).join(' · ');
+  return [tech || node.stack, provided ? `${provided} ${provided === 1 ? 'endpoint' : 'endpoints'}` : null].filter(Boolean).join(' · ');
+}
+
+/** The summary pills: what the map holds, and how many findings the list shows. */
+export function summaryOf(doc, findings) {
+  const n = (k) => (doc.nodes ?? []).filter((x) => x.kind === k).length;
+  const eps = (doc.provides?.endpoints?.length ?? 0) + (doc.consumes?.endpoints?.length ?? 0);
+  return [
+    `${n('module')} ${n('module') === 1 ? 'module' : 'modules'}`,
+    `${n('external')} external`,
+    `${eps} ${eps === 1 ? 'endpoint' : 'endpoints'}`,
+    `${findings.shown.length} ${findings.shown.length === 1 ? 'finding' : 'findings'}`,
+  ];
+}
+
+/** The source strip: the file, the commit it was scanned at, and how far HEAD has moved since. */
+export function sourceOf(data) {
+  const commit = data.doc?.source?.commit ?? null;
+  const behind = data.behind?.count;
+  return {
+    file: data.file,
+    at: commit ? `scanned at ${commit.slice(0, 7)}` : 'scanned outside git',
+    behind: typeof behind === 'number' && behind > 0 ? `${behind} ${behind === 1 ? 'commit' : 'commits'} behind` : null,
+    behindNote: typeof behind === 'number' ? null : (data.behind?.reason ?? null),
+    rule: 'Nothing is run; files are only read.',
+  };
+}
+
+/** What the inspector shows for one node. */
+export function inspectOf(node, doc, edges, findings) {
+  const byId = new Map(nodesOf(doc).map((n) => [n.id, n]));
+  const nameOf = (id) => byId.get(id)?.name ?? byId.get(id)?.label ?? id.replace(/^(mod|svc|ext):/, '');
+  const line = (e, other) => ({
+    kind: e.kind, to: nameOf(other), host: byId.get(other)?.hosts?.[0] ?? null,
+    evidence: e.evidence?.[0] ? `${e.evidence[0].file}:${e.evidence[0].line}` : null, solid: e.solid, line: e.line ?? lineOf(e),
+  });
+  const out = edges.filter((e) => e.from === node.id).map((e) => line(e, e.to));
+  const into = edges.filter((e) => e.to === node.id).map((e) => line(e, e.from));
+  // Connections, by the kind of line: what the inspector's second tab lists.
+  const byKind = {};
+  for (const [dir, list] of [['out', out], ['in', into]]) for (const c of list) (byKind[c.kind] ??= { out: [], in: [] })[dir].push(c);
+  return {
+    title: node.name ?? node.label ?? node.id,
+    path: node.path ?? (node.kind === 'external' ? (node.hosts ?? []).join(', ') : null),
+    chips: (node.tech ?? []).map((t) => t.replace('@', ' ')),
+    // /crew-map's description: { text, cites }, each cite a file:line of this node's evidence (eval/lib/crew-map/narrative.mjs).
+    narrative: typeof node.narrative?.text === 'string' ? node.narrative.text : null,
+    narrativeCites: Array.isArray(node.narrative?.cites) ? node.narrative.cites.filter((c) => typeof c === 'string') : [],
+    narrativeNote: 'Not written yet: this map holds no description of the module, only what its files show.',
+    connectsTo: out,
+    connections: { out, in: into },
+    byKind: Object.entries(byKind).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+    // Every line the map cites for this node itself, as file:line: what the inspector lets the viewer copy.
+    evidence: (node.evidence ?? []).map((e) => `${e.file}:${e.line}`),
+    evidenceTotal: node.evidenceTotal ?? (node.evidence ?? []).length,
+    findings: findings.filter((f) => f.modules.includes(node.id)),
+  };
+}
+
+/** A finding as a task to paste into a session: what, where, and that the map is the source. */
+export function taskOf(f) {
+  return [
+    `${f.title}.`,
+    f.where ? `Evidence: ${f.where}${f.evidence?.[0]?.text ? ` (${f.evidence[0].text})` : ''}.` : null,
+    f.proven ? null : 'The crew map inferred this; check it before acting on it.',
+    f.from ? `Found by comparing this project's map with ${f.from}'s.` : `From the crew map (rule ${f.rule}).`,
+  ].filter(Boolean).join(' ');
+}
+
+/** What the view says when there is no map to draw. */
+export function emptyNote(data) {
+  if (!data) return 'Reading the map…';
+  if (data.measured === false) return data.missing ? `No map yet — ${data.reason}` : `Not read — ${data.reason}`;
+  return null;
+}
+
+export const CARD = { module: [200, 64], service: [200, 64], client: [200, 64], external: [104, 52] };
+const GAP_X = 24;
+const GAP_Y = 20;
+const LEFT = 140;      // the band's label sits in this column
+const PAD_Y = 18;
+const CHIP_ROW = 26;   // one row of endpoint chips under a card, when the Endpoints layer is on
+export const CHIPS_MAX = 4;
+
+/**
+ * Where everything sits: bands from top to bottom, each as tall as its rows of cards; cards left to right,
+ * wrapping at `width`. Empty bands are not drawn. A card with endpoint chips (`chips[id]`) is taller. With
+ * `rowKey`, a run of cards that share a key (an open folder group) starts a row of its own and the next card after
+ * it does too, so a frame drawn around the run holds those cards and no other.
+ * @returns { bands: [{ key, label, y, h }], pos: { id: { x, y, w, h } }, width, height }
+ */
+export function layoutOf(nodes, { width = 960, chips = {}, rowKey = null } = {}) {
+  const pos = {};
+  const bands = [];
+  let y = 0;
+  for (const [key, label] of BANDS) {
+    const members = nodes.filter((n) => n.band === key);
+    if (!members.length) continue;
+    let x = LEFT; let rowY = y + PAD_Y; let rowH = 0; let prev = null;
+    for (const n of members) {
+      const key = rowKey?.(n) ?? null;
+      if (x > LEFT && key !== prev && (key || prev)) { x = LEFT; rowY += rowH + GAP_Y; rowH = 0; }
+      prev = key;
+      const [w, h0] = CARD[n.kind] ?? CARD.module;
+      const extra = Math.ceil(Math.min(chips[n.id] ?? 0, CHIPS_MAX + 1) / 2) * CHIP_ROW;
+      const h = h0 + extra;
+      if (x > LEFT && x + w > width) { x = LEFT; rowY += rowH + GAP_Y; rowH = 0; }
+      pos[n.id] = { x, y: rowY, w, h };
+      x += w + GAP_X; rowH = Math.max(rowH, h);
+    }
+    const h = rowY + rowH + PAD_Y - y;
+    bands.push({ key, label, y, h });
+    y += h;
+  }
+  const right = Object.values(pos).reduce((m, p) => Math.max(m, p.x + p.w), LEFT);
+  return { bands, pos, width: Math.max(width, right + GAP_X), height: y };
+}
+
+/** A line between two cards: out of the bottom of the upper one into the top of the lower, or side to side. */
+export function pathOf(a, b) {
+  if (!a || !b) return null;
+  const down = b.y >= a.y + a.h;
+  const up = a.y >= b.y + b.h;
+  if (down || up) {
+    const [s, t] = down ? [a, b] : [b, a];
+    const x1 = s.x + s.w / 2; const y1 = s.y + s.h; const x2 = t.x + t.w / 2; const y2 = t.y;
+    const m = (y1 + y2) / 2;
+    return { d: `M${x1} ${y1} C${x1} ${m} ${x2} ${m} ${x2} ${y2}`, mid: [(x1 + x2) / 2, m] };
+  }
+  const [s, t] = a.x <= b.x ? [a, b] : [b, a];
+  const x1 = s.x + s.w; const y1 = s.y + s.h / 2; const x2 = t.x; const y2 = t.y + t.h / 2;
+  return { d: `M${x1} ${y1} L${x2} ${y2}`, mid: [(x1 + x2) / 2, (y1 + y2) / 2] };
+}
+
+/** The endpoint chips of a module, as the Endpoints layer lists them: what it provides, then what it calls. */
+export function chipsOf(node, doc) {
+  const p = (doc.provides?.endpoints ?? []).filter((e) => e.module === node.id).map((e) => `${e.method} ${e.path}`);
+  const c = (doc.consumes?.endpoints ?? []).filter((e) => e.module === node.id).map((e) => `→ ${e.method} ${e.path}`);
+  const all = [...p, ...c];
+  return all.length > CHIPS_MAX ? [...all.slice(0, CHIPS_MAX), `+${all.length - CHIPS_MAX} more`] : all;
+}