@adea-ai/ui 0.140.0 → 0.142.0

package/src/components/composites/tool/format-tool-value.ts

@@ -0,0 +1,221 @@
+/**
+ * Turning a tool's input or output into text, safely.
+ *
+ * A tool call's payload is whatever the model sent and whatever the tool
+ * returned: it can be a megabyte of log, an object that refers to itself, a
+ * `BigInt` (which `JSON.stringify` throws on), or a getter that throws. A
+ * transcript component that calls `JSON.stringify` on that and renders the result
+ * is one hostile payload away from a frozen tab or a blank page, so this is a
+ * small serializer of our own rather than a call to the built-in one:
+ *
+ * - **It never throws.** Anything it cannot read becomes a marker string.
+ * - **It stops early.** Output is written into a budget of `maxChars`; the moment
+ *   the budget is spent it stops walking, so the cost is bounded by the budget and
+ *   not by the size of the value.
+ * - **It says when it stopped.** `truncated` is true whenever text was cut, so the
+ *   caller can tell the reader the view is partial instead of passing off a cut
+ *   JSON document as the whole thing.
+ * - **It does not lie about types.** Values JSON cannot carry are written as what
+ *   they are (`12n`, `undefined`, `NaN`) rather than coerced to `null`, which
+ *   would read as the tool having returned null.
+ *
+ * Strings are returned as given, not quoted and not re-parsed: re-serializing a
+ * JSON string would silently round numbers beyond double precision.
+ */
+export type ToolValueText = Readonly<{
+  text: string
+  /** `json` for structured values, `text` for strings and anything that is not JSON. */
+  language: 'json' | 'text'
+  /** True when `text` is only the start of the value. */
+  truncated: boolean
+}>
+
+/** Characters shown per section unless the caller says otherwise. */
+export const TOOL_VALUE_MAX_CHARS = 20_000
+
+/** Nesting deeper than this is written as a marker. */
+const MAX_DEPTH = 12
+
+class BudgetSpent extends Error {}
+
+type Writer = {
+  out: string[]
+  length: number
+  max: number
+}
+
+function write(writer: Writer, chunk: string) {
+  writer.out.push(chunk)
+  writer.length += chunk.length
+  if (writer.length > writer.max) throw new BudgetSpent()
+}
+
+/** A JSON string literal, without stringifying more than the budget could hold. */
+function quote(writer: Writer, value: string): string {
+  const room = Math.max(0, writer.max - writer.length)
+  // Past the budget the result is thrown away, so the tail need not be well formed.
+  return value.length > room + 1
+    ? JSON.stringify(value.slice(0, room + 1)).slice(0, -1)
+    : JSON.stringify(value)
+}
+
+function describeNonJson(value: unknown): string {
+  switch (typeof value) {
+    case 'undefined':
+      return 'undefined'
+    case 'bigint':
+      return `${value}n`
+    case 'symbol':
+      return value.toString()
+    case 'function':
+      return `[Function${value.name ? ` ${value.name}` : ''}]`
+    default:
+      return String(value)
+  }
+}
+
+/** At most `limit` items: each costs at least a character, so more could never be shown. */
+function take<T>(source: Iterable<T>, limit: number): T[] {
+  const taken: T[] = []
+  for (const item of source) {
+    if (taken.length > limit) break
+    taken.push(item)
+  }
+  return taken
+}
+
+function readEntries(value: object, limit: number): [string, unknown][] {
+  const entries: [string, unknown][] = []
+  for (const key of Object.keys(value).slice(0, limit + 1)) {
+    try {
+      entries.push([key, (value as Record<string, unknown>)[key]])
+    } catch {
+      entries.push([key, '[Unreadable]'])
+    }
+  }
+  return entries
+}
+
+function writeValue(writer: Writer, value: unknown, depth: number, ancestors: object[]) {
+  if (value === null) return write(writer, 'null')
+  if (typeof value === 'string') return write(writer, quote(writer, value))
+  if (typeof value === 'number') {
+    return write(writer, Number.isFinite(value) ? JSON.stringify(value) : String(value))
+  }
+  if (typeof value === 'boolean') return write(writer, String(value))
+  if (typeof value !== 'object') {
+    // bigint, undefined, symbol, function: written as what they are, in quotes
+    // only where a bare token would be mistaken for the surrounding structure.
+    const text = describeNonJson(value)
+    return write(
+      writer,
+      typeof value === 'bigint' || typeof value === 'undefined' ? text : quote(writer, text)
+    )
+  }
+
+  if (ancestors.includes(value)) return write(writer, '"[Circular]"')
+
+  let subject: unknown = value
+  if (!Array.isArray(value) && typeof (value as { toJSON?: unknown }).toJSON === 'function') {
+    try {
+      subject = (value as { toJSON: () => unknown }).toJSON()
+    } catch {
+      return write(writer, '"[Unreadable]"')
+    }
+    if (typeof subject !== 'object' || subject === null) {
+      return writeValue(writer, subject, depth, ancestors)
+    }
+  }
+  const node = subject as object
+
+  if (ArrayBuffer.isView(node) || node instanceof ArrayBuffer) {
+    return write(
+      writer,
+      quote(writer, `[${node.constructor.name}: ${node.byteLength.toLocaleString('en')} bytes]`)
+    )
+  }
+
+  let items: unknown[] | undefined
+  let fields: [string, unknown][] | undefined
+  if (Array.isArray(node)) items = node
+  else if (node instanceof Set) items = take(node, writer.max)
+  else if (node instanceof Map) items = take(node, writer.max).map(([key, entry]) => [key, entry])
+  else if (node instanceof Error) {
+    fields = [
+      ['name', node.name],
+      ['message', node.message],
+    ]
+  } else fields = readEntries(node, writer.max)
+
+  if (depth >= MAX_DEPTH) {
+    return write(writer, quote(writer, items ? `[Array(${items.length})]` : '[Object]'))
+  }
+
+  const nested = [...ancestors, value]
+  const indent = '  '.repeat(depth + 1)
+  const closing = '  '.repeat(depth)
+
+  if (items) {
+    if (items.length === 0) return write(writer, '[]')
+    write(writer, '[\n')
+    // Indexed rather than `forEach`, which skips the holes of a sparse array: a
+    // million-slot hole would loop a million times without ever spending the budget.
+    for (let index = 0; index < items.length; index += 1) {
+      write(writer, indent)
+      writeValue(writer, items[index], depth + 1, nested)
+      write(writer, index < items.length - 1 ? ',\n' : '\n')
+    }
+    return write(writer, `${closing}]`)
+  }
+
+  const present = fields ?? []
+  if (present.length === 0) return write(writer, '{}')
+  write(writer, '{\n')
+  present.forEach(([key, entry], index) => {
+    write(writer, `${indent}${quote(writer, key)}: `)
+    writeValue(writer, entry, depth + 1, nested)
+    write(writer, index < present.length - 1 ? ',\n' : '\n')
+  })
+  write(writer, `${closing}}`)
+}
+
+export function formatToolValue(
+  value: unknown,
+  options: { maxChars?: number } = {}
+): ToolValueText {
+  const requested = options.maxChars
+  const max =
+    requested === undefined || Number.isNaN(requested)
+      ? TOOL_VALUE_MAX_CHARS
+      : Math.max(0, Math.floor(requested))
+
+  if (typeof value === 'string') {
+    return {
+      text: value.slice(0, max),
+      language: 'text',
+      truncated: value.length > max,
+    }
+  }
+  if (value === undefined || typeof value === 'symbol' || typeof value === 'function') {
+    return { text: describeNonJson(value).slice(0, max), language: 'text', truncated: false }
+  }
+
+  const writer: Writer = { out: [], length: 0, max }
+  let truncated = false
+  try {
+    writeValue(writer, value, 0, [])
+  } catch (error) {
+    // Anything other than the budget running out is a bug in a getter or a proxy
+    // we could not foresee; the reader still gets what was written so far.
+    truncated = true
+    if (!(error instanceof BudgetSpent) && writer.out.length === 0) {
+      return { text: '[Unreadable]', language: 'text', truncated: false }
+    }
+  }
+  const joined = writer.out.join('')
+  return {
+    text: joined.length > max ? joined.slice(0, max) : joined,
+    language: 'json',
+    truncated: truncated || joined.length > max,
+  }
+}

