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

package/work-orders/NOTIF-12.md

@@ -0,0 +1,214 @@
+# WORK ORDER NOTIF-12 (ui-core-micha + django-core-micha) — popup channel via the wizard renderer
+
+**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 this
+file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
+
+Feature-level WO (Expertenchat envelope). Seams verified against ucm 2.12.0 / dcm 2.32.0.
+
+## HARD GATE — SATISFIED 2026-07-30
+NOTIF-13 landed and published: ucm **2.13.0** (`7a83ee9`), dcm **2.33.0** (`de77335`), both verified
+live on npm/PyPI. This WO was re-verified against the landed code on 2026-07-30 and the context
+package below describes the **actual shipped API**, not the pre-NOTIF-13 state. Cleared to start.
+
+## TIER
+Tier 2 — this extracts a renderer out of `OnboardingWizard`, which **cockpit and jg run in
+production**. The roadmap calls the popup channel "uncritical"; that refers to business urgency, not
+blast radius. Independent `reviewer` mandatory. `sec_reviewer` only on explicit operator request.
+
+## SCAFFOLDING NOTICE — READ FIRST
+**This channel ships with zero producers, deliberately.** Verified 2026-07-29 across dcm, jg-ferien,
+cockpit, hram, spesix and survey_app: **no notification type declares `popup` in `eligible_channels`**,
+so `resolve_channels()` will never route anything to it until some app opts a type in. The operator
+decided to build the scaffolding anyway (2026-07-29), having been shown this.
+
+Two obligations follow, and they are part of the acceptance criteria:
+1. **Do not overclaim.** The CHANGELOG entry and any docstring must state plainly that the popup
+   channel is wired but inactive until a notification type declares `popup`. Precedent: NOTIF-4's
+   reviewer (R1) had to soften a CHANGELOG that promised retry behaviour no shipped dispatcher could
+   reach. Do not repeat that.
+2. **Scaffolding must be tested scaffolding.** Register a test-local notification type that declares
+   `popup` and prove the whole path end-to-end. Untested dead code is not an acceptable outcome.
+
+## GOAL
+Make `popup` a real delivery channel: a notification whose type opts into `popup` is rendered to the
+recipient in a modal that reuses the onboarding **wizard renderer**, with its seen/dismissed status
+recorded on `NotificationRecipient` — **not** in the onboarding progress store.
+
+## EXPECTED OUTCOME
+- dcm's `PopupDispatcher` stops being a logging stub and delivers for real.
+- ucm exports a popup surface that renders popup-eligible notifications and marks them via the
+  existing `feed/mark/` path.
+- Onboarding behaviour is bit-for-bit unchanged for existing consumers.
+- With no producer registered, nothing visibly changes in any app.
+
+## CONTEXT PACKAGE — verified current state
+
+**dcm `notifications/dispatch.py`:**
+- `PopupDispatcher` (`:117-121`) is a stub: logs "queued for unimplemented popup channel" and returns
+  `DeliveryResult(ok=None, error="pending")`. It is registered in `_DISPATCHERS` (`:126-133`).
+- The model to copy is `ChipDispatcher` (`dispatch.py:64-75`, post-NOTIF-13): it calls
+  `push_to_users([recipient.user], notification_envelope({"type": notification.notification_type, "content": ..., "notification_id": ...}))`
+  and returns `DeliveryResult(ok=True)`.
+
+**How NOTIF-13 actually shipped — read this before writing scope D.** The envelope is a
+**domain-level** discriminator, not a per-channel one:
+- `delivery.py:25` `NOTIFICATION_ENVELOPE = "notification"`; `delivery.py:28-35`
+  `notification_envelope(payload)` merges `{"envelope": "notification"}` into any payload. **Additive**
+  — the pre-existing fields, including the overloaded `type`, are unchanged.
+- ucm `src/notifications/realtime.jsx:68` routes purely on `data.envelope ?? DEFAULT_ENVELOPE`, then
+  fans to every handler subscribed to that envelope.
+- **Inside** the notification envelope, `NotificationsProvider` keeps the original two-way split:
+  `data.type === 'notification.status'` patches status (`:98`), and **everything else is appended to
+  the feed with `unreadCount + 1`** (`:120`).
+
+**Consequence — the trap this WO must avoid:** if `PopupDispatcher` simply calls
+`notification_envelope({...})` like Chip does, its message is **indistinguishable from a chip
+message**. The popup surface subscribing to the `"notification"` envelope would receive every chip
+notification and pop up for all of them, and a notification routed to *both* chip and popup would
+produce **two feed entries and `unreadCount + 2` for one notification**. Scope D and D2 below exist
+to close exactly this.
+- `_render_content(content, user)` (`:44-60`) renders `title_key`/`body_key`/`params` in the
+  recipient's language — reuse it rather than re-deriving text client-side if the payload needs text.
+- `prefs.py:22` already treats `popup` as a channel defaulting to True; `router.py:24` narrows to
+  `ntype.eligible_channels`. **No prefs or router change is needed** — only a type opting in.
+
+**ucm `src/onboarding/OnboardingWizard.jsx` (75 LOC)** is the renderer to reuse:
+- MUI `Dialog open fullWidth maxWidth="sm"` (`:59`), `DialogTitle` with a step counter +
+  `LinearProgress` (`:60-67`), `DialogContent` rendering
+  `<StepComponent onComplete={...} onDismiss={...} ctx={...} />` (`:69`).
+- Step contract: `{ id, Component, blocking, persistDismissed }`. `blocking` disables escape/backdrop
+  close (`:59`).
+- **The parts that must NOT come along** (design decision D-F7,
+  `django-core-micha/docs/design/notifications-platform.md:70-71`): `onboarding.markStepSeen` (`:35`),
+  `dismissStep` (`:54`), and the sequential progress store behind them. Popup status lives on
+  `NotificationRecipient`.
+- Exported at `src/index.js:61`; the four existing steps at `:62-65`.
+
+**ucm notification status API:** `useNotifications()` already returns `markSeen` / `markDismissed` /
+`markDone`, backed by `feed/mark/`. Use `markSeen` when a popup is shown and `markDismissed` when the
+user closes it. **Never `markDone`** — done is a todo-channel semantic.
+
+## SCOPE
+
+**A. ucm — extract the dialog shell.** Lift the presentational shell out of `OnboardingWizard` into a
+reusable renderer (dialog frame, counter/progress header, the `onComplete`/`onDismiss`/`ctx` child
+contract). `OnboardingWizard` keeps its current behaviour by composing that shell with the onboarding
+store; the popup surface composes the same shell with notification state.
+
+**B. ucm — the popup surface.** A component that renders popup-eligible notifications through the
+shell, marks `seen` on display and `dismissed` on close. For live popups it subscribes via
+`useRealtime()` to the **`"notification"` envelope** (`DEFAULT_ENVELOPE` — there is no popup-specific
+envelope, see D) and filters on `channel === "popup"`, ignoring `notification.status` messages and
+channel-less legacy payloads. Export additively from `src/index.js`.
+
+**C. Coexistence rule with onboarding — specify and test it.** Both surfaces render a MUI `Dialog`, so
+two modals can be open at once. Required behaviour: **a blocking onboarding step wins**; the popup
+waits until no blocking onboarding step is active. Non-blocking coexistence must not stack two dialogs.
+
+**D. dcm — implement `PopupDispatcher.deliver`, with a channel discriminator *inside* the envelope.**
+Emit through `notification_envelope()` (so Layer-1 routing stays domain-keyed and messaging can still
+ride alongside) and add an explicit **`"channel": "popup"`** field to the payload. Return
+`DeliveryResult(ok=True)`. Keep delivery-record semantics identical to `ChipDispatcher` — the
+surrounding `dispatch()` machinery already records pending → sent/failed; do not re-implement it.
+
+**Do NOT invent a second envelope value** (e.g. `"notification.popup"`). The envelope discriminates
+*domains* so a future messaging stream can share the socket; overloading it with channels would
+undo NOTIF-13's design. Channel selection belongs inside the payload.
+
+For symmetry and so the client can tell the cases apart, `ChipDispatcher` should carry
+`"channel": "chip"` as well. **Backward compatibility:** a payload with **no** `channel` field must
+keep behaving exactly as today (feed entry + unread increment), because an app pinned to an older dcm
+will still send channel-less payloads.
+
+**D2. ucm — de-duplicate by `notification_id` in `NotificationsProvider`.** A notification routed to
+both chip and popup now produces two WS messages. The provider must fold them into **one** feed entry
+and **one** unread increment (de-dupe on `notification_id`, last-write-wins on content). Without this,
+enabling popup alongside chip double-counts the badge. This is an edit to `NotificationsProvider`,
+which is explicitly in scope here — it is not part of NOTIF-13's realtime core.
+
+## DO NOT TOUCH
+- **The onboarding progress store** — `markStepSeen`, `dismissStep`, `persistDismissed` persistence,
+  `OnboardingProvider`'s step-selection semantics, `stepSelection.js`.
+- The four existing step components (`CookieConsentStep`, `CompleteNameStep`, `BrowserPushStep`,
+  `PwaInstallStep`) and their props.
+- **NOTIF-13's realtime core** (`src/notifications/realtime.jsx`) — consume `useRealtime()` /
+  `subscribe(envelope, handler)`, do not restructure it. In particular leave the `seeded` gate, the
+  backoff/reconnect semantics and the envelope-routing alone. (`NotificationsProvider` itself IS
+  editable — scope D2 requires it.)
+- `feed/*` REST contract, `NotificationBell`, `NotificationSettings`.
+- `prefs.py`, `router.py`, `resolve_channels` — popup already works there; a type opting in is an
+  app-side change, not this WO's.
+- Schema, migrations, dependencies, CI.
+- **Do not register a `popup` producer in any app.** This WO ships the channel only.
+
+## RISKS
+- **Onboarding regression** is the main risk: the shell extraction touches a wizard that cockpit and jg
+  run in production. The step counter (`totalRef`/`completed`), the session-dismissed Set, and the
+  `blocking` escape-key behaviour are easy to break silently.
+- **Stacked modals** if C is skipped — two dialogs, neither reachable.
+- **Badge double-count** if D2 is skipped: a notification routed to both chip and popup arrives as two
+  WS messages and increments `unreadCount` twice for one notification. This is the single most likely
+  silent defect in this WO.
+- **Popup storm** if B subscribes to the envelope without filtering on `channel` — every chip
+  notification would pop up a modal.
+- **Regressing the NOTIF-13 R1 fix:** the `seeded` gate in `NotificationsProvider` exists because
+  decoupling the REST seed from the socket connect opened a silent-message-loss race. Do not touch it
+  while implementing D2.
+- **Dead code rot:** with no producer, only the tests exercise the path. Hence the mandatory test-local
+  producer type.
+- **Status semantics drift:** marking a popup `done` instead of `dismissed` would pollute todo-channel
+  semantics.
+
+## REQUIRED TESTS / ACCEPTANCE
+ucm (`pnpm test`, vitest):
+- a popup-eligible notification renders in the shell; `markSeen` fires once on display;
+- closing it fires `markDismissed`, never `markDone`;
+- **coexistence:** with a blocking onboarding step active, no popup dialog renders; once it clears, the
+  popup appears — and never two dialogs at once;
+- **onboarding regression guard:** existing `OnboardingWizard` behaviour unchanged — step counter,
+  progress bar, session-dismissed set, `blocking` disabling escape/backdrop close, `persistDismissed`
+  still calling `dismissStep`;
+- with no popup-eligible notification present, nothing renders;
+- **no popup storm:** a `channel: "chip"` message and a channel-less legacy message both leave the
+  popup surface silent;
+- **no double-count (D2):** two WS messages for the same `notification_id` (one `chip`, one `popup`)
+  yield exactly one feed entry and `unreadCount + 1`;
+- **NOTIF-13 R1 guard:** the `seeded` gate still holds — no socket messages are processed before the
+  REST seed completes.
+
+dcm (`pytest` on the notifications package):
+- register a **test-local** notification type declaring `eligible_channels=["popup"]`, call `notify()`,
+  and assert the dispatcher delivered (`ok=True`) with `envelope: "notification"` **and**
+  `channel: "popup"` on the wire — the end-to-end proof required by the scaffolding notice;
+- a chip delivery still carries `envelope: "notification"` and now `channel: "chip"`, with every other
+  field unchanged (no regression for existing consumers);
+- `resolve_channels` still excludes `popup` for types that do not declare it (no accidental widening);
+- the existing `test_dispatch.py` registry assertion (`:25`) still passes.
+
+Plus `pnpm build` (tsc) green.
+
+## RELEASE
+ucm minor bump + publish. dcm minor bump + publish (publish-from-main), with a **registry live-check
+before any app pin bump**. No app pin bumps in this WO. CHANGELOG in both repos must carry the
+inactive-until-a-producer-opts-in wording from the scaffolding notice.
+
+## TARGET REPO / WORKING DIRECTORY
+- Primary: `C:\Users\biglmi\Documents\webapps\ui-core-micha`
+- Secondary (scope D): `C:\Users\biglmi\Documents\webapps\django-core-micha`
+- Never the workspace root `…\webapps`.
+Both are platform repos: commit directly to the trunk, no feature branches.
+
+## PROGRESS CONTRACT
+Emit 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. Exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+## MINI-HANDOVER (paste into a fresh Orchestrator session)
+```
+Orchestrator: implement work-orders/NOTIF-12.md in ui-core-micha (main; scope D also touches
+django-core-micha). The NOTIF-13 gate is satisfied (ucm 2.13.0 / dcm 2.33.0). git pull, read the WO,
+then follow orchestrate-codex (Codex-first, own independent review, commit on green).
+```

