Aja Neural Retargeting

Purpose#

Admin lane console whose live lane is a skinning-weight validator wired via /v1/admin/aja/neural-retargeting: per vertex it checks that the bone weights sum to 1 within tolerance and stay within the influence cap, and reports normalized / over-cap / valid counts plus reclaimable detail per vertex.

Entry points#

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

Layout regions#

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

• Breadcrumb panel (data-aja-neural-retargeting-breadcrumbs): nav aria-label="Aja Neural Retargeting breadcrumbs" — Studio (link) / Aja Semantic Retargeting (link) / Neural Retargeting (aria-current="page")
• Workspace panel (data-aja-neural-retargeting-workspace):
  • <h1> "Aja Neural Retargeting Workspace" (via WorkspaceHeading)
  • <p data-aja-neural-retargeting-summary> — "Dedicated Neural Retargeting route with dense expert-mode controls, progressive disclosure, and canonical route map."
  • Capability Summary panel (data-aja-neural-retargeting-capability-summary, <h2> "Capability Summary" + data-aja-neural-retargeting-capability cards — static descriptive copy)
  • The embedded SkinWeightValidatorLane (section data-skw-lane, <h2 data-skw-heading> "Live Skinning-Weight Validator")
• Route Map panel (data-aja-neural-retargeting-route-map): <h2> "Route Map" + one <article> per STUDIO_AJA_NEURAL_RETARGETING_ROUTE_MAP entry (6 entries)
• Quick actions panel: .quickAction <Link>s — see Interactions

States#

• Loading — data-skw-loading "Loading skin-weight validator…"
• Unauthorized — on 401/403, data-skw-unauthorized (admin-scope reason, default "Aja workspace scope required to validate skin weights.")
• Error — non-OK / unreachable → data-skw-error
• Ready (form) — data-skw-form with the JSON payload textarea
• Result — data-skw-result: data-skw-headline (valid/total · data-skw-normalized · data-skw-exceeds) and a data-skw-vertices table (data-skw-sum, data-skw-influences, data-skw-state)
• Validation error — data-skw-validate-error "Payload must be valid JSON."

Interactions#

Capability Summary panel#

• Non-interactive data-aja-neural-retargeting-capability cards (retargeting-control-plane, diagnostics-and-trace-observability, security-permission-audit-controls, api-parity-and-contract-assurance)

Skinning-weight form (data-skw-form)#

• Skin weights JSON — textarea data-skw-payload (default maxInfluences, tolerance, vertices with per-bone weights)
• Validate skin weights — button data-skw-submit; submits parsed JSON to POST /v1/admin/aja/neural-retargeting/validate and returns { result: SkwResult }

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

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

Quick actions panel#

• Open Aja Semantic Retargeting workspace → /studio/aja/semantic-retargeting
• Open Aja Blend Shape Retargeting workspace → /studio/aja/blend-shape-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 malformed JSON guard with no POST
• BFF duplicate-vertex 400 detail surfaced in data-skw-validate-error
• valid skin-weight output: 1/3 valid, 2 normalized, 1 over cap, three vertex rows, valid/denormalized/over-cap row states, and row attributes
• 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/neural-retargeting on mount (response read but only used to gate the lane to ready) via buildBffAuthHeaders(), cache: 'no-store'
• Writes: POST …/validate → { result: SkwResult }
• 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/StudioAjaNeuralRetargetingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaNeuralRetargetingRouteMap.ts
• Embedded by aggregator: apps/oshun/web/src/components/studio/StudioAjaSvcMotionAiWorkspace.tsx (Neural Retargeting Lane)
• Siblings from quick-actions: /studio/aja/semantic-retargeting, /studio/aja/blend-shape-retargeting

Known downstream boundaries#

• The mount GET only gates readiness; the current validator does not render the catalog checks beyond the lane becoming ready.
• 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.