V1 Web PWA · Surface walkthrough

Studio Aja · Bone Mapping UI

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/bone-mapping-ui · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/bone-mapping-ui/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 and 8-template catalog, 44 px submit target, empty-selection client guard with no POST, real BFF unknown-template 404 detail, real COCO-17 inspection 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 inspecting built-in skeleton templates. Its operations lane wires @aja/skeleton-mapping via /v1/admin/aja/bone-mapping-ui: pick a template and read back its structure — joint/bone counts, supported body regions, left↔right mirror joint pairs (for symmetric mapping), IK targets, spine segments, and finger/facial tracking flags — the reference data a retarget bone-map is built against.

Entry points#

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

Layout regions#

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

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

States#

  • Loading — data-aja-bm-loading "Loading skeleton templates…" while GET /v1/admin/aja/bone-mapping-ui is in flight
  • Unauthorized (gated) — data-aja-bm-unauthorized on 401/403; admin scope message ("Aja workspace scope required to inspect skeleton templates.")
  • Error — data-aja-bm-error on non-OK / malformed / network failure
  • Ready (form) — data-aja-bm-form once the template catalog loads (the first template id is auto-selected)
  • Result — data-aja-bm-result (-headline joints/bones, -flags regions/spine/finger/facial, -mirror/-mirror-list, -ik) after a successful POST; selection error in data-aja-bm-inspect-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#

Bone Mapping UI Operations Lane#

  • Skeleton template (<select data-aja-bm-template>, label "skeleton template") — options from the catalog ({name} ({id}))
  • "Inspect template" (<button data-aja-bm-submit>) — POSTs { templateId } to /v1/admin/aja/bone-mapping-ui/inspect

Capability Summary panel#

  • 4 cards (data-aja-bone-mapping-ui-capability=<id>): mapping-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 Preview workspace" → /studio/aja/avatar-preview
  • "Open Aja Avatar Preview UI workspace" → /studio/aja/avatar-preview-ui
  • "Open Aja Avatar Integration workspace" → /studio/aja/avatar-integration
  • "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, 8-template catalog, ready form, 44 px submit target, empty-selection client guard with no POST, real BFF unknown-template 404 detail, real COCO-17 inspection output, loading/ unauthorized/error fail-closed states, mobile no-overflow, and direct BFF auth/schema gates.

Data & contracts#

  • Reads: GET /v1/admin/aja/bone-mapping-ui (template catalog) on mount, cache: 'no-store', buildBffAuthHeaders()
  • Writes: POST /v1/admin/aja/bone-mapping-ui/inspect
  • 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 lane inspects templates read-only; authoring or persisting custom bone maps belongs to a separate editor workflow.