paperclip/packages/paperclip-runner/docs/design/live-console-interaction-map.md

Live console Interaction Map — Live Codex Protocol Web UI

Status: approved for implementation (UX gate TASK-16832, 2026-08-08). Owner: UXDesigner. Implementer: browser tracer owner (TASK-16834). Companion record: component decisions. This map is the interaction contract for the Live console required by spec §29.1. It binds every surface to canonical Paperclip Runner Protocol (PRP) events and reducer state only. No surface may derive state from third-party component message types, and no surface may show a control the upstream capability set does not support.

0. Shell and information architecture

Extend the existing devtools browser app (devtools/browser/) with a new Live console mode next to the existing Replay–3 modes. Do not build a second app shell. Reuse the existing token layer in src/styles.css and the existing ui-* primitives.

Layout (desktop ≥ 64rem):

• Left rail (fixed, ~17rem): demo-chat manifest list, session/connection status block, goal banner, parent/child lineage tree.
• Center column (fluid, max ~48rem): chat transcript + composer. This is the primary surface; it gets the widest column and the strongest visual hierarchy.
• Right rail (collapsible, ~24rem): protocol inspector. Closed by default on first load; its toggle lives in the header. State persists per session in localStorage (UI preference only — never protocol state).

Layout (mobile < 64rem): single column. Transcript + composer first; manifest picker, goal banner, lineage, and inspector become stacked collapsible sections behind a segmented control (Chat · Session · Inspector). Composer stays docked to the bottom of the viewport in the Chat segment.

Density: this is a diagnostic console — lean dense (Doherty: prioritize feedback latency over decoration). All spacing from the existing scale.

1. Transcript and composer

Source of truth: the reducer timeline (SessionSnapshot.timeline / SessionItemSnapshot), fed by item.started / item.delta / item.completed / item.failed and turn lifecycle events.

Transcript rules:

1. Items render in reducer order. Never reorder client-side; the reducer's sequence is authoritative (protocol authority rule).
2. Item roles: user, assistant, reasoning, tool, system/diagnostic. User items align right with a filled surface; everything else aligns left full-width. Reasoning and tool items render collapsed by default with a one-line summary (Progressive Disclosure); assistant text renders expanded.
3. Streaming: an in-flight item (item.started + deltas, no terminal event) shows a streaming affordance (pulsing cursor block, --motion-fast respecting prefers-reduced-motion). Text appends without layout jumps.
4. Auto-follow: transcript sticks to bottom while the user is at bottom. Any upward scroll disengages following and shows a "Jump to latest" pill (fixed above the composer) with unseen-item count. Clicking or pressing End re-engages. Never yank scroll position while disengaged.
5. Failed items (item.failed) render in place with a danger surface and the exact diagnostic string — no toast-only errors; failures are part of the record (Visibility of System Status).
6. Empty state: before any session, the transcript shows the manifest picker inline ("Pick a demo chat or start a blank session") — not a bare void.

Composer states (one state machine, one visible primary action):

State	Trigger	Primary action	Notes
idle	no active turn	Send (turn.submitted)	textarea enabled
submitting	send clicked, no turn.accepted yet	disabled, spinner in button	keep text visible
active-turn	turn.started for my turn	Steer (see §2) + Stop icon-button	composer relabels; input stays enabled for steering
interrupting	stop clicked	both disabled, "Stopping…"	see §3
disconnected	transport lost	disabled + reconnect banner	see §7
terminal	session.closed/session.failed	disabled + replay affordance	see §7

Composer behavior: Enter submits, Shift+Enter inserts newline. Textarea auto-grows to 8 lines, then scrolls. The active state is announced via a visually-hidden aria-live="polite" status line ("Turn running", "Steering sent", "Turn stopped").

2. Steering: acknowledgement and stale-turn rejection

While a turn is active the composer's primary action is Steer and sends turn/steer with expectedTurnId bound at submit time.

1. Optimistic pending, explicit ack. On send, append a local "steering" chip to the transcript in a pending visual state (muted, spinner). Promote it to acknowledged (solid, check) only on driver acknowledgement. Never silently merge steering text into the user-message stream before ack.
2. Stale-turn rejection is a first-class outcome, not an error toast. If the turn completed/failed/was interrupted between typing and send, the driver rejects on expectedTurnId mismatch. The chip flips to rejected — turn already ended, with the composed text preserved in an inline "Send as new message" action (Forgiveness: one keystroke recovers the intent; never discard typed input).
3. The pending chip must resolve to exactly one of acknowledged, rejected (stale turn), or failed (diagnostic) — no indefinite pending. If the transport drops mid-steer, resolve to failed with the reconnect banner.
4. aria-live="polite" announces ack/rejection with the same copy as the visual chip.

