# graph-render prototype

An interactive, throwaway prototype of the **`aura graph` render redesign** — the
visual language ratified during the cycle that replaces the `ascii-dag` text view.
It is a *reference for the implementation*, not shippable code: the Rust serializer
in `aura-cli` should emit the DOT this prototype generates, and the shipped viewer
should mirror this harness.

## Run

```sh
./fetch-deps.sh                       # restore the two git-ignored vendored deps
python3 -m http.server 8000 --bind 0.0.0.0
# open http://<host>:8000/ in a browser
```

`index.html` is the artifact (all the design decisions live there). The vendored
deps are git-ignored because one is a ~1.4 MB WASM blob; `fetch-deps.sh` re-pins
them (`@viz-js/viz@3.7.0`, `svg-pan-zoom@3.6.1`).

## What it embodies (the ratified visual language)

- **Substrate.** aura emits **DOT**; layout + draw is **Graphviz compiled to
  WebAssembly**, run in the browser (`@viz-js/viz`). No native binary, no layout
  engine in aura — aura is a *serializer*, Graphviz does the rest. Runs on a thin
  client (validated on a Chromebook over LAN).
- **Homogeneous node template.** Every node = body (type + param signature) + n
  input pins + m output pins, generated from one template off the declared
  interface (`NodeSchema`). Each pin/body is an individually addressable cell.
- **Pin-to-pin edges.** Edges dock output-pin → input-pin (DOT `node:port`), not
  node-to-node.
- **Type as colour.** One colour per scalar base type (i64/f64/bool/timestamp) on
  pins, params, and wires. The `: kind` text is off by default.
- **Navigation.** A composite is opaque with a left `[+]` button (inline-expand to
  a framed cluster, recursively / nested) and a body click (drill-down to its
  interior, with a breadcrumb).
- **Styled per-element tooltips.** A cursor-following div with mini-markdown: a pin
  shows `name · kind` (+ firing), a body shows type + params, an edge shows the
  kind, an expanded cluster shows the composite name.
- **Roles by colour + position.** Sources green, sinks maroon; composite-boundary
  `in:`/`out:` markers render as sources/sinks. Sources/inputs are pinned to the
  top rank in signature order; outputs to the bottom rank (free order); sinks float.

The canonical, prose record of these decisions is the cycle **spec** under
`docs/specs/` — this prototype is the visual companion to it.

## Graphviz gotchas baked in (carry into the implementation)

- Use a Graphviz **core font** (`Courier`) so HTML-label box sizing matches the
  rendered text — a web font overflows the box (Graphviz lays out with its own
  font metrics).
- Graphviz prefixes anchor (`href`) element ids with `a_` in the SVG.
- Strip Graphviz's native `<title>`/`xlink:title` (they pop up as browser tooltips)
  and supply our own.
