@micha.bigler/ui-core-micha 2.14.0 → 2.16.0

package/work-orders/DX-1.md

@@ -0,0 +1,166 @@
+# DX-1 — minimal Vite dev harness for ucm components
+
+Status: planned · Tier 1 (dev-only tooling; **adds devDependencies → approval-gated**) · Target repo: `ui-core-micha` (main)
+
+---
+
+## Part A — Envelope (Expertenchat, 2026-07-31)
+
+### Goal
+
+Give `ui-core-micha` a way to **render** its components during development. Today `package.json`
+exposes only `build` (tsc) and `test` (vitest): there is no Storybook, no demo app, no dev page. Every
+shipped surface — auth, onboarding, notifications, charts — has only ever been verified in jsdom or
+after a consuming app pinned it.
+
+Immediate driver: MSG-3 is ~3700 LOC of new UI (jg's parity target: `Thread.jsx` alone is 2470 LOC)
+that no app mounts until MSG-5, and the operator granted a redesign licence, which is only iterable
+if the result can be looked at. But the gap is not messaging-specific and the harness is not
+messaging-specific.
+
+### Expected outcome
+
+- A `pnpm dev` (or equivalent) script starting a Vite dev server that mounts ucm components in a
+  browser, with the repo's MUI theme, `react-i18next` and router context wired the way a host app
+  wires them.
+- A small set of harness entries covering the existing surfaces well enough to prove the harness is
+  real: at minimum one notifications surface and one charts surface. Adding an entry for a new
+  component must be a few lines, not a framework.
+- **A single component must be mountable standalone**, not only a whole assembled surface. MSG-3
+  relies on this: it requires one harness entry per named component as its decomposition forcing
+  function, so the harness must not assume an entry equals a full page.
+- A **mock transport layer** the entries drive: fixture data plus an injectable API/realtime adapter,
+  so a surface can be exercised without a backend. Where a component takes its data through a
+  provider, the harness supplies a mock provider rather than patching the component.
+- Light/dark theme and viewport switching, since responsive and dark-mode correctness is exactly what
+  jsdom cannot show.
+- Harness code lives outside the published package: not exported from `src/index.js`, excluded from
+  `tsconfig.build.json`, and adding **zero** runtime dependencies. `dist/` must be byte-identical in
+  content to a build from before this WO.
+- `README` (or `CONTRIBUTING`) gains a short section on running the harness and adding an entry.
+
+### Non-goals / do-not-touch
+
+Storybook (deliberately not chosen — a dev page is a fraction of the config surface and this repo has
+no story-writing habit to build on; revisit only if the harness proves insufficient); visual
+regression / screenshot testing; publishing the harness; any change to component source, exports, or
+public API; any change to the existing vitest setup; CI wiring (the harness is a local dev tool, not
+a gate).
+
+### Required tests to WRITE
+
+This is dev tooling, so the meaningful assertions are about **not** affecting the product:
+
+- The published barrel (`src/index.js`) is unchanged — the existing exports regression test
+  (`tests/notificationsExports.test.js` pattern) must still pass, and no harness module is reachable
+  from it.
+- A build (`tsc -p tsconfig.build.json`) succeeds and emits no harness files into `dist/`.
+- `package.json` `dependencies` and `peerDependencies` are unchanged; additions are confined to
+  `devDependencies`.
+
+No component behaviour is under test here — the existing suite covers that and must stay green.
+
+### Risks
+
+- **Dependency addition** is the real cost and the reason this is approval-gated: Vite plus a React
+  plugin. Keep it to the minimum; do not pull in a UI-catalog framework.
+- **Harness fidelity.** A mock adapter can drift from the real REST/realtime contract and produce
+  confidence that does not transfer. Mitigation: fixtures are shaped from the actual dcm contract in
+  `django-core-micha/docs/design/messaging-platform.md` §REST/§Realtime, and the harness is a
+  development aid — it never replaces the tests or the independent review.
+- Scope creep into "a component gallery". The deliverable is a dev page, not a product.
+
+### Preconditions
+
+Operator approval for the devDependency additions — granted 2026-07-31 as part of the MSG-3 scoping
+decision. This WO **runs before MSG-3**.
+
+### 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.
+
+### Release
+
+**No version bump, no publish.** Dev-only tooling changes nothing in the package. The next ucm
+publish rides whatever WO follows (MSG-3).
+
+### Mini-handover (pastable)
+
+Orchestrator: implement `work-orders/DX-1.md` in `ui-core-micha` (main). `git pull` first, read the
+WO, then follow `orchestrate-codex` (Codex-first, own independent review, commit on green, **no
+publish**).
+
+---
+
+## Part B — Implementation map (Orchestrator)
+
+### Target repo / working directory
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root; package `@micha.bigler/ui-core-micha`,
+current published version 2.15.0 — **unchanged by this WO**, no publish).
+
+### Context package
+
+**Repo conventions to mirror:**
+- `package.json` — current `scripts`: `build` (`tsc -p tsconfig.build.json`), `test` (`vitest run`).
+  No `dev` script exists yet; add one. `peerDependencies`/`dependencies` must not change;
+  `devDependencies` gains Vite + `@vitejs/plugin-react` only (or whatever minimal set a Vite+React+JSX
+  dev server needs) — no UI-catalog framework, no Storybook.
+- `tsconfig.build.json` — `"include": ["src"]`, `rootDir: "./src"`, `outDir: "dist"`. The harness must
+  live **outside** `src/` (e.g. a top-level `dev/` directory) so it is never included by this config
+  and never emitted into `dist/`. Confirm after writing: `dist/` from a build with the harness present
+  must be byte-identical to a build from before this WO (no new/changed files under `dist/`).
+- `src/index.js` — the published barrel. Do not add anything here for the harness itself; the harness
+  imports FROM the barrel (or directly from component source, orchestrator's/Codex's call — importing
+  from source is likely simpler and avoids a dist rebuild loop during dev) but nothing is added TO it.
+- `tests/notificationsExports.test.js` — the existing exports-regression pattern to confirm still
+  passes untouched (proves the barrel didn't change).
+- `src/notifications/realtime.jsx` — `useRealtimeCore({ active, wsUrl })` returns `{ subscribe }`;
+  `RealtimeContext` is the context the mock realtime provider must satisfy so components under it can
+  call `useRealtime()` without throwing. The harness's mock realtime adapter should provide a
+  `RealtimeContext.Provider` with an injectable `subscribe` (e.g. a manual event-dispatch harness) so
+  a harness entry can simulate a WS frame arriving, without opening a real socket.
+- `src/notifications/NotificationsProvider.jsx` (read for the provider-wrapping pattern) — a
+  representative provider-consuming surface for the "at minimum one notifications surface" harness
+  entry requirement.
+- `src/i18n/notificationsTranslations.ts` / `src/i18n/chartsTranslations.ts` — the flat i18n key
+  pattern; the harness needs `react-i18next` wired with at least these (or a minimal fixture set) so
+  mounted components render translated text instead of raw keys.
+- Chart components (`ChartFrame`/`BarChart`/`LineChart`, per `tests/ChartFrame.test.jsx` etc.) — the
+  "at minimum one charts surface" harness entry.
+
+**Invariants:**
+- Zero new runtime dependencies (peer or direct) — Vite/plugin additions are dev-only.
+- Harness is not exported, not built, not tested for behavior (only the three "does not affect the
+  product" assertions in Required Tests below).
+- No change to the existing vitest test setup/config or any existing test file.
+- No CI wiring — this is a local dev tool.
+
+### Required tests
+
+Per envelope: extend/confirm the exports-regression test still passes with nothing new reachable from
+it; a `build` succeeds and diffing `dist/` before/after shows no harness files and no content change;
+inspect `package.json` to confirm `dependencies`/`peerDependencies` are byte-identical and only
+`devDependencies` gained entries.
+
+### Progress contract
+
+Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (file opened, file
+edited, command/test run) and `PROGRESS: [<n>/<total>] done` on step completion, spaced so no gap
+exceeds ~2 min, stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+### Preamble (must be appended verbatim to the Codex prompt)
+
+The text above is the COMPLETE spec — read nearest `AGENTS.md`, `.codex/skills/<role>/SKILL.md` (if
+present), and this repo's `MEMORY.md` only for conventions; stay in scope; do not touch
+`peerDependencies`/`dependencies`, only `devDependencies`; do not touch `src/index.js`'s exports; do
+not update `MEMORY.md`; do NOT `git add`/`commit`/`push` — leave the change uncommitted in the working
+tree for the orchestrator's independent review. WRITE and RUN the three required checks (exports test,
+build + dist diff, package.json dependency diff) yourself to confirm — that is your only verification
+run: do NOT run the full vitest suite as a "review" and do NOT run any review; the orchestrator does
+both after you finish (though re-running `vitest run` in full is harmless and encouraged as a sanity
+check since it's the existing test command, just don't treat it as satisfying the review step).

package/work-orders/MSG-3.md

@@ -0,0 +1,375 @@
+# MSG-3 — ucm messaging surfaces (full parity)
+
+Status: planned · Tier 2 · Target repo: `ui-core-micha` (main)
+**Binding spec:** `django-core-micha/docs/design/messaging-platform.md` — especially §ucm surface,
+§REST contract, §Realtime, §Notification contract. On any conflict the design doc wins; deviations
+from it are an operator scope change, never a silent edit.
+
+Canonical register row: `django-core-micha/WORK_ORDERS.md` (the `MSG-*` workstream register). This
+repo carries the ucm-side mirror row.
+
+---
+
+## Part A — Envelope (Expertenchat, 2026-07-31)
+
+### Goal
+
+Build the shared messaging surfaces in ucm against the dcm messaging domain published in 2.36.1, so
+that a consuming app gets a complete chat UI by mounting a provider and a few components, and supplies
+only routing, display placement and scope pickers itself — never a forked state machine.
+
+### Two operator decisions that shape this WO (2026-07-31)
+
+**1. Redesign is permitted — but no feature may be lost.** jg's current messaging UI is *not* a
+verbatim visual target: where it grew organically across MSG-B1..B4, MSG-UX and MSG-DIALOG-1, MSG-3
+may lay it out and structure the interaction better. The licence covers **layout, composition,
+visual language and interaction flow**. It does **not** cover the feature set: the design's paper
+test ("No jg feature is lost") stays binding, and dropping or degrading a capability is a scope
+change back to the operator, not a design choice.
+
+Because "redesign allowed" is easy to over-read, the WO carries a hard deliverable:
+**a written deviation list** — every behavioural difference from jg's current messaging UI, with a
+one-line rationale each, committed alongside the code (`docs/messaging-deviations.md` or an appendix
+in this file). "We changed nothing behaviourally" is an acceptable list; an absent list is not.
+Consequence to record now: **MSG-5 therefore becomes a visible change for jg users**, not a silent
+migration, and needs its own UX review at adoption.
+
+**2. Validation runs through the DX-1 dev harness.** ucm had no way to render anything; DX-1 adds a
+Vite dev page. MSG-3 is expected to **use** it: every surface gets a harness entry, and the redesign
+is iterated there rather than asserted in jsdom.
+
+### Expected outcome
+
+Per design §ucm surface, a new `src/messaging/` subpackage mirroring the layout and conventions of the
+existing `src/notifications/` subpackage (module layout, `src/i18n/<domain>Translations.ts`, flat
+`tests/*.test.jsx`, additive barrel exports in `src/index.js` with an exports regression test):
+
+- `MessagingProvider` + hook, an API adapter over the dcm REST contract, and a normalized cache.
+- Realtime on **Layer 1**: `const { subscribe } = useRealtime()` — destructure it and depend on
+  `subscribe`, never on the recreated context object (design §Realtime states this explicitly; it is
+  a known footgun). Handle every frame the design lists, deduplicate by `event_id`, and refetch REST
+  state and cursors on reconnect. **No second socket, no client→server WS.**
+- `ConversationList`, `Thread`, `Composer`, `ReadTicks`, `ReactionBar`, `PollCard`, `AttachmentList`,
+  config and per-conversation preference surfaces, and conversation launchers.
+- Cursor pagination with infinite reverse scroll on thread history, from day one — the dcm contract
+  is opaque signed cursors, **not** offset paging.
+- Optimistic send: the composer writes a local row keyed by `client_request_id`, reconciles the REST
+  response and the WS confirmation into exactly one row, and surfaces retry/error without duplicates.
+- Labels, status text and validation messages in **de/en/fr**.
+- Host apps supply routing, display placement and scope pickers; ucm supplies the state machine.
+
+### Parity inventory — the files that define "no feature lost"
+
+The deviation list must be built against **all** of these, not just the obvious component folder:
+
+| jg file | LOC | Note |
+|---|---|---|
+| `frontend/src/components/Messaging/Thread.jsx` | 2470 | the bulk: timeline, composer, replies, reactions, edit/delete, image upload, poll UI |
+| `frontend/src/components/Messaging/ConversationList.jsx` | 166 | |
+| `frontend/src/context/MessagingContext.jsx` | 184 | Layer-1 subscription + list/unread state |
+| `frontend/src/components/Messaging/AnnouncementDialog.jsx` | 147 | broadcast/announcement composer incl. `link_target` deep-link |
+| `frontend/src/components/Messaging/MessagingConfig.jsx` | 131 | per-scope config surface |
+| `frontend/src/components/Messaging/NewDirectMessageDialog.jsx` | 103 | DM launcher — **the first-contact case MSG-2b unblocked** |
+| `frontend/src/api/messagingApi.js` | 102 | |
+| `frontend/src/components/Messaging/EmojiPickerButton.jsx` | 44 | |
+| `frontend/src/components/Messaging/conversationHelpers.js` | 22 | |
+| **`frontend/src/pages/MessagesPage.jsx`** | **310** | **easy to miss and NOT purely host-app routing** — see below |
+
+~3700 LOC excluding tests.
+
+**`MessagesPage.jsx` needs an explicit split.** It is nominally jg's page, but it embeds behaviour that
+belongs to this WO's "conversation launchers": the unified conversation+group list that surfaces
+*unopened* groups as clickable launch items, and broadcast-conversation auto-surfacing/auto-open via
+the `?tab=broadcast` query parameter. The page shell (routing, placement, master-detail layout) stays
+with the host app per design §ucm surface; **the launcher behaviour it currently embeds is ucm scope**
+and must appear in the deviation list either as reproduced or as an explicitly surfaced deviation.
+This file was missing from the first parity inventory and is exactly the shape of gap through which a
+feature disappears with nobody deciding to drop it.
+
+### Decomposition is a requirement, not a preference
+
+jg's messaging UI is one 2470-LOC component with a 2173-LOC test file. **Reproducing that shape in ucm
+is a scope violation, even if every feature is present.** The component list above is a set of binding
+boundaries, not a suggested file layout. Concretely:
+
+- **Each named component is a separately exported, independently mountable, independently testable
+  unit** — not an internal helper reachable only through `Thread`. `Composer`, `ReactionBar`,
+  `PollCard`, `AttachmentList` and `ReadTicks` must each stand on their own.
+- **Domain state lives in the provider and its normalized cache; components read it through the
+  hook.** Design §ucm surface says host apps get components, "not a forked state machine" — the
+  corollary inside ucm is that subcomponents do not receive conversation/message state by
+  prop-drilling through `Thread`. This is the actual cause of a 2470-LOC component, not the feature
+  count. **This applies to domain state only** — conversations, messages, receipts, unread counts,
+  poll results. Ephemeral UI state stays local to the component that owns it: composer draft text,
+  upload progress, scroll and virtualization position, open menus, hover state. Lifting those into
+  the provider would be a worse design, not a more compliant one.
+- **Every component gets its own DX-1 harness entry, mountable standalone.** This is the forcing
+  function: a monolith cannot be mounted piecewise, so the harness makes accidental re-monolithisation
+  visible immediately rather than at review time.
+- **Soft size trigger:** any single component file above ~400 LOC must be justified explicitly in that
+  chunk's review. Not a hard cap — a deliberate, argued exception is fine, an unexamined 1500-line
+  component is not.
+- `Thread` itself owns the timeline and its virtualization/scroll behaviour. Composing, reacting,
+  poll rendering, attachment rendering and receipt display are **collaborators it renders**, not
+  responsibilities it absorbs.
+
+The `ui_reviewer` pass at WO end covers this explicitly, alongside design-system consistency.
+
+### Proposed chunk plan (staged commits, one independent review per chunk)
+
+1. `MessagingProvider` + API adapter + normalized cache + Layer-1 subscription (frames, `event_id`
+   dedup, reconnect refetch).
+2. `ConversationList` + launchers + unread / archive / mute + list pagination.
+3. `Thread` (timeline + scroll/virtualization only) + message rendering + one-level replies / thread
+   view + infinite reverse scroll, with `ReadTicks` as a separate collaborator component.
+4. `Composer` (optimistic send, retry/error) + attachment upload + `AttachmentList`.
+5. `ReactionBar` + `PollCard` + config/preferences + i18n sweep + barrel exports + the deviation list.
+
+The register estimates 3–5 chunks. **Treat that as a floor, not a ceiling** — the jg parity target is
+~3700 LOC excluding tests, with `Thread.jsx` alone at 2470. If the work does not fit, split further
+and say so; do not compress by dropping scope.
+
+### Required tests to WRITE (scoped per chunk; the reconciliation set is mandatory)
+
+- **Optimistic send reconciliation:** a REST confirmation and a WS frame for the same
+  `client_request_id` produce exactly one message row — the classic duplicate-message bug.
+- **`event_id` deduplication:** a repeated frame changes nothing.
+- **Reconnect:** current list, open thread and unread count are refetched; no stale cursor is reused.
+- **Pagination:** opaque cursor paging and reverse infinite scroll; a rejected cursor surfaces as an
+  error rather than an empty thread.
+- **Read ticks:** aggregate state renders; per-recipient detail appears only where permitted and
+  **never for a direct conversation** — mirror the dcm carve-out on the client so the UI cannot imply
+  a capability the API refuses.
+- **Attachment upload errors** surface as user-visible validation, not a generic failure (the MSG-2
+  chunk-4 lesson: a rejected upload must read as a rejection).
+- **i18n coverage:** every new key exists in all three languages; no hardcoded user-facing string.
+- **Exports regression:** the barrel exposes the new public surface, mirroring
+  `tests/notificationsExports.test.js`. This doubles as the decomposition check — every named
+  component must be individually exported and individually renderable in its own test, which a
+  monolith cannot satisfy.
+- Existing ucm suites (notifications, onboarding, auth, charts) stay green — this WO is additive.
+
+Per AGENTS.md "Test scope", per-chunk runs stay scoped to that chunk; the WO-end gate is the
+affected-area set (messaging + notifications, since both share the Layer-1 transport).
+
+### Reviews
+
+Beyond the standard independent `reviewer` per chunk, this WO explicitly carries **`ui_reviewer`** at
+WO end — design-system consistency, reuse of existing ucm primitives, responsive behaviour, dark mode
+and translation coverage. With a redesign licence in play, that pass is not optional.
+
+### Non-goals / do-not-touch
+
+dcm changes (small sibling contract fixes are in scope per the design's release plan, but a
+behavioural change to the dcm domain is not); any app-side code; jg's existing messaging UI (untouched
+until MSG-5); the jg data migration; search; typing indicators; client→server WebSocket; scanner
+infrastructure; `src/notifications/` behaviour beyond additive reuse — the Layer-1 primitive is
+consumed, not modified.
+
+### Risks
+
+- **Largest v1 block, built without a consumer.** MSG-5 is the first mount. The DX-1 harness is the
+  only feedback loop until then, and a mock adapter can drift from the real contract — shape fixtures
+  from the design doc's REST/realtime sections, not from imagination.
+- **Redesign licence is the main scope risk.** Without the deviation list it silently becomes
+  "reimplement approximately", and jg loses features nobody decided to drop.
+- **Optimistic send** is where duplicate/ghost messages come from; it has a mandatory test above.
+- **`useRealtime` misuse** re-subscribes on every render if the context object is a dependency — a
+  documented footgun, called out in expected outcome.
+- Estimate risk: see the chunk plan note.
+
+### Preconditions
+
+dcm messaging published (2.36.1, incl. MSG-2b) · **DX-1 done** (the harness this WO validates
+against) · Approval Gate #1 for MSG-3 = operator go on this envelope.
+
+### Release
+
+One version bump + npm publish at WO end. No consumer pins are bumped here; MSG-5 picks the release
+up via its own registry live-check before pinning.
+
+### 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-3.md` in `ui-core-micha` (main), chunk by chunk starting at
+chunk 1. `git pull` first, read the WO + `django-core-micha/docs/design/messaging-platform.md`
+(§ucm surface, §REST contract, §Realtime), then follow `orchestrate-codex` (Codex-first per chunk,
+own review per chunk, `ui_reviewer` at WO end, one publish at WO end).
+
+---
+
+## Part B — Implementation map (Orchestrator)
+
+### Target repo / working directory
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo root; package `@micha.bigler/ui-core-micha`,
+current published version 2.15.0). **Precondition: DX-1 must be landed and committed first** — do
+not start this WO's chunk 1 until DX-1's commit exists on `main`.
+
+### Operator-approved exception: additive Layer-1 reconnect signal (2026-07-31)
+
+Chunk 1's first dispatch found a real blocker: the design's "Reconnect refetches REST state/cursors"
+(§Realtime) cannot be implemented against the existing Layer-1 primitive. `useRealtimeCore`
+(`src/notifications/realtime.jsx`) tracks connect/backoff/reconnect internally but exposes only
+`{ subscribe }` — no consumer, including `NotificationsProvider`'s own `RealtimeContext.Provider`
+value, can observe a reconnect happening. This is confirmed by direct inspection, not assumed.
+
+**Operator decision:** extend `src/notifications/realtime.jsx` and (if needed to thread the value
+through) `src/notifications/NotificationsProvider.jsx` **additively** — e.g. an `onReconnect(callback)`
+registration or a `connected` boolean added to the object `useRealtimeCore` returns and the
+`RealtimeContext` value. This is the ONE approved exception to this WO's "consumed, not modified"
+boundary for `src/notifications/`; do not use it as license to touch anything else there. Requirements
+for the extension itself:
+- Purely additive — existing consumers destructuring only `{ subscribe }` must be completely
+  unaffected (same behavior, same shape for the fields they read).
+- No new WS consumer, no change to the connection/backoff logic itself, only exposing a signal that
+  already exists internally.
+- Covered by its own test in the existing `tests/realtime.test.jsx` (or a new adjacent test file
+  following that convention) proving the reconnect signal actually fires when the internal `connect()`
+  path re-establishes after a close — not just that the field exists.
+- This is chunk 1's first task, before the messaging-specific work; land it as a clearly-separated
+  part of chunk 1's diff (the reviewer will look at it as its own concern) rather than mixing it
+  invisibly into `MessagingProvider`'s implementation.
+
+### Shared context package (applies to every chunk)
+
+**New subpackage to create:** `src/messaging/` — mirror `src/notifications/`'s layout and
+conventions: flat files (`api.js`, `realtime.jsx` or reuse ucm's existing one — see below,
+`MessagingProvider.jsx`, one file per named component), `src/i18n/messagingTranslations.ts` (flat
+`{"Key.SUBKEY": {"de":…, "en":…, "fr":…}}` shape, matching `notificationsTranslations.ts`/
+`chartsTranslations.ts`), flat `tests/*.test.jsx` (not nested under `tests/messaging/`), additive
+barrel exports in `src/index.js` with an exports-regression test extending
+`tests/notificationsExports.test.js`'s pattern (new file `tests/messagingExports.test.js` is fine,
+or extend the existing one — Codex's call, consistency with existing convention matters more than
+which file).
+
+**Binding spec:** `django-core-micha/docs/design/messaging-platform.md` in full — §ucm surface,
+§REST contract (exact endpoint list, payload shapes, cursor pagination), §Realtime (exact frame
+names and payload shape — note MSG-2 chunk 3's fix: `message_deleted` carries ONLY
+`message_id`/`deleted_at`/`deleted_by`, never content), §Notification contract (for awareness, not
+implementation — ucm consumes `Notification`/`feed_visible=False` types via the existing
+notifications surface, messaging doesn't re-implement notification delivery).
+
+**Realtime — reuse, do not reinvent:** `src/notifications/realtime.jsx` already exports
+`RealtimeContext`/`useRealtimeCore`/`useRealtime()`; `NotificationsProvider.jsx` is the sole mounter
+of `RealtimeContext.Provider` (one WebSocket for the whole app). `MessagingProvider` must be mounted
+**inside** an app's existing `NotificationsProvider` tree and call `useRealtime()` (throws if not
+wrapped — see `realtime.jsx:13-19`) to get `{ subscribe }`. **Destructure `subscribe` and depend on
+it in effects — never depend on the object `useRealtime()` returns**, which is recreated on every
+`NotificationsProvider` render including unrelated bell-state changes (documented footgun, design
+§Realtime, and jg's own `MessagingContext.jsx:32-35` comment explains exactly this bug). Messaging
+does NOT open a second socket and does NOT export its own `RealtimeContext`/provider — it is a second
+`subscribe(envelope, handler)` caller on the existing one, envelope key `"messaging"`.
+
+**jg reference implementation (generalize, do not port verbatim — jg is event-scoped and
+monolithic, ucm must be tenant-generic and decomposed per the envelope's decomposition requirement):**
+- `../jg-ferien/frontend/src/context/MessagingContext.jsx` (184 lines, already read in full this
+  session) — provider shape precedent: WS handler switch on `data.type` (`message`,
+  `message_edited`, `message_deleted`, `poll_updated`) updating a conversation list + unread count;
+  `activeIdRef` pattern to avoid stale-closure issues in the WS handler; `markConversationRead`
+  optimistic local update before/alongside the REST call. ucm's version must be scope/tenant-generic
+  (no `eventId` parameter baked in — host app supplies scope/filter params) and must normalize into
+  a proper cache (conversations, messages, threads, polls, reactions as separate normalized slices
+  keyed by id), not just a flat conversation array — chunks 2-5 need to read/write messages and
+  thread state independently of the conversation list.
+- `../jg-ferien/frontend/src/api/messagingApi.js` (102 lines, already read in full) — REST call
+  shape precedent (axios wrapper over `apiClient`). ucm's adapter targets the NEW dcm paths from the
+  design doc (`/api/messaging/conversations/`, `/api/messaging/conversations/direct/`, etc.) — these
+  differ from jg's current paths (jg's own adoption/migration is MSG-5, a separate WO; do not target
+  jg's current legacy paths, target the published dcm 2.36.1 contract in the design doc).
+- `../jg-ferien/frontend/src/context/realtimeEnvelopes.js` — `MESSAGING_ENVELOPE = "messaging"`, the
+  envelope discriminator string ucm's `subscribe("messaging", handler)` call must use (matches the
+  dcm design doc's realtime frame `envelope: 'messaging'` field).
+- `src/notifications/NotificationsProvider.jsx` (already read in part) — `normalizeNotification`-style
+  normalization pattern, `useCallback`/`useRef` conventions, how it composes `AuthContext` + realtime
+  + REST fetch into one provider. Use as the shape precedent for `MessagingProvider`, not as a literal
+  template (notifications is a flat feed; messaging needs a genuinely normalized multi-entity cache).
+
+**Invariants (all chunks):**
+- No app-specific code — no event/scope assumptions baked into components; scope/filter params are
+  passed in by the host app (design §ucm surface: "host apps supply routing, display placement and
+  scope pickers").
+- Every named component (`ConversationList`, `Thread`, `Composer`, `ReadTicks`, `ReactionBar`,
+  `PollCard`, `AttachmentList`) is independently exported and independently mountable — verify via
+  its own DX-1 harness entry per the envelope's decomposition requirement, not just via `Thread`
+  rendering it internally.
+- Domain state (conversations, messages, receipts, unread counts, poll results) lives in the
+  provider's normalized cache; components read via the hook. Ephemeral UI state (draft text, upload
+  progress, scroll position, open menus) stays component-local — do not lift it into the provider.
+- Cursor pagination is opaque and signed (matches dcm's `django.core.signing`-based cursor) — never
+  build an offset/page-number UI; a bad/tampered cursor from the API is a 400, surface it as an
+  error state, not an empty list.
+- `client_request_id`-keyed optimistic send: composer writes a local pending row immediately,
+  reconciles when the REST response and/or the WS `message` frame for the same id arrives — must
+  converge to exactly one row, not two.
+- i18n: every user-facing string goes through `messagingTranslations.ts` in all three languages; no
+  hardcoded text.
+- No client→server WebSocket path anywhere — every write is REST, even optimistic ones (the socket
+  is read-only fan-out).
+
+### Chunk 1 — this dispatch
+
+**Scope:** `MessagingProvider` + hook (`useMessaging()`) + API adapter (`src/messaging/api.js`) +
+normalized cache + Layer-1 subscription (frame handling for at least `message`, `message_edited`,
+`message_deleted`, `conversation_upsert`, `participant_changed`; the remaining frame types
+`reaction`/`poll_updated`/`delivered`/`read_state`/`thread_read_state`/`attachment_ready`/
+`conversation_archived` can have handler stubs wired now and filled in by the chunk that owns that
+feature — e.g. `poll_updated` real handling lands in chunk 5 with `PollCard`, but the dedup/dispatch
+plumbing must exist now so later chunks only add a case, not restructure the subscriber). `event_id`
+deduplication (a `Set` of recently-seen ids, per design's "handlers deduplicate `event_id`").
+Reconnect refetch (on the realtime connection re-establishing, refetch current conversation list +
+open thread + unread count — jg has no precedent for this since it never handles reconnect
+explicitly; this is a v1 requirement per design §Realtime "Reconnect refetches REST state/cursors").
+
+**No components in this chunk** — `ConversationList`/`Thread`/etc. are chunks 2-5. This chunk's DX-1
+harness entry (if any) is a minimal "provider + raw state dump" page proving the provider mounts,
+fetches, and updates on a simulated WS frame — full component harness entries land with their
+owning chunks.
+
+**Required tests for this chunk:**
+- `event_id` deduplication: a repeated frame changes nothing (mandatory per envelope).
+- Reconnect: refetch is triggered (mock the realtime reconnect signal — check `useRealtimeCore`/DX-1
+  harness's mock adapter for how a reconnect is simulated; if the mock adapter can't yet simulate a
+  reconnect, that's a DX-1 gap to note, not something to silently skip).
+- API adapter: each REST call targets the correct dcm path/method per the design doc's §REST table
+  (a scoped unit test per function is fine, doesn't need a live backend).
+- Normalized cache: applying a `message` frame updates only the affected conversation's/message's
+  slice, not the whole cache (proves normalization, not just "state changed").
+- Exports regression: `MessagingProvider`/`useMessaging` reachable from the barrel.
+
+### Progress contract (every chunk)
+
+Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (file opened, file
+edited, command/test run) and `PROGRESS: [<n>/<total>] done` on step completion, spaced so no gap
+exceeds ~2 min, stdout unbuffered, and exactly one final `RESULT: DONE|BLOCKED <reason>` per chunk.
+
+### Preamble (append verbatim to every chunk's Codex prompt)
+
+The text above is the COMPLETE spec for this chunk — read nearest `AGENTS.md`,
+`.codex/skills/<role>/SKILL.md` (if present), and this repo's `MEMORY.md` only for conventions; stay
+in scope; do not touch anything outside `src/messaging/`, `src/i18n/messagingTranslations.ts`, the
+named test files, and additive `src/index.js` barrel exports; do not touch
+`peerDependencies`/`dependencies` (only this WO's own runtime needs, if any, and only with the
+orchestrator's awareness — flag before adding anything beyond what's already a peer/dev dependency);
+do not update `MEMORY.md`; do NOT `git add`/`commit`/`push` — leave the chunk's changes uncommitted
+for the orchestrator's independent review. WRITE this chunk's required tests AND RUN them to confirm
+they pass — that is your only test run: do NOT run the full ucm suite and do NOT run any review; the
+orchestrator runs the affected-area set and the independent review after you finish. Use the DX-1 dev
+harness (`dev/` or wherever DX-1 placed it) to visually verify anything you build that renders —
+add/update a harness entry for this chunk's surface even if the required tests above don't mention it
+explicitly, per the envelope's "every surface gets a harness entry" requirement.
+
+### Mini-handover (pastable, per chunk)
+
+Orchestrator: implement chunk <n> of `work-orders/MSG-3.md` in `ui-core-micha` (main). `git pull`
+first, read the WO + `django-core-micha/docs/design/messaging-platform.md`, then follow
+`orchestrate-codex` (Codex-first, own independent review per chunk, `ui_reviewer` at WO end, one
+publish at WO end).