From 7f485bbe729d339aa9b5b86199fd5de8da706336 Mon Sep 17 00:00:00 2001 From: Brummel Date: Wed, 10 Jun 2026 10:58:47 +0200 Subject: [PATCH] docs(design): graph-render redesign prototype MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Interactive, throwaway prototype of the aura graph render redesign — the visual language ratified for cycle 0026, replacing the ascii-dag text view. Homogeneous pin-nodes (body + n input pins + m output pins) rendered via Graphviz-WASM in the browser; pin-to-pin edges, type-as-colour, drill-down + inline-expand of composites, per-element styled tooltips, source/sink colouring, top-rank input ordering. index.html is the artifact; the ~1.4 MB WASM dep is git-ignored and restored by fetch-deps.sh. Visual companion to docs/specs/0026. --- .../design/prototypes/graph-render/.gitignore | 2 + docs/design/prototypes/graph-render/README.md | 54 ++++ .../prototypes/graph-render/fetch-deps.sh | 8 + .../design/prototypes/graph-render/index.html | 259 ++++++++++++++++++ 4 files changed, 323 insertions(+) create mode 100644 docs/design/prototypes/graph-render/.gitignore create mode 100644 docs/design/prototypes/graph-render/README.md create mode 100755 docs/design/prototypes/graph-render/fetch-deps.sh create mode 100644 docs/design/prototypes/graph-render/index.html diff --git a/docs/design/prototypes/graph-render/.gitignore b/docs/design/prototypes/graph-render/.gitignore new file mode 100644 index 0000000..14e3565 --- /dev/null +++ b/docs/design/prototypes/graph-render/.gitignore @@ -0,0 +1,2 @@ +viz-standalone.js +svg-pan-zoom.min.js diff --git a/docs/design/prototypes/graph-render/README.md b/docs/design/prototypes/graph-render/README.md new file mode 100644 index 0000000..d4fc430 --- /dev/null +++ b/docs/design/prototypes/graph-render/README.md @@ -0,0 +1,54 @@ +# 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://: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 ``/`xlink:title` (they pop up as browser tooltips) + and supply our own. diff --git a/docs/design/prototypes/graph-render/fetch-deps.sh b/docs/design/prototypes/graph-render/fetch-deps.sh new file mode 100755 index 0000000..92d4eee --- /dev/null +++ b/docs/design/prototypes/graph-render/fetch-deps.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +# Restore the vendored, re-downloadable render deps for the graph-render prototype. +# These are deliberately git-ignored (a ~1.4 MB WASM blob); index.html is the artifact. +set -euo pipefail +cd "$(dirname "$0")" +curl -sL https://unpkg.com/@viz-js/viz@3.7.0/lib/viz-standalone.js -o viz-standalone.js +curl -sL https://unpkg.com/svg-pan-zoom@3.6.1/dist/svg-pan-zoom.min.js -o svg-pan-zoom.min.js +echo "deps restored. serve with: python3 -m http.server 8000 --bind 0.0.0.0" diff --git a/docs/design/prototypes/graph-render/index.html b/docs/design/prototypes/graph-render/index.html new file mode 100644 index 0000000..23533f8 --- /dev/null +++ b/docs/design/prototypes/graph-render/index.html @@ -0,0 +1,259 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<title>aura graph — PoC (nested composites, multi-input) + + + +
+ aura graph + + hover · [+] expand · body drill +
+
+
+

+
+
+
+
+
+