V1 Web PWA · Surface walkthrough

Studio · Generation Gallery

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

walked
8sections3 minread
Markdown source
On this page

Context. surface studio · domain generation · route /studio/generation-gallery · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/generation-gallery/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

Purpose#

Unified output gallery (§24.10) for generated illustrations, narrations, ambient audio, captions, 3D briefings, and accessibility passes. Reads only records the caller is entitled to via the §24.1 tier resolver, applies filter facets, and surfaces lineage / branch / replay-with-tweak / compare grid via the GenerationGalleryClient component.

Entry points#

  • Studio root (/studio) — discoverable as a generation workspace
  • Direct URL / bookmark — yes (signed-in + studio entitlement)
  • Deep link from authoring/compose — once a generation completes

Layout regions#

page.tsx is a server component that calls loadGalleryViewForRequest() to fetch the gallery view, then renders the client component:

ts
return <GenerationGalleryClient view={view} />;

The client component (GenerationGalleryClient, ≈ 716 LOC) renders the gallery shell directly — no ShellLayout wrapper.

  • Header: gallery toolbar
  • Filter facets: kind (image / video / audio-narration / audio-music / mesh-3d / caption-dub / accessibility-pass), domain (tara / veritas / nyx / nisaba / metis / arete / sophia), CSV inputs for additional attribute filters
  • Record grid: output records with kind badge, domain badge, lineage hint
  • Lineage tree: per-output OutputLineage visualization
  • Branch / replay-with-tweak drawer: composes a BranchRunRequest via planBranch
  • Compare grid: 2-up / 4-up / n-up layouts via buildCompareGrid plus per-pair diff metrics (pixel / frame / waveform / mesh-vertex)
  • Provenance inspector: GeneratedArtifactProvenanceInspector renders the C2PA-style provenance bundle for a record

States#

  • Loading — server-rendered; view object pre-populated
  • Empty (entitled but no records) — empty-state copy
  • Populated — at least one record per kind / domain
  • Filter facets applied — record grid reduces to matching records
  • Filter excludes all — empty state with reset CTA
  • Lineage tree shown — selecting a record renders its OutputLineage
  • Branch drawer open — planBranch returns the proposed BranchRunRequest
  • Compare 2-up / 4-up / n-up — selecting multiple records sets the layout via chooseCompareLayout(count); per-pair diff metrics show under each pair
  • Provenance inspector open — bundle metadata visible
  • Error (recoverable) — loadGalleryViewForRequest failure renders error state
  • Offline — last-loaded gallery view rendered from SW cache where pinned
  • Standalone PWA — usable

Interactions#

Filter facets#

  • Kind toggle chips (7 chips) — toggle inclusion via toggleOf
  • Domain toggle chips (7 chips) — toggle inclusion via toggleOf
  • CSV input (attribute) — csvToList parses comma-separated values

Record grid#

  • Per-record card — click selects; show kind, domain, lineage hint, cost
  • "Open lineage" (button) — renders the OutputLineage tree
  • "Branch / replay with tweak" (button) — opens the drawer

Lineage tree#

  • Tree nodes — per-record provenance edges from LineageEdge

Branch / replay-with-tweak drawer#

  • Parameter range editors — ParameterAllowedRange
  • "Submit branch run" (button) — emits the BranchRunRequest

Compare grid#

  • Layout toggle (2-up / 4-up / n-up) — read-only computed from count
  • Per-pair diff metric label — pixel delta / frame delta / audio RMS delta / waveform correlation / mesh delta

Provenance inspector#

  • Bundle metadata view — rendered by GeneratedArtifactProvenanceInspector

Data & contracts#

  • Reads: loadGalleryViewForRequest() (server-side) → GalleryView (filters + records)
  • Library: @oshun-web/isis-output-gallery — applyGalleryFilter, buildCompareGrid, planBranch, OutputLineage
  • Writes: branch / replay-with-tweak emits a BranchRunRequest to the upstream generation surface (separate route)
  • Realtime: none in this view
  • Caching: SSR + client SWR for filtered records
  • Auth/role check: middleware (signed-in + studio entitlement); the loader applies the §24.1 tier resolver before returning records

Cross-references#

Open questions / known gaps#

  • Confirm whether the gallery view ever streams new records (Psyche envelope) or only reloads on filter change
  • Document the C2PA / provenance bundle storage path once moved off seeded fixtures