3. Interruption: three races, no session replacement

Stop is a distinct destructive-adjacent action: icon button with Stop label, danger-tinted only while active, never adjacent enough to Send to misclick (Fitts: minimum 2.75rem target, --space-3 gap).

Race matrix (all three must be visually distinguishable — spec test contract):

Race	UI before	UI after
interrupt before start (turn.submitted, no turn.started)	composer submitting	pending turn card resolves to turn.cancelled state: "Cancelled before start"
interrupt during generation	streaming assistant item	stream stops in place; item keeps partial text with an "interrupted" divider; turn.interrupted badge on the turn group
interrupt during tool	tool item running	tool item resolves to interrupted state with its last known status; no fabricated tool result

Rules:

1. Stop → interrupting state ("Stopping…", both actions disabled) until the terminal turn event arrives. If the driver reports interrupt unsupported, show the exact diagnostic and re-enable — never kill or replace the session (spec: "without silently replacing the session").
2. Partial output is preserved and labeled; never blank an interrupted item (the partial record is the point of a tracer).
3. After turn.interrupted, composer returns to idle — resume is just a new send. The turn group shows its terminal badge permanently.

4. Runtime request cards (command / file-change / permission / tool / user-input)

Source of truth: runtime_request.created / .resolved / .expired / .cancelled plus SessionRequestSnapshot (requestId, requestKind, type, status, prompt). Action availability comes from the upstream request contract per request — the card renders only the actions the request offers (never invent "approve for session" if the request does not offer it).

Placement: inline in the transcript at timeline position, plus a compact "pending requests" counter chip in the session status block that scrolls to the oldest pending card. A pending blocking request also pins a slim banner above the composer ("1 request waiting — Review") because the turn cannot proceed (Zeigarnik: make the open loop visible where the user is looking).

Card anatomy (one component, five kinds):

• Kind icon + kind label (Command, File change, Permission, Tool, Input) + requestId (mono, truncated, full value in tooltip/inspector).
• Prompt/body: exact upstream prompt text. Command and file-change payloads render in a mono block (command line, file diff summary) — never paraphrase.
• Action row, in this order when offered: Approve (primary), Approve for session (secondary, only when upstream offers it), Reject (quiet danger), Cancel (ghost, only when upstream allows requester-side cancel). User-input kind renders a text field + Submit instead of approve/reject.
• Resolution states: pending (accent left-border), resolved — <outcome> (success surface, chosen action named, actor + time), expired (muted, "expired before response"), cancelled (muted). Resolved cards collapse to a single summary line, expandable (transcript stays scannable).

Rules:

