# Graph UI Bench Plan (BENCH-GRAPH-21-002)

Purpose: provide a deterministic, headless flow for measuring graph UI interactions over large fixtures (50k/100k nodes).

## Scope
- Use synthetic fixtures under `samples/graph/interim/` until canonical SAMPLES-GRAPH-24-003 lands.
- Optional overlay layer (`overlay.ndjson`) is loaded when present and toggled during the run to capture render/merge overhead.
- Drive a deterministic sequence of interactions:
  1) Load graph canvas with specified fixture.
  2) Pan to node `pkg-000001`.
  3) Zoom in 2×, zoom out 1×.
  4) Apply filter `name contains "package-0001"`.
  5) Select node, expand neighbors (depth 1), collapse.
  6) Toggle overlay layer (once available).
- Capture timings: initial render, filter apply, expand/collapse, overlay toggle (when available).

## Determinism rules
- Fixed seed for any randomized layouts (seed `424242`).
- Disable animations/transitions where possible; otherwise measure after `requestAnimationFrame` settle.
- No network calls; fixtures loaded from local file served by test harness.
- Stable viewport (width=1280, height=720), device scale factor 1.

## Artifacts
- `ui_bench_scenarios.json` — canonical scenario list with step ids and notes.
- `ui_bench_driver.mjs` — helper that reads scenario + fixture manifest and emits a run plan (no browser dependency). Intended to be wrapped by a Playwright script later.
- Results format (proposed): NDJSON with `{stepId, name, durationMs, fixture, timestamp}`.

## Next steps
- Bind `ui_bench_driver.mjs` into a Playwright harness when Graph UI build/serve target is available.
- Swap fixtures to SAMPLES-GRAPH-24-003 + overlay once schema finalized; keep scenario ids stable.
- Add CI slice to run the driver and validate scenario/fixture bindings (no browser) to keep determinism checked in commits.