Introducing a new way to review your PRs.

Read the announcement

ruvnet / ruview

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / dashboard-web-app

Dashboard Web App

Overview

The dashboard is a Vite + Lit single-page app rooted at dashboard/index.html, which mounts <nv-app> and loads dashboard/…/main.ts. main.ts imports global CSS, registers the component tree, restores IndexedDB-backed preferences through dashboard/…/persistence.ts, applies theme/density/reduced-motion classes to the document, and boots the simulator transport. Build and local workflow are defined in dashboard/package.json: npm run dev starts Vite, npm run build runs TypeScript then Vite, npm run test runs Vitest with no source tests required, and npm run test:e2e / test:a11y run Playwright.

State is centralized in dashboard/…/appStore.ts as @preact/signals-core signals. UI components subscribe by reading signals inside effect() callbacks and call requestUpdate() when those values change. main.ts is the data-plane bridge: each incoming MagFrameBatch updates lastFrame, recovered B-vector signals, trace arrays, strip bars, FPS/frame counters, and app-runtime event state. Long-lived preferences and session state are persisted to IndexedDB database nvsim, store kv, via keys such as theme, density, motionReduced, wsUrl, transport, repl-history, scene-positions, app-activations, and onboarding-seen.

dashboard/…/nv-app.ts is the top-level shell. It lays out the left rail, topbar, sidebar, central main view, inspector, console, and global overlays. Navigation is local to this shell: nv-rail emits navigate events for home, scene, apps, inspector, witness, and ghost-murmur, and nv-app swaps the central view among nv-home, nv-scene, nv-app-store, expanded nv-inspector, nv-ghost-murmur, or the default scene. Global overlays (nv-toast, nv-modal, nv-palette, nv-debug-hud, nv-settings-drawer, nv-onboarding, nv-help) are always mounted and mostly communicate via window custom events.

The transport abstraction lives in dashboard/…/NvsimClient.ts. Components call getClient() from appStore.ts and only use the NvsimClient interface for scene/config/seed changes, run control, witness operations, proof export, and transient runs. The default dashboard/…/WasmClient.ts creates dashboard/…/worker.ts as an ES module worker. The worker dynamically imports nvsim-pkg/nvsim.js from the Vite BASE_URL, instantiates WasmPipeline, and responds to postMessage RPCs (boot, setScene, setConfig, setSeed, run, pause, step, witness ops, runTransient, buildId). While running, it emits 32 frames per tick as transferred ArrayBuffers. WasmClient parses those bytes with parseFrameBatch() into the 60-byte little-endian MagFrame layout documented in NvsimClient.ts.

The optional server transport is dashboard/…/WsClient.ts. It probes GET /api/health, opens a binary WebSocket at /ws/stream, parses incoming frame bytes with the same parseFrameBatch() helper, and uses REST endpoints for control-plane operations (PUT /api/scene, PUT /api/config, PUT /api/seed, POST /api/run, /pause, /reset, /step, /api/witness/*, /api/export-proof). main.ts restores the selected transport and wsUrl, then an effect reboots the active client when either changes. If WS is selected without a URL, main.ts logs a warning and falls back to WASM.

Main UI surfaces are split by responsibility. dashboard/…/nv-home.ts is the landing page and starts the demo by calling client.run(). dashboard/…/nv-scene.ts renders the SVG scene, run/step controls, zoom/layer controls, persisted draggable source positions, and live |B|/FPS/SNR readouts. dashboard/…/nv-sidebar.ts presents static scene/sensor context and debounces tunable changes for 300 ms before pushing setConfig() to the client. dashboard/…/nv-inspector.ts renders Signal, Frame, and Witness tabs using the store traces, latest decoded frame, expected witness, and client.verifyWitness(). dashboard/…/nv-console.ts is both log viewer and REPL; commands call client methods, mutate store state, export proof bundles, and persist REPL history.

The App Store flow is split between static catalog and live runtime simulation. dashboard/…/apps.ts lists app manifests, categories, default activation state, event IDs, runtime type (running, simulated, or mesh-only), and search helpers. dashboard/…/nv-app-store.ts persists activation toggles, mirrors active app IDs into activeAppIds, and displays app events. dashboard/…/appRuntimes.ts contains the in-browser simulated runtimes for selected apps; main.ts invokes these runtimes for active IDs on each latest frame, passing the recovered B vector and rolling |B| history, then logs emitted events through pushAppEvent() and pushLog().

Support and research views are self-contained Lit components. dashboard/…/nv-ghost-murmur.ts presents the Ghost Murmur physics audit and its “Try it yourself” sandbox, using client.runTransient() with a generated cardiac-dipole scene. In WASM mode this reaches the worker’s runTransient binding; in WS mode WsClient.runTransient() returns a zero-result sentinel because the server does not expose a transient route. dashboard/…/nv-help.ts and dashboard/…/nv-onboarding.ts embed all help/tour content directly in the bundle. dashboard/…/nv-settings-drawer.ts controls appearance, auto-update, transport mode, WS URL, help/tour actions, and IndexedDB reset.

Styling is mostly component-scoped CSS, with shared variables and global body state in dashboard/…/app.css. Vite/PWA behavior is in dashboard/vite.config.ts: the app base defaults to / but can be overridden with NVSIM_BASE, worker output is ES module format, public assets come from dashboard/public, Workbox precaches JS/CSS/HTML/SVG/WASM/font assets, and nvsim-pkg/nvsim.js plus nvsim-pkg/nvsim_bg.wasm are included as PWA assets. Public app icons are dashboard/…/icon-192.svg and dashboard/…/icon-512.svg. Playwright a11y coverage in dashboard/…/a11y.spec.ts builds against the preview server, dismisses the onboarding modal robustly, navigates every primary rail view, and asserts no critical or serious axe violations.

Coupling

Risks

  • dashboard/…/worker.ts and dashboard/…/WasmClient.ts: witness verification is hard-coded around the canonical reference witness with 256 samples and worker-side referenceWitness(). If the Rust proof contract changes sample count, seed, or reference-scene semantics without matching dashboard updates, the UI can report false witness failures or verify the wrong contract.
  • dashboard/…/WsClient.ts: runTransient() returns a zero-result sentinel because WS V1 lacks a transient route. dashboard/…/nv-ghost-murmur.ts displays transient demo output through the same interface, so in WS mode the demo can show zeros and a sentinel witness string rather than a real server-side run.
  • dashboard/…/nv-console.ts and dashboard/…/appRuntimes.ts: log messages are rendered with .innerHTML. Most messages are internal, but REPL command echo and app event details can include user-derived strings; if those inputs become externally sourced, they can become DOM injection paths.
  • dashboard/…/nv-palette.ts: the “New scene” command queries document.querySelector('nv-app')?.shadowRoot?.querySelector('nv-modal'), but nv-modal is rendered inside nv-app's shadow tree and its own controls are inside a nested shadow root. Changes to modal placement or form IDs can silently break scene creation because the command retrieves values by DOM selectors rather than component state.
  • dashboard/…/nv-settings-drawer.ts: “Reset all preferences” calls indexedDB.databases() and deletes every database returned by the browser, not only the nvsim database used by dashboard/…/persistence.ts. If the dashboard origin hosts other apps, this reset can wipe unrelated IndexedDB state on the same origin.