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

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Only notable, user-facing changes. Not every version — see `WORK_ORDERS.md` for the full history.
 
+## 3.2.1 — UCM-CHART-16
+
+**A horizontal-axis chart with a title, or a large-enough tick font, could render every tick
+label blank.** The x-axis tick band reserved a flat, font-size-independent floor; MUI's own
+internal fit check (`shortenLabels`, against `tickLabelsMaxHeight`) blanks every tick label the
+moment the real rendered text is even slightly taller than that floor leaves room for once MUI's
+own tick/gap overhead — and, when a title shares the same band, its own gap too — is subtracted.
+Correctly positioned tick marks with zero visible label text is the exact, easy-to-misread
+signature; two hram consumers had independently patched around it with the same empirically
+measured `height: 56` before this was traced to its shared-core cause.
+
+The band is now derived from the actual tick font size (and whether an axis title shares it)
+instead of the flat floor, matching MUI's real fit check rather than only its generic default.
+Patch, not minor: this repairs existing behaviour — the SAME size tokens render at the SAME
+heights (`UCM-CHART-15` is untouched) — the only change is the flat tick band growing by a few
+pixels on charts that were previously either mis-sized or silently blanking their labels. The
+rotated-tick path (`xLabels: "angled"`) is unaffected.
+
 ## 3.2.0 — UCM-CHART-15
 
 **Breaking visual change: every existing chart using a `size` token — including the default

package/WORK_ORDERS.md

@@ -27,6 +27,7 @@ prefixed ID; never reuse a bare flat number across workstreams.
 
 | ID | Titel | Beschreibung | Datum | Status | Commit(s) | Notiz |
 |---|---|---|---|---|---|---|
