--- path: /studio/isis/3d-prompt-engineering surface: studio domain: isis auth: signed-in + studio entitlement (AAA-gated — segment `3d-prompt-engineering` in `AAA_ONLY_STUDIO_ROUTES`) source: apps/oshun/web/src/app/studio/isis/3d-prompt-engineering/page.tsx status: walked last_walked: '2026-07-21 isolated Playwright contract walk — eight desktop/mobile Chromium scenarios, one worker, retries disabled, applicable axe coverage, exact built BFF, disposable PostgreSQL database, and all 32 migrations; live screen-reader and offline checks remain manual.' --- # Isis 3D Prompt Engineering ## Purpose Admin-scoped, fail-closed workspace for computing an unsaved prompt preview. Operators supply a key, display name, source template, and variables; the prompt engine applies `{{variable}}`, `{{#if}}`, and `{{#each}}`, estimates tokens, and reports missing variables. The exact disposition is `ephemeral_recomputable` with `persistence: none`, `retention: request_lifetime`, engine revision `isis-prompt-template-preview-v1`, and `authoritativeState: false`. The route does not author or retain a reusable template, rendered prompt, history, revision, approval, export, provider execution, artifact, governance record, or release decision. ## Entry points - Sibling quick-action from `/studio/isis/gaussian-splatting` - Studio index (`/studio`) - Direct URL / bookmark (AAA entitlement required) ## Layout regions `page.tsx` mounts `` (no breadcrumb panel) and three panels: the workspace, the Route Map, and sibling quick-actions. - **Header**: shell header - **Workspace panel** (`data-isis-3d-prompt-engineering-workspace`): - `

` (`WorkspaceHeading`) "Isis 3D Prompt Engineering Workspace" - Summary paragraph (`data-prompt-summary`) - Author/render form (`data-prompt-form`) - Rendered-templates list (`data-prompt-templates`), each `data-prompt-template=`; empty state `data-prompt-templates-empty` - **Route Map panel** (`data-isis-3d-prompt-engineering-route-map`): one mounted route and four `documented-contract` shapes, each labeled with `data-isis-3d-prompt-route-status` - **Sibling quick-actions panel** (`data-isis-3d-prompt-quick-actions`): `/studio/isis/gaussian-splatting`, `/studio` ## States - [ ] **Loading** — `outcome === null`; `data-prompt-loading` "Loading prompt templates…" - [ ] **Unauthorized** — 401/403 admin-scope fail-closed; `data-prompt-unauthorized` ("Isis workspace scope required to author prompt templates.") - [ ] **Error** — non-OK or malformed response; `data-prompt-error` - [ ] **Ready (form)** — exact empty catalog and exact disposition accepted; request-lifetime form + current-tab preview region render - [ ] **Validation** — invalid JSON → `data-prompt-json-invalid`; referenced-but- unsupplied variables previewed via `data-prompt-missing-preview` - [ ] **Result** — after render POST, `data-prompt-result` (`data-prompt-status=ok|error`); an accepted exact record is held only in current React state and clears on reload - [ ] **Malformed/inflated response** — extra catalog, disposition, success- envelope, or record keys are rejected instead of being treated as authority ## Interactions ### Author + render form (`data-prompt-form`) - [ ] **Template key** (`data-prompt-key`, text input) - [ ] **Name** (`data-prompt-name`, text input) - [ ] **Template content** (`data-prompt-content`, monospace textarea; defaults `A {{style}} render of a {{subject}}.`) - [ ] **Variables (JSON)** (`data-prompt-variables`, monospace textarea) - [ ] **Render template** (`data-prompt-render`) — disabled until key, name, content present and variables JSON valid; request-lifetime `POST /v1/admin/isis/prompt-templates`; the accepted preview remains in the current tab without refetching or persistence - [ ] Per-template `data-prompt-rendered` (rendered prompt) and `data-prompt-missing` (missing variables, with `data-prompt-has-missing`) ### Route Map - [ ] **Route-map articles** ×5: only the primary route is mounted; `/scenes/[sceneId]`, `/exports/[exportId]`, `/revisions/[revisionId]`, and `/governance/[policyId]` are documented shapes only ### Sibling quick-actions - [ ] **Open Isis Gaussian Splatting workspace** → `/studio/isis/gaussian-splatting` - [ ] **Back to Studio workspace index** → `/studio` ## Data & contracts - **Reads**: `GET /v1/admin/isis/prompt-templates` always returns an exact empty history plus the exact no-store disposition - **Computes**: `POST /v1/admin/isis/prompt-templates` performs one request- lifetime render and returns one exact record; it does not create stored state - **Input bounds**: template key 1–128 characters matching the server key grammar; name at most 160 characters; content at most 20,000 characters; serialized variables at most 20,000 characters; at most 100 top-level keys, depth 8, and 1,000 aggregate nodes. Prototype-pollution keys, template references, and unknown identity/retention fields are rejected. - **Realtime**: none - **Caching**: client fetch on mount, `cache: 'no-store'`, `buildBffAuthHeaders()` - **Auth/role check**: admin-scoped, fail-closed (401/403); route AAA-gated (`3d-prompt-engineering` in `AAA_ONLY_STUDIO_ROUTES`) - **Component sources**: - `apps/oshun/web/src/components/studio/StudioIsis3DPromptEngineeringWorkspace.tsx` - `apps/oshun/web/src/components/studio/StudioIsis3DPromptEngineeringRouteMap.ts` ## Cross-references - Studio overview: [`../../studio-overview.md`](../../studio-overview.md) - AAA gating: `libs/isis/entitlements/src/studio-boundary.ts` - Sibling routes: - [`studio-isis-gaussian-splatting.md`](./studio-isis-gaussian-splatting.md) - [`studio-isis-3d-generation.md`](./studio-isis-3d-generation.md) - [`studio-isis-3d-post-processing.md`](./studio-isis-3d-post-processing.md) ## Open questions / known gaps - [ ] No breadcrumb panel; primary navigation is via sibling quick-actions - [ ] Route-map sub-paths (`/scenes`, `/exports`, `/revisions`, `/governance`) are declared but not yet implemented as separate pages - [ ] No durable template registry, revision/history store, approval flow, provider execution, artifact/export pipeline, governance authority, or release authority exists on this surface