prism-viz-engine 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# prism-viz-engine
+
+**The canvas is the instrument.** A diagramming engine where every box on screen is a real
+module file that opens — not a picture of a system, the system drawing itself.
+
+Built for the [Griot Creative Suite](https://github.com/TheDigitalGriot). One engine, mounted
+by many surfaces, so Kweli, Djeli, Prism and Synaptiq share a renderer instead of drifting
+three copies of one.
+
+```bash
+npm install prism-viz-engine
+```
+
+React 18 is a **peer dependency** — the host supplies it, the engine never bundles a second copy.
+
+---
+
+## The four layers
+
+| layer | what it does | entry |
+|---|---|---|
+| **01 · generate** | authors archify-shaped IR, gated by archify's own validator plus a grounding rule | `src/layers/01-generate/archify-ir.ts` |
+| **wire** | **JSON Canvas** — the neutral format between generators and canvases | `src/core/json-canvas.ts` |
+| **02 · render** | two renderers chosen by *what is being drawn*, never by a toggle | `src/layers/02-render/route.ts` |
+| **03 · substrate** | harvest adapter over the live code graph | `src/layers/03-substrate/harvest-adapter.ts` |
+| **04 · shell** | the Waku shell where every box opens its source | `src/layers/04-shell/Shell.tsx` |
+
+The wire format is real [JSON Canvas](https://jsoncanvas.org) — the same file opens in Obsidian.
+
+---
+
+## Mount it
+
+**Standalone**
+
+```bash
+npm run dev          # vite + the reveal sidecar
+```
+
+**Composed into a host app**
+
+```ts
+import { mountVizEngine } from "prism-viz-engine"
+
+const handle = mountVizEngine({
+  element: document.getElementById("canvas")!,
+  canvas: myJsonCanvas,
+})
+```
+
+**Data only — no React, no xyflow in your bundle**
+
+```ts
+import { validate, emptyCanvas } from "prism-viz-engine/json-canvas"
+import { LAYER_ROLES, isLayerRole } from "prism-viz-engine/layer-roles"
+```
+
+---
+
+## The eleven layer roles
+
+The output taxonomy every placed node is routed to. Copied byte-verbatim from the Griot Stack
+`LNAME` array — middle dots and all, because the emitter, the canvas and the plan all key on
+exact string equality.
+
+```
+Djeli · container          Collaboration · GenTeam     Creation · build/content/3D
+Capture                    Intelligence · Super Agent  Governance · Governor
+Model-making / data science  Memory · foundation       Deployment
+Suite meta                 Cross-cutting rails
+```
+
+A finding that fits no role is flagged `unplaceable` — **never force-fit into a twelfth**.
+An unfilled layer is reported as unfilled; no source is ever invented to fill it.
+
+---
+
+## Emit a static screen
+
+Writes a self-contained HTML canvas — no vite, no sidecar, no external references — that any
+watcher-based panel can serve.
+
+```bash
+node scripts/emit-screen.mjs --in <canvas.json> --title "..."
+node scripts/emit-screen.mjs --self
+```
+
+The trade is stated rather than hidden: a static screen has **no reveal-to-source**, because
+nothing is listening. Layout, lanes, layer colour and the `file:line` on every card all travel.
+
+---
+
+## Honest seams
+
+Declared, not disguised:
+
+- `prism-graph` and Excalidraw renderers are **named in the router but unbuilt** — the router
+  reports what it fell back to rather than pretending.
+- `loadFromKuzu` **throws** rather than returning invented rows.
+- **Reading Depth** (zoom-linked level of detail) is fully specified and not yet applied.
+
+## Licence
+
+MIT

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "prism-viz-engine",
+  "version": "0.1.0",
+  "description": "prism-viz-engine — the assembled cluster, built. Layer 01 generate -> JSON Canvas wire -> layer 02 render (xyflow) -> layer 03 substrate (Kuzu) -> layer 04 interactive shell (Waku click-any-box). Mounts standalone, composed into another app, or inside the Djeli container.",
+  "license": "MIT",
+  "author": "digitalgriot",
+  "homepage": "https://github.com/TheDigitalGriot/prism/tree/main/apps/prism-viz-engine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheDigitalGriot/prism.git",
+    "directory": "apps/prism-viz-engine"
+  },
+  "keywords": [
+    "diagram",
+    "visualization",
+    "json-canvas",
+    "isometric",
+    "xyflow",
+    "architecture-diagram",
+    "griot"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./mount": "./src/core/mount.ts",
+    "./json-canvas": "./src/core/json-canvas.ts",
+    "./layer-roles": "./src/core/layer-roles.ts",
+    "./motion": "./src/core/motion.ts"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "concurrently -k -n reveal,vite -c magenta,cyan \"node server/reveal-server.mjs\" \"vite\"",
+    "dev:web": "vite",
+    "dev:reveal": "node server/reveal-server.mjs",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "emit-screen": "node scripts/emit-screen.mjs"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "dependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@isoflow/isopacks": "^0.0.10",
+    "@mui/icons-material": "^5.18.0",
+    "@mui/material": "^5.18.0",
+    "@xyflow/react": "^12.3.5",
+    "auto-bind": "^5.0.1",
+    "chroma-js": "^2.6.0",
+    "dom-to-image": "^2.6.0",
+    "file-saver": "^2.0.5",
+    "gsap": "^3.15.0",
+    "immer": "^10.2.0",
+    "mui-color-input": "^2.0.3",
+    "paper": "^0.12.18",
+    "pathfinding": "^0.4.18",
+    "react-hook-form": "^7.87.0",
+    "react-quill": "^2.0.0",
+    "react-router-dom": "^6.30.6",
+    "uuid": "^9.0.1",
+    "zod": "^3.25.76",
+    "zustand": "^4.3.3"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.3",
+    "concurrently": "^9.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11"
+  }
+}

