Dashboard v2: the React shell, the Focus, and the Spine lens (change 1)

[samiujan]

Dashboard v2: the React shell, the Focus, and the Spine lens

Scope: change 1 only — the React shell, the Focus, and the Spine lens.

This branch previously carried three units, because they were developed together. They are now separated:

Unit	Where it lives
Gate scripts (upstream PR sshaaf#109)	here, 4 files — the design doc's gate instructions reference them
Test-target fix (upstream PR sshaaf#120)	here, 3 lines — the dashboard crate's tests do not compile without it
Change 0 — rgctl review export	upstream PR sshaaf#117 only; dropped from this branch
Change 1 — the shell (this PR)	here

The four change-0 commits were removed by rebase (1,029 lines). The original branch feat/dashboard-v2 still carries them, so nothing is lost, and the Review room can branch from it once sshaaf#117 lands. Diff against main: 54 files rather than 62.

---

Fork PR (samiujan/rgctl). Parts of this are bound for sshaaf/rgctl as separate PRs; this branch is
where the dashboard work accumulates so it can be read as a whole.

This began as a design proposal and is now an implementation in progress.

The model is confirmed. The maintainer's answer to "is the Focus the model you were
describing?" is yes — unambiguously. That was the bet the whole design rested on: one portable
selection, carried across rooms and lenses, with analysis downstream of it. The rooms below are no
longer being built against a guess. The v2 shell runs against a
real bundle, the Focus is carried across rooms through the URL, and the Spine lens renders source beside
its control-flow graph — the piece the maintainer named as missing on
issue #61.

---

What it looks like, running

Both screenshots below are the real app against a live 26 MB bundle — 5,345 nodes, 1,479 functions,
154 exported source files — not a mock with a static dataset.

Orientation — one screen. It ranks what is worth attention (1,472 symbols carry data flow, computed from the index) and links into the room that handles it. Totals stay in the graph; they do not tell you where to look.	The Spine lens — source for the focused symbol beside its control flow, bound by line number in both directions: selecting a block highlights the lines it covers. This is the code browser sshaaf#61 asks for.

The Instrument bar at the top is persistent and never a destination: graph digest, index freshness,
version, and capability dots derived from analysis.*_available rather than asserted. Per-language
coverage tiers are not in the bundle, so it says so instead of drawing a plausible dot count.

---

What is in this diff

dashboard/src/v2/	The v2 app: React 19, TanStack Router, Radix Primitives, Tailwind, React Query.
dashboard/vite.config.v2.ts	Its own Vite config and its own output directory, dist-v2.
docs/design/dashboard-v2.md	The design: value, principles, IA, stack decision with its evidence, change sequence.
docs/design/dashboard-v2/screens/	Nine screenshots — two of the v2 app, seven of the retired prototype that settled the stack.
src/cli/review_export.rs	rgctl review export (change 0) — also submitted as sshaaf#117.
scripts/test-dashboard-*.sh	Gate scripts restored (sshaaf#109).

v1 is untouched. dashboard/App.tsx and its 11 tabs are unchanged and dashboard/dist still serves
--with-dashboard, so the 18 dashboard test files stay meaningful while v2 is built rather than being
red-lined all at once. There is one flag — no --with-dashboard-v2, no --dashboard v2; v2 is
selected internally until v1 is retired.

Structural decisions worth reviewing

• Two Vite configs, not one config with a mode switch. v1 needs @preact/preset-vite's
  react → preact/compat alias; v2 must not have it. Exactly one config may carry the alias, so it
  lives in the file it belongs to and neither config contains a branch a reader has to evaluate.
• The Focus is namespaced — fn:<function_id> today, sk:<stable_key> once the export carries it.
  The engine has a stable key in analysis storage, but no dashboard index exports it; rather than
  treat two different identifiers as one string, the URL says which it holds, so a stored link cannot
  silently change meaning. A Focus that no longer resolves renders an explicit stale state.
• Absence is typed everywhere. A missing sidecar, an unavailable capability, a CFG block with no
  source line — each says what it cannot show and why. A surface that renders an empty container leaves
  the reader to guess whether the answer is "nothing" or "never ran".

---

Issue sshaaf#61 — what this does, what it skips, and why

The maintainer parked the navigation work on 2026-08-20, and this is a direct response to that comment
rather than to the original issue. It said:

Universe now has too many independent navigation modes without one model that ties them together
… Treat analysis as downstream of selection, not as a parallel app inside the cosmos …
A code browser is the missing piece. CFG, slice, blast, and dataflow only make sense next to the
actual source. Without that, the graphs are disconnected from the code and navigation feels arbitrary.
When we resume: design one navigation story first (including source), then place analysis tools inside
that story — don't add more surfaces until that is settled.

Requirement from that comment	What this does about it
"one model that ties them together"	The Focus — one portable value, carried across rooms and lenses, serialized into the URL.
"analysis as downstream of selection, not a parallel app"	Lenses, not tabs. CFG·PDG, dataflow, slice, blast, metrics and time are views over the current Focus; switching one never changes the subject.
"a code browser is the missing piece"	The Spine lens — source and graph side by side on one Focus. Built, not promised.

What is skipped, and why

Skipped, not rejected. Each is a view or a flag, and the parked comment says the views were never the
problem — the missing model was. Building the views first is what produced the parked state.

sshaaf#61 item	Decision	Why
--with-universe and its artifacts	Skip for now	A new export mode, a new artifact set and a deprecation path are all downstream of an IA that is still being proven. Shipping the flag first is the move that got parked.
3D as the primary navigation surface	Skip for now	3D-as-primary is a rendering decision and should follow a known selection model, not lead it. The design doc has a "Where 3D is justified" section.
Deprecating --with-dashboard; serve --open preferring universe	Skip for now	You cannot deprecate a surface whose replacement is not settled, and dashboard/dist is compile-time embedded, so this is release engineering too, not only UI.
Clickable in-cosmos commands	Skip for now	A fourth navigation mode before selection and source-reading exist.
LOD L0–L3, metagraph.json reuse, animated fly-to	Not evaluated here	Cosmos internals. If the cosmos is not the primary surface yet, its LOD scheme is not the constraint.
Reviving the existing upstream/universe branch	Not used as a base	3 commits, 188 commits behind main, written against the pre-rename naming (rg-build, rgbuilder-dashboard).

The gate that would un-skip the cosmos

When the Focus and the Spine work in the real dashboard — a symbol carried from search to source to CFG
to slice without losing your place — --with-universe becomes an alternative renderer for one room
and can be judged on its own merits, with the navigation model already proven.

That is the difference between the cosmos as a new mode and the cosmos as one view of a model that works.
Half of it now exists.

One factual correction

sshaaf#61 specifies "Louvain communities". The engine does not use Louvain: community detection is label
propagation (Raghavan 2007) with Newman modularity for the quality score
(docs/design/graph-metrics-design.md:87, crates/rgctl-analysis/README.md:41), and the v1 dashboard's
own label was corrected on this branch. communities.json is consumed either way, so nothing is blocked —
but it is the kind of detail a reader will trust and then repeat.

---

How it was verified

Against the real bundle, not a fixture, and two bugs were found that built cleanly and passed
type-checking:

dashboard/tsconfig.json sets "jsxImportSource": "preact" and includes src. Any .tsx under
src/ — including src/v2/ — therefore compiled its JSX through Preact's jsx-runtime and handed
Preact vnodes to real React: Minified React error #31, an empty #root, and a key list full of Preact's
__k/__b/__v internals. Fixed in both the bundler config and the v2 tsconfig, with the reasoning
recorded, because which config a bundler picks for a file that two configs claim is a resolution detail.
Worth knowing for anyone else adding React under src/.

A CFG block's start_line: 0 is not line zero — it is the absence of a line (synthetic prologue
blocks). Rendering it as L0 repeats the —-versus-0 confusion fixed as D4 on this branch. About 59%
of blocks in the real bundle carry line information; the rest now say —.

The data layer was also rewritten after reading a real bundle: the first version expected manifest.digest
and sources_index.sources, but the real manifest nests the digest under graph and the index calls its
array files. Both would have rendered an empty shell against real data while passing every type check.

---

The prototype, and why it is gone

A prototype was built first, on this stack, with real data from a live .rgctl/, to settle the framework
question and the IA. It did that — including the decisive artefact, a Radix Dialog.Portal rendering
where the same code renders nothing through preact/compat — and it was then retired: the code is
tagged mock-v2-prototype for provenance, and its seven screenshots are committed as the record.

It was not extended because it could not answer the question that matters. It had no WASM engine, so
nothing was driven by a real graph; its Code lens reported a count of source lines rather than source;
and its Spine rendered an empty state for want of a caller/callee index. The one requirement the
maintainer singled out was the one it could not demonstrate. Design decisions now belong in the real app,
where they can be tested against a real graph.

---

Change 1: what it contains, and where it stands

The change is scoped by an OpenSpec proposal (add-dashboard-v2-shell) that lives in a private planning
repo — upstream gitignores openspec/ (.gitignore:7-8), so it is not in this PR. This is the summary, so
the scope and the outstanding work are readable without it.

52 tasks: 30 done, 22 outstanding, 6 of those partial. A task is only ticked when it is actually done;
where the implementation differs from what the task assumed, the task stays open and says how.

Section	Done	Outstanding
1. Stack spike	9	—
1b. Test harness	1	2
2. Shell skeleton	4	1 (partial)
3. Focus primitive	4	2 (1 partial)
4. Lens control	2	—
5. Tests	0	6
5b. Retire the fn: bridge	2	—
6. Build, bundle, offline	1	3
7. Docs	1	2
8. Verification	2	2
9. Spine lens	2	3 (all partial)
10. Decisions	1	1

The three partials that matter

The Spine is source + a block list, not source + the dominance layout. The CFG sits beside the source
and is bound to it, but the prototype's dominator-depth layout is not ported. The binding is also
one-directional: selecting a block highlights its lines, but selecting lines does not highlight a
block. And the source is not syntax-highlighted — monospace with line numbers. All three are real gaps
against the task text rather than details I am waving through.

Coverage reports capabilities, not per-language tiers. The Instrument dots come from
analysis.*_available and semantic.available — real evidence in the bundle — and the label says
per-language tiers not in this bundle. The spec asked for the recorded support tiers; those are not
exported, so the intended source does not exist yet. What is there is honest, and it is not what was asked.

useFocus does not exist as a hook. The Focus stores only the key and that is enforced by the URL
being the store, but App.tsx reads the search param directly. Worth a hook when a second consumer
appears, not before.

What is blocked, and on what

	Blocked on
5.1–5.4 (Focus round-trip, lens preserves subject, default with no Focus, no tab strip at 1440px)	1b.1/1b.2 — vitest.config.ts declares no plugins and there is no DOM environment, so nothing that renders can be asserted. All four were verified by hand against a real bundle, which is how two of this branch's bugs were found; a hand check is not a regression test.
5b.2 (delete the fn: Focus bridge)	10.1, below.
9.1–9.3	Nothing external; just not done.

The Focus identity — decided

The Focus is function_id. Not because it is convenient, but because it is the node's deterministic
id: with_file_path sets it from deterministic_node_id
(crates/rgctl-graph/src/schema.rs:444), which is
UUIDv5(NAMESPACE_RGCTL, BLAKE3(path ‖ 0xff ‖ name ‖ 0xff ‖ node_type)[..8]). So it is the graph's
StableNodeKey in UUID form — which is what the design asked the Focus to be — and it was already exported
in every index.

Measured on a three-function repo — indexed, body edited, then renamed:

change	function_id	analysis stable_key
edit the function body	unchanged	changed
rename the function	changed	changed
re-index, no change	unchanged	unchanged

The alternative was the analysis storage key, file\x1fname\x1fcode_hash
(crates/rgctl-analysis/src/storage.rs:24), whose own doc comment calls it a stable cache key. It is
built for cache invalidation, so it must change when the content does — and it did. A Focus built on it
would expire the moment anyone touched the function, which is exactly when a review link is most
wanted. It was exported, measured, and reverted.

The sk: / fn: namespacing goes with it: the two turned out to be the same identity expressed twice, one
of them worse.

Still unsolved: renames. The name is part of the hash, so a rename produces a different id and an old
link stops resolving. Nothing in the engine survives a rename without a resolution step, and resolution
needs a baseline snapshot that a pasted URL does not have. The shell renders an explicit stale state that
says why. Open decision 10.2 is whether to build rename resolution at all.

Also outstanding, beyond the task list

• No WASM engine is wired into the v2 bundle. CFG details and source are fetched as JSON/text from the
  bundle, which is what v1 does for these views, but interactive graph expansion is not connected.
• Rooms are placeholders. Review, Security, Architecture, Migration and Proof render an explicit
  "not built yet, change N" state naming what fills them. Change 1 builds the frame and adds no analysis
  view; the rooms arrive as changes 2–6.
• v1's tab bar is left alone deliberately — it is the surface v2 replaces, not one to patch.

What review has come back

Two of the upstream PRs have had substantive review, and both are blocked on specific fixes to code in
this branch. The maintainer pre-approved each conditional on one change, so these are the next work
items rather than open questions:

PR	Finding	Fix
sshaaf#116	FunctionLocation::end_byte is documented exclusive; my span check was offset <= loc.end_byte, so at a boundary where one function's exclusive end equals the next function's start, the earlier one can also match and min_by_key may pick the wrong function.	offset < loc.end_byte, plus a test with adjacent functions.
sshaaf#117	I used ViolationLedger::in_memory() to stay read-only, which goes further than read-only — it also discards on-disk history. Regression classification and calendar first_seen would not match review check, so the exported policy section can disagree with the command it claims to compose.	Open the real ledger for classification and skip only the append, plus an integration test with a pre-seeded ledger.

Both are worth stating plainly because of what they have in common: in each case I satisfied one property
and broke an adjacent one. sshaaf#116 is a boundary error in exactly the place the task was about — resolving a
line to a function — and sshaaf#117 is a case where two of my own stated invariants (read-only, and "cannot
disagree with review check") conflicted, and I honoured the first at the cost of the second, which was
the more valuable one.

Also raised, non-blocking: provenance command lines omit flags the export actually used
(--full-snapshots, depths, fanout), so a consumer should not read them as re-run recipes; and
docs/json-api.md's "each section is byte-identical to what the corresponding command emits" is too
strong for policy and should be softened to "same builder, same evaluation path, modulo read-only and no
bisect".

---

Relationship to the upstream PRs

Upstream	Status
sshaaf#109 — restore dashboard gate scripts	Open, mergeable
sshaaf#110 — eight dashboard defects	Merged 8f09655, closed sshaaf#112
sshaaf#113 / sshaaf#114 — rgctl slice defects	Open, with PRs sshaaf#115 / sshaaf#116, all mergeable, DCO green
sshaaf#117 — rgctl review export (change 0)	Open, mergeable, DCO green

This branch was rebased onto main after sshaaf#110 merged, which dropped the nine commits already upstream;
prerequisite commits that are still under review (sshaaf#109, sshaaf#117) remain in the diff.

What I would like from you

1. Is the Focus the model you were describing? Answered: yes.
2. Is "lenses not rooms" the right answer to "analysis as downstream of selection"? If rooms plus
   lenses is still too many surfaces, say so.
3. Is the gate above the right gate for resuming the cosmos?

One correction I owe on this: the comment I posted to sshaaf#61 describes the Focus as
"survives renames because it is derived from identity rather than a row index". That is wrong, and I
found out afterwards — the identity is derived from (path, name, type), so a rename changes it. What it
survives is re-indexing. It is corrected everywhere in this branch, but the comment on sshaaf#61 still says it,
and the maintainer's yes was given partly against that description.