Studio Aja · Blend Shape Retargeting

Purpose#

Admin lane console for the real @aja/blend-shape-retargeting validateRetargetingInput pre-flight. The operator submits source/target blend-shape sets, a global weight scale, a quality threshold, and an optional clip frame count; the lane validates the facial-retarget job before it runs and reads back the blocking errors and advisory warnings plus the source→target shape counts.

Entry points#

• Direct URL / bookmark — /studio/aja/blend-shape-retargeting; metadata canonical to this path
• Studio nav — Domain-bridge studios section of /studio
• Breadcrumb parent — /studio/aja/neural-retargeting (declared in the page.tsx breadcrumb <ol>)
• Sibling quick-actions on this page: Neural Retargeting, Semantic Retargeting, Skeleton-to-Skeleton Retargeting, Back to Studio
• Operator surfacing — see ../../studio-overview.md

Layout regions#

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

• Breadcrumb panel (data-aja-blend-shape-retargeting-breadcrumbs): <nav aria-label="Aja Blend Shape Retargeting breadcrumbs"> → Studio / Aja Neural Retargeting / Blend Shape Retargeting
• Workspace (<StudioAjaBlendShapeRetargetingWorkspace />, archetype: LEAF with a capability summary):
  • <h1> (WorkspaceHeading) "Aja Blend Shape Retargeting Workspace"
  • Summary <p data-aja-blend-shape-retargeting-summary> — typed operations, diagnostics, security, route map; operations lane runs the real pre-flight validator
  • Capability Summary panel (data-aja-blend-shape-retargeting-capability-summary, <h2>Capability Summary</h2>) — 4 data-aja-blend-shape-retargeting-capability cards: retargeting-control-plane, diagnostics-and-trace-observability, security-permission-audit-controls, api-parity-and-contract-assurance
  • Operations lane (data-aja-blend-shape-retargeting-operations-lane, <h2>Blend Shape Retargeting Operations Lane</h2>) — the live validator form
• Route Map panel (data-aja-blend-shape-retargeting-route-map): <h2>Route Map</h2> listing 6 entries from STUDIO_AJA_BLEND_SHAPE_RETARGETING_ROUTE_MAP (primary, scenes, exports, revisions, parity, governance)
• Quick-action panel: four Link.quickAction anchors — Neural Retargeting, Semantic Retargeting, Skeleton-to-Skeleton Retargeting, Back to Studio

States#

• Loading — operations lane GETs the catalog on mount; renders <p data-aja-bsr-loading> "Loading retargeting validator…"
• Unauthorized — 401/403 renders data-aja-bsr-unauthorized ("Access restricted." + admin-scope message, default "Aja workspace scope required to validate retargeting input.")
• Error — non-OK / malformed / unreachable renders data-aja-bsr-error ("Could not load the retargeting validator." + reason)
• Ready (form) — success renders the data-aja-bsr-form
• Result — a successful POST renders data-aja-bsr-result with data-aja-bsr-verdict (✓ ready to retarget / ✗ N blocking error(s) + source→target shape counts), data-aja-bsr-errors (data-aja-bsr-error-row), and either data-aja-bsr-warnings (data-aja-bsr-warning-row) or data-aja-bsr-no-warnings
• Validation error — client guards (weight scale + quality numeric; clip frame count a non-negative integer) and POST failures render data-aja-bsr-validate-error
• Empty / Standalone PWA / offline — N/A beyond the above; shell SSR, lane is a client fetch on mount

Interactions#

Operations lane (data-aja-bsr-form)#

• Source blend shapes (data-aja-bsr-source, input, aria-label "source blend shapes", comma-separated)
• Target blend shapes (data-aja-bsr-target, input, aria-label "target blend shapes", comma-separated)
• Weight scale (data-aja-bsr-weight, input, aria-label "global weight scale")
• Quality threshold (data-aja-bsr-quality, input, aria-label "quality threshold")
• Clip frames (data-aja-bsr-frames, input, aria-label "clip frame count", optional)
• "Validate retargeting input" (data-aja-bsr-submit, submit) — fires POST /v1/admin/aja/blend-shape-retargeting/validate with { sourceBlendShapes, targetBlendShapes, globalWeightScale, qualityThreshold, clipFrameCount? }

Capability Summary#

• Capability cards (4 × <article>) — non-interactive descriptive copy

Route Map panel#

• Route entries (6 × <article>) — non-interactive path+purpose

Quick-action panel#

• "Open Aja Neural Retargeting workspace" → /studio/aja/neural-retargeting
• "Open Aja Semantic Retargeting workspace" → /studio/aja/semantic-retargeting
• "Open Aja Skeleton-to-Skeleton Retargeting workspace" → /studio/aja/skeleton-to-skeleton-retargeting
• "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, route-map count, quick-action hrefs, and 44 px submit target
• client-side nonnumeric quality-threshold guard with no POST
• real BFF warning result for zero weight scale, out-of-range quality threshold, and empty clip
• valid ready-to-retarget result with 3→3 shape counts and No warnings.
• 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/blend-shape-retargeting on mount — catalog { errorChecks: string[], warningChecks: string[] }
• Writes: POST /v1/admin/aja/blend-shape-retargeting/validate → { result } (valid, errors[], warnings[], sourceCount, targetCount)
• Realtime: none
• Caching: client fetch on mount with cache: 'no-store' and buildBffAuthHeaders(); SSR shell only
• Auth/role check: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); route behind the signed-in + studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-aja-neural-retargeting.md (breadcrumb parent), ./studio-aja-semantic-retargeting.md, ./studio-aja-skeleton-to-skeleton-retargeting.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaBlendShapeRetargetingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaBlendShapeRetargetingRouteMap.ts

Known downstream boundaries#

• Capability summary cards are descriptive copy only; the sole live surface is the pre-flight validator.
• Route-map sub-routes are advertised but have no page.tsx in V1; the E2E asserts the current route-map contract only.