# 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.