# 🤖 Media, Links & Docs — design

A per-thread view that makes everything ever *shared* in a chat — pictures,
links, files — quick to find, for any group or DM. The WhatsApp/Telegram
"Media, Links, Docs" mental model, built within lchat's constraint that the
server only ever holds opaque ciphertext.

Status: approved design (Paul, 2026-08-05). Implementation plan to follow.

## The constraint that shapes everything

The server has **zero** metadata distinguishing a message with attachments or
links — message rows are `{id, created_at, blob}` and the blob is AES-GCM
ciphertext (`db.go` `Message`). `blobs.thread_id` exists only for GC and can't
be joined back to a message. So this feature is **fully client-side over
decrypted payloads**, and requires **no server changes at all**:

- **Web** builds on `web/static/store.js` — the IndexedDB ciphertext cache:
  `allMessages(tid)` for the cached sweep, `runBackfill` for the resumable
  deep-history walk (already used by search), decrypting in memory with the
  thread key exactly as `searchui.js` does.
- **Native** is cheaper still: `MessageStore.swift` already persists decrypted
  `MessagePayload` rows in protected SQLite, so the tabs are straight queries.

The extracted index lives **in memory only on web** (like `SearchIndex`) —
`store.js` deliberately keeps only ciphertext at rest, and a plaintext media
index in IndexedDB would break that. The sealed-index upgrade path
(`docs/sealed-search-index.md`) covers this feature too, later.

## Goals

- From any thread (group or DM), open a view listing all shared **media**
  (images, GIFs, videos), **links**, and **docs** (other files), newest first.
- Instant on reopen; complete after a one-time per-thread history walk.
- Jump from any item back to its message in the chat.
- Swipe/arrow between photos in the lightbox from the media grid.
- Ships on web and native (iOS polished first, Mac in the same native change).

## Non-goals (named follow-ups)

- **Pinned messages.** Doesn't exist as a feature yet ("pin" today pins the
  *thread* in the sidebar). Building it means a new folded event type
  (`pin`/`unpin` riding encrypted messages like reactions), event-vector
  entries on both platforms, message-menu UI, group-permission decisions, and
  probably a pinned banner — its own spec. The overlay's **tab bar is
  data-driven** precisely so a Pinned tab slots in with near-zero rework once
  the event exists; the deferral costs nothing.
- **Feed lightbox → thread collection.** Wiring the chat feed's photo taps
  into the same thread-wide swipeable collection is a stated follow-up; this
  change only makes the media grid use collection swipe.
- **Persisted (sealed) extraction index** on web — follows the sealed search
  index work.
- Cross-thread ("all media everywhere") views, storage-management/"largest
  files" views, media search.

## UX (web)

### Entry point

