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

package/work-orders/UCM-CHART-8.md

@@ -1,147 +0,0 @@
-# UCM-CHART-8 — Make the chart presets stop producing dead space below the chart
-
-- **Repo:** `ui-core-micha`, branch `main` (shared-core; publishes from `main` without a staging step)
-- **Tier:** 3 — shared-core. Every consuming app inherits the behaviour change.
-- **Status:** planned
-- **Workstream:** `CHART-*` (chart presets)
-- **Files:** `src/components/charts/ScatterChart.jsx`, `BarChart.jsx`, `LineChart.jsx`,
-  `TimeSeriesChart.jsx`, **`ChartFrame.jsx`** — all five destructure `minHeight` **and** `aspect`
-  (verified 2026-08-21) — plus their tests. **Note for the implementer: only `ScatterChart` and
-  `TimeSeriesChart` reference `height` at all.** `BarChart`, `LineChart` and `ChartFrame` never
-  destructure it, so for them the incoherent "pair" exists only via the rest spread into the MUI
-  chart. Do not go looking for a declared `height` prop there.
-
-> **Why.** `minHeight` and `height` are two different things on these presets, and the API lets a
-> caller pass both. `minHeight` lands on the **wrapper `Box`** —
-> `sx={{ width: '100%', minHeight, aspectRatio: aspect }}` (`ScatterChart.jsx:260`, same
-> construction in `BarChart.jsx`) — while `height` sizes the **chart**. When `minHeight > height`,
-> the difference is dead space **below the chart**.
->
-> Measured in `hram` on 2026-08-20:
->
-> | panel | `minHeight` | `height` | dead space |
-> |---|---|---|---|
-> | `StructuralReachabilityPanel` | 420 | 380 | 40 px |
-> | `ExpertTimelinePanel` | 340 | 280 (×2) | 60 px |
-> | `ResultsTimelinePanel` | 320 | 280 | 40 px |
-> | `GroupMetricsPanel` | 300 | **none** | the whole chart is unsized |
-> | Cost, Ratio, Accessibility, Referral, Total | equal | equal | 0 |
->
-> **The equal-value majority is why this survived.** Passing both looks like harmless
-> belt-and-braces and costs nothing when the numbers match, so the pattern spread by copy-paste and
-> nobody noticed the cases where they diverge. It has been diagnosed and fixed **pointwise twice**
-> in hram (`AllocationPerformancePanel.jsx:462-478`, `OptimizationResultsPanel.jsx:928-940`, both to
-> `height={420}`) — with the explanation written as a comment **inside those two files**, where no
-> new panel will ever read it.
->
-> This is not N panel bugs. It is one shared API that permits an incoherent pair, and it will keep
-> recurring for as long as it does. Fixing it here fixes every consumer at once, including the ones
-> nobody sweeps.
-
----
-
-## Part A — Envelope (authoritative WHAT/WHY)
-
-### Goal
-
-A caller can no longer produce dead space by passing `minHeight`. The presets resolve the pair
-themselves, and the incoherent combination becomes impossible rather than merely discouraged.
-
-### Definition of Done
-
-- [ ] **The resolution is three-way, not two-way — `aspect` is the third input and it changes the
-      answer.** Amended 2026-08-21; the original two-way rule would have broken four live call sites.
-      - **`height` present** → it sizes the chart, and the wrapper reserves no more than that.
-      - **No `height`, no `aspect`** → **`minHeight` sizes the chart**, not merely the wrapper.
-        This is what a caller in that shape meant (`GroupMetricsPanel`: `minHeight={300}`, no
-        `height`, no `aspect` — chart unsized today).
-      - **No `height`, but `aspect` present** → **today's behaviour is correct and must not change.**
-        The wrapper is `width: 100%` with `aspectRatio`, so its height derives from its width, and
-        `minHeight` is the floor that stops it collapsing on a narrow viewport. Here `minHeight`
-        means exactly what its name says.
-
-      **Same prop shape, opposite intent** — which is why the rule cannot be stated on
-      `minHeight`/`height` alone.
-- [ ] **`minHeight > height` produces no wrapper padding.** The chart is sized by `height` and the
-      wrapper does not reserve more than the chart occupies. The extra space was never intentional.
-- [ ] **Equal values behave exactly as today** — that is the majority of call sites and they must
-      not shift by a pixel.
-- [ ] **A dev-mode warning names the offending call site** when both are passed and they disagree.
-      Not a throw: a shared package that throws on a prop combination in production breaks a
-      consumer's page over a layout nit.
-- [ ] **JSDoc on every preset that takes it** states in one line what `minHeight` now does, so the
-      next caller does not have to infer it from a comment in a consumer app.
-
-### Deliberately NOT done
-
-- **`minHeight` is not removed from the API.** Removing it is a breaking change to a shared package,
-  which would make every consumer's pin bump a Tier-3 change with a real chance of unnoticed layout
-  regressions — a worse outcome than the defect. Deprecate in the docstring, coerce in the code.
-- No change to chart internals, palettes, axis defaults or `aspect`.
-- No consumer-side sweep in this WO. hram's call-site cleanup is its own follow-up, gated on the pin
-  bump — see below.
-
-### Preconditions and ordering
-
-The fix only reaches hram after **(a)** this lands and publishes and **(b)** hram bumps its
-`@micha.bigler/ui-core-micha` pin. Verify the published version is actually live before the consumer
-bump — this package publishes from `main` with no staging step, so a failed publish is silent until
-a consumer installs it.
-
-### Risks
-
-- **The consumer check is done, and it found something — 2026-08-21.** It was written here as a
-  hypothetical ("a consumer may be relying on the padding as spacing"); the real finding is
-  different and larger. **Four live call sites pass `aspect` together with `minHeight` and no
-  `height`:**
-
-  | call site | props |
-  |---|---|
-  | `hram/AccessGapScatterPanel.jsx:182` | `aspect={1.8}` + `minHeight={320}` |
-  | `fitness-monitor/BodyHistoryPage.jsx:~328` | `aspect="960 / 380"` + `minHeight={320}` |
-  | `fitness-monitor/BodyHistoryPage.jsx:~355` | `aspect="960 / 380"` + `minHeight={320}` |
-  | `fitness-monitor/BodyHistoryPage.jsx:~450` | `aspect="400 / 220"` + `minHeight={220}` |
-
-  These are not relying on padding-as-spacing. They are using `minHeight` **as a floor under an
-  aspect-derived height**, which is legitimate and is what the name promises. The original
-  Definition of Done would have turned all four into fixed-height charts and removed their
-  responsive behaviour. **That is the reason for the three-way rule above**, and it is the case to
-  hold onto when reading the rest of this order.
-
-  Scope note: `survey-renderer` is named above as a consumer to check. **The standalone repo is
-  retired** (2026-07-31); the widget now lives at `survey_app/frontend/packages/survey-renderer`,
-  and neither it nor `cockpit` or `jg-ferien` passes `aspect` to a chart preset. jg's one `aspect=`
-  hit is an `ImageCropDialog`, unrelated.
-- The dev warning must not fire on the equal-value majority, or it becomes noise that trains people
-  to ignore it.
-
-### Tests to WRITE — narrow
-
-- `minHeight` alone, **no `aspect`** → the chart receives that height.
-- **`minHeight` + `aspect`, no `height` → unchanged from today**: the wrapper keeps its
-  `aspectRatio` and `minHeight` stays a floor, and the chart is **not** given a fixed height. This is
-  the four-call-site case in Risks and the one a two-way rule would have broken — **it is the test
-  that has to fail if someone later re-simplifies the resolution.**
-- `minHeight > height` → the chart receives `height` and the wrapper reserves no more than that.
-- `minHeight === height` → byte-identical to the current output.
-- `height` alone → unchanged.
-- The dev warning fires only on the disagreeing pair, and names the values. It must **not** fire on
-  `minHeight` + `aspect` without `height`, which is a legitimate combination.
-
-No full suite.
-
----
-
-## Part B — Implementation map
-
-> **TO BE FILLED BY THE ORCHESTRATOR** on `git pull`. Must carry the preset files with `path:line`
-> anchors (`ScatterChart.jsx:173-174, :260` and the equivalents), the absolute working directory,
-> the progress contract, and the preamble. **Do not dispatch while this placeholder stands.**
-
----
-
-## Part C — Orchestrator-only
-
-> **TO BE FILLED BY THE ORCHESTRATOR.** Review routing (`reviewer` + `ui_reviewer`, full context —
-> Tier 3 shared-core), verification, register maintenance, commit, publish check, and the execution
-> directive with its self-address guard.

