V1 Web PWA · Surface walkthrough

Aja Semantic Retargeting

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/semantic-retargeting · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/semantic-retargeting/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); 2026-07-02 studio-aja-retargeting-lane-consoles Playwright pass — live real-BFF catalog/action happy path, fail-closed auth/error states, defensive empty-catalog client guard, mobile overflow, touch target, route-map, quick-action, breadcrumb, and direct BFF auth/schema gates.

Purpose#

Admin lane console wired to the real @aja/proportional-adaptation computeAllLimbScales via /v1/admin/aja/semantic-retargeting: pick a source and target skeleton template and compute the per-limb scale factors between them — the proportional component of retargeting motion onto a differently-proportioned body.

Entry points#

  • Direct URL — /studio/aja/semantic-retargeting (signed-in + studio entitlement)
  • Breadcrumb — Studio / Aja Proportional Adaptation / Semantic Retargeting
  • Sibling quick-actions from this page — Proportional Adaptation, Back to Studio

Layout regions#

page.tsx mounts ShellLayout with active="studio" and renders four panels.

  • Breadcrumb panel (data-aja-semantic-retargeting-breadcrumbs): nav aria-label="Aja Semantic Retargeting breadcrumbs" — Studio (link) / Aja Proportional Adaptation (link) / Semantic Retargeting (aria-current="page")
  • Workspace panel (data-aja-semantic-retargeting-workspace):
    • <h1> "Aja Semantic Retargeting Workspace" (via WorkspaceHeading)
    • <p data-aja-semantic-retargeting-summary> — "Dedicated Semantic Retargeting route with typed operations, diagnostics, security controls, and canonical route map. The operations lane computes the real per-limb scale factors between a source and target skeleton."
    • Capability Summary panel (data-aja-semantic-retargeting-capability-summary, <h2> "Capability Summary" + data-aja-semantic-retargeting-capability cards — static descriptive copy)
    • <section data-aja-semantic-retargeting-operations-lane> <h2> "Limb Scaling Operations Lane" wrapping data-aja-sr-op-summary + the compute form
  • Route Map panel (data-aja-semantic-retargeting-route-map): <h2> "Route Map" + one <article> per STUDIO_AJA_SEMANTIC_RETARGETING_ROUTE_MAP entry (6 entries)
  • Quick actions panel: .quickAction <Link>s — see Interactions

States#

  • Loading — data-aja-sr-loading "Loading skeleton templates…"
  • Unauthorized — on 401/403, data-aja-sr-unauthorized ("Access restricted." + reason, default "Aja workspace scope required to compute limb scales.")
  • Error — non-OK / malformed / unreachable → data-aja-sr-error
  • Ready (form) — catalog present: data-aja-sr-op-summary + the compute form (source/target preselected from the loaded templates)
  • Result — data-aja-sr-result: data-aja-sr-headline (source → target · N limbs) and a data-aja-sr-limbs list (data-aja-sr-limb-row)
  • Validation error — data-aja-sr-compute-error "Select a source and target template."

Interactions#

Compute form (data-aja-sr-form)#

  • Source skeleton — select data-aja-sr-source (from catalog.templates)
  • Target skeleton — select data-aja-sr-target (from catalog.templates)
  • Compute limb scales — button data-aja-sr-submit; submits { sourceId, targetId } to POST /v1/admin/aja/semantic-retargeting/limb-scales and returns { result: ScalesResult }

Route Map panel (data-aja-semantic-retargeting-route-map)#

Non-interactive <article> blocks from STUDIO_AJA_SEMANTIC_RETARGETING_ROUTE_MAP (6 entries): /studio/aja/semantic-retargeting plus …/scenes/[sceneId], …/exports/[exportId], …/revisions/[revisionId], …/parity/[parityId], …/governance/[governanceId].

Quick actions panel#

  • Open Aja Proportional Adaptation workspace → /studio/aja/proportional-adaptation
  • Back to Studio workspace index → /studio

E2E coverage#

apps/oshun/web/e2e/studio-aja-retargeting-lane-consoles.spec.ts covers this route against the real Next shell and real BFF:

  • live admin catalog load, breadcrumb panel, capability cards, ready form with eight template options, route-map count, quick-action hrefs, and 44 px submit target
  • valid real BFF limb-scale output for mixamo-standard → unity-humanoid, including six limb rows and exact left-arm/left-leg scale values
  • defensive empty-template catalog guard that renders data-aja-sr-compute-error and sends no POST
  • loading, unauthorized, and catalog error states fail closed with no form/result
  • mobile viewport horizontal-overflow check
  • direct BFF 401, wrong-scope 403, and invalid-payload 400 gates

Data & contracts#

  • Reads: GET /v1/admin/aja/semantic-retargeting (catalog: operation, summary, templates) on mount via buildBffAuthHeaders(), cache: 'no-store'
  • Writes: POST …/limb-scales → { result } (sourceId, targetId, limbScales)
  • Realtime: none
  • Caching: client fetch on mount (no-store); SSR shell only
  • Auth: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); the route is signed-in + studio (proxy gate)

Cross-references#

  • Parent: ../../studio-overview.md
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioAjaSemanticRetargetingWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaSemanticRetargetingRouteMap.ts
  • Sibling from quick-actions: /studio/aja/proportional-adaptation

Known downstream boundaries#

  • Capability Summary cards are static descriptive copy; the E2E asserts card presence/count rather than live data.
  • Route-map sub-routes are descriptive only; the E2E asserts the current route map contract, not child page existence.
  • Studio entitlement / proxy policy remains a shell-auth boundary outside this lane console.