Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(template): render nested lineage graph with ELK layout

Erenf6bb72a2bb0f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 111bc4a..0da2e95 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- Nested lineage graph in the map: React Flow 12 renders epochs → sessions → nodes as collapsible groups, ELK lays them out top-down in the page, with a minimap, controls and kind colours; the latest session opens expanded. 495 nodes lay out in ~96–155 ms per change in Chromium from `file://`.
- Status card at the top of the map: goal, done, pending and next from the most recently updated session, with `needsUser` items merged from every session active within 7 days (deduplicated by text, newest first).
- Template workspace (`packages/template`): React 19 + Vite 8 + `vite-plugin-singlefile`, dev fixture and the shared lineage view-model contract (`packages/cli/src/view/model.ts`).
- `codelineage build [dir]`: renders `.codelineage/lineage.html` from `project.json` and `sessions/*.json` (epochs in project order, nested node tree, unassigned sessions grouped), skips unreadable session files with a warning, redacts secrets and embeds the single-file template into the CLI bundle; `session write` rebuilds quietly afterwards.
diff --git a/package-lock.json b/package-lock.json
index 9bf543f..eefec94 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1809,6 +1809,55 @@
"assertion-error": "^2.0.1"
}
},
+ "node_modules/@types/d3-color": {
+ "version": "3.1.3",
+ "resolved": "https://registry.npmjs.org/@types/d3-color/-/d3-color-3.1.3.tgz",
+ "integrity": "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==",
+ "license": "MIT"
+ },
+ "node_modules/@types/d3-drag": {
+ "version": "3.0.7",
+ "resolved": "https://registry.npmjs.org/@types/d3-drag/-/d3-drag-3.0.7.tgz",
+ "integrity": "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-selection": "*"
+ }
+ },
+ "node_modules/@types/d3-interpolate": {
+ "version": "3.0.4",
+ "resolved": "https://registry.npmjs.org/@types/d3-interpolate/-/d3-interpolate-3.0.4.tgz",
+ "integrity": "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-color": "*"
+ }
+ },
+ "node_modules/@types/d3-selection": {
+ "version": "3.0.12",
+ "resolved": "https://registry.npmjs.org/@types/d3-selection/-/d3-selection-3.0.12.tgz",
+ "integrity": "sha512-Qe/KWYhEiIIxGs7HrAAjMfShxKldx19SJtr5zu53f3afPsdZNz7HHtdTLXo/kqeiWNXVycI24kSnfzBYkTzpgw==",
+ "license": "MIT"
+ },
+ "node_modules/@types/d3-transition": {
+ "version": "3.0.9",
+ "resolved": "https://registry.npmjs.org/@types/d3-transition/-/d3-transition-3.0.9.tgz",
+ "integrity": "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-selection": "*"
+ }
+ },
+ "node_modules/@types/d3-zoom": {
+ "version": "3.0.9",
+ "resolved": "https://registry.npmjs.org/@types/d3-zoom/-/d3-zoom-3.0.9.tgz",
+ "integrity": "sha512-0sE1406XBYJGiqD3AusTl9ZqC//2mIXix51tbom25gDCA8ri4xnSZg28CaSE8Srl6FClqABUKfsn0qghgdepMA==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-interpolate": "*",
+ "@types/d3-selection": "*"
+ }
+ },
"node_modules/@types/deep-eql": {
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
@@ -1837,7 +1886,7 @@
"version": "19.3.0",
"resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
"integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
- "dev": true,
+ "devOptional": true,
"license": "MIT",
"dependencies": {
"csstype": "^3.2.2"
@@ -1847,7 +1896,7 @@
"version": "19.3.0",
"resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.3.0.tgz",
"integrity": "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==",
- "dev": true,
+ "devOptional": true,
"license": "MIT",
"peerDependencies": {
"@types/react": "^19.3.0"
@@ -2323,6 +2372,48 @@
"url": "https://opencollective.com/vitest"
}
},
+ "node_modules/@xyflow/react": {
+ "version": "12.12.0",
+ "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.12.0.tgz",
+ "integrity": "sha512-74oXI0Rgm1Eu33cHQAd74J6oVgCH9mbFyTVQbsGgp2kmWwh0HdtBr2VP04z8mbPD+M/xO69nqG5dDEt7/EN2rQ==",
+ "license": "MIT",
+ "dependencies": {
+ "@xyflow/system": "0.0.83",
+ "classcat": "^5.0.3",
+ "zustand": "^4.4.0"
+ },
+ "peerDependencies": {
+ "@types/react": ">=17",
+ "@types/react-dom": ">=17",
+ "react": ">=17",
+ "react-dom": ">=17"
+ },
+ "peerDependenciesMeta": {
+ "@types/react": {
+ "optional": true
+ },
+ "@types/react-dom": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/@xyflow/system": {
+ "version": "0.0.83",
+ "resolved": "https://registry.npmjs.org/@xyflow/system/-/system-0.0.83.tgz",
+ "integrity": "sha512-a//eDjez3WZF47aaPTfVUDD0OINOq+WVwBZCRTqG+m0a5euX8EwlJ4jMY1Wxz0Ocj4xOeekJ70V22Pq0ll8RJw==",
+ "license": "MIT",
+ "dependencies": {
+ "@types/d3-drag": "^3.0.7",
+ "@types/d3-interpolate": "^3.0.4",
+ "@types/d3-selection": "^3.0.10",
+ "@types/d3-transition": "^3.0.8",
+ "@types/d3-zoom": "^3.0.8",
+ "d3-drag": "^3.0.0",
+ "d3-interpolate": "^3.0.1",
+ "d3-selection": "^3.0.0",
+ "d3-zoom": "^3.0.0"
+ }
+ },
"node_modules/acorn": {
"version": "8.19.0",
"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz",
@@ -2423,6 +2514,12 @@
"url": "https://paulmillr.com/funding/"
}
},
+ "node_modules/classcat": {
+ "version": "5.0.5",
+ "resolved": "https://registry.npmjs.org/classcat/-/classcat-5.0.5.tgz",
+ "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
+ "license": "MIT"
+ },
"node_modules/cli-width": {
"version": "4.1.0",
"resolved": "https://registry.npmjs.org/cli-width/-/cli-width-4.1.0.tgz",
@@ -2467,9 +2564,114 @@
"version": "3.2.3",
"resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
"integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
- "dev": true,
+ "devOptional": true,
"license": "MIT"
},
+ "node_modules/d3-color": {
+ "version": "3.1.0",
+ "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz",
+ "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-dispatch": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
+ "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-drag": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz",
+ "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-dispatch": "1 - 3",
+ "d3-selection": "3"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-ease": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz",
+ "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==",
+ "license": "BSD-3-Clause",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-interpolate": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz",
+ "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-color": "1 - 3"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-selection": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz",
+ "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-timer": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
+ "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+ "license": "ISC",
+ "engines": {
+ "node": ">=12"
+ }
+ },
+ "node_modules/d3-transition": {
+ "version": "3.0.1",
+ "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz",
+ "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-color": "1 - 3",
+ "d3-dispatch": "1 - 3",
+ "d3-ease": "1 - 3",
+ "d3-interpolate": "1 - 3",
+ "d3-timer": "1 - 3"
+ },
+ "engines": {
+ "node": ">=12"
+ },
+ "peerDependencies": {
+ "d3-selection": "2 - 3"
+ }
+ },
+ "node_modules/d3-zoom": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz",
+ "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==",
+ "license": "ISC",
+ "dependencies": {
+ "d3-dispatch": "1 - 3",
+ "d3-drag": "2 - 3",
+ "d3-interpolate": "1 - 3",
+ "d3-selection": "2 - 3",
+ "d3-transition": "2 - 3"
+ },
+ "engines": {
+ "node": ">=12"
+ }
+ },
"node_modules/detect-libc": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -2480,6 +2682,12 @@
"node": ">=8"
}
},
+ "node_modules/elkjs": {
+ "version": "0.12.0",
+ "resolved": "https://registry.npmjs.org/elkjs/-/elkjs-0.12.0.tgz",
+ "integrity": "sha512-YZcKynxVxYoKIOEpywEPwCFdg+BTbxQRNf3pbwdDCvc8O3kQD8bmIwSxKU1eOTVc4Xo+VG9Te+575mlfvOrhEQ==",
+ "license": "EPL-2.0 OR GPL-3.0-or-later"
+ },
"node_modules/es-module-lexer": {
"version": "2.3.2",
"resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
@@ -3556,6 +3764,15 @@
"devOptional": true,
"license": "MIT"
},
+ "node_modules/use-sync-external-store": {
+ "version": "1.7.0",
+ "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.7.0.tgz",
+ "integrity": "sha512-6L+EeigHMQhdaIPNIFUKwfWJSwWFQ8gJbJ2DLOs5sDIegTwR9fRxvnM3uciHKjIZhFz+KAv2emhWMRvDmMcY8A==",
+ "license": "MIT",
+ "peerDependencies": {
+ "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+ }
+ },
"node_modules/vite": {
"version": "8.3.5",
"resolved": "https://registry.npmjs.org/vite/-/vite-8.3.5.tgz",
@@ -3771,6 +3988,34 @@
"url": "https://github.com/sponsors/colinhacks"
}
},
+ "node_modules/zustand": {
+ "version": "4.5.7",
+ "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
+ "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
+ "license": "MIT",
+ "dependencies": {
+ "use-sync-external-store": "^1.2.2"
+ },
+ "engines": {
+ "node": ">=12.7.0"
+ },
+ "peerDependencies": {
+ "@types/react": ">=16.8",
+ "immer": ">=9.0.6",
+ "react": ">=16.8"
+ },
+ "peerDependenciesMeta": {
+ "@types/react": {
+ "optional": true
+ },
+ "immer": {
+ "optional": true
+ },
+ "react": {
+ "optional": true
+ }
+ }
+ },
"packages/cli": {
"name": "codelineage",
"version": "0.1.0",
@@ -3802,6 +4047,8 @@
"packages/template": {
"version": "0.0.0",
"dependencies": {
+ "@xyflow/react": "^12.12.0",
+ "elkjs": "^0.12.0",
"react": "^19.3.1",
"react-dom": "^19.3.1"
},
diff --git a/packages/template/README.md b/packages/template/README.md
new file mode 100644
index 0000000..d145f74
--- /dev/null
+++ b/packages/template/README.md
@@ -0,0 +1,29 @@
+# template
+
+Private workspace package: the React app that becomes `lineage.html`. Vite and
+`vite-plugin-singlefile` inline every asset, including React Flow's stylesheet and
+the bundled ELK layout engine, so the page makes no external requests and works
+from `file://`.
+
+## Dev
+
+```bash
+npm run dev -w template # renders src/fixture.ts through the same app
+npm run build -w template # writes dist/index.html (embedded by the CLI build)
+```
+
+`src/graph.ts` turns the view model into an ELK hierarchy (epoch → session → node)
+and returns React Flow nodes with parent-relative positions. Only expanded groups
+send their children to ELK; the page opens with the most recent session expanded.
+
+## Layout budget
+
+Measured 2026-10-21 in Chromium from `file://`, 495 nodes across 15 sessions in 3
+epochs, every group expanded:
+- `elk.layout` for the full hierarchy: 96–155 ms (smaller partial layouts: 15–90 ms).
+- The map renders 513 React Flow nodes with no console errors and no long main-thread
+ block; collapsing a group re-runs the layout in well under 100 ms.
+- Default view of the same project (groups collapsed, latest session expanded): ~41 ms.
+
+`document.documentElement.dataset.layoutMs` always carries the last measured time,
+which is how these numbers were read from the built page.
diff --git a/packages/template/package.json b/packages/template/package.json
index e695fcd..7f9032b 100644
--- a/packages/template/package.json
+++ b/packages/template/package.json
@@ -9,6 +9,8 @@
"preview": "vite preview"
},
"dependencies": {
+ "@xyflow/react": "^12.12.0",
+ "elkjs": "^0.12.0",
"react": "^19.3.1",
"react-dom": "^19.3.1"
},
diff --git a/packages/template/src/App.tsx b/packages/template/src/App.tsx
index b43d952..b1015b1 100644
--- a/packages/template/src/App.tsx
+++ b/packages/template/src/App.tsx
@@ -1,45 +1,6 @@
-import type {
- LineageViewModel,
- StatusCard,
- ViewNode,
- ViewSession,
-} from "../../cli/src/view/model.js";
-
-function formatTime(iso: string | null): string {
- if (!iso) return "—";
- const date = new Date(iso);
- return Number.isNaN(date.getTime()) ? iso : date.toLocaleString();
-}
-
-function NodeItem({ node }: { node: ViewNode }) {
- return (
- <li className="node">
- <div className="node-head">
- <span className={`kind kind-${node.kind}`}>{node.kind}</span>
- <strong>{node.title}</strong>
- {node.at ? <time dateTime={node.at}>{formatTime(node.at)}</time> : null}
- </div>
- {node.summary ? <p>{node.summary}</p> : null}
- {node.why ? (
- <p className="why">
- <span>why</span> {node.why}
- </p>
- ) : null}
- {node.children.length > 0 ? <NodeList nodes={node.children} /> : null}
- </li>
- );
-}
-
-function NodeList({ nodes }: { nodes: ViewNode[] }) {
- if (nodes.length === 0) return <p className="empty">No steps recorded yet.</p>;
- return (
- <ul className="nodes">
- {nodes.map((node) => (
- <NodeItem key={node.id} node={node} />
- ))}
- </ul>
- );
-}
+import type { LineageViewModel, StatusCard } from "../../cli/src/view/model.js";
+import { formatTime } from "./format.js";
+import { Graph } from "./Graph.js";
function StatusPanel({ status }: { status: StatusCard }) {
return (
@@ -85,20 +46,6 @@ function StatusPanel({ status }: { status: StatusCard }) {
);
}
-function SessionCard({ session }: { session: ViewSession }) {
- return (
- <article className="session">
- <header>
- <h3>{session.title || session.sessionId}</h3>
- <code>{session.sessionId}</code>
- <span className="muted">updated {formatTime(session.updatedAt)}</span>
- </header>
- <p className="session-goal">{session.status.goal}</p>
- <NodeList nodes={session.nodes} />
- </article>
- );
-}
-
export function App({ model }: { model: LineageViewModel }) {
const sessionCount =
model.epochs.reduce((sum, epoch) => sum + epoch.sessions.length, 0) + model.unassigned.length;
@@ -120,27 +67,7 @@ export function App({ model }: { model: LineageViewModel }) {
<StatusPanel status={model.status} />
- {model.epochs.map((epoch) => (
- <section className="epoch" key={epoch.id}>
- <h2>
- {epoch.title} <span className="muted">({epoch.sessions.length})</span>
- </h2>
- {epoch.sessions.map((session) => (
- <SessionCard key={session.sessionId} session={session} />
- ))}
- </section>
- ))}
-
- {model.unassigned.length > 0 ? (
- <section className="epoch unassigned">
- <h2>
- Unassigned <span className="muted">({model.unassigned.length})</span>
- </h2>
- {model.unassigned.map((session) => (
- <SessionCard key={session.sessionId} session={session} />
- ))}
- </section>
- ) : null}
+ <Graph model={model} />
</main>
);
}
diff --git a/packages/template/src/Graph.tsx b/packages/template/src/Graph.tsx
new file mode 100644
index 0000000..d6cea84
--- /dev/null
+++ b/packages/template/src/Graph.tsx
@@ -0,0 +1,214 @@
+import {
+ Background,
+ Controls,
+ Handle,
+ MiniMap,
+ type NodeProps,
+ type NodeTypes,
+ Position,
+ ReactFlow,
+ ReactFlowProvider,
+ useReactFlow,
+} from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import type { LineageViewModel } from "../../cli/src/view/model.js";
+import { formatTime } from "./format.js";
+import {
+ defaultExpanded,
+ type EpochFlowNode,
+ type GraphNode,
+ type LineageFlowNode,
+ layoutGraph,
+ type SessionFlowNode,
+} from "./graph.js";
+
+/** Toggle callback reaches the group headers without threading props through React Flow. */
+const GraphActions = createContext<{ toggle: (id: string) => void }>({ toggle: () => {} });
+
+function GroupToggle({
+ id,
+ data,
+}: {
+ id: string;
+ data: { expanded: boolean; hasChildren: boolean };
+}) {
+ const { toggle } = useContext(GraphActions);
+ if (!data.hasChildren) return <span className="group-toggle is-empty">·</span>;
+ return (
+ <button
+ type="button"
+ className="group-toggle"
+ aria-expanded={data.expanded}
+ aria-label={data.expanded ? "Collapse" : "Expand"}
+ onClick={(event) => {
+ event.stopPropagation();
+ toggle(id);
+ }}
+ >
+ {data.expanded ? "▾" : "▸"}
+ </button>
+ );
+}
+
+/** Edges need handles; they are invisible because the layout owns the geometry. */
+function AnchorHandles() {
+ return (
+ <>
+ <Handle type="target" position={Position.Top} className="flow-handle" isConnectable={false} />
+ <Handle
+ type="source"
+ position={Position.Bottom}
+ className="flow-handle"
+ isConnectable={false}
+ />
+ </>
+ );
+}
+
+function EpochNode({ id, data }: NodeProps<EpochFlowNode>) {
+ return (
+ <div className="flow-group epoch-group">
+ <AnchorHandles />
+ <div className="group-head">
+ <GroupToggle id={id} data={data} />
+ <strong className="group-title">{data.title}</strong>
+ <span className="muted">
+ {data.count} session{data.count === 1 ? "" : "s"}
+ </span>
+ </div>
+ </div>
+ );
+}
+
+function SessionNode({ id, data }: NodeProps<SessionFlowNode>) {
+ return (
+ <div className="flow-group session-group" title={data.goal || data.title}>
+ <AnchorHandles />
+ <div className="group-head">
+ <GroupToggle id={id} data={data} />
+ <strong className="group-title">{data.title}</strong>
+ <span className="muted">{data.count}</span>
+ <time className="muted" dateTime={data.updatedAt}>
+ {formatTime(data.updatedAt)}
+ </time>
+ </div>
+ </div>
+ );
+}
+
+function LineageBox({ data }: NodeProps<LineageFlowNode>) {
+ return (
+ <div className={`lineage-box kind-${data.kind}`}>
+ <AnchorHandles />
+ <div className="lineage-head">
+ <span className={`kind kind-${data.kind}`}>{data.kind}</span>
+ <strong title={data.title}>{data.title}</strong>
+ </div>
+ {data.at ? (
+ <time dateTime={data.at}>{formatTime(data.at)}</time>
+ ) : data.summary ? (
+ <p title={data.summary}>{data.summary}</p>
+ ) : null}
+ </div>
+ );
+}
+
+const nodeTypes: NodeTypes = {
+ epoch: EpochNode,
+ session: SessionNode,
+ lineage: LineageBox,
+};
+
+/** React Flow overlays get their colours from the node type, not the kind. */
+function minimapColor(node: GraphNode): string {
+ if (node.type === "epoch") return "#2b3446";
+ if (node.type === "session") return "#243040";
+ const kind = node.data.kind;
+ if (kind === "decision") return "#4b3a72";
+ if (kind === "question") return "#5a4526";
+ return "#1f2a3d";
+}
+
+function Flow({ model }: { model: LineageViewModel }) {
+ const [expanded, setExpanded] = useState<Set<string>>(() => defaultExpanded(model));
+ const [layout, setLayout] = useState<Awaited<ReturnType<typeof layoutGraph>> | null>(null);
+ const [error, setError] = useState<string | null>(null);
+ const { fitView } = useReactFlow();
+
+ useEffect(() => {
+ let cancelled = false;
+ setError(null);
+ layoutGraph(model, expanded)
+ .then((result) => {
+ if (cancelled) return;
+ setLayout(result);
+ // Survives into the single-file build so a 500-node run can be measured.
+ document.documentElement.dataset.layoutMs = result.layoutMs.toFixed(1);
+ })
+ .catch((err: unknown) => {
+ if (cancelled) return;
+ setError(err instanceof Error ? err.message : String(err));
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [model, expanded]);
+
+ useEffect(() => {
+ if (!layout) return;
+ const timer = setTimeout(() => {
+ void fitView({ padding: 0.15, duration: 200 });
+ }, 60);
+ return () => clearTimeout(timer);
+ }, [layout, fitView]);
+
+ const toggle = useCallback((id: string) => {
+ setExpanded((previous) => {
+ const next = new Set(previous);
+ if (next.has(id)) next.delete(id);
+ else next.add(id);
+ return next;
+ });
+ }, []);
+ const actions = useMemo(() => ({ toggle }), [toggle]);
+
+ if (error) return <p className="error graph-status">{error}</p>;
+ if (!layout) return <p className="graph-status">Laying out the map…</p>;
+ if (layout.nodes.length === 0) {
+ return <p className="graph-status empty">No sessions recorded yet.</p>;
+ }
+
+ return (
+ <GraphActions.Provider value={actions}>
+ <ReactFlow
+ nodes={layout.nodes}
+ edges={layout.edges}
+ nodeTypes={nodeTypes}
+ defaultEdgeOptions={{ style: { stroke: "#4f5b74", strokeWidth: 1.5 } }}
+ fitView
+ minZoom={0.05}
+ maxZoom={2}
+ nodesDraggable={false}
+ nodesConnectable={false}
+ elementsSelectable={false}
+ colorMode="dark"
+ >
+ <Background gap={24} size={1} color="#242a36" />
+ <MiniMap pannable zoomable nodeColor={minimapColor} />
+ <Controls showInteractive={false} />
+ </ReactFlow>
+ </GraphActions.Provider>
+ );
+}
+
+/** Nested epoch → session → node map; layout runs in the page from embedded data. */
+export function Graph({ model }: { model: LineageViewModel }) {
+ return (
+ <section className="graph-wrap" aria-label="Project lineage graph">
+ <ReactFlowProvider>
+ <Flow model={model} />
+ </ReactFlowProvider>
+ </section>
+ );
+}
diff --git a/packages/template/src/format.ts b/packages/template/src/format.ts
new file mode 100644
index 0000000..fff3812
--- /dev/null
+++ b/packages/template/src/format.ts
@@ -0,0 +1,6 @@
+/** Renders an ISO timestamp for humans; an unparseable value is shown as-is. */
+export function formatTime(iso: string | null): string {
+ if (!iso) return "—";
+ const date = new Date(iso);
+ return Number.isNaN(date.getTime()) ? iso : date.toLocaleString();
+}
diff --git a/packages/template/src/graph.ts b/packages/template/src/graph.ts
new file mode 100644
index 0000000..b3cfd59
--- /dev/null
+++ b/packages/template/src/graph.ts
@@ -0,0 +1,354 @@
+import type { Edge as FlowEdge, Node as FlowNode } from "@xyflow/react";
+import ELK, {
+ type ElkExtendedEdge,
+ type ELK as ElkInstance,
+ type ElkNode,
+} from "elkjs/lib/elk.bundled.js";
+import type { LineageViewModel, ViewNode, ViewSession } from "../../cli/src/view/model.js";
+
+/**
+ * Builds the nested React Flow graph (epoch → session → node) and lays it out
+ * with ELK in the page. ELK returns child coordinates relative to their parent,
+ * which is what React Flow's `parentId` children expect, so no conversion is
+ * needed for nested nodes.
+ */
+
+/** Fixed card sizes keep ELK fast: it never needs to measure DOM text. */
+const NODE_WIDTH = 220;
+const NODE_HEIGHT = 64;
+const GROUP_HEIGHT = 56;
+const GROUP_WIDTH = 260;
+const GROUP_PADDING = 24;
+const GROUP_HEADER = 44;
+
+const ROOT_PADDING = 48;
+
+export type EpochData = {
+ title: string;
+ count: number;
+ expanded: boolean;
+ hasChildren: boolean;
+};
+
+export type SessionData = {
+ title: string;
+ sessionId: string;
+ updatedAt: string;
+ goal: string;
+ count: number;
+ expanded: boolean;
+ hasChildren: boolean;
+};
+
+export type LineageData = {
+ kind: ViewNode["kind"];
+ title: string;
+ summary?: string;
+ why?: string;
+ at?: string;
+};
+
+export type EpochFlowNode = FlowNode<EpochData, "epoch">;
+export type SessionFlowNode = FlowNode<SessionData, "session">;
+export type LineageFlowNode = FlowNode<LineageData, "lineage">;
+
+export type GraphNode = EpochFlowNode | SessionFlowNode | LineageFlowNode;
+
+export interface GraphLayout {
+ nodes: GraphNode[];
+ edges: FlowEdge[];
+ /** Wall-clock time spent inside `elk.layout`, in milliseconds. */
+ layoutMs: number;
+}
+
+export const UNASSIGNED_EPOCH_ID = "unassigned";
+
+export function epochId(id: string): string {
+ return `epoch:${id}`;
+}
+
+export function sessionId(id: string): string {
+ return `session:${id}`;
+}
+
+function nodeId(sessionGroup: string, id: string): string {
+ return `node:${sessionGroup}:${id}`;
+}
+
+const LAYOUT_OPTIONS = {
+ "elk.algorithm": "layered",
+ "elk.direction": "DOWN",
+ "elk.hierarchyHandling": "INCLUDE_CHILDREN",
+ "elk.spacing.nodeNode": "40",
+ "elk.layered.spacing.nodeNodeBetweenLayers": "48",
+ "elk.separateConnectedComponents": "true",
+} as const;
+
+function groupOptions() {
+ return {
+ ...LAYOUT_OPTIONS,
+ "elk.padding": `[top=${GROUP_HEADER + 8},left=${GROUP_PADDING},bottom=${GROUP_PADDING},right=${GROUP_PADDING}]`,
+ };
+}
+
+/** The map opens on the most recently updated session, with its epoch expanded. */
+export function defaultExpanded(model: LineageViewModel): Set<string> {
+ const candidates: { session: ViewSession; group: string }[] = [];
+ for (const epoch of model.epochs) {
+ for (const session of epoch.sessions) {
+ candidates.push({ session, group: epochId(epoch.id) });
+ }
+ }
+ for (const session of model.unassigned) {
+ candidates.push({ session, group: UNASSIGNED_EPOCH_ID });
+ }
+ const latest = candidates.sort(
+ (a, b) => Date.parse(b.session.updatedAt) - Date.parse(a.session.updatedAt),
+ )[0];
+ if (!latest) return new Set();
+ return new Set([latest.group, sessionId(latest.session.sessionId)]);
+}
+
+interface Group {
+ id: string;
+ title: string;
+ sessions: ViewSession[];
+}
+
+function toFlowEdge(edge: ElkExtendedEdge, existing: Set<string>): FlowEdge | null {
+ if (existing.has(edge.id)) return null;
+ existing.add(edge.id);
+ const [source] = edge.sources;
+ const [target] = edge.targets;
+ if (!source || !target) return null;
+ return { id: edge.id, source, target, type: "smoothstep" };
+}
+
+/** Links sibling boxes so the layered layout stacks them in model order. */
+function chainEdges(ids: string[]): ElkExtendedEdge[] {
+ const edges: ElkExtendedEdge[] = [];
+ for (let i = 1; i < ids.length; i += 1) {
+ const source = ids[i - 1];
+ const target = ids[i];
+ if (source && target) {
+ edges.push({ id: `edge:${source}->${target}`, sources: [source], targets: [target] });
+ }
+ }
+ return edges;
+}
+
+function collectNodeBoxes(
+ nodes: ViewNode[],
+ parent: string | null,
+ sessionGroup: string,
+ out: ElkNode[],
+ edges: ElkExtendedEdge[],
+ meta: Map<string, string | null>,
+): void {
+ for (const node of nodes) {
+ const id = nodeId(sessionGroup, node.id);
+ out.push({ id, width: NODE_WIDTH, height: NODE_HEIGHT });
+ meta.set(id, sessionGroup);
+ if (parent !== null) {
+ edges.push({ id: `edge:${parent}->${id}`, sources: [parent], targets: [id] });
+ }
+ collectNodeBoxes(node.children, id, sessionGroup, out, edges, meta);
+ }
+}
+
+function buildSession(
+ session: ViewSession,
+ expanded: ReadonlySet<string>,
+ parentId: string,
+ meta: Map<string, string | null>,
+): ElkNode {
+ const id = sessionId(session.sessionId);
+ meta.set(id, parentId);
+ const showChildren = expanded.has(id) && session.nodes.length > 0;
+ if (!showChildren) return { id, width: GROUP_WIDTH, height: GROUP_HEIGHT };
+
+ const children: ElkNode[] = [];
+ const edges: ElkExtendedEdge[] = [];
+ collectNodeBoxes(session.nodes, null, id, children, edges, meta);
+ return { id, children, edges, layoutOptions: groupOptions() };
+}
+
+function buildEpoch(
+ group: Group,
+ expanded: ReadonlySet<string>,
+ meta: Map<string, string | null>,
+): ElkNode {
+ meta.set(group.id, null);
+ const showChildren = expanded.has(group.id) && group.sessions.length > 0;
+ if (!showChildren) return { id: group.id, width: GROUP_WIDTH, height: GROUP_HEIGHT };
+
+ const children = group.sessions.map((session) => buildSession(session, expanded, group.id, meta));
+ const edges = chainEdges(children.map((child) => child.id));
+ return { id: group.id, children, edges, layoutOptions: groupOptions() };
+}
+
+interface Sized {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
+function collectSizes(elk: ElkNode, out: Map<string, Sized>): void {
+ for (const child of elk.children ?? []) {
+ out.set(child.id, {
+ x: child.x ?? 0,
+ y: child.y ?? 0,
+ width: child.width ?? GROUP_WIDTH,
+ height: child.height ?? GROUP_HEIGHT,
+ });
+ collectSizes(child, out);
+ }
+}
+
+function countNodes(nodes: ViewNode[]): number {
+ return nodes.reduce((sum, node) => sum + 1 + countNodes(node.children), 0);
+}
+
+/**
+ * Lays out the whole map. Only expanded groups send their children to ELK, so
+ * the default (collapsed) view costs one small box per epoch and session.
+ */
+export async function layoutGraph(
+ model: LineageViewModel,
+ expanded: ReadonlySet<string>,
+ elk: ElkInstance = new ELK(),
+): Promise<GraphLayout> {
+ const groups: Group[] = model.epochs.map((epoch) => ({
+ id: epochId(epoch.id),
+ title: epoch.title,
+ sessions: epoch.sessions,
+ }));
+ if (model.unassigned.length > 0) {
+ groups.push({ id: UNASSIGNED_EPOCH_ID, title: "Unassigned", sessions: model.unassigned });
+ }
+
+ const parents = new Map<string, string | null>();
+ const rootChildren = groups.map((group) => buildEpoch(group, expanded, parents));
+ const rootEdges = chainEdges(rootChildren.map((child) => child.id));
+
+ const graph: ElkNode = {
+ id: "root",
+ layoutOptions: {
+ ...LAYOUT_OPTIONS,
+ "elk.padding": `[top=${ROOT_PADDING},left=${ROOT_PADDING},bottom=${ROOT_PADDING},right=${ROOT_PADDING}]`,
+ },
+ children: rootChildren,
+ edges: rootEdges,
+ };
+
+ const started = performance.now();
+ const result = await elk.layout(graph);
+ const layoutMs = performance.now() - started;
+
+ const sizes = new Map<string, Sized>();
+ collectSizes(result, sizes);
+ const seenEdges = new Set<string>();
+ const edges: FlowEdge[] = [];
+ const addEdge = (edge: ElkExtendedEdge): void => {
+ const flow = toFlowEdge(edge, seenEdges);
+ if (flow) edges.push(flow);
+ };
+ for (const edge of rootEdges) addEdge(edge);
+ for (const child of rootChildren) {
+ for (const edge of child.edges ?? []) addEdge(edge);
+ for (const session of child.children ?? []) {
+ for (const edge of session.edges ?? []) addEdge(edge);
+ }
+ }
+
+ const nodes: GraphNode[] = [];
+ const box = (id: string): Sized =>
+ sizes.get(id) ?? { x: 0, y: 0, width: GROUP_WIDTH, height: GROUP_HEIGHT };
+
+ for (const group of groups) {
+ const epochExpanded = expanded.has(group.id);
+ const epochSize = box(group.id);
+ nodes.push({
+ id: group.id,
+ type: "epoch",
+ position: { x: epochSize.x, y: epochSize.y },
+ width: epochSize.width,
+ height: epochSize.height,
+ style: { width: epochSize.width, height: epochSize.height },
+ draggable: false,
+ connectable: false,
+ selectable: false,
+ data: {
+ title: group.title,
+ count: group.sessions.length,
+ expanded: epochExpanded,
+ hasChildren: group.sessions.length > 0,
+ },
+ });
+ if (!epochExpanded) continue;
+
+ for (const session of group.sessions) {
+ const id = sessionId(session.sessionId);
+ const sessionExpanded = expanded.has(id);
+ const sessionSize = box(id);
+ nodes.push({
+ id,
+ type: "session",
+ parentId: parents.get(id) ?? group.id,
+ position: { x: sessionSize.x, y: sessionSize.y },
+ width: sessionSize.width,
+ height: sessionSize.height,
+ style: { width: sessionSize.width, height: sessionSize.height },
+ draggable: false,
+ connectable: false,
+ selectable: false,
+ data: {
+ title: session.title || session.sessionId,
+ sessionId: session.sessionId,
+ updatedAt: session.updatedAt,
+ goal: session.status.goal,
+ count: countNodes(session.nodes),
+ expanded: sessionExpanded,
+ hasChildren: session.nodes.length > 0,
+ },
+ });
+ if (!sessionExpanded) continue;
+ collectFlowNodes(session.nodes, id, nodes, sizes);
+ }
+ }
+
+ return { nodes, edges, layoutMs };
+}
+
+function collectFlowNodes(
+ nodes: ViewNode[],
+ parent: string,
+ out: GraphNode[],
+ sizes: Map<string, Sized>,
+): void {
+ for (const node of nodes) {
+ const id = nodeId(parent, node.id);
+ const size = sizes.get(id) ?? { x: 0, y: 0, width: NODE_WIDTH, height: NODE_HEIGHT };
+ out.push({
+ id,
+ type: "lineage",
+ parentId: parent,
+ position: { x: size.x, y: size.y },
+ width: size.width,
+ height: size.height,
+ style: { width: size.width, height: size.height },
+ draggable: false,
+ connectable: false,
+ selectable: false,
+ data: {
+ kind: node.kind,
+ title: node.title,
+ ...(node.summary === undefined ? {} : { summary: node.summary }),
+ ...(node.why === undefined ? {} : { why: node.why }),
+ ...(node.at === undefined ? {} : { at: node.at }),
+ },
+ });
+ collectFlowNodes(node.children, parent, out, sizes);
+ }
+}
diff --git a/packages/template/src/styles.css b/packages/template/src/styles.css
index d3bd1fd..5354f83 100644
--- a/packages/template/src/styles.css
+++ b/packages/template/src/styles.css
@@ -26,7 +26,7 @@ body {
}
main {
- max-width: 960px;
+ max-width: 1200px;
margin: 0 auto;
padding: 32px 24px 64px;
}
@@ -114,77 +114,167 @@ ul {
white-space: nowrap;
}
-.epoch {
- margin-top: 28px;
+.graph-wrap {
+ height: clamp(480px, 72vh, 900px);
+ margin-top: 24px;
+ background: #12151b;
+ border: 1px solid var(--line);
+ border-radius: 12px;
+ overflow: hidden;
}
-.session {
- margin-top: 12px;
- padding: 14px 16px;
- background: var(--panel);
+.graph-status {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ height: 100%;
+ margin: 0;
+ padding: 24px;
+}
+
+/* React Flow group nodes: epoch and session boxes that contain their children. */
+.flow-group {
+ width: 100%;
+ height: 100%;
+ background: rgba(23, 26, 33, 0.72);
border: 1px solid var(--line);
border-radius: 10px;
}
-.session header {
+.epoch-group {
+ background: rgba(20, 24, 32, 0.6);
+ border-color: #333c50;
+}
+
+.group-head {
display: flex;
- align-items: baseline;
- flex-wrap: wrap;
- gap: 10px;
+ align-items: center;
+ gap: 8px;
+ height: 44px;
+ padding: 0 10px;
}
-.session code {
- color: var(--accent);
- font-size: 12px;
+.group-title {
+ min-width: 0;
+ overflow: hidden;
+ white-space: nowrap;
+ text-overflow: ellipsis;
}
-.session-goal {
+.group-toggle {
+ flex: none;
+ width: 20px;
+ height: 20px;
+ padding: 0;
+ line-height: 1;
color: var(--muted);
+ background: #1d222c;
+ border: 1px solid var(--line);
+ border-radius: 5px;
+ cursor: pointer;
+}
+
+.group-toggle:hover {
+ color: var(--text);
+ border-color: var(--accent);
+}
+
+.group-toggle.is-empty {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ cursor: default;
+}
+
+/* Edges attach here; handles stay invisible because layout decides the shape. */
+.react-flow__handle.flow-handle {
+ width: 4px;
+ height: 4px;
+ min-width: 0;
+ min-height: 0;
+ pointer-events: none;
+ opacity: 0;
+ border: 0;
+ background: transparent;
+}
+
+/* Node cards; the left border encodes the node kind. */
+.lineage-box {
+ width: 100%;
+ height: 100%;
+ padding: 7px 10px;
+ overflow: hidden;
+ background: var(--panel);
+ border: 1px solid var(--line);
+ border-left: 3px solid var(--accent);
+ border-radius: 8px;
+}
+
+.lineage-box.kind-phase {
+ border-left-color: var(--accent);
}
-.nodes {
- border-left: 1px solid var(--line);
- padding-left: 16px;
- list-style: none;
+.lineage-box.kind-step {
+ border-left-color: #7dcfff;
}
-.node {
- margin: 8px 0;
+.lineage-box.kind-decision {
+ border-left-color: #c0a8ff;
}
-.node-head {
+.lineage-box.kind-question {
+ border-left-color: var(--warn);
+}
+
+.lineage-head {
display: flex;
- align-items: baseline;
- flex-wrap: wrap;
- gap: 8px;
+ align-items: center;
+ gap: 6px;
+ min-width: 0;
+}
+
+.lineage-head strong {
+ overflow: hidden;
+ font-size: 13px;
+ white-space: nowrap;
+ text-overflow: ellipsis;
+}
+
+.lineage-box p {
+ margin: 3px 0 0;
+ overflow: hidden;
+ color: var(--muted);
+ font-size: 11px;
+ white-space: nowrap;
+ text-overflow: ellipsis;
+}
+
+.lineage-box time {
+ display: block;
+ margin-top: 1px;
}
.kind {
+ flex: none;
padding: 1px 6px;
border-radius: 4px;
- font-size: 11px;
+ font-size: 10px;
text-transform: uppercase;
letter-spacing: 0.04em;
background: #242a36;
color: var(--muted);
}
-.kind-decision {
+.kind.kind-decision {
background: #2b2440;
color: #c0a8ff;
}
-.kind-question {
+.kind.kind-question {
background: #3a2f1d;
color: var(--warn);
}
-.why span {
- color: var(--accent);
- font-size: 11px;
- text-transform: uppercase;
-}
-
.empty,
.error {
color: var(--muted);