egregore-artifacts 0.5.0 → 0.9.5

package/lib/templates/subgraph.js

@@ -1,297 +1,376 @@
 // Handoff subgraph → inline static SVG
 //
-// Shows the graph-only context around a handoff — things the header doesn't
-// already say. Author/recipients/project are in the metadata row above this.
+// Renders the session's knowledge-graph neighborhood AS A GRAPH — typed
+// nodes with labeled edges — rather than as a flat list or zones. Gives
+// the recipient a visual orientation: where this sits, who/what it's
+// connected to, which quests it's part of, what it produced.
 //
-// Central spine is VERTICAL so the SVG fits comfortably in the ~720px
-// artifact column without scaling down and losing legibility:
+// Layered DAG layout (top-to-bottom):
 //
-//                [prior session]
-//                  by Oz
-//                    ↓ implements
-//                ┌──────────────┐
-//                │ THIS HANDOFF │
-//                │    Topic     │
-//                └──────────────┘
-//                    ↓ picked up
-//                [later session]
-//                  by Ali
+//   Row 0 (optional)  [prior session]
+//                           │ IMPLEMENTS / CONTINUES
+//   Row 1             [ THIS HANDOFF ]
+//                     ╱ BY   │ABOUT  ╲ ADVANCED
+//   Row 2   [author, recipients]  [project]   [quests ...]
+//                 │                              ▲
+//                 │ HAS_ACTIVITY    ╭─ PART_OF ──╯
+//                 ▼                 │
+//   Row 3   [artifacts ...]   [PRs ...]   [later sessions]
+//                              │ PRODUCED  ▲
+//                                          │ IMPLEMENTS (incoming)
 //
-//   PRODUCED
-//   [PR #603 · egregore]  [harvest · …]  [decision · …]
+//   Legend  ● Session  ● Person  ● Project  ● Quest  ● Artifact  ● PR
 //
-//   PART OF         (shown only when quests exist — rare)
-//   [quest · Launch Priorities]  [quest · Activity Wall]
+// Rows collapse when empty. If the session has no graph-only context
+// (subgraph is null or has only header-duplicating data), the whole
+// section is skipped.
 //
-// Any zone with no data is skipped entirely; if no zones have data, the
-// whole section is skipped (parser returns null upstream).
-//
-// Zero runtime JS. Colors emitted as var(--token) so dark-mode reaches them.
+// Zero runtime JS — pure SSR SVG. All colors via var(--token) so dark
+// mode reaches them.
 import React from 'react';
 import { fonts } from '../tokens.js';
 
 const h = React.createElement;
 
+// ── Text sizing heuristics ────────────────────────────────────────
 const CHAR_W_SANS_12 = 7.0;
 const CHAR_W_SANS_13 = 7.6;
-const CHAR_W_MONO_10 = 6.0;
 const CHAR_W_MONO_9  = 5.4;
 
