---
path: /studio/aja/blend-shape-retargeting
surface: studio
domain: aja
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/aja/blend-shape-retargeting/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-retargeting-lane-consoles Playwright pass — live
  real-BFF catalog/action happy path, fail-closed auth/error states, client/BFF
  validation and warning/result states, mobile overflow, touch target,
  route-map, quick-action, breadcrumb, and direct BFF auth/schema gates.'
---

# 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`](../../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

- [x] **Loading** — operations lane GETs the catalog on mount; renders
      `<p data-aja-bsr-loading>` "Loading retargeting validator…"
- [x] **Unauthorized** — 401/403 renders `data-aja-bsr-unauthorized` ("Access
      restricted." + admin-scope message, default "Aja workspace scope required
      to validate retargeting input.")
- [x] **Error** — non-OK / malformed / unreachable renders `data-aja-bsr-error`
      ("Could not load the retargeting validator." + reason)
- [x] **Ready (form)** — success renders the `data-aja-bsr-form`
- [x] **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`
- [x] **Validation error** — client guards (weight scale + quality numeric; clip
      frame count a non-negative integer) and POST failures render
      `data-aja-bsr-validate-error`
- [x] **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`)

- [x] **Source blend shapes** (`data-aja-bsr-source`, input, aria-label "source
      blend shapes", comma-separated)
- [x] **Target blend shapes** (`data-aja-bsr-target`, input, aria-label "target
      blend shapes", comma-separated)
- [x] **Weight scale** (`data-aja-bsr-weight`, input, aria-label "global weight
      scale")
- [x] **Quality threshold** (`data-aja-bsr-quality`, input, aria-label "quality
      threshold")
- [x] **Clip frames** (`data-aja-bsr-frames`, input, aria-label "clip frame
      count", optional)
- [x] **"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

- [x] **Capability cards** (4 × `<article>`) — non-interactive descriptive copy

### Route Map panel

- [x] **Route entries** (6 × `<article>`) — non-interactive path+purpose

### Quick-action panel

- [x] **"Open Aja Neural Retargeting workspace"** →
      `/studio/aja/neural-retargeting`
- [x] **"Open Aja Semantic Retargeting workspace"** →
      `/studio/aja/semantic-retargeting`
- [x] **"Open Aja Skeleton-to-Skeleton Retargeting workspace"** →
      `/studio/aja/skeleton-to-skeleton-retargeting`
- [x] **"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`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling routes:
  [`./studio-aja-neural-retargeting.md`](./studio-aja-neural-retargeting.md)
  (breadcrumb parent),
  [`./studio-aja-semantic-retargeting.md`](./studio-aja-semantic-retargeting.md),
  [`./studio-aja-skeleton-to-skeleton-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.