--- path: /studio/aja/face-tracking surface: studio domain: aja auth: signed-in + studio entitlement source: apps/oshun/web/src/app/studio/aja/face-tracking/page.tsx status: walked + e2e-covered 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.' --- # Aja Face Tracking ## 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`): - `

` "Aja Face Tracking Workspace" (via `WorkspaceHeading`) - `

` — "Dedicated Face Tracking route with dense expert-mode controls, progressive disclosure, and canonical route map." - The embedded `BlendshapeCoverageLane` (`section data-bsc-lane`, `

` "Live Blendshape-Coverage Validator") - **Route Map panel** (`data-aja-face-tracking-route-map`): `

` "Route Map" + one `
` per `STUDIO_AJA_FACE_TRACKING_ROUTE_MAP` entry (5 entries) - **Quick actions panel**: `.quickAction` ``s — see Interactions ## States - [x] **Loading** — `data-bsc-loading` "Loading blendshape-coverage validator…" - [x] **Unauthorized** — on 401/403, `data-bsc-unauthorized` (admin-scope reason, default "Aja workspace scope required to validate blendshapes.") - [x] **Error** — non-OK / unreachable → `data-bsc-error` - [x] **Ready (form)** — `data-bsc-form` with the JSON payload textarea - [x] **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 - [x] **Validation error** — `data-bsc-validate-error` "Payload must be valid JSON." ## Interactions ### Blendshape-coverage form (`data-bsc-form`) - [x] **Blendshapes JSON** — `textarea data-bsc-payload` (default `requiredBlendshapes` + `providedBlendshapes` arrays) - [x] **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 `
` 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 - [x] **Open Aja Hand Tracking workspace** → `/studio/aja/hand-tracking` - [x] **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`](../../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.