V1 Web PWA · Surface walkthrough

Studio Aja - MoCap Input Formats

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/mocap-input-formats · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/aja/mocap-input-formats/page.tsx

Last walked. 2026-07-04 focused real-dev-infra Playwright route walk - anonymous redirect, Aja-admin Alembic-JSON catalog, exact shipped valid document, edited malformed document through the real BFF, local/BFF validation, malformed/transport failures, loading/403/503/malformed catalog states, pending controls, route-map + quick-action affordances, mobile/touch/axe, and direct BFF auth/schema gates. Evidence: WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §296.

Purpose#

Admin lane console wired to the real @aja/motion-formats Alembic-JSON validation via /v1/admin/aja/mocap-input-formats: paste an Alembic-JSON document and the tool runs the ingest pre-flight - format tag, joint hierarchy, time samplings, and metadata checks - then reads back the backend, sample count, fps, and joint count.

Entry points#

  • Direct URL / bookmark - /studio/aja/mocap-input-formats; metadata sets alternates.canonical.
  • Studio nav - Domain-bridge studios section of /studio.
  • Sibling quick-actions from this page - Human Mesh Recovery, Back to Studio.

Layout regions#

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

  • Workspace <StudioAjaMocapInputFormatsWorkspace />:
    • <h1> "Aja MoCap Input Formats Workspace" + summary (data-aja-mocap-input-formats-summary).
    • Capability Summary panel (data-aja-mocap-input-formats-capability-summary, 4 cards).
    • Format Validation Operations Lane (data-aja-mocap-input-formats-operations-lane) with the live Alembic-JSON validator form.
  • Route Map panel (data-aja-mocap-input-formats-route-map): 5 STUDIO_AJA_MOCAP_INPUT_FORMATS_ROUTE_MAP entries exposed with data-aja-mocap-input-formats-route-entry / data-route-path.
  • Quick-action lane (data-aja-mocap-input-formats-quick-actions): two Link.quickAction anchors.

States#

The lane fetches GET /v1/admin/aja/mocap-input-formats on mount.

  • Loading - data-aja-mif-loading "Loading format validator...".
  • Unauthorized - data-aja-mif-unauthorized (401/403; default "Aja workspace scope required to validate mocap input.").
  • Error - data-aja-mif-error for non-OK, malformed catalog, network failure, or unavailable fetch.
  • Ready (form) - data-aja-mif-catalog with validator, error-check count, warning-check count, check spans, and idle data-aja-mif-form.
  • Result - data-aja-mif-result with stable valid/error/warning counts plus format, backend, sample, fps, and joint attributes.
  • Validation error - data-aja-mif-validate-error for blank client input, BFF detail messages, malformed success payloads, and transport failures.
  • Pending - textarea and submit disable while data-aja-mif-form-state="validating" / data-aja-mif-submit-state="validating".
  • Mobile/touch containment - form controls and route actions remain at least 44 px tall with no horizontal overflow.

Interactions#

Validate form (data-aja-mif-form)#

  • Alembic-JSON document - textarea data-aja-mif-content seeded with a valid Alembic-JSON sample.
  • Validate document - submit data-aja-mif-submit; fires POST /v1/admin/aja/mocap-input-formats/validate with { content }; locked with data-aja-mif-submit-state="validating" while the real request is pending.

Capability Summary panel#

  • 4 cards (data-aja-mocap-input-formats-capability=<id>): format-governance-control-plane, diagnostics-and-trace-observability, security-permission-audit-controls, and api-parity-and-contract-assurance - non-interactive.

Route Map panel#

  • Route entries (5) - non-interactive listing with exact path ordering.

Quick-action lane#

  • "Open Aja Human Mesh Recovery workspace" - /studio/aja/human-mesh-recovery
  • "Back to Studio workspace index" - /studio

Data & contracts#

  • Reads: GET /v1/admin/aja/mocap-input-formats (catalog: validator, summary, errorChecks, warningChecks); client fails closed unless the expected alembic-json validator and required error/warning checks are present.
  • Writes: POST /v1/admin/aja/mocap-input-formats/validate → { result: { valid, errors, warnings, info } }; client fails closed unless errors/warnings are string arrays and info contains finite sample, fps, and joint counts.
  • Realtime: none.
  • Caching: client fetch on mount (cache: 'no-store'); SSR shell.
  • Auth/role check: BFF endpoints are admin-scoped and fail-closed (401/403 → unauthorized render); route is gated signed-in + studio via proxy.

Cross-references#

  • Parent: ../../studio-overview.md
  • Sibling from quick-actions: /studio/aja/human-mesh-recovery
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioAjaMocapInputFormatsWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaMocapInputFormatsRouteMap.ts

Verification evidence#

  • apps/oshun/web/e2e/studio-aja-mocap-input-formats.spec.ts runs against the real Next Studio shell and local BFF, forwarding browser bearer auth rather than mocking the Alembic-JSON contract.
  • The spec covers anonymous redirect, Aja-admin catalog load, exact shipped valid-document readback, edited malformed-document errors/warnings, local blank validation with no POST, BFF validation details, malformed result, transport failure, loading / 503 / malformed / non-admin states, pending form locking, mobile no-overflow / 44px controls, scoped axe, and direct BFF 401/403/400/200 gates.

Open questions / known gaps#

  • Route Map lists scenes/exports/revisions/governance child routes that are not yet implemented as pages.