V1 Web PWA · Surface walkthrough

Studio Aja · Queue Statistics

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

walked + e2e-covered
9sections3 minread
Markdown source
On this page

Context. surface studio · domain aja · route /studio/aja/queue-statistics · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/queue-statistics/page.tsx

Last walked. 2026-07-02 job-queue lane addendum — Playwright real-dev-infra coverage now proves signed-in render, route-map contract, quick-action href order, ready worker-status form, 44 px submit target, blank-workers client guard with no POST, real queue-health output, real unknown-status BFF validation detail, fail-closed loading/unauthorized/catalog-error states, mobile no-overflow, and direct BFF 401/403/400/200 gates for catalog and stats. Spec: apps/oshun/web/e2e/studio-aja-job-queue-lane-consoles.spec.ts.' '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; body re-derived 2026-06-03 from current source (lane-console architecture)

Purpose#

Admin lane console for the real @aja/distributed-workers system-health aggregation. The operator enters the worker pool's per-worker statuses (comma/space separated); the lane reports the status breakdown, the healthy count and fraction, and the overall system-health band (healthy / degraded / unhealthy).

Entry points#

  • Direct URL / bookmark — /studio/aja/queue-statistics; metadata canonical to this path
  • Studio nav — Domain-bridge studios section of /studio
  • Sibling quick-actions on this page: Job Filtering and Search, Back to Studio (no breadcrumb panel on this route)
  • Operator surfacing — see ../../studio-overview.md

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

  • Workspace (<StudioAjaQueueStatisticsWorkspace />, archetype: LEAF):
    • <h1> (WorkspaceHeading) "Aja Queue Statistics Workspace"
    • Summary <p data-aja-queue-statistics-summary> — operations lane aggregates the worker pool's health on the real distributed-workers engine
    • Worker Pool Statistics Operations Lane (<h2 data-aja-qs-lane-heading> "Worker Pool Statistics Operations Lane") — the live stats form
  • Route Map panel (data-aja-queue-statistics-route-map): <h2>Route Map</h2> listing 5 entries from STUDIO_AJA_QUEUE_STATISTICS_ROUTE_MAP (primary, scenes, exports, revisions, governance)
  • Quick-action panel: two Link.quickAction anchors — Job Filtering and Search, Back to Studio workspace index

States#

  • Loading — GETs the engine catalog on mount; renders <p data-aja-qs-loading> "Loading worker engine…"
  • Unauthorized — 401/403 renders data-aja-qs-unauthorized ("Access restricted." + admin-scope message, default "Aja workspace scope required to read queue statistics.")
  • Error — non-OK / malformed / unreachable renders data-aja-qs-error ("Could not load the worker engine." + reason)
  • Ready (form) — success renders data-aja-qs-engine-summary and the data-aja-qs-form
  • Result — a successful POST renders data-aja-qs-result with data-aja-qs-headline (system-health band · healthy/total · percent) and a data-aja-qs-breakdown list of data-aja-qs-breakdown-row per status
  • Validation / stats error — empty worker list or POST failure renders data-aja-qs-stats-error
  • Empty / Standalone PWA / offline — N/A beyond the above; shell SSR, lane is a client fetch on mount

Interactions#

Operations lane (data-aja-qs-form)#

  • Worker statuses (data-aja-qs-workers, input, aria-label "worker statuses", comma/space separated)
  • "Aggregate statistics" (data-aja-qs-submit, submit) — fires POST /v1/admin/aja/queue-statistics/stats with { workers }

Route Map panel#

  • Route entries (5 × <article>) — non-interactive path+purpose

Quick-action panel#

  • "Open Aja Job Filtering and Search workspace" → /studio/aja/job-filtering-and-search
  • "Back to Studio workspace index" → /studio

E2E coverage#

  • apps/oshun/web/e2e/studio-aja-job-queue-lane-consoles.spec.ts covers signed-in shell render, ready worker-status form, blank worker-list client guard with no POST, real BFF healthy-pool output (healthy · 4/5 healthy (80%) with ready/busy/failed breakdown rows), real unknown-status BFF validation detail, route-map count, exact quick-action hrefs, 44 px submit target, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates.

Data & contracts#

  • Reads: GET /v1/admin/aja/queue-statistics on mount — catalog { summary, workerStatuses: string[], healthyStatuses: string[], healthBands }
  • Writes: POST /v1/admin/aja/queue-statistics/stats — { workers } → { result } (total, healthyCount, healthyRatio, systemHealth, breakdown)
  • Realtime: none
  • Caching: client fetch on mount with cache: 'no-store' and buildBffAuthHeaders(); SSR shell only
  • Auth/role check: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); route behind the signed-in + studio proxy gate

Cross-references#

Known downstream boundaries#

  • Route-map sub-routes are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.