@boostdev/design-system-components 2.4.2 → 2.5.1

package/dist/web-components/index.js

@@ -151,17 +151,17 @@ function resolvePreferredColumns(container, value, totalCols) {
   if (Number.isFinite(n) && n > 0) return Math.min(totalCols, n);
   return Math.max(1, Math.round(totalCols * NAMED_SPAN_FRACTION[value]));
 }
-var ROW_UNIT_PX = 1;
+var TARGET_MAX_IMPLICIT_ROWS = 5e3;
 function supportsNativeMasonry() {
   if (typeof CSS === "undefined" || typeof CSS.supports !== "function") return false;
   return CSS.supports("display", "grid-lanes") || CSS.supports("grid-template-rows", "masonry");
 }
 var ORIGINAL_COL_ATTR = "data-bds-masonry-original-column";
 var LAST_SPAN_ATTR = "data-bds-masonry-span";
+var UNIT_ATTR = "data-bds-masonry-unit";
 function applyMasonryLayout(container, rawChildren, options = {}) {
   const cs = window.getComputedStyle(container);
   const targetGap = parseFloat(cs.columnGap) || 0;
-  container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
   container.style.rowGap = "0px";
   container.style.gridAutoFlow = "dense";
   container.style.overflowAnchor = "none";
@@ -199,7 +199,26 @@ function applyMasonryLayout(container, rawChildren, options = {}) {
     }
   }
   const heights = children.map((child) => child.offsetHeight);
