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

package/work-orders/MSG-3.md

@@ -1,375 +0,0 @@
-# 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).