@workerdeck/ui 0.13.0 → 0.16.0

package/src/components/agent/use-path-links.ts

@@ -0,0 +1,147 @@
+import { useEffect, type RefObject } from 'react'
+
+/**
+ * Cmd/Ctrl+click a file path in the transcript to open it.
+ *
+ * The agent names files constantly — in prose, in tables, in tool arguments —
+ * and every one of them is a place the reader wants to go. They already *look*
+ * like links (inline code renders in the accent), so the affordance is half
+ * promised before anything is wired: this makes it true.
+ *
+ * **Detection is deliberately conservative**, because the cost is asymmetric. A
+ * missed path is a path you select and open yourself; a false positive is a
+ * word that lights up under the modifier and then does nothing, which teaches
+ * the reader not to trust any of them. So:
+ *
+ * - A trailing `/` means a directory. Directories are not openable in a text
+ *   editor, and offering it is worse than staying quiet.
+ * - Outside a `<code>` element the match must be *most* of what the element
+ *   says, or a paragraph mentioning `src/index.ts` in passing would underline
+ *   whole sentences.
+ * - A bare filename (`worker.mjs`) is only a path **inside code**, and only
+ *   with an extension. `18 B` and `Type` are table cells, not files.
+ *
+ * The modifier is the editor's own: hold it and what would open lights up
+ * (`wd-path-link`), which is the only honest way to show which of the blue
+ * things on screen are actually reachable.
+ */
+export type PathHit = { path: string; line?: number }
+
+/** Marks the element under the pointer while the modifier is held. */
+const LINKISH = 'wd-path-link'
+
+/** Absolute, or relative with at least one separator. `:12` is a line number. */
+const PATH_RE = /^(\/[^\s:'"`()[\]{}]+|[\w.@~-]+(?:\/[\w.@~-]+)+)(?::(\d+))?$/
+/** A bare filename — only trusted inside a code element. */
+const FILE_RE = /^([\w.@-]+\.[A-Za-z0-9]{1,10})(?::(\d+))?$/
+
+/** How much of an element's text the match must cover, outside code. */
+const COVERAGE = 0.6
+
+export function matchPath(text: string, inCode: boolean): PathHit | undefined {
+  const trimmed = text.trim()
+  if (!trimmed || trimmed.endsWith('/')) return undefined
+  const hit = PATH_RE.exec(trimmed) ?? (inCode ? FILE_RE.exec(trimmed) : null)
+  if (!hit) return undefined
+  return { path: hit[1]!, line: hit[2] ? Number(hit[2]) : undefined }
+}
+
+/** The path a click on this element means, if any. */
+function hitFor(element: HTMLElement | undefined): PathHit | undefined {
+  if (!element) return undefined
+  const inCode = element.closest('code') !== null
+  const text = element.textContent ?? ''
+  const hit = matchPath(text, inCode)
+  if (!hit) return undefined
+  if (!inCode && hit.path.length < text.trim().length * COVERAGE) return undefined
+  return hit
+}
+
+export function usePathLinks({
+  container,
+  onOpen,
+  enabled = true,
+  ignore,
+}: {
+  /** The subtree to listen in — normally the panel. */
+  container: RefObject<HTMLElement | null>
+  onOpen: (hit: PathHit) => void
+  /** Off when there is no host filesystem to open from: a link that cannot
+   * resolve is worse than plain text. */
+  enabled?: boolean
+  /**
+   * A selector for subtrees to leave alone. Anything with its own meaning for
+   * the modifier needs this — a code editor's Cmd+click is go-to-definition,
+   * and every identifier in it would otherwise match as a filename.
+   */
+  ignore?: string
+}) {
+  useEffect(() => {
+    const root = container.current
+    if (!root || !enabled) return
+    const excluded = (element: HTMLElement | undefined) =>
+      ignore !== undefined && element?.closest(ignore) !== null && element !== undefined
+
+    let marked: HTMLElement | undefined
+    const unmark = () => {
+      marked?.classList.remove(LINKISH)
+      marked = undefined
+    }
+
+    const onClick = (event: MouseEvent) => {
+      if (!event.metaKey && !event.ctrlKey) return
+      const target = event.target instanceof HTMLElement ? event.target : undefined
+      if (excluded(target)) return
+      const hit = hitFor(target)
+      if (!hit) return
+      // Capture phase and stopped here: the row underneath is usually pressable
+      // (a tool call expands), and opening a file is not expanding it.
+      event.preventDefault()
+      event.stopPropagation()
+      unmark()
+      onOpen(hit)
+    }
+
+    const onMove = (event: MouseEvent) => {
+      if (!event.metaKey && !event.ctrlKey) return unmark()
+      const element = event.target instanceof HTMLElement ? event.target : undefined
+      if (element === marked) return
+      unmark()
+      if (!element || excluded(element) || !hitFor(element)) return
+      marked = element
+      element.classList.add(LINKISH)
+    }
+
+    // Releasing the modifier has to clear it: an underline that outlives the key
+    // promises a click that will not work.
+    const onKey = (event: KeyboardEvent) => {
+      if (!event.metaKey && !event.ctrlKey) unmark()
+    }
+
+    root.addEventListener('click', onClick, true)
+    root.addEventListener('mousemove', onMove)
+    document.addEventListener('keydown', onKey)
+    document.addEventListener('keyup', onKey)
+    window.addEventListener('blur', unmark)
+    return () => {
+      unmark()
+      root.removeEventListener('click', onClick, true)
+      root.removeEventListener('mousemove', onMove)
+      document.removeEventListener('keydown', onKey)
+      document.removeEventListener('keyup', onKey)
+      window.removeEventListener('blur', unmark)
+    }
+  }, [container, onOpen, enabled, ignore])
+}
+
+/**
+ * A transcript path against the session's cwd.
+ *
+ * Absolute wins outright. Everything else is relative to where the agent is
+ * working, which is the only root that makes `worker.mjs` mean anything.
+ */
+export function resolveAgainstCwd(path: string, cwd: string | undefined): string {
+  if (path.startsWith('/')) return path
+  if (!cwd) return path
+  return `${cwd.replace(/\/$/, '')}/${path.replace(/^\.\//, '')}`
+}

package/src/components/agent/use-transcript-jumps.ts

@@ -0,0 +1,190 @@
+/**
+ * The jump: aim at a virtual row, land exactly. Every jump on the transcript
+ * surface — the catch-up strip's, and each of the scrubber's marks — comes
+ * through here, along with the re-pin the catch-up strip's dismiss uses.
+ * **Instant**, like everything else that moves the scroll position: VS Code's
+ * editor jumps when you click its scrollbar and so does this.
+ *
+ * The aim loop survives from before the height calculator, with its job
+ * changed twice. It used to be the mechanism: offsets over unmeasured spans
+ * were sums of flat estimates (~3300px off over 600 rows), and the loop
+ * walked them in up to six passes, each pass better than the last because
+ * the rows it crossed had measured. With `estimateSize` computed the first
+ * aim lands within a line or two; with the travel now instant there is also
+ * no in-flight animation suppressing the virtualizer's own adjustments — the
+ * condition that made a *single* smooth `scrollToIndex` unable to
+ * self-correct at all. What is left is convergence insurance for the two
+ * things the calculator cannot know: the recap row's estimated constant, and
+ * flagged content (CJK, compressed tables). It is cheap now — each pass is a
+ * jump, not a journey, so a pass that was already on target costs nothing and
+ * the check exits after one.
+ */
+import { useEffect, useRef, type RefObject } from 'react'
+import type { Virtualizer } from '@tanstack/react-virtual'
+import type { useStickToBottomContext } from 'use-stick-to-bottom'
+import type { HeightEpoch } from '../terminal/height.ts'
+import { gapBefore, type TranscriptRow } from './transcript-rows.ts'
+
+/** How many times a jump re-checks its landing, and how long it waits before
+ * doing so. Both are much smaller than the smooth era's 6 × 300ms: a pass is
+ * now a jump rather than a journey, so the only thing being waited on is a
+ * layout pass in which the crossed rows measure. */
+const AIM_PASSES = 4
+const AIM_SETTLE_MS = 50
+
+export function useTranscriptJumps(options: {
+  rows: TranscriptRow[]
+  terminal: boolean
+  stickyPrompt: boolean
+  epoch: HeightEpoch | null
+  promptRows: readonly number[]
+  scrollElement: HTMLElement | null
+  rowsRef: RefObject<HTMLDivElement | null>
+  virtualizer: Virtualizer<HTMLElement, HTMLDivElement>
+  stick: ReturnType<typeof useStickToBottomContext>
+  jumpToRecapRef?: RefObject<(() => void) | null>
+  repinRef?: RefObject<(() => void) | null>
+}): (rowIndex: number, align?: 'start' | 'center') => void {
+  const {
+    rows,
+    terminal,
+    stickyPrompt,
+    epoch,
+    promptRows,
+    scrollElement,
+    rowsRef,
+    virtualizer,
+    stick,
+    jumpToRecapRef,
+    repinRef,
+  } = options
+
+  // The pending re-aim lives in a ref, and this is the whole reason: the
+  // closure is rebuilt every render to keep `rows` fresh, so anything held in
+  // its scope is torn down every render too — and a jump in flight re-renders
+  // constantly, because that is what rows mounting *is*. A timer in the
+  // closure would be cancelled by the very work it is waiting for.
+  const aimTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  useEffect(() => () => clearTimeout(aimTimer.current), [])
+
+  // `align` is the caller's, and every caller on this surface now asks for
+  // `'start'`: a jump target is a place to *start reading* — what you came for
+  // runs downward from it — so its line lands at exactly the top edge with the
+  // screen below it to read into, and centring wastes half the viewport on what
+  // you have already read. The recap boundary was the one exception, argued as
+  // "a seam, and seeing a little of what came before is how you place it"; in
+  // practice the seam is a starting line too. `'center'` survives as the
+  // default because it is what `scrollIntoView` means and a future caller may
+  // want it, not because anything here uses it.
+  //
+  // The two aligns aim differently, and the split is load-bearing. `'start'`
+  // computes the target offset itself — never `scrollIntoView` — because a
+  // prompt row is `position: sticky` and scrollIntoView aims at the element's
+  // *current* rect, which for a stuck row is wherever it is pinned: the jump
+  // would be a no-op on the very rows the scrubber's left lane points at. The
+  // target is the row's virtual start plus the rows container's own offset in
+  // the scroll content, plus the row's gap padding (the blank line is padding
+  // *on* the row, and the reader asked for the line, not its air) — which also
+  // lands exactly on the sticky engage threshold, so the row arrives pinned.
+  // Re-aims recompute it while rows crossed by the travel measure.
+  //
+  // `stopScroll()` first, because the pin spring is the other `scrollTop`
+  // writer and this is the library's own switch for "the user is leaving the
+  // bottom".
+  const jumpToRow = (rowIndex: number, align: 'start' | 'center' = 'center') => {
+    if (rowIndex < 0 || rowIndex >= rows.length || !scrollElement) return
+    stick.stopScroll()
+    clearTimeout(aimTimer.current)
+    if (align === 'start') {
+      // The gap padding a row's *line* sits below — the target is the line,
+      // not its air.
+      const linePad = (index: number) =>
+        terminal && epoch && index > 0 && gapBefore(rows, index) ? epoch.line : 0
+      const target = () => {
+        const start = virtualizer.measurementsCache[rowIndex]?.start ?? 0
+        const spacer = rowsRef.current
+          ? rowsRef.current.getBoundingClientRect().top -
+            scrollElement.getBoundingClientRect().top +
+            scrollElement.scrollTop
+          : 0
+        let top = start + spacer + linePad(rowIndex)
+        // A non-prompt target lands *below* the pinned prompt, not under it:
+        // at this offset the turn's own prompt head is stuck at the top, and a
+        // jump that puts the line at zero puts it exactly behind that band —
+        // the scrubber's answer marks would all land their first line hidden.
+        // The head is one line tall. A jump *to* a prompt keeps zero: it
+        // becomes the pinned row itself.
+        if (terminal && stickyPrompt && epoch && !promptRows.includes(rowIndex)) {
+          const pinned = promptRows.some((index) => index < rowIndex)
+          if (pinned) top -= epoch.line
+        }
+        return Math.round(top)
+      }
+      const aim = (attempt: number) => {
+        const top = target()
+        scrollElement.scrollTo({ top, behavior: 'instant' })
+        if (attempt >= AIM_PASSES) return
+        aimTimer.current = setTimeout(() => {
+          // Off target: a row that measured under the jump moved it. (It can no
+          // longer be "still travelling" — that was the smooth era.)
+          if (Math.abs(scrollElement.scrollTop - target()) > 1) aim(attempt + 1)
+        }, AIM_SETTLE_MS)
+      }
+      aim(0)
+      return
+    }
+    const aim = (attempt: number) => {
+      const row = scrollElement.querySelector(`[data-index="${rowIndex}"]`)
+      if (row) {
+        row.scrollIntoView({ behavior: 'instant', block: align })
+        return
+      }
+      if (attempt >= AIM_PASSES) return
+      virtualizer.scrollToIndex(rowIndex, { align, behavior: 'auto' })
+      // A frame or two, not a journey: the aim is only better once the rows
+      // crossed have mounted *and* been measured, and that is a layout pass
+      // away — but with the jump instant there is nothing else to wait for.
+      aimTimer.current = setTimeout(() => aim(attempt + 1), AIM_SETTLE_MS)
+    }
+    aim(0)
+  }
+
+  useEffect(() => {
+    if (!jumpToRecapRef) return
+    jumpToRecapRef.current = () => {
+      // `'start'`, like the scrubber's marks. The seam is a place to *start
+      // reading* — everything you missed runs downward from it — so it belongs
+      // at the top edge with the screen below it to read into. Centring it
+      // spent half the viewport on rows you had already read.
+      jumpToRow(
+        rows.findIndex((row) => row.key === 'recap'),
+        'start',
+      )
+    }
+    return () => {
+      jumpToRecapRef.current = null
+    }
+  })
+
+  // Re-pin to the bottom. Published the same way as the jump above, and for the
+  // same reason: only the scroll context can do it, and it lives in here.
+  //
+  // `'instant'`, never the follow spring. The spring exists to keep up with a
+  // stream a few pixels at a time; from a reader who had scrolled a long way up
+  // it would animate the whole way down, which is the smooth-scroll-on-switch
+  // complaint this component already carries two guards against. The target is
+  // trustworthy because the bottom is `totalSize`, which the height calculator
+  // makes exact — unlike a mid-list row, which is why `jumpToRow` needs its
+  // aim/re-aim loop and this needs none.
+  useEffect(() => {
+    if (!repinRef) return
+    repinRef.current = () => {
+      void stick.scrollToBottom('instant')
+    }
+    return () => {
+      repinRef.current = null
+    }
+  })
+
+  return jumpToRow
+}

package/src/components/prompt-area/cursor-helpers.ts

@@ -101,6 +101,69 @@ export function createRangeAtOffset(editor: HTMLElement, targetOffset: number):
   return range
 }
 
+/**
+ * Where the caret is on screen, in viewport coordinates.
+ *
+ * A collapsed range usually measures fine, but not when it sits *between* child
+ * nodes of an element — which is exactly where a freshly inserted newline puts
+ * it, because this editor's content is a flat run of text nodes and `<br>`s
+ * directly under the editor element. There `getBoundingClientRect()` is all
+ * zeros, and the obvious fallback (measure `startContainer`'s element) resolves
+ * to the editor itself, whose rect is the viewport box — so it reports the
+ * caret as trivially visible and scrolls nothing.
+ *
+ * So measure the neighbour instead: the child the caret sits before, or failing
+ * that the one it sits after. Selecting a node gives a real rect even for a
+ * `<br>`, which is what the line the caret just moved to consists of.
+ */
+function caretRect(range: Range): DOMRect | null {
+  const direct = range.getBoundingClientRect()
+  if (direct.height > 0) return direct
+
+  const node = range.startContainer
+  if (node.nodeType !== Node.ELEMENT_NODE) return null
+  const children = (node as Element).childNodes
+  const neighbours = [children[range.startOffset], children[range.startOffset - 1]]
+  for (const neighbour of neighbours) {
+    if (!neighbour) continue
+    const probe = document.createRange()
+    probe.selectNode(neighbour)
+    const rect = probe.getBoundingClientRect()
+    if (rect.height > 0) return rect
+  }
+  return null
+}
+
+/**
+ * Keep the caret inside the editor's visible box after a *programmatic* move.
+ *
+ * The editor is its own scroll container once it hits `maxHeight`
+ * (`prompt-area.tsx` sets `overflowY: auto` there). Typing scrolls the caret
+ * into view for free, because that is the browser's own behaviour for a native
+ * edit — but every path that calls `preventDefault()` and rebuilds the DOM
+ * itself (Shift+Enter, list continuation, undo/redo, the bold/italic wrap,
+ * paste) places the caret with a Range instead, and setting a selection does
+ * not scroll anything. The symptom is a prompt that has grown past its cap and
+ * stops following what you are writing: type and it scrolls, press Shift+Enter
+ * and the new line appears below the fold.
+ *
+ * A no-op when the caret is already visible, so it is safe on every call — it
+ * corrects an off-screen caret rather than scrolling to one.
+ */
+export function scrollCaretIntoView(editor: HTMLElement): void {
+  const sel = window.getSelection()
+  if (!sel || sel.rangeCount === 0) return
+  const range = sel.getRangeAt(0)
+  if (!editor.contains(range.startContainer)) return
+
+  const rect = caretRect(range)
+  if (!rect) return
+
+  const box = editor.getBoundingClientRect()
+  if (rect.bottom > box.bottom) editor.scrollTop += rect.bottom - box.bottom
+  else if (rect.top < box.top) editor.scrollTop -= box.top - rect.top
+}
+
 export function setCursorAtOffset(editor: HTMLElement, targetOffset: number): void {
   const sel = window.getSelection()
   if (!sel) return
@@ -112,6 +175,7 @@ export function setCursorAtOffset(editor: HTMLElement, targetOffset: number): vo
     range.collapse(true)
     sel.removeAllRanges()
     sel.addRange(range)
+    scrollCaretIntoView(editor)
     return
   }
 
@@ -121,6 +185,7 @@ export function setCursorAtOffset(editor: HTMLElement, targetOffset: number): vo
   range.collapse(false)
   sel.removeAllRanges()
   sel.addRange(range)
+  scrollCaretIntoView(editor)
 }
 
 export function getTextLengthInRange(range: Range): number {

package/src/components/prompt-area/use-prompt-area.ts

@@ -1307,21 +1307,27 @@ export function usePromptArea({
         return
       }
 
-      // 3. Enter without Shift (skipping IME): continue a list, else submit when
-      // `submitOnEnter` is set, else insert a newline.
+      // 3. Enter without Shift (skipping IME): submit when `submitOnEnter` is
+      // set, else insert a newline — continuing a list if we are in one.
+      //
+      // Under `submitOnEnter`, Enter submits *unconditionally*. It used to try
+      // a list continuation first, which meant that once you had typed a
+      // bullet, the send key silently stopped sending: every Enter added
+      // another empty bullet, and the only way out was to clear the list. Enter
+      // is the send key in a chat composer, and a key that does something else
+      // depending on what the line above happens to start with is not one.
+      // Continuation lives on Shift+Enter (branch 2.8), which is the newline
+      // key here and therefore where "newline, and keep the list going"
+      // belongs. Without `submitOnEnter`, Enter *is* the newline key, so it
+      // keeps the continuation.
       if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
-        const editor = editorRef.current
-        if (editor && tryListContinuation(editor)) {
-          e.preventDefault()
-          return
-        }
+        e.preventDefault()
         if (submitOnEnter) {
-          e.preventDefault()
           onSubmit?.(readSegmentsFromDOM())
           return
         }
-        e.preventDefault()
-        if (editor) insertPlainNewline(editor)
+        const editor = editorRef.current
+        if (editor && !tryListContinuation(editor)) insertPlainNewline(editor)
         return
       }
 

package/src/components/terminal/PermissionPrompt.tsx

@@ -0,0 +1,119 @@
+import { useState } from 'react'
+import type { PermissionRequest } from '@workerdeck/protocol'
+import { toolInputPreview } from '../../lib/format.ts'
+import { TerminalDiff, previewPatch } from './diff.tsx'
+import { Choices, Hint, PromptInput, PromptTitle, Rule } from './prompt.tsx'
+import { Blank, Row } from './row.tsx'
+
+/**
+ * The approval, as the CLI draws it: a rule, what is being asked and about what,
+ * the change itself, a dashed rule, the question, numbered answers, and the keys.
+ *
+ * Two things it does that the card version does not, both taken from the CLI:
+ *
+ * - **It shows the change, not the payload.** For a file edit, `old_string` and
+ *   `new_string` are a diff — so it renders one, rather than the JSON input a
+ *   reader would have to diff in their head. Without line numbers, necessarily:
+ *   the edit has not happened and this client has never read the file (see
+ *   {@link previewPatch}). Everything else falls back to the input.
+ * - **The heading is the engine's own sentence.** `displayName` ("Edit file")
+ *   over `title`, never "wants to use {tool}" composed here — for codex an
+ *   approval is an *escalation after a sandbox refusal*, and the runner has
+ *   already written the sentence that says so.
+ */
+export interface TerminalPermissionPromptProps {
+  request: PermissionRequest
+  onApprove: (requestId: string) => void
+  /** `message` is fed back to the agent, which can then try something else;
+   * `interrupt` also stops the turn. */
+  onDeny: (requestId: string, message?: string, interrupt?: boolean) => void
+}
+
+export function TerminalPermissionPrompt({
+  request,
+  onApprove,
+  onDeny,
+}: TerminalPermissionPromptProps) {
+  const [focused, setFocused] = useState(0)
+  const [denying, setDenying] = useState(false)
+  const [reason, setReason] = useState('')
+
+  const deny = (interrupt: boolean) => {
+    const message = reason.trim()
+    onDeny(request.id, message || undefined, interrupt || undefined)
+    setReason('')
+    setDenying(false)
+  }
+
+  const patch = previewPatch(request.input)
+  const summary = toolInputPreview(request.input)
+  const heading = request.displayName ?? request.title ?? 'Permission needed'
+  // The path is the subject when there is one; otherwise the input preview says
+  // what this is about, which for a Bash approval is the command itself.
+  const subject = patch?.path ?? (summary || undefined)
+
+  // "Deny" opens the reason field rather than acting, because a denial the agent
+  // can learn from is the one worth defaulting to — an empty field still denies.
+  const options = [
+    { key: 'allow', label: 'Yes' },
+    {
+      key: 'deny',
+      label: 'No, and tell the agent what to do differently',
+      detail: denying ? (
+        <PromptInput
+          value={reason}
+          onChange={setReason}
+          onSubmit={() => deny(false)}
+          onCancel={() => setDenying(false)}
+          placeholder='Reason (optional) — the agent reads this and can try something else'
+        />
+      ) : undefined,
+    },
+    { key: 'stop', label: 'No, and stop the turn', danger: true },
+  ]
+
+  return (
+    <div
+      data-slot='permission-prompt'
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.preventDefault()
+          deny(false)
+        }
+      }}>
+      <Rule />
+      <PromptTitle title={heading} subject={subject} />
+      <Blank />
+      {patch ? (
+        <>
+          <TerminalDiff patch={patch} />
+          <Blank />
+          <Rule dashed />
+        </>
+      ) : request.description ? (
+        <>
+          <Row tone='dim'>{request.description}</Row>
+          <Blank />
+        </>
+      ) : null}
+      {request.decisionReason ? <Row tone='faint'>{request.decisionReason}</Row> : null}
+      <Row>
+        {request.title ?? `Do you want to proceed?`}
+      </Row>
+      <Choices
+        label={heading}
+        options={options}
+        focused={focused}
+        onFocus={setFocused}
+        active={!denying}
+        onChoose={(index) => {
+          if (index === 0) onApprove(request.id)
+          else if (index === 1) setDenying(true)
+          else deny(true)
+        }}
+      />
+      <Blank />
+      <Hint>Enter to select · ↑/↓ to navigate · 1–3 to choose · Esc to cancel</Hint>
+    </div>
+  )
+}