1. Single-response guarantee in the UI: on first click, disable the whole action row and show a resolving spinner; the card resolves only on the runtime_request.resolved event, not optimistically. A late duplicate click therefore cannot double-respond (mirrors the driver's no-double- response contract).
2. A request resolved elsewhere (driver timeout, upstream cancel) must update the card in place with the true outcome.
3. Keyboard: cards are focusable list items; action row is reachable by Tab; see §10 for the full contract.

5. Goal capability states (set / view / pause / resume / clear)

Source of truth: capability negotiation from the app-server (per spec §29.1.5), surfaced through the driver's capability snapshot. Goal state changes arrive as canonical events; the banner derives from reducer state.

Surfaces:

• Durable goal banner in the left rail (and Session segment on mobile): shows active goal text, state (active/paused), and last transition time. Hidden entirely when no goal has ever been set this session; shows a quiet "No goal set" row once goal capability is confirmed supported.
• Goal menu (not a fuzzy palette — five fixed operations, Hick's law): a menu button Goal ▾ in the session status block opening a menu with Set goal…, View, Pause, Resume, Clear. Set goal… opens a small dialog with one textarea. View focuses/expands the banner. Operations invalid in the current goal state (e.g. Resume while active) are disabled with the reason in a tooltip and aria-disabled + description.

Capability gating (spec-critical):

1. If the installed app-server does not advertise goal support, the whole menu renders disabled with the exact diagnostic from capability negotiation (e.g. Goal operations unsupported: app-server 0.132.0 does not advertise goals capability) — copied verbatim into tooltip and inspector. Never hide the control silently (discoverability of the gap is a deliverable) and never fabricate a client-side goal.
2. Partial support (some verbs missing) disables only the missing verbs, same exact-diagnostic rule per verb.
3. Every goal mutation is also a transcript/system event ("Goal paused") so replay shows the same history.

6. Parent/child lineage and subagent activity

Source of truth: upstream thread identities (parent/child thread lineage from the driver; normalizedSessionId / thread ids). No client-side inference.

• Left-rail lineage tree: root session plus child threads, each row = name/id (mono, truncated) + live state dot (starting, running, terminal-ok, terminal-failed) + last-activity relative time. The row for the currently viewed thread is marked with aria-current="true".
• Selecting a child switches the center transcript to that child's timeline (read-only if the driver does not support steering children). Breadcrumb at the transcript top: root ▸ child-a for orientation (Jakob: matches file tree/thread conventions).
• Unsupported child steering renders as an explicit disabled composer with the exact diagnostic ("Direct steering of child threads is not supported by this app-server"), not an absent composer and not an emulated one (spec: "shown as unsupported rather than emulated").
• Child terminal states persist in the tree (terminal dot + badge); activity is history, not just presence.

7. Reconnect, refresh, resume, replay

Source of truth: transport status + session.resuming / session.resumed / session.reconciled / runner.reconnected events and reducer cursor state.

1. Connection status lives in the session status block: connected, reconnecting (attempt n), disconnected, with the socket/cursor detail in the inspector. State changes announce via aria-live="polite".
2. Transport drop: banner above composer ("Connection lost — reconnecting… / Retry now"). Composer disabled while disconnected (§1). On resume, the reducer replays from the durable cursor; the transcript must end byte-identical to a never-disconnected session (live/replay parity is a test contract, and the UI must not maintain shadow state that could diverge).
3. Page refresh: reload restores the same normalized session and renders the full replayed transcript, then continues live. A subtle divider marks "replayed to here" for diagnostic honesty; it disappears on the next live event group.
4. Replay mode: a terminal session offers Replay (from the manifest list or terminal banner): re-runs the recorded canonical events through the reducer with a stepper (play/pause, step, position slider). Replay is visually distinguished by an eyebrow badge REPLAY in the header — never let replay be mistakable for live (trust).
5. Never offer "start new session" as the recovery path for a drop — resume the exact session (Codex rule: never replace a lost session).

8. Protocol inspector

Source of truth: the raw upstream method/event names and the canonical event stream, side by side. The inspector is the debugging surface; the transcript stays clean (Tesler: complexity lives here, deliberately).

Right-rail panel with four tabs:

• Events: virtualized list, one row per canonical event — seq, eventType, turn/item id (mono). Row expands to the full canonical payload and, when present, the raw upstream method/notification that produced it (debug channel). Filter box (plain substring) + eventType facet chips. Clicking a transcript item highlights its events and vice versa (Uniform Connectedness across panels).
• Requests: pending + resolved runtime requests with full lifecycle timestamps; row links to the transcript card.
• Capabilities: negotiated capability/version table (steer, interrupt, goals, child threads, usage…), each row supported / unsupported — <exact diagnostic>. This is the authoritative view backing every disabled control in §5/§6.
• Session: identities (runId, normalizedSessionId, thread ids, sourceInstanceId), sequence/cursor state, gap detection status, usage counters, connection history.

Rules: monospace for identifiers and payloads; copy-to-clipboard per row; redaction is upstream's job but the inspector must render redaction markers verbatim and never attempt client-side un-redaction or pretty-printing that could reconstruct secrets. No credential ever reaches the browser (spec security rule), so the inspector renders only what the demo server sends.

9. Demo-chat manifests

Source of truth: deterministic manifest files shipped with the package (one per spec scenario: completion, steering, interruption/resume, approvals, user input, subagents, goals, reconnect, replay).

• Manifest list in the left rail: name, one-line purpose, scenario badges, and an expected observations disclosure listing exactly what the runner should show (from the manifest, not hand-written in the UI).
• Running a manifest pins a compact observation checklist panel the user can tick off manually (recognition over recall — the human checkpoint script is embedded in the UI, not in a separate doc).
• Reset control per manifest and a global "Reset demo state": resets demo-server state and clears the local session, with a confirm dialog naming exactly what is destroyed ("Discards the current live session transcript. Recorded evidence files are not touched.").
• Manifests must be runnable in any order; the list shows last-run outcome per manifest (passed observations, not run, interrupted).

10. Keyboard and accessibility acceptance criteria

These are the testable ACs for the component/keyboard/a11y checks required by the spec evidence list. Implementation must satisfy every row; QA verifies each with keyboard-only and screen-reader passes.

Keyboard

• K1. Every interactive control is reachable and operable with Tab/ Shift+Tab/Enter/Space alone; no keyboard trap anywhere, including dialogs and the inspector.
• K2. Composer: Enter sends (or steers when a turn is active), Shift+Enter newline. Escape while a turn is active moves focus to the Stop button (it must never interrupt directly — destructive actions require explicit activation).
• K3. Request cards: card list is an role="list"; each card's actions are reachable in visual order; the oldest pending card is focusable via the pending-requests banner (Enter on banner focuses it).
• K4. Goal menu: standard menu-button pattern (Enter/Space/ArrowDown opens, arrows navigate, Escape closes, focus returns to trigger).
• K5. Lineage tree: role="tree" arrow-key navigation; Enter selects a thread; selection is announced.
• K6. Transcript: End jumps to latest and re-engages follow; Home jumps to first item; transcript region is a labeled role="log" landmark.
• K7. Inspector tabs: standard tabs pattern (arrow keys switch, Tab enters panel); event rows expand/collapse with Enter.
• K8. Replay stepper: Space play/pause, ArrowLeft/ArrowRight step, slider operable by arrows with value announced.
• K9. Visible focus indicator (--ring, ≥2px, ≥3:1 contrast against both adjacent colors) on every focusable element; focus order matches visual order.

Screen reader / semantics

• A1. Transcript is role="log" with aria-live="polite"; streaming deltas do not announce per-token — announce on item completion and on state transitions only (avoid SR flooding).
• A2. Turn/steer/interrupt/connection/goal state changes each produce exactly one polite announcement with the same copy as the visible state.
• A3. A pending blocking request announces assertively once (aria-live="assertive" on the banner), then stays quiet.
• A4. Every state conveyed by color (status dots, card borders, badges) has a text or icon equivalent (WCAG 1.4.1 color-independence).
• A5. Disabled capability controls expose the exact diagnostic via aria-describedby, not only a hover tooltip.
• A6. Dialogs (Set goal…, reset confirm) are proper modal dialogs: labeled, focus moved in, trapped, restored on close.
• A7. All identifiers/payload blocks are in <code>/<pre> semantics; copy buttons are labeled with what they copy ("Copy event 42 payload").

Visual/WCAG

• V1. Text contrast ≥ 4.5:1 (normal) / 3:1 (large); non-text UI ≥ 3:1 — verify the token pairs used by new surfaces (notably --muted-foreground on --muted and status-on-surface pairs).
• V2. Pointer targets ≥ 2.75rem (44px) on mobile breakpoints; Stop and Send separated by ≥ --space-3.
• V3. prefers-reduced-motion disables streaming pulse, auto-scroll smoothing, and skeleton shimmer (fall back to instant updates + static placeholders).
• V4. Layout holds at 320px width and 200% zoom without horizontal scroll of the transcript (WCAG 1.4.10 reflow); the inspector may scroll internally.
• V5. Both viewports in evidence: 1440×900 and 390×844 screenshots for every major state (QA gate).

11. UX acceptance criteria for the implementation handoff

1. All surfaces derive from canonical events/reducer snapshots; grep-level check: no import from any AI SDK, and adapted component files contain no third-party message-type imports (see decision record).
2. Every state named in §1–§9 is reachable via the demo manifests, and each has a distinct, labeled visual state (no two states share identical UI).
3. All K/A/V criteria in §10 pass keyboard-only and screen-reader passes.
4. Unsupported capabilities render exact diagnostics (§5, §6, §8-Capabilities) — zero fabricated controls, zero silently hidden controls.
5. Token compliance: no raw color/spacing/radius/type values in new component files; everything through src/styles.css custom properties (extend the token set via PR if a needed token is missing — see decision record §5).
6. Screenshots at both evidence viewports for: idle+empty, streaming turn, steering ack + stale rejection, all three interrupt races, each request kind (pending/resolved/expired), goal supported+unsupported, lineage with an active child, reconnect banner + replayed divider, replay mode, inspector (Events + Capabilities tabs), and one full mobile pass.