Spec: Connection-metaphor client UI for the Gateway page

[NOirBRight]

This was generated by AI during triage.

Problem Statement

The Gateway page's current Client routing area is built around Managed Takeover: every client card ends with an Official/CodexHub segmented control. Under Provider Injection (ADR-0004), connect means adding CodexHub's Injected Block and disconnect means surgically removing it; CodexHub never changes the client's model selection. The right column must present this new contract truthfully without redesigning the already-established Gateway, Recovery, or Usage & Cost surfaces.

Solution

Keep the existing Gateway page and left column unchanged. Redesign only the fixed-height Client routing column as a compact list of five client cards (OpenCode, DeepSeek Harness, ZCode, Pi, OMP). Each card contains its own unframed status label and standard toggle: on = inject, off = detach. No Gateway entity card, topology rail, connection lines, Ready badge, Official/CodexHub segmented control, or active-model indicator is shown.

The right column is exactly as tall as the left column. Five cards fit without scrolling at the normal window size; if height is insufficient or future clients are added, only the client list scrolls and its scrollbar stays at the panel edge.

User Stories

1. As a user, I want the Gateway page's existing left column to remain familiar, so that a client-integration change does not redesign unrelated controls.
2. As a user, I want all five supported clients visible at once, so that I can inspect connections without scrolling in the normal window size.
3. As a DSH user, I want DeepSeek Harness listed alongside OpenCode, ZCode, Pi, and OMP, so that it feels first-class.
4. As a user, I want one toggle inside each client card, so that connect/disconnect is obvious and local to that client.
5. As a user, I want turning a toggle on to inject CodexHub and turning it off to surgically detach it, so that the control maps directly to the backend contract.
6. As a user, I want CodexHub to leave my model-selection switch alone, so that connecting never changes which model my client uses.
7. As a user, I want connection state expressed by meaningful labels and toggle colors, so that I can distinguish Connected, Updating, Repair, Disconnected, and Unavailable.
8. As a user, I want the toggle to use the same simple visual treatment as Auto retry, so that it matches the existing application.
9. As a user, I want the toggle's label and track to use blue for connected/updating, amber for repair, and gray for disconnected/unavailable, so that exceptional states are recognizable.
10. As a user, I want each card to show the client icon, name, kind, version, and config path, so that I know exactly what CodexHub will change.
11. As a user, I want contextual text such as Injected provider or Configuration changed, so that I understand the current state without a meaningless Ready badge.
12. As a user, I want config drift to be actionable, so that reconnecting repairs only the Injected Block.
13. As a user, I want not-installed clients disabled and visibly muted, so that unavailable actions are truthful.
14. As a user, I want connect/disconnect results reported through the shared Toast lifecycle, so that success and failure are explicit.
15. As a keyboard or screen-reader user, I want a real labelled switch with aria-checked state, so that the interaction is accessible.
16. As a user on a smaller window, I want only the client list to scroll, so that the Client routing header and left column stay stable.

Implementation Decisions

• Scope boundary: modify only the Gateway page's Client routing aside. Gateway settings, Copy connection, Recovery, Usage & Cost, RuntimeBar, tabs, and the Providers page remain unchanged.
• Layout: the page grid stretches both columns to one height. Client routing is an h-full/min-h-0 panel with an auto/minmax list row. The internal list uses edge-aligned vertical scrolling; five cards are compact enough to fit at the normal height.
• Header: Client routing keeps a small Network icon and refresh control, following the same PanelTitle pattern as the other Gateway modules.
• No topology decoration: no Gateway source card, vertical rail, horizontal branch, connector node, or flow animation in this column.
• Client cards: neutral surface cards with 12px inner radius and control/raised shadows. Each shows icon, client name, kind, compact version chip, inset config-path row, and state narrative. Drift gets an amber ring/tint; unavailable clients are muted.
• Connection control: a status label plus the existing standard toggle, directly inside the card. There is no outer border, background, pill, or shadow wrapper. Connected/Updating use action blue; Repair uses warning amber; Disconnected/Unavailable use neutral gray.
• Removed UI: delete the Ready badge and Official/CodexHub segmented switch. Do not show an active/pointing state.
• State contract: connected means the Injected Block is present and passes block-fingerprint readback. Repair means drift. The toggle calls client_connect(client_id) / client_disconnect(client_id); takeover-era clients map internally to their legacy apply/restore paths until migrated.
• DSH: add the fifth contract entry, icon, installed/version/config status, and the same card/control semantics as every other client.
• Feedback: persistent changes use the shared Toast lifecycle and disclose exact restart requirements; DSH requires none because it hot-reloads.
• Localization/accessibility: all new copy lands in en-US and zh-CN; labels are not color-only; the toggle is a labelled switch.

