V1 Web PWA · Surface walkthrough

Studio Aja · Output Package Contents

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

walked
8sections2 minread
Markdown source
On this page

Context. surface studio · domain aja · route /studio/aja/output-package-contents · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/output-package-contents/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; body re-derived 2026-06-03 from current source (lane-console architecture)

Purpose#

Admin lane console for verifying output-package coverage. Its operations lane wires the @aja/result-aggregation gap detector via /v1/admin/aja/output-package-contents: assemble distributed worker frame-range segments against an expected frame count and detect coverage gaps — each gap is flagged fillable when it is at most maxFillableGapFrames (≤10) frames wide.

Entry points#

  • Direct URL / bookmark — /studio/aja/output-package-contents; metadata sets alternates.canonical
  • Linked from /studio Domain-bridge studios section (Aja sub-area)
  • Quick action — "Open Aja Output Retrieval workspace" (/studio/aja/output-retrieval)

Layout regions#

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

  • Workspace StudioAjaOutputPackageContentsWorkspace — <h1> "Aja Output Package Contents Workspace" + summary (data-aja-output-package-contents-summary), then the Package Coverage Operations Lane (<h2 data-aja-opc-lane-heading>)
  • Route Map panel (data-aja-output-package-contents-route-map, <h2>) — 5 entries from STUDIO_AJA_OUTPUT_PACKAGE_CONTENTS_ROUTE_MAP
  • Quick-action lane — quickAction links: output-retrieval, /studio

States#

  • Loading — data-aja-opc-loading "Loading aggregation engine…" while GET /v1/admin/aja/output-package-contents is in flight
  • Unauthorized (gated) — data-aja-opc-unauthorized on 401/403; admin scope message ("Aja workspace scope required to inspect output packages.")
  • Error — data-aja-opc-error on non-OK / malformed / network failure
  • Ready (form) — data-aja-opc-form once the catalog loads (with the engine summary data-aja-opc-engine-summary)
  • Result — data-aja-opc-result (-headline complete/incomplete + covered/gap counts, -gaps list or -clean) after a successful POST; validation error in data-aja-opc-analyze-error
  • Offline — SSR shell; lane error state when fetch unavailable
  • Standalone PWA — desktop layout; quickAction anchors wrap
  • Empty — N/A; catalog is constant

Interactions#

Package Coverage Operations Lane#

  • Segments (<textarea data-aja-opc-segments>, label "segments json") — JSON array of { start, end } (≥1)
  • Expected frame count (<input data-aja-opc-expected type="number">) — positive integer
  • "Analyze package" (<button data-aja-opc-submit>) — POSTs { segments, expectedCount } to /v1/admin/aja/output-package-contents/analyze

Route Map panel#

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

Quick-action lane#

  • "Open Aja Output Retrieval workspace" → /studio/aja/output-retrieval
  • "Back to Studio workspace index" → /studio

Data & contracts#

  • Reads: GET /v1/admin/aja/output-package-contents (catalog: summary, maxFillableGapFrames) on mount, cache: 'no-store', buildBffAuthHeaders()
  • Writes: POST /v1/admin/aja/output-package-contents/analyze
  • Realtime: none
  • Caching: client fetch on mount (no-store); SSR shell
  • Auth/role check: BFF endpoints admin-scoped, fail-closed (401/403 → unauthorized render); route gated signed-in + studio via the proxy

Cross-references#

Open questions / known gaps#

  • The lane analyzes segment coverage only; it does not list the actual artifact contents of an assembled output package