+| UCM-CHART-16 | The x-axis band starves MUI's tick-fit check, and two consumers have patched around it | A chart with an axis title **and** horizontal tick labels must render its tick labels without a consumer hand-setting `xAxis[].height`. **Defect:** on the horizontal path `resolveXAxisGeometry` reserves one combined band from `TICK_BAND_BASE_PX` + `AXIS_TITLE_BAND_PX`; once a title is also taken from that budget, MUI's own fit check (`shortenLabels` against `tickLabelsMaxHeight`) is left **just under one line of 12 px text** and blanks **every** label regardless of content. Distinctive and easy to misread: correctly positioned tick marks, zero non-empty label texts -- looks like a data or formatter problem and is neither. **Evidence: two consumers, same workaround, same magic number**, independently, in two different WOs -- hram `StructuralReachabilityPanel.jsx:386` (`HRAM-RES-32`) and `AccessGapScatterPanel.jsx:212` (`HRAM-RES-39`), both `height: 56`. RES-32's own comment already diagnosed it and called it *"a pre-existing, latent shared-core near-miss"*, then patched locally because a shared-core fix was outside that WO; RES-39 read the MUI source, reached the same cause and the same 56, and patched locally again. **The third titled-horizontal-axis chart will hit it too**, and the package is meanwhile violating its own stated Rule 1 (*"nothing outside the resolver does chart arithmetic"*) in two places. Fix: correct the reservation, and **derive** it from the known tick font size and title band rather than adding a second magic number that will be wrong at a different font size. Full order [`work-orders/UCM-CHART-16.md`](work-orders/UCM-CHART-16.md) | 2026-08-25 | done | `9830266` | **Tier 3** -- shared-core. `reviewer` + `ui_reviewer` (the plot-area change across consumers); no `sec_reviewer`. **The risk that decides this WO: a mocked prop-assertion test cannot catch it.** The file already records the same trap for a neighbouring bug (*"a mocked prop-assertion test cannot catch this, it only reproduces on an actual MUI scale computation"*) -- a test asserting the computed band's number passes whatever the number is. **Test 1 must observe rendered label text**, or it is decoration. Also: raising the band changes every titled-horizontal-axis chart's plot area, on top of `UCM-CHART-15`'s 80 px shift -- and fixing it too generously wastes vertical space everywhere, so the near-miss margin is the budget, not a number rounded up to be safe. Release patch unless the plot-area change warrants minor; say which and why in the CHANGELOG. Consumer cleanup (removing hram's two workarounds) is `HRAM-CHT-6`, after this ships. **Third occurrence, 2026-08-25, and it changes the fix:** hram's `AccessibilityPanel` in `Urban/Peri-urban/Rural x Division` mode -- five band categories, five rendered bar groups, **no tick labels at all**, same signature. But that chart has **no `xAxisLabel`**, so the title is not competing for the band; what it has is `tickLabelStyle: { fontSize: 13 }`, one pixel above the 12 px the base band was sized against. **So the trigger is not "a title takes the room" -- it is that the band is a near-miss at all**, and anything consuming a little more pushes it over. A fixed `height: 56` patched into a third consumer would work at 13 px and fail at 14. That is exactly why scope item 2 requires the resolver to **derive** the requirement from the tick font size it already knows, instead of adopting the constant two consumers measured empirically at 12 px. Signature-matched, not yet instrumented -- confirm the mechanism on this third case, since it is the one that distinguishes a derived fix from a bigger constant. **Implementation:** `.claude/models.local.json` has no local override (defaults apply) -- `implementation.runtime` is `claude`/`sonnet`, implemented directly by the Orchestrator, no Codex dispatch. **The defect could not be confirmed from source reading alone** (jsdom does not implement real SVG text measurement, `getBBox`, so a rendered test would trivially pass regardless of correctness): reproduced and calibrated against the real, unmocked `BarChart` in this repo's own dev harness (Chrome, DM Sans, via `dev/entries.jsx`, reverted before commit) -- confirmed the defect reproduces exactly as described, confirmed it does NOT reproduce under MUI's default Roboto stack (explains why it was font-dependent and missed until a consumer used a taller font), then binary-searched the real minimal `xAxis[].height` at ten font-size/title combinations (11-18px) to derive `TICK_TEXT_HEIGHT_FACTOR=1.3`, `TICK_BAND_MUI_OVERHEAD_PX=9`, `TICK_BAND_TITLE_EXTRA_PX=2` -- matched every measured threshold within 1px, never under. Third occurrence (no title, `tickLabelStyle.fontSize:13`) confirmed via the same harness. 180 affected chart tests green (78 `chartDefaults.test.js` + 2 new rendered tests in `chartAxisTickBand.test.jsx`, which install a calibrated `SVGElement.prototype.getBBox` mock since jsdom's real implementation always measures 0x0 + 100 across `BarChart`/`LineChart`/`ScatterChart`/`TimeSeriesChart`/`ChartFrame`), `tsc -p tsconfig.build.json` clean. Both new resolver tests and both new rendered tests independently confirmed to fail against the pre-fix resolver (temporarily reverted, reran, restored) -- test 1 must observe rendered label text, not a computed number, per the WO's own risk section; both requirements met. Version bumped `3.2.0` -> `3.2.1` (patch, per the WO's own classification -- repairs existing behaviour, `UCM-CHART-15`'s heights untouched). **Review: codex/gpt-5.6-luna (`reviewer`) · 3 raised · 1 accepted · worst accepted: defect · chosen** (id not divisible by 5, no rotation configured). `reviewer` findings: (1) ACCEPTED -- the Rule-2 guardrail test only asserted `xTitleBand === 0`, which passes whether or not the title margin leaked into `xAxisBand` instead; fixed to assert the actual band/height values too. (2) REJECTED, out of scope -- a caller-supplied `xAxis[].tickSize` override isn't a documented/supported customization point of this package (grep confirms zero call sites, in this repo or its own tests/docs, ever set it); adding speculative handling for an unused knob is the "second magic number" pattern this WO exists to avoid. (3) REJECTED, out of scope -- a custom/multiline title font size overflowing the fixed `AXIS_TITLE_BAND_PX=20` reservation is a pre-existing `UCM-CHART-12`-era limitation, unchanged and unworsened by this WO. **`ui_reviewer`: codex/gpt-5.6-luna dispatch produced NO USABLE VERDICT** -- ran for an extended period repeatedly re-executing `vitest`/`git` against the live working tree (including applying then reverting a debug `console.log` in the new test file -- confirmed harmless via `git diff`/content check, but a review process should never write to the shared tree) and terminated with exit 0 but no findings/verdict text. Treated as unusable per "a review never lapses because a provider is down" -- fell back to `review_fallback` (`claude`/`sonnet`), spawned read-only, explicitly instructed not to run tests or mutate anything: **no findings**, confirmed the fix is byte-identical to the pre-fix band at the package's own default tick font (zero growth for unaffected charts), the CHANGELOG communicates the visual consequence plainly, and patch is the right classification. **Flagged for awareness, not fixed here:** the codex `ui_reviewer` runaway-without-verdict pattern is worth watching for future Tier-3 dispatches -- consider adding an explicit "review only, do not modify files or run mutating commands" line to review prompts. |
 | UCM-CHART-15 | Shift the chart size scale up one step, and raise the ceiling | `compact` 30->**40** (240->**320 px**), `standard` 40->**50** (320->**400**), `tall` 50->**60** (400->**480**), plus **`extra_tall` 70 (560)** and **`super_tall` 80 (640)**. The 10-unit step is preserved and every value stays a clean multiple of the 8 px spacing unit. **Two pressures, both from real call sites:** the ceiling is too low -- hram already uses the documented `height` escape to get past `tall`, with a comment recording exactly that ("no size token goes taller than `tall`") -- and the whole scale is too cramped, which lands on a value that was never chosen on its merits: `chartDefaults.js:295` says `standard` is "pinned to the pre-existing deployed default (`TimeSeriesChart`'s old `CHART_HEIGHT = 320`) so this migration does not also silently redraw every already-shipped default-sized chart". **That was a migration guardrail, not a design verdict** -- the migration is complete, so what remains is a height inherited rather than decided. Full order [`work-orders/UCM-CHART-15.md`](work-orders/UCM-CHART-15.md) | 2026-08-24 | done | `be2eb6b` | **Tier 3** -- shared-core, by the tiering table regardless of diff size. `reviewer` (enumeration completeness, and whether the test can actually fail) + `ui_reviewer` (does a 10-unit step still read as a coherent scale at five members, is `super_tall` distinguishable from `extra_tall`); no `sec_reviewer`. **Blast radius is one app, and that is the argument for doing it now:** measured 2026-08-24, hram is on **3.0.1 and is the only 3.x consumer**; the other 14 apps are on 2.41.3/2.37.0, where the size tokens do not exist (a 3.0.0 feature, this repo's CHANGELOG marks 3.0.0 "Breaking"). Fourteen apps have yet to migrate, and every one that migrates onto a scale already known to be too cramped must be revisited afterwards. **Version: minor (3.2.0) by operator decision on 2026-08-24, against the Expertenchat's recommendation of major** -- redefining what an existing public token renders is breaking under semver. Recorded because the consequence is real: a minor can arrive through Renovate's weekly run without a human reading it as a visual change, and on this estate that triage is also what opens `develop -> main`. **Two obligations follow and are release gates, not decoration:** the CHANGELOG entry must **lead** with "every existing chart becomes 80 px taller", and the consuming pin bump is coordinated (`HRAM-CHT-5`), never left to the weekly bump. **Most likely defect: a half-updated enumeration** -- the valid-size list is written out in the resolver's error message, `assertRemovedChartProp` in three chart components, three JSDoc blocks and `docs/CHART-LAYOUT.md`; grep the literal `"tall"` before declaring it done. **Implementation:** `.claude/models.local.json` has no local override (defaults apply) -- `implementation.runtime` is `claude`/`sonnet`, implemented directly by the Orchestrator, no Codex dispatch. Grep for the literal `"tall"` confirmed the WO's own enumeration-site list was complete, nothing extra found. 176 affected chart tests green (76 `chartDefaults.test.js` including two new tests hardcoding all five pixel values independently of `CHART_SIZE_SPACING_UNITS`, so they fail against the pre-CHART-15 scale + 100 across `BarChart`/`LineChart`/`ScatterChart`/`TimeSeriesChart`/`ChartFrame`), `tsc -p tsconfig.build.json` clean. Version bumped `3.1.2` -> `3.2.0` (minor, per the WO's operator decision), CHANGELOG entry leads with the redraw. **Review: codex/gpt-5.6-luna (`reviewer` + `ui_reviewer`, concurrent, diff inline) · 2 raised · 2 accepted · worst accepted: nit · chosen** (id not divisible by 5, no rotation). `reviewer`: nit -- a stale `"240px"` example in a `theme.spacing` comment at `chartDefaults.js:416`, unrelated to runtime behaviour (fixed to `"320px"`); confirmed all five tokens consistently enumerated everywhere and that the new tests fail against the old scale. `ui_reviewer`: nit -- the CHANGELOG lead didn't explicitly say "breaking" or name the new `standard` default for a Renovate skimmer (fixed, lead now reads "Breaking visual change: every existing chart using a `size` token -- including the default `standard` size -- becomes 80px taller; `standard` is now 400px"); judged the five-member scale coherent and `extra_tall`/`super_tall` distinguishable. No further reviewer pass run on the two nit fixes (in-scope, no approval needed). |
 | DX-3 | `publish.yml` tests before it builds, so `2.41.2` cannot publish | `DX-2` landed on `main` (`31675d8`, `e75192f`) and **its publish failed** — run [32029216699](https://github.com/bigler-webapps/ui-core-micha/actions/runs/32029216699), `completed/failure`. `publish.yml` runs `Run tests` **before** `Build`; `DX-2`'s new `tests/packageTreeShaking.test.js` copies the package's own `dist/` to assemble a fake installed consumer, and **`dist/` is gitignored** (`.gitignore:2`), so in a clean checkout it does not exist yet: `ENOENT ... lstat '.../dist'`, 510/511 passing with the one new test as the sole failure. The test is neither flaky nor wrong — it inspects the built artifact, which is the point; it cannot pass in the order the workflow runs. It was green locally at 511/511 only because a `dist/` from an earlier build was lying around. Full order [`work-orders/DX-3.md`](work-orders/DX-3.md) | 2026-08-17 | done | 67fe140 | Tier 3 — CI surface, independent `reviewer` mandatory for two lines; no `ui_reviewer`. Fix: move `Build` above `Run tests`, **keeping `if: steps.version_check.outputs.should_publish == 'true'` on both** — dropping one is the only way a reorder can go wrong, so the reviewer is asked to confirm it explicitly. Codex implemented (available today per `.claude/codex-status.md`, no prior fallback needed) — one-file, 4-line diff, nothing else touched. **Independent `reviewer` (Sonnet) confirmed: only file changed, both `if:` conditions retained on Build and Run-tests, order now install→Build→Run-tests→npm-bump→Publish, `tsc` (Build) emits `dist/` before `vitest run` (tests) needs it — no findings, safe to commit.** **Dispatch:** landing the fix did not re-trigger `publish.yml` (its `paths` filter excludes `.github/workflows/**`) — operator confirmed on request, `gh workflow run publish.yml --ref main` dispatched, run [32032549303](https://github.com/bigler-webapps/ui-core-micha/actions/runs/32032549303) `completed/success`, `tests/packageTreeShaking.test.js` passing (not skipped) in the run order fixed above. **Acceptance verified against the registry, not the tile: `npm view @micha.bigler/ui-core-micha version` → `2.41.2`.** `DX-2`'s deliverable is now actually consumable. **The dispatch is the part most likely to be missed:** `publish.yml`'s trigger `paths` cover `package.json`/`pnpm-lock.yaml`/`src/**`/`tsconfig.build.json` but **not `.github/workflows/**`**, so landing this fix does NOT re-trigger the publish — `2.41.2` sits unpublished until `publish.yml` is dispatched on `main`, which needs explicit operator confirmation (not on the safe-allowlist). No version bump: the artifact being published is DX-2's. **Acceptance is `npm view` returning `2.41.2`, not a green tile** — the publish status of this package has now been misreported in both directions in one session. Do NOT skip, delete or self-build the tree-shaking test; a skip would silently retire the only check that `sideEffects` actually tree-shakes. **Recorded, out of scope:** `publish.yml` is the ONLY workflow here that runs tests, and only when `should_publish` is true — so ucm's suite runs in CI *only on a version bump*, and a `src/**` change without one is never tested. Real gap for a twelve-consumer shared core, separate decision. |
 | DX-2 | Declare `sideEffects` so consumers can tree-shake the kit | `package.json` has **no `sideEffects` field** and no `exports` map, so a bundler must assume every module can have an import side effect and cannot drop unused exports — twelve consumers ship the whole kit whatever they import. Measured, not theorised: `hram/THEME-2` switched from three named bundles to the full aggregate and the built size changed by **−11 bytes**. Full order [`work-orders/DX-2.md`](work-orders/DX-2.md) | 2026-08-12 | done | 31675d8 | Tier 3. Codex implemented (available today, no prior fallback needed). **Array form used, not blanket `false`** — the per-module audit found exactly one real import-time side effect group: font CSS. `src/theme/createAppTheme.js` and `src/theme/index.js` both used to `import '@fontsource/dm-sans/*.css'` at module scope; isolated into a new `src/theme/fonts.js`, declared in the `sideEffects` array (both `src/`/`dist/` forms) alongside `index.js`, `theme/index.js`, `theme/createAppTheme.js`, and `notifications/serviceWorker/sw.js` (a genuine `addEventListener` side effect, conservatively listed even though it isn't reachable from `src/index.js` — consumers import it directly). `uiCoreTranslations`'s aggregate-object construction relocated verbatim from `src/index.js` into `src/i18n/uiCoreTranslations.js` (no shape/value change) so the entry module carries no non-trivial logic beyond its own font import. New test `tests/packageTreeShaking.test.js` builds two throwaway consumer bundles against the real `dist/` output via Vite and asserts translations actually tree-shake. **Independent `reviewer` (Sonnet) redid the module-by-module audit from scratch** (walked theme/, auth/apiClient, notifications/realtime, messaging/, onboarding/, i18n/ for CSS imports, `document`/`window`/`self` mutation, axios interceptors, WebSocket construction, i18next `.use()/.init()`) and independently ran `pnpm run build` + the new test — **verdict: classification correct and complete, no missed side effect, safe to commit.** One non-blocking finding, addressed: **`src/index.js`'s font import is unconditional, so `@fontsource/dm-sans` CSS ships in every consumer's bundle regardless of import — it does NOT tree-shake**, and the reviewer flagged that the reported byte delta could be misread as covering the whole entry when it is translations-only. Added a one-line comment at `src/index.js:3` documenting the font/`sideEffects`-array coupling so a future edit can't decouple them silently (the exact false-negative hazard this WO exists to prevent). **Re-measured delta** (built `dist/`, minified, real bundler, supersedes both `I18N-1`'s `+28,943 B`/`+7,327 B` source-reachability figure and `THEME-2`'s `−11 bytes` no-tree-shaking baseline): auth-only **62,294 B raw / 17,653 B gzip** vs. aggregate **90,395 B raw / 25,045 B gzip** → **+28,101 B raw / +7,392 B gzip, translations only — font CSS is a separate, always-shipped, non-tree-shakeable cost not included in this number.** Written into `I18N-2`'s note below. Scoped tests: `pnpm run build` green, new test green, **full existing suite 511/511 green** (WO called for the existing suite as the scoped run, not full-estate). No rendered gate (nothing renders). Version bumped to `2.41.2` (patch by scope, per the WO). **Correction (2026-08-17): the publish failed** — `publish.yml` runs tests before build, and this WO's own new tree-shaking test needs `dist/` (gitignored), so it cannot pass on a clean checkout; registry stayed at `2.41.1`. Fix + re-publish tracked in `DX-3`. |

package/dist/components/charts/chartDefaults.js

@@ -144,6 +144,28 @@ export const PACKAGE_DEFAULT_MARGIN = {
 // PACKAGE_DEFAULT_MARGIN breathing-room, applied here for the same reason (a hard 0px gap reads
 // as clipped even when nothing is actually cut off).
 const ROTATED_TICK_CLEARANCE_PX = 8;
+// UCM-CHART-16: the FLAT (angle 0) tick band used to be the unconditional TICK_BAND_BASE_PX
+// regardless of the actual tick font size -- fine for MUI's own generic default, but MUI's
+// internal fit check (`shortenLabels`, against `tickLabelsMaxHeight`) blanks EVERY tick label the
+// moment the real rendered text is even slightly taller than what that flat floor leaves room
+// for once MUI's own tick/gap overhead (and, when an axis title shares the band, its own gap) is
+// subtracted. `TICK_BAND_BASE_PX` alone was a near-miss with essentially no margin at any font
+// size above whatever MUI itself implicitly assumed -- two hram consumers independently patched
+// around it with the same empirically-measured `height: 56`, and a third, titleless case broke at
+// a tick font just 1px above the untitled default.
+//
+// These three constants are DERIVED, not guessed: binary-searched against the real, unmocked
+// `BarChart` rendered in this repo's own dev harness (`dev/entries.jsx`'s `chart-probe` entry,
+// Chrome, this package's own DM Sans default -- the taller of the two fonts checked; MUI's Roboto
+// fallback needs visibly less and was never the trigger) at tick font sizes 11-18px, with and
+// without an axis title:
+//   required flat tickBand   ~= ceil(fontSize * TICK_TEXT_HEIGHT_FACTOR) + TICK_BAND_MUI_OVERHEAD_PX
+//   required tickBand+title  ~= that, plus TICK_BAND_TITLE_EXTRA_PX, plus AXIS_TITLE_BAND_PX
+// matched every measured threshold exactly or over by at most 1px, never under, across ten
+// font-size/title combinations -- see UCM-CHART-16's work order for the full measurement table.
+const TICK_TEXT_HEIGHT_FACTOR = 1.3;
+const TICK_BAND_MUI_OVERHEAD_PX = 9;
+const TICK_BAND_TITLE_EXTRA_PX = 2;
 // THEME-9: MUI X-Charts' own default y-axis width is a flat 45px (ticks) +
 // 20px (label, if present) = 65px regardless of what the ticks actually say
 // -- confirmed against @mui/x-charts' own DEFAULT_AXIS_SIZE_WIDTH /
@@ -373,8 +395,18 @@ function resolveXAxisGeometry(axis, xLabelsMode, defaultLineHeight, measureTextW
         const needsRotation = dataCount > AUTO_ROTATE_TICK_COUNT && labelWidthPx > AUTO_ROTATE_LABEL_WIDTH_PX;
         angle = needsRotation ? -45 : 0;
     } // "horizontal" always stays at angle 0
-    if (angle === 0)
-        return { tickBand: TICK_BAND_BASE_PX, angle: 0 };
+    if (angle === 0) {
+        // UCM-CHART-16: derive the flat band from the actual tick font size instead of the
+        // unconditional floor -- `axis?.label` is the SAME signal `resolveChartLayout` uses to decide
+        // whether an axis title also shares this band (`xTitleBand`), so a titled axis reserves the
+        // extra room its own gap costs, precisely where the near-miss was.
+        const hasTitle = Boolean(axis === null || axis === void 0 ? void 0 : axis.label);
+        const flatTickBand = fontSize > 0
+            ? Math.ceil(fontSize * TICK_TEXT_HEIGHT_FACTOR) + TICK_BAND_MUI_OVERHEAD_PX
+                + (hasTitle ? TICK_BAND_TITLE_EXTRA_PX : 0)
+            : TICK_BAND_BASE_PX;
+        return { tickBand: Math.max(TICK_BAND_BASE_PX, flatTickBand), angle: 0 };
+    }
     // Rotation is a visual instruction independent of whether a font size is knowable here -- an
     // "angled" axis still rotates even when `fontSize` can't be resolved (no theme fallback given),
     // it just can't project a tighter band than the floor without one.

package/docs/CHART-LAYOUT.md

@@ -15,13 +15,15 @@ chartHeight === plotHeight + xAxisBand + xTitleBand + legendBand
 ```
 
 - `xAxisBand` — the tick row. Zero when the axis has no visible tick content (an empty `data`
-  array, or every formatted tick is a blank string). Non-zero otherwise: a flat baseline for
-  horizontal labels, or a measured/estimated projection for rotated ones (same measurement
-  mechanism as before — a real DOM measurement when available, a per-glyph estimate otherwise).
-  The flat baseline (25px) and the title addition (20px) are MUI X-Charts' own
-  `DEFAULT_AXIS_SIZE_HEIGHT`/`AXIS_LABEL_DEFAULT_HEIGHT` constants, not a re-estimate — the plain
-  unrotated/untitled case renders pixel-identical to before this WO, even though the resolver now
-  sets `axis.height` explicitly where MUI used to fill it in implicitly.
+  array, or every formatted tick is a blank string). Non-zero otherwise: for horizontal labels, a
+  floor of 25px (MUI X-Charts' own `DEFAULT_AXIS_SIZE_HEIGHT`) scaled up from the actual tick font
+  size once it needs more room than that floor leaves MUI's own internal fit check — a flat floor
+  alone was a near-miss with essentially no margin at any font size above whatever MUI itself
+  implicitly assumed (`UCM-CHART-16`); or a measured/estimated projection for rotated ones (same
+  measurement mechanism as before — a real DOM measurement when available, a per-glyph estimate
+  otherwise). The title addition (20px, `AXIS_LABEL_DEFAULT_HEIGHT`) grows by a further few pixels
+  when an axis title shares the tick row's band, matching the extra gap MUI itself reserves
+  between the two.
 - `xTitleBand` — the axis title. Zero unless the x-axis carries a `label`.
 - `legendBand` — one row for the legend. Zero when `hideLegend` is set.
 - `plotHeight` is the residual: `chartHeight` minus the three bands above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micha.bigler/ui-core-micha",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "sideEffects": [

package/src/components/charts/chartDefaults.js

@@ -153,6 +153,29 @@ export const PACKAGE_DEFAULT_MARGIN = {
 // as clipped even when nothing is actually cut off).
 const ROTATED_TICK_CLEARANCE_PX = 8;
 
+// UCM-CHART-16: the FLAT (angle 0) tick band used to be the unconditional TICK_BAND_BASE_PX
+// regardless of the actual tick font size -- fine for MUI's own generic default, but MUI's
+// internal fit check (`shortenLabels`, against `tickLabelsMaxHeight`) blanks EVERY tick label the
+// moment the real rendered text is even slightly taller than what that flat floor leaves room
+// for once MUI's own tick/gap overhead (and, when an axis title shares the band, its own gap) is
+// subtracted. `TICK_BAND_BASE_PX` alone was a near-miss with essentially no margin at any font
+// size above whatever MUI itself implicitly assumed -- two hram consumers independently patched
+// around it with the same empirically-measured `height: 56`, and a third, titleless case broke at
+// a tick font just 1px above the untitled default.
+//
+// These three constants are DERIVED, not guessed: binary-searched against the real, unmocked
+// `BarChart` rendered in this repo's own dev harness (`dev/entries.jsx`'s `chart-probe` entry,
+// Chrome, this package's own DM Sans default -- the taller of the two fonts checked; MUI's Roboto
+// fallback needs visibly less and was never the trigger) at tick font sizes 11-18px, with and
+// without an axis title:
+//   required flat tickBand   ~= ceil(fontSize * TICK_TEXT_HEIGHT_FACTOR) + TICK_BAND_MUI_OVERHEAD_PX
+//   required tickBand+title  ~= that, plus TICK_BAND_TITLE_EXTRA_PX, plus AXIS_TITLE_BAND_PX
+// matched every measured threshold exactly or over by at most 1px, never under, across ten
+// font-size/title combinations -- see UCM-CHART-16's work order for the full measurement table.
+const TICK_TEXT_HEIGHT_FACTOR = 1.3;
+const TICK_BAND_MUI_OVERHEAD_PX = 9;
+const TICK_BAND_TITLE_EXTRA_PX = 2;
+
 // THEME-9: MUI X-Charts' own default y-axis width is a flat 45px (ticks) +
 // 20px (label, if present) = 65px regardless of what the ticks actually say
 // -- confirmed against @mui/x-charts' own DEFAULT_AXIS_SIZE_WIDTH /
@@ -389,7 +412,18 @@ function resolveXAxisGeometry(axis, xLabelsMode, defaultLineHeight, measureTextW
     angle = needsRotation ? -45 : 0;
   } // "horizontal" always stays at angle 0
 
-  if (angle === 0) return { tickBand: TICK_BAND_BASE_PX, angle: 0 };
+  if (angle === 0) {
+    // UCM-CHART-16: derive the flat band from the actual tick font size instead of the
+    // unconditional floor -- `axis?.label` is the SAME signal `resolveChartLayout` uses to decide
+    // whether an axis title also shares this band (`xTitleBand`), so a titled axis reserves the
+    // extra room its own gap costs, precisely where the near-miss was.
+    const hasTitle = Boolean(axis?.label);
+    const flatTickBand = fontSize > 0
+      ? Math.ceil(fontSize * TICK_TEXT_HEIGHT_FACTOR) + TICK_BAND_MUI_OVERHEAD_PX
+        + (hasTitle ? TICK_BAND_TITLE_EXTRA_PX : 0)
+      : TICK_BAND_BASE_PX;
+    return { tickBand: Math.max(TICK_BAND_BASE_PX, flatTickBand), angle: 0 };
+  }
   // Rotation is a visual instruction independent of whether a font size is knowable here -- an
   // "angled" axis still rotates even when `fontSize` can't be resolved (no theme fallback given),
   // it just can't project a tighter band than the floor without one.

package/tests/chartAxisTickBand.test.jsx

@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+import React from 'react';
+import {
+  afterAll, afterEach, beforeAll, describe, expect, it,
+} from 'vitest';
+import { cleanup, render } from '@testing-library/react';
+import { ThemeProvider, createTheme } from '@mui/material/styles';
+
+import { BarChart } from '../src/components/charts/BarChart';
+
+// UCM-CHART-16: MUI's own tick-label fit check (`shortenLabels`, weighed against
+// `tickLabelsMaxHeight`) depends on a REAL SVG text measurement (`getBBox`), which jsdom does not
+// implement -- `SVGElement.prototype.getBBox` is not a function here, so MUI's own
+// `getStringSize` falls back to `getBoundingClientRect`, which jsdom always reports as 0x0. Every
+// measured height therefore comes back 0, MUI's fit check trivially "fits" any text, and the real
+// defect (every tick label blanked) can never be observed by rendering the unmocked chart as-is --
+// a test that skips this setup would pass whether or not the resolver's band is correct, i.e. be
+// exactly the "mocked prop-assertion" trap this package's own tests warn against elsewhere.
+//
+// This installs a deterministic `getBBox` instead, so the SAME code MUI itself runs is actually
+// exercised: height scaled off the measurement span's own `fontSize`, at a ratio (1.28) chosen to
+// sit inside the real near-miss window this WO's own work order measured against a real browser
+// (`resolveXAxisGeometry`'s `TICK_TEXT_HEIGHT_FACTOR` comment) -- large enough that the pre-fix
+// unconditional floor already fails a titled axis at the theme's own default tick font, small
+// enough that the untitled default (never broken) still passes. Width is deliberately near-zero so
+// only the HEIGHT dimension of MUI's fit check is exercised; each chart also sets an explicit
+// `width` so MUI's real responsive sizing (ResizeObserver, unavailable in jsdom) never enters into
+// it.
+function installHeightOnlyTextMeasurement() {
+  const original = SVGElement.prototype.getBBox;
+  // eslint-disable-next-line func-names
+  SVGElement.prototype.getBBox = function getBBox() {
+    const fontSize = Number.parseFloat(this.style.fontSize) || 12;
+    return { x: 0, y: 0, width: 1, height: fontSize * 1.28 };
+  };
+  return () => {
+    SVGElement.prototype.getBBox = original;
+  };
+}
+
+describe('x-axis tick band leaves MUI room for one real line of tick text (UCM-CHART-16)', () => {
+  let restoreGetBBox;
+
+  beforeAll(() => {
+    restoreGetBBox = installHeightOnlyTextMeasurement();
+  });
+
+  afterAll(() => {
+    restoreGetBBox();
+  });
+
+  afterEach(cleanup);
+
+  // WO scope item 1's own signature: an axis title AND horizontal tick labels sharing the same
+  // band, at the theme's own default tick font -- no explicit `height`/`tickLabelStyle` overrides
+  // anywhere, so this exercises the resolver's own default reservation end to end, the exact path
+  // two hram consumers had to work around by hand.
+  it('renders non-empty tick labels when the axis has both a title and horizontal ticks', () => {
+    const { container } = render(
+      <ThemeProvider theme={createTheme()}>
+        <BarChart
+          series={[{ data: [24, 36, 28], label: 'Opened' }]}
+          xAxis={[{ data: ['A', 'B', 'C'] }]}
+          xAxisLabel="Category"
+          width={600}
+        />
+      </ThemeProvider>,
+    );
+    const tickTexts = Array.from(container.querySelectorAll('.MuiChartsAxis-bottom .MuiChartsAxis-tickLabel'))
+      .map((node) => node.textContent);
+    expect(tickTexts).toHaveLength(3);
+    expect(tickTexts.every((text) => text.length > 0)).toBe(true);
+  });
+
+  // Non-goal guardrail: the rotated path projects its own band from real measured/estimated text
+  // width and must stay exactly as before -- this WO only touches the flat (angle 0) case.
+  it('leaves the rotated tick path unaffected', () => {
+    const { container } = render(
+      <ThemeProvider theme={createTheme()}>
+        <BarChart
+          series={[{ data: [24, 36, 28, 12, 9, 7, 15] }]}
+          xAxis={[{
+            data: Array.from({ length: 7 }, (_, i) => `A rather long category label ${i}`),
+          }]}
+          xLabels="angled"
+          width={600}
+        />
+      </ThemeProvider>,
+    );
+    const tickTexts = Array.from(container.querySelectorAll('.MuiChartsAxis-bottom .MuiChartsAxis-tickLabel'))
+      .map((node) => node.textContent);
+    expect(tickTexts).toHaveLength(7);
+    expect(tickTexts.every((text) => text.length > 0)).toBe(true);
+  });
+});

package/tests/chartDefaults.test.js

@@ -594,6 +594,46 @@ describe('resolveChartLayout size tokens and height escape (UCM-CHART-12, UCM-CH
   });
 });
 
+describe('resolveChartLayout flat x-axis tick band leaves MUI room to render (UCM-CHART-16)', () => {
+  // Third occurrence (WO Part A): no title, just a tick font 1px above the untitled default --
+  // already enough to blank every label under the pre-fix, unconditional TICK_BAND_BASE_PX=25.
+  // 26 is not invented: binary-searched against the real, unmocked `BarChart` rendered in this
+  // repo's own dev harness (Chrome, this package's own DM Sans default) -- 25 still blanked every
+  // tick, 26 was the smallest axis height that didn't. A test computing its own expectation from
+  // `CHART_TICK_TEXT_HEIGHT_FACTOR`-style constants would pass whatever those constants say,
+  // proving nothing; this number came from outside the code under test.
+  it('reserves enough room for a tick font one pixel above the untitled default (measured threshold: 26px)', () => {
+    const layout = resolveChartLayout({
+      xAxis: [{
+        scaleType: 'band',
+        data: ['Urban', 'Peri-urban', 'Rural', 'Access', 'Village'],
+        tickLabelStyle: { fontSize: 13 },
+      }],
+      yAxis: [{ scaleType: 'linear' }],
+      xLabels: 'horizontal',
+      spacing: theme.spacing,
+    });
+    expect(layout.xAxis[0].height).toBeGreaterThanOrEqual(26);
+  });
+
+  // Rule 2 (WO non-goal guardrail): an axis without a title still reserves only the tick band --
+  // this WO's extra title-driven margin must not leak in when there is no title to share it with.
+  // Reviewer finding: asserting `xTitleBand === 0` alone passes whether or not the +2px title
+  // margin leaked into `xAxisBand` instead -- the band/height values themselves have to be
+  // checked against the same tick font's no-title formula (`ceil(fontSize * 1.3) + 9`).
+  it('does not add the title margin when the axis has no label', () => {
+    const layout = resolveChartLayout({
+      xAxis: [{ scaleType: 'band', data: ['A', 'B'], tickLabelStyle: { fontSize: 13 } }],
+      yAxis: [{ scaleType: 'linear' }],
+      xLabels: 'horizontal',
+      spacing: theme.spacing,
+    });
+    expect(layout.bands.xTitleBand).toBe(0);
+    expect(layout.bands.xAxisBand).toBe(26);
+    expect(layout.xAxis[0].height).toBe(26);
+  });
+});
+
 describe('resolveChartLayout xLabels rotation (UCM-CHART-12)', () => {
   it('"horizontal" never rotates, regardless of tick count or label length', () => {
     const layout = resolveChartLayout({

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

@@ -0,0 +1,169 @@
+# UCM-CHART-16 — The x-axis band starves MUI's tick-fit check, and two consumers have patched around it
+
+## Part A — Envelope
+
+*Authored by the Expertenchat. Authoritative WHAT/WHY.*
+
+### Goal
+
+A chart with an axis title **and** horizontal tick labels renders its tick labels. No consumer needs
+to set `xAxis[].height` by hand to make that happen.
+
+### The defect
+
+When the x-axis stays horizontal, `resolveXAxisGeometry` reserves one combined band from
+`TICK_BAND_BASE_PX` + `AXIS_TITLE_BAND_PX`. Once an axis title is also taken from that budget, MUI's
+own internal fit check (`shortenLabels`, against `tickLabelsMaxHeight`) is left **just under one line
+of 12 px text** — so it fails for **every** tick and blanks **every** label, regardless of content.
+
+The signature is distinctive and easy to misread: correctly positioned tick marks, zero non-empty
+label texts. It looks like a data or formatter problem and is neither.
+
+### The evidence: two consumers, same workaround, same magic number
+
+In hram, independently, in two different work orders:
+
+```
+StructuralReachabilityPanel.jsx:386   height: 56      (HRAM-RES-32)
+AccessGapScatterPanel.jsx:212         height: 56      (HRAM-RES-39)
+```
+
+`HRAM-RES-32`'s own comment already diagnosed it correctly and called it what it is — *"a
+pre-existing, latent **shared-core** near-miss"* — then patched locally, because a shared-core fix was
+outside that WO. `HRAM-RES-39` hit the identical wall, read the MUI source, arrived at the same
+cause and the same 56, and patched locally again.
+
+Two things follow. **The third chart with a titled horizontal axis will hit it too**, and its author
+will have to rediscover both the cause and the number. And the package is violating its own stated
+rule: `chartDefaults.js` says *"Rule 1: nothing outside the resolver does chart arithmetic"* — a
+caller hand-computing an axis height is exactly that, now in two places.
+
+### A third occurrence — and it proves scope item 2
+
+Reported by the operator on 2026-08-25, hram's `AccessibilityPanel` in its
+`Urban/Peri-urban/Rural × Division` mode: five band categories, five rendered bar groups, **no tick
+labels at all**. Same signature — positioned ticks, blank text.
+
+This one is different in a way that matters. That chart has **no `xAxisLabel`**
+(`AccessibilityPanel.jsx:164-178`), so the axis title is *not* competing for the band. What it does
+have is `tickLabelStyle: { fontSize: 13 }` — one pixel above the 12 px the base band was sized
+against.
+
+**So the trigger is not "a title takes the room". It is that the band is a near-miss at all**, and
+anything that consumes a little more — a title, a slightly larger font, presumably a taller line
+height — pushes it over. A fixed `height: 56` patched into a third consumer would work at 13 px and
+fail at 14. That is precisely why scope item 2 requires the resolver to **derive** the requirement
+from the tick font size it already knows, rather than adopting the constant two consumers measured
+empirically at 12 px.
+
+(Signature-matched, not yet instrumented — confirm the mechanism on this third case as part of the
+work, since it is the one that distinguishes a derived fix from a bigger constant.)
+
+### Scope
+
+1. **Fix the reservation in the resolver.** The band must leave MUI's fit check room for one full
+   line of tick text *after* the axis title's share, not just under it. The near-miss is small, which
+   is why it went unnoticed — the fix is a correction to the arithmetic, not a redesign.
+2. **Derive it, do not add a second magic number.** 56 is what two consumers measured empirically
+   against a 12 px font; the resolver knows the tick font size and the title band, so it can compute
+   the requirement instead of hard-coding a constant that will be wrong at a different font size.
+3. **Say what changed and why in the comment**, in the style the file already uses — this is the
+   third time this arithmetic has been reasoned about and the first time it is written down where it
+   belongs.
+
+### Non-goals / do not touch
+
+- The rotated-tick path (`xLabels: "angled"`, `spaceForRotatedTicks`). The defect is specific to the
+  horizontal case; a rotated axis reserves its own projected band and is unaffected.
+- `CHART_SIZE_SPACING_UNITS` and the size scale — `UCM-CHART-15`, done.
+- `ChartFrame`, margins, the legend band, `resolveChartLayout`'s other outputs.
+- The consuming panels. Removing hram's two workarounds is `HRAM-CHT-6`, after this ships.
+
+### Risks
+
+- **A mocked prop-assertion test cannot catch this.** The file already records the same trap for a
+  neighbouring bug: *"a mocked prop-assertion test cannot catch this, it only reproduces on an actual
+  MUI scale computation"*. A test that asserts the computed band's number would pass whatever the
+  number is. The test has to observe **rendered label text**, or it is decoration — see test 1.
+- **Raising the band changes every titled-horizontal-axis chart's plot area** by the difference. Small,
+  but it is a visual change to consumers, and it lands on top of `UCM-CHART-15`'s 80 px shift.
+- Fixing it too generously wastes vertical space on every chart. The margin of the near-miss is the
+  budget; do not round it up "to be safe".
+
+### Tests to write
+
+1. **A rendered test**: a chart with an axis title and horizontal ticks produces **non-empty** tick
+   label texts. Written so it fails against the current resolver — a blank-label render is the
+   defect, so the test must be able to see blankness.
+2. The rotated path is unchanged — same band as before for `xLabels: "angled"`.
+3. An axis **without** a title still reserves only the tick band (Rule 2: a band that is not needed
+   collapses to zero).
+
+---
+
+## 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.
+
+**The defect could not be diagnosed from source reading alone** (see Risk section: "a mocked
+prop-assertion test cannot catch this"). MUI's internal fit check (`shortenLabels`, weighed
+against `tickLabelsMaxHeight`, in `node_modules/@mui/x-charts/ChartsXAxis/ChartsSingleXAxisTicks.mjs`
+and `shortenLabels.mjs`) depends on `getBBox`, which jsdom does not implement — so the mechanism
+was confirmed and the fix calibrated against a REAL browser render, not derived from reading MUI's
+source alone:
+
+- `dev/entries.jsx`'s dev harness (`vite`, real Chrome via the internal preview browser) was used
+  to dynamically render the actual, unmocked `BarChart` with a titled horizontal axis under this
+  package's own `createAppTheme`/DM Sans default. Confirmed the defect reproduces exactly as
+  described (blank tick labels, correctly positioned) and does NOT reproduce under MUI's default
+  Roboto stack (real glyph metrics run ~1.3-1.36× fontSize for DM Sans vs ~1.06-1.17× for Roboto —
+  explains why the defect is font-dependent and was missed until a consumer used a taller font).
+- Binary-searched the real, minimal `xAxis[].height` needed to stop blanking, at tick font sizes
+  11-18px, with and without a title (ten measured thresholds total). The result matched
+  `ceil(fontSize * 1.3) + 9` (no title) / `+ 11` (with title, i.e. the same plus 2px) almost
+  exactly — over by at most 1px, never under, across all ten points. `9` corresponds to MUI's own
+  `tickSize`(6, default) + `TICK_LABEL_GAP`(3) internal overhead
+  (`ChartsXAxis/utilities.mjs`/`ChartsSingleXAxisTicks.mjs`); the extra `+2` when a title is
+  present was constant across every font size tested, independent of font.
+- The fix (`resolveXAxisGeometry`'s `angle === 0` branch, `chartDefaults.js`) was re-verified
+  against the SAME real-browser harness after implementing, confirming both reproduced scenarios
+  (title + default font; no title + `tickLabelStyle.fontSize: 13`, the `AccessibilityPanel`
+  signature) now render correctly with no explicit `height` override needed.
+
+Context package: `chartDefaults.js:322-341` (`TICK_BAND_BASE_PX`/`AXIS_TITLE_BAND_PX`/new
+constants), `:366-430ish` (`resolveXAxisGeometry`, the `angle === 0` early-return that was the
+defect site), `:450-475` (`resolveChartLayout`'s `xAxisBand`/`xTitleBand` composition, unchanged).
+Non-goal boundary respected: the `angle !== 0` (rotated) branch below the fixed code is untouched.
+
+---
+
+## Part C — Orchestrator only
+
+> **STOP — everything below addresses the Orchestrator.**
+
+**Tier 3 · tests: the three cases above, at least one of them rendered**
+
+Shared-core, by the tiering table regardless of diff size.
+
+- `reviewer` — the arithmetic, and above all whether test 1 can actually fail.
+- `ui_reviewer` — the plot-area change this causes across consumers.
+- `sec_reviewer` — not run; no auth, data or exposure surface.
+
+### Release
+
+Patch or minor per the repo's convention — this repairs existing behaviour rather than adding
+capability, so **patch** unless the plot-area change is judged large enough to warrant a minor. State
+which and why in the CHANGELOG; `UCM-CHART-15`'s entry is the model for describing a visual
+consequence plainly.
+
+### Register
+
+Row `UCM-CHART-16`, both review notes, the published version, landing SHA(s) in a second commit
+before the push. Record that the fix arrived **third** — two consumers patched around it first — so
+the cost of leaving a shared-core near-miss to consumers is on the record.
+
+### Log
+
+- **2026-08-25** — Envelope authored after `HRAM-RES-39` hit the same defect `HRAM-RES-32` had
+  already diagnosed as shared-core, and applied the identical `height: 56` workaround independently.