prism-viz-engine 0.1.0

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

@@ -0,0 +1,288 @@
+/**
+ * Layer 02 — the isometric canvas. Third renderer, same document.
+ *
+ * xyflow draws the graph; this draws the same JSON Canvas as an isometric scene, which
+ * is the read cloud and server architectures want — racks, tiers, zones with depth.
+ * FossFLOW's projection, our document, our motion clock.
+ *
+ * It shares the document rather than converting it: switching views never mutates the
+ * canvas, so positions survive a round trip exactly. The tile quantisation happens on
+ * the way in (isometric.ts `pixelToTile`) and is thrown away on the way out.
+ *
+ * Motion here obeys the same law as everywhere else: the camera eases at
+ * MOTION.camera (FossFLOW's 0.25s), decorative pulse is `loop`-mode only, aria-hidden,
+ * and the first thing dropped under prefers-reduced-motion.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import {
+  isoBox,
+  pixelToTile,
+  depthSort,
+  PROJECTED_TILE_SIZE,
+  type Tile,
+} from "./isometric"
+import type { JSONCanvas, CanvasNode, GriotNodeMeta } from "../../core/json-canvas"
+import { ROLE_EMBER, type LayerSlot } from "../../core/layer-roles"
+
+/**
+ * Colour of last resort. archify components arrive `unplaceable` on purpose — a layer
+ * role is Gavin's to assign and must never be guessed — so an example diagram would
+ * otherwise render as a uniform grey field. Falling back to the component's own
+ * declared `type` keeps the read without inventing a routing.
+ */
+const TYPE_TINT: Record<string, string> = {
+  user: "#38bdf8", client: "#38bdf8", ui: "#38bdf8", desktop: "#38bdf8",
+  service: "#3b82f6", process: "#3b82f6", api: "#3b82f6", gateway: "#818cf8",
+  store: "#10ffba", storage: "#10ffba", db: "#10ffba", cache: "#10ffba",
+  model: "#f472b6", provider: "#f472b6", llm: "#f472b6",
+  tool: "#f59e0b", runtime: "#f59e0b", worker: "#f59e0b",
+  security: "#fb7185", policy: "#fb7185", permission: "#fb7185",
+}
+function tintFor(griot: GriotNodeMeta | undefined, node: CanvasNode): string {
+  const routed = griot?.layer && griot.layer !== "unplaceable"
+  if (routed) return ROLE_EMBER[griot!.layer as LayerSlot]
+  const t = String((node as any).archify?.type ?? griot?.code?.capability ?? "").toLowerCase()
+  for (const k of Object.keys(TYPE_TINT)) if (t.includes(k)) return TYPE_TINT[k]
+  return "#64748b"
+}
+import { MOTION, pulseIntensity, activeIndex, decorativeAttrs, type MotionMode } from "../../core/motion"
+import { loadIcons, resolveIcon, placeIcon, type IsoIcon } from "./icons"
+
+export interface IsometricViewProps {
+  canvas: JSONCanvas
+  /** Pixel footprint one tile stands for. Larger spreads the lattice. */
+  cell?: number
+  /** Extrusion depth — what turns a floor tile into a machine. */
+  boxHeight?: number
+  motionMode?: MotionMode
+  selectedId?: string | null
+  onSelect?: (id: string | null) => void
+  onReveal?: (origin: { repo: string; file: string; line: number }) => void | Promise<void>
+}
+
+interface Placed {
+  node: CanvasNode
+  griot?: GriotNodeMeta
+  tile: Tile
+  box: ReturnType<typeof isoBox>
+}
+
+/** Break on word boundaries, never mid-word — a clipped label is worse than two lines. */
+function wrapLabel(s: string, max = 16, maxLines = 2): string[] {
+  const words = s.split(/\s+/)
+  const lines: string[] = []
+  let cur = ""
+  for (const w of words) {
+    if (!cur) { cur = w; continue }
+    if ((cur + " " + w).length <= max) cur += " " + w
+    else { lines.push(cur); cur = w; if (lines.length === maxLines - 1) break }
+  }
+  if (cur && lines.length < maxLines) lines.push(cur)
+  if (lines.length === maxLines && words.join(" ").length > lines.join(" ").length)
+    lines[maxLines - 1] = lines[maxLines - 1].slice(0, max - 1) + "…"
+  return lines
+}
+
+export function IsometricView({
+  canvas,
+  cell = 96,
+  boxHeight = 26,
+  motionMode = "none",
+  selectedId,
+  onSelect,
+  onReveal,
+}: IsometricViewProps) {
+  const [cam, setCam] = useState({ x: 0, y: 0, zoom: 1 })
+  // 1062 base64 icons load lazily — a canvas that needs none pays nothing.
+  const [icons, setIcons] = useState<IsoIcon[]>([])
+  useEffect(() => { loadIcons().then(setIcons).catch(() => {}) }, [])
+  const [elapsed, setElapsed] = useState(0)
+  const wrap = useRef<HTMLDivElement>(null)
+  const pan = useRef<{ x: number; y: number; cx: number; cy: number } | null>(null)
+
+  // Decorative clock. Only runs in loop mode, and never under reduced motion —
+  // animation.md:76 drops [data-motion-decorative] entirely there.
+  useEffect(() => {
+    if (motionMode !== "loop") return
+    if (typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches)
+      return
+    let raf = 0
+    const t0 = performance.now()
+    const tick = (now: number) => {
+      setElapsed(now - t0)
+      raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [motionMode])
+
+  const placed: Placed[] = useMemo(() => {
+    const items = canvas.nodes
+      .filter((n) => n.type !== "group")
+      .map((n) => {
+        const tile = pixelToTile({ x: n.x, y: n.y }, cell)
+        return { node: n, griot: n.griot as GriotNodeMeta | undefined, tile, box: isoBox(tile, boxHeight) }
+      })
+    // back paints first or a neighbour's extrusion draws over it
+    return depthSort(items)
+  }, [canvas.nodes, cell, boxHeight])
+
+  const byId = useMemo(() => new Map(placed.map((p) => [p.node.id, p])), [placed])
+
+  const bounds = useMemo(() => {
+    if (!placed.length) return { minX: -400, minY: -300, w: 800, h: 600 }
+    const xs = placed.flatMap((p) => [p.box.center.x - PROJECTED_TILE_SIZE.width, p.box.center.x + PROJECTED_TILE_SIZE.width])
+    const ys = placed.flatMap((p) => [p.box.center.y - PROJECTED_TILE_SIZE.height, p.box.center.y + PROJECTED_TILE_SIZE.height + boxHeight])
+    const minX = Math.min(...xs) - 60
+    const minY = Math.min(...ys) - 60
+    return { minX, minY, w: Math.max(...xs) - minX + 60, h: Math.max(...ys) - minY + 60 }
+  }, [placed, boxHeight])
+
+  // Lanshu's sequential activation, under diagram-design's one-at-a-time rule.
+  const lit = motionMode === "loop" ? activeIndex(elapsed, placed.length, 620) : -1
+  const pulse = motionMode === "loop" ? pulseIntensity(elapsed) : 0
+
+  const onDown = useCallback((e: React.PointerEvent) => {
+    if ((e.target as HTMLElement).closest("[data-iso-node]")) return
+    pan.current = { x: e.clientX, y: e.clientY, cx: cam.x, cy: cam.y }
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+    onSelect?.(null)
+  }, [cam.x, cam.y, onSelect])
+
+  const onMove = useCallback((e: React.PointerEvent) => {
+    if (!pan.current) return
+    setCam((c) => ({ ...c, x: pan.current!.cx + (e.clientX - pan.current!.x), y: pan.current!.cy + (e.clientY - pan.current!.y) }))
+  }, [])
+
+  const onUp = useCallback(() => { pan.current = null }, [])
+
+  const onWheel = useCallback((e: React.WheelEvent) => {
+    e.preventDefault()
+    setCam((c) => ({ ...c, zoom: Math.max(0.2, Math.min(2.4, c.zoom * (e.deltaY < 0 ? 1.12 : 1 / 1.12))) }))
+  }, [])
+
+  return (
+    <div className="vz-iso" ref={wrap} onPointerDown={onDown} onPointerMove={onMove} onPointerUp={onUp} onWheel={onWheel}>
+      <svg
+        className="vz-iso-svg"
+        viewBox={`${bounds.minX} ${bounds.minY} ${bounds.w} ${bounds.h}`}
+        style={{
+          transform: `translate(${cam.x}px, ${cam.y}px) scale(${cam.zoom})`,
+          transition: `transform var(--motion-camera, ${MOTION.camera}ms) var(--motion-ease)`,
+        }}
+      >
+        <defs>
+          <filter id="iso-glow" x="-60%" y="-60%" width="220%" height="220%">
+            <feGaussianBlur stdDeviation="4" result="b" />
+            <feMerge>
+              <feMergeNode in="b" />
+              <feMergeNode in="SourceGraphic" />
+            </feMerge>
+          </filter>
+        </defs>
+
+        {/* edges first — they run under the boxes, like cabling under a floor */}
+        <g className="vz-iso-edges">
+          {canvas.edges.map((e) => {
+            const a = byId.get(e.fromNode)
+            const b = byId.get(e.toNode)
+            if (!a || !b) return null
+            const p1 = a.box.anchors[(e.fromSide ?? "bottom") as keyof typeof a.box.anchors]
+            const p2 = b.box.anchors[(e.toSide ?? "top") as keyof typeof b.box.anchors]
+            const mx = (p1.x + p2.x) / 2
+            const d = `M${p1.x},${p1.y} Q${mx},${p1.y} ${mx},${(p1.y + p2.y) / 2} T${p2.x},${p2.y}`
+            // THE HALO — grafted from FossFLOW Connector.tsx:107-125. Two stacked
+            // strokes: a ground-coloured halo at 1.4x width / 0.7 opacity beneath the
+            // line itself. Its A* grid is walls-free, so nothing avoids anything; the
+            // halo is what keeps a connector readable where it crosses a dense scene.
+            // Legibility solved at DRAW time, not at route time.
+            return (
+              <g key={e.id}>
+                <path className="vz-iso-edge-halo" d={d} />
+                <path className="vz-iso-edge" d={d} />
+              </g>
+            )
+          })}
+        </g>
+
+        {/* boxes, painted back to front */}
+        <g className="vz-iso-nodes">
+          {placed.map((p, i) => {
+            const ember = tintFor(p.griot, p.node)
+            const isSel = selectedId === p.node.id
+            const isLit = i === lit
+            const label = (p.node as any).label ?? p.node.id
+            const ax = (p.node as any).archify ?? {}
+            const match = resolveIcon(icons, { label: String(label), type: ax.type, brand: ax.brand })
+            const art = match ? placeIcon(match.icon, p.box.center, boxHeight) : null
+            return (
+              <g
+                key={p.node.id}
+                data-iso-node={p.node.id}
+                className={`vz-iso-node${isSel ? " sel" : ""}`}
+                onClick={(ev) => {
+                  ev.stopPropagation()
+                  onSelect?.(p.node.id)
+                }}
+                onDoubleClick={() => {
+                  const o = p.griot?.ui?.origin
+                  if (o && onReveal) void onReveal(o)
+                }}
+              >
+                {/* Lanshu's pulse, ruled decorative: aria-hidden, loop-only, never semantic */}
+                {isLit && (
+                  <polygon
+                    {...decorativeAttrs()}
+                    points={p.box.top}
+                    fill={ember}
+                    opacity={0.25 + pulse * 0.45}
+                    filter="url(#iso-glow)"
+                  />
+                )}
+                <polygon className="vz-iso-face left" points={p.box.left} fill={ember} />
+                <polygon className="vz-iso-face right" points={p.box.right} fill={ember} />
+                <polygon className="vz-iso-face top" points={p.box.top} fill={ember} />
+                {art && (
+                  /* Two paths, never averaged: an isometric icon is ANCHORED and never
+                     transformed; a flat vendor mark is PROJECTED into the plane as a
+                     decal. Transform the first and it shears; leave the second flat and
+                     it floats above the scene like a sticker. */
+                  <image
+                    className="vz-iso-icon"
+                    href={art.href}
+                    width={art.width}
+                    x={art.x}
+                    y={art.y}
+                    transform={art.transform}
+                    preserveAspectRatio="xMidYMax meet"
+                    aria-hidden="true"
+                  />
+                )}
+                <text
+                  className="vz-iso-label"
+                  x={p.box.labelAt.x}
+                  y={art ? p.box.labelAt.y + boxHeight + 16 : p.box.labelAt.y}
+                  textAnchor="middle"
+                >
+                  {wrapLabel(String(label)).map((line, li, all) => (
+                    <tspan key={li} x={p.box.labelAt.x} dy={li === 0 ? -((all.length - 1) * 6) : 12}>
+                      {line}
+                    </tspan>
+                  ))}
+                </text>
+              </g>
+            )
+          })}
+        </g>
+      </svg>
+
+      {!placed.length && (
+        <p className="vz-empty vz-iso-empty">
+          Nothing to project. The isometric view renders the same JSON Canvas as the graph view —
+          load a source first.
+        </p>
+      )}
+    </div>
+  )
+}

package/src/layers/02-render/icons.ts

@@ -0,0 +1,199 @@
+/**
+ * The isometric icon system — TWO paths, because the packs are two kinds of thing.
+ *
+ * `@isoflow/isopacks` was a devDependency of FossFLOW and the first harvest wrote it off
+ * as "used only by examples." That was the wrong read: a cloud/server isometric without
+ * icons is coloured boxes with captions. Counted after installing:
+ *
+ *   isoflow      37 icons   ALL isometric   — drawn to sit ON a tile
+ *   aws         320 icons   0 isometric     — flat vendor marks
+ *   gcp         217 icons   0 isometric
+ *   azure       448 icons   0 isometric
+ *   kubernetes   40 icons   0 isometric
+ *
+ * So 37 of 1062 are genuinely isometric, and FossFLOW handles the split with two
+ * components rather than one. Both are reproduced here from source:
+ *
+ *   ISOMETRIC  (IconTypes/IsometricIcon.tsx) — never transformed, only ANCHORED.
+ *              width = PROJECTED_TILE_SIZE.width * 0.8, top = -height, left = -width/2.
+ *              Bottom-centre, so the art sits on the tile it belongs to.
+ *
+ *   FLAT       (IconTypes/NonIsometricIcon.tsx) — projected INTO the plane as a decal.
+ *              matrix(0.707, -0.409, 0.707, 0.409, 0, -0.816)  (renderer.ts:204)
+ *              transformOrigin top-left, offset by -W/2/-H/2, image at 0.7 tile width.
+ *
+ * Transforming an already-isometric icon double-projects it and it reads as sheared;
+ * leaving a flat one unprojected makes it float above the scene like a sticker. The
+ * split is the whole trick, which is why it is preserved rather than averaged.
+ *
+ * Every icon is a self-contained `data:image/svg+xml;base64` URI — no network, so this
+ * works under the artifact CSP and offline.
+ */
+
+import { PROJECTED_TILE_SIZE } from "./isometric"
+
+export interface IsoIcon {
+  id: string
+  name: string
+  url: string
+  isIsometric?: boolean
+  pack: string
+}
+
+/** renderer.ts:204 — the decal projection, verbatim. */
+export const ISO_MATRIX = [0.707, -0.409, 0.707, 0.409, 0, -0.816] as const
+export const ISO_MATRIX_CSS = `matrix(${ISO_MATRIX.join(", ")})`
+
+/** IsometricIcon.tsx — anchored art sits at 0.8 tile width. */
+export const ANCHORED_SCALE = 0.8
+/** NonIsometricIcon.tsx — a decal is smaller so the projection does not overrun the face. */
+export const DECAL_SCALE = 0.7
+
+// ── the catalogue, loaded lazily ──────────────────────────────────────────────
+let CATALOGUE: IsoIcon[] | null = null
+
+/**
+ * Packs are dynamically imported so 1062 base64 icons never enter the initial bundle.
+ * A canvas with no icons pays nothing.
+ */
+/**
+ * Literal specifiers, not a template. A bundler cannot statically analyse
+ * `import(`...${p}.js`)` on a bare package name, so the first version resolved nothing
+ * and silently drew no icons — the failure mode a try/catch hides. Each entry is its own
+ * analysable dynamic import, so the packs still code-split.
+ */
+const PACK_LOADERS: Record<string, () => Promise<any>> = {
+  isoflow: () => import("@isoflow/isopacks/dist/isoflow.js"),
+  aws: () => import("@isoflow/isopacks/dist/aws.js"),
+  gcp: () => import("@isoflow/isopacks/dist/gcp.js"),
+  azure: () => import("@isoflow/isopacks/dist/azure.js"),
+  kubernetes: () => import("@isoflow/isopacks/dist/kubernetes.js"),
+}
+
+export async function loadIcons(
+  packs: string[] = ["isoflow", "aws", "gcp", "azure", "kubernetes"]
+): Promise<IsoIcon[]> {
+  if (CATALOGUE) return CATALOGUE
+  const out: IsoIcon[] = []
+  for (const p of packs) {
+    const load = PACK_LOADERS[p]
+    if (!load) continue
+    try {
+      const mod: any = await load()
+      const pack = mod.default ?? mod
+      for (const i of pack.icons ?? []) out.push({ ...i, pack: p })
+    } catch (e) {
+      // Say it. A silent catch here is what made the first version draw nothing while
+      // reporting success.
+      console.warn(`[prism-viz-engine] icon pack "${p}" failed to load`, e)
+    }
+  }
+  CATALOGUE = out
+  return out
+}
+
+// ── resolution ────────────────────────────────────────────────────────────────
+/**
+ * Match a node to an icon by what it IS, not by a lookup table we maintain.
+ *
+ * Order matters: an explicit `brand` wins, then a vendor-prefixed name match, then the
+ * generic isoflow primitive for the component type. Falling through to no icon is a
+ * legitimate result — a wrong icon is worse than none, because it asserts a technology
+ * the diagram never claimed.
+ */
+const TYPE_TO_PRIMITIVE: Record<string, string> = {
+  database: "storage",
+  cloud: "cloud",
+  security: "firewall",
+  messagebus: "block",
+  frontend: "desktop",
+  backend: "server",
+  external: "user",
+}
+
+const HINTS: Array<[RegExp, string]> = [
+  [/\bpostgres|mysql|sql|rds\b/i, "storage"],
+  [/\bredis|cache|memcach/i, "cache"],
+  [/\bdns|route ?53|cloudflare\b/i, "dns"],
+  [/\bfirewall|waf|security ?group|trust\b/i, "firewall"],
+  [/\bcdn|edge|worker\b/i, "cloud"],
+  [/\bqueue|bus|kafka|sqs|pubsub/i, "block"],
+  [/\blambda|function|serverless/i, "function-module"],
+  [/\bcron|schedul/i, "cronjob"],
+  [/\bbucket|s3|storage|volume|r2\b/i, "storage"],
+  [/\bdesktop|client|browser|ui\b/i, "desktop"],
+  [/\blaptop|dev\b/i, "laptop"],
+  [/\bdocument|doc|file\b/i, "document"],
+]
+
+export interface IconMatch {
+  icon: IsoIcon
+  /** why it matched — surfaced in the inspector so a wrong icon is traceable */
+  because: string
+}
+
+export function resolveIcon(
+  catalogue: IsoIcon[],
+  opts: { label?: string; type?: string; brand?: string }
+): IconMatch | null {
+  if (!catalogue.length) return null
+  const norm = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-")
+
+  // 1. an explicit brand is an author's statement — honour it exactly
+  if (opts.brand) {
+    const b = norm(opts.brand)
+    const hit = catalogue.find((i) => norm(i.name) === b) ?? catalogue.find((i) => norm(i.name).endsWith("-" + b))
+    if (hit) return { icon: hit, because: `brand "${opts.brand}"` }
+  }
+
+  // 2. the label naming a vendor service — "API Gateway" -> aws-api-gateway
+  if (opts.label) {
+    const l = norm(opts.label)
+    if (l.length > 3) {
+      const hit = catalogue.find((i) => i.pack !== "isoflow" && norm(i.name).endsWith("-" + l))
+      if (hit) return { icon: hit, because: `label matches ${hit.pack} "${hit.name}"` }
+    }
+    for (const [re, prim] of HINTS) {
+      if (re.test(opts.label)) {
+        const hit = catalogue.find((i) => i.pack === "isoflow" && norm(i.name) === prim)
+        if (hit) return { icon: hit, because: `label reads as ${prim}` }
+      }
+    }
+  }
+
+  // 3. the component type -> a generic isometric primitive
+  const prim = opts.type ? TYPE_TO_PRIMITIVE[opts.type] : undefined
+  if (prim) {
+    const hit = catalogue.find((i) => i.pack === "isoflow" && norm(i.name) === prim)
+    if (hit) return { icon: hit, because: `type "${opts.type}"` }
+  }
+
+  // 4. nothing honest to draw
+  return null
+}
+
+/**
+ * Placement for an SVG <image>, per the icon's own kind. Returns the attributes the
+ * renderer needs rather than a component, so the same maths serves SVG and DOM.
+ */
+export function placeIcon(icon: IsoIcon, centre: { x: number; y: number }, boxHeight: number) {
+  const w = PROJECTED_TILE_SIZE.width * (icon.isIsometric ? ANCHORED_SCALE : DECAL_SCALE)
+  if (icon.isIsometric) {
+    // Anchored: bottom-centre on the tile's top face. Never transformed.
+    return {
+      href: icon.url,
+      width: w,
+      x: centre.x - w / 2,
+      y: centre.y - w * 0.86,
+      transform: undefined as string | undefined,
+    }
+  }
+  // Decal: projected into the plane, sitting on the lid.
+  return {
+    href: icon.url,
+    width: w,
+    x: 0,
+    y: 0,
+    transform: `translate(${centre.x - w / 2}, ${centre.y - boxHeight * 0.5 - w * 0.34}) ${ISO_MATRIX_CSS}`,
+  }
+}

package/src/layers/02-render/isometric.ts

@@ -0,0 +1,149 @@
+/**
+ * Layer 02 — the isometric projection. GRAFTED from FossFLOW, reimplemented over our model.
+ *
+ * Isometric cloud/server views are part of this engine, not a separate tool. What is NOT
+ * lifted is the FossFLOW package: its scene model puts position on the VIEW as integer
+ * tile indices (`views.ts:7-11`) with no width/height on a node at all
+ * (`modelItems.ts:4-9`), so it cannot hold a JSON Canvas document — and adopting it drags
+ * MUI 5 + Emotion + GSAP + Paper + Quill + react-router-dom behind it.
+ *
+ * The maths is the valuable part and it is 20 lines. Read at source 2026-09-11 from
+ * `GriotSandbox/viz-generate/FossFLOW/packages/fossflow-lib/src/`:
+ *
+ *   utils/renderer.ts:89-96   getTilePosition — the forward projection
+ *     x =  halfW * tile.x - halfW * tile.y
+ *     y = -(halfH * tile.x + halfH * tile.y)
+ *
+ *   utils/renderer.ts:51-78   screenToIso — the inverse
+ *   config.ts:17-24           UNPROJECTED_TILE_SIZE = 100
+ *                             TILE_PROJECTION_MULTIPLIERS = { w: 1.415, h: 0.819 }
+ *
+ * Those multipliers are not arbitrary: 1.415 ~ sqrt(2) and 0.819 ~ sqrt(2)/sqrt(3), which
+ * is true 30-degree isometric. Zero CSS 3D and zero WebGL — it is a 2x2 matrix and an SVG
+ * polygon, which is exactly why it is worth having rather than depending on.
+ *
+ * THE ONE HONEST LOSS. Our nodes are pixel-positioned and sized; a tile lattice is
+ * integer-indexed and uniform. Converting quantises position and discards per-node size.
+ * That is a real lossy step, so it happens HERE, visibly, on the way into the view — the
+ * canvas document is never mutated, and switching back to the graph view restores exact
+ * positions because they were never overwritten.
+ */
+
+export const UNPROJECTED_TILE_SIZE = 100
+export const TILE_PROJECTION_MULTIPLIERS = { width: 1.415, height: 0.819 } as const
+export const PROJECTED_TILE_SIZE = {
+  width: UNPROJECTED_TILE_SIZE * TILE_PROJECTION_MULTIPLIERS.width,
+  height: UNPROJECTED_TILE_SIZE * TILE_PROJECTION_MULTIPLIERS.height,
+}
+
+export interface Tile {
+  x: number
+  y: number
+}
+export interface Point {
+  x: number
+  y: number
+}
+
+export type TileOrigin = "CENTER" | "TOP" | "BOTTOM" | "LEFT" | "RIGHT"
+
+/**
+ * Forward projection — tile lattice to screen. Grafted from `getTilePosition`
+ * (renderer.ts:89-96), including the five origin anchors, which is how a node's top face,
+ * base and side midpoints are addressed without a second set of maths.
+ */
+export function tileToScreen(
+  tile: Tile,
+  origin: TileOrigin = "CENTER",
+  size = PROJECTED_TILE_SIZE
+): Point {
+  const halfW = size.width / 2
+  const halfH = size.height / 2
+  const p: Point = {
+    x: halfW * tile.x - halfW * tile.y,
+    y: -(halfH * tile.x + halfH * tile.y),
+  }
+  switch (origin) {
+    case "TOP":
+      return { x: p.x, y: p.y - halfH }
+    case "BOTTOM":
+      return { x: p.x, y: p.y + halfH }
+    case "LEFT":
+      return { x: p.x - halfW, y: p.y }
+    case "RIGHT":
+      return { x: p.x + halfW, y: p.y }
+    default:
+      return p
+  }
+}
+
+/**
+ * Inverse — screen back to tile. Grafted from `screenToIso` (renderer.ts:51-78) with
+ * their scroll/rendererSize framing dropped, because our stage owns pan and zoom; this
+ * takes an already stage-local point.
+ */
+export function screenToTile(p: Point, size = PROJECTED_TILE_SIZE): Tile {
+  const halfW = size.width / 2
+  const halfH = size.height / 2
+  return {
+    x: Math.floor((p.x + halfW) / size.width - p.y / size.height),
+    y: -Math.floor((p.y + halfH) / size.height + p.x / size.width),
+  }
+}
+
+/**
+ * The lossy step, made explicit. Pixel-space node position to a tile index, by dividing
+ * through a cell. `cell` is the pixel footprint one tile stands for — larger spreads the
+ * lattice out, smaller packs it. Callers pick it; we do not guess a "correct" value.
+ */
+export function pixelToTile(p: Point, cell = 220): Tile {
+  return { x: Math.round(p.x / cell), y: Math.round(p.y / cell) }
+}
+
+/**
+ * A node's isometric box, as three SVG polygons: the top face (a diamond) plus the two
+ * visible side faces extruded by `height`. This is the cloud/server-rack read — a flat
+ * diamond alone looks like a floor tile, the extrusion is what makes it a machine.
+ */
+export function isoBox(tile: Tile, height = 34, size = PROJECTED_TILE_SIZE) {
+  const c = tileToScreen(tile, "CENTER", size)
+  const halfW = size.width / 2
+  const halfH = size.height / 2
+
+  // top face, clockwise from the north vertex
+  const n = { x: c.x, y: c.y - halfH }
+  const e = { x: c.x + halfW, y: c.y }
+  const s = { x: c.x, y: c.y + halfH }
+  const w = { x: c.x - halfW, y: c.y }
+
+  const pts = (ps: Point[]) => ps.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(" ")
+  const down = (p: Point) => ({ x: p.x, y: p.y + height })
+
+  return {
+    center: c,
+    /** the lid — this is what carries the node's colour */
+    top: pts([n, e, s, w]),
+    /** south-east wall */
+    right: pts([e, s, down(s), down(e)]),
+    /** south-west wall */
+    left: pts([w, s, down(s), down(w)]),
+    /** where a label sits so it reads flat, not skewed */
+    labelAt: { x: c.x, y: c.y + 4 },
+    /** edge anchor points, reusing the origin anchors rather than a second maths path */
+    anchors: {
+      top: tileToScreen(tile, "TOP", size),
+      right: tileToScreen(tile, "RIGHT", size),
+      bottom: { x: s.x, y: s.y + height },
+      left: tileToScreen(tile, "LEFT", size),
+    },
+  }
+}
+
+/**
+ * Depth order. In an isometric scene a tile further "back" must paint first or it will
+ * draw over its neighbour's extrusion. Back is smaller (x+y). FossFLOW gets this from
+ * array order in its view; we compute it, since our document has no implicit z.
+ */
+export function depthSort<T extends { tile: Tile }>(items: T[]): T[] {
+  return [...items].sort((a, b) => a.tile.x + a.tile.y - (b.tile.x + b.tile.y))
+}