V1 Web PWA · Surface walkthrough

Isis 3D Prompt Engineering

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/3d-prompt-engineering · 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

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.

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 <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-3d-prompt-engineering-workspace):
    • <h1> (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=<templateKey>; 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#

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