fix(web): preserve dynamic terminal background

[sting8k]

Summary

• Mirror OSC 11/111 terminal background changes into Web UI terminal wrapper surfaces.
• Track latest runner OSC 11/111 background state and replay it in reconnect snapshots so colors emitted before browser attach are preserved.
• Add focused browser/runner tests plus harness story/test-matrix evidence.

Validation

• corepack pnpm --filter @jump/web test -- terminal-colors.test.ts (Vitest full @jump/web suite: 26 files, 409 tests)
• TMPDIR=/tmp GOWORK=$PWD/go.work go test -v ./cli/jump/internal/ptyserver -run 'TestTerminalColorTracker|TestPTYServerReconnectSnapshotReplaysTerminalBackground'
• TMPDIR=/tmp GOWORK=$PWD/go.work go test ./cli/jump/internal/ptyserver ./services/jumpd/internal/wsproxy ./services/jumpd/cmd/jumpd
• corepack pnpm --filter @jump/web lint
• corepack pnpm --filter @jump/web build
• git diff --check
• Local reinstall/restart: jumpd 1.15.0 (ready)
• Chrome headless attach to a fresh pre-OSC session reported .terminal-shell --terminal-bg as #123456 without live injection.

[github-actions]

Try this PR

Download the jump-pr37 artifact from this workflow run and copy jump, jumpd, and jump-relayd into your PATH.

Built from 8c27550: 8c27550 — fix(web): preserve dynamic terminal background
_{Artifacts expire after 7 days. Public install scripts are disabled for this fork.}

[greptile-apps]

Greptile Summary

This PR adds end-to-end dynamic terminal background tracking: a new Go streaming OSC parser (terminalColorTracker) captures OSC 11/111 sequences from PTY output and injects the latest background state into each reconnect snapshot, while the browser registers fall-through xterm OSC handlers to mirror those changes into a CSS custom property (--terminal-bg) on the terminal shell wrapper.

• Go layer (terminal_colors.go, ptyserver.go): terminalColorTracker is embedded by value in Server and guarded by the existing s.mu mutex. It handles split sequences across PTY chunks, C1 (0x9d) openers, BEL and ST terminators, and ignores report-only payloads (?). The reconnect snapshot frame now inserts colorSeq between resetSeq and the rendered screen content, so a fresh browser attach always sees the correct background before cell data arrives.
• Web layer (terminal-colors.ts, terminal.tsx): A pure helper normalizes OSC X11 rgb/hex payloads to CSS hex strings. applyTerminalBackground is a stable useCallback (empty deps, reads from a ref at call-time) that drives the --terminal-bg property; it is called on terminal mount, on every session switch, on live OSC 11/111 events, and is reset to the configured fallback by the reconnect effect before the snapshot arrives.

Confidence Score: 4/5

Safe to merge; changes are browser-local on the frontend and additive-only on the runner, with no mutations to daemon APIs, relay protocol, or session persistence.

The Go tracker's mutex discipline and split-sequence handling are correct, the xterm fall-through handlers are properly disposed, and session-switch reset logic is in place. The only gap is a missing test branch for the resolvedTerminalBackground default-color path, which is inconsequential today but could silently regress if DEFAULT_THEME_COLORS is restructured.

The test coverage gap in terminal-colors.test.ts (the DEFAULT_THEME_COLORS fallback branch of resolvedTerminalBackground) is the only area worth a second look before merge.

Important Files Changed

Filename	Overview
cli/jump/internal/ptyserver/terminal_colors.go	New streaming OSC 11/111 tracker embedded in Server struct, guarded by s.mu. Handles split sequences via pending buffer, C1 0x9d openers, BEL and ST terminators, and ignores query payloads.
cli/jump/internal/ptyserver/ptyserver.go	Integrates terminalColorTracker into Server: write() called in readPTY under s.mu, backgroundReplaySeq() inserted between resetSeq and snapshot in handleWS reconnect frame.
apps/jump-web/src/terminal.tsx	Adds terminalBackgroundFallbackRef, applyTerminalBackground callback, and fall-through OSC 11/111 handlers. Callback uses empty dep array correctly via refs; session-switch reset and terminal-mount reset are both in place.
apps/jump-web/src/terminal-colors.ts	New pure helper module: OSC rgb/hex color parsing and resolved background fallback. Logic is correct; conversion from 1-4 hex digit X11 components to 8-bit CSS hex uses proper normalization.
apps/jump-web/src/terminal-colors.test.ts	Good coverage of OSC rgb and hex parsing, query/invalid rejection, and configured-background fallback. The path where options.theme.background is falsy (falling back to DEFAULT_THEME_COLORS) is not exercised.
cli/jump/internal/ptyserver/terminal_colors_test.go	Tests background replay, split OSC across chunks, and report-ignored/previous-color-kept behavior. All key tracker states are exercised.
cli/jump/internal/ptyserver/ptyserver_test.go	New integration test spins up a real PTY server, waits for OSC 11 to be captured, dials via WebSocket, and asserts the reconnect snapshot frame contains the replay sequence.
docs/TEST_MATRIX.md	New row added for web-terminal-dynamic-background story with validation commands and evidence; correctly marks e2e as no per story doc.
docs/stories/web-terminal-dynamic-background.md	Well-formed story packet covering product contract, acceptance criteria, design notes, validation table, and evidence. Correctly scoped to browser-local behavior with no daemon API changes.

Sequence Diagram

sequenceDiagram
    participant PTY as PTY App
    participant Runner as PTY Server Go
    participant WS as WebSocket
    participant XTerm as xterm.js
    participant CSS as CSS --terminal-bg

    PTY->>Runner: OSC 11 rgb set BEL via stdout
    Note over Runner: readPTY acquires s.mu<br/>terminalColors.write(data)<br/>bgSeq stored

    Note over Runner: New browser connects<br/>handleWS acquires s.mu<br/>colorSeq = backgroundReplaySeq()

    Runner->>WS: BSU + modeSeq + resetSeq + colorSeq + snapshot + ESU
    WS->>XTerm: frame bytes
    XTerm->>XTerm: parse OSC 11 payload
    XTerm->>CSS: oscBackgroundDisposable fires
    CSS->>CSS: --terminal-bg set to dynamic color

    PTY->>Runner: OSC 111 BEL restore via stdout
    Note over Runner: terminalColors.write()<br/>bgSeq cleared

    Runner->>WS: live OSC 111 forwarded
    WS->>XTerm: parse OSC 111
    XTerm->>CSS: oscBackgroundRestoreDisposable fires
    CSS->>CSS: --terminal-bg reset to fallback

    Note over CSS: Session switch also calls<br/>applyTerminalBackground to reset

Loading

_{Reviews (1): Last reviewed commit: "fix(web): preserve dynamic terminal back..." | Re-trigger Greptile}