-  const spans = heights.map((h) => Math.max(1, Math.ceil(h + targetGap)));
+  const cols = countGridColumns(container) || 1;
+  const projectedRows = children.reduce((sum, child, i3) => {
+    const rowSpan = Math.max(1, Math.ceil(heights[i3] + targetGap));
+    const colSpan = readExplicitSpan(child, cols);
+    return sum + rowSpan * colSpan;
+  }, 0) / cols;
+  const autoUnit = Math.max(
+    1,
+    Math.ceil(projectedRows / TARGET_MAX_IMPLICIT_ROWS)
+  );
+  const rowUnit = options.rowUnitPx !== void 0 && options.rowUnitPx > 0 ? Math.floor(options.rowUnitPx) : autoUnit;
+  container.style.gridAutoRows = `${rowUnit}px`;
+  const prevUnit = container.getAttribute(UNIT_ATTR);
+  if (prevUnit !== String(rowUnit)) {
+    for (const child of children) child.removeAttribute(LAST_SPAN_ATTR);
+    container.setAttribute(UNIT_ATTR, String(rowUnit));
+  }
+  const spans = heights.map(
+    (h) => Math.max(1, Math.ceil((h + targetGap) / rowUnit))
+  );
   let changed = false;
   for (let i3 = 0; i3 < children.length; i3++) {
     const prev = children[i3].getAttribute(LAST_SPAN_ATTR);
@@ -238,6 +257,7 @@ function clearMasonryLayout(container, rawChildren) {
   container.style.gridAutoFlow = "";
   container.style.rowGap = "";
   container.style.overflowAnchor = "";
+  container.removeAttribute(UNIT_ATTR);
   for (const child of rawChildren) {
     if (child.nodeType !== 1) continue;
     child.style.gridRow = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boostdev/design-system-components",
-  "version": "2.4.2",
+  "version": "2.5.1",
   "description": "BoostDev React component library: accessible, token-driven components built on @boostdev/design-system-foundation",
   "keywords": [
     "React",
@@ -26,7 +26,6 @@
   "type": "module",
   "exports": {
     ".": {
-      "react-native": "./dist/native/index.js",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
@@ -262,7 +261,6 @@
     "./css/section-header": "./src/components/layout/SectionHeader/SectionHeader.module.css"
   },
   "main": "./dist/index.js",
-  "react-native": "./dist/native/index.js",
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
@@ -297,14 +295,12 @@
     "@types/node": "^25.5.0",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@types/react-native": "^0.73.0",
     "@vitejs/plugin-react": "^5.1.4",
     "eslint": "^9",
     "git-cliff": "^2.12.0",
     "identity-obj-proxy": "^3.0.0",
     "jsdom": "^28.1.0",
     "lit": "^3.3.2",
-    "react-native-web": "^0.21.2",
     "remark-gfm": "^4.0.1",
     "storybook": "^8.6.18",
     "storybook-addon-tag-badges": "^1.4.0",
@@ -321,15 +317,11 @@
   "peerDependencies": {
     "@boostdev/design-system-foundation": ">=2.0.0",
     "react": ">=18",
-    "react-dom": ">=18",
-    "react-native": ">=0.70"
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "react-dom": {
       "optional": true
-    },
-    "react-native": {
-      "optional": true
     }
   },
   "publishConfig": {

package/src/components/layout/Grid/Grid.mdx

@@ -131,7 +131,7 @@ Set `isMasonry` on any `Grid` to switch to a masonry (a.k.a. Pinterest-style) la
 Masonry targets [CSS Grid Layout Module Level 3](https://www.w3.org/TR/css-grid-3/) ("grid lanes"):
 
 - **Native path** — when the browser supports `display: grid-lanes` or `grid-template-rows: masonry`, CSS handles everything and the JS polyfill short-circuits. Currently Safari Technology Preview only; the polyfill runs in all other browsers.
-- **Polyfill path** — row-span packing. The container's row tracks are collapsed to a 1 px auto-track with `grid-auto-flow: dense`, and each item is given a `grid-row-end: span ceil(height + gap)`. Items stay in **normal document flow** (no absolute positioning), so surrounding content — footers, scroll anchors, page margins — lays out correctly around the grid.
+- **Polyfill path** — row-span packing. The container's row tracks are collapsed to a small auto-track with `grid-auto-flow: dense`, and each item is given a `grid-row-end: span ceil((height + gap) / rowUnit)`. Items stay in **normal document flow** (no absolute positioning), so surrounding content — footers, scroll anchors, page margins — lays out correctly around the grid. The row-unit defaults to 1 px; for very long galleries the polyfill auto-grows it — see [Row-unit auto-tuner](#row-unit-auto-tuner).
 
 The polyfill re-runs on child size changes (`ResizeObserver` on each child) and child addition/removal (`MutationObserver` on the container). The container itself is not observed — setting row-spans changes the container block-size, which would loop back through the observer.
 
@@ -145,7 +145,7 @@ The polyfill re-runs on child size changes (`ResizeObserver` on each child) and
 
 - **Initial layout** — three passes (clear, batch-read all heights, batch-write all spans). Height reads and writes are each grouped to avoid O(N) forced reflows; the measured cost is one layout pass regardless of item count.
 - **Re-layout** — on child resize or mutation the polyfill is scheduled via `requestAnimationFrame`, so bursts of observer callbacks coalesce into a single re-run per frame.
-- **Ceil overshoot** — the 1 px row track means each item's span can overshoot by up to 1 px. Not visible in practice (row-gap is 0; the gap is baked into each item's span).
+- **Ceil overshoot** — at the default 1 px row track each item's span can overshoot by up to 1 px. Not visible in practice (row-gap is 0; the gap is baked into each item's span). The auto-tuner may grow the row-unit for very long galleries — overshoot is then bounded by the chosen unit (still imperceptible at the unit sizes the auto-tuner picks).
 - **Long lists** — for galleries with hundreds of items, virtualisation is still the correct answer; masonry is orthogonal.
 
 ### SSR / hydration
@@ -237,6 +237,24 @@ Rules:
 
 Column detection runs inside the masonry polyfill's `useLayoutEffect`, so it only executes on the client after mount. The initial server render emits each auto item at its default `full` span until hydration resolves the first polyfill pass — which matches the existing masonry SSR behavior.
 
+## Row-unit auto-tuner
+
+Browsers cap the implicit grid track count for resource protection — historically Chromium at 1000 and Firefox at ~10000 tracks. Past that cap the engine clamps or wraps items, which the user sees as overlapping thumbnails toward the bottom of a long masonry stack. The polyfill expresses each item's height as a row-span (`ceil((height + gap) / rowUnit)`), so a long enough gallery at the default 1 px row-unit will hit the cap.
+
+To stay safely below it, the polyfill auto-tunes the row-unit on every layout pass:
+
+1. Project the implicit row count for the current children using the live column count (`sum(spans) / columns`).
+2. If the projection stays under the safe threshold (~5000 rows — 2× headroom under the strictest reasonable cap), keep the row-unit at 1 px and get pixel-accurate row gaps.
+3. If it would exceed the threshold, grow the row-unit just enough to bring the projection back under (`ceil(projectedRows / threshold)`). Each item's span is recomputed against the new unit; the per-child span cache is invalidated automatically when the unit changes between runs.
+
+This is automatic — most galleries never trigger it. For the rare case where you've measured the auto-tuner picking the wrong unit, escape with `masonryRowUnitPx`:
+
+```tsx
+<Grid isMasonry masonryRowUnitPx={4}>…</Grid>
+```
+
+Trade-off: smaller unit = more pixel-accurate row gaps; larger unit = more headroom under browser caps. Set this **only** when you've confirmed the auto-tuner is wrong for your case — the auto-pick is the right answer for almost every gallery.
+
 ## Migration from `@greenchoice/design-system`
 
 | Greenchoice                     | BoostDev equivalent                    |

package/src/components/layout/Grid/Grid.spec.tsx

@@ -1,5 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { act } from 'react';
+import { afterEach, beforeEach, vi } from 'vitest';
 import { Grid } from './Grid';
 import { GridItem, GridItemSpan } from './GridItem';
 import { applyMasonryLayout, clearMasonryLayout } from './masonry';
@@ -93,9 +94,12 @@ describe('applyMasonryLayout', () => {
     return el;
   }
 
-  it('overrides container to grid-auto-rows: 1px + grid-auto-flow: dense + row-gap: 0', () => {
+  it('overrides container to grid-auto-flow: dense + row-gap: 0 and picks a row-track unit', () => {
     const container = makeContainer(10);
     applyMasonryLayout(container, []);
+    // Auto-tuner picks 1px when the projected row count is well under
+    // the implicit-grid cap; long galleries get a larger unit (covered
+    // in dedicated tests below).
     expect(container.style.gridAutoRows).toBe('1px');
     expect(container.style.gridAutoFlow).toBe('dense');
     expect(container.style.rowGap).toBe('0px');
@@ -141,16 +145,15 @@ describe('applyMasonryLayout', () => {
     expect(a.style.overflowAnchor).toBe('');
   });
 
-  it('assigns grid-row-end: span ceil(height + targetGap) to each item', () => {
+  it('assigns grid-row-end: span ceil((height + targetGap) / rowUnit) to each item', () => {
     const container = makeContainer(10);
     const a = makeItem(100);
     const b = makeItem(201);
     container.append(a, b);
     applyMasonryLayout(container, [a, b]);
 
-    // ceil(100 + 10) = 110
+    // Auto-tuner stays at unit=1 here — projected rows is tiny.
     expect(a.style.gridRowEnd).toBe('span 110');
-    // ceil(201 + 10) = 211
     expect(b.style.gridRowEnd).toBe('span 211');
   });
 
@@ -242,6 +245,73 @@ describe('applyMasonryLayout', () => {
     expect(item.style.alignSelf).toBe('');
   });
 
+  describe('row-unit auto-tuner', () => {
+    it('grows the row-unit when projected implicit row count would exceed the safe threshold', () => {
+      // Build a worst-case scenario: many tall items in a single column so the
+      // projection equals sum(spans). 50 items × 600px each = 30,000 row-units
+      // at unit=1, well over the 5,000 threshold → auto picks unit=ceil(30000/5000)=6.
+      const container = makeContainer(0);
+      container.style.gridTemplateColumns = '100px';
+      const items = Array.from({ length: 50 }, () => makeItem(600));
+      container.append(...items);
+      applyMasonryLayout(container, items);
+      expect(container.style.gridAutoRows).toBe('6px');
+      // span = ceil(600 / 6) = 100
+      expect(items[0].style.gridRowEnd).toBe('span 100');
+    });
+
+    it('accounts for column span when projecting implicit row count', () => {
+      // Regression: the projection has to weight each item by its column span,
+      // otherwise a gallery of half-span items reports half the true row
+      // count and the unit stays at 1. 30 items × 600px tall × 6-col span on
+      // a 12-col grid = 30 * 600 * 6 / 12 = 9,000 implicit rows; the naive
+      // sum(rowSpan)/cols formula would have said 1,500 → unit 1 → overlap in
+      // Firefox. Correct: ceil(9000/5000) = 2.
+      const container = makeContainer(0);
+      container.style.gridTemplateColumns = '100px '.repeat(12).trim();
+      const items = Array.from({ length: 30 }, () => {
+        const el = makeItem(600);
+        el.style.gridColumn = 'span 6';
+        return el;
+      });
+      container.append(...items);
+      applyMasonryLayout(container, items);
+      expect(container.style.gridAutoRows).toBe('2px');
+    });
+
+    it('honors an explicit rowUnitPx override', () => {
+      const container = makeContainer(10);
+      const item = makeItem(100);
+      container.append(item);
+      applyMasonryLayout(container, [item], { rowUnitPx: 8 });
+      expect(container.style.gridAutoRows).toBe('8px');
+      // ceil((100 + 10) / 8) = 14
+      expect(item.style.gridRowEnd).toBe('span 14');
+    });
+
+    it('invalidates the per-child span cache when the row-unit changes between runs', () => {
+      const container = makeContainer(10);
+      const item = makeItem(100);
+      container.append(item);
+      applyMasonryLayout(container, [item], { rowUnitPx: 1 });
+      expect(item.style.gridRowEnd).toBe('span 110');
+      // Switching units must rewrite — without cache invalidation the diff
+      // check would short-circuit because the cached "110" still matches the
+      // newly-computed value (which would be 14 under unit=8).
+      applyMasonryLayout(container, [item], { rowUnitPx: 8 });
+      expect(item.style.gridRowEnd).toBe('span 14');
+    });
+
+    it('clearMasonryLayout removes the unit attribute so the next mount re-tunes', () => {
+      const container = makeContainer(10);
+      const item = makeItem(100);
+      container.append(item);
+      applyMasonryLayout(container, [item], { rowUnitPx: 8 });
+      clearMasonryLayout(container, [item]);
+      expect(container.hasAttribute('data-bds-masonry-unit')).toBe(false);
+    });
+  });
+
   describe('preferredColumnSpan', () => {
     function makeAutoItem(height: number) {
       const el = makeItem(height);
@@ -348,6 +418,126 @@ describe('applyMasonryLayout', () => {
   });
 });
 
+describe('useMasonry scroll debounce', () => {
+  // jsdom has no ResizeObserver — install a mock that captures the callback so
+  // tests can simulate an image decode firing during/outside of a scroll.
+  let roCallback: ResizeObserverCallback | null = null;
+  const originalRO = globalThis.ResizeObserver;
+
+  beforeEach(() => {
+    roCallback = null;
+    class MockResizeObserver {
+      constructor(cb: ResizeObserverCallback) {
+        roCallback = cb;
+      }
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    }
+    (globalThis as unknown as { ResizeObserver: typeof ResizeObserver }).ResizeObserver =
+      MockResizeObserver as unknown as typeof ResizeObserver;
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    if (originalRO) {
+      (globalThis as unknown as { ResizeObserver: typeof ResizeObserver }).ResizeObserver = originalRO;
+    } else {
+      delete (globalThis as unknown as Record<string, unknown>).ResizeObserver;
+    }
+  });
+
+  function stubHeight(el: Element, height: number) {
+    Object.defineProperty(el, 'offsetHeight', { configurable: true, value: height });
+  }
+
+  it('defers re-runs while the user is actively scrolling and applies them once scroll idles', () => {
+    // Regression: during fast scroll in Firefox, an image decode grows its GridItem,
+    // ResizeObserver fires, and the synchronous `grid-auto-flow: dense` re-pack
+    // races the compositor — items appear to overlap because cached tiles from the
+    // pre-shuffle layout are painted over the new layout for a frame or two.
+    const { container } = render(
+      <Grid isMasonry>
+        <GridItem data-testid="a">a</GridItem>
+      </Grid>,
+    );
+    const item = container.querySelector('[data-testid="a"]') as HTMLElement;
+    stubHeight(item, 100);
+
+    // Flush the initial rAF-scheduled layout pass.
+    act(() => {
+      vi.advanceTimersByTime(0);
+      // rAF in jsdom is backed by setTimeout(..., 0)
+    });
+    act(() => {
+      vi.runAllTimers();
+    });
+    const initialSpan = item.style.gridRowEnd;
+    expect(initialSpan).not.toBe('');
+
+    // User starts scrolling.
+    window.dispatchEvent(new Event('scroll'));
+
+    // Image decode grows the item; RO fires.
+    stubHeight(item, 300);
+    act(() => {
+      roCallback?.([] as unknown as ResizeObserverEntry[], {} as ResizeObserver);
+    });
+
+    // Mid-scroll: the new span is NOT applied — deferred until scroll idle.
+    expect(item.style.gridRowEnd).toBe(initialSpan);
+
+    // Scroll stops; after the idle window, the deferred layout pass runs.
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(item.style.gridRowEnd).not.toBe(initialSpan);
+    expect(item.style.gridRowEnd).toBe('span 300');
+  });
+
+  it('still lays out newly-mounted children during active scroll', async () => {
+    // Regression: deferring the whole polyfill during scroll left skeletons
+    // invisible — a child mounted mid-scroll would keep `grid-auto-rows: 1px`
+    // and never receive a row-span write, collapsing to 1px tall until scroll
+    // stopped. Only RO-triggered resizes of already-laid-out items should
+    // defer; initial layout and MutationObserver-driven runs must not.
+    const stub = (h: number) => (el: HTMLElement | null) => {
+      if (el) stubHeight(el, h);
+    };
+
+    function Harness({ extra = false }: { extra?: boolean }) {
+      return (
+        <Grid isMasonry>
+          <GridItem data-testid="a" ref={stub(100)}>a</GridItem>
+          {extra ? <GridItem data-testid="b" ref={stub(80)}>b</GridItem> : null}
+        </Grid>
+      );
+    }
+
+    const { container, rerender } = render(<Harness />);
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+    const a = container.querySelector('[data-testid="a"]') as HTMLElement;
+    expect(a.style.gridRowEnd).not.toBe('');
+
+    // User is actively scrolling when the new child mounts.
+    window.dispatchEvent(new Event('scroll'));
+
+    await act(async () => {
+      rerender(<Harness extra />);
+    });
+    await act(async () => {
+      await vi.runAllTimersAsync();
+    });
+
+    const b = container.querySelector('[data-testid="b"]') as HTMLElement;
+    // The new child must have received a span even though we're mid-scroll.
+    expect(b.style.gridRowEnd).toBe('span 80');
+  });
+});
+
 describe('GridItem', () => {
   it('defaults to full span', () => {
     const { container } = render(<GridItem>x</GridItem>);

package/src/components/layout/Grid/Grid.tsx

@@ -58,6 +58,16 @@ type GridOwnProps = WithClassName & {
    * keep their span.
    */
   masonryPreferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
+  /**
+   * Masonry only. Manual override for the row-track unit (in pixels) the
+   * polyfill uses for `grid-auto-rows` and as the ceil() granularity of each
+   * item's row span. Omit to let the polyfill auto-pick the smallest unit
+   * that keeps the implicit row count under any browser cap — that's the
+   * right answer for almost every gallery and yields pixel-perfect row gaps
+   * when the gallery is short enough to not need rounding. Set this only if
+   * you've confirmed the auto-tuner is wrong for your case.
+   */
+  masonryRowUnitPx?: number;
   as?: ElementType;
 };
 
@@ -73,12 +83,16 @@ export function Grid<C extends ElementType = 'div'>({
   isMasonry = false,
   autoSpanMedia = false,
   masonryPreferredColumnSpan,
+  masonryRowUnitPx,
   as,
   style,
   ...rest
 }: GridProps<C>) {
   const ref = useRef<HTMLElement>(null);
-  useMasonry(ref, isMasonry, { preferredColumnSpan: masonryPreferredColumnSpan });
+  useMasonry(ref, isMasonry, {
+    preferredColumnSpan: masonryPreferredColumnSpan,
+    rowUnitPx: masonryRowUnitPx,
+  });
 
   const classNames = cn(
     css.grid,

package/src/components/layout/Grid/masonry.ts

@@ -65,7 +65,15 @@ function resolvePreferredColumns(
  * `grid-template-rows: masonry` value, the polyfill yields to CSS.
  */
 
-const ROW_UNIT_PX = 1;
+// Target ceiling on the implicit grid row count produced by the polyfill.
+// Browsers cap implicit grid tracks for resource-protection — historically
+// Chromium at 1000 and Firefox at ~10000; past the cap, the layout engine
+// clamps/wraps items and they overlap visually (e.g. bottom thumbnails of a
+// long masonry stack on top of each other in Firefox). The auto-tuner picks
+// a `rowUnitPx` so the projected row count stays under this number. Lower
+// is safer; higher gives finer (more pixel-accurate) row gaps. 5000 leaves
+// 2× headroom under the strictest reasonable cap.
+const TARGET_MAX_IMPLICIT_ROWS = 5000;
 
 export function supportsNativeMasonry(): boolean {
   if (typeof CSS === 'undefined' || typeof CSS.supports !== 'function') return false;
@@ -87,6 +95,17 @@ export type MasonryOptions = {
    * budget for the demotion calculation.
    */
   preferredColumnSpan?: Exclude<GridItemSpanValue, 'auto'>;
+  /**
+   * Manual override for the row-track unit (in pixels) the polyfill uses for
+   * `grid-auto-rows` and as the ceil() granularity of each item's row span.
+   * When omitted (recommended), the polyfill auto-picks the smallest unit that
+   * keeps projected implicit row count under `TARGET_MAX_IMPLICIT_ROWS`.
+   *
+   * Trade-off: smaller = more pixel-accurate row gaps; larger = more headroom
+   * under browser implicit-grid-track caps for very long galleries. Set this
+   * only if you've confirmed the auto-tuner is wrong for your case.
+   */
+  rowUnitPx?: number;
 };
 
 // Data attribute used to remember an auto item's inline `grid-column` before the
@@ -105,6 +124,14 @@ const ORIGINAL_COL_ATTR = 'data-bds-masonry-original-column';
 // of the newly laid out items for a frame or two.
 const LAST_SPAN_ATTR = 'data-bds-masonry-span';
 
+// Container attribute caching the last applied row-unit (px). When the
+// auto-tuner picks a different unit on a re-run (e.g. children added pushed
+// the projected row count past the threshold), every per-child cached span
+// becomes stale because they were computed against the old unit — we clear
+// them so the next diff check forces a full rewrite. Cleared in
+// clearMasonryLayout.
+const UNIT_ATTR = 'data-bds-masonry-unit';
+
 export function applyMasonryLayout(
   container: HTMLElement,
   rawChildren: HTMLElement[],
@@ -117,7 +144,6 @@ export function applyMasonryLayout(
   const cs = window.getComputedStyle(container);
   const targetGap = parseFloat(cs.columnGap) || 0;
 
-  container.style.gridAutoRows = `${ROW_UNIT_PX}px`;
   container.style.rowGap = '0px';
   container.style.gridAutoFlow = 'dense';
   // `dense` + per-child `ResizeObserver` can fight the browser's scroll anchoring:
@@ -190,12 +216,58 @@ export function applyMasonryLayout(
   // O(N) forced-reflow cost of a read-then-write loop.
   const heights = children.map((child) => child.offsetHeight);
 
+  // Pick the row-track unit. Manual override wins; otherwise auto-tune.
+  //
+  // Auto-tune uses the projected implicit row count (assuming ideal `dense`
+  // packing across the current grid columns) and picks the smallest unit such
+  // that the projection stays under TARGET_MAX_IMPLICIT_ROWS. Galleries that
+  // don't risk hitting any browser cap stay at unit=1 and get pixel-perfect
+  // gaps; only galleries large enough to threaten the cap pay the rounding
+  // cost. The unit always grows monotonically with content, so once a gallery
+  // is above the threshold its layout is stable across runs.
+  //
+  // The projection treats each item as occupying `rowSpan × colSpan` cells
+  // — a `columnSpan="full"` item is a whole row to itself, a one-quarter
+  // item shares its row with three siblings. Summing the area and dividing
+  // by total columns gives a lower bound on implicit row count. (A naive
+  // `sum(rowSpan) / cols` would silently underestimate by avg-col-span and
+  // leave galleries with multi-column items overflowing browser caps.)
+  const cols = countGridColumns(container) || 1;
+  const projectedRows = children.reduce((sum, child, i) => {
+    const rowSpan = Math.max(1, Math.ceil(heights[i] + targetGap));
+    const colSpan = readExplicitSpan(child, cols);
+    return sum + rowSpan * colSpan;
+  }, 0) / cols;
+  const autoUnit = Math.max(
+    1,
+    Math.ceil(projectedRows / TARGET_MAX_IMPLICIT_ROWS),
+  );
+  const rowUnit =
+    options.rowUnitPx !== undefined && options.rowUnitPx > 0
+      ? Math.floor(options.rowUnitPx)
+      : autoUnit;
+
+  // Apply the chosen unit. Setting `gridAutoRows` here (not before measurement)
+  // is safe because `align-self: start` makes offsetHeight return the content
+  // height regardless of the cell size — heights are independent of the unit.
+  container.style.gridAutoRows = `${rowUnit}px`;
+
+  // If the unit changed since the last run, every cached span is stale.
+  // Force a re-write by clearing the cache attributes before the diff check.
+  const prevUnit = container.getAttribute(UNIT_ATTR);
+  if (prevUnit !== String(rowUnit)) {
+    for (const child of children) child.removeAttribute(LAST_SPAN_ATTR);
+    container.setAttribute(UNIT_ATTR, String(rowUnit));
+  }
+
   // Compute spans; skip the entire write pass if every span matches the
   // previously-applied value. ResizeObserver fires freely in Firefox during
   // image decode and scroll — without this guard, each fire triggers a dense
   // re-pack that's visible as overlap on fast scroll (the compositor hasn't
   // caught up with the newly shuffled positions).
-  const spans = heights.map((h) => Math.max(1, Math.ceil(h + targetGap)));
+  const spans = heights.map((h) =>
+    Math.max(1, Math.ceil((h + targetGap) / rowUnit)),
+  );
   let changed = false;
   for (let i = 0; i < children.length; i++) {
     const prev = children[i].getAttribute(LAST_SPAN_ATTR);
@@ -249,6 +321,7 @@ export function clearMasonryLayout(container: HTMLElement, rawChildren: HTMLElem
   container.style.gridAutoFlow = '';
   container.style.rowGap = '';
   container.style.overflowAnchor = '';
+  container.removeAttribute(UNIT_ATTR);
   for (const child of rawChildren) {
     if (child.nodeType !== 1) continue;
     child.style.gridRow = '';
@@ -279,24 +352,66 @@ export function useMasonry(
   enabled: boolean,
   options: MasonryOptions = {},
 ): void {
-  const { preferredColumnSpan } = options;
+  const { preferredColumnSpan, rowUnitPx } = options;
   useLayoutEffect(() => {
     const container = ref.current;
     if (!container || !enabled) return;
     if (supportsNativeMasonry()) return;
 
     let frame = 0;
-    const runNow = () => {
-      cancelAnimationFrame(frame);
+    let scrollTimer: ReturnType<typeof setTimeout> | null = null;
+    let scrolling = false;
+    let pending = false;
+
+    const apply = () => {
       applyMasonryLayout(container, Array.from(container.children) as HTMLElement[], {
         preferredColumnSpan,
+        rowUnitPx,
       });
     };
+    const runNow = () => {
+      cancelAnimationFrame(frame);
+      apply();
+    };
     const schedule = () => {
       cancelAnimationFrame(frame);
       frame = requestAnimationFrame(runNow);
     };
 
+    // RO-triggered re-runs (resizes of existing items — image decode, font swap) are
+    // the ones that cause the Firefox compositor race: `grid-auto-flow: dense` re-packs
+    // already-laid-out items, and cached tiles from the pre-shuffle layout paint over
+    // the new positions for a frame or two, looking like overlap. Deferring *those*
+    // writes until scroll stops hides the race. Initial mount and MutationObserver-
+    // triggered runs (new children added) must NOT defer — a skeleton mounting during
+    // active scroll would otherwise stay at `grid-auto-rows: 1px` height, invisibly
+    // collapsed, until scroll idles.
+    const onResize = () => {
+      if (scrolling) {
+        pending = true;
+        return;
+      }
+      apply();
+    };
+
+    const SCROLL_IDLE_MS = 150;
+    const onScroll = () => {
+      scrolling = true;
+      if (scrollTimer) clearTimeout(scrollTimer);
+      scrollTimer = setTimeout(() => {
+        scrolling = false;
+        scrollTimer = null;
+        if (pending) {
+          pending = false;
+          apply();
+        }
+      }, SCROLL_IDLE_MS);
+    };
+    // `capture: true` catches scroll events from any nested scroll container, since
+    // scroll doesn't bubble. `passive: true` tells the browser we won't preventDefault —
+    // critical for not blocking scroll performance.
+    window.addEventListener('scroll', onScroll, { passive: true, capture: true });
+
     schedule();
 
     // ResizeObserver fires during the "update the rendering" step, AFTER layout and
@@ -305,9 +420,10 @@ export function useMasonry(
     // defer to rAF instead, there's a visible frame where a grown item (e.g. a
     // lazy-loaded image whose dimensions just resolved) overflows its stale cell
     // and visually overlaps the next item in its column — easy to see on fast
-    // scroll through a long gallery.
+    // scroll through a long gallery. (onResize itself still defers writes when the
+    // user is actively scrolling — see its `scrolling` guard above.)
     const ro =
-      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(runNow) : null;
+      typeof ResizeObserver !== 'undefined' ? new ResizeObserver(onResize) : null;
     const observeDescendants = (child: Element) => {
       if (!ro) return;
       ro.observe(child);
@@ -342,9 +458,11 @@ export function useMasonry(
 
     return () => {
       cancelAnimationFrame(frame);
+      if (scrollTimer) clearTimeout(scrollTimer);
+      window.removeEventListener('scroll', onScroll, { capture: true } as EventListenerOptions);
       ro?.disconnect();
       mo?.disconnect();
       clearMasonryLayout(container, Array.from(container.children) as HTMLElement[]);
     };
-  }, [ref, enabled, preferredColumnSpan]);
+  }, [ref, enabled, preferredColumnSpan, rowUnitPx]);
 }