@ceriousdevtech/react-cerious-scroll 1.0.6 → 1.1.0

package/CHANGELOG.md

@@ -5,11 +5,32 @@ All notable changes to react-cerious-scroll will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-08-22
+
+### Added
+- Declarative canonical and dynamic Masonry support. The wrapper supplies the core DOM `renderItem` callback while consumers continue returning React nodes from the existing `renderItem` prop.
+- `jumpToItem(index, screenOffset?)` on the hook result and component ref.
+- `CeriousScrollOptions` now accepts Masonry geometry without requiring the engine's imperative DOM callback.
+- Canonical-height and dynamic-height Masonry demo routes and regression tests for both rendering paths.
+
+### Changed
+- Updated `@ceriousdevtech/cerious-scroll` to `^1.1.0` and re-exported the new Masonry and height-provider types.
+- Masonry card-count changes recreate card-derived segment state; list and table count changes continue updating in place.
+
+## [1.0.7] - 2026-06-24
+
+### Changed
+- **A change in the item count now grows/shrinks the dataset in place instead of recreating the engine.** The hook calls `updateTotalElements()` (propagating the new count to navigation bounds, the scrollbar track, the renderer, and the height cache) rather than tearing down and rebuilding the scroller. A live append/prepend therefore keeps the scroll position and any in-progress scrollbar drag alive, and an appended dataset keeps a stable bottom index instead of a bouncing tail. A shrink that leaves the position past the new end is clamped, and the scrollbar thumb is re-synced after the lengthened track re-renders. No public API change.
+- Updated the core engine dependency to `@ceriousdevtech/cerious-scroll@^1.0.8` (native-scrollbar drag rendering is now coalesced to one render per frame, with no per-row layout thrash on fast drags).
+
 ## [1.0.6] - 2026-06-11
 
 ### Fixed
 - **`recalculate()` now refreshes row content, not just heights.** It re-runs `renderItem` for every currently-rendered row (busting the per-index portal cache), so rows whose content depends on state outside `(item, index)` — e.g. a sliding/windowed data source where index → content shifts — update on an in-place refresh. Previously `recalculate()` only cleared the engine's height caches and re-measured, leaving such rows showing stale content; this now matches the Vue/Angular wrappers, whose `recalculate()` re-runs the row template/slot. A plain scroll still reuses cached portals for unchanged rows, so heavy rows stay cheap to scroll.
 
+### Changed
+- Updated the core engine dependency to `@ceriousdevtech/cerious-scroll@^1.0.7` (scrollbar drag-to-top fix).
+
 ## [1.0.5] - 2026-06-08
 
 ### Added

package/README.md

