Skip to content

feat(chat): styled tool-row hover with one shell pipeline stage per line - #18532

Merged
iamwhatever merged 1 commit into
mainfrom
feat/tool-row-hover-tooltip
Oct 10, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
feat/tool-row-hover-tooltip

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Hovering a tool-call row in chat shows its command in a readable, styled tooltip, with a shell pipeline laid out one stage per line.

The collapsed tool row carried its command in a native title. The OS tooltip appears after about a second, uses the proportional UI font, cannot be styled, and wraps a long pipeline mid-token, so cd website && npx tsc ... && npx vitest run ... reads as one undifferentiated block.

Why it matters

Agents run long chained shell commands constantly, and the hover is the quickest way to see what a row actually ran without expanding it. A tooltip that is slow and hard to parse defeats that.

Not a goal

  • Changing the expanded row's details panel, which already shows the full payload.
  • Formatting non-shell tool payloads beyond showing them as written.
  • Full shell parsing: heredocs and other multi-line commands are shown as written, not reflowed.

What changed (motivation → approach → change)

Hovering or focusing a folded tool row opens the app's InstantTip instead of the native title, so it appears after about 100ms, follows the theme, and the row it belongs to is marked while it is open (the hover fill plus a thin inset outline in the muted theme colour, visible in light and dark).

