prism-viz-engine 0.1.0

package/src/layers/01-generate/archify-ir.ts

@@ -0,0 +1,234 @@
+/**
+ * Layer 01 — archify IR → JSON Canvas.
+ *
+ * GROUNDED, not recalled. Every field below was read out of the real schemas in
+ * `GriotSandbox/viz-generate/archify/archify/schemas/` on 2026-09-11. Full harvest:
+ * `.prism/shared/research/2026-09-11-archify.md`.
+ *
+ * WHY ARCHIFY IS THE GRAFT AND LANSHU WAS NOT
+ * -------------------------------------------
+ * Both were shelved as layer-01 generators. Only one has an IR.
+ *
+ *   Lanshu  — no node/edge graph at all. A content-slot form for one hardcoded picture;
+ *             every coordinate is a source literal, arrows carry startBinding = None.
+ *             It serialises ink, not a model. (research/2026-09-11-lanshu.md)
+ *   archify — `package.json:6` calls the package "JSON-IR diagram renderers". Five JSON
+ *             Schema draft-2020-12 documents; NL never reaches a renderer, the model
+ *             reads SKILL.md and emits IR. There is no parser and no prompt engine.
+ *
+ * And the IR is already positional, which is the part that makes this nearly free:
+ *
+ *   archify                                          JSON Canvas
+ *   ───────────────────────────────────────────────  ──────────────────────────────
+ *   component.pos      [x, y]   (:117 -> $defs/point) node.x / node.y
+ *   component.size     [w, h]   (:118-125)            node.width / node.height
+ *   connection.fromSide/toSide  (:161-162)            edge.fromSide / edge.toSide
+ *   common $defs.side  enum                           CanvasSide
+ *     ["left","right","top","bottom"]  (:22-24)         "top"|"right"|"bottom"|"left"
+ *
+ * The side enum is the SAME SET. Not similar — the same four strings. So edge anchoring
+ * survives the conversion untouched, which is the single thing that usually doesn't.
+ *
+ * CORRECTIONS carried from the harvest, so nobody re-learns them here:
+ *  - "single-file, zero-dep" is half wrong: zero RUNTIME deps is real (no `dependencies`
+ *    key), but the repo is 513 files and ajv is standalone-compiled into committed
+ *    source (`generated-validators.mjs`, 421 KB). Zero-dep is an artefact of the build.
+ *  - the top-level arrays are `components` and `connections` — NOT `nodes`/`edges`.
+ *  - layout is mostly authored, not solved: `grid.mjs:1` says "Not auto-layout — fixed
+ *    cell math only." Only workflow v2 has a solver, and it solves X only. So when a
+ *    component gives `row`/`col` instead of `pos`, WE do the cell math here, from the
+ *    IR's own `layout` block — we do not invent a layout engine.
+ *  - licence, as a fact: `spdx:MIT`, two holders (tt-a1i 2026; Cocoon AI 2025) — archify
+ *    is itself derived from `Cocoon-AI/architecture-diagram-generator`.
+ */
+
+import type { JSONCanvas, CanvasNode, CanvasEdge, CanvasSide } from "../../core/json-canvas"
+
+// ── the IR, transcribed from the schemas ───────────────────────────────────────
+/** `common.schema.json:22-24` — identical set to CanvasSide. */
+export type ArchifySide = "left" | "right" | "top" | "bottom"
+/** `common.schema.json $defs.point` — a fixed 2-tuple, `items:false`. */
+export type ArchifyPoint = [number, number]
+
+/** `architecture.schema.json:85` — required `id`, `type`, `label`. */
+export interface ArchifyComponent {
+  id: string
+  type: string
+  label: string
+  sublabel?: string
+  tag?: string
+  brand?: string
+  sources?: unknown
+  row?: number
+  col?: number
+  pos?: ArchifyPoint
+  size?: ArchifyPoint
+}
+
+/** `architecture.schema.json:149` — required `from`, `to`. */
+export interface ArchifyConnection {
+  id?: string
+  from: string
+  to: string
+  label?: string
+  variant?: string
+  fromSide?: ArchifySide
+  toSide?: ArchifySide
+  route?: "auto" | "straight" | "orthogonal-h" | "orthogonal-v"
+  via?: ArchifyPoint[]
+  labelAt?: ArchifyPoint
+  labelDx?: number
+  labelDy?: number
+  labelSegment?: number
+  width?: number
+}
+
+/** Required `kind`, `label`, `wraps` — `wraps` is a list of component ids. */
+export interface ArchifyBoundary {
+  kind: string
+  label: string
+  wraps: string[]
+  pad?: number
+}
+
+/** Required `mode`. The cell math we apply when a component has no `pos`. */
+export interface ArchifyLayout {
+  mode: string
+  origin?: ArchifyPoint
+  cols?: number
+  gapX?: number
+  gapY?: number
+  cellW?: number
+  cellH?: number
+}
+
+/** `architecture.schema.json:7` — required `schema_version`, `diagram_type`, `meta`, `components`. */
+export interface ArchifyIR {
+  schema_version: string | number
+  diagram_type: string
+  meta: Record<string, unknown>
+  layout?: ArchifyLayout
+  components: ArchifyComponent[]
+  boundaries?: ArchifyBoundary[]
+  connections?: ArchifyConnection[]
+  cards?: unknown
+}
+
+// ── defaults, named so they are obviously ours and not archify's ───────────────
+const FALLBACK = { cellW: 180, cellH: 96, gapX: 40, gapY: 40, origin: [0, 0] as ArchifyPoint }
+
+/**
+ * `grid.mjs:1` — "Not auto-layout — fixed cell math only." We reproduce exactly that:
+ * row/col times cell plus gap, offset by origin. We do NOT substitute dagre or a force
+ * pass, because that would silently move authored diagrams.
+ */
+function placeFromGrid(c: ArchifyComponent, L: ArchifyLayout | undefined) {
+  const cellW = L?.cellW ?? FALLBACK.cellW
+  const cellH = L?.cellH ?? FALLBACK.cellH
+  const gapX = L?.gapX ?? FALLBACK.gapX
+  const gapY = L?.gapY ?? FALLBACK.gapY
+  const [ox, oy] = L?.origin ?? FALLBACK.origin
+  return {
+    x: ox + (c.col ?? 0) * (cellW + gapX),
+    y: oy + (c.row ?? 0) * (cellH + gapY),
+    width: cellW,
+    height: cellH,
+  }
+}
+
+export interface AdaptOptions {
+  /** Stamped onto every emitted node so provenance survives the conversion. */
+  harvestedBy?: string
+  harvestedAt?: string
+}
+
+/**
+ * The conversion. Positional fields pass through; grid-placed components get the IR's
+ * own cell math; boundaries become JSON Canvas `group` nodes sized to their members.
+ *
+ * Anything archify carries that JSON Canvas has no home for — `route`, `via`, `labelAt`,
+ * `variant`, `width`, `sublabel`, `tag`, `brand` — is preserved under `griot.code` /
+ * node extras rather than dropped, so a round trip back to archify stays possible.
+ */
+export function archifyToCanvas(ir: ArchifyIR, opts: AdaptOptions = {}): JSONCanvas {
+  const nodes: CanvasNode[] = []
+  const edges: CanvasEdge[] = []
+  const box = new Map<string, { x: number; y: number; width: number; height: number }>()
+
+  for (const c of ir.components) {
+    const geom = c.pos
+      ? {
+          x: c.pos[0],
+          y: c.pos[1],
+          width: c.size?.[0] ?? FALLBACK.cellW,
+          height: c.size?.[1] ?? FALLBACK.cellH,
+        }
+      : placeFromGrid(c, ir.layout)
+
+    box.set(c.id, geom)
+    const node = {
+      id: c.id,
+      type: "text",
+      text: c.sublabel ? `${c.label}\n${c.sublabel}` : c.label,
+      ...geom,
+      griot: {
+        layer: "unplaceable" as const, // routed by a human on the canvas, never guessed here
+        provenance: {
+          harvestedBy: opts.harvestedBy ?? "archify-ir",
+          harvestedAt: opts.harvestedAt ?? new Date().toISOString().slice(0, 10),
+        },
+        code: { licence: "spdx:MIT", capability: c.type },
+      },
+    } as unknown as CanvasNode
+    // keep the archify-only fields so the round trip is lossless
+    ;(node as any).archify = { type: c.type, tag: c.tag, brand: c.brand, sublabel: c.sublabel }
+    ;(node as any).label = c.label
+    nodes.push(node)
+  }
+
+  // Boundaries -> group nodes, sized to the bounding box of what they wrap + pad.
+  for (const [i, b] of (ir.boundaries ?? []).entries()) {
+    const members = b.wraps.map((id) => box.get(id)).filter(Boolean) as Array<{
+      x: number
+      y: number
+      width: number
+      height: number
+    }>
+    if (!members.length) continue // a boundary wrapping nothing is dropped, not faked
+    const pad = b.pad ?? 16
+    const minX = Math.min(...members.map((m) => m.x)) - pad
+    const minY = Math.min(...members.map((m) => m.y)) - pad
+    const maxX = Math.max(...members.map((m) => m.x + m.width)) + pad
+    const maxY = Math.max(...members.map((m) => m.y + m.height)) + pad
+    const group = {
+      id: `boundary-${i}-${b.kind}`,
+      type: "group",
+      label: b.label,
+      x: minX,
+      y: minY,
+      width: maxX - minX,
+      height: maxY - minY,
+    } as CanvasNode
+    // `kind` (region | security-group | …) is archify's own topology declaration. An
+    // earlier pass kept only `label` and the router then had to guess from prose — which
+    // is how a real deployment diagram scored as an app architecture.
+    ;(group as any).archify = { kind: b.kind, wraps: b.wraps }
+    nodes.unshift(group)
+  }
+
+  // Connections -> edges. fromSide/toSide pass through UNTRANSLATED — same enum.
+  for (const [i, c] of (ir.connections ?? []).entries()) {
+    const edge: CanvasEdge = {
+      id: c.id ?? `${c.from}->${c.to}-${i}`,
+      fromNode: c.from,
+      toNode: c.to,
+      ...(c.fromSide ? { fromSide: c.fromSide as CanvasSide } : {}),
+      ...(c.toSide ? { toSide: c.toSide as CanvasSide } : {}),
+      ...(c.label ? { label: c.label } : {}),
+    }
+    ;(edge as any).archify = { route: c.route, via: c.via, variant: c.variant, width: c.width }
+    edges.push(edge)
+  }
+
+  return { nodes, edges }
+}

