Studio Aja · Annotation and Collaboration

Purpose#

Admin lane console for collaborative review of motion takes. It wires the real @aja/motion-validation calculateCohensD effect-size estimator: the operator pastes two groups of annotation / rating scores (e.g. baseline vs. candidate motion takes) and reads back Cohen's d, its magnitude band (negligible / small / medium / large), an approximate 95% confidence interval, and each group's mean — the statistic reviewers use to decide whether a change is meaningful, not just noise.

Entry points#

• Direct URL / bookmark — /studio/aja/annotation-and-collaboration; metadata sets alternates.canonical
• Linked from /studio Domain-bridge studios section (Aja sub-area)
• Quick action — "Open Aja Search and Discovery workspace" (/studio/aja/search-and-discovery)

Layout regions#

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

• Workspace StudioAjaAnnotationAndCollaborationWorkspace — <h1> "Aja Annotation and Collaboration Workspace" + summary (data-aja-annotation-and-collaboration-summary), then the effect-size lane (loading / unauthorized / error / form + result)
• Route Map panel (data-aja-annotation-and-collaboration-route-map, <h2> "Route Map") — 5 entries from STUDIO_AJA_ANNOTATION_AND_COLLABORATION_ROUTE_MAP (path + purpose)
• Quick-action lane — two quickAction links: /studio/aja/search-and-discovery, /studio

States#

• Loading — data-aja-ac-loading "Loading effect-size engine…" while the mount fetch of GET /v1/admin/aja/annotation-and-collaboration is in flight
• Unauthorized (gated) — data-aja-ac-unauthorized on 401/403; admin scope message ("Aja workspace scope required to compare annotation groups.")
• Error — data-aja-ac-error on non-OK / malformed / network failure
• Ready (form) — data-aja-ac-form once the catalog loads
• Result — data-aja-ac-result (-value, -means, -ci) after a successful POST; validation error in data-aja-ac-effect-error
• Offline — SSR shell renders from cache; the lane falls to the error state ("Network unavailable.") when fetch is unavailable
• Standalone PWA — desktop layout; quickAction anchors wrap
• Empty — N/A; catalog is constant

Interactions#

Effect-size lane#

• Group 1 scores (<input data-aja-ac-group1>, label "group 1 scores") — comma-separated numbers
• Group 2 scores (<input data-aja-ac-group2>, label "group 2 scores")
• "Compare groups" (<button data-aja-ac-submit>) — POSTs { group1, group2 } to /v1/admin/aja/annotation-and-collaboration/effect-size; requires ≥2 numbers per group

Route Map panel#

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

Quick-action lane#

• "Open Aja Search and Discovery workspace" → /studio/aja/search-and-discovery
• "Back to Studio workspace index" → /studio

E2E coverage#

• apps/oshun/web/e2e/studio-aja-quality-metrics-lane-consoles.spec.ts covers signed-in shell render, 5 route-map entries, exact quick-action hrefs, ready effect-size catalog/form, 44 px submit target, one-value client guard with no POST, exact real BFF Cohen's d result with group means and 95% CI, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates.

Data & contracts#

• Reads: GET /v1/admin/aja/annotation-and-collaboration (catalog: measure, interpretations) on mount, cache: 'no-store', buildBffAuthHeaders()
• Writes: POST /v1/admin/aja/annotation-and-collaboration/effect-size
• Realtime: none
• Caching: client fetch on mount (no-store); SSR shell
• Auth/role check: BFF endpoints admin-scoped, fail-closed (401/403 → unauthorized render); route itself gated signed-in + studio via the proxy

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-aja-search-and-discovery.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaAnnotationAndCollaborationWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaAnnotationAndCollaborationRouteMap.ts

Known downstream boundaries#

• Route-map sub-routes (scenes/[sceneId], exports/[exportId], revisions/[revisionId], governance/[policyId]) are advertised but have no page.tsx yet; implementation status is tracked separately from this leaf console.