kandev/docs/plans/thinking-message-preview/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-08-30	implemented	REQ-UI-THINKING-MESSAGE-PREVIEW-001	../../specs/ui/system-design/thinking-message-preview.md

Implementation Plan: Preview Collapsed Thinking Messages

Overview

Derive a model-agnostic preview from the first meaningful reasoning line and show it in expandable thinking-message headers. Implement the behavior as one frontend TDD slice because the derivation, row layout, component evidence, and mobile overflow proof share one component contract.

Scope

In scope

• Skip leading blank or decoration-only reasoning lines.
• Strip inline Markdown from the selected preview line.
• Keep the localized Thinking label and add a one-line truncated preview for expandable messages.
• Preserve compact single-line and expanded Markdown behavior; compact text remains complete and may wrap on narrow rows.
• Prove streaming stability and desktop/mobile containment.

Out of scope

• Backend, ACP, persistence, WebSocket, and message-schema changes.
• Provider-specific preview parsing or generated summaries.
• New settings, copy, localization keys, or public documentation.
• Expandable-row interaction and accessibility redesign.

Technical approach

Preview helper and component

• Add a pure first-meaningful-line helper near stripMarkdown in apps/web/components/task/chat/messages/thinking-message.tsx.
• Derive the preview from metadata.thinking or the current content fallback on every render.
• Keep the current compact single-line predicate and expandable-content condition.
• Render the preview for expandable content instead of limiting header text to compact messages.
• Give the header and preview flex regions min-w-0, keep the localized label non-shrinking, truncate only the expandable preview to one visual line, and keep compact text in a shrinkable wrapping region.

Component regression tests

• Add apps/web/components/task/chat/messages/thinking-message.test.tsx.
• First write a failing test for a Codex-shaped source containing leading blank lines, a bold first summary, and later details.
• Cover the empty-preview fallback, conservative inline Markdown stripping, compact single-line preservation and wrapping classes, rerendered appended content, expansion, and truncation classes.

Mobile browser evidence

• Extend apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts with a focused preview scenario.
• Seed leading blank lines, a long bold summary, and a later detail line through the existing mock-agent thinking command.
• Require the first summary in the collapsed row, reveal the later detail only after expansion, and assert that the preview truncates without chat or document horizontal overflow.

Tests

Acceptance criterion	Test evidence
AC-UI-THINKING-MESSAGE-PREVIEW-001.1	Component and mobile browser tests require the first meaningful line in the collapsed header.
AC-UI-THINKING-MESSAGE-PREVIEW-001.2	Component tests cover leading blank, decoration-only, and empty content.
AC-UI-THINKING-MESSAGE-PREVIEW-001.3	A component rerender test appends a later summary and keeps the original preview.
AC-UI-THINKING-MESSAGE-PREVIEW-001.4	Header class assertions and the mobile browser geometry scenario prove expandable one-line containment.
AC-UI-THINKING-MESSAGE-PREVIEW-001.5	Component and mobile browser tests expand the row and find the complete later content.
AC-UI-THINKING-MESSAGE-PREVIEW-001.6	A component test preserves compact inline and non-expandable rendering.
AC-UI-THINKING-MESSAGE-PREVIEW-001.7	The pure helper uses only the provider-neutral thinking string.

E2E tests

• Mobile: run the new thinking-preview scenario in apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts with the mobile-chrome project. This proves the shared component's visible preview, expansion path, expandable-preview truncation, compact full-text wrapping, and containment on the narrowest supported chat surface.
• Desktop behavior is covered by the shared component test because the change does not branch by viewport or pointer mode.

Mobile design contract

• Desktop outcome: an expandable thinking row shows its subject before the complete Markdown block is opened.
• Mobile entry point: the same thinking row in the existing task Chat tab.
• Nearest exemplar: the thinking-message scenario in apps/web/e2e/tests/chat/mobile-markdown-wrap.spec.ts.
• Hierarchy and surface: the localized label remains first; the preview is secondary inline content; the existing transcript remains the scroll owner.
• Presentation rationale: this shallow scan aid belongs in the existing row; a drawer, new route, or separate surface would add interaction without new content depth.
• Shared logic: desktop and mobile use the same preview derivation, expansion state, and complete Markdown content.
• Mobile proof: the new mobile-chrome scenario verifies preview visibility, expansion, expandable-preview truncation, compact full-text wrapping, and the absence of document overflow.

Work orders

• Task 01: Render thinking-message previews

Verification results

Implementation is complete. The exact task verification commands passed:

• Thinking-message component tests: 7 passed.
• Web typecheck, targeted ESLint, and Prettier checks passed.
• Specification tests and all specification files passed lint.
• Mobile Pixel 5 thinking-preview E2E: 2 passed with expandable-preview truncation, compact full-text wrapping, and no chat or document overflow.
• Fresh desktop and 393px mobile PR screenshots captured, inspected, and compressed.

Risks

• A source can begin with Markdown structure rather than a natural-language heading. The contract intentionally selects the first visible line instead of adding provider-specific or semantic ranking.
• Streaming can initially contain only blank lines. The label-only fallback must transition cleanly when the first meaningful content arrives.
• A long preview can widen nested flex content unless every ancestor in the header path permits shrinking.