From 0c227968b12eb7da5ab8dfb16220aeb58bc6a967 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 01:44:59 -0600 Subject: [PATCH 1/3] docs: plan for the transcript refresh (PR 3 of 5) Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_011Ya6qvLmxrim1dK1KjEpJ7 --- .../2026-11-16-chat-refresh-transcript.md | 145 ++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-16-chat-refresh-transcript.md diff --git a/docs/superpowers/plans/2026-11-16-chat-refresh-transcript.md b/docs/superpowers/plans/2026-11-16-chat-refresh-transcript.md new file mode 100644 index 00000000..ee3397b3 --- /dev/null +++ b/docs/superpowers/plans/2026-11-16-chat-refresh-transcript.md @@ -0,0 +1,145 @@ +# Chat Refresh Transcript (PR 3 of 5) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make the transcript read as one quiet column: each turn is one element, its status is a small inline toggle, work is a list of 34 px rows, an answered approval is a receipt row, and reply actions stay out of the way until the turn is pointed at. + +**Architecture:** `TurnContent` wraps what it renders today in one `.turn` element, so spacing, hover and focus can be scoped to a turn; the column rule that applied to the transcript's children moves to the wrapper's children at the same place in the stylesheet, so the cascade is unchanged. Thinking, tool, route and receipt rows share one row style (the one the route row already has). Wording and row kind are pure functions in `src/shared`, unit tested; the components only place them. Markup changes keep every existing `data-testid`, role and accessible name on the element that keeps the meaning. + +**Tech Stack:** Existing TypeScript, React 19, Playwright; no new dependencies. + +**Spec:** `docs/superpowers/specs/2026-11-15-chat-prompts-refresh-design.md`, section "3. Transcript" and the receipt rows of "States the prototype did not show". Stacked on PR 2 (`chat-refresh-menus`). + +## Scope calls (for Val to check) + +1. **The reading column stays 938 px in this PR.** The design narrows it to 760 px for the transcript and the composer together; `layout.spec.ts` pins "column = composer box − 22 px". It moves with the composer in PR 5. +2. **An answered approval becomes a receipt row now; a waiting approval and the question card keep today's card.** The waiting card is replaced by the request panel in PR 4, and the answered question card (one answer per question, read by several specs) moves to a row there with the panel's question variant. +3. **Focus after an answer does not change here.** It still lands on the answer word, which is now in the receipt row. PR 4 moves it to the message box, as designed. +4. **A verb only for commands.** "Ran `$ git status`" / "Running …". Other tools' summaries come from the CLI's own title and already read as a phrase ("edit CONTRIBUTING.md"), so a verb in front would double it. Every row gets an icon for its kind. + +## Global Constraints + +- A work row is `34px` high with a `22px` icon tile (`--radius-xs`, `--tint-strong`), `10px` gap, text `--text-sm`; the target is `12.5px` `--font-mono`; meta is `--text-xs` in `--text-info` at the right. +- Row hover is `--tint`. Rows hang `6px` into the left margin so the tile, not the hover fill, sits on the column edge. +- The turn status line has no rule under it: `--text-sm`, weight `500`, `--text-3`, `26px` high. A live turn shows a `7px` dot: pulsing in `--text-1` while working, steady in `--warn` while waiting. Working text shimmers. +- Existing ids, roles and names stay: `turn-header` (`data-live`), `turn-label` (text exactly "Worked for 38s", "Working for 7s", "Waiting for approval · 7s", "Waiting for your answer · 7s"; a `button` with `aria-expanded` when the turn has work), `item`, `item-toggle`, `item-body`, `tool-title`, `tool-summary` (text unchanged), `tool-meta`, `thinking-label`, `approval-receipt`, `receipt-meta`, `approval-answer` (text unchanged, `tabindex="-1"`), `answer-note`, `approval-reason`, `message-actions`, `jump-latest` (accessible name "Jump to latest"). +- The tool row's `aria-label` stays `": "`. +- Decision words are unchanged: "Approved", "Approved — always for this command", "Denied", "Sending decision…", "Delivery uncertain — not resent", and the three withdrawn sentences. +- Hidden reply actions use `opacity`, never `display` or `visibility`: they stay in the tab order and show on `:focus-within`. On a device without hover they always show. +- No animation under `prefers-reduced-motion`; under `forced-colors` the tile and the jump button get a system-colour border. +- Only dots are round (`50%`); the radius guard in `scripts/test/radius-scale.test.mjs` counts them per file and its count for `styles.css` changes with this PR. +- No behavior change: folding, focus hand-off to the turn toggle, scroll following and "Jump to latest" keep their logic. + +## Review Focus + +1. **A finished turn folds while focus is on the answer word of a receipt row.** Expected: focus moves to the turn's toggle, as today. Pinned by `keyboard-answers.spec.ts` (unchanged) and Task 2's markup keeping `approval-answer` focusable outside any button. +2. **An approval whose delivery is uncertain, loaded from disk.** Expected: a receipt row in the warn tone reading "Delivery uncertain — not resent", `data-answered="false"`, and the note under it. Pinned in Task 1 (unit) and Task 4 (spec). +3. **A stored thread with a tool the app has no kind for.** Expected: a row with the generic icon and today's summary, never an empty tile or a verb. Pinned in Task 1. +4. **Keyboard only, an older turn.** Expected: tabbing into the turn shows its reply actions; they are reachable without the pointer. Pinned in Task 4. +5. **A reader scrolled up in a long thread.** Expected: the jump button is a 32 px square that still reads "Jump to latest" to assistive tech and still returns focus to the message box. Pinned by the existing jump specs plus Task 4's size and name check. + +--- + +### Task 1: Row kind, verb and answered-approval wording in `src/shared` + +**Files:** +- Modify: `apps/desktop/src/shared/tool-summary.ts` +- Modify: `apps/desktop/src/shared/approval-receipt.ts` +- Test: `apps/desktop/test/tool-summary.test.ts`, `apps/desktop/test/approval-receipt.test.ts` + +**Interfaces (produced):** + +```ts +// tool-summary.ts +export type ToolKind = "command" | "edit" | "search" | "fetch" | "agent" | "file" | "other"; +export function toolKind(item: Extract): ToolKind; +/** "Ran" or "Running" for a row whose summary is a command line ("$ …"); null for every other row. */ +export function toolVerb(item: Extract): "Ran" | "Running" | null; + +// approval-receipt.ts +export type AnsweredTone = "allowed" | "refused" | "warn" | "neutral"; +export interface AnsweredApproval { text: string; tone: AnsweredTone; by: string | null } +/** The receipt row for an approval a person answered, or that closed unanswered. Null while it waits. */ +export function answeredApproval(item: Extract): AnsweredApproval | null; +``` + +- [ ] **Step 1: failing tests** + +```ts +test("a row's kind follows the tool, and only a command line gets a verb", () => { + assert.deepEqual([ + toolKind(tool({ name: "shell", args: { command: "git status" } })), toolKind(tool({ name: "Bash", title: "Bash", args: { command: "npm test" } })), + toolKind(tool({ name: "apply_patch" })), toolKind(tool({ name: "Write", args: { file_path: "a.ts" } })), toolKind(tool({ name: "write_file", args: { path: "a.ts" } })), + toolKind(tool({ name: "WebSearch" })), toolKind(tool({ name: "webSearch" })), toolKind(tool({ name: "WebFetch" })), + toolKind(tool({ name: "Agent", args: { description: "x" } })), toolKind(tool({ name: "read_file", args: { file_path: "a.ts" } })), toolKind(tool({ name: "mystery" })), + ], ["command", "command", "edit", "edit", "edit", "search", "search", "fetch", "agent", "file", "other"]); + assert.equal(toolVerb(tool({ name: "shell", args: { command: "git status" } })), "Running"); + assert.equal(toolVerb(tool({ name: "shell", status: "done", args: { command: "git status" } })), "Ran"); + assert.equal(toolVerb(tool({ title: "$ git status", status: "done" })), "Ran"); + assert.equal(toolVerb(tool({ name: "Bash", title: "Run the tests", status: "done", args: { command: "npm test" } })), null, "a CLI title is already a phrase"); + assert.equal(toolVerb(tool({ name: "read_file", status: "done", args: { file_path: "a.ts" } })), null); +}); + +test("an answered approval reads as one receipt line; a waiting one has none", () => { + const approval = (over: object) => ({ id: "a", kind: "approval" as const, question: "Allow?", at: "", ...over }); + assert.equal(answeredApproval(approval({})), null); + assert.deepEqual(answeredApproval(approval({ answer: "yes", answeredBy: "desktop" })), { text: "Approved", tone: "allowed", by: "by you" }); + assert.deepEqual(answeredApproval(approval({ answer: "always", answeredBy: "desktop" })), { text: "Approved — always for this command", tone: "allowed", by: "by you" }); + assert.deepEqual(answeredApproval(approval({ answer: "no", answeredBy: "desktop" })), { text: "Denied", tone: "refused", by: "by you" }); + assert.deepEqual(answeredApproval(approval({ answer: "yes", answeredBy: "phone" })), { text: "Approved", tone: "allowed", by: null }, "the note under the row says where it was answered"); + assert.deepEqual(answeredApproval(approval({ answer: "yes" })), { text: "Approved", tone: "allowed", by: null }, "an answer saved before the field existed claims nobody"); + assert.deepEqual(answeredApproval(approval({ answer: "yes", delivery: "sending" })), { text: "Sending decision…", tone: "neutral", by: null }); + assert.deepEqual(answeredApproval(approval({ answer: "yes", delivery: "uncertain" })), { text: "Delivery uncertain — not resent", tone: "warn", by: null }); + assert.deepEqual(answeredApproval(approval({ answer: "no", withdrawn: "stopped" })), { text: "Not answered — the turn was stopped", tone: "neutral", by: null }); + assert.deepEqual(answeredApproval(approval({ answer: "no", withdrawn: "native" })), { text: "Withdrawn — the agent no longer needs an answer", tone: "neutral", by: null }); + assert.deepEqual(answeredApproval(approval({ answer: "no", withdrawn: "ended" })), { text: "Not answered — the turn ended first", tone: "neutral", by: null }); +}); +``` + +- [ ] **Step 2:** run them, expect "toolKind is not a function". +- [ ] **Step 3:** implement. Precedence in `answeredApproval` is today's: uncertain, then sending, then withdrawn, then the answer. `by` is "by you" only when `answeredBy === "desktop"`, the value main records for an answer given in this window; a phone or paired-desktop answer has its note instead, and an answer saved before the field existed claims nobody. `toolKind`: search and fetch by name (`WebSearch`, `webSearch`, `WebFetch`); agent by `Agent`/`Task`; edit by `PATCH_TOOLS` plus `write_file`; command when a `command` argument is a non-empty string or the name is `shell`/`Bash`; file when a path argument exists; else other. `toolVerb` is non-null only when `toolSummary(item)` starts with `"$ "`. +- [ ] **Step 4:** run them, expect pass. **Step 5:** commit. + +### Task 2: Markup — turn wrapper, status line, rows, receipts, jump button + +**Files:** +- Modify: `apps/desktop/src/renderer/components/transcript/TurnContent.tsx`, `ReasoningItem.tsx` +- Modify: `apps/desktop/src/renderer/components/ThreadView.tsx` (`ToolItem`, `ApprovalItem`, `ApprovalReceiptRow`, the jump button) +- Modify: `apps/desktop/src/renderer/components/ui/Icon.tsx` (`arrow-down`, `thought`) + +**Consumes:** Task 1's `toolKind`, `toolVerb`, `answeredApproval`. + +- [ ] `TurnContent` returns `
` around the user message, header, content and footer. Refs and effects are untouched. +- [ ] `TurnHeader`: class gains `waiting` while `status === "waiting"`; the label's text sits in ``; a live label starts with `