---
path: /studio/isis/reference-image-processing
surface: studio
domain: isis
auth: signed-in + studio entitlement (NOT AAA-gated)
source: apps/oshun/web/src/app/studio/isis/reference-image-processing/page.tsx
status: walked
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'
---

# Isis Reference Image Processing

## 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

- [x] **Loading** — `data-isis-rip-loading`
- [x] **Unauthorized** — 401/403 scope fail-closed; `data-isis-rip-unauthorized`
- [x] **Error** — non-OK or malformed catalog; `data-isis-rip-error`
- [x] **Ready (form)** — catalog present; width + height inputs and the
      supported ratios list render
- [x] **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`)

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

### Route Map

- [x] **Mounted planner route** ×1
- [x] **Documented-contract-only route shapes** ×4

### Sibling quick-actions

- [x] **Open Isis 3D Prompt Engineering workspace** →
      `/studio/isis/3d-prompt-engineering`
- [x] **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

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- Sibling routes:
  - [`studio-isis-3d-prompt-engineering.md`](./studio-isis-3d-prompt-engineering.md)
  - [`studio-isis-multi-provider-3d-generation.md`](./studio-isis-multi-provider-3d-generation.md)
  - [`studio-isis-3d-result-management.md`](./studio-isis-3d-result-management.md)

## 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