V1 Web PWA · Surface walkthrough

Isis Reference Image Processing

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 isis · route /studio/isis/reference-image-processing · auth signed-in + studio entitlement (NOT AAA-gated) · source apps/oshun/web/src/app/studio/isis/reference-image-processing/page.tsx

Last walked. 2026-07-23 production BFF + Playwright desktop/mobile walk — exact GET/POST contracts, live result, authorization denial, responsive containment, 44-pixel controls, and applicable axe coverage passed; manual screen-reader and offline checks remain open

Purpose#

Request-local, non-authoritative preview of the deterministic @isis/seedance-provider aspect-ratio bucketer. The caller supplies width and height metadata, and the route snaps that ratio to the nearest supported generation ratio. It does not ingest, decode, transform, generate, persist, or release an image.

Entry points#

  • Sibling quick-action from /studio/isis/3d-prompt-engineering
  • Studio index (/studio)
  • Direct URL / bookmark

Layout regions#

page.tsx mounts <ShellLayout active="studio"> (no breadcrumb panel) and three panels: the workspace, the Route Map, and sibling quick-actions.

  • Header: shell header
  • Workspace panel (data-isis-reference-image-processing-workspace):
    • <h1> (WorkspaceHeading) "Isis Reference Image Processing Workspace"
    • Summary paragraph (data-isis-rip-summary)
    • Aspect-ratio form (data-isis-rip-aspect-form); supported ratios list (data-isis-rip-ratios)
  • Route Map panel (data-isis-reference-image-processing-route-map): <h2>Route Map</h2> over STUDIO_ISIS_REFERENCE_IMAGE_PROCESSING_ROUTE_MAP (one mounted route and four documented-contract-only shapes)
  • Sibling quick-actions panel: /studio/isis/3d-prompt-engineering, /studio

States#

  • Loading — data-isis-rip-loading
  • Unauthorized — 401/403 scope fail-closed; data-isis-rip-unauthorized
  • Error — non-OK or malformed catalog; data-isis-rip-error
  • Ready (form) — catalog present; width + height inputs and the supported ratios list render
  • Result — after an aspect POST, data-isis-rip-result shows data-isis-rip-ratio (the snapped aspect ratio); failures surface in data-isis-rip-aspect-error

Interactions#

Aspect-ratio form (data-isis-rip-aspect-form)#

  • Reference width (px) (data-isis-rip-field-width, bounded integer input, 1–16,384)
  • Reference height (px) (data-isis-rip-field-height, bounded integer input, 1–16,384)
  • Submit (data-isis-rip-aspect-submit) — POST /v1/admin/isis/reference-image-processing/aspect-ratio

Route Map#

  • Mounted planner route ×1
  • Documented-contract-only route shapes ×4

Sibling quick-actions#

  • Open Isis 3D Prompt Engineering workspace → /studio/isis/3d-prompt-engineering
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/reference-image-processing, returning exactly {generatedAt, supportedAspectRatios, inputBounds, disposition}
  • Writes: POST /v1/admin/isis/reference-image-processing/aspect-ratio accepts exactly {width, height} and returns exactly {ok, input, result, disposition}
  • Realtime: none
  • Supported ratios: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
  • Disposition: request_local_non_authoritative_reference_aspect_ratio_bucket_preview; persistence none, retention request_only, caller-supplied dimensions, deterministic Seedance calculation, no bound image or generation pipeline, no governance record, no release authority, and no authoritative state
  • Caching: authenticated GET and POST responses are no-store; the client also uses cache: 'no-store'
  • Validation: the browser independently verifies the exact catalog, disposition, input echo, raw width/height ratio, and allowlisted snapped ratio before rendering
  • Auth/role check: BFF route is admin-scoped and fails closed (401/403); page route requires signed-in + studio entitlement
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisReferenceImageProcessingWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisReferenceImageProcessingRouteMap.ts

Cross-references#

Open questions / known gaps#

  • No image asset ingest or decoding
  • No image transformation or provider/generation execution
  • No output artifact or durable history
  • No governance record, approval, or release authority
  • No breadcrumb on this route — navigation is via sibling quick-actions
  • Manual screen-reader and offline behavior checks remain open