@micha.bigler/ui-core-micha 2.40.0 → 2.41.1

package/work-orders/AUTH-5.md

@@ -0,0 +1,154 @@
+# AUTH-5 — `addPublicPath` muss dynamische Routen ausdrücken können
+
+**Target repo:** `ui-core-micha` (branch `main`)
+**Tier:** 3 — shared-core. Die Änderung betrifft die Login-Weiterleitung jeder konsumierenden App.
+
+**Kein Prototyp.** Diese Work Order hat keine Oberfläche — sie erweitert eine Registrierungs-API.
+
+**Auslöser:** `jg-ferien` PUB-7 Teil 2. Diese WO ist dessen Vorbedingung; nach der Veröffentlichung
+zieht jg seinen Pin von **`2.37.1`** hoch.
+
+---
+
+## A. Envelope
+
+### Goal
+
+`apiClient` leitet bei 401/403 per hartem `window.location.assign("/login")` um — **ausser** der
+aktuelle Pfad steht auf einer Allowlist (`redirectToLoginOnce`, `src/auth/apiClient.jsx`). Der
+Mechanismus ist richtig gebaut: auf einer öffentlichen Seite unterbleibt die Weiterleitung und der
+401 wird an die Komponente durchgereicht.
+
+**Was er nicht kann, ist dynamische Routen.** `matchesPublicPath` vergleicht mit `startsWith`, ausser
+bei `/`, wo Gleichheit verlangt wird. Eine App mit öffentlichen Seiten unter einem **variablen
+Segment** — `/<slug>`, `/<slug>/team` — kann ihre öffentliche Fläche damit nicht beschreiben. Ein
+konkreter Slug lässt sich eintragen; der nächste, den jemand anlegt, fällt wieder heraus.
+
+**Warum das mehr ist als eine Unbequemlichkeit.** Fehlt der Pfad in der Liste, landet ein anonymer
+Besucher beim ersten 401 auf `/login` — auf einer Seite, die öffentlich sein soll. Von aussen ist das
+nicht von „diese Seite gibt es nicht" zu unterscheiden, und der Fehler zeigt sich erst, wenn ein
+zweites Department existiert. Er sieht dann aus wie ein Zufall, nicht wie eine Lücke.
+
+**Erwartetes Ergebnis.** Eine konsumierende App kann ihre öffentliche Fläche vollständig beschreiben,
+auch wenn Teile davon aus variablen Segmenten bestehen.
+
+### Scope
+
+- **`addPublicPath` nimmt zusätzlich ein `RegExp` entgegen** (String bleibt unverändert gültig).
+- **`matchesPublicPath` unterscheidet nach Typ**: String wie bisher (`/` exakt, sonst `startsWith`),
+  `RegExp` per `test()` gegen **ausschliesslich `window.location.pathname`** — nie gegen Query oder
+  Fragment, damit ein Muster nicht versehentlich über den Pfad hinaus greift.
+- **`removePublicPath` funktioniert für beide Formen.** Bei `RegExp` über Identität des übergebenen
+  Objekts; das gehört dokumentiert, weil zwei gleich aussehende Literale nicht dasselbe Objekt sind.
+- **`BUILTIN_PUBLIC_PATHS` bleibt eingefroren und rein string-basiert.** Kein Muster in der
+  Bibliotheks-Liste — sie darf sich nicht durch eine Konsumenten-Erweiterung verschieben.
+- **Die Dokumentation am Aufruf sagt, was der Konsument nun selbst trägt**: ein zu weites Muster
+  unterdrückt die Weiterleitung dort, wo sie gebraucht wird, und ein abgelaufener Login endet dann in
+  einer stillen Fehlerseite statt am Login. Muster gehören verankert (`^…$`).
+
+### Non-goals / do not touch
+
+- **Keine Änderung am Weiterleitungsverhalten selbst** — weder Ziel, noch `?next=`, noch der
+  einmalige Sperrmechanismus (`redirectingToLogin`).
+- **Keine Änderung an der eingefrorenen Builtin-Liste** und keine an `isPublicSitePath`.
+- **Keine Änderung am Per-Request-Opt-out** für Bootstrap-Proben.
+- **Keine neue Prüfung gegen Query oder Fragment.**
+
+### Risks
+
+- **Die Verantwortung wandert zum Konsumenten.** Ein unverankertes Muster wie `/team` trifft auch
+  `/admin/team`. Das ist der Preis der Flexibilität und muss in der Dokumentation stehen, nicht nur
+  im Kopf des Autors.
+- **Geteilter Code**: jede konsumierende App bekommt die Änderung. Deshalb rein additiv — bestehende
+  String-Registrierungen müssen sich zeichengenau gleich verhalten.
+- **Ein Muster, das zu eng greift, ist unsichtbar**, bis jemand die betroffene Seite anonym öffnet.
+  Deshalb gehört die Gegenrichtung mitgetestet.
+
+### Required tests to WRITE
+
+- **Regression, nicht verhandelbar:** String-Registrierungen verhalten sich exakt wie bisher — `/`
+  nur bei Gleichheit, andere Einträge per Präfix.
+- Ein registriertes `RegExp` trifft die passenden Pfade; ein nicht passender Pfad **löst weiterhin
+  die Weiterleitung aus**.
+- Das Muster wird gegen `pathname` geprüft, nicht gegen Query oder Fragment.
+- `removePublicPath` entfernt einen `RegExp`-Eintrag; ein Builtin-Pfad lässt sich weiterhin **nicht**
+  entfernen.
+- Ein `RegExp` in `CONSUMER_PUBLIC_PATHS` bricht die bestehende Auswertung der String-Einträge nicht.
+- **Affected set** (laufen, nicht schreiben): die vorhandenen `apiClient`-Tests.
+
+---
+
+## B. Implementation map
+
+**Selbst umgesetzt (nicht per Codex)** — laufende Operator-Anweisung für diese Session.
+
+### Design-Entscheidungen
+
+- **`addPublicPath`/`removePublicPath`** akzeptieren jetzt zusätzlich `instanceof RegExp` neben
+  `string`; `CONSUMER_PUBLIC_PATHS` bleibt ein `Set`, das für `RegExp`-Objekte automatisch
+  Identitäts-Löschung liefert (`Set.delete` nutzt SameValueZero) — kein Sonderfall nötig.
+- **`matchesPublicPath`** prüft `entry instanceof RegExp` zuerst und ruft `entry.test(pathname)` —
+  ausschliesslich gegen `window.location.pathname`, nie gegen `search`/`hash`, da die Funktion
+  ohnehin nur `pathname` als Parameter erhält (kein Risiko einer versehentlichen Konkatenation).
+- **`BUILTIN_PUBLIC_PATHS` unverändert** — bleibt string-only und eingefroren, keine Berührung.
+- Dokumentation an `addPublicPath`/`removePublicPath` erweitert: Anker-Pflicht (`^…$`) für
+  `RegExp`-Muster und Identitäts-Hinweis für `removePublicPath`.
+
+### Kontextpaket
+
+- `src/auth/apiClient.jsx` — einzige geänderte Quelldatei.
+
+### Tests
+
+`tests/apiClientPublicPaths.test.js` (neu, 11 Fälle) — fährt durch den echten
+Response-Interceptor (nicht durch eine Nachbildung von `matchesPublicPath`), damit ein Fehler in
+der Verdrahtung selbst auffällt, nicht nur ein Fehler im Matcher. Jeder Test importiert das Modul
+frisch (`vi.resetModules()` + dynamisches `import()`), weil `redirectingToLogin` ein
+Modul-Level-Riegel ist, der sich in jsdom nie durch echte Navigation zurücksetzt.
+`window.location` wird durch ein rein synthetisches Objekt ersetzt (jsdoms echtes
+`location.assign` ist nicht konfigurierbar, und `pushState` bindet nicht an ein ersetztes
+`location`-Objekt) — deckt exakt das ab, was der Interceptor liest (`pathname`) und aufruft
+(`assign`). Affected set: `authApiRegistration.test.js`, `AuthContext.test.jsx`,
+`feedApi.test.js`, `messagingApi.test.js`, `notificationsApi.test.js` — alle grün.
+
+---
+
+## C. Orchestrator only
+
+> **STOPP — wer diesen Auftrag als eigene Spezifikation liest, ist mit diesem Abschnitt nicht
+> gemeint.** Er beschreibt dem Orchestrator, wie er dich aufruft, wie das Ergebnis geprüft und wie es
+> verbucht wird. **Du BIST dieser Aufruf — starte kein `codex exec`, spawne keine Reviewer, pflege
+> das Register nicht, committe nicht.** Deine Aufgabe endet beim Diff.
+
+### Execution directive
+
+`.claude/codex-status.md` im Workspace-Root vor dem Aufruf prüfen. Ohne Zeile für den
+Ausführungstag Codex verwenden — direkt per Bash, nie über die `debugger`/`*_coder`-Wrapper, mit
+BEIDEN Flags `--skip-git-repo-check` und `--dangerously-bypass-approvals-and-sandbox`. Der Rückfall
+auf direkte Umsetzung dreht die Autorschaft und macht den unabhängigen `reviewer` zwingend.
+
+### Review routing
+
+Tier 3 (shared-core): **`reviewer` und `sec_reviewer`**, gleichzeitig in einem Hintergrund-Batch vor
+dem Commit. `ui_reviewer` entfällt — es gibt keine Oberfläche. `sec_reviewer` prüft die Kernfrage:
+kann ein registriertes Muster die Weiterleitung dort unterdrücken, wo sie gebraucht wird, und ist die
+Auswertung auf `pathname` beschränkt.
+
+### Verification
+
+Kein Prototyp, kein Zwei-Breiten-Abgleich. Der Nachweis sind die Tests, insbesondere die
+Regressionsfälle für die String-Registrierung.
+
+Nach grünem Review: Version anheben und veröffentlichen. **Die WO ist erst abgeschlossen, wenn die
+Version veröffentlicht ist** — jg-ferien PUB-7 hängt daran und kann ohne sie nicht landen.
+
+### Register + commit
+
+Zeile `AUTH-5` erreicht `done` nur mit beiden Reviewern samt Verdikt in der `Notiz` und der
+veröffentlichten Version. Auf grün nach `main` committen und pushen.
+
+### Mini-handover
+
+Repo: `ui-core-micha` (`C:\Users\biglmi\Documents\webapps\ui-core-micha`), Branch `main`.
+WO: `work-orders/AUTH-5.md`. Konsument: `jg-ferien` PUB-7 Teil 2 (Pin heute `2.37.1`).
+`git pull`, WO lesen, dann `orchestrate-codex` folgen.

