@lovett/ui 0.0.11 → 0.2.0

package/src/thread/comment.tsx

@@ -0,0 +1,967 @@
+/**
+ * CommentItem — one comment and, recursively, everything under it.
+ *
+ * LAYOUT. Two columns and three rows, which is what lets the rail be a
+ * connector instead of a margin rule (see rail.tsx for the geometry):
+ *
+ *     ┌───────────────┬──────────────────────────────┐
+ *     │ avatar        │ byline · body · action row   │  row 1
+ *     │ stem + circle │                              │
+ *     ├───────────────┴──────────────────────────────┤
+ *     │ (reply composer, hung at --thread-content-x) │  row 2
+ *     ├──────────────────────────────────────────────┤
+ *     │ replies, each indenting itself by --thread-  │  row 3
+ *     │ indent and drawing its own connector segment │
+ *     └──────────────────────────────────────────────┘
+ *
+ * The frame around that grid is a `<li>` (`listItem`, the default), because a
+ * thread is a LIST and its nesting is the whole information structure. It costs
+ * no geometry: the grid is a CHILD of the frame, not the frame itself, so the
+ * element swap is block-for-block — a `list-item` box with `list-style: none`
+ * lays out exactly as the `<div>` did, and the padding that positions every
+ * connector stays on the same box. `display: contents` was never a candidate;
+ * it strips the list semantics in some AT and Safari versions, which is the
+ * entire thing being bought here. A ROOT passes `listItem={false}`: its `<li>`
+ * lives outside its `<Card>` in thread.tsx, since the comment's own block-start
+ * padding is what supplies the card's top inset.
+ *
+ * The avatar column occupies row 1 only, so it stretches to exactly the height
+ * of the comment's own content. That single fact is what pins the collapse
+ * circle level with the action row without anything measuring anything — and
+ * it keeps the circle there when a reply composer opens underneath, because the
+ * composer is in row 2.
+ *
+ * HIERARCHY IS TYPE AND SPACE, NOT BOXES. `↩ Reply` and the `•••` overflow sit
+ * at the inline-end of the byline, and they are QUIET — muted, borderless, no
+ * fill until hover. That combination is the point: an earlier pass put a
+ * BORDERED Reply there and the button competed with the name for the same line,
+ * which is a boxes-over-type failure rather than a placement one. Stripping the
+ * box resolves it, and it serves the product goal too (owner, 2026-09-06):
+ * Reply should be slightly out of the way, so people reach for the main comment
+ * box instead of threading every remark. See actions.tsx for why this is a
+ * deliberate, documented exception to CLAUDE.md §2's ghost-button rule.
+ *
+ * The row below the body is therefore ENGAGEMENT only — emoji reactions or
+ * votes, plus the in-flight notice. One purpose per row.
+ *
+ * SPACING. `--thread-row-gap` (12) separates comments; `--space-1` (4)
+ * separates the groups inside one. Four times the intra-group step, so grouping
+ * is carried by space alone and there is not a divider anywhere in the tree.
+ * That the gap is a comment's OWN block-start padding rather than a container
+ * gap is load-bearing: sibling boxes have to be flush for their connector
+ * segments to concatenate into one line.
+ *
+ * Corrections to the original port, all still in force:
+ *   1. Classes + public tokens, never inline `tok()` styles reaching internals.
+ *   2. Lucide icons, never the text glyphs the reference used.
+ *   3. Engagement state is props/callbacks, never local `useState`.
+ *   4. Nothing that animates open/closed is conditionally rendered.
+ */
+
+import { useState } from 'react'
+import type { CSSProperties, ReactElement, ReactNode } from 'react'
+import {
+  ChevronRight,
+  CornerDownRight,
+  FileText,
+  RotateCw,
+  TriangleAlert,
+} from 'lucide-react'
+import { Avatar, asAvatarTint } from '../avatar'
+import { Button } from '../button'
+import { cn } from '../lib/utils'
+import { CommentActions } from './actions'
+import { CommentBody, type MentionTarget } from './comment-body'
+import { ThreadComposer } from './composer'
+import {
+  RichThreadComposer,
+  type RichComposerAttachmentProps,
+  type RichThreadComposerProps,
+} from './rich-composer'
+import { CommentVote, ReactionBar } from './reactions'
+import { RelativeTime } from './relative-time'
+import { countDescendants } from './comment-tree'
+import { AttachmentGif, AttachmentImage } from './attachments'
+import { LinkPreview } from './link-preview'
+import {
+  CollapsedReplies,
+  DEFAULT_INDENT_CLAMP_DEPTH,
+  LineIcon,
+  ThreadConnector,
+  ThreadRail,
+  ThreadTrunkSegment,
+} from './rail'
+import type { UseThreadResult } from './use-thread'
+import type {
+  CommentNode,
+  MentionSuggestionItem,
+  ThreadAttachment,
+  ThreadAuthor,
+  ThreadLinkPreview,
+  ThreadReactionKey,
+  ThreadVote,
+} from './types'
+
+/**
+ * Everything the recursive renderer needs, assembled once at the root.
+ * One object rather than fourteen props threaded through every level — the
+ * reference passed four and had already started to sprawl.
+ */
+export interface ThreadRenderContext extends RichComposerAttachmentProps {
+  readonly thread: UseThreadResult
+  readonly locale?: string | undefined
+  readonly sending?: boolean | undefined
+  readonly replyAvatar?: ReactNode | undefined
+  /**
+   * Levels deeper than this stop ADDING indent. Purely presentational, which is
+   * why it lives here and not in the hook: nesting itself is uncapped, and the
+   * stored depth is never touched.
+   */
+  readonly indentClampDepth?: number | undefined
+  /**
+   * Writes to the ONE polite live region `<Thread>` owns. Collapse and expand
+   * go through it because `aria-expanded` reports that a state changed and
+   * says nothing about what happened to the eight comments that just left the
+   * page. Absent for a consumer driving `CommentItem` itself; the calls are
+   * optional and the tree renders identically without it.
+   */
+  readonly announce?: ((message: string) => void) | undefined
+  /**
+   * The `@` picker's options (ADR-149 D6). Absent, the popup never opens and
+   * `@` is ordinary text — which is what every host that has not wired a
+   * directory yet should get.
+   *
+   * A CONVENIENCE, never a permission boundary: the server parses `body_md` at
+   * write time and re-checks every mention it extracts, whether this offered
+   * it or someone typed it by hand.
+   */
+  readonly mentionItems?: ((query: string) => readonly MentionSuggestionItem[]) | undefined
+  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 is handed the SHAPE of the slot and asks for the bytes lazily.
+   * Omit it and every attachment renders as its placeholder, at the size it
+   * would have been: the layout never depends on whether this is supplied, or
+   * on whether it succeeded.
+   */
+  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 at all, which is the right
+   * default for a host that has not wired the mutation: an affordance that
+   * silently does nothing is worse than no affordance. The card also needs
+   * `canHide` — the host's optimistic removal and error invalidation live in
+   * the host, exactly as they do for reactions.
+   */
+  readonly onHideLinkPreview?: ((commentId: string, urlHash: string) => void) | undefined
+  /**
+   * The byline overflow menu. Each item is rendered only when its callback
+   * exists — an absent capability is an absent item, never a disabled one,
+   * because a permanently greyed row teaches people the surface is broken.
+   * `onCopyText` is the exception in shape: the body is already in hand, so the
+   * clipboard write happens here and the callback only reports the outcome.
+   */
+  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
+  /**
+   * Called instead of expanding in place when a FINITE `maxDepth` is hit — a
+   * consumer that has a dedicated permalink view wants to navigate there.
+   * Unreachable by default, because the default depth is uncapped.
+   */
+  readonly onContinueThread?: ((commentId: string) => void) | undefined
+  readonly composerMaxLength?: number | undefined
+  /**
+   * Which composer replies use (ADR-148 D5). Mirrors `ThreadProps.composer`.
+   * Threaded through the context rather than read from a store so a consumer
+   * driving `CommentItem` directly gets the plain composer unless it asks.
+   */
+  readonly composer?: 'plain' | 'rich' | undefined
+  /** Lets a REPLY composer's switcher change the whole thread's mode. */
+  readonly onComposerChange?: ((composer: 'plain' | 'rich') => void) | undefined
+}
+
+/** The two-column frame. Declared once so every level is byte-identical. */
+const GRID_STYLE: CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: 'var(--thread-avatar) minmax(0, 1fr)',
+  columnGap: 'var(--thread-gap)',
+}
+
+/**
+ * ADR-147 D5/D6 — the display fallback lives in the component, never in the
+ * data. `users.name` / `given_name` / `family_name` are nullable by standing
+ * policy precisely so nothing fabricates one at write time; that policy only
+ * holds if the read side degrades honestly instead of crashing.
+ */
+function authorLabel(author: ThreadAuthor | null | undefined): string {
+  if (author == null) return 'Deleted user'
+  const name = author.name?.trim()
+  if (name !== undefined && name !== '') return name
+  const email = author.email?.trim()
+  if (email !== undefined && email !== '') return email
+  return 'Unknown member'
+}
+
+/**
+ * THE tombstone strings — two acts, and a deliberate word for each.
+ *
+ * A comment becomes a tombstone two ways now (FU-0031, FU-0032): its author
+ * deleted it, or somebody else removed it. `[deleted]` was written when only
+ * the first existed, and it is read by the person whose comment is gone —
+ * telling them they did it themselves when they did not is the whole defect.
+ *
+ * REMOVED, not deleted. The two verbs carry the entire distinction, so each
+ * one is reserved for exactly one act: you delete your own, somebody removes
+ * yours. Any pair that shared a verb would need a qualifier to be read at all.
+ *
+ * "AN ADMIN", not "a workspace admin" and not "a moderator". The ONE thing
+ * `moderated` licenses the render to claim is that the author did not do it —
+ * that is the whole content of the flag, and how a host derives it is the
+ * host's business, not this module's. (An earlier draft asserted it comes from
+ * `deleted_by <> author_id`. That is one consumer's wire and appears nowhere in
+ * this repository; stating another product's schema as fact here is exactly the
+ * coupling this module's entity-agnostic claim rules out.) Naming a ROLE rather
+ * than a person keeps the claim true — nothing obliges a host to send an actor,
+ * and a string with a slot for one is a string somebody eventually fills.
+ * "Workspace" is one host's noun and this module is entity-agnostic by its own
+ * opening claim (types.ts); "moderator" is a forum's word for a role that
+ * exists in neither consumer. "Admin" is what both of them actually call the
+ * person who can do this, which is the test interface copy actually has to
+ * pass.
+ *
+ * TWO STRINGS PER ACT, because they land in two different slots. The byline is
+ * the AUTHOR position: a sentence there reads as an attribution, and "removed
+ * by an admin" sitting where a name goes says the admin wrote it. It also
+ * feeds two accessible names — "Collapse replies to X" and "More actions for
+ * X's comment" — which a sentence makes unusable. So the byline takes the
+ * short form and the body, which is the interface speaking in its own voice,
+ * takes the sentence.
+ *
+ * The brackets and the lower case are unchanged from `[deleted]`: that form is
+ * what marks a line as the system talking rather than a person, and a
+ * tombstone that stopped looking like one would be a worse regression than the
+ * one being fixed.
+ */
+const TOMBSTONE: Readonly<
+  Record<'deleted' | 'moderated', { readonly byline: string; readonly body: string }>
+> = {
+  deleted: { byline: '[deleted]', body: '[deleted]' },
+  moderated: { byline: '[removed]', body: '[removed by an admin]' },
+}
+
+/** "1 reply" / "8 replies" — the live region's wording, in one place. */
+function replyCountLabel(count: number): string {
+  return `${String(count)} ${count === 1 ? 'reply' : 'replies'}`
+}
+
+function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return ''
+  if (bytes < 1024) return `${String(bytes)} B`
+  if (bytes < 1024 * 1024) return `${String(Math.round(bytes / 1024))} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+function Attachments({
+  attachments,
+  onOpen,
+  resolveUrl,
+}: {
+  attachments: readonly ThreadAttachment[]
+  onOpen?: ((attachment: ThreadAttachment) => void) | undefined
+  resolveUrl?: ((attachmentId: string) => Promise<string | null>) | undefined
+}) {
+  // Three buckets, not two, since ADR-151 D4: a Giphy mp4 renders through
+  // `AttachmentGif`; an uploaded image/gif remains in `images`, where
+  // `AttachmentImage` gives it the equivalent still-frame treatment.
+  const images = attachments.filter((a) => a.kind === 'image')
+  const gifs = attachments.filter((a) => a.kind === 'gif')
+  const files = attachments.filter((a) => a.kind === 'file')
+  return (
+    <div
+      className="flex flex-col gap-[var(--space-2)]"
+      style={{ marginBlockStart: 'var(--space-2)' }}
+    >
+      {images.length === 0 && gifs.length === 0 ? null : (
+        <div className="flex flex-wrap gap-[var(--space-2)]">
+          {images.map((attachment) => (
+            <AttachmentImage
+              key={attachment.id}
+              attachment={attachment}
+              onOpen={onOpen}
+              resolveUrl={resolveUrl}
+            />
+          ))}
+          {gifs.map((attachment) => (
+            <AttachmentGif key={attachment.id} attachment={attachment} resolveUrl={resolveUrl} />
+          ))}
+        </div>
+      )}
+      {files.map((attachment) => (
+        <button
+          key={attachment.id}
+          type="button"
+          disabled={onOpen === undefined}
+          onClick={() => {
+            onOpen?.(attachment)
+          }}
+          className={cn(
+            // Optical padding: 8 inline against 4 block, because the line box
+            // already carries space the glyphs do not fill.
+            'inline-flex max-w-full items-center gap-[var(--space-2)] self-start border px-[var(--space-2)] py-[var(--space-1)] text-[12px]',
+            'border-[rgb(var(--border))] bg-[rgb(var(--surface-inset))] text-[rgb(var(--text-secondary))]',
+            'transition-[background-color,border-color] duration-[var(--dur-fast)] ease-[var(--ease-out)] motion-reduce:transition-none',
+            'enabled:hover:border-[rgb(var(--border-strong))] enabled:hover:bg-[rgb(var(--surface-hover))]',
+            'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+            'disabled:cursor-default',
+          )}
+          style={{ borderRadius: 'var(--thread-inner-radius, var(--radius-sm))' }}
+        >
+          <LineIcon>
+            <FileText size={12} strokeWidth={1.5} aria-hidden="true" />
+          </LineIcon>
+          <span className="truncate">{attachment.name}</span>
+          {attachment.sizeBytes === undefined ? null : (
+            <span className="tabular-nums" style={{ color: 'rgb(var(--text-tertiary))' }}>
+              {formatBytes(attachment.sizeBytes)}
+            </span>
+          )}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+/**
+ * Every visible card on one comment (ADR-150 D8).
+ *
+ * There is ONE of these, reached by the one recursive `CommentItem`, so a root
+ * and a reply are rendered by the same code by construction rather than by
+ * two call sites agreeing. Ordering comes from the worker (`sort_order`,
+ * document order) and is not re-sorted here.
+ */
+function LinkPreviews({
+  commentId,
+  previews,
+  onHide,
+}: {
+  commentId: string
+  previews: readonly ThreadLinkPreview[]
+  onHide?: ((commentId: string, urlHash: string) => void) | undefined
+}) {
+  return (
+    <div
+      className="flex flex-col gap-[var(--space-2)]"
+      style={{ marginBlockStart: 'var(--space-2)' }}
+    >
+      {previews.map((preview) => (
+        <LinkPreview
+          key={preview.urlHash}
+          preview={preview}
+          {...(onHide === undefined
+            ? {}
+            : {
+                onHide: () => {
+                  onHide(commentId, preview.urlHash)
+                },
+              })}
+        />
+      ))}
+    </div>
+  )
+}
+
+export interface CommentItemProps {
+  readonly node: CommentNode
+  readonly ctx: ThreadRenderContext
+  /**
+   * RENDER depth. Only two things read it: the (uncapped by default)
+   * `maxDepth`, and the indent clamp. `node.depth` is the true stored depth.
+   */
+  readonly renderDepth: number
+  /**
+   * Last of its sibling run. The last reply TERMINATES the connector at its own
+   * avatar; every other one carries the line on to the next. Roots are always
+   * last — a root has no rail above it to carry.
+   */
+  readonly isLast?: boolean | undefined
+  /**
+   * Render the frame as an `<li>`. Defaults to true, because the recursive
+   * case is the common one and a comment is a list item: every reply is a
+   * direct child of its parent's replies `<ul>`. Pass false wherever the
+   * `<li>` is supplied by the caller instead — `<Thread>` does exactly that
+   * for a ROOT, whose `<li>` has to sit OUTSIDE its `<Card>` (the comment's own
+   * block-start padding is what supplies the card's top inset). A custom skin
+   * built on `useThread` owns its own root list and should do the same.
+   */
+  readonly listItem?: boolean | undefined
+}
+
+export function CommentItem({
+  node,
+  ctx,
+  renderDepth,
+  isLast = true,
+  listItem = true,
+}: CommentItemProps) {
+  const { thread } = ctx
+  // "Continue this thread" expands the subtree in place when a consumer set a
+  // finite maxDepth and has nowhere to navigate to. Local, and correctly lost
+  // on unmount: it is a view preference, not content.
+  const [continued, setContinued] = useState(false)
+
+  const collapsed = thread.isCollapsed(node.id)
+  const deleted = node.deletedAt != null
+  const state = node.state ?? 'sent'
+  // `moderated` says nothing about a live comment — nobody has removed one —
+  // so it is read HERE, under `deleted`, and nowhere else in the render. A
+  // comment carrying the flag without a `deletedAt` is not a tombstone and
+  // does not become one.
+  const tombstone = deleted ? TOMBSTONE[node.moderated === true ? 'moderated' : 'deleted'] : null
+  const label = tombstone === null ? authorLabel(node.author) : tombstone.byline
+  const descendants = countDescendants(node)
+  const atCap = renderDepth >= thread.maxDepth && !continued
+  const { visible, hidden } = thread.visibleReplies(node)
+  const hasChildren = node.replies.length > 0
+  const replyOpen = thread.isReplyingTo(node.id)
+  // ADR-148 D5: reply composers are rich only after their first open. Every
+  // comment keeps its reply composer MOUNTED (correction 4 — nothing that
+  // animates is conditionally rendered), so without this latch a 24-comment
+  // thread would mount 24 ProseMirror editors before anyone replied. Once
+  // opened it stays rich, so the closing animation never swaps content
+  // mid-flight (the collapse rule: content keeps its size while closing).
+  const [replyEverOpened, setReplyEverOpened] = useState(false)
+  if (replyOpen && !replyEverOpened) setReplyEverOpened(true)
+  // Annotated rather than inferred so the ADR-149/151 seams can be passed to the
+  // union: `RichThreadComposerProps` extends `ThreadComposerProps`, so the
+  // plain composer satisfies this signature and simply never receives the
+  // rich-only capabilities.
+  const ReplyComposer: (props: RichThreadComposerProps) => ReactElement =
+    ctx.composer === 'rich' && replyEverOpened ? RichThreadComposer : ThreadComposer
+  // Narrow once, so the byline never needs a cast to satisfy the callback.
+  const author = node.author ?? null
+  // `avatar_color` is a nullable TEXT column, so it is parsed at this boundary
+  // rather than trusted as a domain value (D6).
+  const tint = asAvatarTint(author?.tint)
+  const canEngage = !deleted && state === 'sent'
+  const indentClampDepth = ctx.indentClampDepth ?? DEFAULT_INDENT_CLAMP_DEPTH
+
+  // A reply draws the segment of the connector that spans its own box.
+  const connected = renderDepth > 0
+  // Past the clamp the indent stops growing, so there is no gutter to curve in
+  // and the line drops straight onto the child's avatar instead.
+  const clamped = renderDepth > indentClampDepth
+  // The rail only exists where it leads somewhere. A leaf comment costs no
+  // chrome at all, which is most of why depth got cheap.
+  const railed = hasChildren && !atCap
+  // Deliberately WITHOUT the count. The summary chip below a collapsed subtree
+  // names the count ("Show 8 replies to Priya Nair"); the circle names the
+  // toggle. Two controls that do the same thing may share a target, but they
+  // must not share an accessible name, or a screen-reader user hears the same
+  // control twice and cannot tell which one they are on.
+  const collapseLabel = `${collapsed ? 'Show' : 'Collapse'} replies to ${label}`
+  // ENGAGEMENT only — Reply lives in the byline now. One purpose per row.
+  const showActions = state === 'pending' || (canEngage && thread.engagement !== 'none')
+
+  // The frame element. A `list-item` box with `list-style: none` (set by the
+  // `<ul>` and inherited) is laid out exactly as a block, so this swap moves
+  // nothing: same padding, same containing block for the connectors.
+  const Frame = listItem ? 'li' : 'div'
+
+  return (
+    <Frame
+      className="relative"
+      data-comment-id={node.id}
+      style={{
+        // The comment's OWN top padding, never a container gap — sibling boxes
+        // must be flush for the connector segments to join.
+        paddingBlockStart: 'var(--thread-row-gap)',
+        ...(connected && !clamped ? { paddingInlineStart: 'var(--thread-indent)' } : {}),
+      }}
+    >
+      {connected ? <ThreadConnector clamped={clamped} isLast={isLast} /> : null}
+
+      <div style={GRID_STYLE}>
+        {/* AVATAR COLUMN — row 1 only, so it stretches to the height of this
+            comment's own content and the circle lands on the action row. */}
+        <div className="flex flex-col items-center" style={{ gridColumn: 1, gridRow: 1 }}>
+          <Avatar
+            // `decorative` because the name is rendered right beside it —
+            // otherwise a screen reader announces the same person twice.
+            decorative
+            name={author?.name ?? author?.email ?? null}
+            size="md"
+            src={author?.avatarUrl ?? null}
+            {...(deleted || author === null ? { initial: '?' } : {})}
+            {...(tint === undefined ? {} : { tint })}
+            {...(author?.id == null ? {} : { seed: author.id })}
+          />
+          {railed ? (
+            <ThreadRail
+              collapsed={collapsed}
+              label={collapseLabel}
+              onToggle={() => {
+                thread.toggleCollapse(node.id)
+                // `collapsed` is the state BEFORE the toggle, so the message
+                // names the state being entered.
+                ctx.announce?.(
+                  `${collapsed ? 'Expanded' : 'Collapsed'} ${replyCountLabel(descendants)}`,
+                )
+              }}
+            />
+          ) : null}
+        </div>
+
+        {/* CONTENT COLUMN — row 1. Identity, then the body, then one action
+            row. Nothing here is a box; the hierarchy is weight and space. */}
+        <div className="min-w-0" style={{ gridColumn: 2, gridRow: 1 }}>
+          <div
+            data-thread-byline
+            // Deliberately NOT `flex-wrap`. A wrapping byline drops the action
+            // cluster onto a second line the moment a name gets long, which is
+            // the reflow this row must never do; the identity group absorbs the
+            // pressure by truncating instead.
+            className="flex items-center gap-[var(--space-2)]"
+            // Optically centres the name against the face beside it. The floor
+            // is the avatar PLUS the trailing gap, because `border-box` counts
+            // padding into `min-block-size`: without the addition the content
+            // box would be 28 and the text would centre 2px above the avatar.
+            style={{
+              minBlockSize: 'calc(var(--thread-avatar) + var(--space-1))',
+              paddingBlockEnd: 'var(--space-1)',
+            }}
+          >
+            <div className="flex min-w-0 flex-1 items-center gap-[var(--space-2)]">
+              {ctx.onSelectAuthor !== undefined && !deleted && author !== null ? (
+                <button
+                  type="button"
+                  onClick={() => {
+                    ctx.onSelectAuthor?.(author)
+                  }}
+                  className={cn(
+                    'min-w-0 truncate text-[14px] font-semibold text-[rgb(var(--foreground))]',
+                    'underline-offset-2 hover:underline',
+                    'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                  )}
+                  style={{ borderRadius: 'var(--radius-xs)' }}
+                >
+                  {label}
+                </button>
+              ) : (
+                <span
+                  className="min-w-0 truncate text-[14px] font-semibold"
+                  style={{
+                    color: deleted ? 'rgb(var(--text-tertiary))' : 'rgb(var(--foreground))',
+                  }}
+                >
+                  {label}
+                </span>
+              )}
+              {author?.role == null || deleted ? null : (
+                <span
+                  className="shrink-0 text-[10.5px] font-semibold tracking-[0.04em] uppercase"
+                  style={{ color: 'rgb(var(--text-tertiary))' }}
+                >
+                  {author.role}
+                </span>
+              )}
+              <span
+                className="flex shrink-0 items-center gap-[var(--space-1)] text-[12px]"
+                style={{ color: 'rgb(var(--text-tertiary))' }}
+              >
+                <RelativeTime
+                  value={node.createdAt}
+                  now={thread.now}
+                  {...(ctx.locale === undefined ? {} : { locale: ctx.locale })}
+                />
+                {node.editedAt == null ? null : <span>· edited</span>}
+              </span>
+            </div>
+
+            <CommentActions
+              label={label}
+              replyOpen={replyOpen}
+              {...(canEngage && thread.canReply
+                ? {
+                    onReplyToggle: () => {
+                      if (replyOpen) thread.cancelReply()
+                      else thread.startReply(node.id)
+                    },
+                  }
+                : {})}
+              {...(deleted || node.bodyMd === '' ? {} : { copyText: node.bodyMd })}
+              {...(ctx.onCopyText === undefined
+                ? {}
+                : {
+                    onCopyText: (ok: boolean) => {
+                      ctx.onCopyText?.(node.id, ok)
+                    },
+                  })}
+              {...(ctx.onCopyLink === undefined
+                ? {}
+                : {
+                    onCopyLink: () => {
+                      ctx.onCopyLink?.(node.id)
+                    },
+                  })}
+              {...(ctx.onEdit === undefined || deleted
+                ? {}
+                : {
+                    onEdit: () => {
+                      ctx.onEdit?.(node.id)
+                    },
+                  })}
+              {...(ctx.onDelete === undefined || deleted
+                ? {}
+                : {
+                    onDelete: () => {
+                      ctx.onDelete?.(node.id)
+                    },
+                  })}
+            />
+          </div>
+
+          {node.orphanedParentId === null ? null : (
+            // ADR-147 D4: this reply named a parent that is NOT in this list.
+            // It is shown at top level because dropping it would be worse,
+            // but it is labelled, because silently promoting it would claim
+            // it was a new remark rather than an answer to something.
+            <p
+              className="flex items-start gap-[var(--space-1)] text-[11.5px] italic"
+              style={{
+                color: 'rgb(var(--text-tertiary))',
+                marginBlockEnd: 'var(--space-1)',
+              }}
+            >
+              <LineIcon>
+                <CornerDownRight size={10} strokeWidth={1.5} aria-hidden="true" />
+              </LineIcon>
+              In reply to a comment that isn&rsquo;t shown here
+            </p>
+          )}
+
+          {tombstone !== null ? (
+            <p className="text-[13px] italic" style={{ color: 'rgb(var(--text-tertiary))' }}>
+              {tombstone.body}
+            </p>
+          ) : (
+            <CommentBody
+              bodyMd={node.bodyMd}
+              {...(ctx.onSelectMention === undefined
+                ? {}
+                : { onSelectMention: ctx.onSelectMention })}
+            />
+          )}
+
+          {node.attachments === undefined || node.attachments.length === 0 || deleted ? null : (
+            <Attachments
+              attachments={node.attachments}
+              {...(ctx.onOpenAttachment === undefined ? {} : { onOpen: ctx.onOpenAttachment })}
+              {...(ctx.resolveAttachmentUrl === undefined
+                ? {}
+                : { resolveUrl: ctx.resolveAttachmentUrl })}
+            />
+          )}
+
+          {/* Link cards sit BELOW the person's own attachments: what they
+              deliberately attached outranks what a scanner found in their
+              prose. A tombstone shows none — the worker already returns none
+              for one (ADR-150 D8), and this is the second lock on it, because
+              a tombstone followed by three intact cards would leak the body
+              the tombstone exists to remove. */}
+          {node.linkPreviews === undefined || node.linkPreviews.length === 0 || deleted ? null : (
+            <LinkPreviews
+              commentId={node.id}
+              previews={node.linkPreviews}
+              {...(ctx.onHideLinkPreview === undefined
+                ? {}
+                : { onHide: ctx.onHideLinkPreview })}
+            />
+          )}
+
+          {/* THE engagement row. Emoji reactions (or votes) and the in-flight
+              notice share one line — the "+" used to sit on a line of its own
+              with nothing beside it, which read as an orphan rather than a
+              control. `--space-1` from the body above it, a quarter of the gap
+              to the next comment, so the grouping is unambiguous without a
+              rule. */}
+          {showActions ? (
+            <div
+              className="flex flex-wrap items-center gap-[var(--space-2)]"
+              style={{
+              marginBlockStart: 'var(--space-1)',
+              minBlockSize: 'var(--thread-action-h, var(--space-8))',
+            }}
+            >
+              {canEngage && thread.engagement === 'reactions' ? (
+                <ReactionBar
+                  reactions={node.reactions ?? []}
+                  {...(ctx.onReact === undefined
+                    ? {}
+                    : {
+                        onReact: (key: ThreadReactionKey) => {
+                          ctx.onReact?.(node.id, key)
+                        },
+                      })}
+                />
+              ) : null}
+
+              {canEngage && thread.engagement === 'votes' ? (
+                <CommentVote
+                  score={node.score ?? 0}
+                  viewerVote={node.viewerVote ?? 0}
+                  {...(ctx.onVote === undefined
+                    ? {}
+                    : {
+                        onVote: (next: ThreadVote) => {
+                          ctx.onVote?.(node.id, next)
+                        },
+                      })}
+                />
+              ) : null}
+
+              {state === 'pending' ? (
+                <span
+                  className="text-[11.5px] font-semibold"
+                  style={{ color: 'rgb(var(--text-tertiary))' }}
+                >
+                  Sending…
+                </span>
+              ) : null}
+            </div>
+          ) : null}
+
+          {state === 'failed' ? (
+            // role="alert": a send that failed after the person already
+            // looked away has to announce itself rather than wait to be
+            // noticed. ADR-147 D17.
+            <div
+              role="alert"
+              // TWO alignment axes, and they want opposite things — which is why
+              // this is two rows rather than one.
+              //
+              // OUTER is `items-center`: the message and the retry are siblings
+              // of unequal height (the button is taller than a line of 12px
+              // text), so aligning them to the start left the message riding
+              // ~2px above the button's centre line. Centring is what makes the
+              // two read as one row.
+              //
+              // INNER stays `items-start` so the icon keeps its `1lh`
+              // first-line alignment when the message wraps. Centring there too
+              // would drop the glyph to the middle of a three-line block, which
+              // is the defect the LineIcon wrapper exists to prevent.
+              className="flex flex-wrap items-center gap-[var(--space-2)] border px-[var(--space-2)] py-[var(--space-1)] text-[12px]"
+              style={{
+                marginBlockStart: 'var(--space-2)',
+                borderRadius: 'var(--thread-inner-radius, var(--radius-sm))',
+                borderColor: 'rgb(var(--destructive))',
+                background: 'rgb(var(--destructive-bg))',
+                color: 'rgb(var(--destructive-ink))',
+              }}
+            >
+              <span className="flex min-w-0 flex-1 items-start gap-[var(--space-2)]">
+                <LineIcon>
+                  <TriangleAlert size={12} strokeWidth={1.75} aria-hidden="true" />
+                </LineIcon>
+                <span className="min-w-0 flex-1">
+                  {node.errorText ?? 'This comment did not send.'}
+                </span>
+              </span>
+              {ctx.onRetry === undefined ? null : (
+                <Button
+                  variant="secondary"
+                  size="sm"
+                  leadingIcon={<RotateCw size={10} strokeWidth={1.75} aria-hidden="true" />}
+                  onClick={() => {
+                    ctx.onRetry?.(node.id)
+                  }}
+                >
+                  Try again
+                </Button>
+              )}
+            </div>
+          ) : null}
+
+          {hasChildren && atCap ? (
+            <Button
+              variant="secondary"
+              size="sm"
+              className="mt-[var(--space-2)]"
+              trailingIcon={<ChevronRight size={12} strokeWidth={1.75} aria-hidden="true" />}
+              onClick={() => {
+                if (ctx.onContinueThread !== undefined) ctx.onContinueThread(node.id)
+                else setContinued(true)
+              }}
+            >
+              Continue this thread
+            </Button>
+          ) : null}
+        </div>
+
+        {/* ROW 2 — the reply composer, hung on the same alignment edge as the
+            body. It sits BELOW the avatar column rather than inside it so that
+            opening it cannot drag the collapse circle off the action row; the
+            trunk segment keeps the line unbroken across it for as long as it is
+            open, and is zero-height while it is closed. */}
+        <div
+          className="relative"
+          style={{
+            gridColumn: '1 / -1',
+            gridRow: 2,
+            paddingInlineStart: 'var(--thread-content-x)',
+          }}
+        >
+          {railed && !collapsed ? <ThreadTrunkSegment /> : null}
+          {/* Mounted, driven by data-open — correction 4. Unmounting this would
+              make the open/close transition unobservable and would also throw
+              away whatever was typed on a stray re-render. `grid-rows` from
+              0fr to 1fr animates the CONTAINER: the content keeps its natural
+              size throughout and is clipped, so nothing reflows mid-collapse. */}
+          <div
+            data-open={replyOpen}
+            // Every control inside is `disabled` while closed, so nothing is
+            // focusable and hiding it from the a11y tree is honest rather
+            // than a focus trap. It stays MOUNTED — correction 4.
+            aria-hidden={!replyOpen}
+            className={cn(
+              'grid grid-rows-[0fr] opacity-0 data-[open=true]:grid-rows-[1fr] data-[open=true]:opacity-100',
+              'transition-[grid-template-rows,opacity] duration-[var(--dur-base)] ease-[var(--ease-out)]',
+              'motion-reduce:transition-none',
+            )}
+          >
+            <div className="overflow-hidden">
+              <div style={{ paddingBlockStart: 'var(--space-2)' }}>
+                <ReplyComposer
+                  {...(ctx.composer === undefined ? {} : { mode: ctx.composer })}
+                  {...(ctx.onComposerChange === undefined
+                    ? {}
+                    : { onModeChange: ctx.onComposerChange })}
+                  label={`Reply to ${label}`}
+                  placeholder={`Reply to ${label}…`}
+                  submitLabel="Reply"
+                  replyingTo={label}
+                  value={thread.replyDraft}
+                  onChange={thread.setReplyDraft}
+                  onSubmit={thread.submitReply}
+                  onCancel={thread.cancelReply}
+                  rows={2}
+                  toolbar={false}
+                  disabled={!replyOpen}
+                  {...(ctx.sending === undefined ? {} : { sending: ctx.sending })}
+                  {...(ctx.composerMaxLength === undefined
+                    ? {}
+                    : { maxLength: ctx.composerMaxLength })}
+                  {...(ctx.replyAvatar === undefined ? {} : { avatar: ctx.replyAvatar })}
+                  {...(ctx.mentionItems === undefined ? {} : { mentionItems: ctx.mentionItems })}
+                  {...(ctx.uploadAttachment === undefined
+                    ? {}
+                    : { uploadAttachment: ctx.uploadAttachment })}
+                  {...(ctx.attachGif === undefined ? {} : { attachGif: ctx.attachGif })}
+                  {...(ctx.searchGifs === undefined ? {} : { searchGifs: ctx.searchGifs })}
+                  {...(ctx.attachmentAccept === undefined
+                    ? {}
+                    : { attachmentAccept: ctx.attachmentAccept })}
+                  {...(ctx.attachmentMaxPerComment === undefined
+                    ? {}
+                    : { attachmentMaxPerComment: ctx.attachmentMaxPerComment })}
+                  {...(ctx.attachmentMaxFileBytes === undefined
+                    ? {}
+                    : { attachmentMaxFileBytes: ctx.attachmentMaxFileBytes })}
+                  {...(ctx.attachmentMaxTotalBytes === undefined
+                    ? {}
+                    : { attachmentMaxTotalBytes: ctx.attachmentMaxTotalBytes })}
+                />
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* ROW 3 — the replies. Collapsed, the subtree becomes a summary and the
+            rail simply terminates at the circle, exactly as the reference's
+            does. No container gap: every reply's own block-start padding is the
+            separation, so the connector segments stay flush. */}
+        {!hasChildren || atCap ? null : (
+          <div style={{ gridColumn: '1 / -1', gridRow: 3 }}>
+            {collapsed ? (
+              <div
+                style={{
+                  paddingBlockStart: 'var(--thread-row-gap)',
+                  paddingInlineStart: 'var(--thread-indent)',
+                }}
+              >
+                <CollapsedReplies
+                  node={node}
+                  count={descendants}
+                  now={thread.now}
+                  parentLabel={label}
+                  {...(ctx.locale === undefined ? {} : { locale: ctx.locale })}
+                  onExpand={() => {
+                    thread.setCollapsed(node.id, false)
+                    ctx.announce?.(`Expanded ${replyCountLabel(descendants)}`)
+                  }}
+                />
+              </div>
+            ) : (
+              <>
+                {/* One `<ul>` per NESTING LEVEL — the depth is the structure,
+                    so a reader gets it from the markup rather than from an
+                    indent they cannot see. Zero margin and zero padding, so
+                    the list contributes no box of its own: the replies keep
+                    the flush top edges their connector segments need.
+                    `role="list"` is restated because `list-style: none` drops
+                    the implicit role in Safari/VoiceOver.
+
+                    "Show N more" stays OUTSIDE the list. It is a control, not
+                    a reply, and inside it would inflate the announced item
+                    count past the number of comments actually there. */}
+                <ul role="list" className="m-0 list-none p-0">
+                  {visible.map((reply, index) => (
+                    <CommentItem
+                      key={reply.id}
+                      node={reply}
+                      ctx={ctx}
+                      // The line stops at the last reply's avatar — unless a
+                      // "Show N more" follows, in which case it carries on to it.
+                      isLast={index === visible.length - 1 && hidden === 0}
+                      // `continued` restarts the render budget for this subtree;
+                      // the STORED depth is untouched (D3 — capping display loses
+                      // nothing, capping storage loses data).
+                      renderDepth={continued ? 0 : renderDepth + 1}
+                    />
+                  ))}
+                </ul>
+                {hidden > 0 ? (
+                  <div
+                    style={{
+                      paddingBlockStart: 'var(--thread-row-gap)',
+                      paddingInlineStart: 'var(--thread-indent)',
+                    }}
+                  >
+                    <Button
+                      variant="secondary"
+                      size="sm"
+                      onClick={() => {
+                        thread.expandReplies(node.id)
+                      }}
+                    >
+                      Show {hidden} more {hidden === 1 ? 'reply' : 'replies'}
+                    </Button>
+                  </div>
+                ) : null}
+              </>
+            )}
+          </div>
+        )}
+      </div>
+    </Frame>
+  )
+}