prism-viz-engine 0.1.0

package/src/layers/04-shell/Gallery.tsx

@@ -0,0 +1,246 @@
+/**
+ * The catalogue — a systems-design diagram database, from BOTH systems, grouped by shape.
+ *
+ * Gavin's framing, and it is the right one: these are not a mood board. 62 diagram-design
+ * layouts are 62 SOLVED LAYOUT PROBLEMS — sankey, wardley, fishbone, swimlane, treemap,
+ * medallion, ridgeline, story-map, ER, gantt. And archify renders its own five from IR.
+ * The two belong in ONE display grouped by SHAPE, because the question being answered is
+ * "how does each system solve this, and which part am I integrating" — and you cannot see
+ * that if they sit in separate galleries.
+ *
+ * So SHARED shapes come first, side by side, same width, same row. Where both systems
+ * answer the same question, you see both answers together. Everything else follows as the
+ * catalogue of layouts only one of them has.
+ *
+ * These are rendered HTML, not IR — nothing here becomes a canvas node, which is why the
+ * catalogue is a mode rather than a canvas source.
+ *
+ * Caveat carried from the harvest and shown in the UI, not buried: style-guide.md:32 says
+ * diagram-design's assets "were built under an earlier skin." A reference, not the spec.
+ */
+
+import { useEffect, useMemo, useState } from "react"
+
+export type CatalogueSource = "diagram-design" | "archify" | "lanshu" | "visual-explainer" | "fossflow"
+
+export interface CatalogueItem {
+  source: CatalogueSource
+  dir: string
+  file: string
+  type: string
+  shape: string
+  variant: "light" | "dark" | "full"
+  /** example | template | index | icons | preview */
+  kind: string
+  animated?: boolean
+  imported?: boolean
+  url: string
+}
+
+export interface GalleryProps {
+  sidecar: string
+}
+
+const SOURCE_LABEL: Record<string, string> = {
+  "diagram-design": "diagram-design",
+  archify: "archify",
+  lanshu: "lanshu",
+  "visual-explainer": "visual-explainer",
+  fossflow: "fossflow",
+}
+
+export function Gallery({ sidecar }: GalleryProps) {
+  const [items, setItems] = useState<CatalogueItem[]>([])
+  const [shared, setShared] = useState<string[]>([])
+  const [notes, setNotes] = useState<string[]>([])
+  const [variant, setVariant] = useState<"dark" | "light" | "full">("dark")
+  const [q, setQ] = useState("")
+  const [open, setOpen] = useState<CatalogueItem | null>(null)
+  /**
+   * Motion ON by default here, deliberately inverting animation.md's publishing default.
+   * A catalogue of still frames cannot answer "how do these move" — and for Lanshu the
+   * movement is the whole argument. Each document runs its own motion; `?motion=static`
+   * is what would freeze them, so it is simply not appended.
+   */
+  const [motion, setMotion] = useState(true)
+  const [compare, setCompare] = useState<CatalogueItem[] | null>(null)
+
+  useEffect(() => {
+    fetch(`${sidecar}/api/gallery`)
+      .then((r) => r.json())
+      .then((b) => {
+        setItems(b.items ?? [])
+        setShared(b.shared ?? [])
+        setNotes(b.notes ?? [])
+      })
+      .catch((e) => setNotes([`catalogue unavailable: ${e.message}`]))
+  }, [sidecar])
+
+  /**
+   * archify renders one variant only, so filtering the whole catalogue by variant would
+   * silently drop it from every shared row — and the comparison is the point. Variant
+   * filters diagram-design; archify always shows what it has.
+   */
+  const visible = useMemo(() => {
+    const needle = q.trim().toLowerCase()
+    return items.filter((i) => {
+      // Only diagram-design ships variants; filtering everything by variant would drop
+      // every other source from every shared row, and the comparison is the point.
+      if (i.source === "diagram-design" && i.variant !== variant) return false
+      if (needle && !(i.shape.includes(needle) || i.type.includes(needle))) return false
+      return true
+    })
+  }, [items, variant, q])
+
+  const byShape = useMemo(() => {
+    const m = new Map<string, CatalogueItem[]>()
+    for (const i of visible) {
+      if (!m.has(i.shape)) m.set(i.shape, [])
+      m.get(i.shape)!.push(i)
+    }
+    const sharedFirst = [...m.entries()].sort(([a], [b]) => {
+      const as = shared.includes(a) ? 0 : 1
+      const bs = shared.includes(b) ? 0 : 1
+      return as - bs || a.localeCompare(b)
+    })
+    return sharedFirst
+  }, [visible, shared])
+
+  const counts = useMemo(
+    () => ({
+      shapes: new Set(items.map((i) => i.shape)).size,
+      bySource: items.reduce<Record<string, number>>((a, i) => ((a[i.source] = (a[i.source] ?? 0) + 1), a), {}),
+      animated: items.filter((i) => i.animated).length,
+    }),
+    [items]
+  )
+
+  const Tile = ({ i, wide }: { i: CatalogueItem; wide?: boolean }) => (
+    <figure className={`vz-gal${wide ? " wide" : ""}`} onClick={() => setOpen(i)}>
+      <div className="vz-gal-frame">
+        {/* Thumbnails freeze: 62 documents animating at once is a fan, not a catalogue.
+            Opening one runs it. */}
+        {i.file.endsWith(".html") ? (
+          <iframe src={`${sidecar}${i.url}?motion=static`} title={i.file} loading="lazy" scrolling="no" />
+        ) : (
+          /* A GIF carries its own motion and has no static query — Lanshu's previews are
+             the clearest case of a thing whose value is the movement. */
+          <img className="vz-gal-img" src={`${sidecar}${i.url}`} alt={i.file} loading="lazy" />
+        )}
+      </div>
+      <figcaption>
+        <span className={`vz-gal-src vz-src-${i.source}`}>{SOURCE_LABEL[i.source]}</span>
+        <b>{i.type}</b>
+        <span className="vz-gal-var">{i.variant}</span>
+      </figcaption>
+    </figure>
+  )
+
+  return (
+    <div className="vz-gallery">
+      <div className="vz-gallery-bar">
+        <span className="vz-gallery-title">
+          Catalogue
+          <span className="vz-count">{counts.shapes} shapes</span>
+          {Object.entries(counts.bySource).map(([src, n]) => (
+            <span key={src} className={`vz-count vz-src-${src}`}>{n} {src}</span>
+          ))}
+          {!!counts.animated && <span className="vz-count vz-anim">{counts.animated} animated</span>}
+        </span>
+        <input
+          className="vz-search vz-gallery-search"
+          placeholder="filter by shape…"
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+        />
+        {(["dark", "light", "full"] as const).map((v) => (
+          <button key={v} className={`vz-chip${variant === v ? " on" : ""}`} onClick={() => setVariant(v)}>
+            {v}
+          </button>
+        ))}
+        <button className={`vz-chip${motion ? " on" : ""}`} onClick={() => setMotion((m) => !m)} title="a catalogue of still frames cannot compare motion">
+          motion {motion ? "on" : "static"}
+        </button>
+        <span className="vz-spacer" />
+        <span className="vz-gallery-note">
+          diagram-design's assets were built under an earlier skin — reference, not spec
+        </span>
+      </div>
+
+      {!!notes.length && <p className="vz-empty">{notes.join(" · ")}</p>}
+
+      <div className="vz-cat">
+        {byShape.map(([shape, group]) => {
+          const isShared = shared.includes(shape)
+          const sources = [...new Set(group.map((g) => g.source))]
+          return (
+            <section key={shape} className={`vz-cat-shape${isShared ? " shared" : ""}`}>
+              <header className="vz-cat-hd">
+                <h3>{shape}</h3>
+                {isShared && (
+                  <button
+                    className="vz-cat-compare"
+                    onClick={() => setCompare(sources.map((s) => group.find((g) => g.source === s)!).filter(Boolean))}
+                  >
+                    compare {sources.length} ↔
+                  </button>
+                )}
+                <span className="vz-cat-count">
+                  {group.length} · {sources.join(" + ")}
+                </span>
+              </header>
+              <div className={`vz-cat-row${isShared ? " vz-cat-pair" : ""}`}>
+                {group.map((i) => (
+                  <Tile key={i.source + i.file} i={i} wide={isShared} />
+                ))}
+              </div>
+            </section>
+          )
+        })}
+      </div>
+
+      {/* side-by-side — the comparison the catalogue exists for */}
+      {compare && (
+        <div className="vz-gal-open" onClick={() => setCompare(null)}>
+          <div className="vz-gal-open-bar">
+            <b>{compare[0]?.shape}</b>
+            <span>the same shape, answered by each system</span>
+            <span className="vz-spacer" />
+            <button onClick={() => setCompare(null)}>close</button>
+          </div>
+          <div className="vz-compare" onClick={(e) => e.stopPropagation()}>
+            {compare.map((c) => (
+              <div key={c.source} className="vz-compare-pane">
+                <div className={`vz-gal-src vz-src-${c.source}`}>
+                  {SOURCE_LABEL[c.source]} · {c.file}
+                </div>
+                <iframe src={`${sidecar}${c.url}${motion ? "" : "?motion=static"}`} title={c.file} />
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {open && !compare && (
+        <div className="vz-gal-open" onClick={() => setOpen(null)}>
+          <div className="vz-gal-open-bar">
+            <span className={`vz-gal-src vz-src-${open.source}`}>{SOURCE_LABEL[open.source]}</span>
+            <b>{open.type}</b>
+            <span>{open.file}</span>
+            <span className="vz-spacer" />
+            <button onClick={() => setOpen(null)}>close</button>
+          </div>
+          {open.file.endsWith(".html") ? (
+            <iframe
+              src={`${sidecar}${open.url}${motion ? "" : "?motion=static"}`}
+              title={open.file}
+              onClick={(e) => e.stopPropagation()}
+            />
+          ) : (
+            <img className="vz-gal-open-img" src={`${sidecar}${open.url}`} alt={open.file} onClick={(e) => e.stopPropagation()} />
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/layers/04-shell/Inspector.tsx

@@ -0,0 +1,153 @@
+/**
+ * Layer 04 — the inspector. The box's real detail, both harvest halves.
+ *
+ * Waku's tabbed loop/memory/ops views, in our terms: when you click a box you get what
+ * it IS (the UI half — file:line, mount point, what not to copy) and what it DOES (the
+ * code half — capability, fit verdict, licence, the standing ruling). Fused, because
+ * that is the pair a tooling decision actually needs.
+ *
+ * The layer select here does the same job as dragging across a lane; both write the
+ * same field. Two routes to one act, never two sources of truth.
+ */
+
+import type { Node } from "@xyflow/react"
+import type { ComponentNodeData } from "../02-render/ComponentNode"
+import { ALL_SLOTS, ROLE_EMBER, ROLE_EQUIV, type LayerSlot } from "../../core/layer-roles"
+
+export interface InspectorProps {
+  node: Node<ComponentNodeData> | null
+  reveal?: (origin: { repo: string; file: string; line: number }) => void | Promise<void>
+  onRelayer: (nodeId: string, layer: LayerSlot) => void
+}
+
+const Field = ({ k, children, mono }: { k: string; children: React.ReactNode; mono?: boolean }) => (
+  <div className="vz-field">
+    <span className="vz-field-k">{k}</span>
+    <span className={`vz-field-v${mono ? " mono" : ""}`}>{children}</span>
+  </div>
+)
+
+export function Inspector({ node, reveal, onRelayer }: InspectorProps) {
+  if (!node) {
+    return (
+      <aside className="vz-inspector">
+        <h2>The canvas is the routing tool</h2>
+        <p className="vz-hint">
+          Drag a component out of the palette onto a lane — the lane it lands in <b>is</b> its layer
+          role. Drag it to another lane and the role is reassigned.
+        </p>
+        <p className="vz-hint">
+          Handle to handle writes an edge: that is how a component becomes part of a flow, and a
+          flow part of a workflow.
+        </p>
+        <p className="vz-hint">
+          <b>Export</b> writes JSON Canvas — the neutral wire between the engine's generators and
+          its canvases. The same file opens in Obsidian and feeds{" "}
+          <code>emit-canvas-nodes.mjs</code>, so bad routing is rejected rather than saved.
+        </p>
+        <div className="vz-legend">
+          {ALL_SLOTS.map((r) => (
+            <span key={r} className="vz-legend-row">
+              <i style={{ background: ROLE_EMBER[r] }} />
+              {r}
+              {ROLE_EQUIV[r] && <em>{ROLE_EQUIV[r]}</em>}
+            </span>
+          ))}
+        </div>
+      </aside>
+    )
+  }
+
+  const g = node.data.griot
+  const ui = g.ui
+  const code = g.code
+
+  return (
+    <aside className="vz-inspector">
+      <h2 style={{ borderColor: ROLE_EMBER[g.layer as LayerSlot] }}>{node.data.label}</h2>
+
+      <div className="vz-field">
+        <span className="vz-field-k">layer role</span>
+        <select
+          className="vz-select"
+          value={g.layer}
+          onChange={(e) => onRelayer(node.id, e.target.value as LayerSlot)}
+        >
+          {ALL_SLOTS.map((r) => (
+            <option key={r} value={r}>
+              {r}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {g.walkLevel && <Field k="walk level">{g.walkLevel}</Field>}
+
+      {ui && (
+        <>
+          <div className="vz-field">
+            <span className="vz-field-k">source · the evidence</span>
+            <button className="vz-reveal" disabled={!reveal} onClick={() => reveal?.(ui.origin)}>
+              {ui.origin.file}:{ui.origin.line}
+              <span className="vz-reveal-cta">{reveal ? "open ↗" : "no reveal here"}</span>
+            </button>
+          </div>
+          <Field k="mount point" mono>
+            {ui.mountPoint}
+          </Field>
+          <Field k="repo" mono>
+            {ui.origin.repo}
+          </Field>
+        </>
+      )}
+
+      {code && (
+        <>
+          {code.capability && <Field k="what it does">{code.capability}</Field>}
+          {!!code.features?.length && (
+            <Field k="features">
+              <ul className="vz-list">
+                {code.features.map((f) => (
+                  <li key={f}>{f}</li>
+                ))}
+              </ul>
+            </Field>
+          )}
+          {code.fit && (
+            <Field k="fit verdict">
+              {code.fit.app} <b>{"·".repeat(code.fit.strength)}</b> — {code.fit.why}
+            </Field>
+          )}
+          <Field k="licence — a fact, never a verdict" mono>
+            {code.licence}
+          </Field>
+          {(code.decision || code.role || code.stage) && (
+            <Field k="ruling" mono>
+              {[code.decision, code.role, code.stage].filter(Boolean).join(" · ")}
+            </Field>
+          )}
+        </>
+      )}
+
+      <Field k="what NOT to copy">
+        {ui?.notCopy?.length ? (
+          <ul className="vz-list vz-notcopy">
+            {ui.notCopy.map((x) => (
+              <li key={x}>{x}</li>
+            ))}
+          </ul>
+        ) : (
+          <span className="vz-dim">— none recorded —</span>
+        )}
+      </Field>
+
+      <Field k="provenance" mono>
+        {g.provenance.harvestedBy} · {g.provenance.harvestedAt}
+        {g.provenance.sourceCommit ? ` · ${g.provenance.sourceCommit}` : ""}
+      </Field>
+      <Field k="id" mono>
+        {node.id}
+      </Field>
+    </aside>
+  )
+}

package/src/layers/04-shell/Palette.tsx

@@ -0,0 +1,149 @@
+/**
+ * Layer 04 — the palette. The harvested components, as things you pick up.
+ *
+ * This is the half that was missing every previous attempt. A lane diagram shows where
+ * a component was ROUTED; it does not let you hold one. The palette is the shelf of
+ * real, harvested components — each one grounded in file:line, carrying its licence and
+ * its fit — that you drag onto the canvas to compose with.
+ *
+ * Grouped by repo, filterable, searchable. Each card is a drag source; the canvas is
+ * the drop target. What crosses between them is the node payload itself, so the thing
+ * you dropped is the thing that was harvested — never a copy that can drift.
+ */
+
+import { useMemo, useState } from "react"
+import type { CanvasNode, GriotNodeMeta } from "../../core/json-canvas"
+import { ROLE_EMBER, type LayerSlot } from "../../core/layer-roles"
+
+export interface PaletteProps {
+  /** Everything harvested — the shelf, independent of what is placed. */
+  library: CanvasNode[]
+  /** Ids already on the canvas, so the palette can mark them. */
+  placed: Set<string>
+  onReveal?: (origin: { repo: string; file: string; line: number }) => void | Promise<void>
+}
+
+export function Palette({ library, placed, onReveal }: PaletteProps) {
+  const [q, setQ] = useState("")
+  const [repo, setRepo] = useState<string>("all")
+
+  const repos = useMemo(
+    () => ["all", ...new Set(library.map((n) => n.griot?.ui?.origin.repo ?? "?").sort())],
+    [library]
+  )
+
+  const shown = useMemo(() => {
+    const needle = q.trim().toLowerCase()
+    return library.filter((n) => {
+      const g = n.griot as GriotNodeMeta | undefined
+      if (!g) return false
+      if (repo !== "all" && g.ui?.origin.repo !== repo) return false
+      if (!needle) return true
+      const hay = [
+        (n as any).label,
+        g.ui?.origin.file,
+        g.ui?.mountPoint,
+        g.layer,
+        g.code?.capability,
+        g.code?.licence,
+      ]
+        .join(" ")
+        .toLowerCase()
+      return hay.includes(needle)
+    })
+  }, [library, q, repo])
+
+  const grouped = useMemo(() => {
+    const m = new Map<string, CanvasNode[]>()
+    for (const n of shown) {
+      const r = n.griot?.ui?.origin.repo ?? "?"
+      if (!m.has(r)) m.set(r, [])
+      m.get(r)!.push(n)
+    }
+    return [...m.entries()].sort(([a], [b]) => a.localeCompare(b))
+  }, [shown])
+
+  return (
+    <aside className="vz-palette">
+      <div className="vz-palette-hd">
+        <div className="vz-palette-title">
+          Components <span className="vz-count">{shown.length}</span>
+        </div>
+        <input
+          className="vz-search"
+          placeholder="search components, files, licences…"
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+        />
+        <div className="vz-repos">
+          {repos.map((r) => (
+            <button key={r} className={`vz-chip${repo === r ? " on" : ""}`} onClick={() => setRepo(r)}>
+              {r}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      <div className="vz-palette-body">
+        {grouped.map(([r, items]) => (
+          <section key={r} className="vz-group">
+            <h3 className="vz-group-hd">
+              {r} <span className="vz-count">{items.length}</span>
+            </h3>
+            {items.map((n) => {
+              const g = n.griot as GriotNodeMeta
+              const ember = ROLE_EMBER[g.layer as LayerSlot] ?? "#6b7385"
+              const isPlaced = placed.has(n.id)
+              return (
+                <div
+                  key={n.id}
+                  className={`vz-card${isPlaced ? " placed" : ""}`}
+                  style={{ ["--ember" as string]: ember }}
+                  draggable
+                  onDragStart={(e) => {
+                    e.dataTransfer.setData("application/griot-node", JSON.stringify(n))
+                    e.dataTransfer.effectAllowed = "copy"
+                  }}
+                  title={g.ui?.mountPoint}
+                >
+                  <div className="vz-card-top">
+                    <span className="vz-card-kind">{g.walkLevel ?? n.type}</span>
+                    <span className="vz-card-layer">{g.layer}</span>
+                    {isPlaced && <span className="vz-placed">on canvas</span>}
+                  </div>
+                  <div className="vz-card-label">{(n as any).label}</div>
+                  {g.ui && (
+                    <button
+                      className="vz-card-src"
+                      disabled={!onReveal}
+                      onClick={(e) => {
+                        e.stopPropagation()
+                        if (onReveal) void onReveal(g.ui!.origin)
+                      }}
+                    >
+                      {g.ui.origin.file}:{g.ui.origin.line}
+                    </button>
+                  )}
+                  <div className="vz-card-foot">
+                    <span className="vz-lic">{g.code?.licence ?? "—"}</span>
+                    {!!g.ui?.notCopy?.length && (
+                      <span className="vz-warn" title={g.ui.notCopy.join("\n")}>
+                        ⚠{g.ui.notCopy.length}
+                      </span>
+                    )}
+                  </div>
+                </div>
+              )
+            })}
+          </section>
+        ))}
+        {!shown.length && (
+          <p className="vz-empty">
+            Nothing harvested matches. The palette only ever shows real walked components — it will
+            not fill itself with placeholders.
+          </p>
+        )}
+      </div>
+    </aside>
+  )
+}