V1 Web PWA · Surface walkthrough

Aja Face Tracking

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/face-tracking · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/face-tracking/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-tracking-lane-consoles Playwright pass — live real-BFF catalog/action happy path, fail-closed auth/error states, client/BFF validation errors, mobile overflow, touch target, route-map, quick-action, and direct BFF auth/schema gates.

Purpose#

Admin lane console whose single lane is a live blendshape-coverage validator wired via /v1/admin/aja/face-tracking: it compares the rig's provided blendshapes against the tracker's required set and reports coverage percentage, missing, and extra blendshapes (the readiness check for driving a face rig from the tracker).

Entry points#

  • Direct URL — /studio/aja/face-tracking (signed-in + studio entitlement)
  • Sibling quick-actions from this page — Hand Tracking, Back to Studio

Layout regions#

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

  • Workspace panel (data-aja-face-tracking-workspace):
    • <h1> "Aja Face Tracking Workspace" (via WorkspaceHeading)
    • <p data-aja-face-tracking-summary> — "Dedicated Face Tracking route with dense expert-mode controls, progressive disclosure, and canonical route map."
    • The embedded BlendshapeCoverageLane (section data-bsc-lane, <h2 data-bsc-heading> "Live Blendshape-Coverage Validator")
  • Route Map panel (data-aja-face-tracking-route-map): <h2> "Route Map" + one <article> per STUDIO_AJA_FACE_TRACKING_ROUTE_MAP entry (5 entries)
  • Quick actions panel: .quickAction <Link>s — see Interactions

States#

  • Loading — data-bsc-loading "Loading blendshape-coverage validator…"
  • Unauthorized — on 401/403, data-bsc-unauthorized (admin-scope reason, default "Aja workspace scope required to validate blendshapes.")
  • Error — non-OK / unreachable → data-bsc-error
  • Ready (form) — data-bsc-form with the JSON payload textarea
  • Result — data-bsc-result: data-bsc-headline (coverage % · complete/incomplete · data-bsc-missing · data-bsc-extra) and a data-bsc-required table of required blendshapes with covered state
  • Validation error — data-bsc-validate-error "Payload must be valid JSON."

Interactions#

Blendshape-coverage form (data-bsc-form)#

  • Blendshapes JSON — textarea data-bsc-payload (default requiredBlendshapes + providedBlendshapes arrays)
  • Validate coverage — button data-bsc-submit; submits parsed JSON to POST /v1/admin/aja/face-tracking/validate and returns { result: BscResult }

Route Map panel (data-aja-face-tracking-route-map)#

Non-interactive <article> blocks from STUDIO_AJA_FACE_TRACKING_ROUTE_MAP (5 entries): /studio/aja/face-tracking plus …/scenes/[sceneId], …/exports/[exportId], …/revisions/[revisionId], …/governance/[policyId].

Quick actions panel#

  • Open Aja Hand Tracking workspace → /studio/aja/hand-tracking
  • Back to Studio workspace index → /studio

E2E coverage#

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

  • live admin catalog load, ready form, route-map count, quick-action hrefs, and 44 px submit target
  • client-side malformed JSON guard with no POST
  • BFF duplicate-required-set 400 detail surfaced in data-bsc-validate-error
  • valid blendshape coverage output: 80% coverage, 1 missing, 2 extra, required table rows, and covered/missing row states
  • 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/face-tracking on mount (catalog response read but only used to gate the lane to ready) via buildBffAuthHeaders(), cache: 'no-store'
  • Writes: POST /v1/admin/aja/face-tracking/validate → coverage result
  • 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/StudioAjaFaceTrackingWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaFaceTrackingRouteMap.ts
  • Sibling from quick-actions: /studio/aja/hand-tracking

Known downstream boundaries#

  • The mount GET only gates readiness; the current validator does not render a catalog or required-set preview.
  • 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.