package/src/components/composites/tool/index.ts

@@ -0,0 +1,2 @@
+export { Tool, TOOL_STATUS_LABELS, type ToolProps, type ToolStatus } from './tool'
+export { formatToolValue, TOOL_VALUE_MAX_CHARS, type ToolValueText } from './format-tool-value'

package/src/components/composites/tool/tool.tsx

@@ -0,0 +1,228 @@
+import { Wrench } from 'lucide-solid'
+import { children as resolveChildren, createMemo, Show, splitProps, type JSX } from 'solid-js'
+import { Badge } from '../../ui/badge'
+import { CodeBlock, type CodeLineMark } from '../../ui/code-block'
+import { TraceDetail, TraceLine, type TraceLineProps, type TraceStatus } from '../../ui/trace'
+import { formatToolValue, TOOL_VALUE_MAX_CHARS } from './format-tool-value'
+
+/**
+ * `TraceLine` reads its children twice: once to decide whether the line can
+ * expand, and once to draw them when it is open. A function child is returned
+ * unevaluated by the first read and run once, when the content mounts, by the
+ * second — so a folded line builds none of its body. Solid's `insert` unwraps
+ * functions; the JSX types simply do not admit them.
+ */
+const deferred = (render: () => JSX.Element) => render as unknown as JSX.Element
+
+/**
+ * Tool.
+ *
+ * One tool call, from what was asked to what came back, as a `TraceLine`: the
+ * tool's name and a short description on the line, and — when there is anything
+ * to show — an input section, an output section and an error underneath. Reach
+ * for `Subagent` when the "tool" is another agent with steps of its own, for a
+ * bare `CodeBlock` when the point is the output itself and not the call that made
+ * it, and for a confirmation (passed as `children`) when the reader has to decide
+ * something about the call.
+ *
+ * ## Everything is optional, and absence is not a claim
+ *
+ * A call with no `status` shows no mark at all — an event that merely arrived is
+ * not "done". `input`, `output` and `errorText` each render a section only when
+ * the host passed them: no empty "Output" box under a call that is still running,
+ * and no invented "No output" under one that failed. An error with no output is
+ * just the error. A call with nothing to expand is a plain line, not a
+ * disclosure that opens onto nothing.
+ *
+ * Two statuses are words, not only marks, because the glyphs for them are easy to
+ * misread: `awaiting-approval` and `denied` also show a badge. Both are spoken
+ * once (the badge is hidden from assistive technology and the status word is
+ * read in its place). A call awaiting approval opens by default, since it is the
+ * one state in which the reader has something to do. The component never decides
+ * whether an approval is allowed: the controls live in `children`, supplied by
+ * the host, or are absent.
+ *
+ * ## Payloads are untrusted and unbounded
+ *
+ * `input` and `output` are `unknown` — whatever the model sent and the tool
+ * returned. They go through `formatToolValue`, which cannot throw (circular
+ * references, `BigInt`, throwing getters) and stops after `maxChars`; a cut view
+ * says so rather than presenting half a document as the whole. Sections render in
+ * a small `CodeBlock` with a capped height. A string is shown as given; anything
+ * structured is pretty-printed JSON. The sections mount only when the line is
+ * opened, so a transcript of hundreds of calls formats none of them until asked.
+ *
+ * A `Tool` is a line: place it inside a `Trace`.
+ */
+export type ToolStatus =
+  | 'pending'
+  | 'running'
+  | 'success'
+  | 'error'
+  | 'awaiting-approval'
+  | 'denied'
+  | 'cancelled'
+
+/**
+ * The words spoken (and, for the last three, shown) for each status. `denied` is
+ * a decision about the call; `cancelled` is the run being stopped while the call
+ * was in flight. Give a call `cancelled` only when the host knows that call was
+ * stopped: a run ending does not by itself say what became of each call.
+ */
+export const TOOL_STATUS_LABELS: Readonly<Record<ToolStatus, string>> = {
+  pending: 'Pending',
+  running: 'Running',
+  success: 'Completed',
+  error: 'Failed',
+  'awaiting-approval': 'Awaiting approval',
+  denied: 'Denied',
+  cancelled: 'Cancelled',
+}
+
+const TRACE_STATUS: Readonly<Record<ToolStatus, TraceStatus>> = {
+  pending: 'pending',
+  running: 'running',
+  success: 'success',
+  error: 'error',
+  'awaiting-approval': 'pending',
+  denied: 'cancelled',
+  cancelled: 'cancelled',
+}
+
+export type ToolProps = Omit<
+  TraceLineProps,
+  'title' | 'status' | 'statusLabel' | 'href' | 'onSelect' | 'selectHaspopup'
+> & {
+  /** The tool's name, as the host knows it. Rendered as text. */
+  name: string
+  /** What this call is for: a path, a query, a command. */
+  description?: JSX.Element
+  status?: ToolStatus
+  /** What the model asked the tool to do. Any value; omit it to show no section. */
+  input?: unknown
+  /** What the tool returned. Any value; omit it to show no section. */
+  output?: unknown
+  /** The failure, as text. */
+  errorText?: string
+  /** Characters of each section shown before it is cut. Defaults to 20,000. */
+  maxChars?: number
+  /** Extra detail below the sections: an approval, a link to the full output. */
+  children?: JSX.Element
+}
+
+const SECTION_MAX_HEIGHT = '16rem'
+
+function Section(props: {
+  title: string
+  value: unknown
+  maxChars: number
+  complete?: boolean
+  failure?: boolean
+}) {
+  const formatted = createMemo(() => formatToolValue(props.value, { maxChars: props.maxChars }))
+  // Every line is marked as an error rather than recolouring the block, which
+  // keeps the mark in the gutter (a glyph, not colour alone) and the copy exact.
+  const marks = createMemo((): Readonly<Record<number, CodeLineMark>> | undefined => {
+    if (!props.failure) return undefined
+    const lines = formatted().text.split('\n').length
+    return Object.fromEntries(Array.from({ length: lines }, (_, index) => [index + 1, 'error']))
+  })
+  return (
+    <div class="flex min-w-0 flex-col gap-1">
+      <CodeBlock
+        size="sm"
+        title={props.title}
+        language={props.failure ? 'error' : formatted().language}
+        code={formatted().text}
+        lineMarks={marks()}
+        complete={props.complete ?? true}
+        maxHeight={SECTION_MAX_HEIGHT}
+        wrap={formatted().language === 'text'}
+      />
+      <Show when={formatted().truncated}>
+        <p class="m-0 px-1 text-xs text-muted-foreground">
+          Showing the first {props.maxChars.toLocaleString('en')} characters.
+        </p>
+      </Show>
+    </div>
+  )
+}
+
+export function Tool(props: ToolProps) {
+  const [local, rest] = splitProps(props, [
+    'name',
+    'description',
+    'status',
+    'input',
+    'output',
+    'errorText',
+    'maxChars',
+    'icon',
+    'meta',
+    'defaultOpen',
+    'children',
+  ])
+  const maxChars = () => local.maxChars ?? TOOL_VALUE_MAX_CHARS
+  const hasInput = () => local.input !== undefined
+  const hasOutput = () => local.output !== undefined
+  const hasError = () => local.errorText !== undefined && local.errorText !== ''
+  // Resolved once: a host's approval controls are created once and keep their
+  // state and focus however often the line is folded.
+  const extra = resolveChildren(() => local.children)
+  const hasDetail = () => hasInput() || hasOutput() || hasError() || extra.toArray().length > 0
+
+  const detail = () => (
+    <TraceDetail class="flex flex-col gap-2">
+      <Show when={hasInput()}>
+        <Section title="Input" value={local.input} maxChars={maxChars()} />
+      </Show>
+      <Show when={hasOutput()}>
+        <Section
+          title="Output"
+          value={local.output}
+          maxChars={maxChars()}
+          complete={local.status !== 'running'}
+        />
+      </Show>
+      <Show when={hasError()}>
+        <Section title="Error" value={local.errorText} maxChars={maxChars()} failure />
+      </Show>
+      {extra()}
+    </TraceDetail>
+  )
+
+  // Words as well as marks for the states whose glyph is easy to misread. The
+  // badge is hidden from assistive technology: the status word is already spoken.
+  const wordBadge = () =>
+    local.status === 'awaiting-approval' ||
+    local.status === 'denied' ||
+    local.status === 'cancelled' ? (
+      <span class="flex items-center gap-2">
+        <Badge
+          aria-hidden="true"
+          size="sm"
+          variant={local.status === 'awaiting-approval' ? 'warning' : 'outline'}
+        >
+          {TOOL_STATUS_LABELS[local.status]}
+        </Badge>
+        {local.meta}
+      </span>
+    ) : (
+      local.meta
+    )
+
+  return (
+    <TraceLine
+      icon={local.icon ?? <Wrench />}
+      title={local.name}
+      description={local.description}
+      status={local.status ? TRACE_STATUS[local.status] : undefined}
+      statusLabel={local.status ? TOOL_STATUS_LABELS[local.status] : undefined}
+      meta={wordBadge()}
+      defaultOpen={local.defaultOpen ?? local.status === 'awaiting-approval'}
+      {...rest}
+    >
+      {hasDetail() ? deferred(detail) : undefined}
+    </TraceLine>
+  )
+}