package/work-orders/UCM-CHART-9.md

@@ -1,265 +0,0 @@
-# UCM-CHART-9 — `ChartFrame` is a card, not a chart: it must never take a fixed height
-
-- **Repo:** `ui-core-micha`, branch `main` (shared-core; publishes from `main`, no staging step)
-- **Tier:** 3 — shared-core, and this is a **live layout regression in a published version**.
-- **Status:** planned
-- **Workstream:** `CHART-*`
-- **Files:** `src/components/charts/ChartFrame.jsx` and its tests. `chartDefaults.js` only if the
-  resolver needs a second shape — see below; the preset behaviour is correct and must not change.
-
-> **Why — regression, observed on staging after hram bumped to 2.42.0.** `UCM-CHART-8` wired
-> `resolveChartHeight()` through the four chart presets **and through `ChartFrame`**. For the
-> presets that is right. For `ChartFrame` it is not, and the difference is what the box contains.
->
-> In the `minHeight` alone / no `height` / no `aspect` branch, `resolveChartHeight` returns
-> `chartHeight = minHeight`, and `ChartFrame` now applies it:
->
-> ```diff
-> -          minHeight,
-> +          minHeight: wrapperMinHeight,
-> +          height: chartHeight,
-> ```
->
-> **A chart preset's box contains exactly one chart. `ChartFrame`'s box contains a whole card** —
-> title, toolbar, the chart, a legend, footnotes, export links. Turning its `minHeight` floor into a
-> fixed `height` makes the box shorter than its content, the content overflows, and **adjacent cards
-> visibly overlap**: the operator's screenshot shows a card title rendered over the chart of the card
-> above it and three sets of "Export SVG / Export PNG" stacked at different offsets.
->
-> `UCM-CHART-8`'s own Files note recorded that `ChartFrame` "never destructures `height`" — and the
-> implementation then gave it one. The rule was written for presets and applied to a frame.
-
----
-
-## Part A — Envelope (authoritative WHAT/WHY)
-
-### Goal
-
-`ChartFrame` stops setting a fixed `height` on its content box. Its `minHeight` goes back to meaning
-what its name says — a floor that content can exceed. The four chart presets keep `UCM-CHART-8`'s
-three-way resolution unchanged.
-
-### Definition of Done
-
-- [ ] **`ChartFrame` never applies `chartHeight` to its content box.** Its box takes `minHeight` as a
-      floor, as it did before 2.42.0. Whether that is done by not calling `resolveChartHeight` at
-      all, or by giving the resolver an explicit frame shape, is the implementer's call — but
-      `ChartFrame` must not end up with a fixed `height` in any branch.
-- [ ] **A `ChartFrame` whose content exceeds `minHeight` grows.** This is the regression, stated as
-      the acceptance criterion: content taller than the floor must extend the box, never overflow it.
-- [ ] **The four presets are untouched.** `ScatterChart`, `BarChart`, `LineChart`, `TimeSeriesChart`
-      keep `UCM-CHART-8` exactly as it landed — including the `aspect` branch that four live call
-      sites depend on. This WO narrows one consumer of the resolver; it does not revisit the rule.
-- [ ] **`ChartFrame`'s JSDoc is corrected.** 2.42.0 added a paragraph claiming `minHeight`
-      "sizes the content box itself" when there is no `height`/`aspect`. That sentence is the bug in
-      prose form and must go.
-- [ ] **`warnOnHeightMismatch` stays** on `ChartFrame` — a caller passing both is still worth a
-      dev-mode note, even though the frame no longer acts on `height`.
-
-### Non-goals
-
-- Do **not** revert `UCM-CHART-8`. Its preset behaviour is correct and is the fix hram needs; only
-  the frame's participation was wrong.
-- Do not change `resolveChartHeight`'s three-way rule for presets.
-- No consumer-side change in this WO.
-
-### Risks
-
-- **`ChartFrame` is used by every Research card in hram and by other consumers.** The change restores
-  pre-2.42.0 behaviour for it, so the risk is low in direction — but it is still a shared-core
-  publish, and the rendered check below is what proves it.
-- 2.42.0 is `latest` on the registry and carries this regression. Publish 2.42.1 promptly; note in
-  the register that 2.42.0 should not be adopted by a new consumer.
-- **hram's Detailed Results tab is fixed as of 2.42.0** (operator-confirmed, 2026-08-21) — it
-  crashed with React #185 before the bump (`HRAM-RES-29` item 1) and does not any more. What is
-  **not** established is *why*: the plausible mechanism is that deterministic sizing removed a
-  resize-driven `setState` loop, but nobody has traced it.
-  **Consequence for this WO, and the only reason it is mentioned here:** since we do not know what
-  fixed it, we cannot know whether moving `ChartFrame` back toward a floor disturbs it. Re-check the
-  tab after this lands. If the crash returns, that is a finding for `HRAM-RES-29` and a sizing
-  dependency worth understanding — not a reason to undo this fix.
-
-### Tests to WRITE — narrow
-
-- **The regression test:** a `ChartFrame` with `minHeight` and no `height`/`aspect`, containing
-  content taller than `minHeight`, does **not** receive a fixed `height` on its content box.
-- `ChartFrame` with `height` explicitly passed: `height` is still not applied as a fixed box height
-  (the frame is not a chart), and no exception is thrown.
-- The four presets' existing `UCM-CHART-8` tests stay green **unchanged** — if one of them has to be
-  edited, the change has leaked out of `ChartFrame` and that is a stop-and-report.
-
-**Rendered check before the hram pin bump — mandatory, and the reason this WO exists.** The unit
-tests for 2.42.0 were 188 green and said nothing about layout, because they cannot. Before hram's pin
-moves again, the affected cards are checked rendered at 375 px and 1280 px: Sensitivity, Access,
-Access Ladder, Allocation, Optimization. Named in the register note, with the substitution declared
-if capture is unavailable.
-
----
-
-## Part B — Implementation map — ADDRESSED TO THE IMPLEMENTER
-
-### Context package
-
-**Named files to change:**
-- `src/components/charts/ChartFrame.jsx` — the fix (below).
-- `tests/ChartFrame.test.jsx:215-256` — the `describe('minHeight/height resolution (CHART-8)', …)`
-  block. It currently **asserts the bug as correct behaviour** (e.g. `minHeight` alone →
-  `style.height` toBe `'300px'`). Rewrite it to assert the fixed behaviour; rename the block to
-  `(CHART-9)`.
-
-**Do NOT touch (verified against the landed code):**
-- `src/components/charts/chartDefaults.js` — `resolveChartHeight` (lines ~289-298) and
-  `warnOnHeightMismatch` (lines ~306-315) keep their exact current contract. If the fix seems to need
-  a change here, that means the change has leaked out of `ChartFrame` — stop and report, don't edit.
-- `src/components/charts/{BarChart,LineChart,ScatterChart,TimeSeriesChart}.jsx` — all four still call
-  `resolveChartHeight({ minHeight, height, aspect })` for their OWN box, unchanged.
-- `tests/chartDefaults.test.js:441+` (`describe('resolveChartHeight (CHART-8)', …)`) and the four
-  presets' own test files — must stay green **unchanged**. If one needs an edit, stop and report.
-
-**The bug, exactly:** `ChartFrame.jsx:61-62` calls `resolveChartHeight({ minHeight, height, aspect })`
-and applies the result to its content box at `:109-125`:
-```jsx
-sx={{
-  width: '100%',
-  minHeight: wrapperMinHeight,
-  height: chartHeight,
-  aspectRatio: aspect,
-  ...
-}}
-```
-In the "no `height`, no `aspect`" branch, `resolveChartHeight` returns `chartHeight = minHeight` —
-correct for a preset's box (which holds exactly one chart) but wrong for `ChartFrame`'s box (which
-holds a whole card: title, toolbar, chart, legend, footnotes, export links). A fixed `height` there
-makes the box shorter than its content, and the content overflows into the next card.
-
-**What "restore pre-2.42.0 behaviour" means concretely** — before `UCM-CHART-8` (commit `11d362c`),
-`ChartFrame` had no `height` prop at all and its content box was:
-```jsx
-sx={{
-  width: '100%',
-  minHeight,
-  aspectRatio: aspect,
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-}}
-```
-i.e. `minHeight` applied raw, straight from props, never touched by any resolver; no `height` was
-ever set on the box.
-
-**The fix:** `ChartFrame`'s content box must end up equivalent to that — `minHeight` (raw, from
-props) as the box's only height-related sx property besides `aspectRatio`, and nothing ever sets
-`height` on the box. The `height` prop stays in `ChartFrame`'s signature (do not remove it — it is
-still a documented prop and `warnOnHeightMismatch('ChartFrame', { minHeight, height })` at line 61
-must keep firing on a caller passing both `minHeight` and a disagreeing `height`), it is simply no
-longer used to size the box. Whether you implement this by dropping the `resolveChartHeight` call
-from `ChartFrame` entirely (simplest — matches the pre-2.42.0 shape exactly) or by giving the
-resolver a second, frame-specific shape in `chartDefaults.js` that never returns a `chartHeight` is
-your call — but per the non-goals below, the existing `resolveChartHeight` export and its three-way
-preset contract must not change.
-
-**JSDoc fix:** `ChartFrame.jsx:19-26`'s docblock currently states: *"otherwise (no `height`, no
-`aspect`) it sizes the content box itself. Once `height` is set, `height` sizes the box…"* — that
-sentence describes the bug as intended behaviour and must be corrected to state that `minHeight` is
-always a floor on `ChartFrame`'s box and `height` is never applied to it (only used for the
-dev-mode mismatch warning).
-
-**Regression check while you're in there:** hram's Detailed Results tab crashed with React #185
-before the 2.42.0 bump and stopped crashing after it (`HRAM-RES-29` item 1, unconfirmed hypothesis:
-deterministic sizing removed a resize-driven `setState` loop). This fix moves `ChartFrame` back
-toward non-deterministic sizing for that one prop. You are not expected to reproduce or verify the
-hram-side crash — the Orchestrator does that separately after your diff lands — but do not add any
-new resize-driven effect to `ChartFrame` while touching this code.
-
-Work from this package; do not explore broadly from scratch — open only the named files to verify.
-If you must dig deeper, delegate to a read-only Explore sub-agent (Haiku).
-
-### Target repo working directory (absolute)
-
-`C:\Users\Micha Bigler\Documents\webapps\ui-core-micha`
-
-### Preamble — binding, read before doing anything else
-
-The text in this file is the COMPLETE spec — the committed WO 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 this repo's own `MEMORY.md` ONLY for conventions. Stay in scope; do not touch
-auth/permissions/deps/schema/CI unless this 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. 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 to WRITE" section (Part A) 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
-and 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>`.
-
----
-
-## Part 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. You ARE the invocation described
-> below; do NOT shell out to `codex exec`.
-
-### 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`, `cwd` = the working directory above (never
-`…\webapps`). Fallback to direct Claude implementation only on Codex quota/rate-limit/non-zero exit —
-check `.claude/codex-status.md` first per its own rule (no line for 2026-08-22 → use Codex). The
-fallback flips authorship, making an independent `reviewer` mandatory even if it already was.
-
-### Review routing (Tier 3, shared-core)
-
-- `reviewer`: **yes**, full context, Sonnet-pinned, background.
-- `ui_reviewer`: **yes** (diff touches frontend), full context, background, same batch as `reviewer`.
-- `sec_reviewer`: not required — no auth/security surface in this diff.
-- Both run concurrently; neither is skippable; commit waits for both clean.
-
-### Verification (the authoritative run — Codex's own run is not the gate)
-
-1. **Test gate:** `npx vitest run tests/ChartFrame.test.jsx tests/chartDefaults.test.js
-   tests/BarChart.test.jsx tests/LineChart.test.jsx tests/ScatterChart.test.jsx
-   tests/TimeSeriesChart.test.jsx` (adjust filenames to whatever actually exists — the affected-area
-   set per AGENTS.md "Test scope": `ChartFrame` itself plus every consumer of `resolveChartHeight`).
-   All must pass; the four presets' pre-existing assertions must be **byte-identical**, not just
-   green — a changed preset assertion means the fix leaked scope.
-2. **Rendered check — this WO's own commit gate, scoped to what this repo can render.** This repo
-   has no prototype artifact, so the generic prototype side-by-side gate does not apply; this WO's
-   own Envelope names a rendered check instead, and it is honoured here at the scope this repo can
-   actually reach:
-   - Run `npm run dev` (Vite) and open the dev harness at 375 px and 1280 px. It already contains
-     `ChartFrame` "shape check" stories that mirror three of the five named hram cards — "Allocation
-     performance", "Access gap", "Optimization results" (`dev/entries.jsx`, search `shape check`).
-     Confirm none of them, nor any neighbouring card, show overlapping title/content/export rows at
-     either width.
-   - Additionally render (ad hoc, in the same dev session — e.g. a temporary story or by editing an
-     existing one's children) a `ChartFrame` with a `minHeight` smaller than its actual content, to
-     directly exercise the Definition of Done's acceptance criterion: the box must grow to fit the
-     content, not overflow it. Revert any temporary dev-harness edit before commit (or keep it only
-     if it's a genuine permanent addition worth keeping — your call, but say which in the Notiz).
-   - This repo's harness has no "Sensitivity" or "Access Ladder" story, so the **full five-card
-     rendered check the Envelope describes ("before hram's pin moves again") is NOT done by this WO**
-     — it cannot be, without linking a built `ui-core-micha` into a running hram dev server. Declare
-     this explicitly in the register Notiz as a carried-forward precondition on whichever WO next
-     bumps hram's pin past 2.42.0, not a silently dropped gate.
-   - Declare screenshots-vs-DOM-inspection substitution explicitly if real screenshots aren't taken.
-
-### Register + commit
-
-- `WORK_ORDERS.md` row → `done`, with: the named review verdicts (`reviewer` + `ui_reviewer`, no
-  open findings — or the findings and their resolution), the test gate result, the rendered-check
-  scope actually achieved (dev harness only, full hram five-card check carried forward), and which
-  evidence from `.claude/codex-status.md` was used (or that no fallback was needed).
-- Note in the Notiz: **publish 2.42.1 promptly after commit** (per Part A Risks — 2.42.0 is `latest`
-  on the registry and carries this regression) and confirm the version bump lands in the same commit
-  or a clearly-linked follow-up; the register row must name whichever it was.
-- Commit message: single concise English subject line (e.g. `fix(ChartFrame): stop applying a fixed
-  height to the card box (CHART-9)`). Push to `main` (this repo publishes from `main`, no `develop`
-  step) once review + tests are clean.

package/work-orders/UCM-CHAT-1.md

@@ -1,190 +0,0 @@
-# UCM-CHAT-1 — Shared AI chat surface: chat list, streaming thread, sources, model and effort picker
-
-Prepared: 2026-10-15. Target repository: `ui-core-micha` (`main`). Backend counterpart and transport contract: `django-core-micha/DCM-CHAT-1`. First consumer: `cockpit/CP-CHAT-4`.
-
-# A. Envelope — addressed to everyone
-
-## Goal and expected outcome
-
-`django-core-micha/DCM-CHAT-1` adds a shared AI chat core with a fixed WebSocket and REST contract. This order adds the matching surface to ui-core-micha, so that an app shows a complete chat by mounting one component. maana's chat UI (`maana/frontend/src/qda/assistant/`) is the functional template, without its proposals, grants and plan views.
-
-Expected outcome: ui-core-micha exports a chat workspace that lists the user's chats (with archive), streams answers into a thread, renders Markdown safely, shows the sources each answer used, and lets the user pick model and effort per chat. The parts are also exported individually so that an app can arrange them differently.
-
-## Visual spec
-
-Prototype: [`work-orders/assets/UCM-CHAT-1-ai-chat.html`](assets/UCM-CHAT-1-ai-chat.html), drawn in cockpit's theme as the first consumer. It shows:
-- at 1280 px, the main working state;
-- at 375 px, the thread, the chat list drawer and the model picker sheet;
-- a 1280 px gallery of the edge states.
-
-The prototype declares its coverage at the top. The built components take every colour, type and radius from the consuming app's MUI theme, never from literals.
-
-**Parity guardrail:** the prototype governs the look and the interaction only. Behaviour, permissions and the data contract come from `DCM-CHAT-1` and are not changed by anything drawn here.
-
-## Operator decisions this Envelope records (2026-10-15)
-
-- Several persistent chats per user, in a list. Each chat can be renamed, archived and deleted. Archived chats sit behind an "Archived" entry with a count, open read-only, and can be restored.
-- Model and effort are chosen per chat, from the app's catalogue. The picker groups the entries by driver and marks pay-per-use entries. A change applies from the next turn, and the thread marks where the model changed.
-- The sources of each answer appear as chips under it. A chip shows the source's short label, and the full reference appears on hover.
-- A prototype was requested and is the visual spec.
-
-## Scope
-
-- **Workspace component.** At wide widths it has a list column and a thread column. At narrow widths the list becomes a drawer and the picker a bottom sheet; the prototype shows the 375 px arrangement.
-- **Chat list:**
-  - new chat;
-  - select a chat;
-  - per-row overflow menu with Rename, Archive and Delete;
-  - Delete asks for confirmation inside the UI;
-  - the archived section with its count;
-  - restore an archived chat.
-- **Thread:**
-  - user messages;
-  - assistant answers rendered as Markdown, streamed live from `delta` frames;
-  - a typing indicator before the first delta;
-  - a tool-activity chip while a tool runs, labelled with the tool's own label from the `tool` frame;
-  - source chips once the turn completes;
-  - a quiet model and effort line under each answer;
-  - a divider where the model changed between turns;
-  - older turns loaded by cursor when scrolling up.
-- **Composer:** a multi-line input and Send. Stop appears next to Send while a turn runs. Send stays disabled while a turn runs, while the chat is archived, and while the connection is down.
-- **Model and effort picker:** a popover at wide widths and a bottom sheet at narrow widths.
-  - Entries come from the catalogue endpoint, grouped by driver, with the billing tag on pay-per-use entries.
-  - Effort is a segmented control with the four normalised levels. Levels the selected entry does not allow are disabled.
-  - The current selection shows in the thread bar as "model · effort".
-- **Edge states, as drawn:**
-  - a new chat with no messages;
-  - the usage limit reached, with "Change model";
-  - an interrupted answer with an "Interrupted" chip and Retry;
-  - connection lost, with a "Reconnecting" chip;
-  - no model configured on this server;
-  - an archived chat opened.
-- **Socket hook:** one WebSocket per open chat, reconnecting with backoff and no automatic resend. It parses the frames listed in `DCM-CHAT-1`, and on close codes 4401, 4403 and 4429 it stops reconnecting and surfaces the matching state.
-- **API client:** a default implementation of every REST call in `DCM-CHAT-1`. The default set is exported, and a consumer can override single functions while the others keep their defaults.
-  - This avoids the `MessagingProvider` limitation described in `webapp-management/SHARED_CAPABILITIES.md`: there, passing any `api` prop replaces the whole default set.
-- **Markdown rendering** uses `react-markdown` with `remark-gfm`, configured like maana's `MarkdownReply.jsx`: no raw HTML, no images, and links rendered as text. Both packages are new dependencies of this repository. They are approved with this order.
-- **Strings:** all strings are registered through ui-core-micha's i18n contract in a new translations module, in German, English, French and Swahili like the existing modules.
-- **Documentation:** a row in `webapp-management/SHARED_CAPABILITIES.md` for the chat surface, as a small companion change in that repository.
-
-## Copy list (released with this Envelope)
-
-Hint and state texts beyond control labels, verbatim from the prototype:
-- "Usage limit reached for {model}. Choose another model or try again later."
-- "The answer could not be completed."
-- "Chat is not available"
-- "No language model is configured on this server."
-- "pay per use" (catalogue billing tag)
-- Chips: "Interrupted", "Reconnecting", "Archived".
-
-The tool-activity text, for example "Searching the knowledge base", is not ui-core-micha copy. It is the label each app gives its tool.
-
-## Token delta list
-
-None. Drawn from the theme.
-
-## Replaces / removes
-
-Nothing. This is a new surface. The existing `messaging` components stay unchanged.
-
-## Non-goals
-
-- Proposals, plans, grants, context inspection, or anything else from maana's domain UI.
-- Credential entry for own logins or API keys (stage 4, `django-core-micha/DCM-CHAT-3`).
-- Search across chats, sharing, attachments, voice input.
-- Mounting the surface in any app. cockpit does that in `CP-CHAT-4`.
-- Changes to `messaging/`, `notifications/` or the theme factory.
-
-## Tier
-
-Tier 3: a new shared-core surface with new dependencies.
-
-## Risks
-
-- **Markdown as an injection path:** answers can echo text from retrieved documents. The renderer must never interpret raw HTML or load images or links automatically. The allow-list configuration above is the control.
-- **Contract drift:** the component is built against the transport contract of `DCM-CHAT-1` before that module is published. Any deviation found later is a change to that contract, not a local adaptation here.
-- **Theme coupling:** literal colours copied from the prototype would make the component look like cockpit in every app. Colours must come from the theme.
-
-## Required tests to write
-
-- Socket hook:
-  - deltas append to the streaming answer;
-  - the `turn` frame replaces it with the final text and sources;
-  - reconnect without resending;
-  - 4401, 4403 and 4429 stop reconnecting and show their state.
-- Thread:
-  - Markdown renders a list and a table;
-  - raw HTML in an answer is shown as text and not executed;
-  - an image reference is not loaded;
-  - source chips show the label, with the reference on hover;
-  - the model-change divider appears between turns with different selections.
-- Picker:
-  - entries are grouped by driver;
-  - a pay-per-use entry shows its tag;
-  - effort levels the entry does not allow are disabled;
-  - a change calls the update-selection endpoint.
-- Chat list:
-  - rename, archive, restore and delete call their endpoints;
-  - delete asks for confirmation first;
-  - an archived chat disables Send.
-- Edge states: the usage-limit, interrupted and not-configured states render from their error codes.
-- API client: overriding one function keeps the defaults for all others.
-- Translations: every key of the new module exists in all four languages.
-
-# B. Implementation map — addressed to the implementer
-
-## Context package
-
-Work from this package; do not explore broadly. Open only the files named here to verify. Target working directory: `C:/Users/Micha Bigler/Documents/webapps/ui-core-micha` (never the workspace root). Dependencies `react-markdown` 10.1.0 and `remark-gfm` 4.0.1 are already installed in `package.json` and the lockfile; do not touch either.
-
-**Templates to read (maana, read-only, do not edit):** `maana/frontend/src/qda/assistant/` (sibling directory of this repo under the workspace root) — `useAssistantSocket.js` (reconnect with backoff, per-chat socket, close-code mapping), `MarkdownReply.jsx` (the allow-list renderer: copy its approach, but take the table/code region labels from this repo's i18n and colours only from the theme), `ChatThread.jsx`, `ChatList.jsx`, `ChatComposer.jsx`, `ChatWorkspace.jsx` (frame handling around line 118), `assistantApi.js`. Take the structure, not maana's proposals, grants, plans, context dialog or project id. Visual spec: `work-orders/assets/UCM-CHAT-1-ai-chat.html` — read it first; it governs look and interaction, with every colour, radius and type size taken from the MUI theme (palette tokens such as `primary.main`, `text.secondary`, `divider`, `action.hover`, `success/warning/error`), never a literal.
-
-**Repo conventions to match (verify in place):**
-- Source is `.jsx`/`.js` under `src/`, tests in `tests/*.test.jsx` (vitest + @testing-library/react + jsdom); look at `tests/Thread.test.jsx`, `tests/ConversationList.test.jsx` and `tests/MessagingProvider.test.jsx` for how a component is tested here (MUI icons are `vi.mock`ed per test file).
-- HTTP goes through `src/auth/apiClient` exactly like `src/messaging/api.js` (default export `apiClient`, each function returns `response.data`).
-- Strings: `useTranslation()` with keys in a new bundle `src/i18n/chatTranslations.ts` that exports exactly one const `chatTranslations`, entries `{ de, en, fr, sw }`, key prefix `Chat.` (check no key collides with another bundle). Register it in three places: `src/i18n/uiCoreTranslations.js` (spread), `src/index.js` (public export next to `messagingTranslations`), and `tests/i18nAggregate.test.js` (`PUBLIC_BUNDLES` plus its import list). German uses the formal variant.
-- Public exports are added to `src/index.js` in a block next to the messaging block (line ~113). Do not edit `src/messaging/**`, `src/notifications/**` or `src/theme/**`.
-
-## Wire shape (binding on this order; the Orchestrator pinned it from maana's implementation because DCM-CHAT-1 is not published yet)
-
-The Envelope fixes WHICH frames and endpoints exist; the field names below are the working assumption and must be isolated in ONE module (`src/chat/wire.js`: URL builders, frame/field names, the three close codes) so a later contract change touches one file.
-
-- **WebSocket** per chat: URL from a `wsUrl(chatId)` option, default `${ws|wss}://${location.host}/ws/assistant/chats/${chatId}/`. Client frames `{type:"send", message}` and `{type:"stop"}`. Server frames: `{type:"history", turns:[turn…]}` on connect; `{type:"delta", text}`; `{type:"tool", phase:"start"|"end", name, label, sources:[{label, reference}]}`; `{type:"turn", turn}`; `{type:"notice", code, text?}`; `{type:"error", code}` with `code` one of `quota_exceeded`, `provider_error`, `timeout`, `prompt_too_long`, `invalid_output`, `security_violation`, `not_configured`, `rate_limited`, `invalid_selection`, `archived`, `turn_active`, `invalid_frame`. Close codes 4401 -> `session_ended`, 4403 -> `access_lost`, 4429 -> `rate_limited`: no reconnect, state surfaced. Any other close -> reconnect with backoff (1 s, 2 s, 4 s, then stop and show the "connection lost" state with a manual Retry), **never resend a message automatically**; ignore malformed JSON frames.
-- **REST**, base path from an `apiBase` option (default `/api/assistant/`): `GET catalogue/` -> `{entries:[{id, driver, model, label, efforts:["low"|"medium"|"high"|"max"…], billing:"subscription"|"pay_per_use"}], default:{entry, effort}}`; `GET chats/?archived=<bool>&cursor=` -> `{results:[chat…], next}`; `POST chats/` body `{scope?}` -> chat; `PATCH chats/{id}/` body any of `{title, archived, selection:{entry, effort}}` -> chat; `DELETE chats/{id}/`; `GET chats/{id}/turns/?cursor=` -> `{results:[turn…], next}` (newest page first, `next` = cursor for older); `GET status/` -> `{status:"available"|"not_configured"}`.
-- **chat** = `{id, title, archived_at|null, selection:{entry, effort}, updated_at}`. **turn** = `{id, seq, user_text, assistant_text, state:"generating"|"completed"|"failed"|"cancelled"|"interrupted", sources:[{label, reference}], driver, model, effort, error_code|null}`.
-
-## Named files to create (all new; owns `src/chat/**`, `src/i18n/chatTranslations.ts`, `tests/chat*.test.*`, and the three registration edits above)
-
-- `src/chat/wire.js` — constants and URL builders above.
-- `src/chat/api.js` — `createChatApi(overrides = {}, { apiBase })` and the exported `defaultChatApi`: one function per REST call (`getCatalogue, listChats, createChat, updateChat, deleteChat, listTurns, getStatus`) returning `response.data`; `{...defaults, ...overrides}` so overriding one function keeps every other default (the point of this design; contrast `MessagingProvider`).
-- `src/chat/useChatSocket.js` — the hook: `(chatId, {wsUrl, onFrame, onOpen, onClose})` -> `{status, connected, send, reconnect}`. State machine as above. Pass the chat id with every delivered frame so a late frame of a left chat is never applied (maana does this).
-- `src/chat/MarkdownReply.jsx` — allow-list renderer. Allowed elements as maana, `unwrapDisallowed`, links render as text (label plus address when different), images never fetched (alt text or address as text), raw HTML shown as text (no rehype-raw), tables and code in focusable scroll regions, a very long reply falls back to plain text (constant `MARKDOWN_LIMIT`). Styling through `sx` with theme tokens only.
-- `src/chat/ChatThread.jsx` — turns, streaming answer, typing indicator before first delta, tool-activity chip (label from the `tool` frame), source chips (short `label`, full `reference` as tooltip), the quiet "model · effort" line under each answer, a divider between turns whose driver/model/effort differ, older turns loaded by cursor on scroll up/"load older", state chips ("Interrupted" + Retry, "Reconnecting"), and the error states.
-- `src/chat/ChatList.jsx` — new chat, select, per-row overflow menu (Rename, Archive, Delete), Delete confirmation inside a MUI Dialog, "Archived" entry with count, restore of an archived chat, load more.
-- `src/chat/ChatComposer.jsx` — multi-line input, Send, Stop while a turn runs; Send disabled while a turn runs, while the chat is archived, and while the connection is down. Enter sends, Shift+Enter newline.
-- `src/chat/ModelPicker.jsx` — popover (wide) / bottom `Drawer` sheet (narrow, via `useMediaQuery(theme.breakpoints.down('md'))`), entries grouped by driver, "pay per use" tag, effort `ToggleButtonGroup` with levels the entry does not allow disabled; a change calls `updateChat(id, {selection})`; the thread bar shows "model · effort".
-- `src/chat/ChatWorkspace.jsx` — composes list + thread + composer + picker. Props: `apiBase`, `wsUrl`, `api` (partial overrides, merged), `scope`, `sx`. Wide: two columns. Narrow: list in a `Drawer`. Loads status/catalogue, owns the active chat, the streaming state and the edge states: new chat empty state, usage limit (`quota_exceeded` -> "Usage limit reached for {model}. Choose another model or try again later." + "Change model"), interrupted/failed ("The answer could not be completed." + Retry, which re-sends that turn's `user_text` as a new `send` only on the user's click), connection lost ("Reconnecting" chip), `not_configured` ("Chat is not available" / "No language model is configured on this server."), archived (read-only, "Archived" chip, Restore).
-- No `src/chat/index.js`; export from `src/index.js`: `ChatWorkspace, ChatList, ChatThread, ChatComposer, ModelPicker, MarkdownReply, useChatSocket, createChatApi, defaultChatApi, chatTranslations`.
-- `src/i18n/chatTranslations.ts` — every string of the Envelope's copy list verbatim in English, plus control labels, aria-labels and the Markdown region labels; all four languages.
-- Tests (names are guidance): `tests/chatSocket.test.jsx`, `tests/chatThread.test.jsx`, `tests/chatPicker.test.jsx`, `tests/chatList.test.jsx`, `tests/chatEdgeStates.test.jsx`, `tests/chatApi.test.js`, `tests/chatTranslations.test.js`, plus a one-line export check in the style of `tests/messagingExports.test.js`. The socket tests use a fake `WebSocket` class and fake timers.
-
-## Invariants, pitfalls, do-not-touch
-
-- No raw HTML, no image fetch, no auto-loading links anywhere in answers; no `dangerouslySetInnerHTML`. User message text is rendered as plain text.
-- No literal colours, radii or font sizes copied from the prototype; theme tokens and spacing units only. Light and dark themes must both work.
-- Accessibility: the streaming answer sits in a polite live region that is not re-announced on every delta (`aria-busy` while generating), icon buttons have aria-labels, the picker and menus are keyboard operable, touch targets at least 40 px at narrow width.
-- Do not edit `src/messaging/**`, `src/notifications/**`, `src/theme/**`, `package.json`, the lockfile, `README.md`, `CHANGELOG.md` or the register. Docs and the version bump are the Orchestrator's.
-- Package build is `tsc -p tsconfig.build.json` (allowJs, `src` only): new files must compile; `tests/packageTreeShaking.test.js` and `tests/checkKitIntegration.test.jsx` exist: do not introduce a top-level side effect in the new modules.
-- The working tree contains unrelated foreign changes (`WORK_ORDERS.md`, `work-orders/UCM-DEP-1.md`, `package.json`, `pnpm-lock.yaml`): leave them alone.
-
-## Preamble
-
-> 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 this WO was dispatched to you as an implementer: STOP here.**
-
-Gate #1 open until recorded in the register row. Can start against the `DCM-CHAT-1` contract in parallel; publish as a new minor version. Prototype in scope: ucm has no host app of its own, so the rendered side-by-side at 375 px and 1280 px runs where the surface is first mounted, in `cockpit/CP-CHAT-4`, and is that order's commit gate; a deviation it finds in the shared components is fixed here and republished.