@micha.bigler/ui-core-micha 3.6.0 → 3.7.0

package/work-orders/UCM-I18N-4.md

@@ -0,0 +1,226 @@
+# UCM-I18N-4 — Let a consumer choose informal German, and translate the hard-coded English in the auth and user screens
+
+# A. Envelope — authored by the Expertenchat
+
+## Goal & expected outcome
+
+- Goal: an app that addresses its users with "du" gets "du" in every ucm screen, and no ucm screen
+  shows hard-coded English in a German UI.
+- Expected outcome:
+  - The kit's German strings exist in a formal ("Sie", today's default) and an informal ("du")
+    variant; a consumer picks one when it registers the kit's strings (the single export from
+    `I18N-1`). Apps that do nothing keep today's formal German.
+  - `UserListComponent`, the invite panel (`UserInviteComponent`, `BulkInviteCsvTab`) and their
+    messages use translation keys for every visible string, in all configured locales.
+
+## Context — measured 2026-09-29 in jg-ferien's local browser test (ucm 3.5.0 installed there)
+
+- jg-ferien addresses its users with "du" throughout; ucm's auth screens use "Sie" — login, signup,
+  reset request, invite and reset pages (`src/i18n/authTranslations.ts`), so the break runs through
+  one flow (`/signup` "Sie", jg's `/signup/confirm` "du"), and one page mixes both (invite page
+  heading "Sie", validation "du").
+- Hard-coded English in German UI: `UserListComponent.jsx` — "All Users", "Search",
+  "Search users...", "Rows per page:", "Successful Login", "Are you sure you want to delete this
+  user?"; invite panel — "Invite a new user", "Bulk Invite via CSV", "Upload a CSV file containing
+  email addresses. Header "email" is supported.", "Upload CSV", "Send Invites", success "Invitation
+  sent.".
+- **Operator decision 2026-09-29: generic fixes go to ucm, app-specific ones to the app.**
+
+## Scope + non-goals
+
+- In scope: the variant mechanism at registration time; the informal German variant of the auth
+  bundle; keys for the hard-coded strings above (de/en/fr at least, plus every locale the bundles
+  already carry).
+- Explicit non-goals / do-not-touch:
+  - Default behaviour for existing consumers stays formal German — no consumer changes wording
+    without opting in.
+  - Behavioural fixes of those screens are `UCM-AUTH-9`.
+
+## Tier · gates
+
+- **Tier 3** — change inside shared-core, a new public option on the registration export.
+- Reviewer: `reviewer` (all lenses) · `ui_reviewer`.
+- **Done means released and jg-ferien's pin bumped with the option set** (separate jg step).
+
+## Risks
+
+- A variant that only covers some keys silently falls back to "Sie" for the rest; a test must prove
+  key parity between the two German variants.
+- Consumers that already override ucm keys locally must keep working (override order unchanged).
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the orchestrator's run is the gate)
+
+1. Registering with the informal option yields "du" strings for the auth pages; without it, today's
+   strings.
+2. Key parity: formal and informal German cover the same key set.
+3. `UserListComponent` and the invite panel render no hard-coded English (render in `de`, assert the
+   listed strings are absent and translated keys present).
+4. Four-locale shape test (`I18N-3`) still passes for the new keys.
+
+---
+
+# B. Implementation map — filled by the Orchestrator — ADDRESSED TO THE IMPLEMENTER
+
+## Context package — two independent parts
+
+### 1. The variant mechanism + the informal auth bundle
+
+- **What "registers the kit's strings" means today, concretely** (so the mechanism plugs into the
+  real thing, not a hypothetical): every consuming app's own `i18n/index.js` imports the named
+  bundle exports (`authTranslations`, `messagingTranslations`, …) or the single aggregate
+  `uiCoreTranslations` (`src/i18n/uiCoreTranslations.js`, built by `I18N-1`) and spreads them into
+  its own i18next `resources` object — see `jg-ferien/frontend/i18n/index.js` for the exact pattern
+  (not this repo; read it for reference only, do not edit it — jg's own pin-bump/adoption is a
+  separate step, out of this WO). **No app currently imports `uiCoreTranslations` itself** (checked
+  — only per-feature bundles are imported today), so changing how the aggregate is BUILT carries no
+  live migration risk.
+- **Do not change `uiCoreTranslations`'s existing shape or behaviour** — `tests/i18nAggregate.test.js`
+  (`I18N-1`/`I18N-3`) asserts it is byte-identical to the plain merge of the 7 per-feature bundles;
+  breaking that assertion is not this WO's job. Add a NEW function alongside it instead:
+  ```js
+  // src/i18n/uiCoreTranslations.js — ADD this export, keep the existing `uiCoreTranslations` export unchanged
+  export function createUiCoreTranslations({ germanVariant = 'formal' } = {}) {
+    return Object.fromEntries(
+      Object.entries(uiCoreTranslations).map(([key, value]) => {
+        const { de_informal, ...rest } = value;
+        if (germanVariant === 'informal' && de_informal) return [key, { ...rest, de: de_informal }];
+        return [key, rest];
+      }),
+    );
+  }
+  ```
+  This is "the single export a consumer picks a variant with" (the Envelope's phrase) — a future jg
+  adoption step calls `createUiCoreTranslations({ germanVariant: 'informal' })` instead of spreading
+  `uiCoreTranslations` directly; every OTHER existing consumer is completely unaffected (they don't
+  call this function at all, and `uiCoreTranslations` itself is untouched) — this is what "no
+  consumer changes wording without opting in" means mechanically.
+- **The informal German variant itself** — add a sibling `de_informal` field to the `de` value of
+  every key in `src/i18n/authTranslations.ts` where the FORMAL wording actually depends on
+  Sie/Ihr-form address. Do NOT add `de_informal` to a key whose German text has no such dependency
+  (e.g. "E-Mail-Adresse", "Passwort", "QR-Token" read identically either way) — the function above
+  already falls back to the formal `de` value when `de_informal` is absent, so omitting it there is
+  correct, not incomplete.
+  - Find every Sie-dependent key with a word-boundary scan of each entry's `de` value against
+    `\bSie\b|\bIhr\b|\bIhre\b|\bIhrem\b|\bIhren\b|\bIhrer\b|\bIhres\b` (covers "Sie", "Ihr(e/em/en/er/es)"
+    in all inflected forms) — this repo already has one page that MIXES both forms today
+    (`Auth.MFA_RECOVERY_TITLE`'s description at `authTranslations.ts` uses "du" while
+    `Auth.PAGE_INVITE_SUBTITLE` uses "Sie" — measured, not hypothetical), so a plain "does the file
+    already use du sometimes" check is not sufficient; use the regex scan.
+  - For each matched key, write a natural informal ("du"/"dein"/"dir"/imperative-du) rewording as
+    `de_informal`, keeping the same meaning, placeholders (`{{email}}` etc. must appear identically),
+    and punctuation style as the formal version. This is a real translation task — this is a
+    shared-core kit that already ships a disclosed machine-translated Swahili bundle (`I18N-3`); do
+    the same here: **disclose in your final `RESULT:` line that the informal wording was machine-
+    translated by you (the implementing model), not reviewed by a fluent German speaker**, exactly
+    as `I18N-3` did for Swahili. Do not silently imply human review.
+- **Test file:** extend `tests/i18nAggregate.test.js` (it already imports `uiCoreTranslations` and
+  the per-bundle exports — read it first) or add a new `tests/i18nGermanVariant.test.js`, covering:
+  1. For a representative key (e.g. `Auth.PAGE_INVITE_SUBTITLE`),
+     `createUiCoreTranslations({ germanVariant: 'informal' }).['Auth.PAGE_INVITE_SUBTITLE'].de`
+     is the informal wording and does NOT match the Sie-form regex; the default call
+     (`createUiCoreTranslations()`, no argument) returns the SAME `de` value as plain
+     `uiCoreTranslations['Auth.PAGE_INVITE_SUBTITLE'].de` (today's formal string, unopted-in
+     consumers see no change).
+  2. **The real parity guard the Risk note asks for:** scan `authTranslations` for every key whose
+     `de` matches the Sie-form regex above, and assert EACH such key has a non-empty `de_informal`
+     that does NOT itself match the Sie-form regex (proves it was actually rewritten, not copied).
+     This is the test that would fail if a future key were added with formal wording only and
+     forgotten — the actual failure mode the Envelope's Risk names, not a generic "same key set"
+     check (which would be trivially true by construction here and prove nothing).
+  3. Four-locale shape test (`I18N-3`, `tests/i18nAggregate.test.js`'s existing
+     `REQUIRED_LOCALES = ['de','en','fr','sw']` check) still passes — it iterates `uiCoreTranslations`
+     itself, which is unchanged; run it to confirm, do not edit it.
+  4. Existing consumers unaffected: `uiCoreTranslations['Auth.PAGE_INVITE_SUBTITLE']` (the plain,
+     unchanged export) still equals exactly what it did before this WO — read from
+     `authTranslations.ts` directly, minus the new `de_informal` field which existing code never
+     reads.
+
+### 2. Hard-coded English in `UserListComponent`, `UserInviteComponent`, `BulkInviteCsvTab`
+
+- **Every string named in the Envelope's Context already uses `t(key, englishDefault)`** — the
+  translation KEYS are already referenced in the JSX, they are simply missing from every bundle, so
+  `t()` silently falls through to the English default regardless of locale. **In almost every case
+  the fix is adding the bundle entry, not touching the component.** Add these keys to
+  `src/i18n/authTranslations.ts` (all four locales it already carries: de/en/fr/sw — plain, correct
+  translations, NOT the informal-German mechanism from part 1, this is unrelated hard-coded-string
+  work):
+  - From `src/components/UserListComponent.jsx` (verified against the file, line refs current):
+    `UserList.DELETE_CONFIRM` (`:93`), `Common.OPERATION_FAILED` (`:278`), `UserList.NEW` (`:313`),
+    `UserList.SUCCESSFUL_LOGIN` (`:331`), `UserList.ROLE` (`:349`), `Common.ACTIONS` (`:398`),
+    `UserList.TITLE` (`:503`), `Common.SEARCH` (`:509`), `UserList.SEARCH_PLACEHOLDER` (`:510`),
+    `UserList.NO_USERS` (`:560`). (`Common.YES`/`Common.NO`/`Common.DELETE`/`Auth.EMAIL_LABEL`/
+    `Profile.NAME_LABEL` already exist — do not re-add them.)
+  - **One genuine code change, not just a bundle entry:** the `<TablePagination>` at `:581` has no
+    localisation props at all — MUI supplies its own English default "Rows per page:" directly, it
+    is not reachable via `t()` today. Add `labelRowsPerPage={t('UserList.ROWS_PER_PAGE', 'Rows per
+    page:')}` to that element, plus the new `UserList.ROWS_PER_PAGE` bundle entry.
+  - From `src/components/UserInviteComponent.jsx`: `Auth.INVITE_SENT_SUCCESS` (`:29`, `:104` in
+    `BulkInviteCsvTab.jsx` too — shared key), `Auth.INVITE_TITLE` (`:43`). (`Auth.EMAIL_LABEL`,
+    `Auth.INVITE_BUTTON` already exist.)
+  - From `src/components/BulkInviteCsvTab.jsx`: `Account.BULK_INVITE_NO_EMAILS` (`:82`),
+    `Account.BULK_INVITE_PARSE_FAILED` (`:87`), `Account.BULK_INVITE_DONE` (`:117`, has `{{ok}}`/
+    `{{total}}` interpolation — keep both placeholders in every locale), `Account.BULK_INVITE_TITLE`
+    (`:129`), `Account.BULK_INVITE_HINT` (`:132-135`, multi-line `t()` call — easy to miss with a
+    single-line grep, it IS in scope), `Account.BULK_INVITE_UPLOAD` (`:143`),
+    `Account.BULK_INVITE_SEND` (`:147`), `Account.BULK_INVITE_COUNT` (`:150`, `{{count}}`),
+    `Common.STATUS` (`:166`), `Common.DETAILS` (`:167`), `Account.BULK_INVITE_PROGRESS` (`:190`,
+    `{{done}}`/`{{total}}`), `Account.BULK_INVITE_SUCCESS_COUNT` (`:192`, `{{count}}`).
+    (`Auth.EMAIL_LABEL`, `Common.SUCCESS`, `Common.ERROR` already exist.)
+  - **`UCM-AUTH-9` already landed** (earlier in this release's sequence) and touched this SAME
+    file: it added `UserList.ROLE_UPDATE_SUCCESS` (already present, all four locales — do not
+    re-add it) and, after its own review, reused the pre-existing `Auth.SELF_SIGNUP_DISABLED` key
+    for the closed-signup message rather than adding a new `Auth.SIGNUP_CLOSED` key (that key does
+    NOT exist — do not look for it or add it).
+- Test file: extend `tests/UserListComponent`/`UserInviteComponent`/`BulkInviteCsvTab` tests if they
+  exist (grep `tests/`), or add focused new ones:
+  1. Render each of the three components with `i18n.language = 'de'` (or however this repo's test
+     harness sets locale — check an existing test that asserts translated text, e.g.
+     `tests/authTranslations.test.js`, for the pattern) and assert NONE of the literal English
+     default strings listed above are present, and the translated (German) text IS present.
+  2. Four-locale shape test (`i18nAggregate.test.js`) still passes for every new key.
+
+## Do-not-touch / invariants
+
+- Default behaviour for existing consumers stays formal German — `uiCoreTranslations` itself must
+  not change; only the new `createUiCoreTranslations` function is variant-aware.
+- Behavioural fixes of the auth screens are `UCM-AUTH-9`'s scope, not this one — this WO only adds
+  strings/keys and the variant mechanism, it does not change component logic (aside from the one
+  named `labelRowsPerPage` prop addition, which is not a behaviour change).
+- No secrets, no dependency changes — everything here is data (translation bundles) plus one small
+  pure function.
+
+## Target repo working directory (absolute)
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`)
+
+## Preamble — a REQUIRED block IN this file, not something appended at invocation
+
+> The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there
+> is no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and the
+> app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
+> unless the spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md` — the register
+> row and the review verdicts are the orchestrator's alone.** **Your tools are for editing source
+> and test files and for running the tests you wrote — nothing else.** Do NOT install dependencies,
+> touch a lockfile, run a package manager, or tidy up stray files; if something in the repo state
+> blocks you, stop and report it as `RESULT: BLOCKED <reason>` instead of fixing it. Do NOT
+> `git add`/`commit`/`push` — leave every
+> change uncommitted in the working tree for the orchestrator's independent review. WRITE the tests
+> the `Required tests` section calls for AND **RUN the tests you just wrote** to confirm they execute
+> and pass — that is the ONLY test run you do (NOT the app's affected/full suite, NOT any review).
+> The orchestrator re-runs the authoritative set + does the independent review after you finish —
+> those are the gate; your own run does not count as the gate.
+>
+> Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+> `PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+> completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+> `RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+# C. Orchestrator only — NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this work order as your own specification: STOP at this line.
+> Everything below describes what the Orchestrator does AFTER you finish. You do none of it — no
+> reviewers, no verification run, no register edit, no commit.**
+
+*(to be filled by the Orchestrator: execution directive; `reviewer` (all lenses) + `ui_reviewer`; release; jg-ferien pin bump with the informal option; register rows here and in jg (`JG-UX-10`).)*

package/work-orders/UCM-MSG-20.md

@@ -0,0 +1,192 @@
+# UCM-MSG-20 — Message composer collapses on narrow screens
+
+# A. Envelope — authored by the Expertenchat
+
+## Goal & expected outcome
+
+- Goal: on a 375 px phone a person can type and send a message in every conversation type.
+- Expected outcome:
+  - The text field keeps a usable width (at least most of the row) next to the action icons; the send
+    button is fully visible.
+  - URLs in messages are clickable links.
+  - The read marker next to the time explains itself (label or tooltip), or is not shown where it
+    carries no information.
+
+## Context — measured 2026-09-29 in jg-ferien's local browser test (ucm 3.5.0 installed there)
+
+- jg-ferien, event announcement conversation, 375 px: next to four icon buttons (attach, emoji, poll,
+  announce) the textarea is **16 px** wide (its field 44 px), "Senden" is clipped (44 px), the row
+  overflows (315 of 295 px).
+- Component: `src/messaging/Composer.jsx` (row layout incl. the four icon buttons,
+  `allowAnnouncement` prop); `src/messaging/MessageBubble.jsx` shows a bare "0/0" next to the time.
+- Long words and URLs wrap correctly inside the bubble; URLs are plain text.
+- The dcm register is canonical for `MSG-*`; this is the ucm-side row.
+
+## Scope + non-goals
+
+- In scope: composer layout at narrow widths (e.g. actions collapse into one menu, or wrap to their
+  own row), linkified URLs, an explained or hidden read marker.
+- Explicit non-goals / do-not-touch:
+  - No change to message sending, polls or announcements behaviour.
+
+## Tier · gates
+
+- **Tier 3** — shared-core component.
+- Reviewer: `reviewer` (all lenses; linkify is new logic) · `ui_reviewer` · `sec_reviewer` (linkify
+  must not create script or `javascript:` links).
+- **Done means released and jg-ferien's pin bumped.**
+
+## Risks
+
+- Linkify is an injection surface: only `http(s)` URLs, `rel="noopener noreferrer"`, no HTML from
+  message text.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the orchestrator's run is the gate)
+
+1. At 375 px width the textarea has at least a defined minimum width and the send button is not
+   clipped, with all four actions enabled.
+2. `https://…` in a message renders as a link; `javascript:…` does not.
+3. The read marker has an accessible label or is absent.
+
+---
+
+# B. Implementation map — filled by the Orchestrator — ADDRESSED TO THE IMPLEMENTER
+
+## Context package — three independent fixes, same file family
+
+### 1. Composer overflow at narrow widths — `src/messaging/Composer.jsx`
+
+- The single overflowing row is at line 139:
+  `<Stack direction="row" spacing={1} alignItems="flex-end">` — it holds, in order: the hidden file
+  `<input>`, 4 `IconButton`s (attach `:141`, emoji `:142`, poll `:143`, announce `:144` conditional
+  on `canAnnounce`), the `TextField` (`:145`, `fullWidth multiline minRows={2}`), and the Send
+  `Button` (`:146`).
+- **Fix: split into two stacked rows, not one collapsing menu** (the WO's "or wrap to their own
+  row" option — simplest, lowest-risk, no new interaction pattern to test):
+  1. First row: a `<Stack direction="row" spacing={1}>` containing only the icon buttons (attach,
+     emoji, poll, and the conditional announce button) — 3–4 icon buttons at ~40px each comfortably
+     fit 375px on their own.
+  2. Second row: `<Stack direction="row" spacing={1} alignItems="flex-end">` containing only the
+     `TextField` and the Send `Button`.
+  3. Give the `TextField` `sx={{ flex: 1, minWidth: 120 }}` (so it never collapses to near-zero
+     width when squeezed) and the Send `Button` `sx={{ flexShrink: 0 }}` (so it is never the thing
+     that gets clipped — it should shrink last, if at all).
+  4. Everything else in the file (state, handlers, the poll/announcement dialogs, the emoji
+     popover) is unchanged — this is a pure JSX layout restructure of one `Stack`.
+- Test file: extend `tests/messagingComposer.test.jsx` (existing — read it first for the render
+  harness/mock-provider pattern already in use, follow it exactly rather than inventing a new one).
+  Add: render the `Composer`, resize the test's container is not meaningful in jsdom (no real
+  layout), so instead assert via computed style: the `TextField`'s wrapping element has
+  `minWidth: '120px'` (or your chosen value) and the Send button's element has `flexShrink: '0'` —
+  both readable via `window.getComputedStyle`, same technique as
+  `tests/StatTile.test.jsx`'s `accent` test. Also assert all four action buttons
+  (`MessagingComposer.ADD_ATTACHMENT`/`ADD_EMOJI`/`MessagingPoll.CREATE`/
+  `MessagingAnnouncement.CREATE` — pass `allowAnnouncement` + a non-`direct` `conversation` prop to
+  exercise the fourth) are present and not `disabled` (aside from the poll button's existing
+  `pollOpen || files.some(isImage)` guard, unrelated to this WO).
+
+### 2. Linkify `http(s)` URLs — new file `src/messaging/linkifyText.jsx`
+
+- No linkify library exists in this repo's dependencies today (checked — do not add one; a
+  dependency addition needs separate approval this WO does not have, and the requirement is narrow
+  enough not to need one).
+- Export a pure function `linkifyText(text)` returning an array of strings and `<a>` React elements
+  (a `key`ed fragment-safe array, the same shape `.map()` output must have). URL matching: a strict
+  **`http://` or `https://` prefix only** — e.g.
+  `/(https?:\/\/[^\s<>"']+)/g` — so a `javascript:`, `data:`, or any other scheme can never match
+  the pattern in the first place (that is the actual security property the sec_reviewer will check
+  for — not an escaping step, an inclusion-list pattern that structurally cannot match anything
+  else). Split `text` on that pattern; for each URL match render
+  `<a href={url} target="_blank" rel="noopener noreferrer">{url}</a>`; non-matching segments pass
+  through as plain strings (React renders an array of strings/elements fine as children).
+- Trim likely trailing punctuation that is prose, not part of the URL (a trailing `.`, `,`, `)`,
+  `!`, `?` immediately followed by a word boundary or end of string) so `"see https://x.com."` does
+  not link the sentence-ending period — check `tests/` for whether any existing kit code already
+  does this trimming (grep `messagingContractConformance` / `messagingApi` tests for a URL-trimming
+  precedent) before inventing your own rule; if none exists, a simple trailing-punctuation strip is
+  sufficient, name it in your `PROGRESS` narration.
+- Wire it into `src/messaging/MessageBubble.jsx:149` — the `<Typography sx={{ whiteSpace:
+  'pre-wrap', overflowWrap: 'anywhere' }}>{...}</Typography>` that renders the message body: replace
+  the raw string child with `linkifyText(<same expression>)` for the non-deleted, non-empty case
+  (deleted messages keep rendering `t('MessagingThread.DELETED')` as plain text, unlinkified).
+- Test file: new `tests/messagingLinkify.test.jsx` (or extend an existing `MessageBubble` test if
+  one already covers body rendering — check `tests/messagingChunk6.test.jsx` and
+  `tests/messagingCompactBubble.test.jsx` first).
+  1. A message body containing `https://example.com/path` renders an `<a>` with that exact `href`,
+     `target="_blank"`, and `rel="noopener noreferrer"`.
+  2. A message body containing the literal text `javascript:alert(1)` renders it as plain text —
+     assert `screen.queryByRole('link')` is `null` and the literal string is present as text.
+  3. A message body containing both a URL and surrounding prose renders the prose as plain text
+     and only the URL portion as a link (i.e. the split doesn't eat the surrounding words).
+
+### 3. Read marker explains itself — `src/messaging/ReadTicks.jsx`
+
+- Both existing branches already set `aria-label` (line 74's `<span role="img">`/`<ButtonBase>` for
+  the counted case, line 80's `<StatusIcon role="img">` for the DM case) — that covers screen
+  readers, but `aria-label` is invisible to a SIGHTED user looking at a bare "0/0", which is the
+  Envelope's actual complaint ("explains itself (**label or tooltip**)" — the current label is
+  ARIA-only, not a visible one).
+- Fix, at the `hasCounts` branch (line 56 onward): wrap the returned ratio element in MUI's
+  `Tooltip` (already imported patterns exist elsewhere in the kit, e.g. `UserListComponent.jsx`'s
+  `<Tooltip title={...}>`) using the same `label` text as the `title`, so hovering explains it
+  visually too. Import `Tooltip` from `@mui/material` at the top of the file (currently only
+  imports `List, ListItem, Popover, Typography, ButtonBase`).
+- Additionally: when `status.recipient_count === 0` (a message with literally nobody to read it —
+  "0/0" carries no information per the Envelope's alternative: "or is not shown where it carries no
+  information"), return `null` before rendering the ratio, same early-return style already used at
+  line 41 (`if (!status) return null;`) and line 50 (`if (!hasCounts && conversation?.kind !==
+  'direct') return null;`).
+- Do NOT change the DM branch (line 78–80) — it already carries a real icon-shape + colour +
+  aria-label signal (not a bare number), out of this fix's actual complaint.
+- Test file: extend `tests/messagingReadTicks*.test.*` if one exists (grep `tests/` for
+  `ReadTicks`); otherwise create `tests/messagingReadTicksTooltip.test.jsx`.
+  1. With `read_count: 2, recipient_count: 5`, assert a `title` attribute (MUI `Tooltip` renders
+     one on the wrapped element before hover, or use `@testing-library/user-event` to hover and
+     assert the tooltip text appears — follow whatever pattern this repo's other `Tooltip` tests
+     already use, grep for one) explaining the ratio is present.
+  2. With `recipient_count: 0`, assert the component renders nothing (e.g. `container.textContent`
+     is empty, or the specific test id/role used elsewhere for "renders null" assertions in this
+     test suite).
+
+## Do-not-touch / invariants
+
+- No change to message sending, polls, or announcements behaviour (Envelope non-goal) — items 1–3
+  above are the complete scope; do not touch `submit`/`submitPoll`/`submitAnnouncement`.
+- `sec_reviewer` will specifically check the linkify regex cannot match a non-`http(s)` scheme —
+  keep the pattern an explicit `https?://` prefix, never a generic "looks like a URL" heuristic.
+
+## Target repo working directory (absolute)
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`)
+
+## Preamble — a REQUIRED block IN this file, not something appended at invocation
+
+> The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there
+> is no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and the
+> app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
+> unless the spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md` — the register
+> row and the review verdicts are the orchestrator's alone.** **Your tools are for editing source
+> and test files and for running the tests you wrote — nothing else.** Do NOT install dependencies,
+> touch a lockfile, run a package manager, or tidy up stray files; if something in the repo state
+> blocks you, stop and report it as `RESULT: BLOCKED <reason>` instead of fixing it. Do NOT
+> `git add`/`commit`/`push` — leave every
+> change uncommitted in the working tree for the orchestrator's independent review. WRITE the tests
+> the `Required tests` section calls for AND **RUN the tests you just wrote** to confirm they execute
+> and pass — that is the ONLY test run you do (NOT the app's affected/full suite, NOT any review).
+> The orchestrator re-runs the authoritative set + does the independent review after you finish —
+> those are the gate; your own run does not count as the gate.
+>
+> Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+> `PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+> completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+> `RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+# C. Orchestrator only — NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this work order as your own specification: STOP at this line.
+> Everything below describes what the Orchestrator does AFTER you finish. You do none of it — no
+> reviewers, no verification run, no register edit, no commit.**
+
+*(to be filled by the Orchestrator: execution directive; `reviewer` (all lenses) + `ui_reviewer` + `sec_reviewer`; release; jg-ferien pin bump and 375 px check in an event conversation; register rows here, in dcm (MSG canonical) and in jg (`JG-UX-14`).)*

package/work-orders/UCM-PRIM-2.md

@@ -0,0 +1,114 @@
+# UCM-PRIM-2 — A shared empty-state primitive
+
+# A. Envelope — authored by the Expertenchat
+
+## Goal & expected outcome
+
+- Goal: every "nothing here yet" in a consuming app looks and reads the same.
+- Expected outcome: `EmptyState` in the kit — an optional icon, one line of text, an optional secondary
+  line and an optional action — built from theme tokens, accessible (text reachable by screen
+  readers, action a real button).
+
+## Context — measured 2026-09-29 in jg-ferien's local browser test (ucm 3.5.0 installed there)
+
+- jg-ferien's 15 event sections show "empty" in **seven** ways (plain text, card, blue info alert,
+  card with title, filled green card, alert inside a green card, nothing at all). No shared component
+  exists in jg or ucm; jg has only a song-search special case.
+- **Operator decision 2026-09-29: generic goes to ucm.** jg adopts it in `JG-UX-9`.
+- `PRIM-1` promoted `StatTile`/`SoftChip` along the same lines.
+
+## Scope + non-goals
+
+- In scope: the component, its export, a story or docs entry, tests.
+- Explicit non-goals / do-not-touch: no adoption in consumers here; no change to `Alert` styling.
+
+## Tier · gates
+
+- **Tier 3** — new public export in shared-core (additive).
+- Reviewer: `reviewer` (all lenses) · `ui_reviewer`.
+- **Done means released; jg adoption is `JG-UX-9`.**
+
+## Risks
+
+- A too-flexible API reintroduces the seven variants; keep the props minimal.
+
+## Required tests to WRITE (you write them and run YOUR OWN new ones; the orchestrator's run is the gate)
+
+1. Renders text only; with secondary line; with action (button with accessible name).
+2. Uses theme tokens (no literal colours; the kit's literal guard passes).
+
+---
+
+# B. Implementation map — filled by the Orchestrator — ADDRESSED TO THE IMPLEMENTER
+
+## Context package
+
+- New file `src/components/EmptyState.jsx`. Model it on the existing primitives
+  `src/components/StatTile.jsx` and `src/components/SoftChip.jsx` — a small functional component,
+  default export, built from `Box`/`Typography`/`Button` (MUI), theme tokens only (no literal
+  colours — `reportOffPaletteColours` in `src/theme/themeCompleteness.js` scans every source file
+  for off-palette hex/rgb/named colours and is part of the kit's literal guard the Required Tests
+  reference).
+- Props (keep minimal per the Risk note — do not over-generalise):
+  `icon` (optional, a rendered MUI icon element, e.g. `<InboxOutlinedIcon />`), `title` (string,
+  required — the one line of text), `description` (optional secondary line), `action` (optional
+  `{ label, onClick }` — rendered as a real `<Button variant="outlined">`, not a link, so it is
+  reachable and operable like `StatTile`'s children slot), `sx` (optional passthrough, MUI
+  convention used throughout the kit, e.g. `Composer.jsx`'s `COMPOSER_EMOJI_BUTTON_SX` pattern).
+- Export it from `src/index.js` next to the other components section (`--- 5. Components ---`,
+  after `SoftChip` at line 65): `export { default as EmptyState } from './components/EmptyState';`.
+- Accessibility: `title` must be real text content (not just an `aria-label`), so a screen reader
+  reads it as part of document flow; if `icon` is passed, it must not need its own label (decorative
+  — rely on the adjacent text, matching how `StatTile` treats its icon-less design).
+- Test file: `tests/EmptyState.test.jsx`, following `tests/StatTile.test.jsx`'s pattern exactly —
+  `@vitest-environment jsdom`, wrap in `<ThemeProvider theme={createAppTheme(...)}>`, `cleanup()`
+  in `afterEach`.
+  - Render text-only, with `description`, with `action` (assert the button has an accessible name
+    matching the label and that clicking it calls the passed `onClick`).
+  - The "theme tokens only" requirement: either call `reportOffPaletteColours([{ path: 'src/components/EmptyState.jsx', source: fs.readFileSync(...) }])` (see how `themeCompleteness.js` self-tests, or grep existing callers of `reportOffPaletteColours` in `tests/` for the established pattern) and assert `findings` is empty, or (simpler, sufficient) just don't use any hex/rgb/named-colour literal in the component at all and note in a comment that the guard is structural, not a runtime assertion in this test. Prefer calling `reportOffPaletteColours` directly if an existing test already does — grep `tests/*.test.*` for `reportOffPaletteColours` to find the precedent and match its call shape exactly.
+
+## Do-not-touch / invariants
+
+- Do not add `EmptyState` to `kitSxRegistry.js` unless you export a top-level `sx` object constant
+  from the component (only needed if the root element gets kit-owned baked-in styling beyond plain
+  `sx` passthrough — for this minimal component you likely don't need one; only add a registry entry
+  if you do add such a constant).
+- No adoption anywhere in this repo's own consumers (`AccountPage`, etc.) — out of scope per the
+  Envelope's non-goals.
+- Do not touch `Alert` styling anywhere.
+
+## Target repo working directory (absolute)
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha` (branch `main`)
+
+## Preamble — a REQUIRED block IN this file, not something appended at invocation
+
+> The text above is the COMPLETE spec — the committed WO file's content, not a plan to refine; there
+> is no separate plan file. Read the nearest `AGENTS.md`, the relevant `.codex/skills/<role>/SKILL.md`, and the
+> app `MEMORY.md` ONLY for conventions. Stay in scope; do not touch auth/permissions/deps/schema/CI
+> unless the spec says so; do not update `MEMORY.md`. **Do NOT edit `WORK_ORDERS.md` — the register
+> row and the review verdicts are the orchestrator's alone.** **Your tools are for editing source
+> and test files and for running the tests you wrote — nothing else.** Do NOT install dependencies,
+> touch a lockfile, run a package manager, or tidy up stray files; if something in the repo state
+> blocks you, stop and report it as `RESULT: BLOCKED <reason>` instead of fixing it. Do NOT
+> `git add`/`commit`/`push` — leave every
+> change uncommitted in the working tree for the orchestrator's independent review. WRITE the tests
+> the `Required tests` section calls for AND **RUN the tests you just wrote** to confirm they execute
+> and pass — that is the ONLY test run you do (NOT the app's affected/full suite, NOT any review).
+> The orchestrator re-runs the authoritative set + does the independent review after you finish —
+> those are the gate; your own run does not count as the gate.
+>
+> Narrate continuously: a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+> `PROGRESS: [<n>/<total>] <present-tense action>` before every relevant action (and `… done` on
+> completion), spaced so no gap exceeds ~2 min, stdout unbuffered, plus exactly one final
+> `RESULT: DONE|BLOCKED <reason>`.
+
+---
+
+# C. Orchestrator only — NOT ADDRESSED TO THE IMPLEMENTER
+
+> **If you are the implementer reading this work order as your own specification: STOP at this line.
+> Everything below describes what the Orchestrator does AFTER you finish. You do none of it — no
+> reviewers, no verification run, no register edit, no commit.**
+
+*(to be filled by the Orchestrator: execution directive; `reviewer` (all lenses) + `ui_reviewer`; release; register row here and cross-reference in jg (`JG-UX-9`).)*