diff --git a/‎.changeset/9681-scatter-zaxis-inert-declaration.md‎
Lines changed: 20 additions & 0 deletions b/‎.changeset/9681-scatter-zaxis-inert-declaration.md‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎packages/plugin-charts/src/AdvancedChartImpl.scatterEdgeClipping-7396.test.tsx‎
Lines changed: 4 additions & 2 deletions b/‎packages/plugin-charts/src/AdvancedChartImpl.scatterEdgeClipping-7396.test.tsx‎
Lines changed: 4 additions & 2 deletions
diff --git a/‎packages/plugin-charts/src/AdvancedChartImpl.scatterSymbolSize-9681.test.tsx‎
Lines changed: 161 additions & 0 deletions b/‎packages/plugin-charts/src/AdvancedChartImpl.scatterSymbolSize-9681.test.tsx‎
Lines changed: 161 additions & 0 deletions
diff --git a/‎packages/plugin-charts/src/AdvancedChartImpl.tsx‎
Lines changed: 37 additions & 13 deletions b/‎packages/plugin-charts/src/AdvancedChartImpl.tsx‎
Lines changed: 37 additions & 13 deletions
@@ -0,0 +1,20 @@
+---
+---
+
+Delete the scatter branch's inert `<ZAxis type="number" range={[60, 400]} />`
+declaration (objectui#9681). Recharts' `selectZAxisWithScale` drops a z axis
+carrying no `dataKey` before it reaches a mark, so the declared area envelope
+never applied and every mark was painted at recharts' own implicit default
+size. ⛔ No package is released by this change: nothing rendered moves, and no
+authored value was ever read through the deleted prop.
+
+The declaration's only effect was on readers, and it had already cost one — the
+triage comment on objectui#7396 derived a variable-bubble-size prediction from
+it whose every clause was false. So the delete is paired with a test that states
+the painted mark size as a reading taken off a render
+(`AdvancedChartImpl.scatterSymbolSize-9681.test.tsx`), and the prose that sized
+objectui#7396's edge margin to the envelope's upper bound is repaired to name
+that number as a headroom budget rather than as something the tree declares.
+The margin itself is unchanged, deliberately: it is the envelope a variable-area
+scatter would have to stay inside, so it already survives the day mark area
+becomes configurable.
@@ -106,7 +106,8 @@ const plotAreaOf = (c: HTMLElement) => {
 
 /** Each mark's painted centre and radius, straight off the symbol path: recharts
  *  writes the symbol's bounding box onto it, so `width / 2` IS the drawn radius
- *  rather than a value assumed from the ZAxis range. */
+ *  rather than a value assumed from a declaration (objectui#9681 — the scatter
+ *  branch's `ZAxis range` was such a declaration, and it was inert). */
 const marksOf = (c: HTMLElement) =>
   [...c.querySelectorAll('path.recharts-symbols')].map((p) => {
     const cx = Number(p.getAttribute('cx'));
@@ -166,7 +167,8 @@ describe('objectui#7396 — every scatter mark is drawn wholly inside the plot a
   it('reserves at least a full mark radius, so the WHOLE symbol clears the edge', () => {
     // Stated as the reader sees it — "half a dot is showing" is the complaint,
     // and clearing the edge by a hair would still leave it half-clipped once a
-    // symbol grows. The margin is sized to the declared symbol envelope, so
+    // symbol grows. The margin is sized to `SCATTER_SYMBOL_MAX_AREA`, the
+    // headroom budget rather than the size painted today (objectui#9681), so
     // every clearance is a full radius or better.
     const { container } = renderScatter(FOUR_EDGES);
     for (const o of overhangs(container)) {
 
@@ -0,0 +1,161 @@
+/**
+ * objectui#9681 — what size the scatter paints its marks, stated as a MEASURED
+ * fact rather than as a declaration.
+ *
+ * ## Why this file exists at all
+ *
+ * The scatter branch used to carry `<ZAxis type="number" range={[60, 400]} />`.
+ * It was INERT: recharts' `selectZAxisWithScale` drops a z axis carrying no
+ * `dataKey` before it reaches a mark, so the declared envelope never applied
+ * and every mark was painted at recharts' own implicit default area. The
+ * declaration's only effect was on readers — and it did mislead one, in
+ * writing, on this repository: the triage comment on objectui#7396 read it and
+ * derived "the symbol radius is not constant … bubble size is variable (area
+ * 60..400 ⇒ radius about 4.4..11.3px)", every clause of which was false at that
+ * head.
+ *
+ * ⭐ The lesson that card left behind: **a declaration is not a reading.** An
+ * inert declaration and a live one look identical in the source, so the only
+ * defensible answer to "how big are the marks?" is one taken off a render. That
+ * is what this file is. Deleting the dead prop removed the wrong answer; this
+ * file supplies a right one that cannot go stale unnoticed.
+ *
+ * ## What would turn these red, and why each red is worth having
+ *
+ * - Mark area becomes variable (a `ZAxis` gains a `dataKey`, or a symbol size
+ *   is bound to data another way). That is a NEW capability, not a repair, and
+ *   whoever adds it must come here, restate the size, and re-check
+ *   `SCATTER_SYMBOL_MAX_AREA` — the edge margin objectui#7396 reserved is sized
+ *   to that budget precisely so it survives that day.
+ * - Recharts changes the implicit default area under a version bump. The margin
+ *   prose in `AdvancedChartImpl.tsx` says the painted size is a third-party
+ *   default; if that default moves, a reader should be told rather than left
+ *   with prose that quietly stopped being true.
+ *
+ * ## Why this is measurable in this environment
+ *
+ * Same mechanism the objectui#7396 edge-clipping suite documents: given an
+ * explicit width/height in place of `ResponsiveContainer`, recharts computes
+ * the plot rect and every symbol's geometry arithmetically, with no DOM
+ * measurement in the path. Nothing here pins an absolute coordinate — only the
+ * symbol's own width, which is not a function of text metrics.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import React from 'react';
+import { render, cleanup } from '@testing-library/react';
+
+vi.mock('recharts', async () => {
+  const actual = await vi.importActual<any>('recharts');
+  return {
+    ...actual,
+    // The widget's real box on the showcase Chart Gallery.
+    ResponsiveContainer: ({ children }: any) =>
+      React.cloneElement(children, { width: 510, height: 350 }),
+  };
+});
+
+import AdvancedChartImpl from './AdvancedChartImpl';
+
+afterEach(cleanup);
+
+type Row = Record<string, unknown>;
+
+/**
+ * Recharts' OWN implicit symbol area, in px² — its `implicitZAxis.range` is
+ * `[64, 64]` and a scatter point with no z value is painted at that range's
+ * lower bound, as a circle of `sqrt(area / PI)`.
+ *
+ * ⚠️ A THIRD-PARTY figure this repo does not choose and cannot set from the
+ * outside today. It is spelled out here, rather than left implicit, so that the
+ * day it moves this file says so instead of the margin prose in
+ * `AdvancedChartImpl.tsx` going quietly wrong.
+ */
+const RECHARTS_IMPLICIT_SYMBOL_AREA = 64;
+
+/** The six aggregate rows the Chart Gallery scatter plots — the same fixture
+ *  the objectui#7396 suite uses, and the one the false bubble-size prediction
+ *  was written about. Its y values span 12..60, a 5x spread. */
+const GALLERY: Row[] = [
+  { progress: 0, avg_estimate: 16.5 },
+  { progress: 45, avg_estimate: 40 },
+  { progress: 55, avg_estimate: 60 },
+  { progress: 80, avg_estimate: 24 },
+  { progress: 90, avg_estimate: 30 },
+  { progress: 100, avg_estimate: 12 },
+];
+
+/** Deliberately a different order of magnitude from GALLERY, and a far wider
+ *  spread inside itself: if anything sized a mark from the data, these two
+ *  fixtures could not come out identical. */
+const WIDE_SPREAD: Row[] = [
+  { progress: 1, avg_estimate: 1 },
+  { progress: 50, avg_estimate: 5000 },
+  { progress: 99, avg_estimate: 250000 },
+];
+
+const CONFIG = { progress: { label: 'Progress' }, avg_estimate: { label: 'Avg Estimate' } };
+
+const renderScatter = (data: Row[]) =>
+  render(
+    <AdvancedChartImpl
+      chartType="scatter"
+      xAxisKey="progress"
+      series={[{ dataKey: 'avg_estimate', label: 'Avg Estimate' }] as any}
+      config={CONFIG as any}
+      data={data as any}
+      isAnimationActive={false}
+    />,
+  );
+
+/** Every mark's painted radius, straight off the symbol path: recharts writes
+ *  the symbol's bounding box onto it, so `width / 2` IS the drawn radius. */
+const radiiOf = (c: HTMLElement) => {
+  const marks = [...c.querySelectorAll('path.recharts-symbols')];
+  expect(marks.length, 'no marks were drawn, so this measures nothing').toBeGreaterThan(0);
+  return marks.map((p) => {
+    const r = Number(p.getAttribute('width')) / 2;
+    expect(Number.isFinite(r), 'symbol carries no width, so this measures nothing').toBe(true);
+    expect(r, 'symbol has no radius, so this measures nothing').toBeGreaterThan(0);
+    return r;
+  });
+};
+
+describe('objectui#9681 — the scatter paints ONE mark size, and it is measured here', () => {
+  it('paints every mark of a chart at the same size', () => {
+    // The clause the objectui#7396 triage comment got wrong, stated as an
+    // assertion: across a 5x spread of values, the marks are one size.
+    const radii = radiiOf(renderScatter(GALLERY).container);
+    expect(radii.length, 'the gallery fixture lost rows').toBe(GALLERY.length);
+    expect(
+      new Set(radii.map((r) => r.toFixed(6))).size,
+      `mark size is NOT constant — radii ${JSON.stringify(radii)}. If that is intended, ` +
+        'variable-area marks have arrived and SCATTER_SYMBOL_MAX_AREA needs re-checking.',
+    ).toBe(1);
+  });
+
+  it('paints the same size for a completely different dataset', () => {
+    // Uniformity within one chart could also come from rows that happen to
+    // agree. This is the stronger statement: the size is a property of the
+    // renderer, not of the data — two fixtures four orders of magnitude apart
+    // come out identical.
+    const [gallery] = radiiOf(renderScatter(GALLERY).container);
+    cleanup();
+    const [wide] = radiiOf(renderScatter(WIDE_SPREAD).container);
+    expect(wide, 'mark size moved with the data').toBeCloseTo(gallery, 6);
+  });
+
+  it("draws marks at recharts' implicit default area — nothing in this tree sets it", () => {
+    // The reading itself, computed on the line below rather than written out.
+    // A red here means
+    // either recharts moved its default or this branch started declaring a
+    // symbol size again — both are things a reader must be told about, because
+    // the edge margin's justification names this as a third-party default.
+    const expected = Math.sqrt(RECHARTS_IMPLICIT_SYMBOL_AREA / Math.PI);
+    for (const r of radiiOf(renderScatter(GALLERY).container)) {
+      expect(r, 'the painted symbol area is no longer recharts’ implicit default').toBeCloseTo(
+        expected,
+        6,
+      );
+    }
+  });
+});
@@ -24,7 +24,6 @@ import {
   PolarRadiusAxis,
   Scatter,
   ScatterChart,
-  ZAxis,
   Cell,
   XAxis,
   YAxis,
@@ -395,12 +394,20 @@ const X_AXIS_ALL_LABELS_MAX_BUCKETS = 5;
 const ROTATED_X_LABEL_MAX_CHARS = 12;
 
 /**
- * Symbol AREA envelope the scatter branch declares for its marks, in px².
+ * Symbol AREA budget the scatter's edge margin below is sized against, in px².
+ *
+ * ⚠️ A HEADROOM figure, ⛔ NOT a reading of what the chart paints. Recharts
+ * paints a scatter mark as a circle of `sqrt(area / PI)` and chooses that area
+ * itself: nothing in this file and no authored metadata sets it, so every mark
+ * is drawn at recharts' own implicit default and the budget here is
+ * deliberately well above it. The size actually painted is measured off the
+ * rendered symbol by `AdvancedChartImpl.scatterSymbolSize-9681.test.tsx` —
+ * read that, never this number, for what the marks are.
  *
  * Kept as a named number because the padding below is derived from it rather
- * than guessed: the scatter's `<ZAxis type="number" range={[60, 400]} />`
- * declares that envelope, recharts paints a scatter mark as a circle of
- * `sqrt(area / PI)`, so this is the upper bound of the radius it can draw.
+ * than guessed, and kept at THIS value rather than lowered to what is painted:
+ * it is the envelope a variable-area scatter would have to stay inside, so the
+ * margin already survives the day mark area becomes variable (objectui#9681).
  */
 const SCATTER_SYMBOL_MAX_AREA = 400;
 
@@ -434,13 +441,14 @@ const SCATTER_SYMBOL_MAX_AREA = 400;
  *
  * ## Why this size
  *
- * `sqrt(SCATTER_SYMBOL_MAX_AREA / PI)`, rounded up — the largest radius the
- * declared envelope admits. It is deliberately the envelope's upper bound and
- * not the radius observed today: with no `dataKey` on that ZAxis recharts
- * ignores the declaration entirely and paints every mark at its own implicit
- * default area (measured: r = 4.514px, i.e. area 64), so sizing this to what is
- * painted would tie the fix to a third-party default AND reopen the defect the
- * day a `dataKey` makes the declared envelope live.
+ * `sqrt(SCATTER_SYMBOL_MAX_AREA / PI)`, rounded up — the largest radius that
+ * budget admits. It is deliberately the budget and ⛔ not the radius observed
+ * today: recharts chooses the symbol area itself and nothing here or in
+ * authored metadata moves it, so sizing this margin to what is painted would
+ * tie the fix to a third-party default AND reopen the defect the day mark area
+ * becomes variable. That the painted radius still fits inside this margin is
+ * asserted, not assumed — `AdvancedChartImpl.scatterSymbolSize-9681.test.tsx`
+ * reads both off the same render, so the two cannot drift apart in silence.
  *
  * ## Why these are module constants and not inline objects
  *
@@ -1973,7 +1981,23 @@ function AdvancedChartImplInner({
             padding={SCATTER_Y_AXIS_PADDING}
             {...yAxisSpecProps(primaryY)}
           />
-          <ZAxis type="number" range={[60, 400]} />
+          {/* ⛔ No `<ZAxis>` here, deliberately — scatter mark AREA is recharts'
+              own implicit default and is not configurable in this product
+              today. This branch used to declare `<ZAxis type="number"
+              range={[60, 400]} />`, which painted NOTHING: recharts'
+              `selectZAxisWithScale` drops a z axis that carries no `dataKey`
+              before it reaches a mark, so the declared envelope never applied
+              and every mark came out at the implicit default size. Its only
+              effect was on readers — and it did mislead one, in writing, on
+              this repository: the triage comment on objectui#7396 derived a
+              variable-bubble-size prediction from it whose every clause was
+              false. ⭐ A DECLARATION IS NOT A READING: an inert declaration and
+              a live one look identical in the source, so what this branch
+              paints is stated by a test that reads the rendered symbol
+              (`AdvancedChartImpl.scatterSymbolSize-9681.test.tsx`), never by a
+              prop sitting here. Variable-area marks remain possible — they need
+              a `dataKey` and a schema key to feed it, which is a new capability
+              and its own card, not a prop restored here (objectui#9681). */}
           <ChartTooltip content={<ChartTooltipContent />} />
           {/* `nameKey` is REQUIRED here, for a reason unique to scatter
               (objectui#7248). `ChartLegendContent` resolves a label as