Studio Aja · Motion Enhancement

Purpose#

Admin lane console for the real @aja/motion-validation calculateTemporalMetrics dynamics scorer. The operator submits an enhanced/smoothed motion and a reference motion (each a { joints, frames } JSON of ≥4 frames); the lane compares the finite-difference velocity and acceleration of the two, plus jerk (third derivative) on both and a smoothness ratio capped at 1, and reads back the per-joint velocity/acceleration error, jerk, and smoothness.

Entry points#

• Direct URL / bookmark — /studio/aja/motion-enhancement; metadata canonical to this path
• Studio nav — Domain-bridge studios section of /studio
• Sibling quick-actions on this page: Annotation and Collaboration, Back to Studio (no breadcrumb panel on this route)
• Operator surfacing — see ../../studio-overview.md

Layout regions#

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

• Workspace (<StudioAjaMotionEnhancementWorkspace />, archetype: LEAF with a capability summary):
  • <h1> (WorkspaceHeading) "Aja Motion Enhancement Workspace"
  • Summary <p data-aja-motion-enhancement-summary> — operations lane scores an enhanced motion's dynamics (velocity, acceleration, jerk, smoothness) against a reference
  • Capability Summary panel (data-aja-motion-enhancement-capability-summary, <h2>Capability Summary</h2>) — 4 data-aja-motion-enhancement-capability cards: enhancement-control-plane, diagnostics-and-trace-observability, security-permission-audit-controls, api-parity-and-contract-assurance
  • Operations lane (data-aja-motion-enhancement-operations-lane, <h2>Motion Enhancement Operations Lane</h2>) — the live assess form
• Route Map panel (data-aja-motion-enhancement-route-map): <h2>Route Map</h2> listing 5 entries from STUDIO_AJA_MOTION_ENHANCEMENT_ROUTE_MAP (primary, scenes, exports, revisions, governance)
• Quick-action panel: two Link.quickAction anchors — Annotation and Collaboration, Back to Studio workspace index

States#

• Loading — operations lane GETs the dynamics catalog on mount; renders <p data-aja-me-loading> "Loading dynamics metric…"
• Unauthorized — 401/403 renders data-aja-me-unauthorized ("Access restricted." + admin-scope message, default "Aja workspace scope required to score motion dynamics.")
• Error — non-OK / malformed / unreachable renders data-aja-me-error ("Could not load the dynamics metric." + reason)
• Ready (form) — success renders data-aja-me-metric-summary and the data-aja-me-form
• Result — a successful POST renders data-aja-me-result with data-aja-me-smoothness (smoothness · jerk ratio), data-aja-me-velocity, data-aja-me-acceleration, and a data-aja-me-per-joint list of data-aja-me-joint-row
• Validation / assess error — client guards (processed + reference valid JSON) and POST failures render data-aja-me-assess-error
• Empty / Standalone PWA / offline — N/A beyond the above; shell SSR, lane is a client fetch on mount

Interactions#

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

• Processed motion (data-aja-me-processed, textarea, aria-label "processed motion json", JSON { joints, frames }, ≥4 frames)
• Reference motion (data-aja-me-reference, textarea, aria-label "reference motion json", JSON { joints, frames }, ≥4 frames)
• "Compare dynamics" (data-aja-me-submit, submit) — fires POST /v1/admin/aja/motion-enhancement/assess with { processed, reference }

Capability Summary#

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

Route Map panel#

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

Quick-action panel#

• "Open Aja Annotation and Collaboration workspace" → /studio/aja/annotation-and-collaboration
• "Back to Studio workspace index" → /studio

E2E coverage#

Coverage depth: deep.

• studio-aja-motion-lane-consoles.spec.ts drives /studio/aja/motion-enhancement through the live temporal-dynamics catalog, malformed-JSON client guard with no POST, real BFF 400 short-motion validation detail, exact velocity / acceleration / jerk / smoothness result for an accelerating motion against a linear reference, 4 capability cards, 5 route-map entries, exact quick-action hrefs, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, 44 px submit target, and direct BFF 401 / 403 / 400 gates.

Data & contracts#

• Reads: GET /v1/admin/aja/motion-enhancement on mount — catalog { metric, summary, measures: string[] }
• Writes: POST /v1/admin/aja/motion-enhancement/assess — { processed, reference } → { result } (velocityError, accelerationError, jerk, smoothness)
• 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-annotation-and-collaboration.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaMotionEnhancementWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaMotionEnhancementRouteMap.ts

Known downstream boundaries#

• Route-map sub-routes are advertised but have no page.tsx in V1; the browser spec asserts the current 5-entry descriptive route map only.