V1 Web PWA · Surface walkthrough

Isis ControlNet

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/controlnet · auth signed-in + studio entitlement (AAA-gated — segment controlnet in AAA_ONLY_STUDIO_ROUTES) · source apps/oshun/web/src/app/studio/isis/controlnet/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, ControlNet/IP-Adapter/InstantID alias resolution, 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-controlnet.spec.ts and WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md.

Purpose#

Admin lane console for the canonical control-conditioning catalog (ControlNet / IP-Adapter / InstantID) and alias resolution. It lists the canonical ControlNet modes and the default blend precedence, then resolves a raw mode or alias for a given domain to its canonical mode and legacy workflow name.

Entry points#

  • Sibling quick-action card from /studio/isis/comfyui-nodes
  • Studio index (/studio)
  • Direct URL / bookmark

Layout regions#

page.tsx mounts ShellLayout active="studio" and three panels (no breadcrumb panel).

  • Workspace panel (data-isis-controlnet-workspace):
    • <h1> "Isis ControlNet Workspace" (WorkspaceHeading)
    • Summary paragraph (data-isis-controlnet-summary)
    • Canonical-modes section (<h2>) listing data-controlnet-mode={m} items + blend precedence (data-controlnet-precedence)
    • The "Resolve a mode" form (data-controlnet-resolve-form, data-controlnet-form-state=idle|pending)
    • Resolution result (data-controlnet-resolved with data-controlnet-canonical / data-controlnet-legacy, or data-controlnet-unresolved)
  • Route map panel (data-isis-controlnet-route-map): <h2> "Route Map" enumerating STUDIO_ISIS_CONTROLNET_ROUTE_MAP; each article carries data-isis-controlnet-route=<path>
  • Quick-actions panel (data-isis-controlnet-quick-actions, data-isis-controlnet-quick-action-count=2): quickAction links to /studio/isis/animatediff-lightning and "Back to Studio workspace index" → /studio; each link carries data-isis-controlnet-quick-action=<id>

States#

  • Loading — data-controlnet-loading "Loading control modes…"; the Playwright spec holds the catalog request open and asserts the resolve form is absent until the request settles.
  • Unauthorized — data-controlnet-unauthorized (admin-scope fail-closed on 401/403)
  • Error — data-controlnet-error on non-OK / malformed response or network failure; the form and mode rows remain hidden.
  • Ready (form) — canonical modes + resolve form render, backed by live GET /v1/admin/isis/controlnet and exact domain options controlnet | ipadapter | instantid
  • Result — data-controlnet-resolved (resolved), data-controlnet-unresolved (no match), or data-controlnet-resolve-error (error)

Interactions#

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

  • Domain — data-controlnet-field-domain select (options from catalog domains); Playwright asserts the live option order and switches across all three domains.
  • Mode / alias — data-controlnet-field-mode text input; tested with openpose, identity, instant-id, not-a-mode, and a whitespace-only invalid payload.
  • Resolve mode — data-controlnet-resolve-submit submit; POSTs to /v1/admin/isis/controlnet/resolve, disables while pending, exposes data-controlnet-submit-state=pending|idle, and renders the live BFF response without fabricating missing fields.

Route map#

  • Route-map articles — non-interactive path + purpose entries; exact five-entry route map is asserted via data-isis-controlnet-route=<path>.

Quick-actions#

  • Open Isis AnimateDiff Lightning workspace → /studio/isis/animatediff-lightning
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/controlnet (CONTROLNET_ENDPOINT) on mount — catalog (controlNetModes, defaultBlendPrecedence, domains)
  • Writes: POST /v1/admin/isis/controlnet/resolve (RESOLVE_ENDPOINT) — resolve a mode/alias
  • Realtime: None
  • Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders()
  • Auth: admin-scoped fail-closed (401/403 → unauthorized state); AAA-gated studio route behind the signed-in + studio proxy gate
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisControlNetWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisControlNetRouteMap.ts

Cross-references#

Open questions / known gaps#

  • Resolution is a catalog lookup: aliases are registered in the real @isis/job-envelope normalizers (normalizeIsisControlNetMode, normalizeIsisIpAdapterMode, normalizeIsisInstantIdMode) and are surfaced through apps/oshun/bff/src/routes/admin-isis-controlnet.ts; this view only resolves aliases and does not add new ones.