V1 Web PWA · Surface walkthrough

Nyx · Dashboard Widgets

A per-surface walkthrough of the V1 Web PWA customer surface: layout, states, interactions, data, and cross-references.

walked
8sections2 minread
Markdown source
On this page

Context. surface customer · domain nyx · route /domains/nyx/widgets · auth signed-in · source apps/oshun/web/src/app/domains/nyx/widgets/page.tsx

Last walked. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md

Specimen surface. Per P3.4 (2026-05-24), this route is reclassified as a widget-primitive preview page. The three widgets (ISS, Moon, Star Map) shown here are reused as embeds inside other Nyx surfaces and the home dashboard. This is not a canonical customer journey on its own. Sibling specimen: domains-nyx-renderer.md.

Purpose#

Compact dashboard surface that previews three Nyx widget primitives — ISS Tracker, Moon Phase, Star Map — intended for embedding in the home / explore shell. Wired via apps/oshun/web/src/app/domains/nyx/widgets/page.tsx ('use client') which mounts <NyxDashboardWidgets onClose={() => router.back()} />.

Entry points#

  • Direct URL / bookmark — yes (signed-in)
  • In-app navigation — verify Nyx hub link
  • Browser back affordance — in-component back button calls router.back()

Layout regions#

NyxDashboardWidgets (apps/oshun/web/src/components/domains/nyx/NyxDashboardWidgets.tsx):

  • Header: back button (aria-label="Go back"), title <h1>Dashboard Widgets</h1>
  • Widget tab bar (WIDGET_TABS): three tabs — ISS Tracker (iss, Satellite icon), Moon Phase (moon, Moon icon), Star Map (starmap, Star icon)
  • Widget panel: compact preview of the selected widget — ISS Tracker showing live position + pass alert, Moon Phase showing current illumination, Star Map showing a small planisphere

States#

  • Loading — bundled fixture; client-only
  • Default tab — verify which widget is initially active
  • ISS Tracker — current position, next pass time (verify animation/timer)
  • Moon Phase — current illumination percentage
  • Star Map — small planisphere preview
  • Offline — static bundle; widgets that simulate live data continue with cached values

Interactions#

  • "Go back" button (icon, ArrowLeft) — onClose → router.back()

Widget tab bar (three tabs)#

  • ISS Tracker tab — sets activeWidget='iss'
  • Moon Phase tab — sets activeWidget='moon'
  • Star Map tab — sets activeWidget='starmap'

Within each widget#

  • Verify any controls — e.g., zoom / refresh — the widget previews may be read-only

Data & contracts#

  • Reads: bundled fixtures inside the component
  • Writes: none
  • Realtime: verify whether ISS position auto-updates
  • Caching: static client bundle
  • Auth/role check: middleware enforces signed-in for /domains/*

Cross-references#

Open questions / known gaps#

  • Cross-cutting: like /domains/nyx/renderer, this surface looks like a preview gallery for primitives consumed by other routes (home / explore lanes) — clarify whether /domains/nyx/widgets ships as a customer-visible route or is a developer preview
  • Confirm whether each widget links out to its full domain surface on tap
  • Document whether ISS / Moon previews auto-refresh