-const PILL_H = 34;
-const PILL_PAD_X = 26;
-const PILL_MIN_W = 160;
-const PILL_MAX_W = 360;
-
-const HANDOFF_H = 56;
-const HANDOFF_MIN_W = 220;
-const HANDOFF_MAX_W = 420;
-
-const VERT_EDGE = 42;       // vertical space for an arrow + its label
-const SIDE_PAD = 24;
-const ZONE_GAP = 26;
-const CAPTION_H = 16;
-const CHIP_H = 26;
-const SUB_LINE_H = 14;
-
-const LABEL_TRUNCATE = 50;
+// ── Node geometry ──────────────────────────────────────────────────
+const PILL_H = 32;
+const PILL_PAD_X = 22;
+const PILL_MIN_W = 110;
+const PILL_MAX_W = 260;
+const SESSION_H = 56;
+const SESSION_MIN_W = 220;
+const SESSION_MAX_W = 360;
+
+// ── Row y-coordinates ──────────────────────────────────────────────
+const ROW_H = 90;
+const TOP_PAD = 30;
+const SIDE_PAD = 18;
+const LEGEND_H = 34;
+
+// ── Truncation caps ────────────────────────────────────────────────
+const TRUNC_SESSION = 60;
+const TRUNC_PILL    = 26;
+const TRUNC_ARTIFACT = 28;
+
+// ── Count caps (to keep the SVG within the container width) ────────
+const MAX_AUTHORS = 2;
+const MAX_RECIPIENTS = 2;
+const MAX_QUESTS = 3;
+const MAX_ARTIFACTS = 4;
+const MAX_PRS = 3;
+const MAX_LATER = 2;
+
+// ── Colors (CSS vars) ──────────────────────────────────────────────
+const STYLE = {
+  session:  { fill: 'var(--terracotta-chip)',    stroke: 'var(--terracotta)',       text: 'var(--black)' },
+  person:   { fill: 'var(--blue-chip)',          stroke: 'var(--blue-muted)',       text: 'var(--blue-muted)' },
+  project:  { fill: 'var(--subtle-fill)',        stroke: 'var(--border)',           text: 'var(--dark)' },
+  quest:    { fill: 'var(--quest-fill)',         stroke: 'var(--green-p1)',         text: 'var(--green-p1)' },
+  artifact: { fill: 'var(--artifact-fill)',      stroke: 'var(--artifact-stroke)',  text: 'var(--artifact-stroke)' },
+  pr:       { fill: 'var(--pr-fill)',            stroke: 'var(--border)',           text: 'var(--dark)' },
+};
 
 export function renderSubgraph({ subgraph, handoffTopic }) {
   if (!subgraph) return null;
 
   const {
-    continues = [],
-    implementsHandoff = [],
-    implementedBy = [],
-    quests = [],
-    artifacts = [],
-    prs = [],
+    authors = [], recipients = [], project = null,
+    continues = [], implementsHandoff = [], implementedBy = [],
+    quests = [], artifacts = [], artifactQuestLinks = [], prs = [],
   } = subgraph;
 
+  // Prior = the most-specific upstream node (implements > continues, pick first).
   const priorNode = implementsHandoff[0] || continues[0] || null;
-  const priorLabel = implementsHandoff[0] ? 'implements' : (continues[0] ? 'continues' : null);
-  const priorMore = (implementsHandoff.length + continues.length) - (priorNode ? 1 : 0);
-
-  const laterNode = implementedBy[0] || null;
-  const laterMore = implementedBy.length - (laterNode ? 1 : 0);
-
-  const shownQuests = quests.slice(0, 4);
-  const questOverflow = quests.length - shownQuests.length;
-
-  const outputs = [
-    ...prs.slice(0, 4).map(p => ({
-      label: `PR #${p.number || p.id}${p.repo ? ` · ${p.repo}` : ''}`,
-      tone: 'pr',
-    })),
-    ...artifacts.slice(0, 4).map(a => ({
-      label: `${a.type || 'artifact'} · ${truncate(a.title || a.id || a.path || 'artifact', 32)}`,
-      tone: 'artifact',
-    })),
-  ].slice(0, 6);
-  const outputsOverflow = (prs.length + artifacts.length) - outputs.length;
-
-  const hasQuests = shownQuests.length > 0;
-  const hasLineage = Boolean(priorNode || laterNode);
-  const hasOutputs = outputs.length > 0;
-
-  if (!hasQuests && !hasLineage && !hasOutputs) return null;
-
-  // ── Widths ──────────────────────────────────────────────────────
-  const handoffText = truncate(handoffTopic || 'this handoff', 60);
-  const handoffW = clamp(
-    textW(handoffText, CHAR_W_SANS_13) + PILL_PAD_X + 16,
-    HANDOFF_MIN_W, HANDOFF_MAX_W,
-  );
-
-  const priorText = priorNode ? truncate(priorNode.topic || priorNode.id || '', LABEL_TRUNCATE) : '';
-  const priorW = priorNode ? pillWidth(priorText) : 0;
+  const priorRel = implementsHandoff[0] ? 'IMPLEMENTS' : (continues[0] ? 'CONTINUES' : null);
+
+  const authorList = authors.slice(0, MAX_AUTHORS);
+  const recipientList = recipients.slice(0, MAX_RECIPIENTS);
+  const questList = quests.slice(0, MAX_QUESTS);
+  const artifactList = artifacts.slice(0, MAX_ARTIFACTS);
+  const prList = prs.slice(0, MAX_PRS);
+  const laterList = implementedBy.slice(0, MAX_LATER);
+  const overflowQuests = quests.length - questList.length;
+  const overflowArtifacts = artifacts.length - artifactList.length;
+  const overflowPrs = prs.length - prList.length;
+
+  // Gate: we render the section if there's any *graph-only* context —
+  // things not already in the header. Author/recipients/project alone
+  // aren't enough (they duplicate the metadata row).
+  const hasGraphOnlyContext =
+    priorNode || laterList.length || questList.length ||
+    artifactList.length || prList.length;
+  if (!hasGraphOnlyContext) return null;
+
+  // ── Assign nodes to layout slots ──────────────────────────────────
+  // Each node = { id, kind, label, x, y, w }. We compute widths first
+  // from label text, then pack rows, then assign y per row.
+
+  const mkNode = (id, kind, label, sub = null) => ({
+    id, kind, label, sub, w: pillWidth(label, kind === 'session'),
+  });
+
+  const nodeSession = mkNode('session', 'session', truncate(handoffTopic || 'this handoff', TRUNC_SESSION));
+
+  const r1Left = authorList.map((a, i) => mkNode(`author-${i}`, 'person', truncate(a.name || a.github || 'author', TRUNC_PILL)))
+    .concat(recipientList.map((r, i) => mkNode(`recip-${i}`, 'person', truncate(r.name || r.github || 'recipient', TRUNC_PILL))));
+  const r1Center = project ? [mkNode('project', 'project', truncate(project, TRUNC_PILL))] : [];
+  const r1Right = questList.map((q, i) => mkNode(`quest-${q.id || i}`, 'quest', truncate(q.title || q.id || 'quest', TRUNC_PILL)));
+
+  const r2Left = artifactList.map((a, i) => mkNode(
+    `art-${a.id || i}`, 'artifact',
+    truncate(a.title || a.id || 'artifact', TRUNC_ARTIFACT),
+    a.type || null,
+  ));
+  const r2Right = prList.map((p, i) => mkNode(
+    `pr-${p.id || p.number || i}`, 'pr',
+    `PR #${p.number || p.id}${p.repo ? ' · ' + p.repo : ''}`,
+  )).concat(laterList.map((l, i) => mkNode(
+    `later-${i}`, 'session',
+    truncate(l.topic || l.id || 'session', TRUNC_PILL),
+  )));
+
+  // Row 1 (identity): Persons on the left, Project in the center.
+  // Row 2 (quests): on its own row so longer quest titles don't push widths.
+  // Row 3 (outputs): Artifacts on the left, PRs + later sessions on the right.
+  const hasRow0 = Boolean(priorNode);
+  const hasRow1 = r1Left.length || r1Center.length;    // persons + project only
+  const hasQuestsRow = r1Right.length > 0;             // quests
+  const hasRow2 = r2Left.length || r2Right.length;
+
+  // ── Compute canvas width from widest row ─────────────────────────
+  const GAP = 14;
+  const widthOfRow = (items, extra = 0) =>
+    items.reduce((a, n) => a + n.w, 0) + Math.max(0, items.length - 1) * GAP + extra;
+
+  const r1W = widthOfRow(r1Left, r1Center.length ? 32 : 0) + widthOfRow(r1Center);
+  const questsW = widthOfRow(r1Right);
+  const r2W = widthOfRow(r2Left, r2Right.length ? 32 : 0) + widthOfRow(r2Right);
+  const priorW = priorNode ? pillWidth(truncate(priorNode.topic || priorNode.id || '', TRUNC_PILL)) : 0;
+  const sessionW = nodeSession.w;
+
+  const contentW = Math.max(r1W, questsW, r2W, priorW, sessionW, 460);
+  const WIDTH = contentW + SIDE_PAD * 2;
+  const CX = WIDTH / 2;
+
+  // ── Assign y coordinates ─────────────────────────────────────────
+  let cy = TOP_PAD;
+  let yPrior = null, ySession = null, yRow1 = null, yQuests = null, yRow2 = null;
+
+  if (hasRow0) {
+    yPrior = cy + PILL_H / 2;
+    cy += ROW_H;
+  }
+  ySession = cy + SESSION_H / 2;
+  cy += SESSION_H + 34;
 
-  const laterText = laterNode ? truncate(laterNode.topic || laterNode.id || '', LABEL_TRUNCATE) : '';
-  const laterW = laterNode ? pillWidth(laterText) : 0;
+  if (hasRow1) {
+    yRow1 = cy + PILL_H / 2;
+    cy += ROW_H - 6;
+  }
+  if (hasQuestsRow) {
+    yQuests = cy + PILL_H / 2;
+    cy += ROW_H - 6;
+  }
+  if (hasRow2) {
+    yRow2 = cy + PILL_H / 2;
+    cy += ROW_H - 6;
+  }
+  const HEIGHT = cy + LEGEND_H + 8;
+
+  // ── Lay out nodes horizontally per row ───────────────────────────
+  let priorPlaced = null;
+  if (hasRow0) {
+    priorPlaced = mkNode('prior', 'session',
+      truncate(priorNode.topic || priorNode.id || 'prior session', TRUNC_PILL),
+      priorNode.author ? `by ${priorNode.author}` : null);
+    priorPlaced.x = CX - priorPlaced.w / 2;
+    priorPlaced.y = yPrior - PILL_H / 2;
+    priorPlaced.h = PILL_H;
+  }
 
-  // Quests and outputs laid out in horizontal rows with wrap
-  const questRows = packRows(
-    shownQuests.map(q => ({
-      label: `quest · ${truncate(q.title || q.id || 'quest', 32)}`,
-      tone: 'quest',
-      w: chipWidth(`quest · ${truncate(q.title || q.id || 'quest', 32)}`),
-    })),
-    640,
-  );
-  const outputRows = packRows(
-    outputs.map(o => ({ ...o, w: chipWidth(o.label) })),
-    640,
-  );
+  nodeSession.x = CX - nodeSession.w / 2;
+  nodeSession.y = ySession - SESSION_H / 2;
+  nodeSession.h = SESSION_H;
+
+  // Row 1 (persons + project): persons left, project centered-right.
+  if (hasRow1) layoutRow(r1Left, r1Center, [], yRow1, WIDTH);
+  // Quests row: center the whole group.
+  if (hasQuestsRow) {
+    const total = questsW;
+    const startX = Math.max(SIDE_PAD, (WIDTH - total) / 2);
+    placeHorizontally(r1Right, startX, yQuests - PILL_H / 2, GAP);
+  }
+  // Outputs row: artifacts left, PRs + later right.
+  if (hasRow2) layoutRow(r2Left, [], r2Right, yRow2, WIDTH);
 
-  // Content width = max of everything
-  const lineageW = Math.max(priorW, handoffW, laterW);
-  const questsMaxRowW = questRows.reduce((m, r) => Math.max(m, rowWidth(r)), 0)
-    + (questOverflow > 0 ? 80 : 0);
-  const outputsMaxRowW = outputRows.reduce((m, r) => Math.max(m, rowWidth(r)), 0)
-    + (outputsOverflow > 0 ? 80 : 0);
+  // ── Collect SVG children ─────────────────────────────────────────
+  const children = [];
 
-  const contentW = Math.max(lineageW, questsMaxRowW, outputsMaxRowW, 420);
-  const VIEW_W = contentW + SIDE_PAD * 2;
-  const CX = VIEW_W / 2;
+  // Arrow marker
+  children.push(h('defs', { key: 'defs' },
+    h('marker', {
+      id: 'sg-arrow',
+      viewBox: '0 0 10 10',
+      refX: 9, refY: 5,
+      markerWidth: 6, markerHeight: 6,
+      orient: 'auto-start-reverse',
+    },
+      h('path', { d: 'M0,0 L10,5 L0,10 z', fill: 'var(--border)' })
+    ),
+  ));
 
-  // ── Vertical layout ─────────────────────────────────────────────
-  const children = [];
-  let cy = 14;
-
-  // Zone: Lineage (vertical spine)
-  if (hasLineage) {
-    if (priorNode) {
-      const y = cy;
-      const x = CX - priorW / 2;
-      children.push(pill({
-        key: 'prior', x, y, width: priorW,
-        label: priorText, tone: 'neutral',
-      }));
-      if (priorNode.author) {
-        children.push(subLabel({
-          key: 'prior-sub', x: CX, y: y + PILL_H + 12,
-          text: `by ${priorNode.author}`,
-        }));
-      }
-      cy += PILL_H + SUB_LINE_H;
-
-      // Edge from prior to handoff (arrow pointing down, out of prior toward this)
-      const e1 = cy + 2;
-      const e2 = cy + VERT_EDGE - 6;
-      children.push(h('line', {
-        key: 'prior-edge',
-        x1: CX, y1: e1, x2: CX, y2: e2,
-        stroke: 'var(--border)', strokeWidth: 1.5,
-        markerEnd: 'url(#sg-arrow)',
-      }));
-      const lbl = `${priorLabel}${priorMore > 0 ? ` · +${priorMore}` : ''}`;
-      children.push(edgeLabel({
-        key: 'prior-edge-lbl',
-        x: CX + 10, y: (e1 + e2) / 2 + 3,
-        text: lbl, anchor: 'start',
-      }));
-      cy += VERT_EDGE;
-    }
+  // ── Edges (drawn first so they sit behind nodes) ─────────────────
 
-    // THIS HANDOFF
-    const hx = CX - handoffW / 2;
-    const hy = cy;
-    children.push(h('rect', {
-      key: 'main-bg',
-      x: hx, y: hy, width: handoffW, height: HANDOFF_H,
-      rx: 10, ry: 10,
-      fill: 'var(--terracotta-chip)',
-      stroke: 'var(--terracotta)', strokeWidth: 1.5,
+  // Row 0 → session (IMPLEMENTS or CONTINUES)
+  if (hasRow0 && priorPlaced) {
+    children.push(edge({
+      key: 'e-prior',
+      x1: CX, y1: priorPlaced.y + PILL_H,
+      x2: CX, y2: nodeSession.y,
+      label: priorRel,
     }));
-    children.push(h('text', {
-      key: 'main-caption',
-      x: CX, y: hy + 17,
-      textAnchor: 'middle',
-      fontFamily: fonts.mono, fontSize: 9,
-      fill: 'var(--terracotta)',
-      letterSpacing: '0.08em',
-    }, 'THIS HANDOFF'));
-    children.push(h('text', {
-      key: 'main-title',
-      x: CX, y: hy + 39,
-      textAnchor: 'middle',
-      fontFamily: fonts.sans, fontSize: 13, fontWeight: 500,
-      fill: 'var(--black)',
-    }, handoffText));
-    cy += HANDOFF_H;
-
-    if (laterNode) {
-      const e1 = cy + 6;
-      const e2 = cy + VERT_EDGE - 2;
-      children.push(h('line', {
-        key: 'later-edge',
-        x1: CX, y1: e1, x2: CX, y2: e2,
-        stroke: 'var(--border)', strokeWidth: 1.5,
-        markerEnd: 'url(#sg-arrow)',
+  }
+
+  // Session → Row 1 nodes
+  if (hasRow1) {
+    r1Left.forEach((n, i) => {
+      const rel = n.id.startsWith('author-') ? 'BY' : 'HANDED_TO';
+      children.push(edge({
+        key: `e-s-${n.id}`,
+        x1: nodeSession.x + sessionW * (0.35 - 0.1 * Math.min(i, 2)),
+        y1: nodeSession.y + SESSION_H,
+        x2: n.x + n.w / 2,
+        y2: n.y,
+        label: rel,
+      }));
+    });
+    r1Center.forEach((n) => {
+      children.push(edge({
+        key: `e-s-${n.id}`,
+        x1: CX, y1: nodeSession.y + SESSION_H,
+        x2: n.x + n.w / 2, y2: n.y,
+        label: 'ABOUT',
       }));
-      const lbl = `picked up${laterMore > 0 ? ` · +${laterMore}` : ''}`;
-      children.push(edgeLabel({
-        key: 'later-edge-lbl',
-        x: CX + 10, y: (e1 + e2) / 2 + 3,
-        text: lbl, anchor: 'start',
+    });
+  }
+  if (hasQuestsRow) {
+    // Quests live on their own row (below persons+project), so these edges
+    // need to curve around the Row 1 nodes rather than crossing them.
+    r1Right.forEach((n, i) => {
+      const sx = nodeSession.x + sessionW * (0.4 + 0.1 * i);
+      children.push(edge({
+        key: `e-s-${n.id}`,
+        x1: sx,
+        y1: nodeSession.y + SESSION_H,
+        x2: n.x + n.w / 2,
+        y2: n.y,
+        label: i === 0 ? 'ADVANCED' : null,
+        curved: true,
       }));
-      cy += VERT_EDGE;
+    });
+  }
 
-      const y = cy;
-      const x = CX - laterW / 2;
-      children.push(pill({
-        key: 'later', x, y, width: laterW,
-        label: laterText, tone: 'neutral',
+  // Session → Row 2 (artifacts and PRs), Later → Session
+  if (hasRow2) {
+    r2Left.forEach((n, i) => {
+      children.push(edge({
+        key: `e-s-${n.id}`,
+        x1: nodeSession.x + sessionW * 0.3,
+        y1: nodeSession.y + SESSION_H,
+        x2: n.x + n.w / 2, y2: n.y,
+        label: i === 0 ? 'HAS_ACTIVITY' : null,
+        curved: true,
       }));
-      if (laterNode.author) {
-        children.push(subLabel({
-          key: 'later-sub', x: CX, y: y + PILL_H + 12,
-          text: `by ${laterNode.author}`,
+    });
+    r2Right.forEach((n, i) => {
+      if (n.id.startsWith('later-')) {
+        // incoming IMPLEMENTS
+        children.push(edge({
+          key: `e-${n.id}-s`,
+          x1: n.x + n.w / 2, y1: n.y,
+          x2: nodeSession.x + sessionW * 0.7, y2: nodeSession.y + SESSION_H,
+          label: i === 0 ? 'IMPLEMENTS' : null,
+          curved: true,
+        }));
+      } else {
+        children.push(edge({
+          key: `e-s-${n.id}`,
+          x1: nodeSession.x + sessionW * 0.7,
+          y1: nodeSession.y + SESSION_H,
+          x2: n.x + n.w / 2, y2: n.y,
+          label: n.id.startsWith('pr-') ? (i === 0 ? 'PRODUCED' : null) : null,
+          curved: true,
         }));
       }
-      cy += PILL_H + SUB_LINE_H;
-    }
+    });
+  }
 
-    cy += ZONE_GAP;
+  // 2-hop: artifact → quest (PART_OF). Curved lines routed up from Row 2
+  // artifacts to their Row 1 quests.
+  if (hasRow1 && hasRow2 && artifactQuestLinks.length > 0) {
+    const questNodeById = new Map(r1Right.map(n => [n.id.replace(/^quest-/, ''), n]));
+    const artNodeById = new Map(r2Left.map(n => [n.id.replace(/^art-/, ''), n]));
+    let edgeIdx = 0;
+    for (const link of artifactQuestLinks) {
+      const artNode = artNodeById.get(link.artifactId);
+      const questNode = questNodeById.get(link.questId);
+      if (!artNode || !questNode) continue;
+      children.push(edge({
+        key: `e-a-q-${edgeIdx++}`,
+        x1: artNode.x + artNode.w / 2, y1: artNode.y,
+        x2: questNode.x + questNode.w / 2, y2: questNode.y + PILL_H,
+        label: edgeIdx === 1 ? 'PART_OF' : null,
+        curved: true,
+        dashed: true,
+      }));
+    }
   }
 
-  // Zone: PRODUCED (before quests — outputs are the everyday signal)
-  if (hasOutputs) {
-    children.push(caption({ key: 'out-cap', x: SIDE_PAD, y: cy + 10, text: 'PRODUCED' }));
-    cy += CAPTION_H;
-    const rows = outputRows;
-    rows.forEach((row, rIdx) => {
-      const rowW = rowWidth(row);
-      let ox = SIDE_PAD + Math.max(0, (contentW - rowW) / 2);
-      if (ox < SIDE_PAD) ox = SIDE_PAD;
-      row.forEach((c, i) => {
-        children.push(chip({
-          key: `o-${rIdx}-${i}`, x: ox, y: cy + CHIP_H,
-          width: c.w, label: c.label, tone: c.tone,
-        }));
-        ox += c.w + 8;
-      });
-      if (rIdx === rows.length - 1 && outputsOverflow > 0) {
-        children.push(h('text', {
-          key: 'o-more',
-          x: ox + 6, y: cy + CHIP_H - 6,
-          fontFamily: fonts.mono, fontSize: 10,
-          fill: 'var(--muted)',
-        }, `+${outputsOverflow} more`));
-      }
-      cy += CHIP_H + 8;
-    });
-    cy += ZONE_GAP;
+  // ── Nodes ────────────────────────────────────────────────────────
+  if (hasRow0 && priorPlaced) children.push(renderNode({ ...priorPlaced, key: 'n-prior' }));
+  children.push(renderSessionNode({ ...nodeSession, key: 'n-session' }));
+  if (hasRow1) [...r1Left, ...r1Center].forEach((n) => children.push(renderNode({ ...n, key: `n-${n.id}` })));
+  if (hasQuestsRow) r1Right.forEach((n) => children.push(renderNode({ ...n, key: `n-${n.id}` })));
+  if (hasRow2) [...r2Left, ...r2Right].forEach((n) => children.push(renderNode({ ...n, key: `n-${n.id}` })));
+
+  // ── Overflow indicators ──────────────────────────────────────────
+  if (overflowQuests > 0 && r1Right.length > 0) {
+    const last = r1Right[r1Right.length - 1];
+    children.push(overflowLabel({ key: 'of-q', x: last.x + last.w + 10, y: last.y + PILL_H / 2 + 3, n: overflowQuests }));
+  }
+  if (overflowArtifacts > 0 && r2Left.length > 0) {
+    const last = r2Left[r2Left.length - 1];
+    children.push(overflowLabel({ key: 'of-a', x: last.x + last.w / 2, y: last.y + PILL_H + 24, n: overflowArtifacts, anchor: 'middle' }));
+  }
+  if (overflowPrs > 0 && r2Right.length > 0) {
+    const lastPr = r2Right.filter(n => n.id.startsWith('pr-')).pop();
+    if (lastPr) {
+      children.push(overflowLabel({ key: 'of-p', x: lastPr.x + lastPr.w / 2, y: lastPr.y + PILL_H + 24, n: overflowPrs, anchor: 'middle' }));
+    }
   }
 
-  // Zone: PART OF (quests) — last; rare, de-emphasized
-  if (hasQuests) {
-    children.push(caption({ key: 'q-cap', x: SIDE_PAD, y: cy + 10, text: 'PART OF' }));
-    cy += CAPTION_H;
-    const rows = questRows;
-    rows.forEach((row, rIdx) => {
-      const rowW = rowWidth(row);
-      let ox = SIDE_PAD + Math.max(0, (contentW - rowW) / 2);
-      if (ox < SIDE_PAD) ox = SIDE_PAD;
-      row.forEach((c, i) => {
-        children.push(chip({
-          key: `q-${rIdx}-${i}`, x: ox, y: cy + CHIP_H,
-          width: c.w, label: c.label, tone: c.tone,
-        }));
-        ox += c.w + 8;
-      });
-      if (rIdx === rows.length - 1 && questOverflow > 0) {
-        children.push(h('text', {
-          key: 'q-more',
-          x: ox + 6, y: cy + CHIP_H - 6,
+  // ── Legend ───────────────────────────────────────────────────────
+  const legendTypes = ['session', 'person', 'project', 'quest', 'artifact', 'pr'];
+  const legendLabels = { session: 'Session', person: 'Person', project: 'Project', quest: 'Quest', artifact: 'Artifact', pr: 'PR' };
+  children.push(h('g', { key: 'legend', transform: `translate(${SIDE_PAD}, ${HEIGHT - LEGEND_H + 4})` },
+    ...legendTypes.map((t, i) => {
+      const x = i * 88;
+      return h('g', { key: `lg-${t}` },
+        h('circle', { cx: x + 6, cy: 10, r: 5, fill: STYLE[t].stroke, fillOpacity: 0.9 }),
+        h('text', {
+          x: x + 17, y: 14,
           fontFamily: fonts.mono, fontSize: 10,
           fill: 'var(--muted)',
-        }, `+${questOverflow} more`));
-      }
-      cy += CHIP_H + 8;
-    });
-  }
-
-  const VIEW_H = cy + 10;
+          letterSpacing: '0.03em',
+        }, legendLabels[t]),
+      );
+    }),
+  ));
 
   return h('div', {
     style: {
@@ -302,151 +381,172 @@ export function renderSubgraph({ subgraph, handoffTopic }) {
   },
     h('div', {
       style: {
-        fontFamily: fonts.mono,
-        fontSize: '11px',
-        textTransform: 'uppercase',
-        letterSpacing: '0.08em',
+        fontFamily: fonts.mono, fontSize: '11px',
+        textTransform: 'uppercase', letterSpacing: '0.08em',
         color: 'var(--muted)',
         marginBottom: '0.75rem',
         paddingLeft: '0.25rem',
       },
     }, 'Subgraph'),
     h('svg', {
-      viewBox: `0 0 ${VIEW_W} ${VIEW_H}`,
+      viewBox: `0 0 ${WIDTH} ${HEIGHT}`,
       width: '100%',
       height: 'auto',
       preserveAspectRatio: 'xMidYMid meet',
-      style: { display: 'block', maxHeight: '520px' },
+      style: { display: 'block', maxHeight: '640px' },
       role: 'img',
       'aria-label': 'Handoff knowledge-graph neighborhood',
-    },
-      h('defs', null,
-        h('marker', {
-          id: 'sg-arrow',
-          viewBox: '0 0 10 10',
-          refX: 9, refY: 5,
-          markerWidth: 7, markerHeight: 7,
-          orient: 'auto-start-reverse',
-        },
-          h('path', { d: 'M0,0 L10,5 L0,10 z', fill: 'var(--border)' })
-        ),
-      ),
-      ...children,
-    ),
+    }, ...children),
   );
 }
 
-// ── helpers ────────────────────────────────────────────────────────
+// ── layout helpers ──────────────────────────────────────────────────
+
+function layoutRow(leftNodes, centerNodes, rightNodes, yCenter, width) {
+  const GAP = 14;
+  const leftW = rowSpan(leftNodes, GAP);
+  const centerW = rowSpan(centerNodes, GAP);
+  const rightW = rowSpan(rightNodes, GAP);
+  const total = leftW + centerW + rightW;
+
+  // If three zones fit comfortably, space them; otherwise compress.
+  const available = width - SIDE_PAD * 2;
+  const slack = Math.max(0, available - total);
+  const padBetween = centerNodes.length > 0 ? slack / 2 : slack;
+
+  let cursor = SIDE_PAD;
+  placeHorizontally(leftNodes, cursor, yCenter - PILL_H / 2, GAP);
+  cursor = SIDE_PAD + leftW + (leftNodes.length ? padBetween : 0);
+  if (centerNodes.length) {
+    // Center the center zone relative to the canvas
+    const centerStart = (width - centerW) / 2;
+    placeHorizontally(centerNodes, centerStart, yCenter - PILL_H / 2, GAP);
+    cursor = centerStart + centerW + padBetween;
+  }
+  // Right zone flush to right
+  const rightStart = width - SIDE_PAD - rightW;
+  placeHorizontally(rightNodes, rightStart, yCenter - PILL_H / 2, GAP);
+}
 
-function pillWidth(label) {
-  return clamp(textW(label, CHAR_W_SANS_12) + PILL_PAD_X, PILL_MIN_W, PILL_MAX_W);
+function rowSpan(nodes, gap) {
+  if (nodes.length === 0) return 0;
+  return nodes.reduce((a, n) => a + n.w, 0) + (nodes.length - 1) * gap;
 }
 
-function chipWidth(label) {
-  return Math.max(96, textW(label, CHAR_W_MONO_10) + 20);
+function placeHorizontally(nodes, startX, y, gap) {
+  let x = startX;
+  for (const n of nodes) {
+    n.x = x;
+    n.y = y;
+    n.h = PILL_H;
+    x += n.w + gap;
+  }
 }
 
-function textW(label, perChar) {
-  return Math.ceil((label || '').length * perChar);
+function pillWidth(label, isSession) {
+  const minW = isSession ? SESSION_MIN_W : PILL_MIN_W;
+  const maxW = isSession ? SESSION_MAX_W : PILL_MAX_W;
+  const charW = isSession ? CHAR_W_SANS_13 : CHAR_W_SANS_12;
+  const raw = Math.ceil((label || '').length * charW) + PILL_PAD_X;
+  return clamp(raw, minW, maxW);
 }
 
+function clamp(n, lo, hi) { return Math.max(lo, Math.min(hi, n)); }
+
 function truncate(s, max) {
   if (!s) return '';
   if (s.length <= max) return s;
   return s.slice(0, max - 1) + '…';
 }
 
-function clamp(n, lo, hi) { return Math.max(lo, Math.min(hi, n)); }
-
-// Pack chips into rows that fit within maxW.
-function packRows(items, maxW) {
-  const rows = [[]];
-  let cur = 0;
-  for (const it of items) {
-    if (cur > 0 && cur + it.w + 8 > maxW) {
-      rows.push([it]);
-      cur = it.w;
-    } else {
-      rows[rows.length - 1].push(it);
-      cur += (cur > 0 ? 8 : 0) + it.w;
-    }
-  }
-  return rows;
-}
-
-function rowWidth(row) {
-  if (row.length === 0) return 0;
-  return row.reduce((a, c) => a + c.w, 0) + (row.length - 1) * 8;
-}
-
-function pill({ key, x, y, width, label, tone }) {
-  const styles = {
-    neutral: { fill: 'var(--subtle-fill)', stroke: 'var(--border)', text: 'var(--dark)' },
-    person:  { fill: 'var(--blue-chip)',   stroke: 'var(--blue-muted)', text: 'var(--blue-muted)' },
-  }[tone] || { fill: 'var(--subtle-fill)', stroke: 'var(--border)', text: 'var(--dark)' };
+// ── rendering helpers ──────────────────────────────────────────────
 
+function renderSessionNode({ x, y, w, label, key }) {
+  const s = STYLE.session;
   return h('g', { key },
     h('rect', {
-      x, y, width, height: PILL_H,
-      rx: PILL_H / 2, ry: PILL_H / 2,
-      fill: styles.fill, stroke: styles.stroke, strokeWidth: 1,
+      x, y, width: w, height: SESSION_H,
+      rx: 10, ry: 10,
+      fill: s.fill, stroke: s.stroke, strokeWidth: 1.5,
     }),
     h('text', {
-      x: x + width / 2,
-      y: y + PILL_H / 2 + 4,
+      x: x + w / 2, y: y + 18,
+      textAnchor: 'middle',
+      fontFamily: fonts.mono, fontSize: 9,
+      fill: 'var(--terracotta)',
+      letterSpacing: '0.08em',
+    }, 'THIS HANDOFF'),
+    h('text', {
+      x: x + w / 2, y: y + 40,
       textAnchor: 'middle',
       fontFamily: fonts.sans, fontSize: 13, fontWeight: 500,
-      fill: styles.text,
+      fill: s.text,
     }, label),
   );
 }
 
-function chip({ key, x, y, width, label, tone }) {
-  const styles = {
-    quest:    { fill: 'var(--terracotta-chip)', text: 'var(--terracotta)' },
-    artifact: { fill: 'var(--blue-chip)',       text: 'var(--blue-muted)' },
-    pr:       { fill: 'var(--subtle-fill)',     text: 'var(--dark)' },
-  }[tone] || { fill: 'var(--subtle-fill)', text: 'var(--muted)' };
-
-  return h('g', { key },
+function renderNode({ x, y, w, label, sub, kind, key }) {
+  const s = STYLE[kind] || STYLE.project;
+  const children = [
     h('rect', {
-      x, y: y - CHIP_H + 4, width, height: CHIP_H,
-      rx: 5, ry: 5,
-      fill: styles.fill,
+      key: 'bg',
+      x, y, width: w, height: PILL_H,
+      rx: PILL_H / 2, ry: PILL_H / 2,
+      fill: s.fill, stroke: s.stroke, strokeWidth: 1,
     }),
     h('text', {
-      x: x + 10, y: y - CHIP_H / 2 + 8,
-      fontFamily: fonts.mono, fontSize: 11, fontWeight: 500,
-      fill: styles.text,
+      key: 'lbl',
+      x: x + w / 2, y: y + PILL_H / 2 + 4,
+      textAnchor: 'middle',
+      fontFamily: fonts.sans, fontSize: 12, fontWeight: 500,
+      fill: s.text,
     }, label),
-  );
-}
-
-function caption({ key, x, y, text }) {
-  return h('text', {
-    key, x, y,
-    fontFamily: fonts.mono, fontSize: 10,
-    fill: 'var(--muted)',
-    letterSpacing: '0.1em',
-  }, text);
+  ];
+  if (sub) {
+    children.push(h('text', {
+      key: 'sub',
+      x: x + w / 2, y: y + PILL_H + 11,
+      textAnchor: 'middle',
+      fontFamily: fonts.mono, fontSize: 9,
+      fill: 'var(--muted)',
+      fontStyle: 'italic',
+    }, sub));
+  }
+  return h('g', { key }, ...children);
 }
 
-function edgeLabel({ key, x, y, text, anchor = 'start' }) {
+function overflowLabel({ key, x, y, n, anchor = 'start' }) {
   return h('text', {
     key, x, y,
     textAnchor: anchor,
     fontFamily: fonts.mono, fontSize: 10,
     fill: 'var(--muted)',
-    letterSpacing: '0.04em',
-  }, text);
+  }, `+${n} more`);
 }
 
-function subLabel({ key, x, y, text }) {
-  return h('text', {
-    key, x, y,
-    textAnchor: 'middle',
-    fontFamily: fonts.mono, fontSize: 10,
-    fill: 'var(--muted)',
-    fontStyle: 'italic',
-  }, text);
+function edge({ key, x1, y1, x2, y2, label, curved, dashed }) {
+  const midx = (x1 + x2) / 2;
+  const midy = (y1 + y2) / 2;
+  const path = curved
+    ? `M ${x1} ${y1} C ${x1} ${midy}, ${x2} ${midy}, ${x2} ${y2}`
+    : `M ${x1} ${y1} L ${x2} ${y2}`;
+  const strokeProps = {
+    fill: 'none',
+    stroke: 'var(--border)',
+    strokeWidth: 1.2,
+    markerEnd: 'url(#sg-arrow)',
+  };
+  if (dashed) strokeProps.strokeDasharray = '3 3';
+  const elems = [h('path', { key: 'p', d: path, ...strokeProps })];
+  if (label) {
+    // Offset label above midpoint for vertical edges, to the right for others
+    elems.push(h('text', {
+      key: 'lbl',
+      x: midx + 4, y: midy + 3,
+      fontFamily: fonts.mono, fontSize: 9,
+      fill: 'var(--muted)',
+      letterSpacing: '0.06em',
+    }, label));
+  }
+  return h('g', { key }, ...elems);
 }