@micha.bigler/ui-core-micha 3.14.3 → 4.0.0

package/work-orders/MSG-3b.md

@@ -1,1002 +0,0 @@
-# MSG-3b — close the MSG-3 parity and contract gaps
-
-Status: planned · Tier 2 · Target repo: `ui-core-micha` (main)
-**Binding spec:** `django-core-micha/docs/design/messaging-platform.md`. Extends the landed MSG-3
-(published ucm 2.16.0), same convention as `MSG-2b` / `NOTIF-8b`.
-
----
-
-## Part A — Envelope (Expertenchat, 2026-07-31)
-
-### Goal
-
-Close the gaps a three-way audit found after MSG-3 was marked done: capabilities jg has that ucm never
-got, capabilities ucm renders but that cannot work against the real backend, and one whole area
-(unread lifecycle) that was never specified and therefore never built.
-
-### Why this WO exists — read before scoping anything
-
-MSG-3 shipped with 139/139 tests green, five per-chunk independent reviews and a clean `ui_reviewer`
-pass, and still missed all of the below. Two causes, both structural:
-
-1. **Both sides were tested against themselves.** dcm tested its services; ucm tested its components
-   against a mock whose API surface mirrors *the provider*, not *the contract*. An endpoint with no
-   caller is structurally invisible to that mock. The seam was never executed.
-2. **"No jg feature is lost" was made binding without anyone writing the feature list first**, and the
-   deviation list that was supposed to prove parity was authored by the same party doing the work.
-   It claimed completeness and was wrong.
-
-This WO fixes both: the checklist below **is** the specification, and a contract-conformance test makes
-the seam mechanically checkable.
-
-### Capability checklist — this is the specification
-
-Status as of ucm 2.16.0. `OK` = present, no action. `DEV` = deviation already recorded in
-`docs/messaging-deviations.md` and deliberately kept. `MISSING` / `BROKEN` / `PARTIAL` = in scope.
-`BLOCKED` = needs dcm work first (see Dependencies).
-
-**Every row not marked `OK` or `DEV` must end this WO either implemented or added to the deviation
-list with an explicit rationale. No row may be silently dropped.**
-
-#### Unread lifecycle — never specified in MSG-3, never built
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 1 | Selecting a conversation marks it read (server + local count) | `MessagesPage.jsx:159-162` | **MISSING** |
-| 2 | Opening a conversation auto-marks read | `Thread.jsx:1581` | **MISSING** |
-| 3 | Global unread badge decrements by that conversation's prior count | `MessagingContext.jsx:158-169` | **MISSING** |
-| 4 | Opening a reply thread marks the thread read | `Thread.jsx:1464-1465` | **MISSING** |
-| 5 | Incoming message raises the unread count, but only for non-active conversations | `MessagingContext.jsx:68-71` | **MISSING** |
-
-Row 5 was initially assessed `OK` and corrected by the independent review — the error direction that
-matters, since a false `OK` leaves a real gap unfixed. The truth is worse than rows 1–4 suggested:
-ucm's unread state does not live-update **at all**. `applyFrame`'s `message` case
-(`MessagingProvider.jsx:107-110`) only reconciles `state.messages` and never touches `state.unread`;
-`activeConversationId`/`activeIdRef` (`MessagingProvider.jsx:139-146, 311`) is stored and exposed but
-never read to gate anything. The badge is populated solely by `refreshUnread()` at mount and on
-reconnect (`154-158, 292, 301-304`).
-
-So the unread badge today neither rises on an incoming message nor falls on reading one — it only ever
-reflects whatever the server said at mount. Rows 1–5 are one defect, not five nice-to-haves, and they
-are the first thing this WO should fix.
-
-#### Message actions
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 6 | Action menu on a message (hover icon desktop / long-press mobile / right-click) | `Thread.jsx:855-894` | **MISSING** |
-| 7 | Edit own message — inline field, save, cancel | `Thread.jsx:912-949, 1722-1737` | **MISSING** |
-| 8 | Edit auto-cancels if the message is deleted elsewhere | `Thread.jsx:1618-1621` | **MISSING** |
-| 9 | Delete message — author **or** moderator (`delete_any`) | `Thread.jsx:1744-1768, 2010` | **MISSING** |
-| 10 | Delete confirmation dialog | `Thread.jsx:2438-2450` | **MISSING** |
-| 11 | Deleting a message being replied-to/edited clears that composer state | `Thread.jsx:1755-1761` | **MISSING** |
-| 12 | Copy message text | `Thread.jsx:1770-1777` | **MISSING** |
-| 13 | Reply to a message | `Thread.jsx:2016-2022` | OK |
-| 14 | Quick-reaction presets | `Thread.jsx:635-649` | DEV (5 presets vs 6) |
-| 15 | Full emoji picker for reactions | `Thread.jsx:650-662` | DEV |
-| 16 | No action menu on deleted or poll messages | `Thread.jsx:2074` | follows from 6 |
-
-Note on 7/9: `api.js` already has `patchMessage`/`deleteMessage`; neither has ever had a caller. The
-provider's local `patchMessage` is a same-named cache reducer — do not mistake it for the API call.
-
-#### Direct conversations
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 17 | Launcher to **start** a DM | `MessagesPage.jsx:202-210` | **MISSING** |
-| 18 | Recipient picker over a candidate list | `NewDirectMessageDialog.jsx:22-46,74-83` | **MISSING** |
-| 19 | Picker loading + empty states | `NewDirectMessageDialog.jsx:71-72,82` | **MISSING** |
-| 20 | Start disabled until a person is chosen / while starting | `NewDirectMessageDialog.jsx:96` | **MISSING** |
-| 21 | Policy rejection surfaced as a readable message | `NewDirectMessageDialog.jsx:54-58,85-89` | **MISSING** |
-| 22 | Fullscreen dialog on small viewports | `NewDirectMessageDialog.jsx:68` | **MISSING** |
-
-`createDirectConversation` exists in `api.js` with no caller. **The candidate list is host-supplied**
-(dcm has no user-directory endpoint; jg feeds it from event memberships) — mirror the existing
-`groupLaunchers` prop pattern rather than inventing a discovery call. MSG-2b unblocked exactly this
-case in the backend and it currently has no client.
-
-#### Threading and quoting
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 23 | Replies group under their root | `Thread.jsx:2108-2146` | **BROKEN** — server sends `reply_to_id`, `Thread.jsx:40,62` reads `reply_to`; every server-loaded reply renders as a root |
-| 24 | Quoted preview (sender + snippet) above a reply | `Thread.jsx:571-607` | **MISSING** |
-| 25 | Click the quote to jump to the original | `Thread.jsx:1997-2005` | **MISSING** |
-| 26 | Quote blanks when its source is deleted | `Thread.jsx:149-157` | **MISSING** |
-| 27 | Unread-reply dot on the thread toggle | `Thread.jsx:2128-2137` | **MISSING** |
-| 28 | Lazy thread fetch on expand / collapse | `Thread.jsx:1435-1486` | OK |
-| 29 | Per-thread reply composer | `Thread.jsx:2197-2229` | DEV |
-
-Row 23 is the highest-value single fix in this WO: it makes an already-built feature actually work.
-
-#### Composer
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 30 | Shift+Enter newline, Enter sends | `Thread.jsx:1957-1962` | **PARTIAL** — verify and complete |
-| 31 | Staged-image preview strip with per-file remove | `Thread.jsx:507-541` | **MISSING** — only a "N attachments selected" caption today |
-| 32 | Upload progress indication | `Thread.jsx:2282-2288` | **MISSING** |
-| 33 | Client-side image compression before upload (>2 MB → max 2560 px, JPEG q0.85, silent fallback) | `Thread.jsx:304-350` | **MISSING** |
-| 34 | Emoji insertion into the message body at cursor | `Thread.jsx:1682-1687` | **MISSING** |
-| 35 | Optimistic send, retry on failure, inline error | `Thread.jsx:1856-1931` | OK |
-| 36 | Poll button disabled while images are staged | `Thread.jsx:2340-2347` | minor, follows from 31 |
-| 37 | Draft text survives a conversation switch | `Thread.jsx:1549-1582` | **do NOT reproduce** — this is a jg bug (unsent text leaks into the next conversation). Record as deliberate non-parity. |
-
-#### Conversation list
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 38 | Last-message preview text | `ConversationList.jsx:155` | **BROKEN / BLOCKED** — reads `conversation.last_message?.body`; dcm never sends `last_message` |
-| 39 | Relative timestamp (now / m / h / d, localized) | `ConversationList.jsx:24-36` | **MISSING** |
-| 40 | Active-row highlight | `ConversationList.jsx:113` | **MISSING** |
-| 41 | Unread badge, bold row when unread | `ConversationList.jsx:121,137` | OK |
-| 42 | Distinguish managed *all* vs managed *team* | `ConversationList.jsx:68-71` | **decide** — dcm exposes only `kind: managed`; the distinction lives in `external_key`. Either surface it or record the loss |
-| 43 | Per-kind row icon | `ConversationList.jsx:39-83` | DEV (generic icons) |
-| 44 | Mute / archive | `Thread.jsx:2057-2061` | OK |
-
-#### Timeline
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 45 | Auto-scroll to bottom on a new incoming message | `Thread.jsx:1592-1602` | **MISSING** — verify |
-| 46 | Announcement deep-link button on a message carrying `link_target` | `Thread.jsx:1142-1146` | **MISSING** — ucm accepts `link_target` on compose but never renders it as an action |
-| 47 | Sender name shown in group/managed, suppressed in 1:1 | `Thread.jsx:996-999` | **PARTIAL** — verify; currently unconditional |
-| 48 | Deleted tombstone, `(edited)` marker, timestamp | `Thread.jsx:823-827` | OK |
-
-#### Read receipts
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 49 | Read tick on own messages | `Thread.jsx:361-400` | OK |
-| 50 | Per-recipient read-status detail, gated moderator **and** non-direct | `Thread.jsx:99-101, 2404-2436` | **PARTIAL** — verify tooltip vs jg's popover list; the DM carve-out must hold |
-
-#### Polls — all gated on dcm
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 51 | Render question, options, per-option counts | `Thread.jsx:951-1073` | **BLOCKED** — no `serialize_poll` exists; `PollCard` reads fields no endpoint returns |
-| 52 | Per-option voter names | `Thread.jsx:1050-1059` | **BLOCKED** |
-| 53 | Closed chip, voting disabled once closed | `Thread.jsx:1014-1022` | **BLOCKED** |
-| 54 | Option bounds 2–10 in the composer | `Thread.jsx:80-81` | verify |
-| 55 | Vote / close | `Thread.jsx:1796-1834` | OK (write path works; read path blocked) |
-
-#### Live synchronisation — gated on dcm
-
-| # | Capability | jg reference | Status |
-|---|---|---|---|
-| 56 | Reactions sync live to all viewers | `Thread.jsx:1608-1610` | **BLOCKED** — dcm never emits `reaction`; ucm's handler is dead code |
-| 57 | Poll updates sync live | `Thread.jsx:1633-1639` | **BLOCKED** — dcm never emits `poll_updated` |
-| 58 | Conversation list reorders + preview updates on new/edited/deleted message | `MessagingContext.jsx:54-109` | **BLOCKED** (needs `last_message`) |
-| 59 | New message / edit / delete arrive live | `Thread.jsx:1604-1663` | OK — the only three frames dcm actually emits |
-
-### Dependencies — what must land in dcm first
-
-Rows 38, 51–53, 56–58 cannot be built correctly against dcm 2.36.1. They need a dcm work order
-(proposed `MSG-2c`) delivering: a poll read contract (design gap — `messaging-platform.md` specifies no
-way to read a poll's question, options or results, so the **design must be amended first**), the
-missing realtime frames (`services.py` has three `_publish` call sites for twelve designed frames), and
-`last_message` on the conversation payload. Do not stub, fake or work around these client-side; leave
-them until dcm ships and say so if the sequencing slips.
-
-Everything else in this WO is buildable against dcm 2.36.1 today.
-
-### Chunk plan — the unblocked scope (staged commits, one independent review per chunk)
-
-**In scope now: 39 rows.** Rows marked `OK` or `DEV` need no work; rows 38, 51-53 and 56-58 are
-BLOCKED on `MSG-2c` and stay untouched. Everything else is buildable against dcm 2.36.1 today.
-
-| Chunk | Rows | Content |
-|---|---|---|
-| 1 | 1-5, plus the contract-conformance test | Unread lifecycle end to end: mark-read on select and on open, thread read, global badge decrement, live increment for non-active conversations. Do this first — it is the one outright broken loop, and the conformance test written here guides every chunk after it. |
-| 2 | 23-27 | Threading: fix the `reply_to_id`/`reply_to` mismatch (row 23 makes an already-built feature work), then quoted preview, jump-to-original, quote blanking on delete, unread-reply dot. |
-| 3 | 6-12, 16 | Message action menu (hover / long-press / right-click), edit, delete with confirmation, copy, and the state-clearing behaviour when a message under edit or reply is deleted. |
-| 4 | 17-22 | DM launcher and recipient picker, candidate list host-supplied via a `groupLaunchers`-style prop. |
-| 5 | 30-34, 36, 37 | Composer: Shift+Enter, staged-image previews with per-file remove, upload progress, client-side image compression, emoji insertion at cursor. Row 37 is a **record-only** item — do not reproduce jg's draft leak. |
-| 6 | 39, 40, 42, 45-47, 50, 54, plus the corrected deviation list | List timestamp and active-row highlight, the managed all-vs-team decision, auto-scroll, announcement deep-link rendering, sender-name suppression in DMs, read-status detail, poll option bounds. Close with the deviation list rewritten against this checklist. |
-
-Rows 45, 47, 50, 54 and 42 are marked verify/decide: look at the code before calling them done in
-either direction, and record the outcome in the deviation list rather than leaving it implicit.
-
-**Conformance-test exemptions.** The test from chunk 1 will flag every `api.js` export without a caller.
-After this WO wires `markConversationRead`, `markThreadRead`, `patchMessage`, `deleteMessage` and
-`createDirectConversation`, three remain unwired: `createManagedConversation`,
-`createObjectThreadConversation` and `getMessage`. Each must either get an explicit, reasoned exemption
-entry or be removed — an unexplained allowlist entry reintroduces exactly the blind spot this test
-exists to close. The frame side of the test compares handlers against **the design's frame list**, not
-against what the backend currently emits, so handlers for `reaction` and `poll_updated` are correct and
-must not be deleted while `MSG-2c` is outstanding.
-
-### Required tests to WRITE
-
-- **One test per row above that this WO implements.** A capability with no test is not delivered.
-  The checklist is the coverage contract.
-- **Contract-conformance test (the systemic fix):** fails when a function exported from
-  `src/messaging/api.js` has no caller in the provider or a component, and when a realtime frame type
-  handled by the provider is not in the design's frame list (or vice versa). This test, existing
-  earlier, would have caught rows 7, 9 and 17 (adapter functions with no caller) and rows 56–58 (dead
-  handlers for frames the backend never emits) mechanically. It would **not** have caught row 23 — a
-  payload field-name mismatch is a different failure shape, and needs the threading regression below.
-  Rows 1–5 need their own coverage too: nothing about a missing capability is detectable from export
-  wiring alone.
-- **Unread lifecycle:** opening a conversation clears its badge and reduces the global count by exactly
-  that conversation's prior unread count.
-- **Threading regression:** replies delivered by REST **and** by realtime frame group under their root
-  — i.e. the test must use a server-shaped payload (`reply_to_id`), not a locally-constructed one. The
-  existing tests pass precisely because they use client-shaped objects.
-- **Edit/delete permissions:** author may edit own; moderator may delete any; neither affordance renders
-  without the capability.
-- **DM launcher:** a first-contact DM against a candidate with no prior conversation succeeds
-  (the MSG-2b case); a policy rejection renders a readable message.
-- Existing ucm suites stay green.
-
-### Deliverables beyond code
-
-- **`docs/messaging-deviations.md` corrected.** Its "Final parity confirmation" section currently claims
-  every jg file is represented by an exported surface or a named deviation. That is demonstrably false
-  (edit, delete, DM launcher, mark-read, quoting, copy, image compression). Replace the claim with this
-  WO's checklist and its per-row outcome.
-
-### Non-goals / do-not-touch
-
-dcm changes (they belong to `MSG-2c`); host-app concerns per design §ucm surface — routing, page
-layout, master/detail, scope pickers, deep-link parsing; jg's own code; the jg data migration (MSG-5);
-search; typing; client→server WS; the decomposition achieved in MSG-3 — new capabilities land as new
-collaborators or in the component that owns them, **not** by growing `Thread` back toward a monolith
-(the ~400 LOC soft trigger and the one-harness-entry-per-component rule stay in force).
-
-### Risks
-
-- **The checklist is long and the temptation is to batch.** Rows that get implemented without their
-  test are how this WO reproduces MSG-3's failure at a smaller scale.
-- **Blocked rows invite workarounds.** Faking a poll payload client-side or synthesising a `reaction`
-  frame would hide the dcm gap instead of closing it.
-- **`Thread` regrowth**, per non-goals.
-- Row 42 and rows 30/45/47/50/54 are marked verify/decide — they need a look at the code before being
-  called done either way, not an assumption.
-
-### Reviews
-
-Independent `reviewer` per chunk plus **`ui_reviewer` at WO end**. The WO-end review must check the
-corrected deviation list **against this checklist row by row** — the review that signed off the false
-completeness claim is the one this WO exists to correct.
-
-### Preconditions
-
-dcm 2.36.1 published (met). Rows marked BLOCKED additionally require `MSG-2c`. Approval Gate #1 =
-operator go on this envelope.
-
-### Release
-
-One version bump + npm publish at WO end.
-
-### Execution directive
-
-Implement through `codex exec` in the background — invoked **directly via Bash** (never the
-`debugger`/`*_coder` Agent wrappers) with **both** flags `--skip-git-repo-check` and
-`--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument from a file;
-fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit. One
-invocation per chunk, each chunk left uncommitted for the orchestrator's independent review.
-
-### Mini-handover (pastable)
-
-Orchestrator: implement `work-orders/MSG-3b.md` in `ui-core-micha` (main), chunk by chunk. `git pull`
-first, read the WO + `django-core-micha/docs/design/messaging-platform.md`, then follow
-`orchestrate-codex` (Codex-first per chunk, own review per chunk, `ui_reviewer` at WO end, one publish
-at WO end). Rows marked BLOCKED stay untouched until `MSG-2c` ships.
-
----
-
-## Part B — Implementation map (Orchestrator)
-
-To be filled by the Orchestrator session on `git pull`, within the envelope above.
-
-**This section covers chunk 1 only (rows 1-5 + the contract-conformance test). Later chunks get
-their own Part B addendum before their `codex exec` invocation.**
-
-### Chunk 1 — unread lifecycle + contract-conformance test
-
-**Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root — no
-`backend`/`frontend` subdir in this repo).
-
-**Files to change:**
-
-- `src/messaging/MessagingProvider.jsx` — the only file with real logic changes.
-- `src/messaging/ConversationList.jsx` — one call site addition (row 1).
-- `src/messaging/Thread.jsx` — one call site addition (row 2), plus the existing `toggleReplies`
-  function is where row 4 (thread-open marks thread read) belongs.
-- New test file(s) under `tests/` (see "Required tests" below) — do not touch existing test files
-  except where a shared test helper genuinely needs extending.
-- `docs/messaging-deviations.md` — not touched this chunk (the doc gets rewritten once, at chunk 6,
-  against the full checklist — do not add partial chunk-1 notes here that chunk 6 would have to
-  reconcile).
-
-**Already in place, reuse, do not re-invent:**
-
-- `src/messaging/api.js:40-41` already exports `markThreadRead(rootId, readAt)` and
-  `markConversationRead(conversationId, readAt)`. Neither has a caller anywhere in the codebase today
-  — that's exactly the gap. Do not write new API functions for this; wire the existing ones.
-- `MessagingProvider.jsx`'s `DEFAULT_API` object (line 31-36) and the `api` param destructuring must
-  both be extended to include `markConversationRead`/`markThreadRead`, following the exact pattern
-  every other adapter function already uses (see `archiveConversation`/`setConversationArchived` at
-  lines 186-189 for the closest shape: call the API, then update local state from the result).
-- `cache.unread` shape (from `EMPTY_CACHE` at line 30): `{ unread_count, by_conversation: { [id]: n } }`
-  — this is also dcm's `GET unread-count/` response shape verbatim (design doc line 75).
-
-**Row-by-row implementation guidance (the "how", not literal code — Codex owns the exact shape):**
-
-- **Row 1 (select marks read) + Row 2 (open marks read):** both end up calling the same new provider
-  action, e.g. `markConversationRead(conversationId)`, from two different call sites:
-  `ConversationList`'s existing `onClick={() => onOpen?.(conversation)}` (around line 61) and a new
-  `useEffect` in `Thread` keyed on `conversationId` (mirroring the existing pattern at
-  `MessagingProvider.jsx:292`'s `useEffect(() => { if (active) refresh()... }, [active, refresh])`).
-  Calling it from both places on the same conversation is expected and must be idempotent — the
-  second call should not double-decrement.
-- **Row 3 (badge decrements by that conversation's prior count):** this is the exact bug named in the
-  envelope's "why it's worse than rows 1-4 suggest" section — the fix must decrement
-  `unread.unread_count` by whatever `unread.by_conversation[conversationId]` held *before* this call,
-  not reset the badge to some assumed value and not just zero the per-conversation entry without
-  touching the global total. Guard against going negative (`Math.max(0, ...)`, matching the existing
-  `toggleReaction` clamp pattern at line 253).
-- **Row 4 (opening a reply thread marks the thread read):** wire `markThreadRead` from
-  `Thread.jsx`'s existing `toggleReplies` function (line 48-53) — call it when a thread is being
-  opened (not on collapse). This does not touch `cache.unread` (dcm's design has no described
-  per-thread unread projection distinct from the parent conversation's count) — confirm against the
-  design doc before assuming otherwise; if thread-level unread turns out to need its own state, that's
-  a scope question to flag, not to quietly invent.
-- **Row 5 (incoming message raises unread, only for non-active conversations):** the real defect
-  described in the envelope — `applyFrame`'s `message` case (line 107-110) never touches
-  `state.unread` at all. Fix requires two things: (a) the reducer needs to know which conversation is
-  currently active when a frame arrives — `applyFrame`/`messagingReducer` are pure and don't have
-  access to `activeIdRef`, so the `dispatch({ type: 'frame', frame })` call in the `subscribe(...)`
-  handler (line 293-300) must pass `activeConversationId: activeIdRef.current` alongside the frame,
-  and `applyFrame` must accept and use it; (b) do not increment unread for a message that reconciles
-  the current user's *own* pending optimistic send (i.e., a `reconcileMessage` match found an existing
-  local entry by `client_request_id`) — only a genuinely new incoming message should bump the badge.
-  `reconcileMessage` (line 62-72) already knows whether it matched; the frame handler needs that
-  signal surfaced, not silently discarded.
-
-**Realtime frame contract note (feeds the conformance test):** the design doc (`messaging-platform.md`
-line 155) names twelve frame types. dcm 2.36.1 only ever emits three (`message`, `message_edited`,
-`message_deleted` — row 59). The provider already has handlers for `reaction`/`poll_updated` (dead
-code until `MSG-2c`, intentionally kept, do not delete — see the WO's conformance-test-exemptions
-section) plus `conversation_upsert`/`conversation_archived`/`participant_changed`. Three design frame
-types have **no handler at all** and are legitimately out of this chunk's scope: `attachment_ready`
-(reserved/deliberately unemitted per the design doc itself), `delivered`, `read_state`,
-`thread_read_state` (no row in this WO's checklist requires them — they're a future receipts-sync
-work item, not part of rows 1-5's local-count-based unread lifecycle). The conformance test's
-frame-side check must not fail on these three/four — give them the same kind of explicit, reasoned
-exemption the WO requires for the `api.js` side, not a silent allowlist.
-
-**Contract-conformance test — shape:** a Node-side static-analysis test (vitest still runs in Node;
-`fs`/`path` are available even under the `jsdom` test environment) that:
-1. Reads `src/messaging/api.js`, extracts every `export function <name>(` — that's the full adapter
-   surface.
-2. Reads `src/messaging/MessagingProvider.jsx` and every other `src/messaging/*.jsx` component file,
-   and checks each exported api function name appears as `api.<name>(` somewhere in that source text.
-3. Fails for any export with zero call sites, **except** an explicit, named, reasoned exemption list
-   in the test file itself: after this chunk, `createManagedConversation`, `createObjectThreadConversation`
-   and `getMessage` remain genuinely uncalled (per the WO's "Conformance-test exemptions" section) —
-   list them with a one-line reason each (row 42's managed/team distinction — chunk 6 — may end up
-   calling `createManagedConversation`; if it does, remove it from the exemption list then, don't
-   leave a stale entry).
-4. Separately, reads the frame types handled in `MessagingProvider.jsx` (every `frame.type === '...'`
-   literal) and checks each is one of the twelve types the design doc lists at
-   `django-core-micha/docs/design/messaging-platform.md:155` — hardcode that list in the test (or read
-   the doc file directly with `fs`, either is fine) with the same explicit-exemption treatment for the
-   design-listed types this chunk doesn't handle (`attachment_ready`, `delivered`, `read_state`,
-   `thread_read_state`).
-5. This test is intentionally source-grepping, not behavioral — keep it in its own file
-   (`tests/messagingContractConformance.test.jsx` or similar) so its assertions and exemption lists
-   stay easy to find and update as later chunks close gaps.
-
-**Required tests to WRITE (chunk 1 scope):**
-- The contract-conformance test above.
-- Row 1: selecting a conversation in `ConversationList` calls `markConversationRead` for that
-  conversation's id.
-- Row 2: mounting `Thread` for a conversation calls `markConversationRead` for that conversation.
-- Row 3: a regression test asserting the decrement is by the conversation's *prior* count specifically
-  — seed `cache.unread` with `{ unread_count: 5, by_conversation: { 12: 2, 7: 3 } }`, mark conversation
-  12 read, assert `unread_count === 3` and `by_conversation[12] === 0`, `by_conversation[7]` untouched.
-- Row 4: expanding a reply thread calls `markThreadRead` for that root message id.
-- Row 5: dispatch a `message` frame for a non-active conversation and assert the badge rises by one;
-  dispatch one for the active conversation and assert it does not; dispatch one that reconciles an
-  existing optimistic own-message (matching `client_request_id`) and assert it does not double-count.
-- Existing ucm suites (139 tests) stay green.
-
-**Invariants / do-not-break:**
-- `applyFrame`/`messagingReducer` stay pure functions — no direct API calls or refs inside them; the
-  active-conversation-id must be threaded in as data, not read from a ref inside the reducer.
-- Don't touch the `reply_to`/`reply_to_id` field-name mismatch (row 23) — that's chunk 2, out of scope
-  here even though it's visible in `Thread.jsx` while you're in this file.
-- Don't touch `docs/messaging-deviations.md` this chunk.
-- Keep the ~400 LOC soft trigger in mind for `MessagingProvider.jsx` — it's already the largest file in
-  the package; if this change pushes it meaningfully past that, flag it rather than silently letting it
-  grow (splitting unread-lifecycle logic into a co-located reducer/action-creator module is an
-  acceptable, non-monolith-regrowing way to keep it manageable, if needed).
-
-**Progress contract:** emit `PLAN: …` once, then a single-line `PROGRESS: [n/total] <action>` before
-every relevant action and `… done` on completion, no gap over ~2 minutes, unbuffered stdout, and a
-final `RESULT: DONE` or `RESULT: BLOCKED <reason>` line. Do NOT `git add`/`commit`/`push` — leave the
-diff for the orchestrator's review. WRITE the tests listed above and run only those to confirm they
-execute and pass — do not run the full suite (the orchestrator runs the affected-areas gate after).
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3b.md` chunk 1 (Part B above). Follow `orchestrate-codex`.
-
-### Chunk 2 — threading and quoting (rows 23-27)
-
-**Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root).
-Runs after chunk 1 is committed (its `markConversationRead`/`markThreadRead`/unread-frame plumbing
-already landed; this chunk does not depend on it beyond that both live in the same
-`MessagingProvider.jsx`).
-
-**Files to change:** `src/messaging/Thread.jsx` (root/reply grouping, unread-reply-dot state),
-`src/messaging/MessageBubble.jsx` (quoted preview rendering, click-to-jump, quote blanking on
-delete), new test coverage under `tests/`. Do not touch `docs/messaging-deviations.md` this chunk
-(rewritten once, at chunk 6).
-
-**Row 23 — the confirmed bug, verified against the actual dcm serializer
-(`django-core-micha/src/django_core_micha/messaging/serializers.py:75`):**
-`serialize_message` emits `"reply_to_id": str(message.reply_to_id) if ... else None` — every
-REST-loaded or realtime-delivered message carries `reply_to_id`, never `reply_to`. But
-`MessagingProvider.jsx`'s own optimistic-send builder (`sendMessage`, the `optimistic` object) sets
-`reply_to: payload.reply_to || null` on the **locally-constructed** row — so client-shaped optimistic
-messages use `reply_to` and server-shaped messages use `reply_to_id`. `Thread.jsx:40` (`!message.reply_to`
-for roots) and `:65` (`item.reply_to === message.id` for replies) only ever check the client-shaped
-name, so every server-loaded or WS-delivered reply silently renders as an unattached root — the exact
-defect named in the envelope.
-
-Fix by reading **both** shapes wherever a message's parent is checked (`message.reply_to_id ?? message.reply_to`),
-not by changing what field name the optimistic builder writes (that's `MessagingProvider.jsx`'s
-`sendMessage`, untouched by this chunk — rewriting it risks reopening chunk 1's just-verified
-optimistic-message tests for no benefit, since reading both shapes fixes the bug without it). Two call
-sites in `Thread.jsx` (root filter, reply filter); check `MessageBubble.jsx` and anywhere else in
-`src/messaging/*.jsx` for a bare `.reply_to` read that should also accept `.reply_to_id`.
-
-**Threading regression test (required, named explicitly in the WO):** must use a **server-shaped**
-payload — i.e. construct the test message with `reply_to_id`, not `reply_to` — for both the REST-load
-path (`listMessages`/`api.js` mock returning `{ ..., reply_to_id: rootId }`) and the realtime-frame
-path (`applyFrame`/`dispatch({ type: 'frame', ... })` with a `message` frame payload carrying
-`reply_to_id`). The WO is explicit that the existing tests pass "precisely because they use
-client-shaped objects" — do not let the new test repeat that mistake.
-
-**Row 24 (quoted preview) + Row 25 (click-to-jump) + Row 26 (quote blanks when its source is
-deleted):** `Thread.jsx:66,68` already passes the full root message object as `MessageBubble`'s
-`replyTo` prop when rendering a reply row — so `MessageBubble` already receives everything it needs
-(sender, body, deleted_at) without a new fetch. Extend the existing `{replyTo && <Typography ...>}`
-block (`MessageBubble.jsx:19`) from a sender-only caption into an actual quoted preview: sender name
-plus a short snippet of `replyTo.body`/`replyTo.title` (truncate client-side, no new i18n key needed
-beyond what's already there unless you introduce a distinct "quote" string — reuse
-`MessagingThread.REPLY_TO` if its copy still fits, otherwise add one translation key in all three
-locales, following the existing `messagingTranslations.ts` shape). Row 26: if `replyTo.deleted_at` is
-set, render a blanked/deleted placeholder in the quote instead of `replyTo.body` (soft-deleted messages
-already have `body`/`title` nulled server-side per the design doc — the placeholder text is what needs
-adding, the null-safety is already structurally there). Row 25: make the quote block clickable
-(`onClick`/`role="button"` or a `Button`, matching `MessageBubble`'s existing MUI-only convention —
-see the ui_reviewer's earlier MSG-3 finding on raw `<button>` usage, do not repeat it) and scroll the
-original into view — `Thread.jsx` owns the scroll container (`scrollRef`, line 34); the click handler
-needs a way to reach a specific message's DOM node from `MessageBubble`, e.g. an `id`/`data-message-id`
-attribute on each bubble's root `Paper` plus a callback prop threaded down from `Thread`
-(`onJumpToMessage`) that does `scrollRef.current.querySelector(...)?.scrollIntoView(...)`. Keep this
-addition in `Thread`/`MessageBubble` only — no new top-level exported component needed, this is
-within an existing component's remit, not new decomposition surface.
-
-**Row 27 (unread-reply dot on the thread toggle) — verify data availability before implementing,
-this needs the same care as the WO's explicit verify/decide rows even though it isn't tagged one:**
-investigated against dcm — `MessageThreadReceipt` (`root,user,last_read_at`) exists as a model
-(design doc line 25) and is written by `POST messages/{root_id}/thread/read/`
-(`django-core-micha/src/django_core_micha/messaging/services.py:286-289`), but **no GET endpoint or
-message-serializer field currently exposes a thread's `last_read_at` or an unread-reply flag/count to
-the client** — `serialize_message` (`serializers.py:60-79`) has no such field, and there is no
-"list threads with receipt state" endpoint. A true, cross-device-accurate unread-reply dot is
-therefore not buildable against dcm 2.36.1 — this is a real (if narrower and previously-unnoticed) gap
-of the same shape as the checklist's explicitly-BLOCKED rows, discovered while implementing, not
-assumed in advance.
-
-Do not silently drop it and do not fake server data. Two acceptable outcomes, pick one and record it
-explicitly in this chunk's summary (for chunk 6's deviation-doc rewrite to pick up verbatim):
-(a) build a **session-local, client-only heuristic** — track locally (e.g. a ref/map keyed by root id)
-the last time this provider instance called `markThreadRead` for that root in the current session, and
-show the dot when a root has replies (`reply_count`/loaded replies) newer than that local marker or
-never marked in this session; test it as exactly that — a session-local approximation, not a synced
-read receipt — and the deviation-doc entry must say so plainly (no cross-device/cross-tab accuracy
-until dcm exposes thread receipt state), or (b) skip implementation and record it as a straight
-`BLOCKED`-shaped deviation alongside rows 38/51-53/56-58, with the one-line reason above. Do not spend
-this chunk inventing a third option (e.g. guessing at an undocumented endpoint) — the two above are
-the only ones consistent with "do not stub, fake or work around blocked capabilities."
-
-**Required tests to WRITE (chunk 2 scope):**
-- The threading regression test described above (REST + realtime, both `reply_to_id`-shaped).
-- Quoted preview renders sender + snippet for a reply; blanks correctly when the quoted source is
-  deleted.
-- Click-to-jump scrolls/focuses the original message (test what's observable in jsdom — e.g. that the
-  jump handler is invoked with the right message id / that `scrollIntoView` is called on the right
-  node — not literal pixel scroll position).
-- Row 27's outcome, whichever of (a)/(b) above: if (a), a test proving the session-local dot
-  appears/clears correctly; if (b), no test needed but the decision must still be stated in the
-  chunk's own summary text.
-- Existing ucm suites (chunk-1-inclusive baseline) stay green.
-
-**Invariants / do-not-break:** don't touch chunk 1's unread-lifecycle code paths; don't touch
-`docs/messaging-deviations.md`; keep the fix to reading both `reply_to`/`reply_to_id` shapes rather
-than changing what the optimistic builder writes; no new top-level `src/index.js` export needed for
-this chunk (quoting/jump/dot are internal `Thread`/`MessageBubble` behavior, not new mountable
-surfaces) — if you find yourself wanting one, stop and flag it rather than assuming it's warranted.
-
-**Progress contract / preamble:** identical to chunk 1's (see above) — `PLAN:`/`PROGRESS:`/`RESULT:`
-lines, no git operations, write-and-run-only-the-new-tests, leave the diff uncommitted.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3b.md` chunk 2 (Part B above, after chunk 1 is committed). Follow `orchestrate-codex`.
-
-**Chunk 2 outcome record — row 27 (unread-reply dot), for chunk 6's deviation-doc rewrite to copy
-verbatim:** **BLOCKED, not implemented.** Verified against dcm 2.36.1
-(`django-core-micha/src/django_core_micha/messaging/views.py:302-307`'s `ThreadReadView.post` only
-returns the actor's own just-written `last_read_at` from marking a thread read — there is no GET
-endpoint or `serialize_message`/`serialize_conversation` field (`serializers.py:60-79`) exposing a
-thread's prior receipt state to the client). No truthful unread-reply dot can be rendered — client or
-server — without dcm exposing thread receipt state to read, not just write. This is the same shape of
-gap as the checklist's already-BLOCKED rows (38, 51-53, 56-58), discovered during chunk 2 rather than
-scoped in advance; row 27 should be treated as `BLOCKED` alongside them for any future `MSG-2c`-style
-dcm work, not attempted client-side.
-
-### Chunk 3 — message actions: menu, edit, delete, copy (rows 6-12, 16)
-
-**Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root). Runs
-after chunk 2 is committed.
-
-**Files to change:** `src/messaging/MessageBubble.jsx` (action menu, edit-inline UI, delete
-confirmation), `src/messaging/MessagingProvider.jsx` (wire the already-existing, never-called
-`patchMessage`/`deleteMessage` `api.js` exports — note the provider already has a same-named **local**
-reducer action-creator called `patchMessage` at `MessagingProvider.jsx:247`, which is a cache merge
-helper, not an API call; do not confuse the two or silently overload the name — expose the new API
-call under a distinct name, e.g. `editMessage`/`removeMessage`, and keep the existing local
-`patchMessage` cache helper as-is, used internally the way it already is), `src/messaging/Thread.jsx`
-or `Composer.jsx` (row 11 — clearing reply/edit state when the message under edit or reply is
-deleted), `src/i18n/messagingTranslations.ts` (new copy — menu labels, edit save/cancel, delete
-confirm dialog, copy), new tests under `tests/`.
-
-**Already in place, reuse:** `src/messaging/api.js:35-36` exports `patchMessage(messageId, patch)` and
-`deleteMessage(messageId)`, both unwired (the two of chunk 1's three originally-named conformance-test
-exemptions this chunk closes — remove `patchMessage`/`deleteMessage` from
-`tests/messagingContractConformance.test.js`'s `API_EXEMPTIONS` once wired, per the exemption note
-already left there). dcm's actual permission logic (verified against
-`django-core-micha/src/django_core_micha/messaging/services.py:167-192`): `edit_message` allows the
-sender or anyone with `edit_any` in `moderation_rights(...)`; `soft_delete_message` the same with
-`delete_any`; editing a deleted message raises; deletion is idempotent (already-deleted is a no-op,
-not an error). The PATCH/DELETE endpoints are `django-core-micha`'s
-`MessageDetailView` (`views.py:227-235`) — `PATCH messages/{id}/` (`body`/`title`/`link_target` only,
-per the design doc's REST table) and `DELETE messages/{id}/`.
-
-**A real gap found while scoping this chunk, needs a decision, not silent assumption:** `serialize_message`
-(`django-core-micha/src/django_core_micha/messaging/serializers.py:60-79`) never includes any
-per-viewer capability field (no `can_edit`/`can_delete`/`is_moderator`) — moderator status
-(`edit_any`/`delete_any`) is resolved server-side from each app's `MessagingPolicy` hook and never
-surfaced to the client in any payload this repo has access to. That matches the design doc's stated
-model (`messaging-platform.md`: "Event-manager rights map to moderation/config capabities" — i.e.
-moderator-ness is host-app domain knowledge, not a generic messaging-REST fact), and mirrors the
-existing `allowAnnouncement`/`linkTarget` pattern in `Composer.jsx` (a host-supplied capability prop,
-since the client can't compute it itself).
-
-Implement accordingly: the action menu/edit/delete affordances always render for the message's own
-sender (`message.sender?.id === currentUser?.id`, matching the existing `canShowReadTicks` pattern in
-`Thread.jsx`) **and** additionally for anyone when a new host-supplied capability prop indicates
-moderator rights — thread this down from wherever it naturally enters (e.g. a `canModerateMessages`
-boolean prop on `Thread`, passed through to `MessageBubble`, defaulting to `false`). The server remains
-the actual enforcement (a 403 from a stale/wrong host-side flag must surface as a readable error, not
-crash) — client-side gating is UX-only, not the security boundary. Do not invent a REST call to fetch
-moderator status that doesn't exist; do not skip the moderator case entirely either (that would silently
-drop row 9's "or moderator" half without recording it) — the host-prop approach satisfies both.
-
-**Row 6 (action menu):** MUI `Menu`/`IconButton` triggered by a hover-revealed icon (desktop) — jg
-additionally does long-press (mobile) and right-click; matching the WO's general redesign licence
-(interaction may be redesigned, capability may not be lost), a plain always-visible-on-hover icon plus
-a right-click (`onContextMenu`) handler opening the same menu is sufficient parity; long-press-to-open
-context menu on touch is a reasonable **explicit deviation** to record (desktop hover + right-click
-covers the capability; a dedicated long-press gesture handler is disproportionate for a MUI-only
-component) rather than something to build a custom touch-gesture library for.
-
-**Row 7 (edit) + Row 8 (edit auto-cancels if deleted elsewhere):** inline edit swaps the message body
-for a `TextField` with save/cancel, calling the new `editMessage` provider action; row 8 needs the edit
-state to react to a live `message_deleted` frame or `messagePatched`/cache update marking the message
-deleted while it's being edited — since edit state is local `useState` in `MessageBubble` (or wherever
-you put it), watch `message.deleted_at` becoming true (already reactive via props, since
-`MessageBubble` re-renders on cache changes) and close the edit UI when it does, rather than polling.
-
-**Row 9 (delete, author or moderator) + Row 10 (confirmation dialog) + Row 11 (deleting a
-message under edit/reply clears that composer state):** a `Dialog` confirm before calling the new
-`removeMessage` provider action. Row 11: `Composer.jsx`'s `replyTarget` prop and `Thread.jsx`'s
-`replyingTo`/edit-in-progress state need to clear if the specific message they reference becomes
-deleted — same reactive-to-`deleted_at` approach as row 8, surfaced via the existing
-`onReplyTargetChange` callback `Composer` already accepts.
-
-**Row 12 (copy message text):** `navigator.clipboard.writeText(message.body)` from the action menu; no
-special test-environment handling needed beyond mocking `navigator.clipboard` in the test (a common,
-already-solved jsdom pattern — check whether any existing test in this repo already mocks clipboard
-before adding a new mocking approach).
-
-**Row 16 (no action menu on deleted or poll messages):** the menu trigger must not render when
-`message.deleted_at` is set (already implied — nothing to edit/delete/copy on a tombstone) or when
-`message.kind === 'poll'` (poll messages have their own `PollCard` mutation surface; the WO frames this
-as "follows from 6," i.e. a one-line gate on the menu-render condition, not new logic).
-
-**Required tests to WRITE (chunk 3 scope):**
-- Action menu renders for the sender; renders for a non-sender only when the moderator capability
-  prop is true; does not render for a non-sender/non-moderator; does not render on a deleted or poll
-  message.
-- Edit: author can edit own message (calls the API with the right payload); edit auto-closes when the
-  message's `deleted_at` flips true mid-edit.
-- Delete: confirmation dialog gates the actual delete call; author-delete and moderator-delete (via the
-  capability prop) both succeed; a non-author/non-moderator never gets the affordance in the first
-  place (so there's nothing to test-block client-side beyond "the button isn't there" — don't invent a
-  client-side permission-check unit test for a check the server owns).
-- Row 11: deleting a message currently targeted by `replyTarget`/edit-in-progress clears that state.
-- Copy: clipboard write is called with the message's exact body text.
-- Existing ucm suites (chunks 1-2 inclusive) stay green.
-
-**Deliverable note for chunk 6's deviation-doc rewrite:** record two things explicitly — the
-long-press-vs-hover/right-click interaction deviation (row 6), and the moderator-capability
-host-supplied-prop mechanism (rows 7/9), including that dcm exposes no server-side capability field so
-this is inherently a UX-only gate backed by server enforcement, not a security boundary claim.
-
-**Invariants / do-not-break:** don't touch chunks 1-2's code paths; don't rename/repurpose the existing
-local `patchMessage` cache-merge action creator in `MessagingProvider.jsx` — add new, distinctly-named
-functions for the API calls; keep `docs/messaging-deviations.md` untouched this chunk; keep the
-~400 LOC soft trigger in mind for `MessageBubble.jsx` (already grew in chunk 2) — if the menu/edit/
-delete UI pushes it over, consider a small `MessageActions`-style co-located subcomponent rather than
-letting one file sprawl, but this does not need to become a new top-level exported/index.js surface
-unless it's independently useful outside a bubble (it isn't here).
-
-**Progress contract / preamble:** identical to chunks 1-2's — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no
-git operations, write-and-run-only-the-new-tests, leave the diff uncommitted.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3b.md` chunk 3 (Part B above, after chunk 2 is committed). Follow `orchestrate-codex`.
-
-### Chunk 4 — DM launcher and recipient picker (rows 17-22)
-
-**Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root). Runs
-after chunk 3 is committed.
-
-**Files to change:** a new `src/messaging/DirectMessageLauncher.jsx` (or similar name — a new,
-independently-exported, independently-mountable component per the WO's decomposition rule, mirroring
-`ConversationLaunchers.jsx`'s existing shape rather than folding this into `ConversationList.jsx`),
-`src/messaging/MessagingProvider.jsx` (wire the already-existing, never-called
-`createDirectConversation` export), `src/index.js` (new export), `dev/entries.jsx` (new harness
-entry — binding requirement, not optional), `src/i18n/messagingTranslations.ts`, new tests.
-
-**Already in place, reuse:** `src/messaging/api.js:21` exports `createDirectConversation(payload)` with
-zero callers — the exact chunk-1-named gap. Verified against dcm's actual view
-(`django-core-micha/src/django_core_micha/messaging/views.py:131-141`, `DirectConversationView.post`):
-payload is `{ target_user_id, scope? }` (`scope` optional — omit for the global scope, matching
-`open_direct`'s default in `services.py:79-83`). A policy rejection (e.g. `dm_policy` disallows this
-pair) surfaces as a plain DRF `PermissionDenied` → generic `{"detail": "..."}` 403
-(`views.py:112-113`) — `extractApiErrorMessage` (already in `MessagingProvider.jsx`) already handles
-this shape; no new error-parsing logic needed, just a place to render it.
-
-**The candidate list is host-supplied — do not invent a discovery call.** dcm has no user-directory/
-membership-listing endpoint (verified: no such view exists in `messaging/views.py`); jg feeds its
-picker from event memberships, which is app-specific domain data outside messaging's remit. Mirror the
-existing `groupLaunchers` prop pattern (`ConversationLaunchers.jsx:12`, an array of
-`{id, label, payload}` the host constructs from its own data) — this component takes a
-`candidates` prop (e.g. `[{id, display_name}, ...]`) the host supplies, plus a `scope` value to pass
-through to `createDirectConversation`. Do not add a REST call, a search box hitting a nonexistent
-endpoint, or any client-side "list users" logic.
-
-**Row 17 (launcher to start a DM):** a button/affordance opening the picker dialog — same placement
-convention as `ConversationLaunchers`' existing broadcast/group buttons (this new component can be
-rendered alongside `ConversationLaunchers` by a host, or the host may choose to compose them together
-in its own layout — do not merge the two components into one, they have independent host-supplied
-data shapes and the WO's decomposition rule favors small, single-purpose collaborators).
-
-**Row 18 (recipient picker over the candidate list) + Row 19 (loading + empty states) + Row 20 (start
-disabled until chosen / while starting):** a `Dialog` with a list/autocomplete over the `candidates`
-prop (a plain MUI `List`/`ListItemButton` selection is sufficient — an `Autocomplete` is also fine if
-it fits better, either is within the existing MUI-only convention); "loading" here means the dialog's
-own in-flight `createDirectConversation` call (there's no separate candidate-fetch to show a loading
-state for, since candidates arrive as a prop already resolved by the host — don't invent a loading
-state for data that isn't being fetched by this component); "empty" is an empty `candidates` array.
-The start/confirm button is disabled with nothing selected and while the create call is in flight
-(mirror `Composer.jsx`'s `sending`-gated `disabled` pattern).
-
-**Row 21 (policy rejection surfaced as a readable message):** on a `createDirectConversation` rejection,
-show `extractApiErrorMessage(error)` in an `Alert` inside the dialog (matching every other
-messaging-component error pattern in this repo — `ConversationList.jsx`, `Composer.jsx`, etc.), not a
-silent failure or a generic toast.
-
-**Row 22 (fullscreen dialog on small viewports):** MUI `Dialog`'s `fullScreen` prop driven by
-`useMediaQuery(theme.breakpoints.down('sm'))` — this repo has essentially no existing
-`useMediaQuery`/breakpoint usage (noted as a residual risk in the MSG-3 `ui_reviewer` pass, not a
-blocker), so this is a legitimate, WO-required first use, not scope creep; keep it scoped to this one
-dialog, don't retrofit other components.
-
-**MSG-2b connection (context, not new work):** the WO's envelope notes MSG-2b already unblocked the
-backend first-contact-DM case; this chunk is purely the client wiring — no dcm-side work, no
-verification of MSG-2b itself needed beyond the payload shape already confirmed above.
-
-**Required tests to WRITE (chunk 4 scope):**
-- The DM launcher opens the picker; picker renders the host-supplied candidate list; empty-candidates
-  state renders distinctly.
-- Start is disabled with no selection and while the create call is pending; enabled once a candidate is
-  chosen.
-- Selecting a candidate and confirming calls `createDirectConversation` with the right
-  `target_user_id`/`scope` and opens the resulting conversation (mirror `ConversationLaunchers`'
-  existing `onOpen` callback convention).
-- A policy-rejection response renders a readable error in the dialog, does not close it, and does not
-  crash.
-- `fullScreen` responds to the small-viewport media query (test via mocking `useMediaQuery` or
-  `window.matchMedia`, whichever this repo's existing test setup already supports — check
-  `tests/setup`/`vitest.config` for an existing `matchMedia` mock before adding a new one).
-- Existing ucm suites (chunks 1-3 inclusive) stay green.
-
-**Deliverable note for chunk 6:** this chunk closes the third of chunk 1's three originally-named
-conformance-test exemptions (`createDirectConversation`) — remove it from
-`tests/messagingContractConformance.test.js`'s `API_EXEMPTIONS` once wired (mirror how chunk 3 already
-removed `patchMessage`/`deleteMessage`).
-
-**Invariants / do-not-break:** don't touch chunks 1-3's code paths; keep
-`docs/messaging-deviations.md` untouched this chunk (chunk 6 rewrites it once); this is new
-decomposition surface, so it DOES need a `src/index.js` export and a `dev/entries.jsx` harness entry
-(unlike chunks 2-3's internal-only changes) — don't skip either.
-
-**Progress contract / preamble:** identical to chunks 1-3's — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no
-git operations, write-and-run-only-the-new-tests, leave the diff uncommitted.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3b.md` chunk 4 (Part B above, after chunk 3 is committed). Follow `orchestrate-codex`.
-
-### Chunk 5 — composer: shortcuts, previews, progress, compression, emoji (rows 30-34, 36, 37)
-
-**Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root). Runs
-after chunk 4 is committed.
-
-**Files to change:** `src/messaging/Composer.jsx` (all six rows land here — it's the composer, not new
-decomposition surface, so no new `src/index.js` export or harness entry needed, just editing the
-existing mounted component), `src/i18n/messagingTranslations.ts`, new tests. `docs/messaging-deviations.md`
-untouched this chunk.
-
-**Row 30 (Shift+Enter newline, Enter sends — currently PARTIAL, verify and complete):** the `TextField`
-at `Composer.jsx:94` is a bare `multiline` field with no `onKeyDown` handler at all — Enter currently
-just inserts a newline (native textarea behavior), it does not submit. Add an `onKeyDown` that submits
-on plain `Enter` (calling the existing `submit()` function) and allows the default newline behavior on
-`Shift+Enter` (do not `preventDefault` in that branch). Guard against submitting on IME composition
-(`event.nativeEvent.isComposing`) if you want to be thorough, but the WO's minimum bar is the
-Enter-sends/Shift+Enter-newline split itself.
-
-**Row 31 (staged-image preview strip, per-file remove — currently only a "N attachments selected"
-caption):** replace/extend the `files.length > 0` caption at `Composer.jsx:88` with a horizontal strip
-of thumbnails for image files (`file.type.startsWith('image/')` — use `URL.createObjectURL(file)`,
-matching the existing revoke-on-cleanup pattern already used in `AttachmentList.jsx:15-25` for
-downloaded thumbnails, don't leak object URLs) plus a filename chip for non-image files, each with a
-small remove (×) control that splices that one file out of the `files` state array. Keep the existing
-"N attachments selected" caption as a fallback/count label if useful, or replace it entirely with the
-strip — either is fine, the capability (see what's staged, remove one) is what's required.
-
-**Row 32 (upload progress indication):** `sendAttachments` (`MessagingProvider.jsx`) calls
-`api.uploadAttachments(conversationId, formData, {...})`, which goes through `apiClient` (axios) —
-axios requests support an `onUploadProgress` callback. Check `src/messaging/api.js:32`
-(`uploadAttachments`) and `src/auth/apiClient.jsx` for how request config is threaded through, and
-whether adding an `onUploadProgress` option is a small, additive change to `uploadAttachments`'s
-signature/config (it should be — axios accepts it in the request config object) versus something that
-needs a larger plumbing change. If threading real byte-progress through turns out to require touching
-several layers disproportionately, an indeterminate `CircularProgress`/`LinearProgress` shown for the
-duration of the upload (already-existing `sending` state) is an acceptable minimum — but attempt real
-progress first since the WO names it explicitly and the axios hook is a small addition, not a redesign.
-
-**Row 33 (client-side image compression, >2MB → max 2560px, JPEG q0.85, silent fallback):** verified
-against dcm — the server's own limit is 25MB (`django-core-micha/src/django_core_micha/messaging/attachments.py:23`,
-`MAX_ATTACHMENT_SIZE`), so this compression is purely a client-side bandwidth/upload-time optimization,
-not required for the server to accept anything; a compression failure must silently fall back to the
-original file (never block or corrupt the send) exactly as the WO's row text specifies. Implement via
-canvas: draw the image onto a `<canvas>` scaled down so its longest edge is ≤2560px (skip entirely if
-already smaller), then `canvas.toBlob(callback, 'image/jpeg', 0.85)`, wrap in a promise, and only
-apply this to files over 2MB (`file.size > 2 * 1024 * 1024`) and of an image MIME type — non-image
-files and images ≤2MB pass through unchanged. Wrap the whole compression attempt in try/catch (or a
-promise `.catch`) that resolves to the original `File` on any failure (canvas/image-decode errors,
-unsupported format, etc.) — this is the "silent fallback" the WO requires, not optional robustness.
-
-**Row 34 (emoji insertion into the message body at cursor):** an emoji picker button next to the
-existing attachment/poll/announcement `IconButton`s in `Composer.jsx:89-93`, inserting the picked
-emoji into `body` at the current cursor position (track/read `TextField`'s underlying `<textarea>`
-`selectionStart`/`selectionEnd` via a ref, splice the emoji in, then restore focus/cursor position
-after the emoji). Row 15 (`ReactionBar.jsx:8`, `QUICK_EMOJIS = ['👍', '❤️', '😂', '🎉', '👀']`) already
-established this package's precedent of a small fixed emoji set rather than a full picker library
-(recorded as an accepted `DEV` deviation from jg's `EmojiPickerButton.jsx` in the existing deviation
-doc) — reuse that same small-set convention here for consistency rather than introducing a different
-emoji selection UI or a new picker dependency; a `Menu`/`Popover` of the same or a similarly-sized
-curated emoji set opened from the new button is sufficient. Don't add a new npm dependency for this.
-
-**Row 36 (poll button disabled while images are staged) — trivial, follows from row 31:** once row 31's
-staged-file state exists, add `disabled={pollOpen indicator || files.some(f => f.type.startsWith('image/'))}`-style
-gating to the existing poll `IconButton` (`Composer.jsx:92`) — a one-line condition addition, not new
-logic; verify against the WO's exact framing (jg disables poll-composing while images are staged,
-presumably because a message can't carry both a poll and attachments in one send) before wiring it,
-i.e. confirm this is really about mutual exclusivity of poll vs. attachment in a single send (check
-`send_message`/`create_conversation` service logic in dcm if the reasoning isn't obvious from the
-existing chat-send code path) rather than assume the reason without checking.
-
-**Row 37 (draft text does NOT survive a conversation switch — explicit non-goal, jg bug, do NOT
-reproduce):** confirm current behavior already satisfies this (a fresh `Composer` mount per
-`conversationId` via React's key/prop change naturally resets local `useState` — check whether the
-host's typical usage pattern, e.g. a `key={conversationId}` on `Composer` or equivalent remount, is
-already implied elsewhere in this codebase, or whether `Composer`'s `body`/`files` state could
-persist across a `conversationId` prop change without a remount). If `Composer` is typically kept
-mounted while `conversationId` changes (rather than remounted), add an effect resetting `body`/`files`
-when `conversationId` changes, so unsent text never leaks into the next conversation — this is a
-one-line fix if needed, not a redesign. No test is required if you confirm the existing remount pattern
-already prevents this (document which is true in your chunk summary), but if you add the reset effect,
-test it.
-
-**Required tests to WRITE (chunk 5 scope):**
-- Row 30: Enter submits (with body present); Shift+Enter inserts a newline without submitting.
-- Row 31: staged images render a preview strip; removing one via its control drops it from the
-  eventual submitted `FormData`/`files[]` without affecting the others.
-- Row 32: an in-flight upload shows progress (whichever form — byte-percentage or indeterminate,
-  matching whichever you implemented); test what's actually observable (e.g. an `onUploadProgress`
-  callback firing and updating visible state, or the indeterminate indicator rendering during
-  `sending`).
-- Row 33: a file over 2MB is compressed (mock canvas/`toBlob` — check whether this repo's existing test
-  setup already provides a canvas/image mock before adding a new one) before being included in the
-  upload's `FormData`; a compression failure still results in the original file being sent, not a
-  blocked/broken send.
-- Row 34: picking an emoji inserts it into `body` at the cursor position (not just appended to the
-  end — construct a test with a non-trivial cursor position to actually prove insertion-at-cursor, not
-  insertion-at-end, which would pass a weaker test trivially).
-- Row 36: poll button is disabled once an image is staged, enabled again once removed.
-- Row 37: either a passing test proving draft state doesn't leak across a `conversationId` change, or
-  (if you conclude the existing remount pattern already prevents it) no new test, but state that
-  conclusion explicitly in your chunk summary.
-- Existing ucm suites (chunks 1-4 inclusive) stay green.
-
-**Invariants / do-not-break:** don't touch chunks 1-4's code paths; keep `Composer.jsx` component
-cohesive — if this chunk pushes it meaningfully past the ~400 LOC soft trigger, a small co-located
-helper module (e.g. `composerImageCompression.js` for the canvas logic, kept internal/unexported) is an
-acceptable way to manage size without violating the no-new-top-level-surface rule (it's not a new
-mountable component, just an extracted pure function); flag rather than silently letting one file
-sprawl if it happens anyway. No new npm dependency for the emoji picker (row 34) or anything else in
-this chunk — everything here is buildable with existing MUI + native browser APIs (canvas, axios
-progress hooks).
-
-**Progress contract / preamble:** identical to chunks 1-4's — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no
-git operations, write-and-run-only-the-new-tests, leave the diff uncommitted.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3b.md` chunk 5 (Part B above, after chunk 4 is committed). Follow `orchestrate-codex`.
-
-### Chunk 6 — list polish, timeline polish, receipts, poll bounds, and the deviation-doc rewrite (rows 39, 40, 42, 45-47, 50, 54)
-
-**Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root). Runs
-after chunk 5 is committed. This is the WO's last content chunk — after it lands, the WO-end
-`ui_reviewer` pass and the version-bump/publish are the only remaining steps.
-
-**Files to change:** `src/messaging/ConversationList.jsx` (rows 39, 40, 42), `src/messaging/Thread.jsx`
-+ `src/messaging/MessageBubble.jsx` (rows 45, 46, 47), `src/messaging/ReadTicks.jsx` (row 50),
-`src/messaging/Composer.jsx` (row 54), `src/i18n/messagingTranslations.ts`, new tests, and finally
-**`docs/messaging-deviations.md` — rewritten once, at the end of this chunk**, against the WO's full
-checklist (this is the deliverable the WO's envelope calls out as correcting MSG-3's false completeness
-claim).
-
-**Row 39 (relative timestamp, localized) + Row 40 (active-row highlight):** `ConversationList.jsx`
-currently renders no timestamp at all (`ListItemText`'s `secondary` is the last-message preview only).
-Add a relative-time label ("now"/"5m"/"3h"/"2d") next to or under the title, computed from
-`conversation.last_message_at`, using the browser-native `Intl.RelativeTimeFormat` (locale-aware,
-zero new dependency — this repo has no existing relative-time helper to reuse, don't add a date
-library for this). For row 40: `ListItemButton` already sets `selected={conversation.id ===
-activeConversationId}` (`ConversationList.jsx:61`) — MUI's `selected` prop does apply a background
-highlight by default, so verify in the rendered/test DOM whether this is actually visually
-distinguishable (check the applied `Mui-selected` class is present) before assuming it needs new work;
-if the existing `selected` wiring already produces a real highlight, this row may already be `OK` and
-should be recorded as such rather than reimplemented — don't add redundant styling on top of something
-that already works, verify first.
-
-**Row 42 (managed *all* vs. managed *team* — decide, not build):** verified against dcm — the
-`Conversation` model has `external_key` (`django-core-micha/src/django_core_micha/messaging/models.py:86`),
-which is where jg's all-vs-team distinction lives, but `serialize_conversation_core`
-(`serializers.py:106-113`) never includes `external_key` in any REST response. This field genuinely
-cannot be surfaced client-side without a dcm change (out of this WO's scope — dcm changes belong to a
-future `MSG-2c`-style order). **Decision: record as a deviation, do not attempt to guess the
-distinction from `title` text or any other client-visible field.** This is a `decide` row, and the
-decision is: not buildable against dcm 2.36.1, closest in shape to the already-BLOCKED rows.
-
-**Row 45 (auto-scroll to bottom on a new incoming message — verify, currently missing):** `Thread.jsx`'s
-scroll container (`scrollRef`, line 34) has no effect reacting to new messages arriving in `roots`. Add
-one: on a new message appended to the active conversation, scroll to bottom — but gate it on the user
-already being near the bottom before the new message arrived (e.g. `scrollHeight - scrollTop -
-clientHeight` under some small threshold), so a user scrolled up reading history doesn't get yanked to
-the bottom by an unrelated new message. This nuance isn't explicit in the WO's one-line row text but is
-standard chat-UI behavior and avoids a real usability regression — implement it, and note the
-near-bottom gating as a considered addition in your chunk summary (not silently assumed).
-
-**Row 46 (announcement deep-link button, `link_target` accepted on compose but never rendered as an
-action):** `MessageBubble.jsx` has no rendering for `message.link_target` at all currently. Add a
-button/link shown when `!deleted && message.kind === 'announcement' && message.link_target` — but the
-link's *destination handling* is host-app routing (same reasoning already established for
-`resolveLink` on `NotificationBell` elsewhere in this package), so this needs a host-supplied callback
-prop threaded `Thread` → `MessageBubble` (e.g. `onAnnouncementLink(linkTarget)`), not a hardcoded
-`window.location`/`<a href>` navigation. Without a host callback supplied, render nothing extra (no
-broken/no-op link) rather than a non-functional button.
-
-**Row 47 (sender name shown in group/managed, suppressed in 1:1 — PARTIAL, currently unconditional):**
-`MessageBubble.jsx:31` (`senderName(message)`) renders unconditionally. `Thread.jsx` already has
-`conversation` in scope (line 40) but doesn't pass it to `MessageBubble` — thread it through (a new
-`conversation` prop on `MessageBubble`, alongside the existing `replyTo`/`onReply`/etc.) and suppress
-the sender-name line when `conversation?.kind === 'direct'` (matches jg's 1:1 convention: in a two-
-person DM, whose message it is is already visually implied by side/alignment in most chat UIs, or at
-minimum isn't worth repeating every bubble — since this package doesn't currently do left/right
-alignment by sender, keep the bubble layout as-is and just suppress the redundant name text for DMs,
-which is the capability the row asks for, not a new alignment scheme).
-
-**Row 50 (per-recipient read-status detail, gated moderator + non-direct — PARTIAL, verify tooltip vs.
-jg's popover list):** `ReadTicks.jsx` already correctly gates the DM carve-out (`conversation?.kind ===
-'direct' ? null : status.recipient_detail`, line 20) — **this part is already correct, do not touch
-the gating logic.** What's flagged PARTIAL is the *presentation*: a hover-only MUI `Tooltip` (line 22)
-is not touch/keyboard accessible the way jg's popover list is — a moderator on a touch device cannot
-see who read a message at all today. Convert to a click-to-open `Popover`/`Menu` showing the recipient
-names as a proper list (anchored on the existing `Typography` trigger), keeping the same content
-(`detailText`/aggregate `label`) — this is an interaction-fidelity fix, not new data plumbing.
-
-**Row 54 (poll option bounds 2-10 in the composer — verify):** dcm's server-side validation
-(`django-core-micha/src/django_core_micha/messaging/serializers.py:27`,
-`PollInputSerializer.options`) only enforces `min_length=2`, no maximum — the "2-10" bound is a
-client-only UX guard (jg's convention), not a server contract. `Composer.jsx`'s poll dialog
-(`pollOptions` state, `setPollOptions((current) => [...current, ''])`) currently allows unlimited
-options. Cap at 10: disable/hide the "Add option" button once `pollOptions.length >= 10`, and keep the
-existing minimum-2 validation as-is (already correct).
-
-**Deliverable: `docs/messaging-deviations.md` rewritten once, at the end of this chunk.** The WO's
-envelope is explicit that the doc's current "Final parity confirmation" section overclaims completeness
-and must be replaced with an honest, row-by-row account against this WO's full checklist (all 59 rows,
-not just chunks 1-6's 39 unblocked ones) — every row gets one of: `OK` (unchanged from before this WO,
-or newly landed), `DEV` (deliberate deviation with rationale — carry forward the existing ones from
-chunks 2/3/4/5 plus this chunk's row 6/42/47/50 interaction deviations), or `BLOCKED` (rows 38, 51-53,
-56-58, plus row 27's now-recorded BLOCKED outcome from chunk 2, plus row 42's newly-recorded BLOCKED
-outcome from this chunk). This is the single most important deliverable of the whole WO per its own
-"why this WO exists" framing — do not compress it into a vague summary; go row by row, referencing the
-row number from the checklist in `work-orders/MSG-3b.md` Part A.
-
-**Correction from chunk 5's independent review, apply when writing row 36's deviation-doc entry:**
-chunk 5's guidance above (row 36 section) speculated the poll-disabled-while-images-staged gate exists
-"presumably because a message can't carry both a poll and attachments in one send." That premise is
-**not** true — verified against dcm's `services.py`: `send_message` and `create_poll` are always two
-structurally separate `Message` rows created via two separate API calls; there is no combined send that
-could carry both, so there is no server-side mutual-exclusivity constraint. The gate is real and kept
-(it's harmless UX convenience matching jg), but its deviation-doc rationale must say **"UI convenience,
-matching jg's composer behavior — no dcm-side constraint requires it,"** not the unverified premise
-above. Do not restate the wrong reasoning as fact — this is exactly the failure mode ("claimed
-completeness/reasoning without checking the seam") this WO exists to correct.
-
-**Required tests to WRITE (chunk 6 scope):**
-- Row 39: relative-timestamp rendering for a few representative ages (just-now, minutes, hours, days).
-- Row 40: only if genuinely fixing something (see the verify-first note above) — otherwise state the
-  `already OK` conclusion in your summary instead of a padding test.
-- Row 45: a new message in the active conversation while scrolled near the bottom triggers a scroll-to-
-  bottom call; while scrolled away from the bottom, it does not (assert the scroll call, not real
-  jsdom layout, which has no real scroll metrics — mock `scrollHeight`/`scrollTop`/`clientHeight` on
-  the container the way this environment's other scroll-adjacent tests already do, if any precedent
-  exists, otherwise establish a minimal one here).
-- Row 46: the announcement link button renders only when a host callback is supplied and
-  `link_target` is present; clicking it calls the host callback with the right value; absent either
-  precondition, nothing extra renders.
-- Row 47: sender name renders in a group conversation, is suppressed in a direct conversation.
-- Row 50: the recipient-detail control is click-openable (not hover-only) and still respects the DM
-  carve-out (no detail control rendered/openable at all for a direct conversation, even for a
-  moderator) — this is a regression test for existing correct behavior, not just new UI.
-- Row 54: the "add option" control disables/hides at 10 options; existing 2-minimum validation stays
-  covered by its current test (don't duplicate, just don't break it).
-- Existing ucm suites (chunks 1-5 inclusive) stay green.
-
-**Invariants / do-not-break:** don't touch chunks 1-5's code paths beyond the specific additive props
-described above (`conversation` on `MessageBubble`, `onAnnouncementLink` threading); don't invent a
-managed-all-vs-team distinction client-side (row 42's decision is BLOCKED/deviation, not a guess); keep
-the ~400 LOC soft trigger in mind across `Thread.jsx`/`MessageBubble.jsx`/`ConversationList.jsx` — this
-chunk touches all three, watch for any of them growing past the trigger and flag rather than silently
-letting it happen.
-
-**Progress contract / preamble:** identical to chunks 1-5's — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no
-git operations, write-and-run-only-the-new-tests, leave the diff uncommitted.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3b.md` chunk 6 (Part B above, after chunk 5 is committed) — the WO's last content
-chunk. Follow `orchestrate-codex`; after this chunk's independent review and commit, run the WO-end
-`ui_reviewer` pass (checking the rewritten deviation doc against the full checklist row by row per the
-WO's "Reviews" section), then one version bump + npm publish.