V1 Web PWA · Surface walkthrough

Isis IP-Adapter

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/ip-adapter · auth signed-in + studio entitlement (AAA-gated — ip-adapter is in AAA_ONLY_STUDIO_ROUTES; contemplative-tier users are redirected to the Yemaya upgrade CTA or hard-blocked per resolveStudioBoundary) · source apps/oshun/web/src/app/studio/isis/ip-adapter/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, IP-Adapter 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-ip-adapter.spec.ts and WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md.

Purpose#

Admin lane console that wires the real @isis/job-envelope IP-Adapter mode normalizer via the shared /v1/admin/isis/controlnet route (domain ipadapter): it lists the canonical IP-Adapter modes (style / face / composition) 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/controlnet
  • 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-ip-adapter-workspace):
    • <h1> (WorkspaceHeading) "Isis IP-Adapter Workspace"
    • Summary paragraph (data-isis-ip-adapter-summary)
    • "Canonical IP-Adapter modes" list (<h2>, data-ipadapter-mode=<mode>)
    • "Resolve a mode" form (<h2>, data-ipadapter-resolve-form, data-ipadapter-form-state=idle|pending)
  • Route Map panel (data-isis-ip-adapter-route-map): <h2>Route Map</h2> over STUDIO_ISIS_IP_ADAPTER_ROUTE_MAP (5 entries); each article carries data-isis-ip-adapter-route=<path>
  • Sibling quick-actions panel (data-isis-ip-adapter-quick-actions, data-isis-ip-adapter-quick-action-count=2): /studio/isis/controlnet, /studio; each link carries data-isis-ip-adapter-quick-action=<id>

States#

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

Interactions#

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

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

Route Map#

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

Sibling quick-actions#

  • Open Isis ControlNet workspace → /studio/isis/controlnet
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/controlnet (canonical mode catalog for domain ipadapter)
  • 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/StudioIsisIPAdapterWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisIPAdapterRouteMap.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.
  • IP-Adapter and InstantID share the same /v1/admin/isis/controlnet route, differentiated by domain (ipadapter vs instantid); confirm the BFF routes the resolve by the workspace's domain correctly. Playwright captures the browser POST bodies and direct BFF checks prove { domain: 'ipadapter', mode: 'identity' } resolves to canonical face and legacy workflow ipadapter-face.