package/scripts/emit-screen.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * emit-screen.mjs — the engine as a brainstorm panel.
+ *
+ * Gavin's read, and it closes the loop: prism-viz-engine should be dogfooded by the
+ * brainstorm companion exactly the way Gavel and the workgraph panels are. The mechanism
+ * already exists and needed nothing new —
+ *
+ *   server.cjs:76   CONTENT_DIR = <BRAINSTORM_DIR>/content   (watched; a new file is a
+ *                                                             new screen)
+ *   server.cjs:82   CHANNEL_PORT = 52342                      (the same channel drive()
+ *                                                             already targets)
+ *   isFullDocument() — a fragment gets wrapped in frame-template.html; a full document is
+ *                      served as-is. Both get helper.js and the channel meta injected.
+ *
+ * So a screen is a file. This writes one: a canvas, self-contained, that the companion
+ * serves and whose nodes can wake the agent through the channel it is already wired to.
+ *
+ * WHY A SCREEN AND NOT AN IFRAME OF THE APP. A brainstorm screen has to survive on its
+ * own — no vite, no sidecar, no dev server. So this emits a STATIC render of the canvas
+ * document rather than a pointer at a running one. The trade is real and stated: no
+ * reveal-to-source, because nothing is listening. Everything else — layout, lanes, layer
+ * colour, file:line on every card — travels.
+ *
+ * Usage:
+ *   node emit-screen.mjs --in <canvas.json> [--title "..."] [--out <dir>]
+ *   node emit-screen.mjs --self                         # the engine's own document
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs"
+import { join, resolve, basename } from "node:path"
+
+const argv = process.argv.slice(2)
+const flag = (n) => argv.includes(n)
+const opt = (n) => { const i = argv.indexOf(n); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null }
+
+const PRISM_ROOT = resolve(process.env.PRISM_ROOT ?? join(import.meta.dirname, "..", "..", ".."))
+/** server.cjs:76 — the companion watches <BRAINSTORM_DIR>/content. */
+const BRAINSTORM_DIR = process.env.BRAINSTORM_DIR ?? "/tmp/prism-brainstorm"
+const CONTENT_DIR = opt("--out") ?? join(BRAINSTORM_DIR, "content")
+
+const LAYER_ROLES = [
+  "Djeli · container", "Collaboration · GenTeam", "Creation · build/content/3D",
+  "Capture", "Intelligence · Super Agent", "Governance · Governor",
+  "Model-making / data science", "Memory · foundation", "Deployment",
+  "Suite meta", "Cross-cutting rails",
+]
+const EMBER = {
+  "Djeli · container": "#e0a458", "Collaboration · GenTeam": "#9b8cf0",
+  "Creation · build/content/3D": "#f2915f", Capture: "#4fd0e0",
+  "Intelligence · Super Agent": "#e85d3a", "Governance · Governor": "#d4af37",
+  "Model-making / data science": "#e0a458", "Memory · foundation": "#7c7cf0",
+  Deployment: "#9a8c98", "Suite meta": "#e0a458", "Cross-cutting rails": "#d4af37",
+  unplaceable: "#6b7385",
+}
+
+const inPath = opt("--in")
+let canvas
+let title = opt("--title")
+
+if (flag("--self")) {
+  const p = join(PRISM_ROOT, ".prism", "shared", "workgraph", "uxui-canvas-nodes.json")
+  if (!existsSync(p)) {
+    console.error(`emit-screen: --self needs ${p}. Run a harvest first; nothing is invented here.`)
+    process.exit(1)
+  }
+  const nodes = JSON.parse(readFileSync(p, "utf-8"))
+  canvas = {
+    // The emitter's own shape carries `layer` at top level and the rest under `data`;
+    // lifting it is what the lane layout keys on. Missing it silently collapsed every
+    // node into `unplaceable` and reported 1/11 layers — a wrong picture that still
+    // rendered, which is the failure mode this engine exists to catch.
+    nodes: nodes.map((n) => ({
+      ...n,
+      x: n.position?.x ?? 0,
+      y: n.position?.y ?? 0,
+      width: 232,
+      height: 96,
+      griot: { ...n.data, layer: n.layer, ui: { origin: { ...n.data.origin, repo: n.data.provenance?.repo } } },
+    })),
+    edges: nodes.filter((n) => n.data?.parentId).map((n) => ({ id: `${n.data.parentId}->${n.id}`, fromNode: n.data.parentId, toNode: n.id })),
+  }
+  title ??= "Harvested components"
+} else if (inPath) {
+  if (!existsSync(inPath)) { console.error(`emit-screen: --in not found: ${inPath}`); process.exit(1) }
+  canvas = JSON.parse(readFileSync(inPath, "utf-8"))
+  title ??= basename(inPath).replace(/\.(canvas\.)?json$/i, "")
+} else {
+  console.error("Usage: node emit-screen.mjs --in <canvas.json> [--title ...] | --self")
+  process.exit(1)
+}
+
+const nodes = (canvas.nodes ?? []).filter((n) => n.griot)
+if (!nodes.length) { console.error("emit-screen: no Griot nodes to draw — refusing to emit an empty screen."); process.exit(1) }
+
+const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]))
+const LANE_H = 168, RAIL = 210, CARD_W = 232, CARD_H = 96
+
+// Lay out by lane, same rule as the canvas: the band a node sits in IS its layer role.
+const laneIdx = (l) => Math.max(0, LAYER_ROLES.indexOf(l))
+const packed = new Map()
+const placed = nodes.map((n) => {
+  const layer = LAYER_ROLES.includes(n.griot.layer) ? n.griot.layer : "unplaceable"
+  const key = layer
+  const i = packed.get(key) ?? 0
+  packed.set(key, i + 1)
+  return { n, layer, x: RAIL + 24 + i * (CARD_W + 18), y: laneIdx(layer) * LANE_H + 26 }
+})
+const W = RAIL + 24 + Math.max(1, ...[...packed.values()]) * (CARD_W + 18) + 24
+const H = LAYER_ROLES.length * LANE_H
+
+const byId = new Map(placed.map((p) => [p.n.id, p]))
+const edges = (canvas.edges ?? []).filter((e) => byId.has(e.fromNode) && byId.has(e.toNode))
+
+const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>${esc(title)} · prism-viz-engine</title>
+<style>
+:root{--void:#0a0a0c;--panel:#101418;--panel2:#0d1116;--line:rgba(255,255,255,.08);
+ --line2:rgba(255,255,255,.14);--ink:#e8ecf2;--mute:#9aa3b2;--dim:#6b7385;--mint:#10ffba;
+ --mono:"JetBrains Mono","SF Mono",ui-monospace,Consolas,monospace;
+ --sans:Inter,-apple-system,"Segoe UI",Roboto,sans-serif}
+*{box-sizing:border-box}body{margin:0;background:var(--void);color:var(--ink);font-family:var(--sans)}
+.hd{padding:14px 18px;border-bottom:1px solid var(--line);background:var(--panel);
+ display:flex;align-items:baseline;gap:12px;flex-wrap:wrap}
+.hd h1{font-size:15px;margin:0;font-weight:650}
+.hd .m{font-family:var(--mono);font-size:11px;color:var(--mute)}
+.wrap{overflow:auto}
+.stage{position:relative;width:${W}px;height:${H}px;
+ background-image:radial-gradient(#1a1f26 1px,transparent 1px);background-size:22px 22px}
+.lane{position:absolute;left:0;width:${W}px;border-bottom:1px dashed var(--line)}
+.lane-hd{position:absolute;left:0;top:0;bottom:0;width:${RAIL}px;padding:10px 12px;
+ display:flex;flex-direction:column;justify-content:center;gap:3px;
+ border-right:1px solid var(--line);background:var(--panel2)}
+.lane-nm{font-size:11.5px;font-weight:600;line-height:1.25}
+.lane-nm::before{content:"";display:inline-block;width:3px;height:11px;border-radius:2px;
+ background:var(--e);margin-right:7px;vertical-align:-1px}
+.nd{position:absolute;width:${CARD_W}px;border:1px solid var(--line2);border-left:3px solid var(--e);
+ background:var(--panel);border-radius:9px;padding:8px 10px;display:flex;flex-direction:column;gap:3px;
+ box-shadow:0 2px 6px rgba(0,0,0,.35)}
+.rp{font-family:var(--mono);font-size:8.5px;text-transform:uppercase;letter-spacing:.06em;
+ color:var(--mute);font-weight:700}
+.ty{font-family:var(--mono);font-size:8px;text-transform:uppercase;color:var(--dim);
+ border:1px solid var(--line);border-radius:3px;padding:0 4px}
+.lb{font-size:12px;font-weight:560;line-height:1.3}
+.sr{font-family:var(--mono);font-size:9px;color:var(--dim);overflow:hidden;
+ text-overflow:ellipsis;white-space:nowrap}
+.lic{font-family:var(--mono);font-size:9px;color:#f59e0b}
+svg.ed{position:absolute;inset:0;width:${W}px;height:${H}px;pointer-events:none}
+svg.ed path{fill:none;stroke:var(--dim);stroke-width:1.5;opacity:.55}
+.ft{padding:10px 18px;border-top:1px solid var(--line);font-family:var(--mono);
+ font-size:10.5px;color:var(--dim);display:flex;gap:20px;flex-wrap:wrap}
+</style></head><body>
+<div class="hd"><h1>${esc(title)}</h1>
+<span class="m">${placed.length} nodes · ${edges.length} edges · ${packed.size}/11 layers</span>
+<span class="m" style="color:var(--mint)">prism-viz-engine · static screen</span></div>
+<div class="wrap"><div class="stage">
+${LAYER_ROLES.map((r, i) => `<div class="lane" style="top:${i * LANE_H}px;height:${LANE_H}px;--e:${EMBER[r]}">
+  <div class="lane-hd"><span class="lane-nm">${esc(r)}</span></div></div>`).join("")}
+<svg class="ed">${edges.map((e) => {
+  const a = byId.get(e.fromNode), b = byId.get(e.toNode)
+  const x1 = a.x + CARD_W / 2, y1 = a.y + CARD_H, x2 = b.x + CARD_W / 2, y2 = b.y, m = (y1 + y2) / 2
+  return `<path d="M${x1},${y1} C${x1},${m} ${x2},${m} ${x2},${y2}"/>`
+}).join("")}</svg>
+${placed.map((p) => {
+  const g = p.n.griot, o = g.ui?.origin ?? g.origin ?? {}
+  const repo = o.repo ?? g.provenance?.repo ?? ""
+  return `<div class="nd" style="left:${p.x}px;top:${p.y}px;--e:${EMBER[p.layer]}">
+    <div style="display:flex;align-items:center;gap:6px">
+      ${repo ? `<span class="rp">${esc(repo)}</span>` : ""}
+      <span class="ty">${esc(p.n.type ?? g.walkLevel ?? "node")}</span></div>
+    <div class="lb">${esc(p.n.label ?? p.n.id)}</div>
+    ${o.file ? `<div class="sr">${esc(o.file)}:${esc(o.line ?? "")}</div>` : ""}
+    ${g.code?.licence || g.licence ? `<span class="lic">${esc(g.code?.licence ?? g.licence)}</span>` : ""}
+  </div>`
+}).join("")}
+</div></div>
+<div class="ft">
+  <span>static screen — reveal-to-source needs the sidecar, which is not listening here</span>
+  <span>every card carries the file:line it was read from</span>
+</div>
+</body></html>`
+
+mkdirSync(CONTENT_DIR, { recursive: true })
+const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")
+const out = join(CONTENT_DIR, `viz-${slug}.html`)
+writeFileSync(out, html, "utf-8")
+
+console.log(`emit-screen: ${placed.length} nodes · ${edges.length} edges · ${packed.size}/11 layers`)
+console.log(`  wrote  ${out}`)
+console.log(`  The brainstorm companion watches this directory — it will appear as a screen.`)
+console.log(`  Channel :52342 is the same one drive() targets, so panel and engine share it.`)

package/src/core/json-canvas.ts

@@ -0,0 +1,301 @@
+/**
+ * JSON Canvas — the neutral wire between layer 01 (generate) and layer 02 (canvas).
+ *
+ * The shelf card for `obsidianmd/jsoncanvas` states its own job and this file just
+ * honours it: "An interchange FORMAT, not a renderer: the neutral wire between the viz
+ * engine's generators (layer 01) and its canvases (layer 02)." Spec v1.0 — nodes
+ * (text/file/link/group) + edges, z-order by array position.
+ *
+ * WHY A WIRE AND NOT A DIRECT COUPLING. Layer 01 has four generators (archify, Diagram
+ * Design, Lanshu, visual-explainer) and layer 02 has three canvases (xyflow,
+ * react-force-graph, Excalidraw). Wiring 4x3 directly is twelve adapters that rot.
+ * Wiring both sides to one format is seven.
+ *
+ * CORRECTION (2026-09-11, harvest of cclank/lanshu-animated-architecture-diagram).
+ * An earlier revision of this comment claimed Lanshu "already emits .excalidraw, which
+ * is the same move one step down the stack." That was repeating a shelf blurb, and the
+ * harvest killed it: Lanshu has NO node/edge graph. Its spec is a content-slot fill-in
+ * form for one hardcoded picture -- every coordinate is a source literal in
+ * render_static() (scripts/render_animated_diagram.py:456-554), there is no id/x/y/w/h,
+ * and arrows carry startBinding/endBinding = None (:263-264), so 0 of 14 arrows are
+ * bound to anything. It serialises ink, not a model, and therefore does not demonstrate
+ * this seam at all.
+ *
+ * What IS liftable from it is narrower and real: the `Excal` writer class
+ * (:176-280, 105 lines) -- the element-envelope + id/seed/version discipline an
+ * .excalidraw consumer requires. That belongs in a layer-02 Excalidraw exporter, not
+ * here. Full grounding: .prism/shared/research/2026-09-11-lanshu.md
+ *
+ * The Griot additions live under `griot` on each node, never in the spec fields, so a
+ * plain JSON Canvas reader (Obsidian, any spec-compliant tool) still opens our files.
+ */
+
+import { type LayerSlot, isLayerSlot, UNPLACEABLE, ALL_SLOTS } from "./layer-roles"
+
+// ── the spec (v1.0) ────────────────────────────────────────────────────────────
+export type CanvasNodeType = "text" | "file" | "link" | "group"
+
+export interface CanvasNodeBase {
+  id: string
+  type: CanvasNodeType
+  x: number
+  y: number
+  width: number
+  height: number
+  color?: string
+  /** Griot extension — ignored by spec-compliant readers, load-bearing for us. */
+  griot?: GriotNodeMeta
+}
+
+export interface CanvasTextNode extends CanvasNodeBase {
+  type: "text"
+  text: string
+}
+export interface CanvasFileNode extends CanvasNodeBase {
+  type: "file"
+  file: string
+  subpath?: string
+}
+export interface CanvasLinkNode extends CanvasNodeBase {
+  type: "link"
+  url: string
+}
+export interface CanvasGroupNode extends CanvasNodeBase {
+  type: "group"
+  label?: string
+  background?: string
+  backgroundStyle?: "cover" | "ratio" | "repeat"
+}
+
+export type CanvasNode = CanvasTextNode | CanvasFileNode | CanvasLinkNode | CanvasGroupNode
+
+export type CanvasSide = "top" | "right" | "bottom" | "left"
+export interface CanvasEdge {
+  id: string
+  fromNode: string
+  fromSide?: CanvasSide
+  toNode: string
+  toSide?: CanvasSide
+  color?: string
+  label?: string
+}
+
+export interface JSONCanvas {
+  nodes: CanvasNode[]
+  edges: CanvasEdge[]
+}
+
+// ── the Griot extension ────────────────────────────────────────────────────────
+/**
+ * Both harvest modes land here, on ONE node. That is the whole point of the two-mode
+ * split: `griot-harvest` supplies the code half (what it does, features, fit verdict,
+ * licence) and `griot-harvest-ux-ui` supplies the UI half (screen, flow, mount point).
+ * UX is functionality — a decision about the future of the tooling needs both, fused,
+ * on the same object.
+ */
+export interface GriotNodeMeta {
+  /** One of the eleven verbatim roles, or `unplaceable`. Never a twelfth. */
+  layer: LayerSlot
+  /** component | screen | flow | workflow — the UI-walk rung this finding reached. */
+  walkLevel?: "component" | "screen" | "flow" | "workflow"
+
+  /** ── the UI half (griot-harvest-ux-ui) ───────────────────────────────── */
+  ui?: {
+    /** The evidence. A node without file:line is rejected, never defaulted. */
+    origin: { repo: string; file: string; line: number }
+    /** Render path from app root to this node. */
+    mountPoint: string
+    /** UX antipatterns — what NOT to copy, first-class output. */
+    notCopy?: string[]
+    /** Captured render of the real component, if one exists. Never a mock. */
+    preview?: { kind: "screenshot" | "iframe" | "none"; src?: string }
+  }
+
+  /** ── the code half (griot-harvest) ───────────────────────────────────── */
+  code?: {
+    /** What it does, in the tool's own terms. */
+    capability?: string
+    features?: string[]
+    /** griot-harvest's fit verdict against a Griot app. */
+    fit?: { app: string; strength: 1 | 2 | 3; why: string }
+    /** A FACT for a field, never a verdict. `spdx:<id>` | "none declared". */
+    licence: string
+    /** adopt | trial | defer | pass — mirrors the DGS decision store. */
+    decision?: "adopt" | "trial" | "defer" | "pass" | "undecided"
+    /** scaffold | component | pattern. */
+    role?: "scaffold" | "component" | "pattern"
+    stage?: "now" | "next" | "later"
+  }
+
+  provenance: {
+    harvestedBy: string
+    harvestedAt: string
+    sourceCommit?: string | null
+  }
+}
+
+// ── construction + validation ──────────────────────────────────────────────────
+export const emptyCanvas = (): JSONCanvas => ({ nodes: [], edges: [] })
+
+/**
+ * GRAFTED from archify's validator (`renderers/shared/validator.mjs`, spdx:MIT), harvested
+ * 2026-09-11. Its own comment names the reason this shape exists:
+ *
+ *   validator.mjs:4-5 — "'/nodes/3/label' reads much better as
+ *   '/nodes/3 (id: \"router\") /label' FOR THE LLM FIXING THE JSON; resolve the nearest
+ *   enclosing element's id or label."
+ *
+ * That is the insight worth taking. A gate whose output an agent can act on directly
+ * closes the loop: generator emits -> gate rejects -> the rejection IS the repair
+ * instruction -> generator re-emits. A bare "invalid at nodes[3]" makes the agent guess.
+ *
+ * Two pieces lifted, both reimplemented against OUR schema rather than copied:
+ *   - `identity`  — the nearest enclosing id/label, so a path names a thing not an index
+ *                   (validator.mjs:6-19, `annotatedPath`)
+ *   - `fixes`     — imperative repair strings, one per failure kind
+ *                   (validator.mjs:56-68, `supportedFixes`)
+ *
+ * What we did NOT take: archify drives ajv with five JSON Schema documents and a 421 KB
+ * standalone-compiled `generated-validators.mjs`. Our node shape is small and fixed, so
+ * a schema compiler would be weight without benefit. The diagnostic ergonomics are the
+ * pattern; the validation engine is not.
+ */
+export interface Violation {
+  /** Where it failed — a JSON-pointer-ish path into the canvas. */
+  where: string
+  /** What is wrong. */
+  problem: string
+  /** The nearest enclosing `id` or `label`, so the path names a thing, not an index. */
+  identity?: string | null
+  /** Imperative repair instructions an agent can act on without guessing. */
+  fixes?: string[]
+}
+
+/** Render violations as the repair brief an agent should be handed. */
+export function explainViolations(violations: Violation[]): string {
+  if (!violations.length) return "valid"
+  return violations
+    .map((v) => {
+      const who = v.identity != null ? ` (id/label: ${JSON.stringify(v.identity)})` : ""
+      const how = v.fixes?.length ? `\n      fix: ${v.fixes.join(" | ")}` : ""
+      return `  - ${v.where}${who}: ${v.problem}${how}`
+    })
+    .join("\n")
+}
+
+/**
+ * Gate, don't coerce. Same posture as `emit-canvas-nodes.mjs`: collect every violation,
+ * write nothing on failure. A silently-defaulted `line: 0` is worse than a rejection —
+ * it looks like evidence and isn't.
+ */
+export function validate(canvas: JSONCanvas): Violation[] {
+  const v: Violation[] = []
+  const seen = new Set<string>()
+  /** The archify move: name the thing, not the index. */
+  const idOf = (o: any): string | null => o?.id ?? o?.label ?? null
+
+  for (const [i, n] of canvas.nodes.entries()) {
+    const where = `/nodes/${i}`
+    const identity = idOf(n)
+    const bad = (problem: string, fixes: string[] = []) => v.push({ where, identity, problem, fixes })
+
+    if (!n || typeof n !== "object") {
+      bad("not an object", ["replace with a node object per canvas-node-schema.md"])
+      continue
+    }
+    if (!n.id) bad('missing "id"', ['add a stable kebab-case "id" unique within this canvas'])
+    else if (seen.has(n.id))
+      bad(`duplicate id ${JSON.stringify(n.id)}`, [
+        "give one of the two a distinct id — merge is keyed on id, so a duplicate silently overwrites",
+      ])
+    else seen.add(n.id)
+
+    for (const k of ["x", "y", "width", "height"] as const) {
+      if (typeof n[k] !== "number")
+        bad(`"${k}" must be a number, got ${JSON.stringify((n as any)[k])}`, [
+          `set "${k}" to a number`,
+        ])
+    }
+
+    const g = n.griot
+    if (!g) continue // a plain spec node is legal; only Griot nodes carry our gates
+
+    if (!isLayerSlot(g.layer))
+      bad(
+        `"griot.layer" must be one of the eleven verbatim roles or "${UNPLACEABLE}", got ${JSON.stringify(g.layer)}`,
+        [`choose one of ${JSON.stringify([...ALL_SLOTS])}`, "copy the string byte-verbatim, middle dots included"]
+      )
+    if (!g.provenance?.harvestedBy)
+      bad('missing "griot.provenance.harvestedBy"', [
+        'set "griot.provenance.harvestedBy" to the skill or agent that produced this node',
+      ])
+
+    if (g.ui) {
+      if (!g.ui.origin?.file)
+        bad('missing "griot.ui.origin.file"', ['set "griot.ui.origin.file" to a repo-relative path'])
+      if (typeof g.ui.origin?.line !== "number")
+        bad('missing "griot.ui.origin.line" — every finding needs file:line', [
+          'set "griot.ui.origin.line" to the line the claim was read from — do not default it to 0',
+        ])
+      if (!g.ui.mountPoint)
+        bad('missing "griot.ui.mountPoint"', [
+          'set "griot.ui.mountPoint" to the render path from app root to this node',
+        ])
+    }
+    if (g.code && typeof g.code.licence !== "string")
+      bad('missing "griot.code.licence"', [
+        'set "griot.code.licence" to "spdx:<id>" or "none declared" — a fact for a field, never omitted, never a verdict',
+      ])
+    if (!g.ui && !g.code)
+      bad("a Griot node carries neither harvest half — nothing to place", [
+        'add "griot.ui" (the UX/UI walk) or "griot.code" (the harvest) — a node needs at least one',
+      ])
+  }
+
+  const ids = new Set(canvas.nodes.map((n) => n.id))
+  for (const [i, e] of canvas.edges.entries()) {
+    const where = `/edges/${i}`
+    const identity = idOf(e)
+    const bad = (problem: string, fixes: string[] = []) => v.push({ where, identity, problem, fixes })
+
+    if (!e.id) bad('missing "id"', ['add an "id" — merge is keyed on it'])
+    if (!ids.has(e.fromNode))
+      bad(`fromNode ${JSON.stringify(e.fromNode)} is not a node in this canvas`, [
+        "point fromNode at an existing node id, or add the missing node",
+      ])
+    if (!ids.has(e.toNode))
+      bad(`toNode ${JSON.stringify(e.toNode)} is not a node in this canvas`, [
+        "point toNode at an existing node id, or add the missing node",
+      ])
+    for (const k of ["fromSide", "toSide"] as const) {
+      const s = e[k]
+      if (s !== undefined && !["top", "right", "bottom", "left"].includes(s))
+        bad(`"${k}" must be a side, got ${JSON.stringify(s)}`, [
+          'choose one of ["top","right","bottom","left"]',
+        ])
+    }
+  }
+  return v
+}
+
+export function assertValid(canvas: JSONCanvas): JSONCanvas {
+  const v = validate(canvas)
+  if (v.length) {
+    throw new Error(
+      `json-canvas: ${v.length} violation(s), nothing written.\n` +
+        v.map((x) => `  - ${x.where}: ${x.problem}`).join("\n")
+    )
+  }
+  return canvas
+}
+
+/** Merge by id — re-running a walk updates in place, never duplicates. */
+export function merge(base: JSONCanvas, incoming: JSONCanvas): JSONCanvas {
+  const nodes = new Map(base.nodes.map((n) => [n.id, n]))
+  for (const n of incoming.nodes) nodes.set(n.id, n)
+  const edges = new Map(base.edges.map((e) => [e.id, e]))
+  for (const e of incoming.edges) edges.set(e.id, e)
+  return { nodes: [...nodes.values()], edges: [...edges.values()] }
+}
+
+export const serialize = (c: JSONCanvas) => JSON.stringify(c, null, 2) + "\n"