V1 Web PWA · Surface walkthrough

Aja Video Analysis

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked + e2e-covered
9sections3 minread
Markdown source
On this page

Context. surface studio · domain aja · route /studio/aja/video-analysis · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/video-analysis/page.tsx

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-motion-lane-consoles Playwright pass covers live BFF catalog/analyze, auth/schema gates, error states, quick actions, route map, and mobile no-overflow.

Purpose#

Admin lane console wired to the real @aja/motion-quality analyzeJitter via /v1/admin/aja/video-analysis: it takes the acceleration of every joint's trajectory across a video-derived motion, scores high-frequency-noise jitter, and flags the frames whose acceleration exceeds a threshold — reading back the jitter score, average/peak acceleration, per-joint scores, and problematic frame indices.

Entry points#

  • Direct URL — /studio/aja/video-analysis (signed-in + studio entitlement)
  • Sibling quick-actions from this page — Motion Enhancement, Back to Studio

Layout regions#

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

  • Workspace panel (data-aja-video-analysis-workspace):
    • <h1> "Aja Video Analysis Workspace" (via WorkspaceHeading)
    • <p data-aja-video-analysis-summary> — "Dedicated Video Analysis route with typed operations, diagnostics, security controls, and canonical route map. The operations lane runs the real jitter analyzer — high-frequency acceleration noise — over a video-derived motion."
    • Capability Summary panel (data-aja-video-analysis-capability-summary, <h2> "Capability Summary" + data-aja-video-analysis-capability cards — static descriptive copy)
    • <section data-aja-video-analysis-operations-lane> <h2> "Video Analysis Operations Lane" wrapping data-aja-va-analyzer-summary + the analyze form
  • Route Map panel (data-aja-video-analysis-route-map): <h2> "Route Map" + one <article> per STUDIO_AJA_VIDEO_ANALYSIS_ROUTE_MAP entry (5 entries)
  • Quick actions panel: .quickAction <Link>s — see Interactions

States#

  • Loading — data-aja-va-loading "Loading jitter analyzer…"
  • Unauthorized — on 401/403, data-aja-va-unauthorized ("Access restricted." + reason, default "Aja workspace scope required to analyze video motion.")
  • Error — non-OK / malformed / unreachable → data-aja-va-error
  • Ready (form) — catalog present: data-aja-va-analyzer-summary + the analyze form
  • Result — data-aja-va-result: data-aja-va-headline (jitter score · N problematic frames), data-aja-va-accel (avg/peak), data-aja-va-frames-flagged or data-aja-va-clean, and a data-aja-va-per-joint list
  • Validation error — data-aja-va-analyze-error (e.g. "Provide at least 4 frames." / "Acceleration threshold must be a positive number.")

Interactions#

Analyze form (data-aja-va-form)#

  • Joint ids (comma-separated) — input data-aja-va-joints
  • Frames (JSON array, ≥4) — textarea data-aja-va-frames
  • Acceleration threshold — input data-aja-va-threshold
  • Analyze jitter — button data-aja-va-submit; POST /v1/admin/aja/video-analysis/analyze with { joints, frames, accelerationThreshold } → { result: AnalyzeResult }

Route Map panel (data-aja-video-analysis-route-map)#

Non-interactive <article> blocks from STUDIO_AJA_VIDEO_ANALYSIS_ROUTE_MAP (5 entries): /studio/aja/video-analysis plus …/scenes/[sceneId], …/exports/[exportId], …/revisions/[revisionId], …/governance/[policyId].

Quick actions panel#

  • Open Aja Motion Enhancement workspace → /studio/aja/motion-enhancement
  • Back to Studio workspace index → /studio

E2E coverage#

Coverage depth: deep.

  • studio-aja-motion-lane-consoles.spec.ts drives /studio/aja/video-analysis through the live jitter catalog, malformed-JSON client guard with no POST, real BFF 400 missing-joint validation detail, oscillating-motion analysis, exact jitter score / acceleration / flagged-frame / per-joint output, route-map count, 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/video-analysis (catalog: analyzer, summary, defaultAccelerationThreshold, reports) on mount via buildBffAuthHeaders(), cache: 'no-store'
  • Writes: POST …/analyze → { result } (score, average/peak acceleration, perJointScores, problematicFrames)
  • 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/StudioAjaVideoAnalysisWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaVideoAnalysisRouteMap.ts
  • Embedded by aggregator: apps/oshun/web/src/components/studio/StudioAjaSvcMotionAiWorkspace.tsx (Video Analysis Lane)
  • Sibling from quick-actions: /studio/aja/motion-enhancement

Known downstream boundaries#

  • Capability Summary cards are static descriptive copy; the browser spec asserts the 4-card contract, not a data-backed catalog.
  • Route-map sub-routes are descriptive only; the browser spec asserts the current 5-entry map but does not claim those dynamic sub-routes are implemented.
  • The browser spec enters through the authenticated Studio shell and exercises the BFF admin fail-closed gates. Any future /studio/aja/* proxy entitlement policy split remains a shell-auth contract change.