egregore-artifacts 0.4.0 → 0.6.0

package/lib/parsers/handoff.js

@@ -3,28 +3,36 @@
 // Detects referenced memory files and inlines their content
 import fs from 'node:fs';
 import path from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 
 export function parseHandoff(input) {
   let content;
   let inputDir = null;
+  let inputPath = null;
 
   if (typeof input === 'string' && (input.endsWith('.md') || input.includes('/'))) {
     if (!fs.existsSync(input)) throw new Error(`File not found: ${input}`);
     content = fs.readFileSync(input, 'utf-8');
     inputDir = path.dirname(input);
+    inputPath = input;
   } else if (typeof input === 'string') {
     content = input;
   } else {
     throw new Error('parseHandoff expects a file path or markdown string');
   }
 
-  const title = extractTitle(content);
-  const meta = extractMeta(content);
-  const sections = extractSections(content);
+  // Resolve graph subgraph first (reads the raw content), then strip the
+  // embedded block so it doesn't leak into section bodies or rendered text.
+  const gitRoot = findGitRoot();
+  const subgraph = resolveSubgraph({ content, inputPath, gitRoot });
+  const cleanContent = content.replace(/<!--\s*subgraph[\s\S]*?-->/g, '').trim();
+
+  const title = extractTitle(cleanContent);
+  const meta = extractMeta(cleanContent);
+  const sections = extractSections(cleanContent);
 
   // Detect referenced files (memory/*.md paths in backticks) and inline them
-  const attachments = extractReferencedFiles(content, inputDir);
+  const attachments = extractReferencedFiles(cleanContent, inputDir);
 
   return {
     title,
@@ -37,6 +45,7 @@ export function parseHandoff(input) {
     entryPoints: extractBullets(sections['Entry Points'] || ''),
     context: sections.Context || null,
     attachments,
+    subgraph,
     // Catch-all for non-standard sections
     extraSections: Object.entries(sections)
       .filter(([k]) => !['Summary', 'Briefing', 'Current State', 'Decisions',
@@ -47,6 +56,158 @@ export function parseHandoff(input) {
   };
 }
 
+// ── Subgraph resolution ────────────────────────────────────────────
+//
+// The subgraph shows the handoff's *graph-only* context — things not already
+// in the markdown header (author/recipients/project). Source priority:
+//   1. Embedded <!-- subgraph ... --> block if present (defensive — we don't
+//      write one today, but a future caller could snapshot manually).
+//   2. Live Cypher query via bin/graph.sh in connected mode.
+// If neither yields real data, the subgraph is null and the template skips
+// the section entirely — no "degraded" placeholder.
+
+function resolveSubgraph({ content, inputPath, gitRoot }) {
+  const embedded = extractEmbeddedSubgraph(content);
+
+  let live = null;
+  if (inputPath && gitRoot && isConnectedMode(gitRoot)) {
+    const sessionId = deriveSessionIdFromPath(inputPath);
+    if (sessionId) live = tryLiveSubgraphQuery(sessionId, gitRoot);
+  }
+
+  const sourced = live || embedded;
+  if (sourced && hasAnySubgraphData(sourced)) return sourced;
+  return null;
+}
+
+function extractEmbeddedSubgraph(content) {
+  const m = content.match(/<!--\s*subgraph\s*([\s\S]*?)-->/);
+  if (!m) return null;
+  try {
+    return JSON.parse(m[1].trim());
+  } catch {
+    return null;
+  }
+}
+
+function hasAnySubgraphData(sg) {
+  if (!sg) return false;
+  return (sg.continues && sg.continues.length)
+    || (sg.implementsHandoff && sg.implementsHandoff.length)
+    || (sg.implementedBy && sg.implementedBy.length)
+    || (sg.quests && sg.quests.length)
+    || (sg.artifacts && sg.artifacts.length)
+    || (sg.prs && sg.prs.length);
+}
+
+function findGitRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel 2>/dev/null', { encoding: 'utf-8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function isConnectedMode(gitRoot) {
+  try {
+    const configPath = path.join(gitRoot, 'egregore.json');
+    if (!fs.existsSync(configPath)) return false;
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (config.mode === 'local') return false;
+    return Boolean(config.api_url) || config.mode === 'connected';
+  } catch {
+    return false;
+  }
+}
+
+function deriveSessionIdFromPath(filePath) {
+  // memory/handoffs/2026-04/22-author-topic.md → 2026-04-22-author-topic
+  const base = path.basename(filePath, '.md');
+  const dir = path.basename(path.dirname(filePath));
+  if (/^\d{4}-\d{2}$/.test(dir)) return `${dir}-${base}`;
+  // Filename already starts with YYYY-MM-DD
+  if (/^\d{4}-\d{2}-\d{2}-/.test(base)) return base;
+  return null;
+}
+
+function tryLiveSubgraphQuery(sessionId, gitRoot) {
+  // 1-hop neighbors + 2-hop artifact→quest linkage. The artifactQuestLinks
+  // collection lets the renderer draw the :PART_OF edges from artifacts up
+  // to the quests they belong to — the feature that makes this a graph
+  // instead of a list.
+  const cypher = `MATCH (s:Session {id: $sessionId})
+OPTIONAL MATCH (s)-[:BY]->(author:Person)
+OPTIONAL MATCH (s)-[:HANDED_TO]->(recipient:Person)
+OPTIONAL MATCH (s)-[:ABOUT]->(project:Project)
+OPTIONAL MATCH (s)-[:IMPLEMENTS]->(prior:Session)
+OPTIONAL MATCH (prior)-[:BY]->(priorAuthor:Person)
+OPTIONAL MATCH (later:Session)-[:IMPLEMENTS]->(s)
+OPTIONAL MATCH (later)-[:BY]->(laterAuthor:Person)
+OPTIONAL MATCH (s)-[:CONTINUES]->(cont:Session)
+OPTIONAL MATCH (cont)-[:BY]->(contAuthor:Person)
+OPTIONAL MATCH (s)-[:ADVANCED|INVOLVES]->(quest:Quest)
+OPTIONAL MATCH (s)-[:HAS_ACTIVITY]->(art:Artifact)
+OPTIONAL MATCH (art)-[:PART_OF]->(artQuest:Quest)
+OPTIONAL MATCH (s)-[:PRODUCED]->(pr:PR)
+RETURN
+  collect(DISTINCT {name:author.name, github:author.github})                  AS authors,
+  collect(DISTINCT {name:recipient.name, github:recipient.github})            AS recipients,
+  project.name                                                                AS project,
+  collect(DISTINCT {id:prior.id, topic:prior.topic, author:priorAuthor.name}) AS implementsHandoff,
+  collect(DISTINCT {id:later.id, topic:later.topic, author:laterAuthor.name}) AS implementedBy,
+  collect(DISTINCT {id:cont.id,  topic:cont.topic,  author:contAuthor.name})  AS continues,
+  collect(DISTINCT {id:quest.id, title:quest.title})                          AS quests,
+  collect(DISTINCT {id:art.id, title:art.title, type:art.type})               AS artifacts,
+  collect(DISTINCT {artifactId:art.id, questId:artQuest.id, questTitle:artQuest.title}) AS artifactQuestLinks,
+  collect(DISTINCT {id:pr.id, number:pr.number, title:pr.title, repo:pr.repo}) AS prs`;
+
+  try {
+    const out = execFileSync(
+      'bash',
+      [path.join(gitRoot, 'bin/graph.sh'), 'query', cypher, JSON.stringify({ sessionId })],
+      { encoding: 'utf-8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+    return parseGraphResponse(out);
+  } catch {
+    return null;
+  }
+}
+
+function parseGraphResponse(raw) {
+  if (!raw || !raw.trim()) return null;
+  let body;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = body.results?.[0] || body;
+  const fields = result.fields;
+  const row = result.values?.[0];
+  if (!Array.isArray(fields) || !Array.isArray(row)) return null;
+
+  const obj = {};
+  fields.forEach((f, i) => { obj[f] = row[i]; });
+
+  // OPTIONAL MATCH + collect() emits sentinel entries when nothing matched —
+  // filter them out by requiring at least one of the key fields to be set.
+  const clean = (list, ...keys) => Array.isArray(list)
+    ? list.filter(x => x && keys.some(k => x[k] != null))
+    : [];
+  return {
+    authors:            clean(obj.authors,            'name', 'github'),
+    recipients:         clean(obj.recipients,         'name', 'github'),
+    project:            obj.project || null,
+    implementsHandoff:  clean(obj.implementsHandoff,  'id'),
+    implementedBy:      clean(obj.implementedBy,      'id'),
+    continues:          clean(obj.continues,          'id'),
+    quests:             clean(obj.quests,             'id', 'title'),
+    artifacts:          clean(obj.artifacts,          'id', 'title'),
+    artifactQuestLinks: clean(obj.artifactQuestLinks, 'artifactId', 'questId'),
+    prs:                clean(obj.prs,                'id', 'number'),
+  };
+}
+
 function extractReferencedFiles(content, inputDir) {
   const attachments = [];
   // Find backtick-wrapped paths that look like memory files

package/lib/shell.js

@@ -45,6 +45,13 @@ export function htmlShell(bodyHtml, { title = 'Egregore Artifact', type = 'artif
     --success-bg: #e8f5e9;
     --success-fg: #2e7d32;
     --green-p1: #2A7B5B;
+    /* Subgraph node fills — subtle tinted backgrounds per node type.
+       Strokes/labels use the existing strong tokens (--terracotta,
+       --blue-muted, --green-p1, --gold, etc.) for contrast. */
+    --quest-fill: rgba(42, 123, 91, 0.12);
+    --artifact-fill: rgba(176, 141, 87, 0.14);
+    --artifact-stroke: #B08D57;
+    --pr-fill: rgba(59, 45, 33, 0.04);
   }
 
   /* Dark mode overrides */
@@ -67,6 +74,10 @@ export function htmlShell(bodyHtml, { title = 'Egregore Artifact', type = 'artif
     --success-bg: rgba(107, 191, 107, 0.12);
     --success-fg: #9ed9a0;
     --green-p1: #6BBF6B;
+    --quest-fill: rgba(107, 191, 107, 0.14);
+    --artifact-fill: rgba(200, 169, 122, 0.16);
+    --artifact-stroke: #C8A97A;
+    --pr-fill: rgba(255, 255, 255, 0.04);
   }
 
   *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

package/lib/templates/handoff.js

@@ -6,6 +6,7 @@ import {
 } from '../components.js';
 import { renderMarkdownLite } from '../markdown.js';
 import { fonts } from '../tokens.js';
+import { renderSubgraph } from './subgraph.js';
 
 const h = React.createElement;
 
@@ -87,6 +88,16 @@ export function handoffTemplate(handoff) {
     );
   }
 
+  // Subgraph — handoff's neighborhood in the knowledge graph.
+  // Rendered as static SVG; renderSubgraph returns null if there's nothing to show.
+  const subgraphNode = renderSubgraph({
+    subgraph: handoff.subgraph,
+    handoffTopic: handoff.title,
+  });
+  if (subgraphNode) {
+    sections.push(React.cloneElement(subgraphNode, { key: 'subgraph' }));
+  }
+
   // Summary / Briefing
   if (handoff.summary) {
     sections.push(

package/lib/templates/subgraph.js

@@ -0,0 +1,552 @@
+// Handoff subgraph → inline static SVG
+//
+// 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.
+//
+// Layered DAG layout (top-to-bottom):
+//
+//   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)
+//
+//   Legend  ● Session  ● Person  ● Project  ● Quest  ● Artifact  ● PR
+//
+// 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.
+//
+// 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_9  = 5.4;
+
+// ── 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 {
+    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 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;
+
+  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;
+  }
+
+  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);
+
+  // ── Collect SVG children ─────────────────────────────────────────
+  const children = [];
+
+  // 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)' })
+    ),
+  ));
+
+  // ── Edges (drawn first so they sit behind nodes) ─────────────────
+
+  // 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,
+    }));
+  }
+
+  // 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',
+      }));
+    });
+  }
+  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,
+      }));
+    });
+  }
+
+  // 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,
+      }));
+    });
+    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,
+        }));
+      }
+    });
+  }
+
+  // 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,
+      }));
+    }
+  }
+
+  // ── 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' }));
+    }
+  }
+
+  // ── 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)',
+          letterSpacing: '0.03em',
+        }, legendLabels[t]),
+      );
+    }),
+  ));
+
+  return h('div', {
+    style: {
+      marginBottom: '2rem',
+      padding: '1rem 0.5rem 0.75rem',
+      borderBottom: '1px solid var(--hairline)',
+    },
+  },
+    h('div', {
+      style: {
+        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 ${WIDTH} ${HEIGHT}`,
+      width: '100%',
+      height: 'auto',
+      preserveAspectRatio: 'xMidYMid meet',
+      style: { display: 'block', maxHeight: '640px' },
+      role: 'img',
+      'aria-label': 'Handoff knowledge-graph neighborhood',
+    }, ...children),
+  );
+}
+
+// ── 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 rowSpan(nodes, gap) {
+  if (nodes.length === 0) return 0;
+  return nodes.reduce((a, n) => a + n.w, 0) + (nodes.length - 1) * gap;
+}
+
+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 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) + '…';
+}
+
+// ── rendering helpers ──────────────────────────────────────────────
+
+function renderSessionNode({ x, y, w, label, key }) {
+  const s = STYLE.session;
+  return h('g', { key },
+    h('rect', {
+      x, y, width: w, height: SESSION_H,
+      rx: 10, ry: 10,
+      fill: s.fill, stroke: s.stroke, strokeWidth: 1.5,
+    }),
+    h('text', {
+      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: s.text,
+    }, label),
+  );
+}
+
+function renderNode({ x, y, w, label, sub, kind, key }) {
+  const s = STYLE[kind] || STYLE.project;
+  const children = [
+    h('rect', {
+      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', {
+      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),
+  ];
+  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 overflowLabel({ key, x, y, n, anchor = 'start' }) {
+  return h('text', {
+    key, x, y,
+    textAnchor: anchor,
+    fontFamily: fonts.mono, fontSize: 10,
+    fill: 'var(--muted)',
+  }, `+${n} more`);
+}
+
+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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "egregore-artifacts",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Generate branded HTML artifacts from Egregore data",
   "type": "module",
   "license": "MIT",