Piece What it does
website/src/utils/shellTipFormat.ts Splits a command at top-level `
website/src/pages/chat/ToolCommandTip.tsx Renders one stage per line in the monospace font, the joining operator in a left gutter (a pipe in the accent, && / `
website/src/pages/chat/ToolCallLine.tsx Gives the folded row the tooltip in place of title and marks the pill while it is open. The reflowed grid is aria-hidden; the tooltip carries the exact raw command in a screen-reader-only span. An expanded row shows no tooltip.
website/src/utils/toolCallTitle.ts deriveToolCallTitle reports shell alongside the icon kind, so a command shown as a read or search (cat, `rg …
website/src/components/InstantTip.tsx A bubble that opens above but would cross the top of the viewport opens below when there is more room there; when neither side fits, its top edge stays on screen so the start of the text is readable. Bubbles that fit above are unaffected.

docs/feature-map/README.md gains a "Tool row hover bubble" row. A website/scripts/capture-tool-pill-hover.mjs harness hovers rows in the built SPA, asserts the styled bubble (and that no native title remains), and shoots dark and light frames.

Backwards compatibility

Compatible: the row still exposes the same command text on hover and focus, in a tooltip instead of a title; no API, setting or stored data changes. InstantTip consumers whose bubble fits above keep their exact position.

Removes nothing: the hover content is the same command, presented in a different component.

Tests

  • website/src/test/ToolCommandTip.test.tsx (new): one stage per line led by its operator; no split inside quotes or substitutions; >| and 2>| read as one redirect; a leading env assignment is not the program; a trailing ; leaves no empty line; multi-line commands shown as written; no character lost; the raw command reaches assistive tech while the reflow is hidden; the length caps and the cut hint (line, character and prose cuts, absent when nothing is cut); pipes and sequencing operators get distinct gutter classes; the row shows the bubble instead of a title, wears the open-row classes only while it is open, and shows none once opened; a purpose-labelled rg … | head row gets the shell grid.
  • website/src/test/InstantTip.test.tsx: an above bubble that would cross the viewport top flips below; one that fits stays above; when neither side fits the top edge stays inside the viewport.
  • website/src/utils/toolCallTitle.test.ts: shell is true for classified shell reads/searches and live Running: titles, false for native and MCP calls.
  • website/src/test/ToolCallLine.test.tsx: the two checks that read the old title read the tooltip's verbatim text.
  • Determinism: the changed test files passed 3 runs each with --sequence.shuffle and random seeds. The 37 related frontend test files pass (1007 tests, including the focusRingContrast ratchet the pill's focus-ring-accent is held to); the i18n suites (745 tests) and npm run i18n:check pass.

Manual verification

Built the SPA on this head and ran website/scripts/capture-tool-pill-hover.mjs: the styled bubble appears on hover for a pipeline, an && chain, a recognised rg … | head search, a 14-stage command cut at 12 lines, and a file-read row's prose title, in dark and light themes, with the hovered row outlined and no native tooltip left.

Screenshots / video

Long pipeline, dark theme:

Tooltip for a pytest | grep | head pipeline in dark theme, one stage per line, hovered row outlined

&& chain, light theme:

Tooltip for a cd && tsc && vitest chain in light theme, one stage per line, hovered row outlined

A shell search the row labels as a search, dark theme:

Tooltip for rg -n InstantTip website/src | head -20 in dark theme, two stages

A non-shell row (file read) shows its title as prose, dark theme:

Prose tooltip for a file-read row in dark theme

A 14-stage command cut at 12 lines, light theme:

Tooltip for a 14-stage && chain in light theme, twelve lines then the cut hint

Other theme variants

Pipeline tooltip in light theme

Chain tooltip in dark theme

Search tooltip in light theme

Prose tooltip in light theme

Capped tooltip in dark theme

Related Issues

Closes #18522

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 9, 2026 17:09
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of e5614e5ccfd1413b7bdc062830640b04623d3c49 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the other useInstantTip consumers with tall bubbles near the viewport top still look right now that the shared InstantTip opens them below the anchor.

[DESIGN-REVIEWED] e5614e5

Description read

[DESCRIPTION-READ] 8a4b45004fbfa8869a51c1d1ac23fff16287432d3f45d7e25f5576809ac87372

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e5614e5ccfd1413b7bdc062830640b04623d3c49 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

InstantTip's new flip-below rule also applies to FilePreviewStrip.tsx:17, the only other default-above consumer. Check its bubble near the viewport top.

What this change ships

Inventory (9 items) — 9 justified

Intent: when someone hovers a folded tool row, they can read the command it ran quickly and clearly, without expanding the row. ADDITION (Closes #18522).

  1. A folded tool row's hover or focus shows a styled bubble after about 100ms instead of the slow native title — justified
  2. A shell command in that bubble shows one pipeline stage per line, with the joining operator in a gutter and words coloured by role — justified
  3. A non-shell tool's title shows as wrapped prose in the same bubble — justified
  4. The bubble stops at 1200 characters or 12 lines and ends with a translated "Open the step" hint — justified
  5. The row is outlined and tinted while its bubble is open — justified
  6. An expanded row shows no hover bubble at all — justified
  7. Any default-above InstantTip that would cross the viewport top now opens below, or stays clamped on screen — justified
  8. deriveToolCallTitle reports a new shell flag, read by one consumer (ToolCallLine) — justified
  9. A new screenshot harness capture-tool-pill-hover.mjs and a new feature-map row — justified

[FIRST-PRINCIPLES-REVIEWED] e5614e5

Description read

[DESCRIPTION-READ] 74734b46153bbaccd4319df539e294a6a68331476226136b30ae1f6da1400f44

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

UX-level review of e5614e5ccfd1413b7bdc062830640b04623d3c49 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

The cut-off note "… Open the step to see the rest" names an action the reader couldn't find; they asked "Do I click the step name?"

Watch

  • The cut-off note doesn't say how to see the rest. tip_cut_hint tells the user to "Open the step", but in shots 05 and 10 nothing reads as an open control. The blind reader wrote: "I don't know how to 'open' a step… Nothing in the screenshots looks like an 'open' button." This only appears on long commands, but those are exactly the ones a user most wants to read in full, so they're left stuck at the cut. Severity: rare × friction × every time it appears. Smallest fix: name the gesture, e.g. "… Click the step to see the full command".
  • Readers only guessed that the bubble belongs to the step below it. The reader got it right in shots 01–03 but rated it "a guess". The bubble has no arrow, it hides the step above (shots 03 and 08), and the outline is the only link back. Severity: every hover × mild friction. Smallest fix: add a small pointer or caret aimed at the hovered row.

Suggestions

  • Shots 02 and 07 are both dark, so the light-theme && chain was shown with no dark counterpart and vice versa. Replace one with the matching theme variant so every case is shown in both themes.

[UX-REVIEWED] e5614e5

Description read

[DESCRIPTION-READ] c6505e15d1af8d0bb28f4f146d7a6f3573488bdfa973d158ef259ee090494bb5

That sha256 names everything this verdict read: the PR description, plus the 13 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 9, 2026
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed e5614e5ccfd1413b7bdc062830640b04623d3c49 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] e5614e5

Verdict parsed from the review's SHA-scoped output markers for commit e5614e5ccfd1413b7bdc062830640b04623d3c49.

False positive or not applicable? A repository writer can comment:
/ai-review override fable e5614e5ccfd1413b7bdc062830640b04623d3c49: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of e5614e5ccfd1413b7bdc062830640b04623d3c49 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e5614e5

False positive or not applicable? A repository writer can comment:
/ai-review override gpt e5614e5ccfd1413b7bdc062830640b04623d3c49: <one-sentence reason>

@kyleseaman
kyleseaman force-pushed the feat/tool-row-hover-tooltip branch from bb7fa61 to 92e7d7b Compare October 9, 2026 18:01
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 9, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=2a548f98fa3a: readers cannot tell which row a bubble belongs to

fixed in 92e7d7b: the pill whose bubble is open is tinted with the theme's bg-bg-hover while the bubble is open, and only then (pillTipOpen in website/src/pages/chat/ToolCallLine.tsx).
Locked in by the ToolCommandTip.test.tsx case that tints the pill whose bubble is open, and only while it is open; the r4 screenshots in the description show the tinted row under each bubble.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=7b071b607b65: the main hover was read correctly but only as a guess

fixed in 92e7d7b by the same change as the row-link item: the hovered row is tinted while its bubble is open, which ties the bubble to the step it describes.
The description adds the evidence the BLOCK asked for: a file-read row's prose bubble and a 14-stage command cut at 12 lines with its marker, in both themes.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=e50abe8f394b: >| tokenized as > so | split the line

fixed in 92e7d7b: website/src/utils/shellTipFormat.ts tries >\| before >>?, so echo x >| out.txt and 2>| f stay one redirect on one line.
Regression test in website/src/test/ToolCommandTip.test.tsx fails with the old alternation order and passes with the fix.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

E2E (stub ACP backend, offline) is red on 92e7d7b only because session-tags-e2e.spec.ts 17b passed on a retry (ceiling 0). That is the known flake in #17941, seen on many unrelated PRs; this diff touches no sidebar, tag or context-menu code. Recorded the sighting on #17941. #18529 makes 17b retry-safe; this PR waits for it to merge, then rebases onto it rather than rerunning a test already reported more than twice this fortnight.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 9, 2026
@kyleseaman
kyleseaman force-pushed the feat/tool-row-hover-tooltip branch from 92e7d7b to 641f0f4 Compare October 9, 2026 18:30
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/pages/chat/ToolCallLine.tsx (#18500 Tool calls start expanded) and GitHub marked this PR conflicting (d4c3a73 -> c241d6b). The only conflict was the import block; range-diff shows the patch otherwise unchanged. tsc, eslint and the 27 related frontend test files (755 tests) pass on 641f0f4; CI re-running.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 9, 2026
@kyleseaman
kyleseaman force-pushed the feat/tool-row-hover-tooltip branch from 641f0f4 to b9ca7e5 Compare October 9, 2026 19:14
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=0158f5d0f949: light-theme tint is invisible

fixed in b9ca7e5: --bg-hover sits about 1.1:1 off --bg on every light palette, so no fill alone can mark the row. While its bubble is open the pill wears PILL_TIP_OPEN_CLASS (website/src/pages/chat/ToolCommandTip.tsx): the hover fill plus a 1px inset outline in neutral --muted, at least 3.8:1 against the fill on every light palette.
The light frames in the description (chain, capped, classified, prose) show the outlined row; ToolCommandTip.test.tsx asserts every open-row class is added with the bubble and removed with it.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=3491d1f08013: a cut-off command gives no way to see the rest

fixed in b9ca7e5: a cut bubble (12 lines, 1200 characters, or a long prose title) ends in a muted "… Open the step to see the rest", from pages.chat.toolCallLine.tip_cut_hint in every locale catalog.
Screen readers still get the full verbatim command, so they hear no hint about a cut they never got. Tests cover all three cuts and the no-cut case; the capped frames show it.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=cff955a39f93: the main tooltip was read correctly but only as a guess

fixed in b9ca7e5 by the open-row outline (span 0158f5d0f949): the row the bubble describes is outlined in both themes, which is the link the reader was missing.
No separate change, as the item itself suggests.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=82a17b39a173: pipe and && share one gutter colour

fixed in b9ca7e5: the gutter paints a pipe (|, |&) in the accent and the sequencing operators (&&, ||, ;) muted, so a pipeline reads apart from a chain (PIPE_OPS in website/src/pages/chat/ToolCommandTip.tsx).
ToolCommandTip.test.tsx asserts the distinct classes; compare the pipeline and chain frames.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 9, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

main went red on src/test/focusRingContrast.test.ts (AskAnswersCard.tsx kept an accent-only focus ring when #15250 and #17705 crossed): #18577, fix in #18581. This PR also conflicts with #17705 in ToolCallLine.tsx; the rebase that resolves it (pill keeps focus-ring-accent plus the open-row classes) is ready locally and goes out once #18581 merges, so it is not pushed onto a red base.

@kyleseaman
kyleseaman force-pushed the feat/tool-row-hover-tooltip branch from b9ca7e5 to a6f4c4a Compare October 9, 2026 21:23
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Rebased onto aee520e, which carries the red-main fix #18581 and #17705's focus-ring migration (b9ca7e5 -> a6f4c4a). The only conflict was the pill's className: it keeps focus-ring-accent plus the open-row classes. tsc, the 37 related frontend test files (1007 tests, incl. focusRingContrast), the i18n suites and i18n:check, and the feature-map check pass; local GPT and Opus reviews found nothing. CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 9, 2026
@kyleseaman
kyleseaman force-pushed the feat/tool-row-hover-tooltip branch from a6f4c4a to e5614e5 Compare October 10, 2026 01:18
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 10, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Rebased onto main to pick up #18644, which fixed the session-tags 17b flake (#17941) that was the only red on a6f4c4a (a6f4c4a -> e5614e5). range-diff shows the patch unchanged; tsc, the 37 related frontend test files (1007 tests), the i18n suites, i18n:check and the feature-map check pass. CI re-running.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=4075af94acfe: the cut-off note does not say how to see the rest

rebutted: the step the note names is the row directly under the bubble, and that row is the control: it is a button whose click opens the step's details with the full payload, with a pointer cursor and hover brightening. A static frame cannot show either cue, which is why the blind reader saw no "open" control; in the live app the hovered row is also outlined while the bubble is up.
"Step" is the word the existing tool-row strings already use for that row, so the hint names it the way the rest of the transcript does. Kept as shipped.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=29837bf50004: readers only guessed the bubble belongs to the step below it

rebutted as disproportional: the reader matched every bubble to the right step in shots 01-03, and the open-row outline (added for this exact concern) is the link back. An arrow or a different anchor would change the shared InstantTip placement for every consumer in the app, which is outside this PR's goal.
The bubble covering the row above is the house above-placement rule; it flips below when it would leave the viewport.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • span=cf12b9e812a1: shots 02 and 07 are both dark

rebutted: the attachments disagree. Shot 02 is the && chain on the light theme (white surface, dark text) and shot 07 is the same chain on the dark theme; I downloaded both attachments from the description and checked them.
Every case (pipeline, chain, classified search, prose, capped) is shown once per theme across the ten frames, so no swap is needed.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 10, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR swaps the folded tool row's native title for the app's InstantTip, with a shell command laid out one pipeline stage per line (utils/shellTipFormat.ts, pages/chat/ToolCommandTip.tsx). The slow, mid-word-wrapping OS tooltip is fixed at its source. I read the production diff. The tokenizer is display-only and keeps quotes, $(...), backticks, 2>&1 and >| (the earlier Opus finding, fixed with a regression test) from splitting a line. Screen readers get the verbatim command, and output is capped at 1200 characters or 12 lines. The shared InstantTip change only affects an above bubble that would leave the viewport top: it now flips below when there is more room. Bubbles that fit are unchanged. All three UX CONCERNS items on head e5614e5 have per-span dispositions, and the rebuttals are reasonable (the row itself is the click target, and an arrow would change shared InstantTip placement). Design and First Principles PASS, checks are green, base is main, and no change request is open. — crew-pr-reviewer

@iamwhatever
iamwhatever enabled auto-merge (squash) October 10, 2026 07:57
@iamwhatever
iamwhatever merged commit 0327a05 into main Oct 10, 2026
102 checks passed
@iamwhatever
iamwhatever deleted the feat/tool-row-hover-tooltip branch October 10, 2026 07:57
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Readable, styled hover for tool-call rows (shell pipelines one stage per line)

2 participants