@micha.bigler/ui-core-micha 3.2.1 → 3.3.1

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

@@ -0,0 +1,195 @@
+# UCM-CHART-17 — The two export buttons make two different promises; make them keep them
+
+## Part A — Envelope
+
+*Authored by the Expertenchat. Authoritative WHAT/WHY.*
+
+### Goal
+
+**Export SVG** yields the chart as scalable, correctly styled vector art. **Export PNG** yields what
+the user is looking at — legend, size key and footnotes included.
+
+### The defect, from the source
+
+`exportChart.js:7-11` clones the first `<svg>` in the container and serialises it raw:
+
+```js
+const svg = findSvg(chartContainer).cloneNode(true);
+svg.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+return new Blob([new XMLSerializer().serializeToString(svg)], …)
+```
+
+Three consequences, and they compound:
+
+1. **No styles are carried.** MUI X-Charts styles nearly everything through emotion CSS classes —
+   tick fonts and sizes, axis and grid colours, text fill, the theme's typography. The clone keeps
+   `class="MuiChartsAxis-tickLabel css-1abc"` and none of the rules behind it, so a standalone
+   viewer applies bare SVG defaults. This is the "graphically massively different" the operator
+   reported. **The PNG inherits it**, because it rasterises the same blob.
+
+2. **The legend is gone, and that is ours.** `findSvg` takes the *first* `<svg>`, i.e. the chart.
+   Since `HRAM-RES-39`/`HRAM-VIS-2`, consuming panels hide MUI's own legend and render a hand-built
+   one as **HTML** beside the chart, with the size key as a *second* SVG. Both sit outside the
+   exported element. **Before that consolidation, MUI's legend was inside the chart SVG and did get
+   exported** — unstyled, but present. Fixing a legend overlap silently degraded the export, and
+   nobody noticed because nobody opened an exported file.
+
+3. **"The first SVG" is fragile** regardless — a panel that renders any SVG ahead of the chart
+   exports the wrong element. It works today by accident of ordering.
+
+### The decision: two paths, two meanings
+
+The operator chose option C on 2026-08-25. The two buttons already promise different things and
+should stop pretending to be one mechanism:
+
+- **SVG — the chart, faithfully styled.** Keep the clone-and-serialise path, but **inline computed
+  styles onto the cloned nodes** before serialising. Stays true vector: scalable, editable in
+  Illustrator/Inkscape, chart only. It does **not** gain the legend, and that is correct for what
+  this format is for.
+- **PNG — the container, as seen.** Rasterise the whole `chartRef` node rather than the chart SVG, so
+  legend, size key and footnotes are in the file and the output matches the screen by construction.
+
+**Make the difference legible to the user, not only to us.** Two buttons that produce visibly
+different content need labels or tooltips saying so; today they read as one thing in two formats.
+
+### Scope
+
+**`src/components/charts/exportChart.js`**
+
+1. **Inline computed styles** into the SVG clone before serialisation. Walk the clone against the
+   live tree and write the resolved properties as inline style. Keep it to the properties that matter
+   for chart rendering rather than dumping every computed property — a full dump produces enormous
+   files and is its own defect.
+2. **Rasterise the container for PNG.** The `chartRef` node ChartFrame already passes
+   (`ChartFrame.jsx:138`) is the right root — it holds the chart plus everything the panel renders
+   beside it.
+3. **Stop relying on "the first SVG"** for the SVG path — take the chart deliberately, not
+   positionally.
+4. **Preserve the public signatures.** `exportChartSvg(container, filename)` and
+   `exportChartPng(container, filename, backgroundColour)` are consumed by `ChartFrame` and possibly
+   directly; the change is what they produce, not how they are called.
+
+**`src/components/charts/ChartFrame.jsx`** — labels or tooltips that distinguish the two outputs.
+Translated via the existing `chartsTranslations` path, not hard-coded.
+
+### Non-goals / do not touch
+
+- The chart presets, `resolveChartLayout`, the size scale, the axis bands.
+- Consuming apps. hram's six panels with `exportOptions` gain the fix through the pin bump; that is
+  a separate row.
+- Adding export to panels that do not have it (`HRAM-RES-43` did that for one panel in hram).
+
+### Risks
+
+- **A rasteriser is a new dependency in shared-core**, and this package currently has exactly one
+  runtime dependency (`@fontsource/dm-sans`). Adding a second is a real decision — check whether the
+  job can be done with the platform's own APIs first, and if a library is warranted, say why in the
+  WO's implementation record rather than just installing one.
+- **Canvas tainting.** DOM-to-canvas rasterisation routes through an SVG `foreignObject`; any
+  external image or font reference taints the canvas and `toBlob` throws. The existing PNG path
+  already has this exposure and may already be failing on it — worth checking before assuming the new
+  path introduces it.
+- **Fonts in the SVG.** Inlining computed styles records `font-family: "DM Sans"`, which a machine
+  without that font will substitute. Either embed the font or accept the substitution — but decide it
+  and write it down, because a silently substituted font is exactly the "looks different" complaint
+  this WO is fixing.
+- **Style inlining can bloat.** See scope item 1.
+- **This has no test that can see it.** A unit test can assert that a `style` attribute exists; it
+  cannot see that the file looks right. See verification.
+
+### Verification
+
+**Open the exported files.** That is the whole gate, and its absence is why this defect shipped: the
+SVG in a viewer and the PNG in an image viewer, both compared against the rendered panel.
+
+Do it for **two** panels with different shapes — one with a hand-built legend and size key
+(`AccessGapScatterPanel`), one without — because the legend behaviour is precisely what differs
+between the two export paths.
+
+Unit tests: the SVG clone carries inlined styles for tick labels and axis strokes; both entry points
+still resolve with their existing signatures; the PNG path resolves for a container holding more than
+one SVG.
+
+---
+
+## Part B — Implementation map
+
+`.claude/models.local.json` has no local override, so the default applies: `implementation.runtime`
+is `claude`/`sonnet` — the Orchestrator implemented directly, no Codex dispatch.
+
+**Dependency decision (risk section, and Part C's approval gate):** no library added. Checked
+first, per the WO's own instruction, and it held up: the platform's own `<foreignObject>` → `Image`
+→ `<canvas>` pipeline works for arbitrary DOM rasterisation with no dependency at all. The one
+obstacle — **confirmed live, not assumed** — is that Chrome taints the canvas on `toBlob`
+unconditionally the moment the source SVG contains a `<foreignObject>` with HTML content, even with
+zero external references (a minimal repro: a `<foreignObject>` holding one `<div>` with inline
+`color: red` styling and no images/fonts/external refs still throws `SecurityError: Tainted
+canvases may not be exported` when the SVG is loaded via `URL.createObjectURL`). The SAME SVG loaded
+via a `data:` URI instead does **not** taint the canvas — confirmed with an identical minimal repro,
+then re-confirmed end-to-end against the real `exportChartPng`/`ChartFrame` (real Chrome, via the
+dev harness). This is why the approval gate never triggered: the platform-only approach IS viable,
+it just needed the `blob:` → `data:` URI swap in `rasterize` (`exportChart.js`), documented inline
+there.
+
+**Canvas tainting on the PRE-FIX path:** checked per the risk section's own instruction ("may
+already be failing on it"). It was not — a plain SVG-only blob (no `foreignObject`) loaded via
+`URL.createObjectURL` does **not** taint the canvas; the exposure is specific to the `foreignObject`
+this WO's PNG path adds, not a pre-existing defect.
+
+**Verification (both real-browser, via the dev harness's module graph — `dev/entries.jsx` never
+committed a probe entry, all verification was done by dynamically rendering `ChartFrame` into a
+detached container and calling the real `exportChartSvg`/`exportChartPng`):**
+
+- Panel shape WITH a hand-built legend + size key (mirroring `AccessGapScatterPanel`: MUI's own
+  legend hidden, a `<div>` HTML legend with a coloured swatch, a second `<svg>` "size key" beside
+  the chart): PNG rasterised at 2x scale, no taint, and pixel-sampling the produced PNG at the
+  swatch's and size-key's known screen coordinates read back their EXACT source colours
+  (`rgb(25,118,210)` / `#1976d2` and `rgb(156,39,176)` / `#9c27b0`) — the legend and size key are
+  genuinely present in the raster, not just "no error thrown". SVG export of the same panel:
+  contains `MuiChartsSurface-root` (the chart), does NOT contain the legend's own text/markup —
+  chart-only as designed.
+- Panel shape WITHOUT a hand-built legend (plain `BarChart` inside `ChartFrame`): both exports
+  resolve cleanly, no regression for the common case.
+
+Context package used: `exportChart.js` (rewritten in full, was short), `ChartFrame.jsx:42-108`
+(the `runExport`/`exportOptions` wiring) and `:137-151` (`chartRef`, the export root — confirmed
+correct: it wraps `content` only, excluding the meta/export-button footer), `chartsTranslations.ts`
+(new `EXPORT_SVG_TOOLTIP`/`EXPORT_PNG_TOOLTIP` keys, all four locales).
+
+---
+
+## Part C — Orchestrator only
+
+> **STOP — everything below addresses the Orchestrator.**
+
+**Tier 3 · verification: opened files for two panel shapes, plus the unit tests above**
+
+Shared-core, and — depending on scope item 2's answer — a dependency addition, which is its own
+approval surface under Core Behaviour. If a library is needed, **stop and get the operator's
+approval for that specific dependency** before adding it; the approval given on 2026-08-25 was for
+the approach, not for a named package.
+
+- `reviewer` — the inlining's completeness and the taint/font questions.
+- `ui_reviewer` — whether the two buttons now read as two different things to a user.
+- `sec_reviewer` — not run; no auth, data or exposure surface.
+
+### Release
+
+**Minor → 3.3.0**, per the operator. The PNG's *content* changes (it now includes the legend and
+footnotes), so the CHANGELOG entry must **lead** with that, in the style `UCM-CHART-15` established:
+a consumer who bumps and finds their exported PNGs different should read why in the first line, not
+find it in a bullet.
+
+### Register
+
+Row `UCM-CHART-17`, both review notes, the published version, landing SHA(s) in a second commit
+before the push. Record what the opened files actually looked like — that evidence is the point.
+
+Consumer adoption (hram's pin bump) is a separate row; a shared-core fix that is published but not
+consumed is not finished.
+
+### Log
+
+- **2026-08-25** — Envelope authored after the operator reported exports producing graphically very
+  different plots. Diagnosed from source, not reproduced by the Expertenchat: the operator has seen
+  the files. Option C chosen — SVG stays vector and chart-only, PNG becomes what the screen shows.

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

@@ -0,0 +1,200 @@
+# UCM-CHART-18 — The PNG export shows what the chart says, not what the user can click
+
+## Part A — Envelope
+
+*Authored by the Expertenchat. Authoritative WHAT/WHY.*
+
+### Goal
+
+The whole-container PNG export contains the chart and everything that **explains** it, and none of the
+controls that **operate** it. And a rotated element exports rotated.
+
+### Two defects, one file, a few lines apart
+
+Both raised by `HRAM-CHT-7`'s independent `ui_reviewer` on 2026-08-25 and confirmed — partly by
+reading, partly live in the running app.
+
+**1. Interactive controls are in the image.** Since 3.3.0 the PNG rasterises `ChartFrame`'s whole
+`chartRef` box, and `chartRef` wraps `children` only — not `toolbar`, `controls` or `meta`. Anything a
+panel renders as children is now in the file. In hram:
+
+- `StructuralReachabilityPanel.jsx:468` — the footer "More about these caveats" `IconButton`, always
+  visible, so **every** PNG of that panel carries a button.
+- `AllocationPerformancePanel.jsx:536,548` — the drill-down `Button`, and `ResearchDrilldownPanel`
+  itself when open, both inside the `<ChartFrame>` children.
+- `OptimizationResultsPanel.jsx:1120,1141` — the same shape on the frontier chart.
+
+**2. `transform` is not inlined.** `CHART_STYLE_PROPERTIES` (`:32-36`) and
+`CONTAINER_LAYOUT_STYLE_PROPERTIES` (`:44-52`) do not list it, so
+`OptimizationResultsPanel.jsx:1107`'s rotated legend swatch exports as a **square instead of a
+diamond**.
+
+### Why this is fixed here and not in the consuming app
+
+The alternative was moving each panel's controls out of `children` into `ChartFrame`'s `controls` /
+`toolbar` slots, which sit outside `chartRef`. That was rejected, for two reasons:
+
+- **It is a property of the element kind, not of each panel.** An exported image should show what the
+  chart communicates, not what can be clicked. Solved generically here, it also holds for every
+  consumer nobody has looked at.
+- **It would undo a deliberate design decision.** `StructuralReachabilityPanel`'s info affordance sits
+  in the **footer**, beside the caveat line, because `HRAM-RES-30` put it there. Hoisting it into the
+  toolbar to dodge an export defect would trade a design choice for a workaround.
+
+After this, hram needs **only a pin bump** — `HRAM-CHT-8` becomes a consumer row, not a rebuild of
+three panels.
+
+### Scope
+
+`src/components/charts/exportChart.js`
+
+1. **Drop interactive controls from the container clone** in `containerSvgBlob` (`:120`) — `button`,
+   `input`, `select`, `textarea`, `[role="button"]` at minimum. The SVG path is unaffected: it
+   exports the chart surface, which holds no HTML controls.
+
+2. **Do it *after* `inlineComputedStyles`, never before.** That function walks source and clone
+   **in lockstep by index** (`:70-77`, `sourceNodes[index]` ↔ `cloneNodes[index]`). Removing nodes
+   from the clone first shifts every subsequent index, so elements silently receive their
+   neighbours' styles — an export that looks plausible and is wrong everywhere after the first
+   removal. **This is the single most likely way to get this WO wrong.**
+
+3. **Add `transform` (and `transform-origin`) to the inlined properties.**
+
+### Non-goals / do not touch
+
+- The SVG export path, `findChartSvg`, the `data:`-URI decision, the taint workaround —
+  `UCM-CHART-17`, done and verified.
+- `ChartFrame`'s slot structure. `chartRef` wrapping `children` only is correct; the fix is what the
+  rasteriser does with them.
+- The consuming panels. hram's adoption is `HRAM-CHT-8`.
+
+### Risks
+
+- **The lockstep-index trap.** Scope item 2. Name it in the code comment too, not only here.
+- **What disappears must be operation, not content.** A consumer whose legend items are `<button>`s —
+  MUI's own legend can be interactive — would lose its legend to this change. The affected hram panels
+  all pass `hideLegend`, so they are not the test case. **Verify against a chart that keeps MUI's own
+  legend**, and if it vanishes, that is a finding that changes the approach, not a detail to paper
+  over.
+- **`transform` may double-apply on SVG nodes.** An SVG element can carry `transform` as a
+  *presentation attribute*, which the clone already keeps, while `getComputedStyle` returns the
+  resolved CSS transform. Writing that inline could compose with the attribute and move the element
+  twice. Check on a chart with rotated tick labels (`xLabels="angled"`) before assuming it is inert.
+- Removing nodes changes layout if anything sized around them — a flex row that held a button now
+  has one fewer item. Expected, but look at it rather than assuming it is invisible.
+
+### Verification
+
+**Open the files.** Same gate as `UCM-CHART-17`, and for the same reason — both of these defects were
+invisible to every test and visible immediately in an exported image.
+
+1. A PNG of a panel with a control in `children`: the control is gone, everything else is where it
+   was.
+2. A PNG of a chart that keeps **MUI's own legend**: the legend is still there. This is the
+   counter-check for the risk above, and it is not optional.
+3. A rotated element exports rotated — the diamond is a diamond.
+4. A chart with `xLabels="angled"`: tick labels are not doubly rotated or displaced.
+
+Unit tests: the clone contains no `button` after export; a non-interactive sibling at the same depth
+survives; `transform` appears in the inlined declarations.
+
+---
+
+## Part B — Implementation map
+
+`.claude/models.local.json` has no local override, so the default applies: `implementation.runtime`
+is `claude`/`sonnet` — the Orchestrator implemented directly, no Codex dispatch.
+
+Implemented exactly per scope: `transform`/`transform-origin` added to `CHART_STYLE_PROPERTIES`
+(shared by both export paths); a new `INTERACTIVE_CONTROL_SELECTOR`
+(`button, input, select, textarea, [role="button"]`) and `stripInteractiveControls` helper, called
+in `containerSvgBlob` strictly **after** `inlineComputedStyles` (the lockstep-index trap named in
+the WO) — verified by temporarily reverting the ordering-safe call and confirming the new tests
+fail, then restoring.
+
+**Verification (real Chrome, via the dev harness's module graph — no probe entry committed to
+`dev/entries.jsx`, all four cases rendered via direct script injection into detached containers):**
+
+1. Control in `children` (an `IconButton` beside a `<span>` caveat note, mirroring
+   `StructuralReachabilityPanel`'s footer affordance): captured the PNG path's actual intermediate
+   SVG (intercepting `Image.src`) and confirmed no `<button` tag and no button text present, while
+   the sibling text and the chart itself both survive.
+2. MUI's own legend (two-series `BarChart`, no `hideLegend`): confirmed live that MUI's legend
+   renders as `<ul>/<li>/<div>/<span>` (no `button`/`role="button"` in it), then confirmed both
+   series labels ("Opened", "Resolved") and the `MuiChartsLegend-root` class survive the export
+   fully intact.
+3. Rotated element: a 24x24px swatch with `transform: rotate(45deg)`, exported to PNG and
+   pixel-sampled on a real `<canvas>` — the swatch's own bounding-box corner reads back as
+   background white, its centre as the swatch's own red, i.e. a genuine diamond (clipped corners),
+   not an unrotated square.
+4. `xLabels="angled"` (7 long category labels): the exported tick `<text>` carries BOTH its
+   original `transform="rotate(-45, 30, 9)"` XML presentation attribute (kept by `cloneNode`) AND
+   the newly-inlined `style="transform: matrix(0.707107, -0.707107, 0.707107, 0.707107, ...)"`.
+   The matrix values are exactly `cos(-45°)=0.707107, sin(-45°)=-0.707107` — a SINGLE 45° rotation,
+   not a doubled/composed one (which would show different values, e.g. matching -90°) — confirming
+   the inline `style` declaration wins over the presentation attribute (SVG2: presentation
+   attributes carry the lowest specificity) rather than composing with it. Tick text still renders
+   non-blank.
+
+Context package used: `exportChart.js` in full (short, already read start to finish),
+`ChartFrame.jsx:137-151` (`chartRef` — re-confirmed it wraps `children` only).
+
+**Post-review correction, both reviewers converging independently on the same gap the WO's own
+risk section named:** the initial `stripInteractiveControls` removed EVERY matched element
+outright, including MUI's own chart legend when it is interactive
+(`onItemClick`/`toggleVisibilityOnClick`) — X-Charts renders each legend item as
+`<button role="button" class="...MuiChartsLegend-series...">` wrapping the series swatch and
+label, so a blanket removal deleted the legend's content along with its click handler. This is
+EXACTLY the WO's own risk section, made concrete: "if it vanishes, that is a finding that changes
+the approach, not a detail to paper over." Fixed by UNWRAPPING `MuiChartsLegend-series` matches
+(replace with a plain `<span>` carrying the same class/style/children) instead of removing them —
+content survives, only the (irrelevant, in a static image) clickability is dropped. Re-verified
+live against a REAL interactive legend (`slotProps={{ legend: { toggleVisibilityOnClick: true } }}`,
+confirmed the live legend items render as actual `<BUTTON>` tags): the export contains zero
+`<button` tags, but `MuiChartsLegend-series` and both series labels survive intact. `INTERACTIVE_
+CONTROL_SELECTOR` also broadened to `a[href]`/`[role="link"]` (reviewer finding — a drill-down
+built as a link, not only a `<Button>`, is equally out of place in an export).
+
+Also fixed a genuine test-coverage gap the reviewer found: the original ordering test's `<button>`
+was the LAST descendant in its fixture, so a "strip before inline" regression would not have shifted
+any node the test actually asserted on — content-presence checks can't observe a style
+misattribution at all, only a missing/wrong STYLE VALUE can. Rewrote it with a distinctively-styled
+sibling AFTER the button (stylesheet-driven colour, not an inline style `cloneNode` would copy
+regardless) and confirmed, by temporarily reverting the call order, that the new assertion actually
+fails when the order is wrong (the button's own style — `border-style: none`, `text-align: center`
+— leaks onto the trailing sibling).
+
+---
+
+## Part C — Orchestrator only
+
+> **STOP — everything below addresses the Orchestrator.**
+
+**Tier 3 · verification: opened files for the four cases above, plus the unit tests**
+
+Shared-core, by the tiering table regardless of diff size.
+
+- `ui_reviewer` — what belongs in an exported image, and the MUI-legend counter-check.
+- `reviewer` — the ordering trap and the `transform` double-apply question.
+- `sec_reviewer` — not run; no auth, data or exposure surface.
+
+### Release
+
+**Patch → 3.3.1.** This repairs behaviour 3.3.0 itself introduced — the whole-container PNG was never
+meant to carry buttons — rather than adding capability. `UCM-CHART-16` (a repair) went out as a patch
+on the same reasoning, while `-15` and `-17` were minors because they changed what a consumer gets on
+purpose. The CHANGELOG should still say plainly that exported PNGs no longer contain controls; a
+consumer who liked the button in their image deserves to find out by reading, not by looking.
+
+### Register
+
+Row `UCM-CHART-18`, both review notes, the published version, landing SHA(s) in a second commit
+before the push. Record what the opened files looked like, including the MUI-legend counter-check.
+
+Consumer adoption is `HRAM-CHT-8`, which this WO reduces to a pin bump.
+
+### Log
+
+- **2026-08-25** — Envelope authored. The operator chose the shared-core fix over moving controls in
+  three hram panels, so that the rule holds for every consumer and `HRAM-RES-30`'s footer placement
+  survives.