package/work-orders/NOTIF-13.md

@@ -0,0 +1,142 @@
+# WORK ORDER NOTIF-13 (ui-core-micha + django-core-micha) — Layer-1 transport extraction
+
+**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 this
+file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
+
+Feature-level WO (Expertenchat envelope). The seams below are **verified against the landed code**
+(ucm 2.12.0, dcm 2.32.0) and are the required scope. The Orchestrator fills the exact line map.
+
+## TIER
+Tier 2 — restructures a provider that **cockpit consumes in production**, and changes a WebSocket
+message contract shared across apps. Independent `reviewer` mandatory. Per AGENTS.md Tier 2,
+`sec_reviewer` is NOT auto-included; request it only if the operator asks.
+
+## GOAL
+Turn ucm's notification-only socket into a generic **Layer-1 realtime primitive**: one socket,
+subscribe-by-message-type, so a second domain (messaging) can ride it without being misread as a
+notification. **Additive**: `NotificationsProvider` remains the sole mount point and its public
+context value is unchanged (operator decision 2026-07-29).
+
+## EXPECTED OUTCOME
+- ucm exports a `useRealtime()`-style subscribe primitive alongside the unchanged `useNotifications()`.
+- An unknown/unsubscribed message type is **ignored** instead of being appended to the notification feed.
+- No app has to change its provider tree. cockpit and jg keep working untouched.
+- NOTIF-15 (jg bell adoption, retiring jg's local context) becomes implementable; Phase B messaging
+  gets its substrate.
+
+## CONTEXT PACKAGE — verified current state
+
+**ucm `src/notifications/NotificationsProvider.jsx` (232 LOC)** owns *both* the socket and the
+notifications domain state:
+- socket ownership: `socketRef`, `connect()`, exponential backoff `INITIAL_BACKOFF_MS` 1s →
+  `MAX_BACKOFF_MS` 30s, auth-gated effect keyed on `[authenticated, refresh, replaceNotifications, wsUrlBase]` (`:87-179`).
+- `handleMessage` (`:103-133`) dispatches on exactly **one** envelope type, `notification.status` (`:111`).
+- **The blocker:** everything else falls through to `normalizeNotificationPush(data)` and is appended
+  to the feed with `unreadCount + 1` (`:130-132`). A messaging payload on this socket becomes a fake
+  notification today.
+- **Field overload — the reason a third stream cannot simply be added:** in the status branch
+  `data.type` is the *envelope* type; in the new-notification branch `normalizeNotificationPush`
+  reads `data.type` as the *domain* notification-type key (`:25`). One field, two meanings. The
+  envelope contract must resolve this without breaking either reading.
+- WS URL hardcoded to `/ws/notifications/` (`:36`, `:40`).
+- exports in `src/index.js:48` (`NotificationsProvider`, `useNotifications`).
+
+**dcm transport is ALREADY generic — correct the roadmap wording here.** The roadmap §4 calls for a
+"dcm multi-stream consumer"; that overstates the dcm work:
+- `notifications/delivery.py::push_to_users(users, payload)` (`:20-43`) fans an **arbitrary** payload
+  into the per-user group `notifications_user_{id}`.
+- `notifications/consumers.py::NotificationConsumer.message()` (`:21-22`) is `send_json(event["payload"])` —
+  fully stream-agnostic. jg's messaging **already** rides this same group via `push_to_users`.
+- The only dcm-side envelope producer is `notifications/views.py:235` (`"type": "notification.status"`);
+  the contract is documented at `views.py:3`.
+- **So the dcm work is the envelope contract + a thin authoring helper + doc — NOT a consumer rewrite.**
+
+**Reference implementation to promote:** jg's `frontend/src/context/NotificationsContext.jsx` (91 LOC,
+docstring "WebSocket owner only") already does exactly this multiplexing with
+`registerMessageCallback` / `registerChatCallback`. Read it for the shape. **Do not edit jg here.**
+
+## SCOPE
+
+**A. ucm — extract the socket into an internal realtime core.** Single owner; preserve the existing
+backoff, reconnect, auth-gating and cleanup semantics **verbatim**. Expose
+`subscribe(type, handler) -> unsubscribe`.
+
+**B. ucm — `NotificationsProvider` becomes the first subscriber.** It registers handlers for the
+notification envelope types. Its returned context value stays **exactly**
+`{ notifications, unreadCount, markSeen, markDismissed, markDone, refresh }`.
+
+**C. Envelope contract.** Introduce an explicit envelope discriminator that does not collide with the
+domain `type` field (see the field-overload note above). Unknown / unsubscribed envelope types are
+**ignored** — the catch-all at `:130-132` dies. This is a deliberate behaviour change and must be
+called out in the CHANGELOG.
+
+**D. Backward compatibility in BOTH directions** — apps pin dcm and ucm independently, so mismatched
+versions are normal:
+- *new ucm + old dcm* (payload has no envelope field): must still be recognised as a new notification,
+  exactly as today. Without this the feed silently goes dead against an un-bumped backend.
+- *old ucm + new dcm*: dcm must keep emitting the legacy fields so a ucm 2.12.0 client is unaffected
+  (**cockpit runs 2.12.0 in staging/prod**).
+
+**E. dcm — formalize the contract.** Document the envelope next to `views.py:3` and add a thin
+authoring helper so producers stop hand-rolling the dict. `push_to_users`'s signature stays unchanged.
+
+## DO NOT TOUCH
+- **jg-ferien** (`NotificationsContext.jsx`, `MessagingContext.jsx`) — that is NOTIF-15.
+- The messaging domain itself — Phase B (`MSG-*`).
+- `NotificationBell.jsx`, `NotificationSettings.jsx`, `feedApi.js`, the `feed/*` REST contract.
+- `BaseSecureConsumer` / S112 permission model, `IsAuthenticatedWs`, the group name `notifications_user_{id}`.
+- **No standalone `RealtimeProvider` export that apps must mount.** Operator decision 2026-07-29:
+  additive only. A standalone provider is a later, separate WO if a second consumer ever needs it.
+- Reconnect/backoff semantics and the single-socket-owner invariant — preserve, do not "improve".
+- Schema, migrations, dependencies, CI.
+- **No app pin bumps** in this WO (cockpit/jg stay where they are).
+
+## RISKS
+- **Silent feed death** if C lands without D: an envelope-less payload from an older dcm would be
+  ignored instead of shown. D is not optional.
+- **cockpit is a live consumer** at ucm 2.12.0 — any change to the returned context shape breaks it.
+- **Subscription leaks / double delivery:** `subscribe` must return a stable unsubscribe, and handlers
+  must **survive reconnects** without the caller re-registering them.
+- **Reconnect loop:** the socket effect currently depends on `refresh` / `replaceNotifications`;
+  moving the socket out must not make the socket re-create on every feed update.
+
+## REQUIRED TESTS / ACCEPTANCE
+ucm runs `vitest` (`pnpm test`) and has **no tests under `src/notifications/` today** — this WO adds
+the first ones:
+- an unknown envelope type is ignored: feed and `unreadCount` both untouched (the regression that
+  protects messaging from being misread as a notification);
+- two subscribers on distinct types each receive only their own messages, from **one** socket —
+  assert exactly one `WebSocket` was constructed;
+- `unsubscribe` stops delivery for that subscriber and does not affect the others;
+- handlers keep receiving after a close → backoff → reopen cycle, with no re-registration by the caller;
+- a legacy envelope-less payload still lands in the feed (backward-compat D);
+- `notification.status` handling and the `unreadCount` delta are unchanged — this guards the NOTIF-6
+  R1 fix (badge went stale after a cross-device mark);
+- `NotificationsProvider`'s public context value is unchanged.
+
+Plus `pnpm build` (tsc) green. If E lands in dcm, run the dcm notifications `pytest` package.
+
+## RELEASE
+ucm minor bump + publish (publish-from-main). dcm only if E lands there — then publish-from-main with
+a **registry live-check before any app pin bump**. No app pin bumps in this WO.
+
+## TARGET REPO / WORKING DIRECTORY
+- Primary: `C:\Users\biglmi\Documents\webapps\ui-core-micha`
+- Secondary (scope E only): `C:\Users\biglmi\Documents\webapps\django-core-micha`
+- Never the workspace root `…\webapps`.
+Both are platform repos: commit directly to the trunk, no feature branches.
+
+## PROGRESS CONTRACT
+Emit 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. Exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+## MINI-HANDOVER (paste into a fresh Orchestrator session)
+```
+Orchestrator: implement work-orders/NOTIF-13.md in ui-core-micha (main; scope E also touches
+django-core-micha). git pull first, read the WO, then follow orchestrate-codex (Codex-first, own
+independent review, commit on green).
+```