package/work-orders/THEME-10.md

@@ -0,0 +1,303 @@
+# THEME-10 — A scatter preset, drawn from three real consumers
+
+## Part A — Envelope
+
+**Goal.** Add a `ScatterChart` preset alongside `BarChart` / `LineChart` / `TimeSeriesChart`,
+with the same axis handling, tick formatting, legend and frame behaviour, so a consuming app
+can plot a point cloud without building its own chart from raw SVG.
+
+**Why.** hram draws **three** scatters entirely by hand — its own axis lines, gridlines, ticks,
+tick labels and rotated axis titles, on hard-coded canvases. Only `ChartFrame` comes from this
+package. That is not negligence: **this package has no scatter preset**, so there was nothing
+to reach for. Every fix this kit has made since (axis sizing, tick formatting, label placement,
+the role palette) passes all three by, and will keep doing so until a preset exists.
+
+| Consumer | Canvas | Composition |
+|---|---|---|
+| `AllocationPerformancePanel` | `WIDTH 720`, `HEIGHT 420`, `MARGIN.left 92` | cloud + computed envelope curve + three individually marked points; continuous per-point colouring by one of three equity measures |
+| `AccessGapScatterPanel` | `CHART_H 714`, responsive width, `M.left 58` | bubble cloud (radius by population, z-ordered) + labelled y=x reference diagonal; **categorical** per-point colouring (division or settlement) with a discrete legend; both axes pinned to 0–1, ticks fixed at 0/25/50/75/100 % |
+| `OptimizationResultsPanel` | `WIDTH 720`, `HEIGHT 420`, `MARGIN.left 72` | cloud at `r=6` + dashed reference line; the status-quo point drawn hollow (`fill: none`) against filled candidates |
+
+The operator chose this route deliberately over letting each app reach for MUI X directly
+(hram `FIX-15`, fork option b), so that scatters are built the same way as every other chart in
+the estate rather than becoming a second, parallel charting style.
+
+**On the single-consumer risk this WO originally carried.** The first draft was written when
+only the allocation panel was known, and warned that an abstraction drawn from one example is
+how the wrong shape gets frozen. **The operator then named the access panel, and a sweep found
+a third.** That risk is largely spent: three independent consumers, written by different hands
+at different times, are enough to tell a real axis of variation from a guess. What replaces it
+is a narrower discipline:
+
+- **Every option in the API must be traceable to one of the three panels above.** They are the
+  requirements document. An option no listed consumer needs does not go in — adding one later
+  is cheap, removing one from a published package is not.
+- **Two of the variation axes were discovered, not designed**, and that is the point: neither
+  categorical-colour-plus-discrete-legend nor data-driven mark radius appears in the allocation
+  panel at all. Had this been built from that panel alone, both would have been missed and the
+  access panel would have had to bypass the preset.
+- The surface is no longer "provisional pending a second consumer" — but the docs should still
+  state which consumers it was drawn from, so a fourth with different needs knows what it is
+  extending.
+
+**Scope.**
+
+1. **`ScatterChart` preset** with the same contract shape as the existing presets: `series`,
+   `xAxis`, `yAxis`, `xAxisLabel`, `yAxisLabel`, `palette`, `grid`, `minHeight`, `aspect`,
+   `hideLegend`, `legendPosition`, `slotProps`, and remaining props forwarded to MUI.
+2. **Reuse the THEME-9 machinery rather than reimplementing it** — `withAxisDefaults`,
+   `sizeYAxisForContent`, `spaceForRotatedTicks`, `defaultNumericTickFormatter`,
+   `withGridDefaults`, `withChartSlotDefaults`. A preset that sizes its own axes differently
+   from `BarChart` would re-open exactly what THEME-9 just closed.
+3. **A neutral cloud by default.** Unlike a bar chart, where each series takes a categorical
+   colour, an *undifferentiated* scatter cloud is one neutral mass — the role register's
+   neutral, not a series hue. **The distinction matters, because one consumer colours
+   categorically and is right to:** the access panel encodes division or settlement class, a
+   real data dimension, and already draws those from the frozen family register. The allocation
+   panel's defect is different in kind — it paints a cloud that encodes *nothing* in
+   `dataViz.cost.main`, a KPI identity colour. Neutral is the default for "no dimension
+   encoded", not a prohibition on colour.
+4. **Three colouring modes, all three in use today:** neutral (default), **categorical** with a
+   discrete legend (access — division, settlement), and **continuous** with a scale legend
+   (allocation — three equity measures). Categorical draws from the family register's
+   positional slots; the consumer must not have to hand-index a palette array to get them.
+5. **Mark size: small fixed default, optionally data-driven.** The default is sized for hundreds
+   of overlapping points (hram plots ~300; it must not fuse into a solid area). The access panel
+   additionally needs a **radius bound to a value** (`max(3, 10·√(pop/maxPop))`) with **explicit
+   z-ordering by that value**, so large bubbles do not hide small ones. Bubble sizing without a
+   defined draw order is a silently wrong chart.
+6. **Support the compositions the consumers actually need** — a point cloud **plus** overlaid
+   reference geometry **plus** individually marked points:
+   - reference geometry appears in all three: a computed curve (allocation's envelope), a
+     straight identity line carrying a rotated inline label (access's y=x "no gap"), and a
+     dashed reference line (optimization);
+   - individually marked points appear in two, including a **hollow** state — optimization
+     draws the status quo as `fill: none` with a coloured stroke against filled candidates.
+
+   Whether that is one component with layers or a documented composition of MUI's
+   `ChartContainer` + plots is an implementation decision — but a consumer must be able to do it
+   *through* this package. If it cannot, the app bypasses the preset and we are back where we
+   started.
+7. **Axis furniture from theme tokens, not hard-coded greys.** This is the concrete regression
+   the preset exists to stop: the access panel hard-codes `#F0F0F0` (grid), `#D0D0D0` (axis),
+   `#999` (ticks), `#666` (tick labels), `#555` (axis titles), `#B0B0B0` (reference line) —
+   six greys that no theme change can reach. The other two are better but still partial.
+8. **Support a pinned tick set on a fixed domain.** The access panel's axes are both 0–1 with
+   ticks fixed at 0/25/50/75/100 % — a deliberate choice (the y=x diagonal is only readable on
+   equal, fixed axes), not something auto-ticking should override.
+9. Documentation in `DESIGN.md` alongside the other chart guidance, including the axis-title
+   rule THEME-9 introduced, and naming the three consumers the surface was drawn from.
+
+**Non-goals / do-not-touch.** No changes to the existing presets beyond what sharing helpers
+requires. No new colour tokens — everything comes from the existing role register and palette.
+No zoom, brush, selection-rectangle or animation features: none of them has a consumer, and
+each would be a guess. Do not change `ChartFrame`.
+
+**Explicitly NOT in scope — the row-based dot plots.** The same sweep found two more
+hand-drawn hram panels that also plot circles, and they are **a different chart, not a wide
+scatter**: `CalibrationPanel` is a forest plot (`MARGIN.left = 150`, one `ROW_HEIGHT` band per
+parameter, point estimate `r=5` plus a dashed interval) and `SensitivityAnalysisPanel` is a
+tornado (`MARGIN.left = 220`, `<rect>` bars per row). `OptimizationResultsPanel` carries a third
+of the same family in its divergence sub-view (`DIVERGENCE_MARGIN.left = 150`). Their y-axis is
+categorical, their left margin is 150–220 px of row labels, and their layout problem is row
+density — none of which a scatter preset should try to absorb. **Stretching this preset to cover
+them is exactly the over-generalisation this WO is guarding against.** They are a separate
+preset and a separate WO; note them, do not serve them.
+
+**Tier 3** — shared-core surface, new public API. `reviewer` mandatory; `ui_reviewer` too,
+since the deliverable is visual.
+
+**Tests to write.** The mark count — a scatter that silently drops points is the failure mode
+nobody sees, and it is trivial to assert. That the default cloud colour is the neutral role, not
+a categorical series colour. That bubble mode draws large marks **before** small ones (the
+z-order is the whole correctness of a bubble chart, and it is one assertion on draw order). Axis
+behaviour is already covered by THEME-9's tests if the helpers are reused — if a test has to be
+duplicated here, the helpers were not reused.
+
+**Risks.**
+- **Serving three consumers is not the same as serving all scatters.** The single-consumer risk
+  is spent, but the opposite one is now live: with three shapes in hand it is tempting to
+  generalise to a fourth that does not exist. Every option traces to a listed panel, or it does
+  not go in. If the API starts growing during implementation, stop and report.
+- **The row-plot family is the specific over-reach to watch** (see non-goals). Two more panels
+  draw circles and will look like near-misses. They are not.
+- **Performance at a few hundred marks** is fine; at tens of thousands it is not. State the
+  tested magnitude in the docs rather than implying it scales indefinitely.
+- The overlay composition (scope 6) is where this can quietly fail its purpose. Verify against
+  the real panel shapes — cloud + envelope + three special points, and bubble cloud + labelled
+  diagonal — not against a synthetic example.
+
+**This WO is commissioned before the requirement set is closed — deliberately.** The operator
+dispatched it on 2026-08-14 knowing that the access and optimization panels will each get their
+own prototype, and that **those prototypes are expected to carry additional requirements**. The
+three shapes listed above are what is known now, not the final set. Two consequences the
+implementer must honour:
+
+- **Keep the surface additively extensible.** A later requirement must be satisfiable by adding
+  a prop, not by changing the meaning of an existing one or reshaping the contract. Prefer an
+  explicit option over an inferred behaviour wherever the two cost the same.
+- **Do not read this as licence to pre-build for the unknown.** The rule stands: every option
+  ships because a listed panel needs it. "A prototype might later want X" is not a consumer.
+  The insurance against the unknown is that the API can grow, not that it already did.
+
+**One forthcoming shape is already named — do NOT build it, but do not foreclose it.** The
+optimization panel will want its MILP solution and its simulated solution shown as a **paired
+point** (two marks joined by a connector, with the difference between them displayed). The
+plumbing is largely there: that panel already puts both on shared scales
+(`buildScale([...cloud.map(p => p.cost), ...milp.map(p => p.x)])`) and already joins the MILP
+points with a `polyline`. The part that is **not** additive is the data unit: every contract in
+this WO is *one mark per datum*, whereas a pair is two marks plus a link that must travel
+together — shared tooltip, shared colour, one hit target, and a delta label anchored between
+them. Retrofitting that means reshaping `series`, not adding a prop.
+
+So: **design the point contract so a "pair" variant can be added later without changing what a
+single point means** — most simply, by not assuming a 1:1 datum→mark mapping anywhere in the
+internals. Ship nothing for it now. It has no prototype yet, and two of its questions are
+app-level rather than preset-level: which key joins a MILP point to its simulated counterpart
+(the scatter's points come from `planningPoints`, the deltas from a separate `getDivergence`
+call keyed by regime), and whether the difference is rendered as a per-pair numeric label —
+which would be genuine mark labelling, absent from this preset — or carried by the connector
+length plus the tooltip, which costs nothing.
+
+**Delivery is not done at publish.** hram `FIX-15` (allocation) is the first consumer and is
+blocked on this package; the pin bump and that panel's rebuild are what prove the preset works.
+The access and optimization panels are known consumers with **no WO yet** — they are what this
+surface was designed against, so they are not optional evidence, but converting them is separate
+work to be scheduled, not folded in here. THEME-8 and THEME-9 are both sitting published with
+consumer pins still open, so bundle the pin bump rather than adding a third pending hop.
+
+## Part B — Implementation map — ADDRESSED TO THE IMPLEMENTER
+
+Codex was not dispatched: `.claude/codex-status.md` already carried a same-day (2026-08-14)
+`unavailable` line (THEME-8/9/FIX-11/FIX-13, same day), so per the known-unavailable shortcut
+the Orchestrator implemented directly, which flips authorship — `reviewer` + `ui_reviewer`
+became mandatory (already required at Tier 3).
+
+### What landed
+
+`src/components/charts/ScatterChart.jsx` (new), exported from `src/index.js` alongside
+`BarChart`/`LineChart`/`TimeSeriesChart`:
+
+- **Contract shape (scope 1).** `series`/`xAxis`/`yAxis`/`xAxisLabel`/`yAxisLabel`/`palette`/
+  `grid`/`minHeight`/`aspect`/`hideLegend`/`legendPosition`/`slotProps`, remaining props
+  forwarded to MUI's own `ScatterChart` — same shape as `BarChart`/`LineChart`.
+- **THEME-9 reuse (scope 2).** `withAxisDefaults` + `sizeYAxisForContent` +
+  `defaultNumericTickFormatter` for the Y axis (both axes on a scatter are numeric by
+  construction, so no band/point default or `spaceForRotatedTicks` reuse was needed — X gets
+  MUI's own default sizing, which THEME-9 already established is adequate for an unrotated
+  numeric axis).
+- **Neutral default + colouring modes (scope 3/4).** `palette.js` gained a `neutral` key
+  (`theme.palette.text.secondary`) — a single series with no explicit `color` renders in that
+  tone; multiple series render categorically (MUI's own multi-series legend, unchanged
+  mechanism already used by `BarChart`); continuous colouring is the caller's own resolved
+  colour applied via `getPointStyle` (this package does not ship a colour-scale/legend
+  component — out of scope, see "Not built" below).
+- **Bubble sizing + explicit z-order (scope 5).** `scaleBubbleRadius(value, maxValue)` —
+  `max(3, 10·√(value/maxValue))`, exported. `sizeAccessor` on `ScatterChart` turns on bubble
+  mode: every series is sorted largest-first before being handed to MUI (SVG paints later
+  elements on top, so small bubbles are never hidden), and the max is **one chart-wide value
+  across every series** (matches the access panel's own `Math.max(1, ...points.map(p =>
+  p.population))` over ALL points regardless of division/settlement — a per-series max was an
+  implementation bug caught during the rendered verification below, fixed before commit).
+- **Individually marked points (scope 6, part).** `getPointStyle(point, {seriesId, dataIndex})
+  => {hollow?, color?, shape?, radius?, strokeWidth?}` — a status-quo point drawn hollow
+  (`fill:none`), a per-point colour override, `'circle'|'square'|'diamond'`. Every shape option
+  traces to the allocation panel specifically (`AllocationPerformancePanel.jsx:500-554`, its
+  `ShapeGlyph` legend): `isSelected` → diamond, `isTargeted` → **square**, plain candidate →
+  filled circle, status quo → **hollow** circle — the SAME panel that also motivated the
+  hollow state (allocation's own status-quo point is hollow too, not only optimization's — the
+  Envelope's Part A table names optimization's hollow explicitly but allocation's own point
+  rendering carries the identical `fill: isStatusQuo ? 'none' : color` pattern). `ui_reviewer`
+  finding U1 flagged `'square'` as apparently untraceable; it traces to `isTargeted`, cited here
+  because the original Part A table didn't spell out allocation's shape variety. Implemented via
+  a custom MUI marker slot (`slots.marker`) — confirmed against `@mui/x-charts/ScatterChart/
+  Scatter.js` that MUI's own marker size is fixed PER SERIES (`series.markerSize`), never
+  derived from a point's own `z`, so per-point radius/colour/shape genuinely requires replacing
+  the marker, not a prop MUI already exposes.
+- **Reference geometry (scope 6, part).** `ScatterReferenceCurve`/`ScatterReferenceLine`,
+  exported, rendered as `ScatterChart` `children` — read the chart's own live `useXScale`/
+  `useYScale` (confirmed exported from `@mui/x-charts/hooks`), never a second hand-rolled pixel
+  mapping. Covers all three named shapes: allocation's envelope (curve), access's labelled y=x
+  diagonal (line + inline rotated label), optimization's dashed threshold (line, dashed).
+- **Theme-token furniture (scope 7).** Inherited for free — grid/axis/tick colours already come
+  from the theme via `withGridDefaults`/MUI's own axis styling (the same mechanism `BarChart`/
+  `LineChart` already use), never a hard-coded grey.
+- **Pinned tick set on a fixed domain (scope 8).** No new mechanism needed — MUI's own
+  `tickInterval: any[]` (confirmed in `@mui/x-charts/hooks/useTicks.d.ts`) already accepts an
+  explicit tick array via plain `xAxis`/`yAxis` passthrough (`tickInterval: [0,0.25,0.5,0.75,1]`
+  reproduces the access panel's fixed 0/25/50/75/100% ticks exactly).
+- **DESIGN.md (scope 9).** New principle 8b: neutral-by-default, the three colouring modes, the
+  bubble-z-order rule, and the explicit "not this preset" pointer to the row-based dot-plot
+  family (forest plot, tornado — a different WO).
+
+### Forward-compatibility requirement (added to the Envelope after initial implementation)
+
+The WO was updated mid-session to add: "commissioned before the requirement set is closed,"
+additive-only extension going forward, and an explicit instruction to **not assume a 1:1
+datum→mark mapping anywhere in the internals**, so a later "paired point" shape (optimization's
+MILP-vs-simulated pair) can be added without reshaping the contract. Reviewed against the
+landed code: nothing here assumes a fixed mark count per datum — a point object may carry
+arbitrary extra fields beyond `{x,y,z,id}` (already exercised by `getPointStyle`'s status-
+quo/bubble usage), `getPointStyle`/`sizeAccessor` key off the datum itself, and reference
+geometry composes via `children` rather than being baked into the per-point contract. A pair
+variant can layer on later (extra series entries + a connector drawn through `children`)
+without touching `series`'s shape or either callback's signature. Documented in the component's
+own docstring so this reasoning survives independent of this WO file.
+
+### Not built (named, not silently dropped)
+
+- **A continuous colour-scale/legend component.** The WO's scope items describe "continuous
+  with a scale legend" as a supported MODE, not a component this package must ship — the
+  allocation panel already owns a working gradient-legend implementation
+  (`AllocationPerformancePanel.jsx:594-646`) built from its own `getColorScale` utility;
+  `getPointStyle` is the seam that lets it apply that resolved colour per point through this
+  preset. Building a second, generic version was not named as a required deliverable in scope
+  1-9 and risked exactly the over-generalisation the WO warns against (no listed consumer needs
+  a DIFFERENT continuous-legend implementation from the one it already has).
+- **The paired-point shape.** Explicitly deferred per the Envelope update above — no prototype,
+  no WO, ship nothing.
+- ~~A `dev/entries.jsx` fixture for optimization's exact shape was not added as a third harness
+  entry~~ — **reversed per `ui_reviewer` finding U2.** It was added (`OptimizationShapeScatterEntry`)
+  and rendered live: this is exactly the combination (no `yAxis` min/max, no explicit `palette`)
+  that `reviewer` finding R1 caught a real bug on (`sizeYAxisForContent` never received number
+  candidates from scatter's `{x,y}` point objects) — the other two fixtures each avoided the gap
+  incidentally (access sets explicit `yAxis` min/max; allocation's Y magnitude happened to fit
+  MUI's flat default), so U2's point that live rendering catches what the unit suite doesn't was
+  correct and specific, not general caution.
+
+### Target repo
+
+`C:\Users\biglmi\Documents\webapps\ui-core-micha`
+
+## 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.**
+
+- **Execution.** Codex known-unavailable today (see Part B) — implemented directly in Claude.
+- **Review routing.** `reviewer` + `ui_reviewer`, concurrent, one background batch.
+- **Verification.** Package suite (`ScatterChart.test.jsx` — 15 tests: mark count, neutral
+  default, categorical/explicit palette override, bubble z-order, chart-wide bubble max,
+  hollow/shape marker rendering, reference curve/line geometry against the live scale;
+  `chartsPalette.test.js` gained the `neutral` key pin; full affected set incl.
+  `BarChart.test.jsx`/`LineChart.test.jsx`/`chartDefaults.test.js` — 51 tests, green).
+  **Rendered check against both real consumer shapes, done live** in `ui-core-micha`'s own dev
+  harness (`dev/entries.jsx`, two new entries: "ScatterChart (allocation shape)" and "(access
+  shape)"), on the browser tab already carrying real viewport dimensions (cross-origin
+  navigation from the previously-displayed hram tab, working around the earlier THEME-9 session's
+  0×0-viewport limitation on freshly-opened tabs).
+  - **Allocation shape:** 6/6 points rendered (mark count matches supplied), hollow status-quo
+    (`fill:"none"`), continuous per-point colour gradient (hsl hue 188→164→132→104.8 tracking
+    the fixture's equity values), diamond shape for the selected point, envelope curve drawn
+    through the correct live-scale pixel coordinates (`M85,295 L377.9,196 L729.3,86 L905,64`,
+    matching the four supplied envelope points).
+  - **Access shape:** 7/7 points rendered across 3 categorical series (colours `#0F62FE`/
+    `#24A148`/`#FF832B`, correct per-series), fixed 0/25/50/75/100% ticks on both axes, labelled
+    dashed y=x reference line present. **First render caught a real bug**: bubble radii were
+    computed per-series instead of chart-wide, so a small series' own largest point rendered at
+    full radius regardless of its actual size relative to other series — fixed (`chartMax`,
+    single value across all series' data) and re-verified live: radii now correctly proportional
+    across all three series against one shared max (7.75/6.32/3.16 · 5.48/4.08 · 10/3).
+- **Register & commit.** Advance the THEME-10 row with the reviewer verdicts and the rendered
+  mark counts above. hram `FIX-15` (the first actual consumer) does not exist yet — no pin bump
+  to bundle in this WO; that happens when `FIX-15` is authored.