V1 Web PWA · Surface walkthrough

Isis InstantID

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/instantid · auth signed-in + studio entitlement (AAA-gated — instantid is in AAA_ONLY_STUDIO_ROUTES; contemplative-tier users get redirected to the Yemaya upgrade CTA or hard-blocked with 404 per resolveStudioBoundary) · source apps/oshun/web/src/app/studio/isis/instantid/page.tsx

Last walked. 2026-07-03 real-dev-infra Playwright walk — direct Studio Isis boundary hard-block, authenticated localhost-only lane bypass, real BFF catalog load, InstantID alias resolution through the shared ControlNet resolver, pending-submit lockout, unresolved/invalid/malformed/network failure states, non-admin fail-closed auth, direct BFF auth/schema gates, route map, quick actions, 44 px controls, mobile containment, and shared axe scan. Evidence: apps/oshun/web/e2e/studio-isis-instantid.spec.ts and WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md.

Purpose#

Admin lane console that wires the real @isis/job-envelope InstantID mode normalizer via the shared /v1/admin/isis/controlnet route (domain instantid): it lists the canonical InstantID modes (instantid / faceid) and resolves a raw mode/alias to its canonical mode + legacy workflow string. It is admin-scoped and fails closed.

Entry points#

  • Sibling quick-action from /studio/isis/ip-adapter
  • 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-instantid-workspace):
    • <h1> (WorkspaceHeading) "Isis InstantID Workspace"
    • Summary paragraph (data-isis-instantid-summary)
    • Canonical modes list (data-instantid-mode=<mode>)
    • "Resolve a mode" form (<h2>, data-instantid-resolve-form, data-instantid-form-state=idle|pending)
  • Route Map panel (data-isis-instantid-route-map): <h2>Route Map</h2> over STUDIO_ISIS_INSTANTID_ROUTE_MAP (5 entries); each article carries data-isis-instantid-route=<path>
  • Sibling quick-actions panel (data-isis-instantid-quick-actions, data-isis-instantid-quick-action-count=2): /studio/isis/ip-adapter, /studio; each link carries data-isis-instantid-quick-action=<id>

States#

  • Loading — data-instantid-loading; Playwright holds the catalog request open and asserts the resolve form remains hidden until settlement.
  • Unauthorized — 401/403 admin-scope fail-closed; data-instantid-unauthorized
  • Error — non-OK, malformed catalog, or network failure; data-instantid-error renders and the form/mode rows stay hidden.
  • Ready (form) — catalog present; exact live modes instantid | faceid plus resolve form render.
  • Result — after a resolve POST, data-instantid-resolved shows data-instantid-canonical ("canonical: …") and data-instantid-legacy ("legacy workflow: …"); an unresolvable alias → data-instantid-unresolved; failures → data-instantid-resolve-error

Interactions#

Resolve a mode (data-instantid-resolve-form)#

  • Mode / alias (data-instantid-field-mode, text input); tested with instant-id, instantid-sdxl, ip-adapter-face, not-a-mode, and whitespace-only invalid payload.
  • Resolve mode (data-instantid-resolve-submit, submit; "Resolving…" while in flight) — POST /v1/admin/isis/controlnet/resolve (domain: instantid), disables while pending, exposes data-instantid-submit-state=pending|idle, and fails closed on malformed 200 responses.

Route Map#

  • Route-map articles ×5; asserted exactly via data-isis-instantid-route=<path>.

Sibling quick-actions#

  • Open Isis IP-Adapter workspace → /studio/isis/ip-adapter
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/controlnet (canonical mode catalog for domain instantid)
  • Writes: POST /v1/admin/isis/controlnet/resolve (returns { resolved: { canonicalMode, legacyWorkflowMode } })
  • Realtime: none
  • Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders()
  • Auth/role check: admin-scoped, fail-closed (401/403); route gated on signed-in + studio entitlement (AAA segment)
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisInstantIDWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisInstantIDRouteMap.ts

Cross-references#

Open questions / known gaps#

  • No breadcrumb on this route — current V1 behavior is sibling quick-actions only, asserted by the dedicated quick-action selectors and route-map coverage.
  • InstantID and IP-Adapter share the same /v1/admin/isis/controlnet route, differentiated by domain (instantid vs ipadapter); confirm the BFF routes the resolve by the workspace's domain correctly. Playwright captures the browser POST bodies and direct BFF checks prove { domain: 'instantid', mode: 'instant-id' } resolves to canonical instantid and legacy workflow instantid; { domain: 'instantid', mode: 'face-id' } resolves to canonical faceid and legacy workflow ipadapter-faceid.