@workerdeck/ui 0.20.0 → 0.22.0

package/src/components/agent/Transcript.tsx

@@ -31,6 +31,7 @@ import { taskBrief } from '../terminal/tool-run.ts'
 import { taskBusy } from '../terminal/tool-run.ts'
 import { briefPx, estimateBlockPx } from '../terminal/height.ts'
 import { TerminalScrubber } from '../terminal/scrubber.tsx'
+import { Scrubber } from './Scrubber.tsx'
 import { gapBefore, positionInRow, rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
 import { useHeightEpoch } from './use-height-epoch.ts'
 import { useTranscriptJumps } from './use-transcript-jumps.ts'
@@ -320,59 +321,106 @@ function nestedClass(item: TranscriptItem, frameParentId?: string): string | und
 // here because this file is where consumers have always found them.
 export { rowIndexForItem, type TranscriptRow } from './transcript-rows.ts'
 
+/** The cards head's one line: the prompt as a plain run of text. Deliberately
+ * not the Message component — a proportional card clipped by height is a
+ * sliced bubble, and un-styling one from CSS is a fight (see theme.css's
+ * sticky-prompt block for the other half of this decision). Prompt syntax
+ * stays literal — a 28px bar is a reminder of what was asked, not a rendering
+ * surface — and newlines collapse under the bar's `nowrap`. Attachment-only
+ * prompts fall back to the attachments' names so the bar is never blank. */
+function promptHeadText(item: Extract<TranscriptItem, { kind: 'user' }>): string {
+  return item.text || (item.attachments ?? []).map((attachment) => attachment.name).join(', ')
+}
+
 /**
  * A prompt row's sticky lane — the strip spanning its turn, leading with the
  * one-line pinned **head** (see the pinned-prompt comment in
  * {@link TranscriptRows}).
  *
+ * The head's content is the variant's: the terminal passes the row again
+ * (clipping it to one line is exact under a monospace grid), cards passes the
+ * prompt as plain text for theme.css to draw as a compact bar. Only the
+ * terminal head carries the row's gap class — its stuck geometry parks that
+ * padding above the viewport edge so the visible line docks at zero
+ * (terminal.css); the cards bar never aligns with the row in flow, so the gap
+ * stays off it entirely and the 1st prompt and the Nth share one geometry.
+ *
  * The head starts `visibility: hidden` and shows only while actually stuck —
  * an overlay that is visible in flow would sit on the real row's first line
  * and swallow its selection highlight, which reads as "the first line cannot
  * be selected". CSS cannot ask "am I stuck?", so a 1px sentinel at the head's
- * engage threshold (the line's own y) feeds an IntersectionObserver: sentinel
- * above the scrollport top → stuck. Transition-only callbacks — this adds no
- * per-scroll work, and the pin itself is still the compositor's.
+ * engage threshold (the line's own y) answers it: sentinel above the
+ * scrollport top → stuck, read by a passive scroll listener. It was an
+ * IntersectionObserver once, for the "no per-scroll work" purity — and that
+ * was a real bug: IO is edge-triggered, and an *instant* jump (the open-at-
+ * bottom pin, `jumpToRow`, a reveal) teleports the sentinel from below the
+ * viewport to above it between two observations — ratio 0 → 0, no threshold
+ * crossed, `isIntersecting` unchanged — so no entry is ever queued and the
+ * flag strands, in whichever direction the jump left it (observed: a session
+ * opened at the bottom, its prompt bar missing; the stale-true twin paints a
+ * bar over the real bubble). The flag needs level-triggered truth. The cost
+ * is two rect reads per scroll event per mounted lane — layout is clean
+ * during scrolling, and the pin itself is still the compositor's; only the
+ * bar's visibility rides the listener.
  */
 function StickyPromptLane({
   top,
   height,
   gapClass,
+  gapPx,
+  terminal,
   scrollRoot,
   index,
   measureRef,
+  head,
   content,
 }: {
   top: number
   height: number
   gapClass?: string | false
+  /** The gap's size in px (`ROW_GAP[...].px`) — the cards sentinel offset,
+   * where the terminal uses `--term-line` (exact against its own cell where a
+   * px constant would drift). */
+  gapPx: number
+  terminal: boolean
   scrollRoot: HTMLElement | null
   index: number
   measureRef: (element: HTMLDivElement | null) => void
+  /** What the pinned head shows — see the component comment. */
+  head: ReactNode
   content: ReactNode
 }) {
   const headRef = useRef<HTMLDivElement | null>(null)
   const sentinelRef = useRef<HTMLDivElement | null>(null)
+  // `top`/`height`/`gapClass` are deps because they move the sentinel without
+  // any scroll: a measurement refinement re-positions the lane under a still
+  // scroller, and only a fresh evaluation notices. Scroll covers the rest —
+  // including programmatic jumps, which fire a scroll event like any other
+  // write of `scrollTop`.
   useEffect(() => {
-    const head = headRef.current
+    const headElement = headRef.current
     const sentinel = sentinelRef.current
-    if (!head || !sentinel || !scrollRoot) return
-    const observer = new IntersectionObserver(
-      ([entry]) => {
-        if (!entry) return
-        // Above the scrollport, not merely out of it — a lane still below the
-        // viewport has its sentinel non-intersecting too.
-        const stuck =
-          !entry.isIntersecting &&
-          entry.boundingClientRect.top < (entry.rootBounds?.top ?? 0)
-        head.toggleAttribute('data-stuck', stuck)
-      },
-      { root: scrollRoot },
-    )
-    observer.observe(sentinel)
-    return () => observer.disconnect()
-  }, [scrollRoot])
+    if (!headElement || !sentinel || !scrollRoot) return
+    const evaluate = () => {
+      // Strictly above the scrollport's top edge — at exact equality the real
+      // row's first line is itself flush with the top, and the head must not
+      // cover it.
+      const stuck =
+        sentinel.getBoundingClientRect().top < scrollRoot.getBoundingClientRect().top
+      headElement.toggleAttribute('data-stuck', stuck)
+    }
+    evaluate()
+    scrollRoot.addEventListener('scroll', evaluate, { passive: true })
+    return () => scrollRoot.removeEventListener('scroll', evaluate)
+  }, [scrollRoot, top, height, gapClass])
   return (
-    <div data-sticky-lane='' className='absolute inset-x-0' style={{ top, height }}>
+    // The attribute VALUE is the styling seam: terminal.css matches the bare
+    // attribute under its `[data-terminal]` scope, theme.css keys the cards
+    // bar on `[data-sticky-lane='cards']` — no `:not()` acrobatics either side.
+    <div
+      data-sticky-lane={terminal ? 'terminal' : 'cards'}
+      className='absolute inset-x-0'
+      style={{ top, height }}>
       {/* The head rides in its own absolutely positioned sub-lane rather than
           in flow with a cancelled footprint: sticky confinement clamps the
           *margin* box, and a negative bottom margin shrinks that box to zero
@@ -381,15 +429,15 @@ function StickyPromptLane({
           Out of flow, the border box is what gets clamped, and the push-off
           lands exactly at the lane's bottom edge. */}
       <div data-sticky-headlane='' aria-hidden>
-        <div ref={headRef} data-sticky-head='' className={gapClass || undefined}>
-          {content}
+        <div ref={headRef} data-sticky-head='' className={(terminal && gapClass) || undefined}>
+          {head}
         </div>
       </div>
       <div
         ref={sentinelRef}
         aria-hidden
         className='absolute left-0 w-px'
-        style={{ top: gapClass ? 'var(--term-line)' : 0, height: 1 }}
+        style={{ top: gapClass ? (terminal ? 'var(--term-line)' : gapPx) : 0, height: 1 }}
       />
       <div ref={measureRef} data-index={index} className={gapClass || undefined}>
         {content}
@@ -525,7 +573,7 @@ function TranscriptRows({
     enabled: false,
     promptRows: [],
   })
-  pinRef.current = { enabled: terminal && stickyPrompt, promptRows }
+  pinRef.current = { enabled: stickyPrompt, promptRows }
   useEffect(() => {
     setScrollElement(stick.scrollRef.current)
   }, [stick.scrollRef])
@@ -882,13 +930,15 @@ function TranscriptRows({
             </div>
           )
         // A prompt row's sticky lane — see the pinned-prompt comment above.
-        // The lane is sized to the turn; the sticky **head** (one clipped
-        // line, the same content again) comes first with its flow footprint
-        // cancelled, and the *measured* element is the real row after it, so
-        // the virtualizer's heights are untouched by either. Both carry the
-        // gap class: the row because the gap is part of its measured height,
-        // the head so its one visible line sits on the same y while in flow —
-        // the pin parks that padding above the viewport edge when stuck.
+        // The lane is sized to the turn; the sticky **head** comes first, out
+        // of flow, and the *measured* element is the real row after it, so
+        // the virtualizer's heights are untouched by either. Under terminal
+        // the head is the same content again clipped to one line, and carries
+        // the row's gap class so its visible line sits on the same y while in
+        // flow (the pin parks that padding above the viewport edge when
+        // stuck). Under cards the head is the prompt as plain text — theme.css
+        // draws it as a compact bar — and carries no gap class: it is never
+        // an in-flow overlay of the row, so it has no y to match.
         // Positioned with `top`, NOT the translate every other row gets:
         // `position: sticky` is resolved at layout time and a transform is
         // paint-only, so under a translate the head would stick against the
@@ -897,7 +947,6 @@ function TranscriptRows({
         // Same predicate as `promptRows` above — the lane and the forced range
         // must agree on which rows are prompts.
         if (
-          terminal &&
           stickyPrompt &&
           'item' in row &&
           row.item.kind === 'user' &&
@@ -914,9 +963,12 @@ function TranscriptRows({
               top={virtualRow.start}
               height={Math.max(laneEnd - virtualRow.start, 0)}
               gapClass={gapClass}
+              gapPx={gap.px}
+              terminal={terminal}
               scrollRoot={scrollElement}
               index={virtualRow.index}
               measureRef={virtualizer.measureElement}
+              head={terminal ? content : promptHeadText(row.item)}
               content={content}
             />
           )
@@ -938,31 +990,38 @@ function TranscriptRows({
           — the virtualizer's offsets, the epoch, the row list, the jump — is
           this component's. The portal target is the Conversation root
           (`relative`), the same containing block the scroll button uses. */}
-      {terminal && scrubber && scrollElement?.parentElement
+      {scrubber && scrollElement?.parentElement
         ? createPortal(
-            <TerminalScrubber
-              items={items}
-              pendingApprovals={pendingApprovals}
-              recapRow={recapRow}
-              bookmarks={scrubberMarks ?? []}
-              frameParentId={frameParentId}
-              rowIndexFor={(itemIndex) => rowIndexForItem(rows, itemIndex)}
-              positionInRow={(itemIndex) => positionInRow(rows, itemIndex)}
-              // The public memoized measurements array — `getTotalSize()` just
-              // above refreshed it, and with the calculator feeding
-              // `estimateSize` these starts are honest for unmounted rows too.
-              offsetOfRow={(rowIndex) => virtualizer.measurementsCache[rowIndex]?.start ?? 0}
-              sizeOfRow={(rowIndex) => virtualizer.measurementsCache[rowIndex]?.size ?? 0}
-              totalSize={virtualizer.getTotalSize()}
-              scrollOffset={virtualizer.scrollOffset ?? 0}
-              viewportH={virtualizer.scrollRect?.height ?? 0}
-              // To the top: a mark is where you start reading, not the middle of
-              // what you want to see.
-              onJumpToRow={(rowIndex) => jumpToRow(rowIndex, 'start')}
-              interactive={scrubInteractive}
-              fontSize={fontSize}
-              lineHeight={lineHeight}
-            />,
+            terminal ? (
+              <TerminalScrubber
+                items={items}
+                pendingApprovals={pendingApprovals}
+                recapRow={recapRow}
+                bookmarks={scrubberMarks ?? []}
+                frameParentId={frameParentId}
+                rowIndexFor={(itemIndex) => rowIndexForItem(rows, itemIndex)}
+                positionInRow={(itemIndex) => positionInRow(rows, itemIndex)}
+                offsetOfRow={(rowIndex) => virtualizer.measurementsCache[rowIndex]?.start ?? 0}
+                sizeOfRow={(rowIndex) => virtualizer.measurementsCache[rowIndex]?.size ?? 0}
+                totalSize={virtualizer.getTotalSize()}
+                scrollOffset={virtualizer.scrollOffset ?? 0}
+                viewportH={virtualizer.scrollRect?.height ?? 0}
+                onJumpToRow={(rowIndex) => jumpToRow(rowIndex, 'start')}
+                interactive={scrubInteractive}
+                fontSize={fontSize}
+                lineHeight={lineHeight}
+              />
+            ) : (
+              <Scrubber
+                items={items}
+                pendingApprovals={pendingApprovals}
+                recapItemIndex={recapIndex >= 0 ? boundary : undefined}
+                bookmarks={scrubberMarks}
+                frameParentId={frameParentId}
+                interactive={scrubInteractive}
+                onJumpToItem={(itemIndex) => jumpToRow(rowIndexForItem(rows, itemIndex), 'start')}
+              />
+            ),
             scrollElement.parentElement,
           )
         : null}
@@ -1004,17 +1063,21 @@ export interface TranscriptProps {
   /** Terminal theme only: the pointer affordances a real terminal cannot offer.
    * `false` for none. See {@link TerminalAffordances}. */
   affordances?: TerminalAffordances | boolean
-  /** Terminal theme only: hold the prompt of the turn being read at the top of
-   * the scroller. The *real* row is pinned, not a copy — see `TranscriptRows`. */
+  /** Hold the prompt of the turn being read at the top of the scroller. Works
+   * in both variants: the terminal clips to one line, cards shows a frosted
+   * bar. The *real* row is pinned, not a copy — see `TranscriptRows`. */
   stickyPrompt?: boolean
   /**
-   * Terminal theme only: mount the overview-ruler scrubber — a 2ch rail of
-   * marks (your prompts, each turn's response and result as one mark, errors,
-   * the pending approval, the catch-up boundary) that replaces the native
-   * scrollbar. Ignored under `cards`: the rail's positions ride the height
-   * calculator, which has no claim there. With `affordances={false}` the rail
-   * degrades to passive paint — no drag, peek or click — and the native
-   * scrollbar stays. See {@link TerminalScrubber}.
+   * Mount the overview scrubber — a 12px rail of marks (your prompts, each
+   * turn's response and result as one mark, errors, the pending approval, the
+   * catch-up boundary) over the scroller's right edge. Two rails behind one
+   * prop: under `terminal` it is the pixel-exact ruler that replaces the
+   * native scrollbar (positions ride the height calculator; drag scrubs), and
+   * under `cards` it is the **proportional annotation rail** — positioned by
+   * `itemIndex / items.length`, because proportional text gives the
+   * calculator no claim there — where the native scrollbar stays and the rail
+   * only peeks and jumps. With `affordances={false}` either rail degrades to
+   * passive paint — no drag, peek or click.
    */
   scrubber?: boolean
   /**
@@ -1102,6 +1165,12 @@ export interface TranscriptProps {
    * sessions list instead.
    */
   onOpenSubagent?: (toolUseId: string) => void
+  /**
+   * Replaces the default empty state when the transcript has no items. Pass a
+   * `ReactNode` to show your product's own onboarding instead of WorkerDeck's
+   * generic "`>_` Tell the agent what to do." placeholder.
+   */
+  emptyState?: ReactNode
   className?: string
 }
 
@@ -1126,6 +1195,7 @@ export function Transcript({
   reveal,
   frame,
   onOpenSubagent,
+  emptyState,
   className,
 }: TranscriptProps) {
   const terminal = variant === 'terminal'
@@ -1231,12 +1301,16 @@ export function Transcript({
               </div>
             ) : null
           ) : items.length === 0 && state.status !== 'starting' ? (
-            <SessionEmptyState
-              cwd={state.cwd}
-              hasCommands={!!state.commands?.length}
-              hasSkills={!!state.skills?.some((s) => s.enabled)}
-              canBrowseFiles={canBrowseFiles}
-            />
+            emptyState !== undefined ? (
+              emptyState
+            ) : (
+              <SessionEmptyState
+                cwd={state.cwd}
+                hasCommands={!!state.commands?.length}
+                hasSkills={!!state.skills?.some((s) => s.enabled)}
+                canBrowseFiles={canBrowseFiles}
+              />
+            )
           ) : null}
           {frame && frameTask === undefined && !replaying ? null : (
             <TranscriptRows
@@ -1316,7 +1390,7 @@ export function Transcript({
             className='wd-hold-appear visible pointer-events-none absolute inset-0 overflow-hidden'>
             <div
               className={cn(
-                'mx-auto w-full max-w-[var(--wd-content-max-w,48rem)]',
+                'mx-auto w-full max-w-[var(--wd-transcript-max-width)]',
                 !terminal && 'px-4 py-4',
               )}>
               {terminal ? (

package/src/components/agent/UsageDialog.tsx

@@ -26,6 +26,7 @@ export interface UsageDialogProps {
   updatedAt?: number
   open: boolean
   onOpenChange: (open: boolean) => void
+  className?: string
 }
 
 /**
@@ -40,11 +41,12 @@ export function UsageDialog({
   updatedAt,
   open,
   onOpenChange,
+  className,
 }: UsageDialogProps) {
   const now = useMinuteClock(open)
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent>
+      <DialogContent className={className}>
         <DialogHeader
           title='Usage'
           description={engine === 'claude' ? 'Claude Code' : engine}

package/src/components/agent/scrubber-marks.ts

@@ -0,0 +1,277 @@
+import type { TranscriptItem } from '@workerdeck/react'
+import { formatCost, formatDuration, toolInputPreview } from '../../lib/format.ts'
+import { parentOf } from '../terminal/blocks.ts'
+
+/**
+ * The scrubber's mark model, shared between the two rails.
+ *
+ * The terminal scrubber (`terminal/scrubber.tsx`) positions marks in **pixel
+ * space** — the virtualizer's row offsets, honest because the height calculator
+ * feeds `estimateSize`. The cards variant has no such claim (proportional text,
+ * variable row heights), so its rail (`agent/Scrubber.tsx`) positions marks in
+ * **index space**: `itemIndex / items.length` of the rail. Less precise, but it
+ * still answers the reader's questions — where did I type, where did it fail,
+ * where is the approval waiting.
+ *
+ * What is shared here is the *classification*: which items earn a mark, which
+ * lane a mark lives in, and who wins the colour when marks merge. The walk in
+ * {@link buildMarks} mirrors `buildClusters`'s first half (the segment
+ * machinery, sub-agent detection, bookmark/recap injection) minus everything
+ * that needs a row model. One deliberate divergence: the terminal marks a
+ * failed tool call only when it is its row's *outcome* (a fold's last member),
+ * because that is what its transcript reddens; cards folds nothing
+ * (`terminalBlocks` with `fold=false`), every failed top-level call reddens its
+ * own card, so every one marks — the same "the rail marks what the transcript
+ * reddens" rule, read against a surface with no folds.
+ */
+
+export type Lane = 'l' | 'r' | 'f'
+export type MarkKind =
+  | 'user'
+  | 'subagent'
+  | 'turn'
+  | 'turnFailed'
+  | 'toolFailed'
+  | 'error'
+  | 'approval'
+  | 'recap'
+  | 'bookmark'
+
+export type Mark = {
+  kind: MarkKind
+  /** The jump anchor (for a turn mark: the paired response). */
+  itemIndex: number
+  /** The `turn_result` behind a right-lane mark — the peek shows its done-line. */
+  turnIndex?: number
+}
+
+/** Members keep their own y: a dense transcript chain-merges a lane into one
+ * tall bar, and the bar answers the pointer by its *nearest member* — a press
+ * or peek at the middle of the bar must not act on the mark that happened to
+ * found the cluster. */
+export type Cluster = {
+  lane: Lane
+  kind: MarkKind
+  y: number
+  h: number
+  marks: { mark: Mark; y: number }[]
+}
+
+/** The member closest to a rail-space y — what a press or peek on a merged
+ * cluster resolves to. */
+export function nearestMember(cluster: Cluster, y: number): Mark | undefined {
+  let best: { mark: Mark; y: number } | undefined
+  for (const member of cluster.marks)
+    if (!best || Math.abs(member.y - y) < Math.abs(best.y - y)) best = member
+  return best?.mark
+}
+
+/** The two lanes are channels, not classes: left is what went *in* (your
+ * prompts, the sub-agents you dispatched), right is what came *out* (each
+ * turn's answer, and everything that went wrong producing one). Full width is
+ * for what is not a channel at all: the waiting approval, a bookmark, the
+ * catch-up seam. See the terminal scrubber for the full argument. */
+export const LANE: Record<MarkKind, Lane> = {
+  user: 'l',
+  subagent: 'l',
+  turn: 'r',
+  turnFailed: 'r',
+  toolFailed: 'r',
+  error: 'r',
+  approval: 'f',
+  recap: 'f',
+  bookmark: 'f',
+}
+
+/** Who wins the colour when marks merge. */
+export const LOUDNESS: Record<MarkKind, number> = {
+  approval: 7,
+  error: 6,
+  turnFailed: 5,
+  toolFailed: 4,
+  user: 3,
+  turn: 2,
+  bookmark: 1,
+  subagent: 1,
+  recap: 0,
+}
+
+export const KIND_NAME: Record<MarkKind, string> = {
+  user: 'you',
+  subagent: 'sub-agent',
+  turn: 'response · turn end',
+  turnFailed: 'turn failed',
+  toolFailed: 'tool failed',
+  error: 'error',
+  approval: 'pending approval',
+  recap: 'catch-up boundary',
+  bookmark: 'bookmark',
+}
+
+/** The floor: an index-proportional mark has no extent to draw, so this is
+ * usually the height too — 2px keeps a tick findable. */
+export const MIN_MARK = 2
+
+export const doneLine = (turn: Extract<TranscriptItem, { kind: 'turn_result' }>): string =>
+  `${turn.isError ? turn.subtype : 'done'} · ${formatDuration(turn.durationMs)} · ${formatCost(turn.totalCostUsd)}`
+
+export function excerpt(item: TranscriptItem): string {
+  switch (item.kind) {
+    case 'user':
+    case 'assistant_text':
+    case 'thinking':
+    case 'notice':
+      return item.text
+    case 'tool_call':
+      return `${item.name}(${toolInputPreview(item.input)})`
+    case 'turn_result':
+      return doneLine(item)
+    case 'file_delivered':
+      return item.path
+    default:
+      return ''
+  }
+}
+
+/** One right-lane mark per segment, emitted when the segment closes — by the
+ * next prompt, by its own turn end, or by running out of items (which is what
+ * a replayed history is made of, since `#backfillHistory` carries no turn
+ * rows). A `turn_result` *decorates* the answer rather than conjuring the
+ * mark, so a live answer with no turn end yet is still on the rail. */
+type Segment = { response?: number; turn?: number; failed?: boolean }
+
+export interface BuildMarksOptions {
+  /** The sub-agent takeover's parent id, when the rail belongs to a frame — it
+   * is what "top level" means here (`undefined` at the conversation's own
+   * level). Inside a frame every narration step is its own mark: the stream
+   * carries no prompts and no `turn_result` for the segment machinery to work
+   * with, and a fifty-step agent run is exactly where a rail earns its keep. */
+  frameParentId?: string
+  /** Bookmarked item indices. Paint only — the store is the client's. */
+  bookmarks?: readonly number[]
+  /** The catch-up boundary's item index, when the recap is spliced in. */
+  recapItemIndex?: number
+}
+
+export function buildMarks(
+  items: readonly TranscriptItem[],
+  { frameParentId, bookmarks = [], recapItemIndex }: BuildMarksOptions = {},
+): Mark[] {
+  const marks: Mark[] = []
+  // Which top-level calls a sub-agent ran inside — by `parentToolUseId`, never
+  // by the spawning call's *name*: `Task` is the SDK's convention (a background
+  // agent arrives as `Agent`), and an id other items demonstrably nest under IS
+  // a sub-agent whatever spawned it.
+  const subagentParents = new Set<string>()
+  for (const item of items) {
+    const parent = parentOf(item)
+    if (parent !== undefined) subagentParents.add(parent)
+  }
+  let segment: Segment = {}
+  const closeSegment = () => {
+    const anchor = segment.response ?? segment.turn
+    if (anchor !== undefined) {
+      marks.push({
+        kind: segment.failed ? 'turnFailed' : 'turn',
+        itemIndex: anchor,
+        turnIndex: segment.turn,
+      })
+    }
+    segment = {}
+  }
+  items.forEach((item, index) => {
+    // The dispatch itself. Deliberately not part of the chain below: a `Task`
+    // whose own result errored earns a red tick in the response lane *and*
+    // this mark in the input lane — one says a sub-agent ran here, the other
+    // says it came back broken.
+    if (item.kind === 'tool_call' && subagentParents.has(item.id)) {
+      marks.push({ kind: 'subagent', itemIndex: index })
+    }
+    // Top-level prompts only, like the answer check below: a sub-agent's brief
+    // is a `user` item too, and it would both paint a "you" mark for something
+    // nobody typed and close the segment mid-turn.
+    if (item.kind === 'user' && parentOf(item) === frameParentId) {
+      closeSegment()
+      marks.push({ kind: 'user', itemIndex: index })
+    } else if (item.kind === 'turn_result') {
+      segment.turn = index
+      segment.failed = item.isError
+      closeSegment()
+    } else if (item.kind === 'notice' && item.level === 'error') {
+      marks.push({ kind: 'error', itemIndex: index })
+    } else if (
+      // Both spellings are needed: an out-of-loop execution failure sets
+      // `status` with no `is_error` block to read, and an engine can flag
+      // `is_error` on a call this reducer has not settled yet. Top level only
+      // — a sub-agent's failed child is represented by the sub-agent mark and
+      // the Task's own red tick, exactly as the terminal rail does.
+      item.kind === 'tool_call' &&
+      parentOf(item) === frameParentId &&
+      (item.status === 'failed' || item.result?.isError === true)
+    ) {
+      marks.push({ kind: 'toolFailed', itemIndex: index })
+    } else if (item.kind === 'assistant_text' && parentOf(item) === frameParentId) {
+      if (frameParentId !== undefined) {
+        marks.push({ kind: 'turn', itemIndex: index })
+        return
+      }
+      segment.response = index
+    }
+  })
+  // A history that ends mid-segment still has an answer in it.
+  closeSegment()
+  for (const index of bookmarks)
+    if (index >= 0 && index < items.length) marks.push({ kind: 'bookmark', itemIndex: index })
+  if (recapItemIndex !== undefined) marks.push({ kind: 'recap', itemIndex: recapItemIndex })
+  return marks
+}
+
+/**
+ * Place marks proportionally — y = `itemIndex / itemCount` of the rail, every
+ * mark one item's share tall (floored at {@link MIN_MARK}) — then merge
+ * adjacent ones per lane, the loudest colour winning. The same merge rule as
+ * the terminal rail; only the position source differs.
+ */
+export function clusterMarks(marks: readonly Mark[], railH: number, itemCount: number): Cluster[] {
+  const count = Math.max(1, itemCount)
+  const h = Math.max(MIN_MARK, Math.round(railH / count))
+  const lanes = new Map<Lane, { mark: Mark; y: number }[]>()
+  for (const mark of marks) {
+    const y = Math.min(Math.max(0, railH - h), Math.round((mark.itemIndex / count) * railH))
+    const lane = LANE[mark.kind]
+    const list = lanes.get(lane) ?? []
+    list.push({ mark, y })
+    lanes.set(lane, list)
+  }
+  const clusters: Cluster[] = []
+  for (const [lane, list] of lanes) {
+    list.sort((a, b) => a.y - b.y)
+    let current: Cluster | null = null
+    for (const { mark, y } of list) {
+      // Merge when the gap is under a pixel; the merged mark grows and takes
+      // the loudest member's colour.
+      if (current && y <= current.y + current.h + 1) {
+        current.h = Math.max(current.h, y + h - current.y)
+        if (LOUDNESS[mark.kind] > LOUDNESS[current.kind]) current.kind = mark.kind
+        current.marks.push({ mark, y })
+      } else {
+        current = { lane, kind: mark.kind, y, h, marks: [{ mark, y }] }
+        clusters.push(current)
+      }
+    }
+  }
+  return clusters
+}
+
+/** The approval is not an item — the prompt renders below the transcript — so
+ * its mark pins at the rail's foot, where the prompt is. Built by hand (no
+ * item to derive a position from), hence `marks: []`. */
+export function approvalCluster(railH: number): Cluster {
+  return {
+    lane: LANE.approval,
+    kind: 'approval',
+    y: Math.max(0, railH - MIN_MARK),
+    h: MIN_MARK,
+    marks: [],
+  }
+}