V1 Web PWA · Surface walkthrough

Studio Aja · Job Filtering and Search

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

Last walked. 2026-07-02 job-queue lane addendum — Playwright real-dev-infra coverage now proves signed-in render, route-map contract, quick-action href order, ready job-query form, 44 px submit target, malformed-JSON client guard with no POST, real search/sort query output, real malformed-job BFF validation detail, fail-closed loading/unauthorized/catalog-error states, mobile no-overflow, and direct BFF 401/403/400/200 gates for catalog and query. Spec: apps/oshun/web/e2e/studio-aja-job-queue-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 job-queue query engine. The operator supplies a job list and a query, and the lane filters by status, applies a full-text search over job id + name, sorts by a key/direction, and reports the total / matched / returned counts plus the matching jobs.

Entry points#

  • Direct URL / bookmark — /studio/aja/job-filtering-and-search.
  • Studio nav — Domain-bridge studios section of /studio.
  • Sibling quick-action — "Open Aja Job Operations workspace" (/studio/aja/job-operations).

Layout regions#

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

  • Workspace <StudioAjaJobFilteringAndSearchWorkspace />:
    • <h1> "Aja Job Filtering and Search Workspace" + summary (data-aja-job-filtering-and-search-summary).
    • Job Query Operations Lane (heading data-aja-jfs-lane-heading) — the form; includes data-aja-jfs-engine-summary (catalog summary).
  • Route Map panel (data-aja-job-filtering-and-search-route-map, <h2> "Route Map"): 5 STUDIO_AJA_JOB_FILTERING_AND_SEARCH_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/job-filtering-and-search on mount.

  • Loading — data-aja-jfs-loading "Loading job query engine…".
  • Unauthorized — data-aja-jfs-unauthorized (401/403; default "Aja workspace scope required to query jobs.").
  • Error — data-aja-jfs-error.
  • Ready (form) — data-aja-jfs-form.
  • Result — data-aja-jfs-result with data-aja-jfs-headline (matched/total · returned) and data-aja-jfs-jobs-list (rows data-aja-jfs-job-row).
  • Validation error — data-aja-jfs-query-error (e.g. "Jobs must be a JSON array.").

Interactions#

Query form (data-aja-jfs-form)#

  • Jobs (JSON array) — textarea data-aja-jfs-jobs.
  • Status — select data-aja-jfs-status (options from catalog statuses, plus "— any —").
  • Search — input data-aja-jfs-search (default render).
  • Sort by — select data-aja-jfs-sortby (catalog sortKeys).
  • Dir — select data-aja-jfs-sortdir (catalog sortDirections).
  • Run query — submit data-aja-jfs-submit; fires POST /v1/admin/aja/job-filtering-and-search/query with { jobs, query }.

Route Map#

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

Quick-action lane#

  • "Open Aja Job Operations workspace" → /studio/aja/job-operations
  • "Back to Studio workspace index" → /studio

E2E coverage#

  • apps/oshun/web/e2e/studio-aja-job-queue-lane-consoles.spec.ts covers signed-in shell render, ready job-query form, malformed JSON client guard with no POST, real BFF search/sort output (2/4 matched · 2 returned, j1 then j3), real malformed-job BFF validation detail, route-map count, exact quick-action hrefs, 44 px submit target, 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/job-filtering-and-search (catalog: summary, statuses, sortKeys, sortDirections).
  • Writes: POST /v1/admin/aja/job-filtering-and-search/query → { total, matched, returned, jobs }.
  • Realtime: none.
  • Caching: client fetch on mount (cache: 'no-store'); SSR shell.
  • Auth/role check: BFF endpoint admin-scoped + fail-closed; route gated signed-in + studio via proxy.

Cross-references#

  • Parent: ../../studio-overview.md
  • Sibling (quick-action): /studio/aja/job-operations
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioAjaJobFilteringAndSearchWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioAjaJobFilteringAndSearchRouteMap.ts

Known downstream boundaries#

  • Route Map lists scenes/exports/revisions/governance child routes as descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.