V1 Web PWA · Surface walkthrough

Studio Aja · Batch Operations

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

Last walked. 2026-07-02 developer-ops lane addendum — Playwright real-dev-infra coverage now proves signed-in render, route-map contract, quick-action href order, ready memory/FPS sizing forms, 44 px submit targets, memory/FPS client guards with no POST, real memory-fit and throughput sizing results, fail-closed loading/unauthorized/catalog-error states, mobile no-overflow, and direct BFF 401/403/400/200 gates for catalog and both sizing actions. Spec: apps/oshun/web/e2e/studio-aja-developer-ops-lane-consoles.spec.ts.' '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)

Purpose#

Leaf lane console that wires the real @aja/batch-inference batch sizers. It exposes two computations: pick a memory-fit power-of-two batch size for a GPU memory budget, and rescale a batch toward a target FPS given the current batch and latency.

Entry points#

  • Direct URL / bookmark — /studio/aja/batch-operations.
  • Studio nav — Domain-bridge studios section of /studio.
  • Embedded — appears as the Batch Operations Lane inside /studio/aja/distributed-workers.
  • Sibling quick-action — "Open Aja Avatar Integration workspace" (/studio/aja/avatar-integration).

Layout regions#

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

  • Workspace <StudioAjaBatchOperationsWorkspace />:
    • <h1> "Aja Batch Operations Workspace" + summary (data-aja-batch-operations-summary).
    • Batch Sizing Operations Lane (heading data-aja-bo-lane-heading) — the two forms; includes data-aja-bo-engine-summary (catalog summary).
  • Route Map panel (data-aja-batch-operations-route-map, <h2> "Route Map"): 5 STUDIO_AJA_BATCH_OPERATIONS_ROUTE_MAP entries — primary, scenes, exports, revisions, governance.
  • Quick-action lane: two Link.quickAction anchors. No breadcrumb panel.

States#

The lane fetches GET /v1/admin/aja/batch-operations on mount.

  • Loading — data-aja-bo-loading "Loading batch-inference engine…".
  • Unauthorized — data-aja-bo-unauthorized (401/403; default "Aja workspace scope required to size batches.").
  • Error — data-aja-bo-error.
  • Ready (forms) — data-aja-bo-mem-form + data-aja-bo-fps-form.
  • Memory result — data-aja-bo-mem-result (batch size, (clamped)).
  • FPS result — data-aja-bo-fps-result (batch size, (clamped)).
  • Validation errors — data-aja-bo-mem-error / data-aja-bo-fps-error (e.g. "Memory values must be positive numbers.").

Interactions#

Memory-fit form (data-aja-bo-mem-form)#

  • Available memory (bytes) — input data-aja-bo-mem (default 8589934592).
  • Per-frame memory (bytes) — input data-aja-bo-perframe (default 104857600).
  • Size for memory — submit data-aja-bo-mem-submit; fires POST /v1/admin/aja/batch-operations/initial-batch-size.

FPS form (data-aja-bo-fps-form)#

  • Target FPS — input data-aja-bo-fps (default 30).
  • Current batch — input data-aja-bo-curbatch (default 8).
  • Current latency (ms) — input data-aja-bo-latency (default 200).
  • Size for FPS — submit data-aja-bo-fps-submit; fires POST /v1/admin/aja/batch-operations/fps-batch-size.

Route Map#

  • Route entries (5) — non-interactive listing.

Quick-action lane#

  • "Open Aja Avatar Integration workspace" → /studio/aja/avatar-integration
  • "Back to Studio workspace index" → /studio

E2E coverage#

  • apps/oshun/web/e2e/studio-aja-developer-ops-lane-consoles.spec.ts covers signed-in shell render, ready memory/FPS forms, non-positive memory and invalid current-batch client guards with no POST, real memory-fit outputs (32 (clamped) and 4), real throughput outputs (7 and 10), route-map count, exact quick-action hrefs, 44 px submit targets, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates for both sizing actions.

Data & contracts#

  • Reads: GET /v1/admin/aja/batch-operations (catalog: summary, memorySizer, fpsSizer).
  • Writes: POST /v1/admin/aja/batch-operations/initial-batch-size and POST /v1/admin/aja/batch-operations/fps-batch-size, each → { batchSize, clamped }.
  • Realtime: none.
  • Caching: client fetch on mount (cache: 'no-store'); SSR shell.
  • Auth/role check: BFF endpoints admin-scoped + fail-closed; route gated signed-in + studio via proxy.

Cross-references#

  • Parent: ../../studio-overview.md
  • Aggregator that embeds this lane: ./studio-aja-distributed-workers.md
  • Sibling (quick-action): /studio/aja/avatar-integration
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioAjaBatchOperationsWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaBatchOperationsRouteMap.ts

Known downstream boundaries#

  • Route-map sub-routes are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.