package/src/components/conversation/conversation-surface.tsx

@@ -4,6 +4,7 @@ import { Show, splitProps } from 'solid-js'
 import { cn } from '#lib/utils'
 import { Button } from '../ui/button/button'
 import { createScrollFollow } from './scroll-follow'
+import type { ScrollFollowHold } from './scroll-follow'
 
 /**
  * ConversationSurface.
@@ -44,6 +45,12 @@ export type ConversationSurfaceProps = ComponentProps<'div'> & {
    * frame around the surface is `ConversationPane`'s job.
    */
   gutter?: boolean
+  /**
+   * Receives the surface's `hold`, once, when it is created. A host that moves content
+   * under a reader who is following (a history load that lands after the conversation
+   * changed) opens a hold around it, so the move is not read as the reader scrolling away.
+   */
+  onFollowHold?: (hold: ScrollFollowHold) => void
 }
 
 export function ConversationSurface(props: ConversationSurfaceProps) {
@@ -57,6 +64,7 @@ export function ConversationSurface(props: ConversationSurfaceProps) {
     'empty',
     'header',
     'gutter',
+    'onFollowHold',
     'children',
     'onScroll',
     'ref',
@@ -72,6 +80,7 @@ export function ConversationSurface(props: ConversationSurfaceProps) {
     initialPosition: () => local.initialReadingPosition,
     onPositionChange: (position) => local.onReadingPositionChange?.(position),
   })
+  local.onFollowHold?.(follow.hold)
   const onScroll: JSX.EventHandlerUnion<HTMLDivElement, Event> = (event) => {
     follow.onScroll()
     const handler = local.onScroll

package/src/components/conversation/scroll-follow-core.ts

@@ -169,6 +169,37 @@ export function resolveUserScrollStick(args: {
   return stick
 }
 
+/** What the reader did to the scroller, as far as telling a scroll-up from anything else. */
+export type ReaderInput =
+  | { kind: 'wheel'; deltaY: number }
+  | { kind: 'key'; key: string; shiftKey: boolean }
+  | { kind: 'touchmove' }
+  | { kind: 'pointerdown'; onScroller: boolean }
+
+const SCROLL_UP_KEYS = new Set(['ArrowUp', 'PageUp', 'Home'])
+
+/**
+ * Is this the reader moving the view up, right now?
+ *
+ * A held position (see `createScrollFollow().hold`) is the caller's until the reader takes it,
+ * and only an input that can scroll the view up takes it: a wheel notch up, an up key, a
+ * touch drag, or a press on the scroller itself (its scrollbar or gutter). A click or a
+ * selection inside the content, a letter, a wheel notch down or a down key do not move the
+ * view away from the end, so they leave it where it is.
+ */
+export function isScrollUpIntent(input: ReaderInput): boolean {
+  switch (input.kind) {
+    case 'wheel':
+      return input.deltaY < 0
+    case 'key':
+      return SCROLL_UP_KEYS.has(input.key) || (input.key === ' ' && input.shiftKey)
+    case 'touchmove':
+      return true
+    case 'pointerdown':
+      return input.onScroller
+  }
+}
+
 /** Result of an automatic (RO / append) pin evaluation. */
 export interface AutoPinResult {
   /** Whether to write `el.scrollTop = target` now. */

package/src/components/conversation/scroll-follow.ts

@@ -16,11 +16,16 @@
 import { createEffect, createSignal, onCleanup, untrack } from 'solid-js'
 import type { ConversationReadingPosition } from './conversation-surface'
 import {
+  atBottomEpsilon,
   bottomTarget,
   computeAtBottom,
+  distanceFromBottom,
   evaluateAutoPin,
+  isScrollUpIntent,
   isSelfScroll,
   resolveUserScrollStick,
+  SELF_SCROLL_EPSILON,
+  type ReaderInput,
 } from './scroll-follow-core'
 
 const geometry = (element: HTMLDivElement) => ({
@@ -30,6 +35,9 @@ const geometry = (element: HTMLDivElement) => ({
 })
 const noop = () => {}
 
+/** Opens a hold on the follow position (see `createScrollFollow`); the function it returns closes it. */
+export type ScrollFollowHold = () => () => void
+
 /** Internal plain-scroller binding; host-owned restoration can disable follow. */
 export function createScrollFollow(options: {
   enabled: () => boolean
@@ -49,6 +57,26 @@ export function createScrollFollow(options: {
   let pendingRestore: { frame: number; fromTop: number; target: number } | undefined
   let pendingRestoreUserIntent = false
   let removeRestoreIntentListeners = noop
+  // A hold is the caller saying it is positioning the view (see `hold`): while one is
+  // open and the reader was following, the content's moves are not read as the reader's.
+  let holds = 0
+  let holdFollowing = false
+  let holdIntent = false
+  let holdTop = -1
+  // Bumped on every identity change, so a hold opened for the previous conversation can
+  // neither pin the next one nor close over its state.
+  let holdGeneration = 0
+  const holding = () => holds > 0 && holdFollowing && !holdIntent
+  // Is the view still where the hold left it? The content can move the offset only by
+  // clamping it to the end it has now; anything else moved it from outside (a reveal, a
+  // search jump), and that is the caller's to keep, so the hold gives way.
+  const holdsPosition = (element: HTMLDivElement) => {
+    if (!holding()) return false
+    const maxTop = Math.max(0, element.scrollHeight - element.clientHeight)
+    if (Math.abs(element.scrollTop - Math.min(holdTop, maxTop)) <= SELF_SCROLL_EPSILON) return true
+    holdIntent = true
+    return false
+  }
   const reportPosition = () => {
     if (scroller)
       untrack(() =>
@@ -68,8 +96,24 @@ export function createScrollFollow(options: {
     lastWriteClientHeight = element.clientHeight
     previousTop = element.scrollTop
   }
+  const pinHeld = (element: HTMLDivElement) => {
+    const geom = geometry(element)
+    stick = true
+    if (distanceFromBottom(geom) > atBottomEpsilon()) writePin(element, bottomTarget(geom))
+    // An end the engine already clamped to is accepted as it stands, and is the reference
+    // from here on: the write before it is further down than the content now reaches.
+    else {
+      lastWriteTop = element.scrollTop
+      lastWriteClientHeight = element.clientHeight
+      previousTop = element.scrollTop
+    }
+    holdTop = element.scrollTop
+    setAtBottom(computeAtBottom(geometry(element), options.threshold()))
+    reportPosition()
+  }
   const pinAuto = () => {
     if (!scroller || !options.enabled() || pendingRestore) return
+    if (holdsPosition(scroller)) return pinHeld(scroller)
     const geom = geometry(scroller)
     const result = evaluateAutoPin({
       stick,
@@ -112,6 +156,7 @@ export function createScrollFollow(options: {
       reportPosition()
       return
     }
+    if (holdsPosition(scroller)) return pinHeld(scroller)
     const geom = geometry(scroller)
     setAtBottom(computeAtBottom(geom, options.threshold()))
     if (!isSelfScroll(geom.scrollTop, lastWriteTop)) {
@@ -145,6 +190,46 @@ export function createScrollFollow(options: {
     scroller.focus({ preventScroll: true })
   }
 
+  // Open while the caller moves content under a reader who is following, so a clamp or an
+  // insert it causes is not mistaken for the reader leaving the end. It gives way to the
+  // reader's own scroll-up (`isScrollUpIntent`) and to anything else that moves the view
+  // from outside (a reveal, a search jump); closing it puts a reader who is still following
+  // back at the end. A change of conversation invalidates it, so the next conversation's
+  // saved position is its own. A reveal or search jump outside a hold is never affected.
+  const hold = () => {
+    if (holds === 0) {
+      holdFollowing = options.enabled() && stick && scroller !== undefined
+      holdIntent = false
+      holdTop = scroller ? scroller.scrollTop : -1
+    }
+    holds += 1
+    const generation = holdGeneration
+    let open = true
+    return () => {
+      if (!open || generation !== holdGeneration) return
+      open = false
+      // Asked while this hold still counts: `holdsPosition` is false once none is open.
+      const last = holds === 1
+      const resume = last && scroller !== undefined && holdsPosition(scroller)
+      holds -= 1
+      if (!last) return
+      holdFollowing = false
+      holdIntent = false
+      if (resume && scroller && options.enabled() && !pendingRestore) pinHeld(scroller)
+    }
+  }
+  const noteHoldInput = (event: Event) => {
+    if (holds === 0 || holdIntent) return
+    let input: ReaderInput | undefined
+    if (event instanceof WheelEvent) input = { kind: 'wheel', deltaY: event.deltaY }
+    else if (event instanceof KeyboardEvent)
+      input = { kind: 'key', key: event.key, shiftKey: event.shiftKey }
+    else if (event.type === 'touchmove') input = { kind: 'touchmove' }
+    else if (event.type === 'pointerdown')
+      input = { kind: 'pointerdown', onScroller: event.target === scroller }
+    if (input && isScrollUpIntent(input)) holdIntent = true
+  }
+
   createEffect(() => {
     options.resetKey()
     const enabled = options.enabled()
@@ -165,6 +250,10 @@ export function createScrollFollow(options: {
       observer?.disconnect()
     })
     stick = true
+    holdGeneration += 1
+    holds = 0
+    holdFollowing = false
+    holdIntent = false
     lastWriteTop = -1
     lastWriteClientHeight = -1
     previousTop = -1
@@ -248,8 +337,11 @@ export function createScrollFollow(options: {
     atBottom,
     onScroll,
     jump,
+    hold,
     bindScroller: (element: HTMLDivElement) => {
       scroller = element
+      for (const type of ['wheel', 'touchmove', 'pointerdown', 'keydown'])
+        element.addEventListener(type, noteHoldInput, { passive: true })
     },
     bindContent: (element: HTMLDivElement) => {
       content = element