---
path: /studio/isis/topaz-enhancement
surface: studio
domain: isis
auth:
  signed-in + studio entitlement (AAA-gated — `topaz-enhancement` is in
  `AAA_ONLY_STUDIO_ROUTES`)
source: apps/oshun/web/src/app/studio/isis/topaz-enhancement/page.tsx
status: walked
last_walked:
  '2026-07-23 exact-production-BFF Playwright (desktop + mobile Chrome) — hard
  route boundary, exact/no-store catalog and plan contracts, adversarial
  authority rejection, 44px controls, responsive containment, and automated axe
  checks passed; live screen-reader and telemetry-delivery checks remain manual.'
---

# Studio · Isis · Topaz Enhancement

## Purpose

Admin lane console for a request-local film-aware upscaling-plan preview. The
operator picks an upscale factor and supplies bounded frame metadata as JSON;
the deterministic planner selects a source-defined model/backend and computes
input/output pixel counts plus grain-analysis diagnostics. The route does not
ingest frame assets, execute a GPU/provider, create an artifact, persist
history, or authorize release.

## Entry points

- Sibling quick-action from `/studio/isis/rife-interpolation`
- Studio index (`/studio`)
- Direct URL / bookmark (AAA entitlement required)

## 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-topaz-enhancement-workspace`):
  - `<h1>` (`WorkspaceHeading`) "Isis Topaz Enhancement Workspace"
  - Summary paragraph (`data-isis-topaz-enhancement-summary`)
  - Exact request-only disposition (`data-topaz-disposition`)
  - Backends (`data-topaz-backends`, `data-topaz-model`)
  - Plan form (`data-topaz-plan-form`)
  - Result with `data-topaz-model-selected`, `data-topaz-frame-count`,
    `data-topaz-input-pixels`, `data-topaz-output-pixels`
- **Route Map panel** (`data-isis-topaz-enhancement-route-map`):
  `<h2>Route Map</h2>` over one mounted route and four documented-contract-only
  shapes
- **Sibling quick-actions panel**: `/studio/isis/rife-interpolation`, `/studio`

## States

- [ ] **Loading** — `data-topaz-loading` "Loading enhancement planner…"
- [ ] **Unauthorized** — 401/403 admin-scope fail-closed;
      `data-topaz-unauthorized`
- [ ] **Error** — non-OK / malformed; `data-topaz-error`
- [ ] **Ready (form)** — backends + plan form render
- [ ] **Validation** — invalid frames JSON → `data-topaz-plan-invalid`
- [ ] **Result** — pixel counts after planning; plan failure →
      `data-topaz-plan-error`

## Interactions

### Plan form (`data-topaz-plan-form`)

- [ ] **Upscale factor** (`data-topaz-field-factor`, `<select>`)
- [ ] **Frames (JSON)** (`data-topaz-field-frames`, textarea)
- [ ] **Plan batch** (`data-topaz-plan-submit`, submit; disabled while planning)
      — `POST /v1/admin/isis/topaz-enhancement/plan`

### Route Map

- [ ] **Route-map articles** ×5; each exposes `mounted` or `documented-contract`
      status

### Sibling quick-actions

- [ ] **Open Isis RIFE Interpolation workspace** →
      `/studio/isis/rife-interpolation`
- [ ] **Back to Studio workspace index** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/isis/topaz-enhancement` (backends / models)
- **Writes**: `POST /v1/admin/isis/topaz-enhancement/plan` (plan a film-aware
  upscale batch)
- **Disposition**:
  `request_local_non_authoritative_film_aware_upscaling_plan_preview`;
  persistence `none`; retention `request_only`; caller-supplied frame metadata;
  source-defined model catalog; deterministic planner; no asset ingest, GPU or
  provider execution, artifact output, governance record, release authority, or
  authoritative state
- **Bounds**: exactly 1–256 frames; unique trimmed frame ids of 1–128
  characters; integer dimensions up to 2048×1556; nine finite normalized metrics
  in [0,1]; exact source/content-profile enums; factor 2 or 4; optional
  supported model/backend/strategy and 1–160-character batch name
- **Successful contracts**: GET has exactly nine catalog, bounds, and
  disposition fields. POST has exactly
  `{ok, input, summary, grainAnalysis, disposition}` with a normalized input
  echo.
- **Validation**: the client requires exact catalog, disposition, input,
  summary, and grain-analysis shapes. It checks input echo, frame count,
  selected enums, grain-analysis consistency, normalized scores, and
  input/output pixel arithmetic; missing, extra, malformed, or
  authority-inflated successes fail closed.
- **Realtime**: none
- **Caching**: client fetches with `cache: 'no-store'`; authenticated scoped BFF
  success and failure responses also emit `cache-control: no-store`
- **Auth/role check**: admin-scoped, fail-closed (401/403); route AAA-gated
  (`topaz-enhancement` in `AAA_ONLY_STUDIO_ROUTES`)
- **Component sources**:
  - `apps/oshun/web/src/components/studio/StudioIsisTopazEnhancementWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisTopazEnhancementRouteMap.ts`

## Cross-references

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- AAA gating: `libs/isis/entitlements/src/studio-boundary.ts`
- Sibling routes:
  - [`studio-isis-rife-interpolation.md`](./studio-isis-rife-interpolation.md)
  - [`studio-isis-nvidia-rtx-processing.md`](./studio-isis-nvidia-rtx-processing.md)

## Open questions / known gaps

- [ ] No breadcrumb on this route — navigation via sibling quick-actions
- [ ] Scene, export, revision, and governance sub-paths are documented contract
      shapes only; no corresponding page or authority is mounted
- [ ] Real frame-asset ingestion, GPU/provider execution, generated-media
      artifacts, durable plan history, governance approval, and release remain
      unbound