rg universe: 3D cosmos dashboard (--with-universe), deprecate --with-dashboard

[sshaaf]

Summary

Introduce rg universe — a full rewrite of the static dashboard as a single full-screen 3D cosmos for browsing the codebase by communities, with animated search fly-to, and clickable actions to run CLI workflows (semantic index, CFG analysis, discover flags, etc.). No tab-based UI.

Ship via new discover flag --with-universe. --with-dashboard remains for now; universe replaces it later and dashboard is deprecated.

Motivation

• Today’s dashboard is tab-centric (Graph, Functions, CFG, Slice, Blast, …) with 2D Sigma as the main graph view.
• Users want a primary 3D “code universe” — communities as regions, browse/zoom, search functions in space with camera animation.
• Agents stay on CLI -f json; universe is the human exploration surface (complements MCP/CLI, see Dual mode: CLI (today) + MCP server (rg-build mcp serve) #60).
• Structural data already exists: communities.json, metagraph.json, WASM expand(), semantic search — but not as one spatial experience.

CLI / discover

New flag

rg-build discover . --with-universe
# Optional: same analysis flags as today when needed for universe actions
rg-build discover . --with-universe --with-cfg --with-security

• Writes bundle under .rgbuilder/universe/ (or .rgbuilder/dashboard/ with manifest.mode: universe — decide in implementation).
• --with-dashboard continues to export legacy tab dashboard until deprecation.
• Both flags may be mutually exclusive or allow both during transition (document choice).

Deprecation path

1. Ship --with-universe alongside --with-dashboard.
2. serve --open opens universe when present; fallback to legacy dashboard.
3. Document universe as default human UI in user guide.
4. Deprecate --with-dashboard in a later release; remove legacy tab UI in a follow-up.

serve integration

rg-build serve --open   # universe static bundle + query API when available

Universe search benefits from live semantic API (/api/semantic/query) when served; static bundle should degrade gracefully (embedded search landmarks / index metadata).

Product: rg universe (no tabs)

Core UX

• One 3D viewport — full screen; no tab bar.
• LOD navigation (required for scale):
  • L0 Universe — Louvain communities + inter-community call bridges
  • L1 Galaxy — package/metanodes inside a community
  • L2 Neighborhood — functions via WASM expand() (existing worker)
  • L3 Symbol — detail for one function (panels / 2D insets)
• Unified search (always-visible command bar):
  • Semantic, name/pattern, qualified name, community label
  • Animated camera fly-to hits; pulse/highlight; optional multi-hit tour
• Breadcrumb — Universe › community › package › symbol
• Context panels (replace tabs) — blast radius, metrics, slice/CFG/dataflow insets on selection

Clickable CLI actions (“universe commands”)

In-universe UI to trigger or guide discover-time and post-discover workflows (not silent magic — show command, progress, or invoke via documented path):

User action (UI)	Underlying workflow
Build semantic search index	rg-build semantic index (+ embedder options)
Run CFG / PDG analysis	discover --with-cfg or incremental CFG pass
Security / taint	discover --with-security / --with-taint
Refresh graph	rg-build discover . --with-universe …
Label communities	rg-build communities label --write
Export migration plan	discover --export-migration-hints
Open query guide	Link to docs / copy-paste CLI recipes

Implementation options (pick in design):

• A. Show exact CLI + copy button; user runs in terminal (simplest, offline-safe).
• B. serve POST endpoints that spawn bounded subprocess (rg-build …) with progress SSE.
• C. WASM-only actions where already possible; CLI for heavy passes.

Start with A + partial B for serve mode.

What replaces legacy tabs

Legacy tab	Universe pattern
Graph	Default cosmos
Search	Primary search bar + fly-to
Functions	Search results + optional list panel
Blast	Selection panel
Slice / CFG / Dataflow	Panel or 2D inset on landed symbol
Migration	Spatial layer / scheduled regions + panel
Taint	Path highlight in scene + panel
Guide	? overlay / universe help (not a tab)

Technical architecture

New export artifacts (discover + --with-universe)

Extend rgbuilder-dashboard (or new rgbuilder-universe crate):

File	Content
universe.json	Community 3D positions, bridges, package local coords, schema version
communities.json	Existing (reuse)
metagraph.json	Existing (reuse for L1)
manifest.json	mode: "universe", paths, feature flags, action availability
graph_payload.bin	Existing columnar snapshot
search_landmarks.json	Optional: top functions / semantic-ready ids → cosmos coords for static fly-to
wasm/	Existing rgbuilder-wasm bundle

Precompute community layout at export (Rust) — browser renders and animates; avoid cold-start full-repo force layout in UI.

Frontend rewrite

• New app shell: dashboard/src/universe/ or universe/ package (may replace most of App.tsx tab router).
• Three.js instanced rendering + Web Worker layout (d3-force-3d or dedicated worker); consider graphier as reference/wrapper.
• Keep WASM worker (useEngineWorker) for L2 expand, blast, slice, CFG load.
• 2D Sigma only for small CFG/PDG insets inside panels — not primary navigation.
• Offline bundle via existing Vite → include_dir embed path.

Layout strategy

• Communities: hierarchical shells or precomputed 3D grid (export-time).
• Optional future: semantic embedding → 3D (UMAP/PCA) for NL-search-aligned space.
• Do not render full function graph at L0 (300k+ nodes) — LOD only.

Animation

• Camera ease on search / selection / zoom level change.
• Defer L2 load until camera nears target; pulse matched nodes.
• “Reduce motion” accessibility mode (instant jumps).

Relationship to other work

• Dual mode: CLI (today) + MCP server (rg-build mcp serve) #60 — MCP for agents; universe is human UI; share JSON shapes where possible.
• Agent telemetry: request/response audit log + token usage estimates #59 — Telemetry per search/fly-to and universe actions.
• Git hooks and CLI automation to keep graph updated (init-hooks, update, watch) #58 — Git hooks / watch refresh → universe “graph updated” notification.
• ForceAtlas3 / Sigma layout — legacy dashboard concern; universe uses 3D layout pipeline (separate).
• Markdown communities — universe may look sparse until community detection includes doc graphs; document limitation.

Phased rollout

Phase	Deliverable
P0	--with-universe exports minimal bundle; static L0 communities in 3D; serve serves it
P1	Unified search + animated fly-to (semantic via serve; static landmarks fallback)
P2	L1 packages + L2 WASM drill-down with landing animation
P3	Context panels: blast, symbol detail, CFG/slice insets
P4	Clickable universe commands (index, cfg, refresh) + progress UX
P5	Migration/taint parity in cosmos; deprecate --with-dashboard

MVP (P0–P2): browse communities in 3D + search with animation.

Acceptance criteria (MVP)

• rg-build discover . --with-universe writes universe bundle under .rgbuilder/
• rg-build serve --open opens universe when bundle present
• Full-screen 3D view: communities + inter-community edges (no tabs)
• Search bar: semantic (when index + serve) and/or name search with camera animation to target
• Click community → zoom to galaxy; click package → WASM neighborhood (L2)
• At least one clickable action UI: “Build search index” with CLI copy or serve-triggered run
• Legacy --with-dashboard still works unchanged
• Docs: user-guide section “rg universe”; AGENTS.md notes CLI remains agent default
• Playwright smoke: load universe, search, assert canvas + no tab bar

Open decisions

• Bundle path: .rgbuilder/universe/ vs reuse .rgbuilder/dashboard/ with mode flag
• serve subprocess for actions vs copy-only CLI hints
• 3D renderer: custom Three.js vs graphier vs nexgraph spike
• Whether --with-universe implies --with-dashboard assets during transition

References

• docs/dashboard-design.md — legacy dashboard phases
• dashboard/src/App.tsx — current tab shell
• crates/rgbuilder-dashboard/ — export pipeline, metagraph, communities
• dashboard/src/useEngineWorker.ts — WASM integration
• dashboard/package.json — sigma/graphology (legacy); universe will add Three.js stack

---

Visual design mockup

Concept UI for rg universe — full-screen 3D cosmos, unified search, community galaxies, context panel, and actionable CLI hints.

Elements shown:

• Deep-space 3D cosmos with Louvain community clusters (colored galaxies) and bridge edges between subsystems
• Search bar — primary entry for semantic / name / community search with fly-to animation
• Breadcrumb — spatial path (Universe › payments › OrderService)
• Context panel — blast-radius style metrics + “Build search index” action (clickable universe command)
• No tabs — single immersive viewport

Repo copy (for docs after commit): docs/universe/rg-universe-design-mockup.png (high-res) · docs/universe/rg-universe-design-mockup.jpg

Release asset (issue attachment): universe-design-mockup-61 (pre-release, for hosting only)

[sshaaf]

Added a visual design mockup to the issue description (full-screen 3D cosmos concept). High-res copies: docs/universe/rg-universe-design-mockup.png in the repo (uncommitted). Image hosted via prerelease asset for GitHub rendering.

[rokon12]

rg-universe-mockup.zip

[rokon12]

Interactive HTML mockup of the rg universe concept from this issue — full-screen 3D cosmos (no tabs), unified search with animated fly-to (semantic aliases + name), L0→L2 LOD zoom, blast-radius context panel, breadcrumb, and clickable universe commands (Option A: exact CLI + copy button). Single self-contained file, no dependencies — unzip and open in any browser.

rg-universe-mockup.zip

[sshaaf]

Navigation — parked (needs a better strategy)

Work on stuffing CFG / DFG / slice / blast / migration into the cosmos HUD is parked. The right-panel analysis tabs (and the follow-up left-rail + drawer experiment) are not a good fit. This is a product/IA problem, not a missing icon.

What’s going wrong

Universe now has too many independent navigation modes without one model that ties them together:

• LOD drill (cosmos → community → package → function)
• Analysis tools (CFG, dataflow, slice, blast, migration) that jump into full legacy-dashboard views
• Always-on spatial context on the right
• Commands overlay

Those analysis views were built for the old tabbed dashboard. Dropping them into a 3D explorer makes it hard to know where you are and what you are looking at.

Suggestion

Treat analysis as downstream of selection, not as a parallel app inside the cosmos:

spatial explore → select a symbol → read the code → then open analysis on that symbol

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.