V1 Web PWA · Surface walkthrough

Isis Model Comparison

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

walked
8sections2 minread
Markdown source
On this page

Context. surface studio · domain isis · route /studio/isis/model-comparison · auth signed-in + studio entitlement (AAA-gated — model-comparison is in AAA_ONLY_STUDIO_ROUTES) · source apps/oshun/web/src/app/studio/isis/model-comparison/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; body re-derived 2026-06-03 from current source (lane-console architecture)

Purpose#

Admin lane console for §24.10 A/B output comparison. It loads the output gallery, lets an operator select two or more outputs of the same kind, and builds a 2-up / 4-up / n-up compare grid with per-pair diff metrics (pixel / frame / audio / waveform / mesh delta). Cross-kind comparisons (e.g. image vs. audio) are rejected.

Entry points#

  • Sibling quick-action card from /studio/isis/model-merging
  • Studio index (/studio)
  • Direct URL / bookmark

Layout regions#

page.tsx mounts ShellLayout active="studio" and three panels (no breadcrumb panel).

  • Workspace panel (data-isis-model-comparison-workspace):
    • <h1> "Isis Model Comparison Workspace" (WorkspaceHeading)
    • Summary paragraph (data-isis-model-comparison-summary)
    • Layout + build controls (data-compare-layout select, data-compare-build button, data-compare-result / data-compare-status)
    • Output list (data-compare-records, <h2>) of selectable data-compare-record rows
  • Route map panel (data-isis-model-comparison-route-map): <h2> "Route Map" enumerating STUDIO_ISIS_MODEL_COMPARISON_ROUTE_MAP
  • Quick-actions panel: quickAction links to /studio/isis/model-merging and "Back to Studio workspace index" → /studio

States#

  • Loading — data-compare-loading "Loading outputs…"
  • Unauthorized — data-compare-unauthorized (admin-scope fail-closed on 401/403)
  • Error — data-compare-error on non-OK / malformed response
  • Ready — layout/build controls + selectable output list render
  • Result — data-compare-result with data-compare-status (ok / error); build disabled until ≥2 selected

Interactions#

Build a compare grid#

  • Layout — data-compare-layout select (2-up / 4-up / n-up); persisted via workspace persistence
  • Output selection — data-compare-record={outputId} selectable rows (≥2 of the same kind required)
  • Build compare grid — data-compare-build button; POSTs to /v1/admin/isis/model-comparison/grid

Route map#

  • Route-map articles — non-interactive path + purpose entries

Quick-actions#

  • Open Isis Model Merging workspace → /studio/isis/model-merging
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/output-gallery (GALLERY_ENDPOINT) on mount — comparable outputs
  • Writes: POST /v1/admin/isis/model-comparison/grid (COMPARE_ENDPOINT) — build a diff grid
  • Realtime: None
  • Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders(); layout preference persisted locally
  • Auth: admin-scoped fail-closed (401/403 → unauthorized state); AAA-gated studio route behind the signed-in + studio proxy gate
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisModelComparisonWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisModelComparisonRouteMap.ts

Cross-references#

Open questions / known gaps#

  • Diff metrics are computed server-side over the output gallery — confirm how large galleries paginate into the selectable list
  • Cross-kind selection is rejected on build; the UI does not pre-disable mismatched picks