package/src/layers/02-render/Canvas.tsx

@@ -0,0 +1,211 @@
+/**
+ * Layer 02 — the canvas. xyflow, because the decision was already made.
+ *
+ * The djeli-uxui-harvest stage contract, decision 4: "CANVAS is xyflow (layer 02)
+ * because nodes are a plain JSON array an agent reads and writes directly, with no
+ * canvas-widget indirection." The shelf agrees — xyflow is "the node-graph engine under
+ * Langflow/Flowise", MIT, Fragment's visual-builder base.
+ *
+ * The load-bearing word in that decision is WRITES. So this canvas is not a rendering
+ * of a harvest, it is the instrument that edits one:
+ *
+ *   - drag a card in from the palette      -> a component is placed
+ *   - drag a node across a lane            -> its layer role is REASSIGNED
+ *   - drag handle to handle                -> an edge is written
+ *   - every mutation calls onChange        -> the host persists; the engine never writes
+ *
+ * Lanes are the eleven verbatim roles, drawn as background bands. Dropping into a band
+ * IS the routing act — which is why the routing view and the editing view are the same
+ * screen rather than a table you read and a canvas you look at.
+ */
+
+import { useCallback, useMemo, useRef } from "react"
+import {
+  ReactFlow,
+  Background,
+  BackgroundVariant,
+  Controls,
+  MiniMap,
+  ReactFlowProvider,
+  ViewportPortal,
+  useReactFlow,
+  useViewport,
+  applyNodeChanges,
+  applyEdgeChanges,
+  addEdge,
+  type Node,
+  type Edge,
+  type NodeChange,
+  type EdgeChange,
+  type Connection,
+  type ReactFlowInstance,
+  type OnNodeDrag,
+} from "@xyflow/react"
+import "@xyflow/react/dist/style.css"
+
+import { ComponentNode, type ComponentNodeData } from "./ComponentNode"
+import { ALL_SLOTS, ROLE_EMBER, ROLE_EQUIV, type LayerSlot } from "../../core/layer-roles"
+
+export const LANE_H = 168
+
+const nodeTypes = { griot: ComponentNode }
+
+export interface CanvasProps {
+  nodes: Node<ComponentNodeData>[]
+  edges: Edge[]
+  onNodesChange: (c: NodeChange[]) => void
+  onEdgesChange: (c: EdgeChange[]) => void
+  onConnect: (c: Connection) => void
+  /** Fired when a node's y puts it in a different lane — the re-route. */
+  onReroute: (nodeId: string, layer: LayerSlot) => void
+  /** Fired when a palette card is dropped onto the canvas. */
+  onDropComponent: (payload: string, position: { x: number; y: number }, layer: LayerSlot) => void
+  onSelect: (nodeId: string | null) => void
+}
+
+export const laneOf = (y: number): LayerSlot =>
+  ALL_SLOTS[Math.max(0, Math.min(ALL_SLOTS.length - 1, Math.floor(y / LANE_H)))]
+
+/**
+ * The lanes live in FLOW space, not screen space.
+ *
+ * They were rendered as a plain child of <ReactFlow>, which put them in the viewport's
+ * own coordinates — so the graph panned and zoomed underneath them and the labels
+ * stopped describing the rows they sat on. A lane that does not move with its nodes is
+ * worse than no lane: it asserts a role for whatever happens to be under it.
+ *
+ * <ViewportPortal> renders into the transformed pane, so a lane is pinned to the same
+ * coordinates as the nodes it contains and survives any camera move.
+ */
+function LaneBands({ width }: { width: number }) {
+  return (
+    <ViewportPortal>
+      {ALL_SLOTS.map((role, i) => (
+        <div
+          key={role}
+          className="vz-lane"
+          style={{ top: i * LANE_H, height: LANE_H, width, ["--ember" as string]: ROLE_EMBER[role] }}
+        />
+      ))}
+    </ViewportPortal>
+  )
+}
+
+/**
+ * The label rail — screen space, but tracking the bands.
+ *
+ * Bands belong in flow space or a node drifts out of the role it is sitting in. Labels
+ * do NOT: send them through the same transform and the legend slides off the left edge
+ * the moment you pan right, which is the context loss this is fixing, just rotated 90
+ * degrees.
+ *
+ * So the rail is pinned to the viewport and reads `useViewport()` to place each label at
+ * its band's PROJECTED y. Bands move with the graph; the legend never leaves. Labels
+ * fade out when their band is too short to read at the current zoom rather than
+ * overlapping their neighbours — the same instinct as archify's Reading Depth, where
+ * detail drops out by scale but nothing moves to make room.
+ */
+function LaneRail() {
+  const { y, zoom } = useViewport()
+  const h = LANE_H * zoom
+  const readable = h > 26
+  return (
+    <div className="vz-rail" aria-hidden={!readable}>
+      {ALL_SLOTS.map((role, i) => {
+        const top = y + i * h
+        return (
+          <div
+            key={role}
+            className="vz-rail-row"
+            style={{
+              top,
+              height: h,
+              opacity: readable ? 1 : 0,
+              ["--ember" as string]: ROLE_EMBER[role],
+            }}
+          >
+            <span className="vz-lane-name">{role}</span>
+            {ROLE_EQUIV[role] && h > 48 && <span className="vz-lane-eq">{ROLE_EQUIV[role]}</span>}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+function CanvasInner(props: CanvasProps) {
+  const { screenToFlowPosition } = useReactFlow()
+  const wrap = useRef<HTMLDivElement>(null)
+  const laneWidth = useMemo(() => 4000, [])
+
+  const onDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+    e.dataTransfer.dropEffect = "copy"
+  }, [])
+
+  const onDrop = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault()
+      const payload = e.dataTransfer.getData("application/griot-node")
+      if (!payload) return
+      const position = screenToFlowPosition({ x: e.clientX, y: e.clientY })
+      props.onDropComponent(payload, position, laneOf(position.y))
+    },
+    [screenToFlowPosition, props]
+  )
+
+  // xyflow v12 types this handler's event as MouseEvent | TouchEvent (not React's
+  // synthetic MouseEvent) because a drag can end from touch. We never read the event.
+  const onNodeDragStop: OnNodeDrag<Node<ComponentNodeData>> = useCallback(
+    (_e, node) => {
+      const target = laneOf(node.position.y + (node.measured?.height ?? 96) / 2)
+      const current = node.data.griot.layer
+      if (target !== current) props.onReroute(node.id, target)
+    },
+    [props]
+  )
+
+  return (
+    <div className="vz-canvas" ref={wrap} onDragOver={onDragOver} onDrop={onDrop}>
+      <ReactFlow
+        nodes={props.nodes}
+        edges={props.edges}
+        nodeTypes={nodeTypes}
+        onNodesChange={props.onNodesChange}
+        onEdgesChange={props.onEdgesChange}
+        onConnect={props.onConnect}
+        onNodeDragStop={onNodeDragStop}
+        onPaneClick={() => props.onSelect(null)}
+        onNodeClick={(_e, n) => props.onSelect(n.id)}
+        minZoom={0.2}
+        maxZoom={2.2}
+        fitView
+        proOptions={{ hideAttribution: false }}
+      >
+        <LaneBands width={laneWidth} />
+        <LaneRail />
+        <Background variant={BackgroundVariant.Dots} gap={22} size={1} color="var(--grid)" />
+        <Controls position="bottom-right" />
+        <MiniMap
+          pannable
+          zoomable
+          bgColor="#0d1116"
+          maskStrokeColor="rgba(255,255,255,.12)"
+          nodeColor={(n) => ROLE_EMBER[(n.data as ComponentNodeData).griot?.layer as LayerSlot] ?? "#555"}
+          maskColor="rgba(0,0,0,.55)"
+        />
+      </ReactFlow>
+    </div>
+  )
+}
+
+export function Canvas(props: CanvasProps) {
+  return (
+    <ReactFlowProvider>
+      <CanvasInner {...props} />
+    </ReactFlowProvider>
+  )
+}
+
+export { applyNodeChanges, applyEdgeChanges, addEdge }
+export type { Node, Edge, NodeChange, EdgeChange, Connection, ReactFlowInstance }

package/src/layers/02-render/ComponentNode.tsx

@@ -0,0 +1,103 @@
+/**
+ * Layer 02 — the node. A Waku box: every box IS a real module file.
+ *
+ * The prism-viz-engine thesis ends "...ships them as interactive, source-wired surfaces
+ * in the Waku mold — not static SVGs." So this component refuses to be a label:
+ *
+ *   Wiring A — click selects it and the shell reveals its detail (hash-deep-linkable)
+ *   Wiring B — the ⟨source⟩ control opens the REAL file at the REAL line
+ *   Wiring C — `data-node` id glows when a live trace event names it
+ *
+ * It carries BOTH harvest halves on one card, because a decision about the future of
+ * the tooling needs the picture and the function together: the UI half gives the
+ * file:line and mount point, the code half gives licence, fit and the standing ruling.
+ */
+
+import { memo, useCallback } from "react"
+import { Handle, Position, type NodeProps } from "@xyflow/react"
+import { ROLE_EMBER, type LayerSlot } from "../../core/layer-roles"
+import type { GriotNodeMeta } from "../../core/json-canvas"
+
+export interface ComponentNodeData extends Record<string, unknown> {
+  label: string
+  griot: GriotNodeMeta
+  tracing?: boolean
+  reveal?: (origin: { repo: string; file: string; line: number }) => void | Promise<void>
+}
+
+const DECISION_TONE: Record<string, string> = {
+  adopt: "var(--ok)",
+  trial: "var(--sky)",
+  defer: "var(--amber)",
+  pass: "var(--dim)",
+  undecided: "var(--dim)",
+}
+
+function ComponentNodeImpl({ data, selected, id }: NodeProps) {
+  const d = data as ComponentNodeData
+  const g = d.griot
+  const ember = ROLE_EMBER[g.layer as LayerSlot] ?? "#6b7385"
+  const ui = g.ui
+  const code = g.code
+
+  const onReveal = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation()
+      if (ui?.origin && d.reveal) void d.reveal(ui.origin)
+    },
+    [ui, d]
+  )
+
+  return (
+    <div
+      className={`vz-node${selected ? " sel" : ""}${d.tracing ? " tracing" : ""}`}
+      data-node={id}
+      style={{ ["--ember" as string]: ember }}
+      title={ui?.mountPoint}
+    >
+      <Handle type="target" position={Position.Top} className="vz-handle" />
+
+      <div className="vz-node-top">
+        {ui && <span className="vz-repo">{ui.origin.repo}</span>}
+        {g.walkLevel && <span className="vz-kind">{g.walkLevel}</span>}
+        {code?.decision && code.decision !== "undecided" && (
+          <span className="vz-dec" style={{ color: DECISION_TONE[code.decision] }}>
+            {code.decision}
+          </span>
+        )}
+        {!!ui?.notCopy?.length && (
+          <span className="vz-warn" title={ui.notCopy.join("\n")}>
+            ⚠{ui.notCopy.length}
+          </span>
+        )}
+      </div>
+
+      <div className="vz-label">{d.label}</div>
+
+      {/* The evidence, always visible. A card without file:line is not a finding. */}
+      {ui && (
+        <button className="vz-src" onClick={onReveal} disabled={!d.reveal} title={d.reveal ? "open the real source" : "no reveal on this host"}>
+          <span className="vz-src-file">{ui.origin.file}</span>
+          <span className="vz-src-line">:{ui.origin.line}</span>
+        </button>
+      )}
+
+      {/* The code half — licence is a FACT for a field, never a verdict. */}
+      {code && (
+        <div className="vz-code">
+          <span className="vz-lic">{code.licence}</span>
+          {code.fit && (
+            <span className="vz-fit" title={code.fit.why}>
+              {code.fit.app}
+              <b>{"·".repeat(code.fit.strength)}</b>
+            </span>
+          )}
+        </div>
+      )}
+
+      <Handle type="source" position={Position.Bottom} className="vz-handle" />
+    </div>
+  )
+}
+
+export const ComponentNode = memo(ComponentNodeImpl)