Testing Decisions

Good tests assert visible behavior and command contracts, not CSS hierarchy.

• Mock the frontend api boundary and verify that each card's toggle calls the correct connect/disconnect command with its client id.
• Verify success, failure, drift, unavailable, and busy responses render the correct label/color and Toast lifecycle.
• Extend ui-contract.json/ui-contract.test.mjs with DSH and the final Client routing copy/structure; remove assertions tied to the segmented switch.
• Verify five client cards fit the normal-height fixture without list overflow and that a constrained-height fixture scrolls only the client list.
• Verify each toggle exposes role=switch, aria-checked, and a client-specific accessible label.
• Backend inject/detach/readback behavior remains covered by Declarative per-client injection descriptor (managed-client adapter seam) #432, Block-fingerprint readback for injected clients (replace byte-compare) #433, and Add DeepSeek Harness (DSH) as CodexHub's fifth fully supported managed client #430 tests rather than repeated in frontend tests.

Out of Scope

• Backend injection/readback implementation (Declarative per-client injection descriptor (managed-client adapter seam) #432/Block-fingerprint readback for injected clients (replace byte-compare) #433/Add DeepSeek Harness (DSH) as CodexHub's fifth fully supported managed client #430).
• Provider page, Gateway settings, Recovery, Usage & Cost, RuntimeBar, or tab redesign.
• Topology lines, flow animations, Gateway entity cards, active-model indicators, or in-UI model selection.
• Legacy-client migration implementation (Migrate pi + codex clients to Provider Injection #434/Migrate opencode + omp + zcode clients to Provider Injection #435).

Further Notes

• Campaign: Campaign map: 0.1.9 coexistence Provider Injection & DSH #436, phase beta2. Depends on Add DeepSeek Harness (DSH) as CodexHub's fifth fully supported managed client #430's DSH lifecycle and Declarative per-client injection descriptor (managed-client adapter seam) #432/Block-fingerprint readback for injected clients (replace byte-compare) #433's Injected Block/readback seam.
• Final visual decision validated in prototype branch prototype/issue-438-client-routing at commit 3f64127. The prototype is a primary-source artifact, not production code.

[NOirBRight]

This was generated by AI during triage.

Final prototype verdict

Approved design: preserve the existing Gateway page and left column; redesign only the fixed-height Client routing aside as five compact client cards with internal, unframed state label + toggle controls. No Gateway entity card, topology lines, flow animation, Ready badge, segmented Official/CodexHub control, or active-model indicator.

The final prototype is captured as primary-source throwaway code on branch prototype/issue-438-client-routing, commit 3f64127. Production implementation should follow the issue spec rather than promote the prototype code directly.

[NOirBRight]

Linux cleanup after 0.1.9-beta.1: the local prototype worktree is removed. Primary source stays on prototype/issue-438-client-routing @ 3f64127 (now on origin, not merged to main). Production implementation already landed via #440.

[NOirBRight]

Track 0 note from #441: the connection-toggle UI commits landed on the 0.1.9-beta.1 line. This ticket stays open until a dedicated 1024×768 / five-card / Toast / restart-disclosure acceptance pass. Not a blocker for Gateway module extraction.