@micha.bigler/ui-core-micha 3.1.0 → 3.1.1

package/tests/chart-api-census.test.js

@@ -0,0 +1,366 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findChartApiUsage, runCensus, TARGET_PROPS } from '../scripts/chart-api-census.mjs';
+
+const IMPORT_LINE = "import { BarChart, LineChart, ScatterChart, TimeSeriesChart, ChartFrame } from '@micha.bigler/ui-core-micha';\n";
+
+function propsFound(entry) {
+  return TARGET_PROPS.filter((p) => entry.props[p]);
+}
+
+// UCM-CHART-14: this WO exists because a grep could not see JSX structure. First-round fixtures
+// (below) cover what broke the ad-hoc scans behind this series' wrong consumer counts (see
+// work-orders/UCM-CHART-14.md's own table of six). A second, independent review round (both
+// `reviewer` and `ui_reviewer`) found the FIRST version of this file could itself produce a WRONG,
+// non-UNPARSED answer -- worse than honest UNPARSED -- and that two of these very fixtures did not
+// actually exercise the trap their name claimed. Both are fixed; the second-round traps are in the
+// next describe block. Each fixture asserts the EXACT props found, not just "found something".
+describe('findChartApiUsage -- traps that broke ad-hoc grep scans (UCM-CHART-14)', () => {
+  it('trap 1: an arrow function inside a prop value does not truncate the tag at its own "=>"', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ScatterChart
+            getPointStyle={(point) => ({ hollow: point.isStatusQuo, color: point.isStatusQuo ? undefined : '#123' })}
+            aspect={1.8}
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('ScatterChart');
+    expect(entry.unparsed).toBe(false);
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+
+  // Second-round finding: the original fixture put the comment BETWEEN two already-closed tags
+  // (JSX children), never exercising an open tag's own attribute-scan while a comment is active.
+  // This version puts both a line comment AND a block comment, each carrying an apostrophe, INSIDE
+  // the attribute list itself -- the position that actually needs string/comment tracking to be
+  // correct, since a naive apostrophe could be misread as a string-open.
+  it('trap 2: an apostrophe inside a comment WITHIN the attribute list does not desynchronise string tracking', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame
+            // don't confuse this line comment's apostrophe with a string open
+            minHeight={300}
+            /* it's a block comment here too */
+            title="Body weight"
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('ChartFrame');
+    expect(propsFound(entry)).toEqual(['minHeight']);
+  });
+
+  // Second-round finding: the original fixture's nested keys (`angle`/`left`/`top`) were not even
+  // in TARGET_PROPS, so a parser that falsely collected ANY nested key would still have passed.
+  // This version nests `aspect` and `height` themselves as object keys several levels deep -- the
+  // exact prop names the census is looking for -- so a depth-tracking bug that leaks nested keys
+  // up as top-level attributes is now something this test can actually catch.
+  it('trap 3: nested braces are tracked by depth -- a nested key with a TARGET PROP NAME is never mistaken for a top-level attribute', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <BarChart
+            xAxis={[{ scaleType: 'band', tickLabelStyle: { aspect: 'not-real', height: 999 } }]}
+            margin={{ top: 8 }}
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    // `margin` IS a top-level attribute (found); the nested `aspect`/`height` keys -- despite being
+    // real TARGET_PROPS names -- must never surface as attributes of the tag itself.
+    expect(propsFound(entry)).toEqual(['margin']);
+  });
+
+  it('trap 4: a prop many lines below the component name is still attributed to the same tag', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame
+            title="Body weight"
+            subtitle="Last 12 months"
+            variant="outlined"
+            titleVariant="h6"
+            exportOptions
+            meta="Updated daily"
+            aspect={1.8}
+          >
+            {children}
+          </ChartFrame>
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('ChartFrame');
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+});
+
+// Second review round -- the four NEW traps that surfaced against the first version's three-pass
+// design (a raw regex tag-open search with no string/comment context, and no regex-literal
+// tracking at all). All four are wrong-answer risks, not merely UNPARSED risks -- exactly the
+// class of bug this WO's own F1 finding is about (a false measurement nobody flagged).
+describe('findChartApiUsage -- second-round traps: string/comment-blind matching and regex literals', () => {
+  it('does not count JSX-looking text inside a STRING literal as a real element', () => {
+    const source = `${IMPORT_LINE}
+      const example = '<BarChart aspect />';
+      function Panel() {
+        return <LineChart margin={{ top: 1 }} />;
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('LineChart');
+  });
+
+  it('does not count JSX-looking text inside a LINE comment as a real element', () => {
+    const source = `${IMPORT_LINE}
+      // <BarChart aspect />
+      function Panel() {
+        return <LineChart margin={{ top: 1 }} />;
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('LineChart');
+  });
+
+  it('does not count JSX-looking text inside a BLOCK comment as a real element', () => {
+    const source = `${IMPORT_LINE}
+      /* an old example: <BarChart aspect /> -- removed */
+      function Panel() {
+        return <LineChart margin={{ top: 1 }} />;
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('LineChart');
+  });
+
+  // The concrete case found in review: a regex literal's `}`/`>` characters must not be read as
+  // real brace/tag-close tokens, or a later real prop on the same tag gets silently dropped.
+  it('a regex literal in a prop value does not corrupt brace depth or close the tag early', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <BarChart
+            data={/[}>]/}
+            aspect={1.8}
+          />
+        );
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.unparsed).toBe(false);
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+
+  // A component nested INSIDE another target component's own prop expression -- the outer tag's
+  // scan must not swallow the inner one, and each must report its OWN props independently.
+  it('finds a target component nested inside another target component\'s prop expression', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame minHeight={300} content={<BarChart aspect={1.8} />} />
+        );
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    const frame = entries.find((e) => e.component === 'ChartFrame');
+    const bar = entries.find((e) => e.component === 'BarChart');
+    expect(entries).toHaveLength(2);
+    expect(propsFound(frame)).toEqual(['minHeight']);
+    expect(propsFound(bar)).toEqual(['aspect']);
+  });
+
+  // Regression test for a bug this WO's OWN verification run found (not review, an actual real-
+  // world run against hram): the regex-literal heuristic originally included `<`/`>` in the set of
+  // characters that can precede a regex-starting `/`. Every JSX CLOSING tag (`</Something>`) has a
+  // `/` immediately after a `<` -- so `</ChartFrame>` itself was misread as opening a regex
+  // literal, silently corrupting brace depth for the rest of the file and turning every multi-line
+  // `<ChartFrame>...</ChartFrame>` usage in the estate into a false UNPARSED. This fixture is
+  // shaped like the real file that exposed it: a target component with real JSX children,
+  // including an interleaved NON-target component's own closing tag before the target's own.
+  it('a target component with real JSX children (own closing tag, and a sibling non-target closing tag) is not corrupted by the </Tag> regex-heuristic bug', () => {
+    const source = `${IMPORT_LINE}
+      function Panel() {
+        return (
+          <ChartFrame minHeight={320} toolbar={<Toolbar><Button>Go</Button></Toolbar>}>
+            <ScatterChart aspect={1.8}>
+              <ScatterReferenceLine from={{ x: 0, y: 0 }} to={{ x: 1, y: 1 }} />
+            </ScatterChart>
+          </ChartFrame>
+        );
+      }
+    `;
+    const entries = findChartApiUsage(source);
+    const frame = entries.find((e) => e.component === 'ChartFrame');
+    const scatter = entries.find((e) => e.component === 'ScatterChart');
+    expect(frame).toBeDefined();
+    expect(frame.unparsed).toBe(false);
+    expect(propsFound(frame)).toEqual(['minHeight']);
+    expect(scatter).toBeDefined();
+    expect(scatter.unparsed).toBe(false);
+    expect(propsFound(scatter)).toEqual(['aspect']);
+  });
+});
+
+describe('findChartApiUsage -- import resolution and non-traps', () => {
+  it('only counts components actually imported from @micha.bigler/ui-core-micha -- a same-named local component is not a consumer', () => {
+    const source = `
+      import { BarChart } from './my-local-chart';
+      function Panel() {
+        return <BarChart aspect={1.8} />;
+      }
+    `;
+    expect(findChartApiUsage(source)).toEqual([]);
+  });
+
+  it('resolves an aliased import back to its canonical export name', () => {
+    const source = `
+      import { BarChart as Bar } from '@micha.bigler/ui-core-micha';
+      function Panel() {
+        return <Bar aspect={1.8} />;
+      }
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.component).toBe('BarChart');
+    expect(propsFound(entry)).toEqual(['aspect']);
+  });
+
+  it('reports no elements in a file with no matching import at all (the fast path)', () => {
+    expect(findChartApiUsage('const BarChart = 1; const x = <BarChart aspect={1} />;')).toEqual([]);
+  });
+
+  it('reports a boolean-shorthand attribute (no value) the same as a valued one', () => {
+    const source = `${IMPORT_LINE}
+      const el = <ChartFrame minHeight />;
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(propsFound(entry)).toEqual(['minHeight']);
+  });
+
+  it('finds a clean element with none of the target props as an entry with an empty prop list', () => {
+    const source = `${IMPORT_LINE}
+      const el = <BarChart xAxisLabel="Month" series={[]} />;
+    `;
+    const [entry] = findChartApiUsage(source);
+    expect(entry.unparsed).toBe(false);
+    expect(propsFound(entry)).toEqual([]);
+  });
+
+  it('finds multiple distinct elements in the same file, each with its own props', () => {
+    const source = `${IMPORT_LINE}
+      const a = <BarChart aspect={1} />;
+      const b = <LineChart margin={{ top: 1 }} />;
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(2);
+    expect(entries[0].component).toBe('BarChart');
+    expect(entries[1].component).toBe('LineChart');
+  });
+});
+
+// Definition of Done: "A tag it cannot close is reported as UNPARSED, never skipped and never
+// counted as clean" -- a census that silently drops what it cannot read is the failure it exists
+// to prevent.
+describe('findChartApiUsage -- UNPARSED, never silently skipped', () => {
+  it('reports a tag that never closes as UNPARSED rather than dropping it', () => {
+    const source = `${IMPORT_LINE}
+      const el = <BarChart aspect={1.8} xAxisLabel="Month unterminated
+    `; // no closing `>` or `/>` anywhere after this point
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].unparsed).toBe(true);
+    expect(entries[0].component).toBe('BarChart');
+  });
+
+  it('keeps scanning after an UNPARSED tag and still finds a later, well-formed one', () => {
+    // An unmatched `{` (not a string) leaves brace depth permanently elevated but string tracking
+    // intact -- so a LATER tag, opening at that same (now-baseline) depth, can still close
+    // correctly relative to it. `BarChart` never returns to its own start depth and is UNPARSED;
+    // `LineChart` opens and closes entirely within the leaked depth and is found correctly.
+    const source = `${IMPORT_LINE}
+      const broken = <BarChart aspect={1.8} xAxis={{ scaleType: 'band';
+      const el2 = <LineChart margin={{ top: 1 }} />;
+    `;
+    const entries = findChartApiUsage(source);
+    const bar = entries.find((e) => e.component === 'BarChart');
+    const lineChart = entries.find((e) => e.component === 'LineChart');
+    expect(bar.unparsed).toBe(true);
+    expect(lineChart).toBeDefined();
+    expect(lineChart.unparsed).toBe(false);
+    expect(propsFound(lineChart)).toEqual(['margin']);
+  });
+
+  // An UNTERMINATED STRING is a genuinely different case from an unmatched brace: nothing can
+  // recover from it without guessing where the string was meant to end, so honestly reporting
+  // "nothing found after this point" is the correct behaviour, not a bug -- the alternative (the
+  // first version of this scanner's per-tag-independent design) would have silently RESYNCHRONISED
+  // past a real syntax error, which is exactly the kind of confident-but-wrong answer this WO's
+  // second review round exists to rule out.
+  it('an unterminated string desyncs the rest of the file -- reported as UNPARSED, not silently resynchronised', () => {
+    const source = `${IMPORT_LINE}
+      const broken = <BarChart aspect={1.8} xAxisLabel="unterminated;
+      const el2 = <LineChart margin={{ top: 1 }} />;
+    `;
+    const entries = findChartApiUsage(source);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].component).toBe('BarChart');
+    expect(entries[0].unparsed).toBe(true);
+  });
+});
+
+describe('runCensus -- filesystem walking degrades gracefully (UCM-CHART-14 Risks)', () => {
+  let workspaceRoot;
+
+  afterEach(() => {
+    if (workspaceRoot) rmSync(workspaceRoot, { recursive: true, force: true });
+  });
+
+  it('reports "not present" for a sibling with no frontend/src or src, and never throws', () => {
+    workspaceRoot = mkdtempSync(join(tmpdir(), 'ucm-census-'));
+    mkdirSync(join(workspaceRoot, 'empty-repo'));
+
+    const result = runCensus(workspaceRoot);
+    const entry = result.apps.find((a) => a.app === 'empty-repo');
+    expect(entry.present).toBe(false);
+  });
+
+  it('finds a real usage under frontend/src, and reports a clean sibling with no ucm import as present with zero entries', () => {
+    workspaceRoot = mkdtempSync(join(tmpdir(), 'ucm-census-'));
+    const appSrc = join(workspaceRoot, 'sample-app', 'frontend', 'src');
+    mkdirSync(appSrc, { recursive: true });
+    writeFileSync(
+      join(appSrc, 'Panel.jsx'),
+      `${IMPORT_LINE}\nconst el = <BarChart aspect={1.8} />;\n`,
+    );
+    mkdirSync(join(workspaceRoot, 'clean-app', 'src'), { recursive: true });
+    writeFileSync(join(workspaceRoot, 'clean-app', 'src', 'index.js'), 'export const x = 1;\n');
+
+    const result = runCensus(workspaceRoot);
+    const sample = result.apps.find((a) => a.app === 'sample-app');
+    const clean = result.apps.find((a) => a.app === 'clean-app');
+    expect(sample.present).toBe(true);
+    expect(sample.entries).toHaveLength(1);
+    expect(sample.entries[0].props.aspect).toBe(true);
+    expect(clean.present).toBe(true);
+    expect(clean.entries).toHaveLength(0);
+  });
+
+  it('excludes ui-core-micha itself from the sibling walk by default', () => {
+    workspaceRoot = mkdtempSync(join(tmpdir(), 'ucm-census-'));
+    mkdirSync(join(workspaceRoot, 'ui-core-micha', 'src'), { recursive: true });
+
+    const result = runCensus(workspaceRoot);
+    expect(result.apps.find((a) => a.app === 'ui-core-micha')).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,198 @@
+# UCM-CHART-14 — The removal was right. The reason on the record is false, and the error message says the opposite of the docblock.
+
+- **Repo:** `ui-core-micha`, branch `main`
+- **Tier:** 3 — shared-core. Version **`3.1.1`** (patch — see "Why 3.1.1 and not 4.0.0").
+- **Status:** planned
+- **Workstream:** `CHART-*`
+- **Files:** `src/components/charts/ChartFrame.jsx`, `docs/CHART-LAYOUT.md`,
+  `tests/ChartFrame.test.jsx`, `package.json`, and one new dev script + its tests.
+
+> **`UCM-CHART-13` shipped the right change for a stated reason that is false.** The mechanics are
+> correct and are not being reopened: `height` and `aspect` are gone, `minHeight` stays,
+> `warnOnChartFrameHeightMismatch` is deleted, and parameterising `assertRemovedChartProp` with
+> `removedIn` was a genuine improvement over what the WO asked for — the error now attributes the
+> right WO instead of always blaming `UCM-CHART-12`.
+>
+> What is wrong is the **justification** recorded alongside it, and one user-visible consequence.
+
+## Part A — Envelope (authoritative WHAT/WHY)
+
+### The three findings
+
+**F1 — the shipped consumer measurement is false.** Three places state that nothing passed `aspect`:
+
+| where | text |
+|---|---|
+| `ChartFrame.jsx:29-30` (docblock) | "no consumer across the five apps passes it (measured against 3.0.1)" |
+| `docs/CHART-LAYOUT.md` | "it is gone because no consumer across the five apps passed it (measured against 3.0.1)" |
+| commit `676af5c` message | "aspect was applied … but unused by all five consuming apps" |
+
+**Four `ChartFrame`s pass `aspect`**, at `origin/main` of fitness-monitor and in its working tree
+right now:
+
+```
+fitness-monitor/frontend/src/pages/BodyHistoryPage.jsx:295   <ChartFrame minHeight aspect>
+fitness-monitor/frontend/src/pages/BodyHistoryPage.jsx:444   <ChartFrame minHeight aspect>
+fitness-monitor/frontend/src/pages/EnvironmentPage.jsx:245   <ChartFrame minHeight aspect>
+fitness-monitor/frontend/src/pages/EnvironmentPage.jsx:279   <ChartFrame minHeight aspect>
+```
+
+Measured 2026-08-22 by parsing JSX opening tags with brace- and string-awareness, across all 13 app
+repos plus ucm. Same scan confirms **hram is clean**: 16 `ChartFrame`s, 11 carrying `minHeight` only,
+zero carrying `aspect` or `height` — so `HRAM-CHT-4` (landed, `4e55d1ae`) is unaffected by this WO.
+
+**F2 — the runtime error message states the opposite of the docblock 50 lines above it.**
+
+```js
+// ChartFrame.jsx:79
+'Removed -- it was never applied to the frame. Use size on the chart inside the frame …'
+```
+
+```js
+// ChartFrame.jsx:28, the same file
+// it WAS wired to `aspectRatio` on the box at 3.0.1, and worked.
+```
+
+**The four consumers who hit this error are the four whose cards actually change shape**, and the
+message tells them the prop never did anything. Deleting it on that advice is a silent layout change.
+This WO's predecessor argued that "a prop accepted and silently ignored is worse than one that
+errors" — an error that misdescribes what it is guarding is worse than both.
+`tests/ChartFrame.test.jsx:254` repeats the same false claim in a comment.
+
+**F3 — `3.1.0` is a minor for removing an applied prop with four live call sites.** The removal is
+breaking, and the minor was chosen *because* of F1. `3.1.0` is published and cannot be unpublished.
+**The remedy is a corrected record and a truthful error message, NOT a compensating major** — see
+below; this was argued the other way first and the operator was right.
+
+### Goal
+
+The record matches what was measured, the error message tells the truth to the four callers who will
+see it — and **the consumer count stops being a claim and becomes a command.**
+
+### The actual deliverable: a census, not three corrected sentences
+
+`UCM-CHART-12` established the pattern — *the deliverable is the invariant, not the fix*. The
+analogue here is blunt: **this is the sixth wrong consumer count in this series**, and every one of
+them came from a grep.
+
+| # | claim | reality |
+|---|---|---|
+| 1 | `UCM-CHART-8`: 3 `aspect` sites in fitness-monitor | 8 hits; `EnvironmentPage` never listed |
+| 2 | "8 call sites" | 4 charts (4 frame+chart pairs) |
+| 3 | `HRAM-CHT-4`: "18 preset files" | 14 files, 19 old-API sites |
+| 4 | "0 consumers pass `aspect`/`height` to `ChartFrame`" | 4 pass `aspect` |
+| 5 | "`aspect` is never applied in `ChartFrame`" | applied at `:139`; a `head`-truncated grep hid it |
+| 6 | `UCM-CHART-13`: "no consumer across the five apps passed it" | the same 4 |
+
+Greps cannot see JSX structure: a prop three lines below its component name, an arrow function whose
+`=>` ends the match early, an apostrophe inside a comment, a `{a > b}` in a sibling prop. Every entry
+above is one of those. **Ship the parser, and "measured against X" becomes reproducible output
+instead of a sentence somebody has to trust.**
+
+### Definition of Done
+
+- [ ] **`scripts/chart-api-census.mjs`** — takes a workspace root, walks every sibling repo's
+      `frontend/src` (falling back to `src/`), and reports per app: every `<ChartFrame>` and every ucm
+      chart preset element, with which of `aspect` / `height` / `minHeight` / `margin` / `xAxisAngle`
+      each one carries, and file:line. Only counts components actually imported from
+      `@micha.bigler/ui-core-micha` — a local `BarChart` of the same name is not a consumer.
+- [ ] **It parses, it does not grep.** Opening-tag scanning must track string literals, template
+      literals, `{}` depth, and `//` + `/* */` comments. **A tag it cannot close is reported as
+      `UNPARSED`, never skipped and never counted as clean** — a census that silently drops what it
+      cannot read is the failure it exists to prevent.
+- [ ] **Its own tests, over fixtures carrying the four traps that actually broke the ad-hoc scans:**
+      an arrow function in a prop, an apostrophe inside a JSX comment, nested braces, and a prop on a
+      line far below the component name. Each fixture asserts the exact props found.
+- [ ] **`aspect`'s error message rewritten to be true and actionable.** It must say the prop *was*
+      applied (`aspectRatio` on the card box, up to 3.0.1), that the card's height now follows its
+      content with `minHeight` as the floor, and that a caller who wants the chart taller or shorter
+      sets `size` on the chart inside. Do not describe it as never-applied anywhere.
+- [ ] **`height`'s message left as it is** — it *was* genuinely dead, so that one is already true.
+- [ ] **F1's text corrected in all three places** — docblock, `docs/CHART-LAYOUT.md`, and the comment
+      at `tests/ChartFrame.test.jsx:254`. Replace "no consumer passed it" with what the census
+      reports: four call sites in fitness-monitor, removed by `FM-CHART-1`. **Do not quietly delete
+      the sentence** — the point is that a measurement was wrong, and that is worth leaving legible.
+- [ ] **Version `3.1.1`**, with a CHANGELOG entry saying plainly that **`3.1.0` removed an applied
+      prop under a minor**, that four call sites were affected, and that the dev-mode error is what
+      makes the break loud. Do not publish a compensating `4.0.0`.
+- [ ] **Run the census and paste its output into this WO's register Notiz.** A WO about unverified
+      counts that lands with an unverified count is self-refuting.
+
+### Why `3.1.1` and not `4.0.0`
+
+**This WO changes no API.** Corrected prose, one error-message string, one dev script that never
+ships. On its own diff it is a patch, and labelling it `4.0.0` would announce a breaking change it
+does not contain.
+
+The counter-argument, made first in this WO and **withdrawn**: no consumer has crossed `3.1.0` —
+hram is on `3.0.1` (`HRAM-CHT-4`, landed), fitness-monitor on `2.37.0` committed / `3.0.1` in its
+working tree, jg-ferien on `2.41.1` — so the break is still ahead of all three, and a major would put
+the boundary where they will actually meet it.
+
+**What settles it: the break is not silent.** `assertRemovedChartProp` throws on first render in dev
+and names the replacement. The protection a major version buys — "read the notes before upgrading" —
+is already delivered by a hard error at the exact call site, which is strictly better than a version
+number nobody reads. A major would buy a second copy of a signal that already exists, at the cost of
+a version number that lies about its own contents.
+
+**This is conditional, and the condition is F2.** The guard is only a safety net if it tells the
+truth. An error saying `aspect` "was never applied" invites precisely the wrong action from the four
+callers whose cards change shape. **`3.1.1` is defensible because F2 is fixed in it — not
+independently of that.** If F2 were deferred, this argument collapses and the major comes back.
+
+`3.1.0` may additionally be deprecated on npm (`npm deprecate`, operator-only — a registry mutation).
+Low value here since nobody is on it and `3.1.1` supersedes it immediately; noted as available, not
+recommended.
+
+### Non-goals
+
+- **Do not reinstate `aspect`, and do not touch `minHeight`.** The removal stands; only its stated
+  reason and its error text are wrong.
+- Do not migrate fitness-monitor's four call sites — `FM-CHART-1` owns them.
+- Do not rewrite history, unpublish `3.1.0`, or publish a compensating `4.0.0`.
+- Do not extend the census beyond chart props. It answers "who passes what to the chart API", not
+  "who uses ucm".
+
+### Risks
+
+- **The census must stay out of the published package.** It is a dev script: keep it off the
+  `exports` map and out of `files`, and confirm the existing `packageTreeShaking` test still passes —
+  that test has been flaky under concurrent load before (`UCM-CHART-12`'s note), so a failure there
+  needs re-running alone before it is believed.
+- **The census reads sibling repos and must degrade gracefully** when a repo is absent, has no
+  frontend, or is a fresh clone — report "not present", never throw. It must never write anything.
+- **`FM-CHART-1` is mid-flight** with fitness-monitor's pin at `3.0.1` and all four `aspect` props
+  still in place. Until it lands, the census correctly reports 4 — that is the expected output, not a
+  failure. Do not "fix" fitness-monitor from here.
+- The corrected error message will be seen by that session. Getting F2 right is what makes its
+  remaining work safe, so **do F2 before anything else in this WO.**
+
+### Tests to WRITE — narrow
+
+- `ChartFrame` + `aspect`: the thrown message names `minHeight` and `size`, and **does not contain
+  "never applied"**. Assert on content, not just that it throws — `13`'s test matched
+  `/ChartFrame.*aspect.*size/s`, which the false message passes.
+- `ChartFrame` + `height`: unchanged, still green.
+- The census fixtures above.
+- Nothing else. `13`'s suite stays as it is apart from the corrected comment and the tightened
+  message assertion.
+
+No full suite.
+
+---
+
+## Part B — Implementation map
+
+> **TO BE FILLED BY THE ORCHESTRATOR** on `git pull`. Must carry: `ChartFrame.jsx:22-35` (docblock)
+> and `:72-81` (the two `assertRemovedChartProp` calls); `assertRemovedChartProp` itself at
+> `chartDefaults.js:566`; the `docs/CHART-LAYOUT.md` "What stays unchanged" block; the test file's
+> `describe` at `:257` and comment at `:254`; the absolute working directory; the progress contract;
+> and the preamble. **Do not dispatch while this placeholder stands.**
+
+---
+
+## Part C — Orchestrator-only
+
+> **TO BE FILLED BY THE ORCHESTRATOR.** Review routing (Tier 3: `reviewer` + `ui_reviewer`
+> concurrent), register maintenance including the pasted census output, publish verification for
+> `3.1.1`, commit, and the execution directive with its self-address guard.