kandev/docs/plans/terminal-theme-rendering/task-02-implement-adaptive-terminal-themes.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
02-implement-adaptive-terminal-themes	Implement adaptive terminal themes	done	2	01-add-terminal-theme-regressions	plan.md	REQ-UI-TERMINAL-RENDERING-001	AC-UI-TERMINAL-RENDERING-001.1 AC-UI-TERMINAL-RENDERING-001.2 AC-UI-TERMINAL-RENDERING-001.3 AC-UI-TERMINAL-RENDERING-001.4 AC-UI-TERMINAL-RENDERING-001.5 AC-UI-TERMINAL-RENDERING-001.6	../../specs/ui/system-design/terminal-rendering.md

Task 02: Implement Adaptive Terminal Themes

Summary

Implement the shared light, dark, and fixed-dark theme contract. Update open adaptive terminals without replacing their xterm instance or connection.

In scope

• Add separate light and dark ANSI palettes.
• Add the shared xterm minimum contrast value.
• Apply the resolved theme during every xterm construction path.
• Synchronize open task and agent terminals after a resolved theme change.
• Use the shared fixed-dark theme in PtyTerminalView.
• Turn every Task 01 regression green.

Out of scope

• Change PTY or WebSocket ownership.
• Clear or recreate a terminal during a theme change.
• Add a theme preference or configurable palette.
• Change desktop, tablet, or phone terminal composition.

Acceptance

• Every xterm constructor uses the shared palette and minimum contrast contract.
• An open adaptive terminal updates all theme colors without losing buffer content, focus, scroll position, a running command, or new shell output.
• Desktop, mobile, and fixed-dark terminal checks pass without changing their lifecycle behavior.

Verification

cd apps/web && pnpm test -- lib/theme/terminal-theme.test.ts

cd apps/web && pnpm test -- components/task/use-terminal-theme.test.ts components/theme/app-theme.test.tsx

cd apps/web && pnpm run typecheck

cd apps/web && pnpm exec eslint lib/theme/terminal-theme.ts lib/theme/terminal-theme.test.ts components/task/use-terminal-theme.ts components/task/use-passthrough-terminal.ts components/task/passthrough-terminal.tsx components/task/shell-terminal.tsx components/task/terminal-buffer-reader.ts components/settings/pty-terminal-view.tsx e2e/tests/terminal/terminal-test-helpers.ts e2e/tests/terminal/terminal-theme.spec.ts e2e/tests/terminal/mobile-terminal-theme.spec.ts

cd apps/web && pnpm e2e:run tests/terminal/terminal-theme.spec.ts

cd apps/web && pnpm e2e:run --project mobile-chrome tests/terminal/mobile-terminal-theme.spec.ts

Files likely touched

• apps/web/lib/theme/terminal-theme.ts
• apps/web/components/task/use-terminal-theme.ts
• apps/web/components/task/use-terminal-theme.test.ts
• apps/web/components/theme/app-theme.test.tsx
• apps/web/components/task/use-passthrough-terminal.ts
• apps/web/components/task/passthrough-terminal.tsx
• apps/web/components/task/shell-terminal.tsx
• apps/web/components/settings/pty-terminal-view.tsx
• Files from Task 01 when selectors or helper types need final adjustment.

Dependencies

• Task 01 must record the expected red tests.

Risks

• Reading computed CSS colors too early can apply the previous theme.
• Recreating xterm can interrupt active commands and erase the scrollback buffer.
• A palette correction can reduce the distinction between ANSI hues after contrast adjustment.

Parallelism

sequential

Inputs

• Task 01 failure evidence.
• REQ-UI-TERMINAL-RENDERING-001
• docs/specs/ui/system-design/terminal-rendering.md
• All three current xterm constructor paths.

Results

Implemented the shared light and dark palettes, xterm minimum contrast setting, adaptive live-theme synchronization, and fixed-dark PTY theme. The root theme now applies before descendant terminal construction effects, and the light bright variants remain visually distinct. The existing terminal instance, buffer, WebSocket, focus, scroll position, running command, and mobile composition remain unchanged. Unit, typecheck, targeted lint, desktop production E2E, and Pixel 5 production E2E verification all pass.