V1 Web PWA · Surface walkthrough

Studio Aja · Avatar Integration

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/avatar-integration · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/avatar-integration/page.tsx

Last walked. 2026-07-02 avatar-lane console addendum — Playwright real-dev-infra coverage now proves signed-in render, breadcrumb and route-map contracts, capability card count, quick-action href order, ready form, 44 px submit target, malformed JSON client guard with no POST, real BFF unknown-target 400 detail, real mapped/unmapped/ambiguous result rows, fail-closed loading/unauthorized/ error states, mobile no-overflow, and direct BFF 401/403/400 gates. Spec: apps/oshun/web/e2e/studio-aja-avatar-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 retarget bone-map validation. Its operations lane wires the avatar bone-map validator via /v1/admin/aja/avatar-integration: paste a source/target bone list plus the mapping pairs and the engine classifies each target bone as mapped / unmapped / ambiguous, reports coverage, and lists the per-target status with which source bone(s) each maps from.

Entry points#

  • Direct URL / bookmark — /studio/aja/avatar-integration; metadata sets alternates.canonical
  • Breadcrumb — Studio → Aja → Avatar Integration
  • Linked from /studio Domain-bridge studios section (Aja sub-area)
  • Quick actions — Avatar Library, Avatar Preview, Bone Mapping UI

Layout regions#

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

  • Breadcrumb panel (data-aja-avatar-integration-breadcrumbs) — nav Studio / Aja / Avatar Integration (current)
  • Workspace StudioAjaAvatarIntegrationWorkspace — <h1> "Aja Avatar Integration Workspace" + summary (data-aja-avatar-integration-summary), a Capability Summary panel (data-aja-avatar-integration-capability-summary, 4 capability cards), then the Avatar Integration Operations Lane (data-aja-avatar-integration-operations-lane) embedding the live BoneMapValidatorLane (data-bmv-lane)
  • Route Map panel (data-aja-avatar-integration-route-map, <h2>) — 6 entries from STUDIO_AJA_AVATAR_INTEGRATION_ROUTE_MAP
  • Quick-action lane — quickAction links: avatar-library, avatar-preview, bone-mapping-ui, /studio

States#

  • Loading — data-bmv-loading "Loading bone-map validator…" while GET /v1/admin/aja/avatar-integration is in flight
  • Unauthorized (gated) — data-bmv-unauthorized on 401/403; admin scope message ("Aja workspace scope required to validate the bone map.")
  • Error — data-bmv-error on non-OK / network failure
  • Ready (form) — data-bmv-form once catalog loads
  • Result — data-bmv-result (-coverage, -unmapped, -ambiguous, -targets table) after a successful POST; payload error in data-bmv-validate-error
  • Offline — SSR shell; lane fetch failures collapse into the verified error state.
  • Standalone PWA — no separate implementation beyond the responsive shell; mobile no-overflow is covered by E2E.
  • Empty — N/A; capability cards + route map are constant

Interactions#

Avatar Integration Operations Lane#

  • Bone-map JSON (<textarea data-bmv-payload>, label "bone map json") — { sourceBones, targetBones, mappings }
  • "Validate bone map" (<button data-bmv-submit>) — POSTs the parsed JSON to /v1/admin/aja/avatar-integration/validate; reads back coverage %, valid/invalid, unmapped/ambiguous counts, and a per-target status table

Capability Summary panel#

  • 4 cards (data-aja-avatar-integration-capability=<id>): integration-control-plane, diagnostics-and-trace-observability, security-permission-audit-controls, api-parity-and-contract-assurance — non-interactive

Route Map panel#

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

Quick-action lane#

  • "Open Aja Avatar Library workspace" → /studio/aja/avatar-library
  • "Open Aja Avatar Preview workspace" → /studio/aja/avatar-preview
  • "Open Aja Bone Mapping UI workspace" → /studio/aja/bone-mapping-ui
  • "Back to Studio workspace index" → /studio

E2E coverage#

  • apps/oshun/web/e2e/studio-aja-avatar-lane-consoles.spec.ts covers signed-in shell render, breadcrumb visibility, capability cards, route map shape, exact quick-action hrefs, ready form, 44 px submit target, malformed JSON client guard with no POST, real BFF unknown-target 400 detail, real mapped/unmapped/ambiguous result rows, loading/unauthorized/error fail-closed states, mobile no-overflow, and direct BFF auth/schema gates.

Data & contracts#

  • Reads: GET /v1/admin/aja/avatar-integration on mount, cache: 'no-store', buildBffAuthHeaders()
  • Writes: POST /v1/admin/aja/avatar-integration/validate
  • 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#

Known downstream boundaries#

  • The 4 Capability Summary cards are descriptive copy only; the live affordance is the bone-map validator lane.