V1 Web PWA · Surface walkthrough

Studio Aja · Avatar Preview UI

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

walked
8sections3 minread
Markdown source
On this page

Context. surface studio · domain aja · route /studio/aja/avatar-preview-ui · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/avatar-preview-ui/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#

Aggregator workspace that composes the avatar lanes — Avatar Preview, Avatar Library, Avatar Integration, and Bone Mapping UI — into one preview surface, and adds three governance-preview panels built from the design system (disclosure/memory, avatar identity indicators, rights & license summary). It owns no /v1 fetch; the live lane data comes from the embedded leaves. The page adds a Capability Summary, a breadcrumb, a Route Map, and a quick-action lane.

Entry points#

  • Direct URL / bookmark — /studio/aja/avatar-preview-ui.
  • Studio nav — Domain-bridge studios section of /studio.
  • Breadcrumb parent — /studio/aja/avatar-preview.
  • Quick-actions — Avatar Preview, Avatar Library, Avatar Integration, Bone Mapping UI.

Layout regions#

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

  • Breadcrumb panel (data-aja-avatar-preview-ui-breadcrumbs): <nav aria-label="Aja Avatar Preview UI breadcrumbs"> → Studio (link) / Aja Avatar Preview (link → /studio/aja/avatar-preview) / Avatar Preview UI (aria-current="page").
  • Workspace <StudioAjaAvatarPreviewUiWorkspace />:
    • <h1> "Aja Avatar Preview UI Workspace" + summary (data-aja-avatar-preview-ui-summary).
    • Capability Summary (data-aja-avatar-preview-ui-capability-summary, <h2>) — 4 cards (data-aja-avatar-preview-ui-capability=<id>): Preview Orchestration Control Plane, Diagnostics and Trace Observability, Security/Permission/Audit Controls, API Parity and Contract Assurance.
    • Disclosure Governance Preview (data-aja-avatar-preview-ui-disclosure-governance, <h2>) — AssistantDisclosureStrip + AssistantMemoryState (design-system, static).
    • Avatar Identity Indicator Preview (data-aja-avatar-preview-ui-identity-governance, <h2>) — identity chips
      • AvatarPackCards (data-aja-avatar-preview-ui-identity=<id>) + lineage note (data-aja-avatar-preview-ui-identity-lineage).
    • Rights and License Summary Preview (data-aja-avatar-preview-ui-rights-license-governance, <h2>) — RightsSummaryCards (data-aja-avatar-preview-ui-rights-summary) + LicenseSummaryCards (data-aja-avatar-preview-ui-license-summary) + note.
    • Avatar Preview Lane (data-aja-avatar-preview-ui-preview-lane) → embeds <StudioAjaAvatarPreviewWorkspace />.
    • Avatar Library Lane (data-aja-avatar-preview-ui-library-lane) → embeds <StudioAjaAvatarLibraryWorkspace />.
    • Avatar Integration Lane (data-aja-avatar-preview-ui-integration-lane) → embeds <StudioAjaAvatarIntegrationWorkspace />.
    • Bone Mapping UI Lane (data-aja-avatar-preview-ui-bone-mapping-lane) → embeds <StudioAjaBoneMappingUiWorkspace />.
  • Route Map panel (data-aja-avatar-preview-ui-route-map, <h2> "Route Map"): 6 STUDIO_AJA_AVATAR_PREVIEW_UI_ROUTE_MAP entries.
  • Quick-action lane: five Link.quickAction anchors (no self-link).

States#

No own data fetch; runtime state is per embedded lane (each leaf runs its own Loading / Unauthorized / Error / Ready lifecycle). The three governance-preview panels are static design-system renders.

  • Loading — per embedded lane.
  • Unauthorized — per embedded lane (admin-scope 401/403).
  • Error — per embedded lane.
  • Populated — governance panels + all four lanes render.
  • Empty — N/A; cards, governance panels, and lanes always render.

Interactions#

  • "Studio" → /studio
  • "Aja Avatar Preview" → /studio/aja/avatar-preview
  • "Avatar Preview UI" — aria-current="page"

Workspace body#

  • Capability cards (4) — non-interactive.
  • Disclosure / Identity / Rights-License preview panels — design-system previews, non-interactive.
  • Avatar Preview Lane → embeds StudioAjaAvatarPreviewWorkspace.
  • Avatar Library Lane → embeds StudioAjaAvatarLibraryWorkspace.
  • Avatar Integration Lane → embeds StudioAjaAvatarIntegrationWorkspace.
  • Bone Mapping UI Lane → embeds StudioAjaBoneMappingUiWorkspace.

Route Map#

  • Route entries (6) — non-interactive listing.

Quick-action lane#

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

Data & contracts#

  • Reads: none at page level — delegated to the embedded leaves, which fetch their own catalogs on mount. The governance panels are built from design-system helpers (buildAvatarVoiceIdentityCollection, buildRightsLicenseSummaryCollection, buildAssistantDisclosureIndicators), not from /v1.
  • Writes: none at page level; each leaf fires its own POST verbs.
  • Realtime: none.
  • Caching: client fetch on mount (cache: 'no-store') per leaf; SSR shell.
  • Auth/role check: BFF endpoints admin-scoped + fail-closed per lane; route gated signed-in + studio via proxy.

Cross-references#

  • Parent: ../../studio-overview.md
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioAjaAvatarPreviewUiWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaAvatarPreviewUiRouteMap.ts

Open questions / known gaps#

  • The four embedded lanes are not yet in this walkthrough sweep — link once those files are created.