@@ -110,7 +110,7 @@ function List() {
 | `totalElements` | `number` | Total item count. Required if `items` is omitted. |
 | `getItem` | `(index) => TItem` | Lazy item getter for large/sparse datasets. |
 | `tableHeader` | `ReactNode` | Table mode only. A `<tr>` of `<th>`s rendered into the engine's `<thead>` (see [Table layout](#table-layout)). |
-| `options` | `CeriousScrollOptions` | Engine options (keyboard/touch/wheel/scrollbar/`layout`/etc.). Read once at creation. |
+| `options` | `CeriousScrollOptions` | Engine options. Masonry's DOM callback is supplied by the wrapper. Read once at creation. |
 | `autoRender` | `boolean` | Re-render on scroll/resize/data changes. Default `true`. |
 | `onViewportChange` | `(detail) => void` | Normalized viewport-change callback. |
 | `onMeasuredViewport` | `(range) => void` | Measured range after each render pass. |
@@ -122,6 +122,7 @@ function List() {
 ```tsx
 const ref = useRef<CeriousScrollHandle>(null);
 // ref.current?.jumpToElement(500);
+// ref.current?.jumpToItem(500); // Masonry cards
 // ref.current?.scrollToPercentage(50);
 // ref.current?.reset();
 // ref.current?.render();
@@ -131,6 +132,38 @@ const ref = useRef<CeriousScrollHandle>(null);
 
 ---
 
+## Masonry layout
+
+Set `layout: 'masonry'` and provide Masonry geometry without a DOM
+`renderItem`; the wrapper connects your existing React render prop to the core
+renderer. Supplying `getItemHeight` selects canonical placement:
+
+```tsx
+<CeriousScroll
+  ref={ref}
+  className="gallery"
+  totalElements={photos.length}
+  getItem={(index) => photos[index]}
+  options={{
+    layout: 'masonry',
+    masonry: {
+      getItemHeight: (_index, width) => width * 0.75 + 48,
+      targetColumnWidth: 280,
+      gap: 16,
+    },
+  }}
+  renderItem={(photo, index) => <PhotoCard photo={photo} index={index} />}
+/>
+```
+
+Omit `getItemHeight` for dynamic DOM-measured cards. React static markup is
+used for the offscreen measurement probe; visible cards remain normal live
+portals with Context, refs, state, and events.
+
+Use `ref.current?.jumpToItem(index, screenOffset?)` for card navigation and
+`ref.current?.scroller?.masonryDeterminism` to read `'canonical'` or `'local'`.
+The demo gallery includes matching canonical and dynamic Masonry pages.
+
 ## Table layout
 
 Pass `options={{ layout: 'table' }}` to render real `<table>` / `<tr>` / `<td>` rows with a frozen header and native column alignment. Your `renderItem` returns the row's `<td>` cells, and `tableHeader` provides the (declarative, reactive) `<thead>` row:
@@ -173,8 +206,8 @@ import { TABLE_COLUMNS } from './data';
   built-in `ResizeObserver`.
 - **`options` are read at creation.** Changing `options` after mount has no
   effect; remount (e.g. with a `key`) to apply new engine options.
-- **Changing the item count** recreates the engine internally (scroll position
-  is preserved). Mutating items without changing the count just re-renders the
+- **Changing the item count** updates lists/tables in place. Masonry recreates
+  its card-count-derived segment layout. Mutating items without changing the count just re-renders the
   content (cheap, and your row state is preserved) — it does **not** discard
   cached heights, so editable grids that produce a new `items` array on every
   edit don't trigger a full viewport re-measure.

package/dist/cerious-scroll.d.ts

@@ -24,6 +24,7 @@ export interface CeriousScrollHandle {
     scroller: CeriousScrollEngine | null;
     render(): MeasuredViewportRange | null;
     jumpToElement(index: number): MeasuredViewportRange | null;
+    jumpToItem(index: number, screenOffset?: number): MeasuredViewportRange | null;
     scrollToPercentage(percentage: number): MeasuredViewportRange | null;
     reset(): MeasuredViewportRange | null;
     /**

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const ee=require("react/jsx-runtime"),r=require("react"),z=require("react-dom"),te=require("react-dom/server"),G=require("@ceriousdevtech/cerious-scroll"),$="data-cerious-scroll-content",re="data-cerious-scroll-row";function ne(e){const u=e.querySelector(`[${$}]`);if(u)return u;const n=document.createElement("div");return n.setAttribute($,""),n.style.position="relative",n.style.width="100%",n.style.height="100%",n.style.overflowY="clip",n.style.overflowX="auto",e.appendChild(n),n}function ce(e,u){const n=h=>{const l=h.detail;l&&u({percentage:l.percentage,currentElement:l.currentElement,scrollOffset:l.scrollOffset,result:{element:l.result.element,offset:l.result.offset}})},f=h=>{const l=h.detail;l&&u({percentage:l.percentage,currentElement:l.element,scrollOffset:l.scrollOffset,result:{element:l.element,offset:l.scrollOffset}})};return e.addEventListener("cerious-viewport-change",n),e.addEventListener("viewport-change",f),()=>{e.removeEventListener("cerious-viewport-change",n),e.removeEventListener("viewport-change",f)}}function le(e,u){const n=typeof e=="number"?e:typeof u=="number"?u:void 0;if(n===void 0||Number.isNaN(n))throw new Error("useCeriousScroll: provide `totalElements` or `items`.");return Math.max(1,Math.floor(n))}function J(e){var Y;const u=r.useRef(null),n=r.useRef(null),f=r.useRef(new Map),h=r.useRef(new Map),l=r.useRef(null),R=r.useRef(null),S=r.useRef(null),T=r.useRef(e.tableHeader),[,M]=r.useReducer(t=>t+1,0),[A,p]=r.useState(null),b=r.useRef(e.renderItem),g=r.useRef(e.items??null),v=r.useRef(e.getItem),L=r.useRef(e.options),q=r.useRef(e.autoRender??!0),D=r.useRef(e.totalElements??null),H=r.useRef(e.onViewportChange),P=r.useRef(e.onMeasuredViewport),j=r.useRef(e.onReady);b.current=e.renderItem,g.current=e.items??null,v.current=e.getItem,T.current=e.tableHeader,L.current=e.options,q.current=e.autoRender??!0,D.current=e.totalElements??null,H.current=e.onViewportChange,P.current=e.onMeasuredViewport,j.current=e.onReady;const B=r.useCallback(t=>{const c=v.current;if(c)return c(t);const o=g.current;return o?o[t]:void 0},[]),s=r.useCallback(()=>{var I,O;const t=n.current;if(!t)return null;const{scroller:c,contentEl:o,container:a}=t,k=a.clientHeight||a.offsetHeight||0,w=[],m=((I=L.current)==null?void 0:I.layout)==="table",_=(i,d)=>{const C=document.createElement("div");m&&(C.style.display="contents"),C.setAttribute(re,String(i)),C.innerHTML=te.renderToStaticMarkup(r.createElement(r.Fragment,null,b.current(B(i),i))),d.appendChild(C),f.current.set(i,{el:d,mount:C}),w.push(C)},y=c.renderViewport(k,o,_),F=new Set(c.getRenderedIndices());return f.current.forEach((i,d)=>{F.has(d)||f.current.delete(d)}),w.forEach(i=>{i.textContent=""}),z.flushSync(M),(O=P.current)==null||O.call(P,y),y},[]),K=e.totalElements??((Y=e.items)==null?void 0:Y.length)??null;r.useEffect(()=>{var F,I,O;const t=u.current;if(!t)return;const c=ne(t),o=L.current??{},a=o.onScroll,k={...o,onScroll:()=>{a==null||a(),q.current&&s()}};if(o.layout==="table"&&T.current!=null){const i=(F=o.table)==null?void 0:F.header;k.table={...o.table,header:d=>{S.current=d,i==null||i(d)}}}const w=le(D.current,((I=g.current)==null?void 0:I.length)??null),m=new G.CeriousScroll(t,w,k);R.current&&(m.currentElement=Math.min(R.current.currentElement,w-1),m.scrollOffset=R.current.scrollOffset,R.current=null),n.current={scroller:m,contentEl:c,container:t},p(m);const _=ce(t,i=>{var d;(d=H.current)==null||d.call(H,i)});(O=j.current)==null||O.call(j,m);let y=0;return q.current&&(y=requestAnimationFrame(()=>s())),()=>{cancelAnimationFrame(y),_(),R.current={currentElement:m.currentElement,scrollOffset:m.scrollOffset},f.current.clear(),h.current.clear(),l.current=null,c.textContent="",m.detachScrollbar(t),m.dispose(),n.current=null,p(null)}},[K,s]),r.useEffect(()=>{if(!n.current||!q.current)return;const t=requestAnimationFrame(()=>s());return()=>cancelAnimationFrame(t)},[e.items,e.getItem]);const Q=r.useCallback(t=>{const c=n.current;return c?(c.scroller.jumpToElement(t),s()):null},[s]),U=r.useCallback(t=>{const c=n.current;return c?(c.scroller.handleScrollPercentage(t),s()):null},[s]),Z=r.useCallback(()=>{const t=n.current;return t?(t.scroller.reset(),s()):null},[s]),x=r.useCallback(()=>{const t=n.current;return t?(t.scroller.clearAllCaches(),h.current.clear(),s()):null},[s]),W=g.current,X=!v.current&&W!=null?W.length:null,N=b.current,E=h.current;l.current!==N&&(E.clear(),l.current=N);const V=[];return f.current.forEach((t,c)=>{if(X!==null&&c>=X){E.delete(c);return}const o=B(c);let a=E.get(c);(!a||a.item!==o||a.mount!==t.mount)&&(a={item:o,mount:t.mount,node:z.createPortal(N(o,c),t.mount,String(c))},E.set(c,a)),V.push(a.node)}),E.size>f.current.size&&E.forEach((t,c)=>{f.current.has(c)||E.delete(c)}),e.tableHeader!=null&&S.current&&V.push(z.createPortal(e.tableHeader,S.current,"cerious-thead")),{containerRef:u,portals:V,scroller:A,render:s,jumpToElement:Q,scrollToPercentage:U,reset:Z,recalculate:x}}function oe(e,u){const{className:n,style:f,"data-testid":h,children:l,...R}=e,{containerRef:S,portals:T,scroller:M,render:A,jumpToElement:p,scrollToPercentage:b,reset:g,recalculate:v}=J(R);return r.useImperativeHandle(u,()=>({scroller:M,render:A,jumpToElement:p,scrollToPercentage:b,reset:g,recalculate:v}),[M,A,p,b,g,v]),ee.jsxs("div",{ref:S,className:n,"data-testid":h,style:{position:"relative",overflow:"hidden",...f},children:[l,T]})}const ue=r.forwardRef(oe);Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>G.CeriousScroll});exports.CeriousScroll=ue;exports.useCeriousScroll=J;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const ae=require("react/jsx-runtime"),n=require("react"),G=require("react-dom"),x=require("react-dom/server"),re=require("@ceriousdevtech/cerious-scroll"),ee="data-cerious-scroll-content",_="data-cerious-scroll-row";function ie(r){const m=r.querySelector(`[${ee}]`);if(m)return m;const c=document.createElement("div");return c.setAttribute(ee,""),c.style.position="relative",c.style.width="100%",c.style.height="100%",c.style.overflowY="clip",c.style.overflowX="auto",r.appendChild(c),c}function fe(r,m){const c=E=>{const l=E.detail;l&&m({percentage:l.percentage,currentElement:l.currentElement,scrollOffset:l.scrollOffset,result:{element:l.result.element,offset:l.result.offset}})},a=E=>{const l=E.detail;l&&m({percentage:l.percentage,currentElement:l.element,scrollOffset:l.scrollOffset,result:{element:l.element,offset:l.scrollOffset}})};return r.addEventListener("cerious-viewport-change",c),r.addEventListener("viewport-change",a),()=>{r.removeEventListener("cerious-viewport-change",c),r.removeEventListener("viewport-change",a)}}function te(r,m){const c=typeof r=="number"?r:typeof m=="number"?m:void 0;if(c===void 0||Number.isNaN(c))throw new Error("useCeriousScroll: provide `totalElements` or `items`.");return Math.max(1,Math.floor(c))}function ne(r){var Z;const m=n.useRef(null),c=n.useRef(null),a=n.useRef(new Map),E=n.useRef(new Map),l=n.useRef(null),y=n.useRef(null),w=n.useRef(null),q=n.useRef(r.tableHeader),[,k]=n.useReducer(e=>e+1,0),[H,T]=n.useState(null),[F,P]=n.useReducer(e=>e+1,0),p=n.useRef(r.renderItem),b=n.useRef(r.items??null),$=n.useRef(r.getItem),S=n.useRef(r.options),I=n.useRef(r.autoRender??!0),B=n.useRef(r.totalElements??null),L=n.useRef(r.onViewportChange),N=n.useRef(r.onMeasuredViewport),V=n.useRef(r.onReady);p.current=r.renderItem,b.current=r.items??null,$.current=r.getItem,q.current=r.tableHeader,S.current=r.options,I.current=r.autoRender??!0,B.current=r.totalElements??null,L.current=r.onViewportChange,N.current=r.onMeasuredViewport,V.current=r.onReady;const z=n.useCallback(e=>{const t=$.current;if(t)return t(e);const s=b.current;return s?s[e]:void 0},[]),J=n.useCallback((e,t)=>{const s=z(e);if(t.dataset.ceriousMasonry==="probe"){const f=document.createElement("div");f.setAttribute(_,String(e)),f.innerHTML=x.renderToStaticMarkup(n.createElement(n.Fragment,null,p.current(s,e))),t.appendChild(f);return}let o=t.querySelector(`[${_}]`);o||(o=document.createElement("div"),t.appendChild(o)),o.setAttribute(_,String(e)),a.current.forEach((f,R)=>{f.el===t&&R!==e&&a.current.delete(R)}),a.current.set(e,{el:t,mount:o})},[z]),u=n.useCallback(()=>{var O,A,j;const e=c.current;if(!e)return null;const{scroller:t,contentEl:s,container:o}=e,f=o.clientHeight||o.offsetHeight||0,R=[],M=((O=S.current)==null?void 0:O.layout)==="table",v=((A=S.current)==null?void 0:A.layout)==="masonry",D=(h,i)=>{const g=document.createElement("div");M&&(g.style.display="contents"),g.setAttribute(_,String(h)),g.innerHTML=x.renderToStaticMarkup(n.createElement(n.Fragment,null,p.current(z(h),h))),i.appendChild(g),a.current.set(h,{el:i,mount:g}),R.push(g)},d=t.renderViewport(f,s,D),Y=v?null:new Set(t.getRenderedIndices());return a.current.forEach((h,i)=>{v?(!h.el.isConnected||h.el.dataset.elementIndex!==String(i))&&a.current.delete(i):Y.has(i)||a.current.delete(i)}),R.forEach(h=>{h.textContent=""}),G.flushSync(k),(j=N.current)==null||j.call(N,d),d},[]),K=r.totalElements??((Z=r.items)==null?void 0:Z.length)??null;n.useEffect(()=>{var A,j,h;const e=m.current;if(!e)return;const t=S.current??{},s=t.layout==="masonry",o=s?e:ie(e),f=t.onScroll,{masonry:R,...M}=t,v={...M,onScroll:()=>{f==null||f(),I.current&&u()}};if(s){if(!R)throw new Error("useCeriousScroll: layout 'masonry' requires `options.masonry`.");v.masonry={...R,renderItem:J}}if(t.layout==="table"&&q.current!=null){const i=(A=t.table)==null?void 0:A.header;v.table={...t.table,header:g=>{w.current=g,i==null||i(g)}}}const D=te(B.current,((j=b.current)==null?void 0:j.length)??null),d=new re.CeriousScroll(e,D,v);y.current&&(d.currentElement=Math.min(y.current.currentElement,D-1),d.scrollOffset=y.current.scrollOffset,y.current=null),c.current={scroller:d,contentEl:o,container:e},T(d);const Y=fe(e,i=>{var g;(g=L.current)==null||g.call(L,i)});(h=V.current)==null||h.call(V,d);let O=0;return I.current&&(O=requestAnimationFrame(()=>u())),()=>{var i;cancelAnimationFrame(O),Y(),y.current=((i=S.current)==null?void 0:i.layout)==="masonry"?null:{currentElement:d.currentElement,scrollOffset:d.scrollOffset},a.current.clear(),E.current.clear(),l.current=null,d.detachScrollbar(e),d.dispose(),o.textContent="",c.current=null,T(null)}},[u,J,F]),n.useEffect(()=>{var f,R;const e=c.current;if(!e||K==null)return;const t=te(B.current,((f=b.current)==null?void 0:f.length)??null),s=((R=S.current)==null?void 0:R.layout)==="masonry",o=s?e.scroller.itemCount:e.scroller.totalElements;if(t!==o){if(s){P();return}if(e.scroller.updateTotalElements(t),e.scroller.currentElement>t-1&&e.scroller.jumpToElement(t-1),I.current){const M=e.scroller;requestAnimationFrame(()=>{u(),M.syncScrollbar()})}else e.scroller.syncScrollbar()}},[K,u]),n.useEffect(()=>{if(!c.current||!I.current)return;const e=requestAnimationFrame(()=>u());return()=>cancelAnimationFrame(e)},[r.items,r.getItem]);const ce=n.useCallback(e=>{const t=c.current;return t?(t.scroller.jumpToElement(e),u()):null},[u]),oe=n.useCallback((e,t=0)=>{const s=c.current;return s?(s.scroller.jumpToItem(e,t),u()):null},[u]),le=n.useCallback(e=>{const t=c.current;return t?(t.scroller.handleScrollPercentage(e),u()):null},[u]),se=n.useCallback(()=>{const e=c.current;return e?(e.scroller.reset(),u()):null},[u]),ue=n.useCallback(()=>{const e=c.current;return e?(e.scroller.clearAllCaches(),E.current.clear(),u()):null},[u]),Q=b.current,U=!$.current&&Q!=null?Q.length:null,W=p.current,C=E.current;l.current!==W&&(C.clear(),l.current=W);const X=[];return a.current.forEach((e,t)=>{if(U!==null&&t>=U){C.delete(t);return}const s=z(t);let o=C.get(t);(!o||o.item!==s||o.mount!==e.mount)&&(o={item:s,mount:e.mount,node:G.createPortal(W(s,t),e.mount,String(t))},C.set(t,o)),X.push(o.node)}),C.size>a.current.size&&C.forEach((e,t)=>{a.current.has(t)||C.delete(t)}),r.tableHeader!=null&&w.current&&X.push(G.createPortal(r.tableHeader,w.current,"cerious-thead")),{containerRef:m,portals:X,scroller:H,render:u,jumpToElement:ce,jumpToItem:oe,scrollToPercentage:le,reset:se,recalculate:ue}}function me(r,m){const{className:c,style:a,"data-testid":E,children:l,...y}=r,{containerRef:w,portals:q,scroller:k,render:H,jumpToElement:T,jumpToItem:F,scrollToPercentage:P,reset:p,recalculate:b}=ne(y);return n.useImperativeHandle(m,()=>({scroller:k,render:H,jumpToElement:T,jumpToItem:F,scrollToPercentage:P,reset:p,recalculate:b}),[k,H,T,F,P,p,b]),ae.jsxs("div",{ref:w,className:c,"data-testid":E,style:{position:"relative",overflow:"hidden",...a},children:[l,q]})}const de=n.forwardRef(me);Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>re.CeriousScroll});exports.CeriousScroll=de;exports.useCeriousScroll=ne;

package/dist/index.d.ts

@@ -8,7 +8,7 @@
 export { CeriousScroll } from './cerious-scroll';
 export type { CeriousScrollProps, CeriousScrollHandle } from './cerious-scroll';
 export { useCeriousScroll } from './use-cerious-scroll';
-export type { UseCeriousScrollOptions, UseCeriousScrollResult, } from './use-cerious-scroll';
+export type { UseCeriousScrollOptions, UseCeriousScrollResult, CeriousScrollOptions, } from './use-cerious-scroll';
 export type { CeriousViewportChangeDetail } from './viewport-change';
 export { CeriousScroll as CeriousScrollEngine } from '@ceriousdevtech/cerious-scroll';
-export type { CeriousScrollOptions, KeyboardNavigationOptions, TouchNavigationOptions, WheelNavigationOptions, ElementRenderer, ElementHeightCalculator, ScrollResult, MeasuredViewportRange, } from '@ceriousdevtech/cerious-scroll';
+export type { KeyboardNavigationOptions, TouchNavigationOptions, WheelNavigationOptions, ElementRenderer, ElementHeightCalculator, ScrollResult, MeasuredViewportRange, HeightProvider, MasonryDeterminism, MasonryOptions, } from '@ceriousdevtech/cerious-scroll';

package/dist/index.js

@@ -1,185 +1,230 @@
-import { jsxs as ee } from "react/jsx-runtime";
-import { useRef as o, useReducer as te, useState as re, useCallback as w, useEffect as Y, createElement as ne, Fragment as ce, forwardRef as oe, useImperativeHandle as le } from "react";
-import { flushSync as se, createPortal as G } from "react-dom";
-import { renderToStaticMarkup as ue } from "react-dom/server";
-import { CeriousScroll as ae } from "@ceriousdevtech/cerious-scroll";
-import { CeriousScroll as ye } from "@ceriousdevtech/cerious-scroll";
-const J = "data-cerious-scroll-content", ie = "data-cerious-scroll-row";
-function fe(e) {
-  const s = e.querySelector(`[${J}]`);
-  if (s) return s;
-  const r = document.createElement("div");
-  return r.setAttribute(J, ""), r.style.position = "relative", r.style.width = "100%", r.style.height = "100%", r.style.overflowY = "clip", r.style.overflowX = "auto", e.appendChild(r), r;
+import { jsxs as fe } from "react/jsx-runtime";
+import { useRef as u, useReducer as ee, useState as de, useCallback as b, createElement as te, Fragment as re, useEffect as J, forwardRef as he, useImperativeHandle as ge } from "react";
+import { flushSync as Ee, createPortal as ne } from "react-dom";
+import { renderToStaticMarkup as oe } from "react-dom/server";
+import { CeriousScroll as pe } from "@ceriousdevtech/cerious-scroll";
+import { CeriousScroll as He } from "@ceriousdevtech/cerious-scroll";
+const ce = "data-cerious-scroll-content", B = "data-cerious-scroll-row";
+function ye(r) {
+  const f = r.querySelector(`[${ce}]`);
+  if (f) return f;
+  const n = document.createElement("div");
+  return n.setAttribute(ce, ""), n.style.position = "relative", n.style.width = "100%", n.style.height = "100%", n.style.overflowY = "clip", n.style.overflowX = "auto", r.appendChild(n), n;
 }
-function me(e, s) {
-  const r = (h) => {
-    const c = h.detail;
-    c && s({
+function be(r, f) {
+  const n = (p) => {
+    const c = p.detail;
+    c && f({
       percentage: c.percentage,
       currentElement: c.currentElement,
       scrollOffset: c.scrollOffset,
       result: { element: c.result.element, offset: c.result.offset }
     });
-  }, f = (h) => {
-    const c = h.detail;
-    c && s({
+  }, a = (p) => {
+    const c = p.detail;
+    c && f({
       percentage: c.percentage,
       currentElement: c.element,
       scrollOffset: c.scrollOffset,
       result: { element: c.element, offset: c.scrollOffset }
     });
   };
-  return e.addEventListener("cerious-viewport-change", r), e.addEventListener("viewport-change", f), () => {
-    e.removeEventListener("cerious-viewport-change", r), e.removeEventListener("viewport-change", f);
+  return r.addEventListener("cerious-viewport-change", n), r.addEventListener("viewport-change", a), () => {
+    r.removeEventListener("cerious-viewport-change", n), r.removeEventListener("viewport-change", a);
   };
 }
-function de(e, s) {
-  const r = typeof e == "number" ? e : typeof s == "number" ? s : void 0;
-  if (r === void 0 || Number.isNaN(r))
+function le(r, f) {
+  const n = typeof r == "number" ? r : typeof f == "number" ? f : void 0;
+  if (n === void 0 || Number.isNaN(n))
     throw new Error("useCeriousScroll: provide `totalElements` or `items`.");
-  return Math.max(1, Math.floor(r));
+  return Math.max(1, Math.floor(n));
 }
-function he(e) {
-  var X;
-  const s = o(null), r = o(null), f = o(/* @__PURE__ */ new Map()), h = o(/* @__PURE__ */ new Map()), c = o(null), g = o(null), C = o(null), M = o(e.tableHeader), [, A] = te((t) => t + 1, 0), [H, S] = re(null), v = o(e.renderItem), E = o(e.items ?? null), R = o(e.getItem), _ = o(e.options), F = o(e.autoRender ?? !0), $ = o(e.totalElements ?? null), L = o(e.onViewportChange), N = o(e.onMeasuredViewport), P = o(e.onReady);
-  v.current = e.renderItem, E.current = e.items ?? null, R.current = e.getItem, M.current = e.tableHeader, _.current = e.options, F.current = e.autoRender ?? !0, $.current = e.totalElements ?? null, L.current = e.onViewportChange, N.current = e.onMeasuredViewport, P.current = e.onReady;
-  const B = w((t) => {
-    const n = R.current;
-    if (n) return n(t);
-    const l = E.current;
-    return l ? l[t] : void 0;
-  }, []), u = w(() => {
-    var T, O;
-    const t = r.current;
-    if (!t) return null;
-    const { scroller: n, contentEl: l, container: a } = t, j = a.clientHeight || a.offsetHeight || 0, y = [], m = ((T = _.current) == null ? void 0 : T.layout) === "table", z = (i, d) => {
-      const b = document.createElement("div");
-      m && (b.style.display = "contents"), b.setAttribute(ie, String(i)), b.innerHTML = ue(
-        ne(ce, null, v.current(B(i), i))
-      ), d.appendChild(b), f.current.set(i, { el: d, mount: b }), y.push(b);
-    }, I = n.renderViewport(j, l, z), V = new Set(n.getRenderedIndices());
-    return f.current.forEach((i, d) => {
-      V.has(d) || f.current.delete(d);
-    }), y.forEach((i) => {
-      i.textContent = "";
-    }), se(A), (O = N.current) == null || O.call(N, I), I;
-  }, []), K = e.totalElements ?? ((X = e.items) == null ? void 0 : X.length) ?? null;
-  Y(() => {
-    var V, T, O;
-    const t = s.current;
-    if (!t) return;
-    const n = fe(t), l = _.current ?? {}, a = l.onScroll, j = {
-      ...l,
+function ve(r) {
+  var x;
+  const f = u(null), n = u(null), a = u(/* @__PURE__ */ new Map()), p = u(/* @__PURE__ */ new Map()), c = u(null), v = u(null), I = u(null), F = u(r.tableHeader), [, L] = ee((e) => e + 1, 0), [q, T] = de(null), [N, P] = ee((e) => e + 1, 0), S = u(r.renderItem), y = u(r.items ?? null), D = u(r.getItem), R = u(r.options), M = u(r.autoRender ?? !0), W = u(r.totalElements ?? null), V = u(r.onViewportChange), $ = u(r.onMeasuredViewport), k = u(r.onReady);
+  S.current = r.renderItem, y.current = r.items ?? null, D.current = r.getItem, F.current = r.tableHeader, R.current = r.options, M.current = r.autoRender ?? !0, W.current = r.totalElements ?? null, V.current = r.onViewportChange, $.current = r.onMeasuredViewport, k.current = r.onReady;
+  const z = b((e) => {
+    const t = D.current;
+    if (t) return t(e);
+    const l = y.current;
+    return l ? l[e] : void 0;
+  }, []), K = b((e, t) => {
+    const l = z(e);
+    if (t.dataset.ceriousMasonry === "probe") {
+      const m = document.createElement("div");
+      m.setAttribute(B, String(e)), m.innerHTML = oe(
+        te(re, null, S.current(l, e))
+      ), t.appendChild(m);
+      return;
+    }
+    let o = t.querySelector(`[${B}]`);
+    o || (o = document.createElement("div"), t.appendChild(o)), o.setAttribute(B, String(e)), a.current.forEach((m, E) => {
+      m.el === t && E !== e && a.current.delete(E);
+    }), a.current.set(e, { el: t, mount: o });
+  }, [z]), s = b(() => {
+    var A, H, j;
+    const e = n.current;
+    if (!e) return null;
+    const { scroller: t, contentEl: l, container: o } = e, m = o.clientHeight || o.offsetHeight || 0, E = [], O = ((A = R.current) == null ? void 0 : A.layout) === "table", w = ((H = R.current) == null ? void 0 : H.layout) === "masonry", _ = (h, i) => {
+      const g = document.createElement("div");
+      O && (g.style.display = "contents"), g.setAttribute(B, String(h)), g.innerHTML = oe(
+        te(re, null, S.current(z(h), h))
+      ), i.appendChild(g), a.current.set(h, { el: i, mount: g }), E.push(g);
+    }, d = t.renderViewport(m, l, _), G = w ? null : new Set(t.getRenderedIndices());
+    return a.current.forEach((h, i) => {
+      w ? (!h.el.isConnected || h.el.dataset.elementIndex !== String(i)) && a.current.delete(i) : G.has(i) || a.current.delete(i);
+    }), E.forEach((h) => {
+      h.textContent = "";
+    }), Ee(L), (j = $.current) == null || j.call($, d), d;
+  }, []), Q = r.totalElements ?? ((x = r.items) == null ? void 0 : x.length) ?? null;
+  J(() => {
+    var H, j, h;
+    const e = f.current;
+    if (!e) return;
+    const t = R.current ?? {}, l = t.layout === "masonry", o = l ? e : ye(e), m = t.onScroll, { masonry: E, ...O } = t, w = {
+      ...O,
       onScroll: () => {
-        a == null || a(), F.current && u();
+        m == null || m(), M.current && s();
       }
     };
-    if (l.layout === "table" && M.current != null) {
-      const i = (V = l.table) == null ? void 0 : V.header;
-      j.table = {
-        ...l.table,
-        header: (d) => {
-          C.current = d, i == null || i(d);
+    if (l) {
+      if (!E)
+        throw new Error("useCeriousScroll: layout 'masonry' requires `options.masonry`.");
+      w.masonry = {
+        ...E,
+        renderItem: K
+      };
+    }
+    if (t.layout === "table" && F.current != null) {
+      const i = (H = t.table) == null ? void 0 : H.header;
+      w.table = {
+        ...t.table,
+        header: (g) => {
+          I.current = g, i == null || i(g);
         }
       };
     }
-    const y = de($.current, ((T = E.current) == null ? void 0 : T.length) ?? null), m = new ae(t, y, j);
-    g.current && (m.currentElement = Math.min(g.current.currentElement, y - 1), m.scrollOffset = g.current.scrollOffset, g.current = null), r.current = { scroller: m, contentEl: n, container: t }, S(m);
-    const z = me(t, (i) => {
-      var d;
-      (d = L.current) == null || d.call(L, i);
+    const _ = le(W.current, ((j = y.current) == null ? void 0 : j.length) ?? null), d = new pe(e, _, w);
+    v.current && (d.currentElement = Math.min(v.current.currentElement, _ - 1), d.scrollOffset = v.current.scrollOffset, v.current = null), n.current = { scroller: d, contentEl: o, container: e }, T(d);
+    const G = be(e, (i) => {
+      var g;
+      (g = V.current) == null || g.call(V, i);
     });
-    (O = P.current) == null || O.call(P, m);
-    let I = 0;
-    return F.current && (I = requestAnimationFrame(() => u())), () => {
-      cancelAnimationFrame(I), z(), g.current = {
-        currentElement: m.currentElement,
-        scrollOffset: m.scrollOffset
-      }, f.current.clear(), h.current.clear(), c.current = null, n.textContent = "", m.detachScrollbar(t), m.dispose(), r.current = null, S(null);
+    (h = k.current) == null || h.call(k, d);
+    let A = 0;
+    return M.current && (A = requestAnimationFrame(() => s())), () => {
+      var i;
+      cancelAnimationFrame(A), G(), v.current = ((i = R.current) == null ? void 0 : i.layout) === "masonry" ? null : { currentElement: d.currentElement, scrollOffset: d.scrollOffset }, a.current.clear(), p.current.clear(), c.current = null, d.detachScrollbar(e), d.dispose(), o.textContent = "", n.current = null, T(null);
     };
-  }, [K, u]), Y(() => {
-    if (!r.current || !F.current) return;
-    const t = requestAnimationFrame(() => u());
-    return () => cancelAnimationFrame(t);
-  }, [e.items, e.getItem]);
-  const Q = w(
-    (t) => {
-      const n = r.current;
-      return n ? (n.scroller.jumpToElement(t), u()) : null;
+  }, [s, K, N]), J(() => {
+    var m, E;
+    const e = n.current;
+    if (!e || Q == null) return;
+    const t = le(W.current, ((m = y.current) == null ? void 0 : m.length) ?? null), l = ((E = R.current) == null ? void 0 : E.layout) === "masonry", o = l ? e.scroller.itemCount : e.scroller.totalElements;
+    if (t !== o) {
+      if (l) {
+        P();
+        return;
+      }
+      if (e.scroller.updateTotalElements(t), e.scroller.currentElement > t - 1 && e.scroller.jumpToElement(t - 1), M.current) {
+        const O = e.scroller;
+        requestAnimationFrame(() => {
+          s(), O.syncScrollbar();
+        });
+      } else
+        e.scroller.syncScrollbar();
+    }
+  }, [Q, s]), J(() => {
+    if (!n.current || !M.current) return;
+    const e = requestAnimationFrame(() => s());
+    return () => cancelAnimationFrame(e);
+  }, [r.items, r.getItem]);
+  const se = b(
+    (e) => {
+      const t = n.current;
+      return t ? (t.scroller.jumpToElement(e), s()) : null;
+    },
+    [s]
+  ), ue = b(
+    (e, t = 0) => {
+      const l = n.current;
+      return l ? (l.scroller.jumpToItem(e, t), s()) : null;
     },
-    [u]
-  ), U = w(
-    (t) => {
-      const n = r.current;
-      return n ? (n.scroller.handleScrollPercentage(t), u()) : null;
+    [s]
+  ), ae = b(
+    (e) => {
+      const t = n.current;
+      return t ? (t.scroller.handleScrollPercentage(e), s()) : null;
     },
-    [u]
-  ), Z = w(() => {
-    const t = r.current;
-    return t ? (t.scroller.reset(), u()) : null;
-  }, [u]), x = w(() => {
-    const t = r.current;
-    return t ? (t.scroller.clearAllCaches(), h.current.clear(), u()) : null;
-  }, [u]), D = E.current, W = !R.current && D != null ? D.length : null, q = v.current, p = h.current;
-  c.current !== q && (p.clear(), c.current = q);
-  const k = [];
-  return f.current.forEach((t, n) => {
-    if (W !== null && n >= W) {
-      p.delete(n);
+    [s]
+  ), ie = b(() => {
+    const e = n.current;
+    return e ? (e.scroller.reset(), s()) : null;
+  }, [s]), me = b(() => {
+    const e = n.current;
+    return e ? (e.scroller.clearAllCaches(), p.current.clear(), s()) : null;
+  }, [s]), U = y.current, Z = !D.current && U != null ? U.length : null, X = S.current, C = p.current;
+  c.current !== X && (C.clear(), c.current = X);
+  const Y = [];
+  return a.current.forEach((e, t) => {
+    if (Z !== null && t >= Z) {
+      C.delete(t);
       return;
     }
-    const l = B(n);
-    let a = p.get(n);
-    (!a || a.item !== l || a.mount !== t.mount) && (a = {
+    const l = z(t);
+    let o = C.get(t);
+    (!o || o.item !== l || o.mount !== e.mount) && (o = {
       item: l,
-      mount: t.mount,
-      node: G(q(l, n), t.mount, String(n))
-    }, p.set(n, a)), k.push(a.node);
-  }), p.size > f.current.size && p.forEach((t, n) => {
-    f.current.has(n) || p.delete(n);
-  }), e.tableHeader != null && C.current && k.push(G(e.tableHeader, C.current, "cerious-thead")), {
-    containerRef: s,
-    portals: k,
-    scroller: H,
-    render: u,
-    jumpToElement: Q,
-    scrollToPercentage: U,
-    reset: Z,
-    recalculate: x
+      mount: e.mount,
+      node: ne(X(l, t), e.mount, String(t))
+    }, C.set(t, o)), Y.push(o.node);
+  }), C.size > a.current.size && C.forEach((e, t) => {
+    a.current.has(t) || C.delete(t);
+  }), r.tableHeader != null && I.current && Y.push(ne(r.tableHeader, I.current, "cerious-thead")), {
+    containerRef: f,
+    portals: Y,
+    scroller: q,
+    render: s,
+    jumpToElement: se,
+    jumpToItem: ue,
+    scrollToPercentage: ae,
+    reset: ie,
+    recalculate: me
   };
 }
-function ge(e, s) {
-  const { className: r, style: f, "data-testid": h, children: c, ...g } = e, {
-    containerRef: C,
-    portals: M,
-    scroller: A,
-    render: H,
-    jumpToElement: S,
-    scrollToPercentage: v,
-    reset: E,
-    recalculate: R
-  } = he(g);
-  return le(
-    s,
-    () => ({ scroller: A, render: H, jumpToElement: S, scrollToPercentage: v, reset: E, recalculate: R }),
-    [A, H, S, v, E, R]
-  ), /* @__PURE__ */ ee(
+function Se(r, f) {
+  const { className: n, style: a, "data-testid": p, children: c, ...v } = r, {
+    containerRef: I,
+    portals: F,
+    scroller: L,
+    render: q,
+    jumpToElement: T,
+    jumpToItem: N,
+    scrollToPercentage: P,
+    reset: S,
+    recalculate: y
+  } = ve(v);
+  return ge(
+    f,
+    () => ({ scroller: L, render: q, jumpToElement: T, jumpToItem: N, scrollToPercentage: P, reset: S, recalculate: y }),
+    [L, q, T, N, P, S, y]
+  ), /* @__PURE__ */ fe(
     "div",
     {
-      ref: C,
-      className: r,
-      "data-testid": h,
-      style: { position: "relative", overflow: "hidden", ...f },
+      ref: I,
+      className: n,
+      "data-testid": p,
+      style: { position: "relative", overflow: "hidden", ...a },
       children: [
         c,
-        M
+        F
       ]
     }
   );
 }
-const we = oe(ge);
+const Me = he(Se);
 export {
-  we as CeriousScroll,
-  ye as CeriousScrollEngine,
-  he as useCeriousScroll
+  Me as CeriousScroll,
+  He as CeriousScrollEngine,
+  ve as useCeriousScroll
 };

package/dist/use-cerious-scroll.d.ts

@@ -1,6 +1,13 @@
 import { ReactNode, RefObject } from 'react';
-import { CeriousScroll as CeriousScrollEngine, CeriousScrollOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { CeriousScroll as CeriousScrollEngine, CeriousScrollOptions as CoreCeriousScrollOptions, MasonryOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
 import { CeriousViewportChangeDetail } from './viewport-change';
+/** Engine options adapted for React-owned Masonry rendering. */
+export type CeriousScrollOptions = Omit<CoreCeriousScrollOptions, 'masonry'> & {
+    masonry?: Omit<MasonryOptions, 'renderItem'> & {
+        /** Accepted for backward compatibility; React supplies the active renderer. */
+        renderItem?: MasonryOptions['renderItem'];
+    };
+};
 export interface UseCeriousScrollOptions<TItem = unknown> {
     /** Total number of items. Falls back to `items.length` when omitted. */
     totalElements?: number | null;
@@ -38,6 +45,8 @@ export interface UseCeriousScrollResult {
     render: () => MeasuredViewportRange | null;
     /** Jump to an element index, then render. */
     jumpToElement: (index: number) => MeasuredViewportRange | null;
+    /** Masonry mode only: jump to a card index, then render. */
+    jumpToItem: (index: number, screenOffset?: number) => MeasuredViewportRange | null;
     /** Scroll to a percentage (0..100), then render. */
     scrollToPercentage: (percentage: number) => MeasuredViewportRange | null;
     /** Reset to the top, then render. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ceriousdevtech/react-cerious-scroll",
-  "version": "1.0.6",
-  "description": "React bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
+  "version": "1.1.0",
+  "description": "React bindings for CeriousScroll — virtualized lists, native tables, and Masonry grids",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -44,6 +44,7 @@
     "large-lists",
     "data-grid",
     "variable-height",
+    "masonry",
     "o1-memory",
     "cerious-scroll"
   ],
@@ -56,7 +57,7 @@
     "demo:build": "vite build --config demo/vite.config.ts"
   },
   "dependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.7"
+    "@ceriousdevtech/cerious-scroll": "^1.1.0"
   },
   "peerDependencies": {
     "react": ">=18 <20",