@lovett/ui 0.0.11 → 0.2.0

package/src/thread/attachments.tsx

@@ -0,0 +1,1071 @@
+/**
+ * Composer attachments — the rendered half (ADR-151 D1, D4, D5, D6).
+ *
+ * Four things live here, and they are together because they are one feature
+ * seen from four places: the tray of chips under the composer, the button and
+ * drop target that fill it, the GIF picker that fills it a different way, and
+ * the renderers a posted comment uses.
+ *
+ * ## Reserve the slot, always
+ *
+ * Every surface below declares its box before it has anything to put in it —
+ * the chip has a fixed height, the progress bar occupies its row whether or not
+ * it is moving, the thumbnail uses the declared `aspectRatio`, and a broken
+ * image becomes a placeholder inside the same box rather than a collapse. The
+ * layout is not allowed to depend on whether bytes arrived.
+ *
+ * ## Motion
+ *
+ * `prefers-reduced-motion` is not decoration here. An autoplaying wall of GIFs
+ * is the single most reduced-motion-hostile thing this product could ship
+ * (ADR-151 D4), so under that preference a GIF renders as a still frame with an
+ * explicit play control, and pressing play is a choice the person made. A
+ * Giphy pick stores an **mp4**, so its `<video>` can genuinely hold the first
+ * frame. An uploaded GIF stays `kind: 'image'`; its renderer snapshots the
+ * loaded `<img>` to a canvas once and shows that still until the person elects
+ * to swap the live image back in.
+ *
+ * ## "Powered by GIPHY"
+ *
+ * Rendered in the picker. `TODO(legal):` required by Giphy's terms; noted once
+ * here and in ADR-151 D4, not litigated.
+ *
+ * ## Why this is not `packages/ui/src/file-upload/*`
+ *
+ * That family already ships — `FileUploadButton`, `FileDropZone`,
+ * `FilePreviewGrid`, `useFileUpload` — and CLAUDE.md §2 is explicit that
+ * forking a primitive is a defect. This is a deliberate exception, and the
+ * reasons are specific rather than aesthetic:
+ *
+ *   - **`useFileUpload` allows what ADR-151 D3 forbids.** Its accept list
+ *     includes `text/html`, `application/javascript` and Office documents; D3
+ *     enumerates nine formats and refuses everything else by name.
+ *   - **It uploads directly.** It drives its own XHR to a destination; D1
+ *     requires the two-step dance — bytes to the engine, then a server-verified
+ *     ticket — and the tray's states are `uploading | ready | failed` against
+ *     that ticket, not against a transfer.
+ *   - **Its 20 MB cap is hardcoded** and disagrees with D3's 25 MB, and it has
+ *     no per-comment total at all.
+ *   - **It calls `toast` internally**, so a refusal is announced by the
+ *     primitive rather than reported to the surface, and this composer needs
+ *     the message inline on the chip.
+ *   - Nothing in it has a concept of a pasted-text chip, an "Insert as text
+ *     instead" undo, or a GIF.
+ *
+ * **What that fork costs, stated rather than discovered later:** `FileDropZone`
+ * recurses into dropped FOLDERS via `FileSystemEntry`; `AttachmentDropZone`
+ * takes `dataTransfer.files` only, so dropping a folder attaches nothing. If
+ * folder drop is wanted here, lift that traversal out of `file-upload/` into a
+ * shared helper rather than copying it a second time.
+ *
+ * Recorded in `docs/follow-ups/_pending/adr-151-attachments-open-edges.md` §8
+ * as well, because a fork that is only justified in a file header is a fork
+ * nobody finds.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type DragEvent,
+  type ReactNode,
+} from 'react'
+import { FileText, Image as ImageIcon, ImageOff, Paperclip, Play, Search, X } from 'lucide-react'
+import { Button } from '../button'
+import { Input } from '../input'
+import { cn } from '../lib/utils'
+import {
+  GIF_SEARCH_DEBOUNCE_MS,
+  useAttachmentUrl,
+  type ComposerAttachment,
+} from './use-attachments'
+import type { ThreadAttachment } from './types'
+
+/* ── shared bits ────────────────────────────────────────────────────────── */
+
+/**
+ * The same quiet icon button `actions.tsx` uses, for the same reason.
+ *
+ * Exported (module-level, NOT from the package barrel) because `link-preview.tsx`
+ * needs the identical treatment for the identical reason: a 12px dismiss cross
+ * sitting inside an already-bordered card. Sharing the constant is what keeps
+ * "pick one hover treatment and use it for every interactive surface" true;
+ * `actions.tsx` holds a second, older copy of this pair, and a FOURTH consumer
+ * should promote the three of them into one module rather than copy it again.
+ *
+ * CLAUDE.md §2 bans `ghost` as the DEFAULT lesser button — "buttons must read
+ * as buttons" — with the exception it names being "genuinely chrome-dense
+ * contexts … inline icon toolbars". A 12px remove-cross inside a chip is that
+ * exception: a bordered button inside a bordered chip is two borders 4px apart,
+ * and the chip already reads as a button-shaped thing. The primary action of
+ * this whole surface is the composer's send, and it stays the only filled one.
+ */
+export const QUIET_ICON = cn(
+  'inline-flex shrink-0 items-center justify-center border-0 bg-transparent',
+  'text-[rgb(var(--text-tertiary))]',
+  'transition-[background-color,color] duration-[var(--dur-fast)] ease-[var(--ease-out)]',
+  'motion-reduce:transition-none',
+  'hover:bg-[rgb(var(--surface-overlay))] hover:text-[rgb(var(--foreground))]',
+  'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+  'disabled:cursor-default disabled:opacity-60',
+)
+
+/** The 24px hit-area floor from the interface standards §6, met by padding. */
+export const QUIET_ICON_BOX = {
+  minBlockSize: 'var(--space-6)',
+  minInlineSize: 'var(--space-6)',
+  borderRadius: 'var(--radius-xs)',
+} as const
+
+/**
+ * "2,500 characters" — grouped, because the whole reason this chip exists is
+ * that the number is large, and an ungrouped five-digit run is the one shape a
+ * reader cannot size at a glance.
+ */
+export function formatCharacterCount(count: number): string {
+  const n = Math.max(0, Math.round(count))
+  return `${n.toLocaleString('en-US')} ${n === 1 ? 'character' : 'characters'}`
+}
+
+export function formatAttachmentSize(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`
+}
+
+/**
+ * Does this viewer want less motion?
+ *
+ * Read as state and subscribed to, not read once: the preference can change
+ * while the page is open, and a GIF that keeps playing after someone turns
+ * reduced motion on has ignored them at the moment they asked.
+ */
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false)
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return
+    const query = window.matchMedia('(prefers-reduced-motion: reduce)')
+    setReduced(query.matches)
+    const onChange = (event: MediaQueryListEvent) => {
+      setReduced(event.matches)
+    }
+    query.addEventListener('change', onChange)
+    return () => {
+      query.removeEventListener('change', onChange)
+    }
+  }, [])
+  return reduced
+}
+
+/* ── the tray (D1, D5) ──────────────────────────────────────────────────── */
+
+export interface AttachmentTrayProps {
+  readonly attachments: readonly ComposerAttachment[]
+  readonly onRemove: (localId: string) => void
+  /**
+   * D5's undo. Given only for pasted-text chips; the action does not render on
+   * anything else, because there is nothing to restore.
+   */
+  readonly onInsertAsText?: ((localId: string) => void) | undefined
+  readonly className?: string | undefined
+}
+
+/**
+ * The chips under the composer.
+ *
+ * Nothing here is a pill: chips are lightly-rounded bars, per the data-display
+ * recipe. The row reserves its own height so adding the first attachment does
+ * not shove the editor upward, and the progress bar keeps its track whether or
+ * not it is moving.
+ */
+export function AttachmentTray({
+  attachments,
+  onRemove,
+  onInsertAsText,
+  className,
+}: AttachmentTrayProps) {
+  if (attachments.length === 0) return null
+  return (
+    <ul
+      className={cn('flex list-none flex-wrap gap-[var(--space-2)] p-0', className)}
+      style={{ marginBlockStart: 'var(--space-2)' }}
+    >
+      {attachments.map((attachment) => (
+        <AttachmentChip
+          key={attachment.localId}
+          attachment={attachment}
+          onRemove={onRemove}
+          {...(onInsertAsText === undefined ? {} : { onInsertAsText })}
+        />
+      ))}
+    </ul>
+  )
+}
+
+function AttachmentChip({
+  attachment,
+  onRemove,
+  onInsertAsText,
+}: {
+  attachment: ComposerAttachment
+  onRemove: (localId: string) => void
+  onInsertAsText?: ((localId: string) => void) | undefined
+}) {
+  const uploading = attachment.state === 'uploading'
+  const failed = attachment.state === 'failed'
+  const restorable = onInsertAsText !== undefined && attachment.pastedText !== undefined
+
+  return (
+    <li
+      className={cn(
+        'flex min-w-0 items-center gap-[var(--space-2)] border px-[var(--space-2)] py-[var(--space-1)]',
+        'text-[12px]',
+      )}
+      style={{
+        borderRadius: 'var(--radius-sm)',
+        borderColor: failed ? 'rgb(var(--destructive))' : 'rgb(var(--border))',
+        // `--muted`, not `--surface-overlay*`. CLAUDE.md §2 names chips as
+        // exactly what the flat opaque grey is for; the translucent overlay
+        // tints wash out when they stack on another layer, and a chip inside a
+        // composer inside a card is two layers deep already.
+        background: 'rgb(var(--muted))',
+        // The chip's height cannot depend on whether it holds a thumbnail, a
+        // progress bar or an error, or the composer would jump on every state
+        // change. One declared minimum, three contents.
+        minBlockSize: 'var(--ctrl-md)',
+        maxInlineSize: 'calc(var(--space-12) * 5)',
+      }}
+    >
+      <AttachmentChipThumb attachment={attachment} />
+
+      <span className="flex min-w-0 flex-col">
+        <span className="truncate" style={{ color: 'rgb(var(--foreground))' }}>
+          {attachment.name}
+        </span>
+        <span
+          className="flex items-center gap-[var(--space-2)] tabular-nums"
+          style={{
+            color: failed ? 'rgb(var(--destructive))' : 'rgb(var(--text-tertiary))',
+            // Reserved so the second line exists before there is anything on it.
+            minBlockSize: 'var(--space-4)',
+          }}
+        >
+          {failed ? (
+            <span className="truncate">{attachment.error ?? 'Upload failed'}</span>
+          ) : uploading ? (
+            <AttachmentProgress value={attachment.progress} label={attachment.name} />
+          ) : attachment.charCount === undefined ? (
+            <span>{formatAttachmentSize(attachment.sizeBytes)}</span>
+          ) : (
+            // D5, verbatim: "the character count shown on the chip". A byte
+            // size would be the wrong unit here — the person pasted characters,
+            // and for anything non-ASCII the two numbers differ.
+            <span>{formatCharacterCount(attachment.charCount)}</span>
+          )}
+        </span>
+      </span>
+
+      {restorable ? (
+        <Button
+          type="button"
+          variant="secondary"
+          size="sm"
+          onClick={() => {
+            onInsertAsText?.(attachment.localId)
+          }}
+        >
+          Insert as text instead
+        </Button>
+      ) : null}
+
+      <button
+        type="button"
+        aria-label={uploading ? `Cancel ${attachment.name}` : `Remove ${attachment.name}`}
+        className={QUIET_ICON}
+        style={QUIET_ICON_BOX}
+        onClick={() => {
+          onRemove(attachment.localId)
+        }}
+      >
+        <X size={12} strokeWidth={1.75} aria-hidden="true" />
+      </button>
+    </li>
+  )
+}
+
+/** A square thumbnail slot that exists whether or not there is an image in it. */
+function AttachmentChipThumb({ attachment }: { attachment: ComposerAttachment }) {
+  const visual = attachment.kind === 'image' || attachment.kind === 'gif'
+  return (
+    <span
+      className="flex shrink-0 items-center justify-center overflow-hidden border"
+      style={{
+        inlineSize: 'var(--space-6)',
+        blockSize: 'var(--space-6)',
+        borderRadius: 'var(--radius-xs)',
+        borderColor: 'rgb(var(--border))',
+        background: 'rgb(var(--muted))',
+        color: 'rgb(var(--text-tertiary))',
+      }}
+    >
+      {visual && attachment.previewUrl !== undefined ? (
+        <img src={attachment.previewUrl} alt="" className="h-full w-full object-cover" />
+      ) : visual ? (
+        <ImageIcon size={12} strokeWidth={1.5} aria-hidden="true" />
+      ) : (
+        <FileText size={12} strokeWidth={1.5} aria-hidden="true" />
+      )}
+    </span>
+  )
+}
+
+/**
+ * A determinate bar in a track that is always there.
+ *
+ * `role="progressbar"` with the real values, so a screen reader gets the number
+ * rather than a decorative div. The transition is on `inline-size` alone and
+ * drops out under reduced motion — this is a data change, and D-principles say
+ * data settles with ease-out and never springs.
+ */
+function AttachmentProgress({ value, label }: { value: number; label: string }) {
+  const percent = Math.round(Math.max(0, Math.min(1, value)) * 100)
+  return (
+    <span
+      role="progressbar"
+      aria-label={`Uploading ${label}`}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={percent}
+      className="block overflow-hidden"
+      style={{
+        inlineSize: 'calc(var(--space-12) * 2)',
+        blockSize: 'var(--space-1)',
+        borderRadius: 'var(--radius-full)',
+        background: 'rgb(var(--muted))',
+      }}
+    >
+      <span
+        className="block transition-[inline-size] duration-[var(--dur-base)] ease-[var(--ease-out)] motion-reduce:transition-none"
+        style={{
+          inlineSize: `${String(percent)}%`,
+          blockSize: '100%',
+          background: 'rgb(var(--accent))',
+        }}
+      />
+    </span>
+  )
+}
+
+/* ── the button + the drop target (D1) ──────────────────────────────────── */
+
+export interface AttachmentButtonProps {
+  readonly onFiles: (files: FileList) => void
+  /** `accept` for the file input. Mirrors the server's extension allowlist. */
+  readonly accept?: string | undefined
+  readonly disabled?: boolean | undefined
+  readonly label?: string | undefined
+}
+
+/** The paperclip. A real `<input type="file">` behind a labelled button. */
+export function AttachmentButton({
+  onFiles,
+  accept,
+  disabled = false,
+  label = 'Attach a file',
+}: AttachmentButtonProps) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const inputId = useId()
+  return (
+    <>
+      <input
+        ref={inputRef}
+        id={inputId}
+        type="file"
+        multiple
+        hidden
+        {...(accept === undefined ? {} : { accept })}
+        onChange={(event) => {
+          const { files } = event.currentTarget
+          if (files !== null && files.length > 0) onFiles(files)
+          // Reset so re-choosing the SAME file fires `change` again.
+          event.currentTarget.value = ''
+        }}
+      />
+      <button
+        type="button"
+        aria-label={label}
+        className={QUIET_ICON}
+        style={QUIET_ICON_BOX}
+        disabled={disabled}
+        onClick={() => {
+          inputRef.current?.click()
+        }}
+      >
+        <Paperclip size={14} strokeWidth={1.75} aria-hidden="true" />
+      </button>
+    </>
+  )
+}
+
+export interface AttachmentDropZoneProps {
+  readonly onFiles: (files: FileList) => void
+  readonly disabled?: boolean | undefined
+  readonly children: ReactNode
+  readonly className?: string | undefined
+}
+
+/**
+ * Wrap the composer to accept a drop.
+ *
+ * The overlay is `visibility`-toggled inside a slot that is always present, so
+ * a drag does not resize the composer — same reserve-the-slot rule as
+ * everything else here. The drag counter exists because `dragleave` fires when
+ * the pointer crosses a CHILD boundary, and a naive boolean flickers the
+ * overlay every time the cursor passes over the toolbar.
+ */
+export function AttachmentDropZone({
+  onFiles,
+  disabled = false,
+  children,
+  className,
+}: AttachmentDropZoneProps) {
+  const depth = useRef(0)
+  const [over, setOver] = useState(false)
+
+  const onDragEnter = useCallback(
+    (event: DragEvent<HTMLDivElement>) => {
+      if (disabled || !Array.from(event.dataTransfer.types).includes('Files')) return
+      depth.current += 1
+      setOver(true)
+    },
+    [disabled],
+  )
+
+  const onDragLeave = useCallback(() => {
+    depth.current = Math.max(0, depth.current - 1)
+    if (depth.current === 0) setOver(false)
+  }, [])
+
+  return (
+    <div
+      className={cn('relative', className)}
+      onDragEnter={onDragEnter}
+      onDragOver={(event) => {
+        if (!disabled && Array.from(event.dataTransfer.types).includes('Files')) {
+          event.preventDefault()
+        }
+      }}
+      onDragLeave={onDragLeave}
+      onDrop={(event) => {
+        depth.current = 0
+        setOver(false)
+        if (disabled) return
+        const { files } = event.dataTransfer
+        if (files.length === 0) return
+        event.preventDefault()
+        onFiles(files)
+      }}
+    >
+      {children}
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute inset-0 flex items-center justify-center border border-dashed transition-opacity duration-[var(--dur-fast)] ease-[var(--ease-out)] motion-reduce:transition-none"
+        style={{
+          visibility: over ? 'visible' : 'hidden',
+          opacity: over ? 1 : 0,
+          borderRadius: 'var(--radius-md)',
+          borderColor: 'rgb(var(--accent))',
+          background: 'rgb(var(--accent-subtle))',
+          color: 'rgb(var(--accent-ink))',
+        }}
+      >
+        Drop to attach
+      </div>
+    </div>
+  )
+}
+
+/* ── the GIF picker (D4) ────────────────────────────────────────────────── */
+
+export interface GifPickerResult {
+  readonly id: string
+  readonly title: string
+  readonly previewUrl: string
+  readonly stillUrl: string
+  readonly width: number
+  readonly height: number
+}
+
+export interface GifPickerProps {
+  /** Injected by the host — the primitive owns no fetch client (ADR-147 D5). */
+  readonly search: (query: string) => Promise<readonly GifPickerResult[]>
+  readonly onPick: (gif: GifPickerResult) => void
+  readonly className?: string | undefined
+}
+
+/**
+ * Type-to-search, debounced, with the still frame under reduced motion.
+ *
+ * The debounce is `GIF_SEARCH_DEBOUNCE_MS` and it is load-bearing rather than
+ * polish: Giphy's free tier is 100 requests/hour and an undebounced picker
+ * spends it in a minute.
+ *
+ * The grid reserves its own height so results appearing does not shove the
+ * composer, and every tile declares its aspect ratio so the grid does not
+ * reflow as renditions load at different sizes.
+ */
+export function GifPicker({ search, onPick, className }: GifPickerProps) {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState<readonly GifPickerResult[]>([])
+  const [state, setState] = useState<'idle' | 'searching' | 'error'>('idle')
+  const reduced = usePrefersReducedMotion()
+  const listId = useId()
+
+  /**
+   * `search` is read through a ref and is NOT a dependency — the same hazard
+   * `useAttachmentUrl` documents. A host writing
+   * `search={(q) => api.searchGifs(brandId, q)}` hands over a new identity every
+   * render; with that in the dependency array this effect would re-run, call
+   * `setState('searching')`, re-render, and re-run forever. The query is what
+   * identifies a search, and it is the only thing that should restart one.
+   */
+  const searchRef = useRef(search)
+  searchRef.current = search
+
+  useEffect(() => {
+    const trimmed = query.trim()
+    if (trimmed.length === 0) {
+      setResults([])
+      setState('idle')
+      return
+    }
+    let live = true
+    setState('searching')
+    const timer = setTimeout(() => {
+      void searchRef
+        .current(trimmed)
+        .then((next) => {
+          if (!live) return
+          setResults(next)
+          setState('idle')
+        })
+        .catch(() => {
+          if (!live) return
+          setResults([])
+          setState('error')
+        })
+    }, GIF_SEARCH_DEBOUNCE_MS)
+    return () => {
+      live = false
+      clearTimeout(timer)
+    }
+  }, [query])
+
+  return (
+    <div className={cn('flex flex-col gap-[var(--space-3)]', className)}>
+      <Input
+        value={query}
+        onChange={(event) => {
+          setQuery(event.currentTarget.value)
+        }}
+        placeholder="Search GIFs"
+        aria-label="Search GIFs"
+        aria-controls={listId}
+        leadingAffix={<Search size={14} strokeWidth={1.75} aria-hidden="true" />}
+      />
+
+      <div
+        id={listId}
+        className="grid grid-cols-3 gap-[var(--space-2)] overflow-y-auto"
+        style={{
+          // Declared, so the panel is the same size empty, searching and full.
+          blockSize: 'calc(var(--space-12) * 6)',
+        }}
+      >
+        {results.map((gif) => (
+          <button
+            key={gif.id}
+            type="button"
+            onClick={() => {
+              onPick(gif)
+            }}
+            className="block overflow-hidden border transition-[border-color] duration-[var(--dur-fast)] ease-[var(--ease-out)] hover:border-[rgb(var(--border-strong))] focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)] motion-reduce:transition-none"
+            style={{
+              borderRadius: 'var(--radius-sm)',
+              borderColor: 'rgb(var(--border))',
+              background: 'rgb(var(--muted))',
+              aspectRatio: gif.height > 0 ? String(gif.width / gif.height) : '1',
+            }}
+          >
+            {reduced ? (
+              <img src={gif.stillUrl} alt={gif.title} className="h-full w-full object-cover" />
+            ) : (
+              <video
+                src={gif.previewUrl}
+                poster={gif.stillUrl}
+                autoPlay
+                loop
+                muted
+                playsInline
+                aria-label={gif.title}
+                className="h-full w-full object-cover"
+              />
+            )}
+          </button>
+        ))}
+        {results.length === 0 ? (
+          <p
+            className="col-span-3 self-center text-center text-[12px]"
+            style={{ color: 'rgb(var(--text-tertiary))' }}
+          >
+            {state === 'error'
+              ? "GIF search isn't available right now."
+              : state === 'searching'
+                ? 'Searching…'
+                : query.trim().length === 0
+                  ? 'Type to search.'
+                  : 'No GIFs matched.'}
+          </p>
+        ) : null}
+      </div>
+
+      {/* TODO(legal): "Powered by GIPHY" attribution is required by Giphy's
+          terms of service. Noted here and in ADR-151 D4. */}
+      <p
+        className="text-[11px] uppercase"
+        style={{ color: 'rgb(var(--text-tertiary))', letterSpacing: '0.06em' }}
+      >
+        Powered by GIPHY
+      </p>
+    </div>
+  )
+}
+
+/* ── posted-comment rendering (D6) ──────────────────────────────────────── */
+
+export interface AttachmentGifProps {
+  readonly attachment: ThreadAttachment
+  /** Resolves the short-lived URL. Omit and the placeholder renders instead. */
+  readonly resolveUrl?: ((attachmentId: string) => Promise<string | null>) | undefined
+  readonly className?: string | undefined
+}
+
+/**
+ * A GIF in a posted comment, under `prefers-reduced-motion`.
+ *
+ * The stored rendition is an mp4, so "still frame with a play control" is a
+ * `<video>` that has not been told to play: it paints its poster frame and sits
+ * there. Pressing play is an explicit choice, and the control disappears once
+ * it is playing because at that point the video's own affordances take over.
+ *
+ * Without the preference it autoplays muted and looping, which is what a GIF
+ * is. With it, nothing moves until asked.
+ */
+export function AttachmentGif({ attachment, resolveUrl, className }: AttachmentGifProps) {
+  const reduced = usePrefersReducedMotion()
+  const { url, failed, loading } = useAttachmentUrl(attachment.id, resolveUrl)
+  const [playing, setPlaying] = useState(false)
+  const videoRef = useRef<HTMLVideoElement>(null)
+
+  // The preference can flip while the comment is on screen. Honouring it only
+  // at mount would leave a GIF looping at exactly the moment someone asked for
+  // less motion.
+  useEffect(() => {
+    if (reduced) setPlaying(false)
+  }, [reduced])
+
+  const shouldPlay = !reduced || playing
+
+  if (url === null || failed) {
+    return (
+      <AttachmentPlaceholder
+        attachment={attachment}
+        state={loading && !failed ? 'loading' : 'broken'}
+        className={className}
+      />
+    )
+  }
+
+  return (
+    <span
+      className={cn('relative block overflow-hidden border', className)}
+      style={{
+        aspectRatio: String(attachment.aspectRatio ?? 16 / 10),
+        borderRadius: 'var(--thread-inner-radius, var(--radius-sm))',
+        borderColor: 'rgb(var(--border))',
+        background: 'rgb(var(--surface-inset))',
+        inlineSize: 'calc(var(--space-12) * 3)',
+        minInlineSize: 'calc(var(--space-12) * 3)',
+      }}
+    >
+      <video
+        ref={videoRef}
+        src={url}
+        loop
+        muted
+        playsInline
+        autoPlay={shouldPlay}
+        aria-label={attachment.name}
+        className="h-full w-full object-cover"
+      />
+      {shouldPlay ? null : (
+        <button
+          type="button"
+          aria-label={`Play ${attachment.name}`}
+          onClick={() => {
+            setPlaying(true)
+            void videoRef.current?.play()
+          }}
+          className="absolute inset-0 flex items-center justify-center focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]"
+          style={{ background: 'rgb(var(--media-scrim-mid))', color: 'rgb(var(--media-on-scrim))' }}
+        >
+          <Play size={20} strokeWidth={1.75} aria-hidden="true" />
+        </button>
+      )}
+    </span>
+  )
+}
+
+/**
+ * The box an image keeps when it has nothing to show.
+ *
+ * D6: "a broken image is a placeholder with a small icon, never a collapsed
+ * box". The dimensions come from the DECLARED aspect ratio, which is why this
+ * is the same size as the image would have been.
+ */
+export function AttachmentPlaceholder({
+  attachment,
+  state = 'broken',
+  className,
+}: {
+  attachment: ThreadAttachment
+  /**
+   * `loading` while the URL is still being resolved, `broken` once it is known
+   * not to be coming. Same BOX either way — the layout must not depend on which
+   * — but not the same picture: the broken icon is a statement about the file,
+   * and saying it while the answer is still in flight is saying something
+   * untrue about someone's own comment.
+   */
+  state?: 'loading' | 'broken'
+  className?: string | undefined
+}) {
+  return (
+    <span
+      className={cn('flex items-center justify-center overflow-hidden border', className)}
+      style={{
+        aspectRatio: String(attachment.aspectRatio ?? 16 / 10),
+        borderRadius: 'var(--thread-inner-radius, var(--radius-sm))',
+        borderColor: 'rgb(var(--border))',
+        background: 'rgb(var(--surface-inset))',
+        color: 'rgb(var(--text-tertiary))',
+        inlineSize: 'calc(var(--space-12) * 3)',
+        minInlineSize: 'calc(var(--space-12) * 3)',
+      }}
+      aria-label={state === 'loading' ? `Loading ${attachment.name}` : undefined}
+    >
+      {state === 'broken' ? <ImageOff size={14} strokeWidth={1.5} aria-hidden="true" /> : null}
+    </span>
+  )
+}
+
+export interface AttachmentImageProps {
+  readonly attachment: ThreadAttachment
+  readonly onOpen?: ((attachment: ThreadAttachment) => void) | undefined
+  /** Resolves the short-lived URL. Omit and the placeholder renders instead. */
+  readonly resolveUrl?: ((attachmentId: string) => Promise<string | null>) | undefined
+  readonly className?: string | undefined
+}
+
+/**
+ * A posted image with a stable reserved box and a real reduced-motion path for
+ * uploaded GIFs.
+ *
+ * Uploaded GIFs intentionally remain `kind: 'image'`: unlike a Giphy mp4, the
+ * stored file cannot be paused. Its MIME type lets this renderer capture the
+ * loaded image into a canvas once. Under reduced motion the live image is
+ * hidden behind that still; the labelled play button swaps it back only after
+ * an explicit choice.
+ */
+export function AttachmentImage({
+  attachment,
+  onOpen,
+  resolveUrl,
+  className,
+}: AttachmentImageProps) {
+  const reduced = usePrefersReducedMotion()
+  const [broken, setBroken] = useState(false)
+  const [playing, setPlaying] = useState(false)
+  const [capturedSrc, setCapturedSrc] = useState<string | null>(null)
+  const imageRef = useRef<HTMLImageElement>(null)
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const capturedSrcRef = useRef<string | null>(null)
+
+  // Two ways a picture can be absent, and they are NOT the same: `url` on the
+  // attachment (a host that already has one) versus a lazy resolve. Both end at
+  // the same placeholder, which is why the box is declared above either.
+  const resolved = useAttachmentUrl(attachment.id, attachment.url === undefined ? resolveUrl : undefined)
+  const src = attachment.url ?? resolved.url ?? undefined
+  const uploadedGif = attachment.mime?.toLowerCase() === 'image/gif'
+
+  const captureStill = useCallback(
+    (image: HTMLImageElement) => {
+      if (!uploadedGif || src === undefined || capturedSrcRef.current === src) return
+      const canvas = canvasRef.current
+      const width = image.naturalWidth
+      const height = image.naturalHeight
+      if (canvas === null || width <= 0 || height <= 0) return
+      canvas.width = width
+      canvas.height = height
+      const context = canvas.getContext('2d')
+      if (context === null) return
+      context.drawImage(image, 0, 0, width, height)
+      capturedSrcRef.current = src
+      setCapturedSrc(src)
+    },
+    [src, uploadedGif],
+  )
+
+  // The preference can flip while the comment is mounted. Capture normally
+  // happens on load; the complete check also covers a cached image whose load
+  // event preceded the preference change.
+  useEffect(() => {
+    if (!reduced) return
+    setPlaying(false)
+    const image = imageRef.current
+    if (image?.complete === true) captureStill(image)
+  }, [captureStill, reduced])
+
+  const missing = broken || resolved.failed || src === undefined
+  // Still resolving is NOT the same as broken. Both keep the reserved box; only
+  // one of them says the file is gone.
+  const pending = resolved.loading && !broken && !resolved.failed
+  const interactive = onOpen !== undefined && !missing
+  const showStill = uploadedGif && reduced && !playing && !missing
+
+  const body = pending ? null : missing ? (
+    <span
+      className="flex h-full w-full items-center justify-center"
+      style={{ color: 'rgb(var(--text-tertiary))' }}
+    >
+      <ImageOff size={14} strokeWidth={1.5} aria-hidden="true" />
+    </span>
+  ) : (
+    <span className="relative block h-full w-full">
+      <img
+        ref={imageRef}
+        src={src}
+        alt={attachment.name}
+        loading="lazy"
+        className="h-full w-full object-cover"
+        style={{ visibility: showStill ? 'hidden' : 'visible' }}
+        onLoad={(event) => {
+          captureStill(event.currentTarget)
+        }}
+        onError={() => {
+          setBroken(true)
+        }}
+      />
+      {uploadedGif ? (
+        <canvas
+          ref={canvasRef}
+          aria-hidden="true"
+          hidden={!showStill || capturedSrc !== src}
+          className="absolute inset-0 h-full w-full object-cover"
+        />
+      ) : null}
+    </span>
+  )
+
+  return (
+    <span
+      className={cn(
+        'relative block overflow-hidden border',
+        'transition-[border-color] duration-[var(--dur-fast)] ease-[var(--ease-out)] motion-reduce:transition-none',
+        interactive && !showStill && 'hover:border-[rgb(var(--border-strong))]',
+        (interactive || showStill) &&
+          'focus-within:outline-none focus-within:[box-shadow:var(--ring-focus)]',
+        className,
+      )}
+      style={{
+        // Declared up front so the row cannot reflow when the bytes land.
+        aspectRatio: String(attachment.aspectRatio ?? 16 / 10),
+        borderRadius: 'var(--thread-inner-radius, var(--radius-sm))',
+        borderColor: 'rgb(var(--border))',
+        background: 'rgb(var(--surface-inset))',
+        inlineSize: 'calc(var(--space-12) * 3)',
+        minInlineSize: 'calc(var(--space-12) * 3)',
+      }}
+    >
+      {interactive ? (
+        <button
+          type="button"
+          aria-label={`Open ${attachment.name}`}
+          aria-hidden={showStill ? true : undefined}
+          disabled={showStill}
+          onClick={() => {
+            onOpen?.(attachment)
+          }}
+          className="block h-full w-full focus-visible:outline-none"
+        >
+          {body}
+        </button>
+      ) : (
+        body
+      )}
+      {showStill ? (
+        <button
+          type="button"
+          aria-label={`Play ${attachment.name}`}
+          onClick={() => {
+            setPlaying(true)
+          }}
+          className="absolute inset-0 flex items-center justify-center focus-visible:outline-none"
+          style={{ background: 'rgb(var(--media-scrim-mid))', color: 'rgb(var(--media-on-scrim))' }}
+        >
+          <Play size={20} strokeWidth={1.75} aria-hidden="true" />
+        </button>
+      ) : null}
+    </span>
+  )
+}
+
+/* ── the lightbox (D6) ──────────────────────────────────────────────────── */
+
+export interface AttachmentLightboxProps {
+  readonly attachment: ThreadAttachment | null
+  readonly onClose: () => void
+  readonly resolveUrl?: ((attachmentId: string) => Promise<string | null>) | undefined
+}
+
+/**
+ * Full-size view of one attachment.
+ *
+ * Deliberately small: a scrim, the image, a close button, and `Escape`. It is
+ * not a gallery — ADR-151 says "click opens a lightbox", and a carousel with
+ * keyboard paging is a different feature with a different accessibility
+ * surface.
+ *
+ * Focus moves to the close button on open, because otherwise `Escape` is the
+ * only way out for a keyboard and the focus ring is somewhere behind the scrim.
+ */
+export function AttachmentLightbox({ attachment, onClose, resolveUrl }: AttachmentLightboxProps) {
+  const closeRef = useRef<HTMLButtonElement>(null)
+  const id = attachment?.id ?? ''
+  const { url, failed } = useAttachmentUrl(id, attachment === null ? undefined : resolveUrl)
+
+  const surfaceRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (attachment === null) return
+    closeRef.current?.focus()
+
+    /**
+     * `aria-modal="true"` asserts that nothing behind the scrim is reachable.
+     * Without a trap that assertion is false — Tab walks straight out into a
+     * page a sighted user can see is covered and a screen-reader user has been
+     * told is not there. Focus is therefore wrapped rather than merely placed.
+     *
+     * The dialog holds two focusables at most (the close button, and a video's
+     * controls), so a full focus-trap library would be more machinery than the
+     * problem: collect what is focusable at the moment Tab is pressed, and
+     * wrap at the ends.
+     */
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        onClose()
+        return
+      }
+      if (event.key !== 'Tab') return
+      const root = surfaceRef.current
+      if (root === null) return
+      const focusable = Array.from(
+        root.querySelectorAll<HTMLElement>(
+          'a[href], button:not([disabled]), video[controls], [tabindex]:not([tabindex="-1"])',
+        ),
+      )
+      if (focusable.length === 0) {
+        event.preventDefault()
+        return
+      }
+      const first = focusable[0]
+      const last = focusable[focusable.length - 1]
+      const active = document.activeElement
+      if (event.shiftKey && (active === first || !root.contains(active))) {
+        event.preventDefault()
+        last?.focus()
+      } else if (!event.shiftKey && (active === last || !root.contains(active))) {
+        event.preventDefault()
+        first?.focus()
+      }
+    }
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [attachment, onClose])
+
+  if (attachment === null) return null
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={attachment.name}
+      className="fixed inset-0 z-50 flex items-center justify-center p-[var(--space-6)]"
+      style={{ background: 'rgb(var(--media-scrim-strong))' }}
+      onClick={onClose}
+    >
+      <div
+        ref={surfaceRef}
+        className="relative flex max-h-full max-w-full items-center justify-center"
+        onClick={(event) => {
+          event.stopPropagation()
+        }}
+      >
+        {url === null || failed ? (
+          <p style={{ color: 'rgb(var(--media-on-scrim))' }}>
+            {failed ? "This file isn't available." : 'Loading…'}
+          </p>
+        ) : attachment.kind === 'gif' ? (
+          <video
+            src={url}
+            controls
+            loop
+            muted
+            playsInline
+            aria-label={attachment.name}
+            className="max-h-full max-w-full"
+          />
+        ) : (
+          <img src={url} alt={attachment.name} className="max-h-full max-w-full object-contain" />
+        )}
+        <span className="absolute" style={{ insetBlockStart: 0, insetInlineEnd: 0 }}>
+          <button
+            ref={closeRef}
+            type="button"
+            aria-label="Close"
+            className={QUIET_ICON}
+            style={{ ...QUIET_ICON_BOX, color: 'rgb(var(--media-on-scrim))' }}
+            onClick={onClose}
+          >
+            <X size={14} strokeWidth={1.75} aria-hidden="true" />
+          </button>
+        </span>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * The `accept` string for the file input, mirroring the extension allowlist the
+ * server enforces (ADR-151 D3). Exported so a host does not re-type the list
+ * and drift from it.
+ *
+ * It is a filter, never a check: the worker reads the MAGIC NUMBER, so a
+ * renamed file sails past `accept` and is refused there. What this buys is that
+ * the file chooser shows the right files.
+ */
+export const ATTACHMENT_ACCEPT = '.png,.jpg,.jpeg,.webp,.gif,.pdf,.txt,.md,.csv,.json'