A new **"Media, links and docs"** item in the thread kebab, between Members
and Apps — a `<button class="menu-item" id="thread-media">` in
`web/pages/index.html`, handler in `shell.js`, implementation exported from
`groupactions.js` (which owns the kebab's whole surface). **Not group-gated**:
it renders for DMs and groups alike (so it must not join the group-only id
loop in `paintThreadHeader`). Hidden for app-takeover threads that have no
chat feed.

### The overlay

A **full-pane overlay** bounded to the feed box, patterned on the
reply-thread overlay in `apps/chat.js` (`threadSid`, z-index 30): the chat
stays mounted beneath; closing returns to it with focus restored to the kebab.
Header: back control, thread name, and a segmented control **Media | Links |
Docs**, each segment showing its count (pluralised + locale-formatted per the
counts convention). Tabs are **data** — an ordered array of
`{id, label, render}` — not hardcoded markup, so future tabs (Pinned) are
additive.

Accessibility per the WCAG 2.2 AA bar: the overlay is keyboard-operable
(tab order into the segmented control and grid/list, Escape closes, focus
managed on open/close), tiles ≥24px targets with labelled controls, works in
light and dark, and any progress animation respects `prefers-reduced-motion`.
All untrusted strings (filenames, link URLs, unfurl titles) rendered via
`textContent` — never `innerHTML`.

### Media tab

- 3–4 column grid (responsive), grouped under **month headers**
  ("August 2026"), newest month first.
- Tiles render **instantly from payload metadata** before any blob is
  fetched: aspect ratio from `w`/`h`, BlurHash placeholder from `bh`. Blobs
  decrypt lazily via an `IntersectionObserver` — only tiles scrolled into
  view call `host.loadBlob` (memoized in `blobURLs`). Videos use their
  smaller **poster** blob for the tile plus a duration badge (`dur`); GIFs
  show their still.
- Tap → lightbox with **collection swipe** (below). 🤖 v1 reality: videos
  open their **poster still** in the lightbox, same as photos — there's no
  in-grid video player yet. Playing the video rides **"Show in chat"** (jump
  to the source message, which has the existing feed player). An in-grid
  player that plays inline from the tile is a named follow-up, not v1 scope.

### Links tab

- One row **per link occurrence**: all links in a message via
  `tokenizeText(text)` `href` tokens (not just `firstLink`), newest first.
  The same URL posted twice is two rows.
- Row: lazily-fetched unfurl card (`host.unfurl`, memoized; graceful
  plain-URL row when unfurl fails), the URL, sender name, date.
- Tap opens the link (same `target=_blank rel=noopener` discipline as the
  feed).

### Docs tab

- Non-image/video attachments: file-type icon, name, size
  (`formatBytes`), sender, date; newest first.
- Tap downloads/previews exactly as `buildFileCard` does in the feed.

### Show in chat

Every item (long-press on touch, hover kebab on desktop — matching the feed's
message-action split) offers **"Show in chat"**: closes the overlay and
reuses search's `jumpToMessage` to page back to and flash the source message.

### Completeness: auto-backfill on open

Opening the overlay shows cached results **instantly**, then auto-runs the
per-thread `runBackfill` in the background, streaming each older page through
the extractor into the tabs. A progress line (inline, occupying layout — no
floating toast) shows the walk ("Loading earlier messages… March 2024") with
a **Stop** control. The walk is resumable and its marks are **shared with
search** — either feature completing the walk completes it for both; once
marked complete, opens are instant and total. A thread mid-walk that's closed
resumes from its mark next open.

## Data flow (web)

New pure module `web/static/threadmedia.js` (`media.js` is taken by the
image-processing helpers), Node-testable like `format.js`:

- `extractEntries(data, meta)` — decrypted payload + `{id, ts}` →
  `{media: [], links: [], docs: []}` classified entries. Rules:
  - skip app events (`data.type`) and tombstones;
  - attachments: `type` prefix `image/` (incl. GIFs) or `video/` → media,
    everything else → docs;
  - links: every `href` token from `tokenizeText(data.text)`;
  - entries carry `{sid, ts, uid, name}` plus the attachment/link fields
    needed to render without re-decrypting the row.
- `class ThreadMediaIndex` — in-memory per-thread accumulator mirroring
  `SearchIndex`'s shape: `ensureThread(tid, rows)` with an injected
  `decryptRow`, a `seen` set for idempotent re-folds, `addPage(rows)` for
  backfill streaming, month-bucketed sorted output per tab. Invalidation:
  edits re-extract the row (links can change); deletes drop its entries;
  moderation-hidden senders (muted/blocked, via `moderation.js`) are
  filtered at query time so un-muting doesn't need a re-scan.

The overlay UI itself lives in a new `web/static/mediaview.js` (keeping
`groupactions.js` from growing another whole surface), registered through the
existing verbs/imports seams; `groupactions.js` exports the kebab entry that
opens it.

## Lightbox collection swipe

`lightbox.js`'s `openLightbox` gains an optional collection form:
`openLightbox(url, source, { items, index })` — `items` an array of
`{url | load(), source?}`. Behaviour:

- Horizontal **swipe** on touch, **←/→** on desktop, moving through the
  collection; the FLIP fly-in/out still anchors to the tapped tile, and
  fly-out targets the *current* item's tile when it's in view.
- Neighbours preload lazily (decrypt-on-approach, not the whole thread).
- Single-URL callers are untouched — existing feed/avatar behaviour is
  byte-for-byte the same path.

## Native (iOS + Mac, one PR)

- **Entry**: a "Media, Links & Docs" item in the thread menu
  (`NativeChatScreen.swift`'s `Menu`), opening a screen (sheet on iOS,
  window-pushed view on Mac) with the same three segmented tabs.
- **Data**: queries over `MessageStore`'s decrypted payload rows — decode,
  filter with the existing `isImage`/`isVideo` helpers and a link tokenizer
  matching `format.js` semantics (shared in LChatCore so iOS and Mac can't
  drift). Month grouping and ordering match web.
- **Completeness**: `HistoryBackfill` auto-runs on open with the same
  progress + stop affordance, sharing its existing marks.
- **Viewing**: the media grid feeds QuickLook's multi-item data source —
  collection swipe is native behaviour there; files reuse `FilePreview`,
  videos the existing player. Blur-hash placeholders via `Blurhash.swift`;
  tiles load through `BlobImageLoader`/`BlobDataCache`.
- Accessibility: labels/traits on tiles, survives largest Dynamic Type.

Logic that both platforms must agree on (classification rules, link
extraction) is specified by the extractor's Node tests + a matching Swift
test fixture — same discipline as the event vectors, but no vector-file
change: **this feature adds no event types and never touches the event
contract.**

## Edge cases

- **Deleted messages**: tombstones excluded; a delete while the overlay is
  open drops the entries live (same fold pipeline).
- **Edits**: re-extract; a link edited out disappears from Links.
- **Moderation**: muted/blocked senders' items hidden, live via
  `onModerationChange`.
- **Sparse threads**: a thread with three photos in 10k messages still walks
  the full history once — the progress line makes the wait legible, Stop
  bails out, and the resumable mark means it never repeats.
- **Huge threads**: `allMessages` caps at 50k rows; the media view inherits
  that cap and the store's documented above-watermark gap. Acceptable for
  v1; noted for the sealed-index follow-up.
- **Ephemeral/relay-only frames** are never stored, so never appear.
- **Memory**: grid blob URLs are the same memoized `blobURLs` the feed uses;
  the IntersectionObserver keeps decryption proportional to what's viewed.

## Testing

- `test/threadmedia.test.mjs` — extractor unit tests: classification
  (image/GIF/video/file), multi-link extraction, app-event/tombstone
  skipping, edit/delete invalidation, month bucketing, idempotent re-folds.
- Lightbox collection logic: pure index/navigation helpers split out and
  Node-tested; gestures verified by hand.
- Swift: fixture tests asserting classification + link extraction parity
  with the extractor fixtures.
- `npm test` + `go test ./...` stay green untouched (no server or event
  changes). Manual verification per stored preference: live canary
  (`ops canary create`), though a canary exercises only the web side.

## Shipping

PR series (small, each stands alone):

1. **web: extractor + overlay** — `threadmedia.js`, `mediaview.js`, kebab
   entry, auto-backfill, tests. Changelog entry rides this PR.
2. **web: lightbox collection swipe** — `lightbox.js` collection support,
   media grid adopts it. (Until this lands, PR 1's grid taps open the
   single-image lightbox — the feed's exact current behaviour.)
3. **native: iOS + Mac tabs** — shared LChatCore logic, both UIs. Changelog
   entry held until the release is minted, per convention.