@lovett/ui 0.0.11 → 0.2.0

package/src/thread/thread.tsx

@@ -0,0 +1,718 @@
+/**
+ * Thread — the styled default skin over `useThread`.
+ *
+ * ADR-147 T3. This is ONE presentation of the hook, not the only one: a
+ * consumer that wants different chrome calls `useThread` and draws its own.
+ * Everything below the hook boundary is layout and tokens.
+ *
+ * DELIBERATELY NOT A DIALOG. The reference was a modal, and the port
+ * correction it needed was "never `if (!open) return null`, because that kills
+ * the open/close animation". The cleanest way to not regress that rule is to
+ * not own the dialog at all: the thread is a panel, its host decides whether
+ * it lives in a drawer, a modal or a column. Inside this file the same rule is
+ * applied where it does bite — the reply composer and the reaction picker stay
+ * mounted and are driven by `data-open`.
+ *
+ * ONE CARD PER ROOT THREAD. This is the structural decision the rest of the
+ * layout follows from. The first build gave every comment its own card-like
+ * object, which made a conversation read as a stack of unrelated notices and
+ * made depth expensive — a reply had to earn a whole new box. Now a root
+ * comment AND its entire descendant tree share one card, sibling roots are
+ * separate cards, and depth inside a card costs an indent and a hairline.
+ * A thread is the unit people actually think in; a comment is not.
+ *
+ * SURFACES follow CLAUDE.md's data-display recipe, and the recipe is what
+ * forces the panel to step DOWN rather than the cards to step up. The panel is
+ * the frame (`data-framed` → `--surface-frame`: 247 light / 21 dark) and each
+ * thread card is `--surface-card` (255 / 27) with a border and a shadow — the
+ * same board-column-to-card relationship the rest of the system uses, opaque in
+ * both directions. A card tinted onto the panel with `--surface-overlay*` is
+ * the washed-out defect; grey STRUCTURE inside the card (the date rule, the
+ * depth rails, the composer border) is required and is not a candidate for
+ * "cleanup".
+ *
+ * RADII are computed, not eyeballed (interface standards §1). The panel is
+ * `--radius-xl` (20) with `--space-3` (12) of padding, so a thread card is
+ * 20 − 12 = 8 = `--radius-sm`. The card then re-declares the same property one
+ * rung down for its own contents. `.ds-thread` in styles.css owns both values.
+ */
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import { Fragment, useCallback, useEffect, useRef, useState } from 'react'
+import { MessageSquare } from 'lucide-react'
+import { Avatar, AvatarGroup, asAvatarTint } from '../avatar'
+import Card from '../card'
+import { cn } from '../lib/utils'
+import { CommentItem, type ThreadRenderContext } from './comment'
+import { ThreadComposer } from './composer'
+import {
+  RichThreadComposer,
+  type RichComposerAttachmentProps,
+  type RichThreadComposerProps,
+} from './rich-composer'
+import { DEFAULT_INDENT_CLAMP_DEPTH } from './rail'
+import { useThread, type UseThreadOptions } from './use-thread'
+import type { MentionTarget } from './comment-body'
+import type {
+  CommentDeliveryState,
+  CommentNode,
+  MentionSuggestionItem,
+  ThreadAttachment,
+  ThreadAuthor,
+  ThreadReactionKey,
+  ThreadSort,
+  ThreadVote,
+} from './types'
+
+/** React accepts CSS custom properties in `style`; the DOM typings do not declare them. */
+type StyleWithVars = CSSProperties & Record<`--${string}`, string>
+
+// `--thread-inner-radius` is NOT set here. It is declared once by `.ds-thread`
+// in styles.css, which the `<section>` below always carries — duplicating it
+// inline is exactly how the declared value and the effective one drift apart.
+// Every consumer still reads it as `var(--thread-inner-radius, var(--radius-sm))`,
+// so a host that forgot the stylesheet degrades to the right corner anyway.
+const PANEL_STYLE: StyleWithVars = {
+  borderRadius: 'var(--radius-xl)',
+  padding: 'var(--space-3)',
+}
+
+/**
+ * A thread card is the one place the concentric chain steps down a rung, and
+ * it does it by re-declaring the property its descendants already read rather
+ * than by introducing a second one. Everything inside — the reply composer,
+ * an attachment thumbnail, the failure notice — keeps asking exactly one
+ * question and gets the answer that is right for where it is mounted.
+ */
+const CARD_STYLE: StyleWithVars = {
+  borderRadius: 'var(--thread-inner-radius, var(--radius-sm))',
+  '--thread-inner-radius': 'var(--thread-card-inner-radius, var(--radius-xs))',
+  // No block-start padding: the first comment's own `--thread-row-gap` supplies
+  // it, so the card reads as an even `--space-3` inset all round while every
+  // comment box in the tree — first or not — keeps an identical top edge. That
+  // identity is what lets one derived `--thread-avatar-center` place every
+  // elbow in the tree.
+  padding: '0 var(--space-3) var(--space-3)',
+}
+
+const SORTS: readonly { readonly id: ThreadSort; readonly label: string }[] = [
+  { id: 'top', label: 'Top' },
+  { id: 'new', label: 'Newest' },
+]
+
+function SortPills({
+  value,
+  onChange,
+}: {
+  value: ThreadSort
+  onChange: (next: ThreadSort) => void
+}) {
+  return (
+    <div
+      // A selected state must step UP to an opaque surface, never be an alpha
+      // tint on a translucent track (CLAUDE.md §2): the track is the recessed
+      // opaque `--surface-inset`, the active pill is `--surface-card` with an
+      // accent border. Two alpha layers composited is how a "raised" pill ends
+      // up rendering darker than the well it sits in.
+      className="inline-flex gap-[var(--space-1)] border p-[var(--space-1)]"
+      role="group"
+      aria-label="Sort comments"
+      style={{
+        borderRadius: 'var(--radius-sm)',
+        borderColor: 'rgb(var(--border))',
+        background: 'rgb(var(--surface-inset))',
+      }}
+    >
+      {SORTS.map((sort) => {
+        const active = sort.id === value
+        return (
+          <button
+            key={sort.id}
+            type="button"
+            aria-pressed={active}
+            onClick={() => {
+              onChange(sort.id)
+            }}
+            className={cn(
+              'inline-flex h-[24px] items-center px-[var(--space-2)] text-[12px] font-semibold',
+              'transition-[background-color,color,border-color,box-shadow] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+              'motion-reduce:transition-none',
+              'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+              active
+                ? 'border border-[rgb(var(--accent))] bg-[rgb(var(--surface-card))] text-[rgb(var(--accent-ink))] [box-shadow:var(--shadow-sm)]'
+                : 'border border-transparent text-[rgb(var(--text-tertiary))] hover:text-[rgb(var(--foreground))]',
+            )}
+            style={{ borderRadius: 'var(--radius-xs)' }}
+          >
+            {sort.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+const DAY = 86_400_000
+
+/** Local midnight for an epoch value — the boundary a person means by "day". */
+function startOfDay(value: number): number {
+  const date = new Date(value)
+  date.setHours(0, 0, 0, 0)
+  return date.getTime()
+}
+
+/**
+ * "Today" / "Yesterday" / a written date. Derived from the INJECTED `now`, so
+ * a frozen clock produces a frozen label and the separators are as assertable
+ * as the timestamps beside them (D16).
+ */
+function dayLabel(value: number, now: number, locale?: string): string {
+  const days = Math.round((startOfDay(now) - startOfDay(value)) / DAY)
+  if (days <= 0) return 'Today'
+  if (days === 1) return 'Yesterday'
+  const date = new Date(value)
+  const sameYear = date.getFullYear() === new Date(now).getFullYear()
+  return date.toLocaleDateString(locale, {
+    day: 'numeric',
+    month: 'long',
+    ...(sameYear ? {} : { year: 'numeric' }),
+    ...(days < 7 ? { weekday: 'long' } : {}),
+  })
+}
+
+/**
+ * A date separator, sticky to the top of the scroll region.
+ *
+ * Grouping is by RUN, not by bucket: a separator is emitted whenever a root's
+ * day differs from the previous root's. Under `new` that is the obvious
+ * chronological grouping; under `top` a day can legitimately appear more than
+ * once, and showing that honestly is better than either suppressing the
+ * separators or lying about the order by re-bucketing a ranked list into
+ * calendar order.
+ *
+ * It carries the PANEL's surface because a sticky element with no background
+ * smears the cards scrolling under it. `--surface-frame` is the panel in the
+ * `panel` variant; a `bare` host that sits on a different surface overrides it
+ * the same way it overrides the panel's other assumptions.
+ */
+function DateSeparator({ label }: { label: string }) {
+  return (
+    <div
+      className="sticky top-0 z-[1] flex items-center gap-[var(--space-3)]"
+      style={{
+        paddingBlock: 'var(--space-2)',
+        background: 'rgb(var(--surface-frame))',
+      }}
+    >
+      <span className="h-px flex-1" style={{ background: 'rgb(var(--border))' }} />
+      <span
+        className="text-[12px] font-medium"
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      >
+        {label}
+      </span>
+      <span className="h-px flex-1" style={{ background: 'rgb(var(--border))' }} />
+    </div>
+  )
+}
+
+export interface ThreadParticipant {
+  readonly id: string
+  readonly name: string
+  readonly avatarUrl?: string | undefined
+  readonly tint?: string | undefined
+}
+
+export interface ThreadProps extends UseThreadOptions, RichComposerAttachmentProps {
+  readonly onReact?: ((commentId: string, key: ThreadReactionKey) => void) | undefined
+  readonly onVote?: ((commentId: string, next: ThreadVote) => void) | undefined
+  readonly onRetry?: ((commentId: string) => void) | undefined
+  readonly onSelectAuthor?: ((author: ThreadAuthor) => void) | undefined
+  readonly onSelectMention?: ((target: MentionTarget) => void) | undefined
+  readonly onOpenAttachment?: ((attachment: ThreadAttachment) => void) | undefined
+  /**
+   * Resolve one attachment's short-lived URL (ADR-151 D6). The wire carries no
+   * URL — the storage key never leaves the worker — so the renderer asks for
+   * the bytes lazily, after the box is already reserved from the declared
+   * aspect ratio.
+   */
+  readonly resolveAttachmentUrl?: ((attachmentId: string) => Promise<string | null>) | undefined
+  /**
+   * Hide one link preview on one comment (ADR-150 D7). Absent and no card
+   * renders a dismiss control — the affordance follows the wiring rather than
+   * appearing and doing nothing.
+   *
+   * The host owns the optimistic removal and the invalidate-on-error, in the
+   * same pattern as the existing mutations. `canHide` on the row is a rendering
+   * convenience; the server is the gate.
+   */
+  readonly onHideLinkPreview?: ((commentId: string, urlHash: string) => void) | undefined
+  /**
+   * The byline overflow menu. An item whose callback is absent is NOT RENDERED
+   * — never rendered disabled, because a permanently greyed row teaches people
+   * the surface is broken rather than that they lack a permission.
+   *
+   * `onCopyText` is the odd one out by design: the body is already in hand, so
+   * "Copy text" appears whenever there is a body and a clipboard to write to,
+   * performs the write itself, and uses this callback only to report the
+   * outcome — `ok: false` covers a denied permission or an unfocused document,
+   * which a host will usually want to surface as a toast.
+   */
+  readonly onCopyLink?: ((commentId: string) => void) | undefined
+  readonly onCopyText?: ((commentId: string, ok: boolean) => void) | undefined
+  readonly onEdit?: ((commentId: string) => void) | undefined
+  readonly onDelete?: ((commentId: string) => void) | undefined
+  readonly onContinueThread?: ((commentId: string) => void) | undefined
+  /** In flight. Disables the composers and shows "Sending…". */
+  readonly sending?: boolean | undefined
+  /**
+   * Nesting depth past which a level stops ADDING indent. Nesting itself stays
+   * uncapped — this only stops a ~380px task drawer running out of column
+   * around depth 9. Past it the rail is drawn as a stacking hairline border
+   * and collapse moves to the footer control; nothing is hidden and nothing
+   * becomes unreachable. Default 6 (≈144px of indent at `--space-6`).
+   */
+  readonly indentClampDepth?: number | undefined
+  /** Rendered above the sort bar. A title, a resolve control, whatever the host needs. */
+  readonly header?: ReactNode | undefined
+  /** Faces on the thread, shown beside the count. `total` may exceed the list. */
+  readonly participants?: readonly ThreadParticipant[] | undefined
+  readonly participantTotal?: number | undefined
+  /** The current user's avatar, beside the root composer. */
+  readonly composerAvatar?: ReactNode | undefined
+  readonly composerPlaceholder?: string | undefined
+  readonly composerMaxLength?: number | undefined
+  /** Day separators between runs of root threads. */
+  readonly dateSeparators?: boolean | undefined
+  readonly emptyState?: ReactNode | undefined
+  readonly locale?: string | undefined
+  /** `panel` paints the opaque frame the cards sit on; `bare` inherits the host's. */
+  readonly variant?: 'panel' | 'bare' | undefined
+  /**
+   * Draw the pinned ROOT composer. Default true.
+   *
+   * `false` is for a host that pins a composer of its own BELOW the thread and
+   * needs exactly one on screen — the task detail's activity pane, whose
+   * composer stays put across Everything / Comments / Activity, so it cannot
+   * be the one this component owns. Replies are unaffected: they are still
+   * gated on `onSubmit`, so turning the root composer off does not turn
+   * replying off with it.
+   */
+  readonly rootComposer?: boolean | undefined
+  /**
+   * Which composer the root composer IS (ADR-148 D5). `'rich'` mounts the
+   * TipTap surface behind one lazy boundary — the chunk is requested when a
+   * composer mounts, never by rendering the list — and falls back to the plain
+   * textarea if the chunk cannot load (D6) or the draft holds syntax outside
+   * the subset (D3 rule 2). `'plain'` is the default until the owner flips it
+   * after the eyeball pass. Both satisfy the same `value`/`onChange` seam, so
+   * nothing else here can tell them apart.
+   */
+  /**
+   * Which composer to draw. Uncontrolled by default: this is the INITIAL
+   * value and the footer's switcher changes it from there, so the switcher
+   * works with no wiring. Pass `onComposerChange` to control it instead.
+   */
+  /**
+   * The `@` picker's options, for the root composer and every reply
+   * (ADR-149 D6). The host filters a list it already has; the picker is a
+   * convenience and never an authorization gate, because the server re-checks
+   * every mention it extracts from `body_md` at write time.
+   *
+   * Absent — the default — `@` is ordinary text and no popup opens. It reaches
+   * the rich composer only; the plain textarea has no suggestion layer, by
+   * design (ADR-149 D2).
+   */
+  readonly mentionItems?: ((query: string) => readonly MentionSuggestionItem[]) | undefined
+  readonly composer?: 'plain' | 'rich' | undefined
+  readonly onComposerChange?: ((composer: 'plain' | 'rich') => void) | undefined
+  readonly className?: string | undefined
+}
+
+export function Thread({
+  onReact,
+  onVote,
+  onRetry,
+  onSelectAuthor,
+  onSelectMention,
+  onOpenAttachment,
+  resolveAttachmentUrl,
+  onHideLinkPreview,
+  onCopyLink,
+  onCopyText,
+  onEdit,
+  onDelete,
+  onContinueThread,
+  sending = false,
+  indentClampDepth = DEFAULT_INDENT_CLAMP_DEPTH,
+  header,
+  participants,
+  participantTotal,
+  composerAvatar,
+  composerPlaceholder = 'Add a comment…',
+  composerMaxLength,
+  dateSeparators = true,
+  emptyState,
+  locale,
+  variant = 'panel',
+  rootComposer = true,
+  mentionItems,
+  uploadAttachment,
+  attachGif,
+  searchGifs,
+  attachmentAccept,
+  attachmentMaxPerComment,
+  attachmentMaxFileBytes,
+  attachmentMaxTotalBytes,
+  composer = 'plain',
+  onComposerChange,
+  className,
+  ...threadOptions
+}: ThreadProps) {
+  const thread = useThread(threadOptions)
+
+  /**
+   * THE live region's text, and the only state that feeds it.
+   *
+   * `seq` exists because a live region speaks when its text CHANGES, not when
+   * it is written: collapsing two different comments that happen to have the
+   * same number of replies produces byte-identical text and the second one
+   * would be silent. The rendered string alternates a trailing NBSP on the
+   * sequence, which every screen reader trims out of the spoken output but the
+   * DOM counts as a change. Cheaper and more reliable than the two-region
+   * swap, and it keeps ONE region rather than two.
+   */
+  const [announcement, setAnnouncement] = useState<{
+    readonly text: string
+    readonly seq: number
+  }>({ text: '', seq: 0 })
+
+  const announce = useCallback((message: string) => {
+    setAnnouncement((prev) => ({ text: message, seq: prev.seq + 1 }))
+  }, [])
+
+  const announcementText =
+    announcement.text === ''
+      ? ''
+      : announcement.seq % 2 === 0
+        ? `${announcement.text}\u{00A0}`
+        : announcement.text
+
+  const comments = threadOptions.comments
+  const seenStates = useRef<ReadonlyMap<string, CommentDeliveryState> | null>(null)
+
+  /**
+   * Content that changes with NO user action behind it has to announce itself.
+   *
+   * Two things do that here and neither used to say anything, while the one
+   * thing that already spoke was the failure (`role="alert"` on a failed send,
+   * comment.tsx): an optimistic comment landing, and the poll bringing in
+   * replies the viewer did not write. Success and other people's words were
+   * silent; only failure had a voice.
+   *
+   * The two are told apart by DELIVERY STATE rather than by an author id,
+   * which this primitive deliberately does not have: an optimistic send enters
+   * the list as `pending`, so an id that appears already `sent` arrived from
+   * the server and belongs to somebody else. `failed` -> `sent` counts as a
+   * landing too, because a successful retry is the same event.
+   */
+  useEffect(() => {
+    const next = new Map<string, CommentDeliveryState>()
+    for (const comment of comments) next.set(comment.id, comment.state ?? 'sent')
+    const previous = seenStates.current
+    seenStates.current = next
+    // FIRST RUN SEEDS THE BASELINE AND SAYS NOTHING. Announcing here would
+    // make every single page load read the whole comment count aloud, which is
+    // the documented way this pattern gets turned off by the people it is for.
+    if (previous === null) return
+    let landed = 0
+    let arrived = 0
+    for (const [id, state] of next) {
+      const before = previous.get(id)
+      if (before === undefined) {
+        if (state === 'sent') arrived += 1
+      } else if (before !== 'sent' && state === 'sent') {
+        landed += 1
+      }
+    }
+    const parts: string[] = []
+    if (landed > 0) {
+      parts.push(landed === 1 ? 'Comment posted' : `${String(landed)} comments posted`)
+    }
+    if (arrived > 0) {
+      parts.push(arrived === 1 ? '1 new comment' : `${String(arrived)} new comments`)
+    }
+    if (parts.length > 0) announce(parts.join('. '))
+  }, [announce, comments])
+
+  // Uncontrolled unless the host asks to own it. `composer` seeds the state and
+  // keeps it in sync when a controlling host changes it; without a callback the
+  // switcher just works.
+  const [composerMode, setComposerMode] = useState<'plain' | 'rich'>(composer)
+  useEffect(() => {
+    setComposerMode(composer)
+  }, [composer])
+  const activeComposer = onComposerChange === undefined ? composerMode : composer
+  const changeComposer = useCallback(
+    (next: 'plain' | 'rich') => {
+      setComposerMode(next)
+      onComposerChange?.(next)
+    },
+    [onComposerChange],
+  )
+  const ctx: ThreadRenderContext = {
+    composer: activeComposer,
+    onComposerChange: changeComposer,
+    thread,
+    sending,
+    indentClampDepth,
+    announce,
+    ...(locale === undefined ? {} : { locale }),
+    ...(composerAvatar === undefined ? {} : { replyAvatar: composerAvatar }),
+    ...(onReact === undefined ? {} : { onReact }),
+    ...(onVote === undefined ? {} : { onVote }),
+    ...(onRetry === undefined ? {} : { onRetry }),
+    ...(onSelectAuthor === undefined ? {} : { onSelectAuthor }),
+    ...(onSelectMention === undefined ? {} : { onSelectMention }),
+    ...(onOpenAttachment === undefined ? {} : { onOpenAttachment }),
+    ...(resolveAttachmentUrl === undefined ? {} : { resolveAttachmentUrl }),
+    ...(onHideLinkPreview === undefined ? {} : { onHideLinkPreview }),
+    ...(onCopyLink === undefined ? {} : { onCopyLink }),
+    ...(onCopyText === undefined ? {} : { onCopyText }),
+    ...(onEdit === undefined ? {} : { onEdit }),
+    ...(onDelete === undefined ? {} : { onDelete }),
+    ...(onContinueThread === undefined ? {} : { onContinueThread }),
+    ...(composerMaxLength === undefined ? {} : { composerMaxLength }),
+    ...(mentionItems === undefined ? {} : { mentionItems }),
+    ...(uploadAttachment === undefined ? {} : { uploadAttachment }),
+    ...(attachGif === undefined ? {} : { attachGif }),
+    ...(searchGifs === undefined ? {} : { searchGifs }),
+    ...(attachmentAccept === undefined ? {} : { attachmentAccept }),
+    ...(attachmentMaxPerComment === undefined ? {} : { attachmentMaxPerComment }),
+    ...(attachmentMaxFileBytes === undefined ? {} : { attachmentMaxFileBytes }),
+    ...(attachmentMaxTotalBytes === undefined ? {} : { attachmentMaxTotalBytes }),
+  }
+
+  const panel = variant === 'panel'
+  // Annotated, not inferred — see the same note in comment.tsx: the plain
+  // composer satisfies the rich composer's (wider) props and ignores the seam.
+  const Composer: (props: RichThreadComposerProps) => ReactElement =
+    activeComposer === 'rich' ? RichThreadComposer : ThreadComposer
+
+  // Derived up front rather than by mutating a cursor inside the map: render
+  // stays pure, and the run boundaries are one readable expression instead of
+  // a side effect hidden in a JSX callback.
+  const separatorFor: readonly (string | null)[] = thread.roots.map((node, index) => {
+    if (!dateSeparators) return null
+    const previous = thread.roots[index - 1]
+    if (previous !== undefined && startOfDay(previous.createdAt) === startOfDay(node.createdAt)) {
+      return null
+    }
+    return dayLabel(node.createdAt, thread.now, locale)
+  })
+
+  /**
+   * Roots grouped into day RUNS, one `<ul>` per run.
+   *
+   * The list markup is not cosmetic: a thread IS a list and its nesting is the
+   * whole information structure, so without `<ul>`/`<li>` a screen reader gets
+   * no item count, no boundaries and no depth. A `<ul>` may contain only
+   * `<li>`, which leaves the day separator somewhere to go, and the answer is
+   * NOT inside the item. A sticky element is clipped to its own containing
+   * block, so a separator moved into a list item would unstick the moment that
+   * one comment scrolled past, and the rest of its run would sit under no
+   * heading at all. One list per run keeps the separator a sibling of the list
+   * — exactly where it is today — and the geometry byte-identical: the run
+   * `<ul>` is a zero-margin, zero-padding flex column carrying the SAME
+   * `--space-2` gap the outer column had, so every box keeps its old edges.
+   */
+  const runs: {
+    readonly key: string
+    readonly separator: string | null
+    readonly nodes: CommentNode[]
+  }[] = []
+  thread.roots.forEach((node: CommentNode, index: number) => {
+    const separator = separatorFor[index] ?? null
+    const current = runs[runs.length - 1]
+    if (separator !== null || current === undefined) {
+      runs.push({ key: node.id, separator, nodes: [node] })
+    } else {
+      current.nodes.push(node)
+    }
+  })
+
+  return (
+    <section
+      aria-label="Comments"
+      className={cn('ds-thread flex min-h-0 flex-col', panel && 'ds-card-surface', className)}
+      {...(panel ? { 'data-framed': 'true' } : {})}
+      style={panel ? PANEL_STYLE : undefined}
+    >
+      {/* THE polite live region, and it is rendered EMPTY here on mount and
+          kept in the DOM for the life of the thread. A live region injected
+          into the document at the moment it has something to say is the
+          documented way to get an announcement that never arrives — the AT has
+          to be observing the node before the text lands. */}
+      <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+        {announcementText}
+      </div>
+
+      {header === undefined ? null : (
+        <div style={{ marginBlockEnd: 'var(--space-3)' }}>{header}</div>
+      )}
+
+      {/* Sticky sort bar. The rule under it is required structure, not
+          decoration — it is what separates the header from the list when the
+          list scrolls under it. */}
+      <div
+        className="flex items-center gap-[var(--space-3)] border-b"
+        style={{
+          borderColor: 'rgb(var(--border))',
+          paddingBlockEnd: 'var(--space-2)',
+        }}
+      >
+        <span
+          className="inline-flex items-center gap-[var(--space-1)] text-[13px] font-semibold"
+          style={{ color: 'rgb(var(--foreground))' }}
+        >
+          <MessageSquare size={12} strokeWidth={2} aria-hidden="true" />
+          Comments
+          {/* Reserved slot: 12 → 13 must not move the sort pills. */}
+          <span
+            className="text-right tabular-nums"
+            style={{ minInlineSize: '2.5ch', color: 'rgb(var(--text-tertiary))' }}
+          >
+            {thread.totalCount}
+          </span>
+        </span>
+
+        {participants === undefined || participants.length === 0 ? null : (
+          <AvatarGroup
+            max={4}
+            total={participantTotal ?? participants.length}
+            className="ds-avatar-on-frame"
+          >
+            {participants.map((participant) => {
+              const tint = asAvatarTint(participant.tint)
+              return (
+                <Avatar
+                  key={participant.id}
+                  name={participant.name}
+                  size="sm"
+                  ring
+                  seed={participant.id}
+                  src={participant.avatarUrl ?? null}
+                  {...(tint === undefined ? {} : { tint })}
+                />
+              )
+            })}
+          </AvatarGroup>
+        )}
+
+        <div className="ms-auto">
+          <SortPills value={thread.sort} onChange={thread.setSort} />
+        </div>
+      </div>
+
+      <div className={cn(
+          'ds-thread__scroll min-h-0 flex-1 overflow-y-auto',
+          // Scroll stops here. Without containment a wheel gesture that hits
+          // the end of this list chains to PageShell's content region and the
+          // page moves under the thread.
+          'overscroll-contain',
+        )}>
+        {thread.roots.length === 0 ? (
+          <div
+            className="text-[13px]"
+            style={{ color: 'rgb(var(--text-tertiary))', paddingBlock: 'var(--space-4)' }}
+          >
+            {emptyState ?? 'No comments yet. Start the conversation.'}
+          </div>
+        ) : (
+          <div className="flex flex-col gap-[var(--space-2)]">
+            {runs.map((run) => (
+              <Fragment key={run.key}>
+                {run.separator === null ? null : <DateSeparator label={run.separator} />}
+                {/* `role="list"` is restated because `list-style: none` drops
+                    the implicit list role in Safari/VoiceOver, which would
+                    hand back exactly the structure this markup exists to
+                    give. `m-0 p-0` removes the UA list indent, which is the
+                    only geometry a bare `<ul>` would have changed. */}
+                <ul
+                  role="list"
+                  className="m-0 flex list-none flex-col gap-[var(--space-2)] p-0"
+                >
+                  {run.nodes.map((node) => (
+                    // The `<li>` is the list item; the card is its chrome. The
+                    // root CommentItem stays a `<div>` (`listItem={false}`)
+                    // because the card has to sit BETWEEN the item and the
+                    // comment — the comment's own block-start padding is what
+                    // supplies the card's top inset.
+                    <li key={node.id}>
+                      {/* One card, the whole thread. `<Card>` rather than a
+                          forked `<div>` with a background token — the
+                          primitive owns the opaque surface, the border and the
+                          shadow (CLAUDE.md §2). */}
+                      <Card
+                        // `h-full` + `overflow-hidden` are Card's defaults for
+                        // a grid cell. Here the card is a flow item whose
+                        // height is its content, and clipping would eat the
+                        // focus ring on the rail hairline sitting at its
+                        // inline-start edge.
+                        className="h-auto overflow-visible"
+                        style={CARD_STYLE}
+                      >
+                        <CommentItem
+                          node={node}
+                          ctx={ctx}
+                          renderDepth={0}
+                          listItem={false}
+                        />
+                      </Card>
+                    </li>
+                  ))}
+                </ul>
+              </Fragment>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Pinned composer — a long thread stays replyable without scrolling
+          back to the top. */}
+      {thread.canReply && rootComposer ? (
+        <div
+          className="shrink-0 border-t"
+          style={{
+            borderColor: 'rgb(var(--border))',
+            paddingBlockStart: 'var(--space-3)',
+            marginBlockStart: 'var(--space-3)',
+          }}
+        >
+          <Composer
+            mode={activeComposer}
+            onModeChange={changeComposer}
+            label="Add a comment"
+            placeholder={composerPlaceholder}
+            value={thread.draft}
+            onChange={thread.setDraft}
+            onSubmit={thread.submit}
+            sending={sending}
+            {...(composerAvatar === undefined ? {} : { avatar: composerAvatar })}
+            {...(composerMaxLength === undefined ? {} : { maxLength: composerMaxLength })}
+            {...(mentionItems === undefined ? {} : { mentionItems })}
+            {...(uploadAttachment === undefined ? {} : { uploadAttachment })}
+            {...(attachGif === undefined ? {} : { attachGif })}
+            {...(searchGifs === undefined ? {} : { searchGifs })}
+            {...(attachmentAccept === undefined ? {} : { attachmentAccept })}
+            {...(attachmentMaxPerComment === undefined
+              ? {}
+              : { attachmentMaxPerComment })}
+            {...(attachmentMaxFileBytes === undefined ? {} : { attachmentMaxFileBytes })}
+            {...(attachmentMaxTotalBytes === undefined ? {} : { attachmentMaxTotalBytes })}
+          />
+        </div>
+      ) : null}
+    </section>
+  )
+}