@ceriousdevtech/vue-cerious-scroll 1.0.7 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to vue-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.1] - 2026-08-23
+
+### Added
+- Masonry real-content demo: network images, composed Vue card components, and a per-card carousel over 50,000 items. Demonstrates the three constraints recycled cards impose — media space reserved from intrinsic dimensions, card height enforced rather than estimated, and per-card UI state held outside component state and keyed by card index so it survives a card leaving the window.
+- Demo image handling shows the practices that matter with virtualization: no `loading="lazy"` (the window is already the lazy loader), an instant placeholder colour behind each reserved box, a bounded low-priority prefetch window, and bucketed request widths so a resizing CDN can cache them.
+
+### Changed
+- Updated `@ceriousdevtech/cerious-scroll` to `^1.1.1`.
+
+## [1.1.0] - 2026-08-22
+
+### Added
+- Declarative canonical and dynamic Masonry support through the existing `#item` slot or `render-item` prop.
+- Dynamic-height probe rendering with short-lived Vue trees that are disposed after synchronous measurement.
+- `jumpToItem(index, screenOffset?)` on the composable result and exposed component API.
+- `CeriousScrollOptions` support for wrapper-owned Masonry rendering, canonical/dynamic demo routes, and regression coverage for both modes.
+
+### 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
 
 ### Fixed

package/README.md

@@ -109,7 +109,7 @@ const { containerRef } = useCeriousScroll({
 | `totalElements` | `number` | Total item count. Required if `items` is omitted. |
 | `getItem` | `(index) => TItem` | Lazy item getter for large/sparse datasets. |
 | `renderItem` | `(item, index) => VNodeChild` | Render prop alternative to the `#item` scoped slot. |
-| `options` | `CeriousScrollOptions` | Engine options (keyboard/touch/wheel/scrollbar/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`. |
 
 The row is provided by the **`#item` scoped slot** (`{ item, index }`) or the
@@ -130,6 +130,7 @@ component — they fall through onto the scroll container (set a height!).
 ```ts
 const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
 // scroll.value?.jumpToElement(500);
+// scroll.value?.jumpToItem(500); // Masonry cards
 // scroll.value?.scrollToPercentage(50);
 // scroll.value?.reset();
 // scroll.value?.render();
@@ -139,6 +140,40 @@ const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
 
 ---
 
+## Masonry layout
+
+Set `layout: 'masonry'`; the wrapper renders the `#item` slot into each core
+Masonry card, so no imperative DOM callback is exposed:
+
+```vue
+<CeriousScroll
+  ref="scroll"
+  class="gallery"
+  :total-elements="photos.length"
+  :get-item="(index) => photos[index]"
+  :options="{
+    layout: 'masonry',
+    masonry: {
+      getItemHeight: (_index, width) => width * 0.75 + 48,
+      targetColumnWidth: 280,
+      gap: 16
+    }
+  }"
+>
+  <template #item="{ item: photo, index }">
+    <PhotoCard :photo="photo" :index="index" />
+  </template>
+</CeriousScroll>
+```
+
+Omit `getItemHeight` for dynamic DOM measurement. Vue creates a short-lived
+offscreen render tree for measurement and disposes it after the synchronous
+height read; visible cards remain reactive Vue trees with provide/inject and
+event handling.
+
+Use `scroll.value?.jumpToItem(index, screenOffset?)` for card navigation. The
+demo gallery includes 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. The `#item` slot returns the row's `<td>` cells; a `#header` slot provides the (declarative, reactive) `<thead>` row:
@@ -176,8 +211,8 @@ Pass `:options="{ layout: 'table' }"` to render real `<table>` / `<tr>` / `<td>`
   the engine's 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 in place (cheap; Vue patches each row, so focus/selection survive) — 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

@@ -1,5 +1,6 @@
 import { PropType, VNodeChild } from 'vue';
-import { CeriousScrollOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { CeriousScrollOptions } from './use-cerious-scroll';
 import { CeriousViewportChangeDetail } from './viewport-change';
 /**
  * High-performance virtual scroll list. Provide `items` (or `total-elements` +
@@ -93,10 +94,10 @@ export declare const CeriousScroll: import('vue').DefineComponent<import('vue').
     "onMeasured-viewport"?: ((_range: MeasuredViewportRange) => any) | undefined;
     onReady?: ((_scroller: unknown) => any) | undefined;
 }>, {
+    renderItem: (item: unknown, index: number) => VNodeChild;
     totalElements: number | null;
     items: readonly unknown[] | null;
     getItem: (index: number) => unknown;
-    renderItem: (item: unknown, index: number) => VNodeChild;
     options: CeriousScrollOptions;
     autoRender: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("vue"),j=require("@ceriousdevtech/cerious-scroll"),A="data-cerious-scroll-content",_="data-cerious-scroll-row";function q(e){const l=e.querySelector(`[${A}]`);if(l)return l;const c=document.createElement("div");return c.setAttribute(A,""),c.style.position="relative",c.style.width="100%",c.style.height="100%",c.style.overflowY="clip",c.style.overflowX="auto",e.appendChild(c),c}function L(e,l){const c=m=>{const o=m.detail;o&&l({percentage:o.percentage,currentElement:o.currentElement,scrollOffset:o.scrollOffset,result:{element:o.result.element,offset:o.result.offset}})},y=m=>{const o=m.detail;o&&l({percentage:o.percentage,currentElement:o.element,scrollOffset:o.scrollOffset,result:{element:o.element,offset:o.scrollOffset}})};return e.addEventListener("cerious-viewport-change",c),e.addEventListener("viewport-change",y),()=>{e.removeEventListener("cerious-viewport-change",c),e.removeEventListener("viewport-change",y)}}function O(e,l){const c=typeof e=="number"?e:typeof l=="number"?l: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 P(e){var I;const l=n.getCurrentInstance(),c=l==null?void 0:l.provides,y=l?{...l.appContext,provides:c??l.appContext.provides}:void 0,m=n.ref(null),o=n.shallowRef(null);let t=null;const v=new Map,S=((I=e.options)==null?void 0:I.layout)==="table";let g=null;const M=r=>{if(!e.renderHeader)return;g==null||g();const u=y??null,s=n.effectScope(!0);s.run(()=>n.watchEffect(()=>{const i=e.renderHeader(),a=Array.isArray(i)?i:[i];for(const d of a)n.isVNode(d)&&(d.appContext=u);const f=n.h(n.Fragment,a);f.appContext=u,n.render(f,r)},{flush:"sync"})),g=()=>s.stop()},R=()=>n.toValue(e.autoRender)??!0,N=r=>{if(e.getItem)return e.getItem(r);const u=n.toValue(e.items);return u?u[r]:void 0},x=(r,u)=>{const s=y??null,i=n.effectScope(!0);return i.run(()=>n.watchEffect(()=>{const a=e.renderItem(N(r),r),f=Array.isArray(a)?a:[a];for(const C of f)n.isVNode(C)&&(C.appContext=s);const d=n.h(n.Fragment,f);d.appContext=s,n.render(d,u)},{flush:"sync"})),()=>i.stop()},V=r=>{r.stop(),n.render(null,r.mount),r.mount.remove()},h=()=>{var C;if(!t)return null;const{scroller:r,contentEl:u,container:s}=t,i=s.clientHeight||s.offsetHeight||0,a=(p,E)=>{const w=document.createElement("div");S&&(w.style.display="contents"),w.setAttribute(_,String(p)),E.appendChild(w);const b=x(p,w);v.set(p,{el:E,mount:w,stop:b})},f=r.renderViewport(i,u,a),d=new Set(r.getRenderedIndices());return v.forEach((p,E)=>{d.has(E)||(V(p),v.delete(E))}),(C=e.onMeasuredViewport)==null||C.call(e,f),f},H=r=>{if(!t)return;const u=t;t=null,u.unsubscribe(),v.forEach(s=>V(s)),v.clear(),g==null||g(),g=null,u.contentEl.textContent="",u.scroller.detachScrollbar(u.container),u.scroller.dispose(),o.value=null},F=r=>{var p,E,w;const u=q(r),s=e.options??{},i=s.onScroll,a={...s,onScroll:()=>{i==null||i(),R()&&h()}};if(S&&e.renderHeader){const b=(p=s.table)==null?void 0:p.header;a.table={...s.table,header:T=>{b==null||b(T),M(T)}}}const f=O(n.toValue(e.totalElements),((E=n.toValue(e.items))==null?void 0:E.length)??null),d=new j.CeriousScroll(r,f,a),C=L(r,b=>{var T;(T=e.onViewportChange)==null||T.call(e,b)});t={scroller:d,contentEl:u,container:r,unsubscribe:C},o.value=d,(w=e.onReady)==null||w.call(e,d),R()&&requestAnimationFrame(()=>h())};return n.onMounted(()=>{const r=m.value;r&&F(r)}),n.onBeforeUnmount(()=>{H()}),n.watch(()=>[n.toValue(e.totalElements),n.toValue(e.items)],()=>{var u;if(!t)return;const r=O(n.toValue(e.totalElements),((u=n.toValue(e.items))==null?void 0:u.length)??null);t.scroller.totalElements!==r&&(t.scroller.updateTotalElements(r),t.scroller.currentElement>r-1&&t.scroller.jumpToElement(r-1),R()&&h(),t.scroller.syncScrollbar())}),{containerRef:m,scroller:o,render:h,jumpToElement:r=>t?(t.scroller.jumpToElement(r),h()):null,scrollToPercentage:r=>t?(t.scroller.handleScrollPercentage(r),h()):null,reset:()=>t?(t.scroller.reset(),h()):null,recalculate:()=>t?(t.scroller.clearAllCaches(),h()):null}}const B=n.defineComponent({name:"CeriousScroll",props:{totalElements:{type:Number,default:null},items:{type:Array,default:null},getItem:{type:Function,default:void 0},renderItem:{type:Function,default:void 0},options:{type:Object,default:void 0},autoRender:{type:Boolean,default:!0}},emits:{"viewport-change":e=>!0,"measured-viewport":e=>!0,ready:e=>!0},setup(e,{slots:l,emit:c,expose:y}){const m=(t,v)=>{var S;return e.renderItem?e.renderItem(t,v):(S=l.item)==null?void 0:S.call(l,{item:t,index:v})},o=P({totalElements:()=>e.totalElements,items:()=>e.items,getItem:e.getItem?t=>e.getItem(t):void 0,renderItem:m,renderHeader:l.header?()=>l.header():void 0,options:e.options,autoRender:()=>e.autoRender,onViewportChange:t=>c("viewport-change",t),onMeasuredViewport:t=>c("measured-viewport",t),onReady:t=>c("ready",t)});return y({scroller:o.scroller,render:o.render,jumpToElement:o.jumpToElement,scrollToPercentage:o.scrollToPercentage,reset:o.reset,recalculate:o.recalculate}),()=>{var t;return n.h("div",{ref:o.containerRef,style:{position:"relative",overflow:"hidden"}},(t=l.default)==null?void 0:t.call(l))}}});Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>j.CeriousScroll});exports.CeriousScroll=B;exports.useCeriousScroll=P;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("vue"),L=require("@ceriousdevtech/cerious-scroll"),F="data-cerious-scroll-content",A="data-cerious-scroll-row";function X(e){const s=e.querySelector(`[${F}]`);if(s)return s;const u=document.createElement("div");return u.setAttribute(F,""),u.style.position="relative",u.style.width="100%",u.style.height="100%",u.style.overflowY="clip",u.style.overflowX="auto",e.appendChild(u),u}function Y(e,s){const u=p=>{const l=p.detail;l&&s({percentage:l.percentage,currentElement:l.currentElement,scrollOffset:l.scrollOffset,result:{element:l.result.element,offset:l.result.offset}})},w=p=>{const l=p.detail;l&&s({percentage:l.percentage,currentElement:l.element,scrollOffset:l.scrollOffset,result:{element:l.element,offset:l.scrollOffset}})};return e.addEventListener("cerious-viewport-change",u),e.addEventListener("viewport-change",w),()=>{e.removeEventListener("cerious-viewport-change",u),e.removeEventListener("viewport-change",w)}}function _(e,s){const u=typeof e=="number"?e:typeof s=="number"?s:void 0;if(u===void 0||Number.isNaN(u))throw new Error("useCeriousScroll: provide `totalElements` or `items`.");return Math.max(1,Math.floor(u))}function B(e){var N,q;const s=n.getCurrentInstance(),u=s==null?void 0:s.provides,w=s?{...s.appContext,provides:u??s.appContext.provides}:void 0,p=n.ref(null),l=n.shallowRef(null);let r=null;const f=new Map,T=((N=e.options)==null?void 0:N.layout)==="table",b=((q=e.options)==null?void 0:q.layout)==="masonry";let y=null;const $=t=>{if(!e.renderHeader)return;y==null||y();const o=w??null,c=n.effectScope(!0);c.run(()=>n.watchEffect(()=>{const a=e.renderHeader(),m=Array.isArray(a)?a:[a];for(const d of m)n.isVNode(d)&&(d.appContext=o);const i=n.h(n.Fragment,m);i.appContext=o,n.render(i,t)},{flush:"sync"})),y=()=>c.stop()},V=()=>n.toValue(e.autoRender)??!0,U=t=>{if(e.getItem)return e.getItem(t);const o=n.toValue(e.items);return o?o[t]:void 0},j=(t,o)=>{const c=w??null,a=n.effectScope(!0);return a.run(()=>n.watchEffect(()=>{const m=e.renderItem(U(t),t),i=Array.isArray(m)?m:[m];for(const C of i)n.isVNode(C)&&(C.appContext=c);const d=n.h(n.Fragment,i);d.appContext=c,n.render(d,o)},{flush:"sync"})),()=>a.stop()},M=t=>{t.stop(),n.render(null,t.mount),t.mount.remove()},W=(t,o)=>{let c=o.querySelector(`[${A}]`);if(c||(c=document.createElement("div"),o.appendChild(c)),c.setAttribute(A,String(t)),o.dataset.ceriousMasonry==="probe"){const i=j(t,c);queueMicrotask(()=>{i(),n.render(null,c)});return}f.forEach((i,d)=>{i.el===o&&d!==t&&(i.stop(),f.delete(d))});const a=f.get(t);if((a==null?void 0:a.mount)===c)return;const m=j(t,c);f.set(t,{el:o,mount:c,stop:m})},v=()=>{var C;if(!r)return null;const{scroller:t,contentEl:o,container:c}=r,a=c.clientHeight||c.offsetHeight||0,m=(h,E)=>{const g=document.createElement("div");T&&(g.style.display="contents"),g.setAttribute(A,String(h)),E.appendChild(g);const R=j(h,g);f.set(h,{el:E,mount:g,stop:R})},i=t.renderViewport(a,o,m),d=b?null:new Set(t.getRenderedIndices());return f.forEach((h,E)=>{(b?!h.el.isConnected||h.el.dataset.elementIndex!==String(E):!d.has(E))&&(M(h),f.delete(E))}),(C=e.onMeasuredViewport)==null||C.call(e,i),i},O=t=>{if(!r)return;const o=r;r=null,o.unsubscribe(),f.forEach(c=>M(c)),f.clear(),y==null||y(),y=null,o.scroller.detachScrollbar(o.container),o.scroller.dispose(),o.contentEl.textContent="",l.value=null},P=t=>{var g,R,H;const o=e.options??{},c=b?t:X(t),a=o.onScroll,{masonry:m,...i}=o,d={...i,onScroll:()=>{a==null||a(),V()&&v()}};if(b){if(!m)throw new Error("useCeriousScroll: layout 'masonry' requires `options.masonry`.");d.masonry={...m,renderItem:W}}if(T&&e.renderHeader){const S=(g=o.table)==null?void 0:g.header;d.table={...o.table,header:I=>{S==null||S(I),$(I)}}}const C=_(n.toValue(e.totalElements),((R=n.toValue(e.items))==null?void 0:R.length)??null),h=new L.CeriousScroll(t,C,d),E=Y(t,S=>{var I;(I=e.onViewportChange)==null||I.call(e,S)});r={scroller:h,contentEl:c,container:t,unsubscribe:E},l.value=h,(H=e.onReady)==null||H.call(e,h),V()&&requestAnimationFrame(()=>v())};return n.onMounted(()=>{const t=p.value;t&&P(t)}),n.onBeforeUnmount(()=>{O()}),n.watch(()=>[n.toValue(e.totalElements),n.toValue(e.items)],()=>{var c;if(!r)return;const t=_(n.toValue(e.totalElements),((c=n.toValue(e.items))==null?void 0:c.length)??null);if((b?r.scroller.itemCount:r.scroller.totalElements)!==t){if(b){const a=p.value;O(),a&&P(a);return}r.scroller.updateTotalElements(t),r.scroller.currentElement>t-1&&r.scroller.jumpToElement(t-1),V()&&v(),r.scroller.syncScrollbar()}}),{containerRef:p,scroller:l,render:v,jumpToElement:t=>r?(r.scroller.jumpToElement(t),v()):null,jumpToItem:(t,o=0)=>r?(r.scroller.jumpToItem(t,o),v()):null,scrollToPercentage:t=>r?(r.scroller.handleScrollPercentage(t),v()):null,reset:()=>r?(r.scroller.reset(),v()):null,recalculate:()=>r?(r.scroller.clearAllCaches(),v()):null}}const k=n.defineComponent({name:"CeriousScroll",props:{totalElements:{type:Number,default:null},items:{type:Array,default:null},getItem:{type:Function,default:void 0},renderItem:{type:Function,default:void 0},options:{type:Object,default:void 0},autoRender:{type:Boolean,default:!0}},emits:{"viewport-change":e=>!0,"measured-viewport":e=>!0,ready:e=>!0},setup(e,{slots:s,emit:u,expose:w}){const p=(r,f)=>{var T;return e.renderItem?e.renderItem(r,f):(T=s.item)==null?void 0:T.call(s,{item:r,index:f})},l=B({totalElements:()=>e.totalElements,items:()=>e.items,getItem:e.getItem?r=>e.getItem(r):void 0,renderItem:p,renderHeader:s.header?()=>s.header():void 0,options:e.options,autoRender:()=>e.autoRender,onViewportChange:r=>u("viewport-change",r),onMeasuredViewport:r=>u("measured-viewport",r),onReady:r=>u("ready",r)});return w({scroller:l.scroller,render:l.render,jumpToElement:l.jumpToElement,jumpToItem:l.jumpToItem,scrollToPercentage:l.scrollToPercentage,reset:l.reset,recalculate:l.recalculate}),()=>{var r;return n.h("div",{ref:l.containerRef,style:{position:"relative",overflow:"hidden"}},(r=s.default)==null?void 0:r.call(s))}}});Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>L.CeriousScroll});exports.CeriousScroll=k;exports.useCeriousScroll=B;

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { CeriousScroll } 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,145 +1,177 @@
-import { getCurrentInstance as B, ref as U, shallowRef as W, onMounted as X, onBeforeUnmount as Y, watch as z, toValue as w, effectScope as V, watchEffect as j, isVNode as M, h as A, Fragment as N, render as S, defineComponent as D } from "vue";
-import { CeriousScroll as G } from "@ceriousdevtech/cerious-scroll";
-import { CeriousScroll as ue } from "@ceriousdevtech/cerious-scroll";
-const P = "data-cerious-scroll-content", J = "data-cerious-scroll-row";
-function K(e) {
-  const o = e.querySelector(`[${P}]`);
-  if (o) return o;
-  const l = document.createElement("div");
-  return l.setAttribute(P, ""), l.style.position = "relative", l.style.width = "100%", l.style.height = "100%", l.style.overflowY = "clip", l.style.overflowX = "auto", e.appendChild(l), l;
+import { getCurrentInstance as z, ref as D, shallowRef as G, onMounted as J, onBeforeUnmount as K, watch as Q, toValue as y, render as A, effectScope as L, watchEffect as $, isVNode as B, h as V, Fragment as x, defineComponent as Z } from "vue";
+import { CeriousScroll as ee } from "@ceriousdevtech/cerious-scroll";
+import { CeriousScroll as pe } from "@ceriousdevtech/cerious-scroll";
+const U = "data-cerious-scroll-content", O = "data-cerious-scroll-row";
+function te(e) {
+  const c = e.querySelector(`[${U}]`);
+  if (c) return c;
+  const s = document.createElement("div");
+  return s.setAttribute(U, ""), s.style.position = "relative", s.style.width = "100%", s.style.height = "100%", s.style.overflowY = "clip", s.style.overflowX = "auto", e.appendChild(s), s;
 }
-function Q(e, o) {
-  const l = (m) => {
-    const n = m.detail;
-    n && o({
-      percentage: n.percentage,
-      currentElement: n.currentElement,
-      scrollOffset: n.scrollOffset,
-      result: { element: n.result.element, offset: n.result.offset }
+function re(e, c) {
+  const s = (p) => {
+    const o = p.detail;
+    o && c({
+      percentage: o.percentage,
+      currentElement: o.currentElement,
+      scrollOffset: o.scrollOffset,
+      result: { element: o.result.element, offset: o.result.offset }
     });
-  }, y = (m) => {
-    const n = m.detail;
-    n && o({
-      percentage: n.percentage,
-      currentElement: n.element,
-      scrollOffset: n.scrollOffset,
-      result: { element: n.element, offset: n.scrollOffset }
+  }, w = (p) => {
+    const o = p.detail;
+    o && c({
+      percentage: o.percentage,
+      currentElement: o.element,
+      scrollOffset: o.scrollOffset,
+      result: { element: o.element, offset: o.scrollOffset }
     });
   };
-  return e.addEventListener("cerious-viewport-change", l), e.addEventListener("viewport-change", y), () => {
-    e.removeEventListener("cerious-viewport-change", l), e.removeEventListener("viewport-change", y);
+  return e.addEventListener("cerious-viewport-change", s), e.addEventListener("viewport-change", w), () => {
+    e.removeEventListener("cerious-viewport-change", s), e.removeEventListener("viewport-change", w);
   };
 }
-function H(e, o) {
-  const l = typeof e == "number" ? e : typeof o == "number" ? o : void 0;
-  if (l === void 0 || Number.isNaN(l))
+function W(e, c) {
+  const s = typeof e == "number" ? e : typeof c == "number" ? c : void 0;
+  if (s === void 0 || Number.isNaN(s))
     throw new Error("useCeriousScroll: provide `totalElements` or `items`.");
-  return Math.max(1, Math.floor(l));
+  return Math.max(1, Math.floor(s));
 }
-function Z(e) {
-  var x;
-  const o = B(), l = o == null ? void 0 : o.provides, y = o ? { ...o.appContext, provides: l ?? o.appContext.provides } : void 0, m = U(null), n = W(null);
-  let t = null;
-  const f = /* @__PURE__ */ new Map(), T = ((x = e.options) == null ? void 0 : x.layout) === "table";
-  let v = null;
-  const _ = (r) => {
+function ne(e) {
+  var q, _;
+  const c = z(), s = c == null ? void 0 : c.provides, w = c ? { ...c.appContext, provides: s ?? c.appContext.provides } : void 0, p = D(null), o = G(null);
+  let r = null;
+  const d = /* @__PURE__ */ new Map(), T = ((q = e.options) == null ? void 0 : q.layout) === "table", b = ((_ = e.options) == null ? void 0 : _.layout) === "masonry";
+  let g = null;
+  const X = (t) => {
     if (!e.renderHeader) return;
-    v == null || v();
-    const c = y ?? null, s = V(!0);
-    s.run(
-      () => j(
+    g == null || g();
+    const n = w ?? null, l = L(!0);
+    l.run(
+      () => $(
         () => {
-          const u = e.renderHeader(), i = Array.isArray(u) ? u : [u];
-          for (const a of i) M(a) && (a.appContext = c);
-          const d = A(N, i);
-          d.appContext = c, S(d, r);
+          const u = e.renderHeader(), m = Array.isArray(u) ? u : [u];
+          for (const i of m) B(i) && (i.appContext = n);
+          const a = V(x, m);
+          a.appContext = n, A(a, t);
         },
         { flush: "sync" }
       )
-    ), v = () => s.stop();
-  }, I = () => w(e.autoRender) ?? !0, F = (r) => {
-    if (e.getItem) return e.getItem(r);
-    const c = w(e.items);
-    return c ? c[r] : void 0;
-  }, L = (r, c) => {
-    const s = y ?? null, u = V(!0);
+    ), g = () => l.stop();
+  }, j = () => y(e.autoRender) ?? !0, Y = (t) => {
+    if (e.getItem) return e.getItem(t);
+    const n = y(e.items);
+    return n ? n[t] : void 0;
+  }, M = (t, n) => {
+    const l = w ?? null, u = L(!0);
     return u.run(
-      () => j(
+      () => $(
         () => {
-          const i = e.renderItem(F(r), r), d = Array.isArray(i) ? i : [i];
-          for (const C of d)
-            M(C) && (C.appContext = s);
-          const a = A(N, d);
-          a.appContext = s, S(a, c);
+          const m = e.renderItem(Y(t), t), a = Array.isArray(m) ? m : [m];
+          for (const C of a)
+            B(C) && (C.appContext = l);
+          const i = V(x, a);
+          i.appContext = l, A(i, n);
         },
         { flush: "sync" }
       )
     ), () => u.stop();
-  }, O = (r) => {
-    r.stop(), S(null, r.mount), r.mount.remove();
-  }, h = () => {
+  }, N = (t) => {
+    t.stop(), A(null, t.mount), t.mount.remove();
+  }, k = (t, n) => {
+    let l = n.querySelector(`[${O}]`);
+    if (l || (l = document.createElement("div"), n.appendChild(l)), l.setAttribute(O, String(t)), n.dataset.ceriousMasonry === "probe") {
+      const a = M(t, l);
+      queueMicrotask(() => {
+        a(), A(null, l);
+      });
+      return;
+    }
+    d.forEach((a, i) => {
+      a.el === n && i !== t && (a.stop(), d.delete(i));
+    });
+    const u = d.get(t);
+    if ((u == null ? void 0 : u.mount) === l) return;
+    const m = M(t, l);
+    d.set(t, { el: n, mount: l, stop: m });
+  }, v = () => {
     var C;
-    if (!t) return null;
-    const { scroller: r, contentEl: c, container: s } = t, u = s.clientHeight || s.offsetHeight || 0, i = (g, p) => {
-      const E = document.createElement("div");
-      T && (E.style.display = "contents"), E.setAttribute(J, String(g)), p.appendChild(E);
-      const b = L(g, E);
-      f.set(g, { el: p, mount: E, stop: b });
-    }, d = r.renderViewport(u, c, i), a = new Set(r.getRenderedIndices());
-    return f.forEach((g, p) => {
-      a.has(p) || (O(g), f.delete(p));
-    }), (C = e.onMeasuredViewport) == null || C.call(e, d), d;
-  }, $ = (r) => {
-    if (!t) return;
-    const c = t;
-    t = null, c.unsubscribe(), f.forEach((s) => O(s)), f.clear(), v == null || v(), v = null, c.contentEl.textContent = "", c.scroller.detachScrollbar(c.container), c.scroller.dispose(), n.value = null;
-  }, q = (r) => {
-    var g, p, E;
-    const c = K(r), s = e.options ?? {}, u = s.onScroll, i = {
-      ...s,
+    if (!r) return null;
+    const { scroller: t, contentEl: n, container: l } = r, u = l.clientHeight || l.offsetHeight || 0, m = (f, E) => {
+      const h = document.createElement("div");
+      T && (h.style.display = "contents"), h.setAttribute(O, String(f)), E.appendChild(h);
+      const R = M(f, h);
+      d.set(f, { el: E, mount: h, stop: R });
+    }, a = t.renderViewport(u, n, m), i = b ? null : new Set(t.getRenderedIndices());
+    return d.forEach((f, E) => {
+      (b ? !f.el.isConnected || f.el.dataset.elementIndex !== String(E) : !i.has(E)) && (N(f), d.delete(E));
+    }), (C = e.onMeasuredViewport) == null || C.call(e, a), a;
+  }, P = (t) => {
+    if (!r) return;
+    const n = r;
+    r = null, n.unsubscribe(), d.forEach((l) => N(l)), d.clear(), g == null || g(), g = null, n.scroller.detachScrollbar(n.container), n.scroller.dispose(), n.contentEl.textContent = "", o.value = null;
+  }, H = (t) => {
+    var h, R, F;
+    const n = e.options ?? {}, l = b ? t : te(t), u = n.onScroll, { masonry: m, ...a } = n, i = {
+      ...a,
       onScroll: () => {
-        u == null || u(), I() && h();
+        u == null || u(), j() && v();
       }
     };
+    if (b) {
+      if (!m)
+        throw new Error("useCeriousScroll: layout 'masonry' requires `options.masonry`.");
+      i.masonry = {
+        ...m,
+        renderItem: k
+      };
+    }
     if (T && e.renderHeader) {
-      const b = (g = s.table) == null ? void 0 : g.header;
+      const I = (h = n.table) == null ? void 0 : h.header;
       i.table = {
-        ...s.table,
-        header: (R) => {
-          b == null || b(R), _(R);
+        ...n.table,
+        header: (S) => {
+          I == null || I(S), X(S);
         }
       };
     }
-    const d = H(w(e.totalElements), ((p = w(e.items)) == null ? void 0 : p.length) ?? null), a = new G(r, d, i), C = Q(r, (b) => {
-      var R;
-      (R = e.onViewportChange) == null || R.call(e, b);
+    const C = W(y(e.totalElements), ((R = y(e.items)) == null ? void 0 : R.length) ?? null), f = new ee(t, C, i), E = re(t, (I) => {
+      var S;
+      (S = e.onViewportChange) == null || S.call(e, I);
     });
-    t = { scroller: a, contentEl: c, container: r, unsubscribe: C }, n.value = a, (E = e.onReady) == null || E.call(e, a), I() && requestAnimationFrame(() => h());
+    r = { scroller: f, contentEl: l, container: t, unsubscribe: E }, o.value = f, (F = e.onReady) == null || F.call(e, f), j() && requestAnimationFrame(() => v());
   };
-  return X(() => {
-    const r = m.value;
-    r && q(r);
-  }), Y(() => {
-    $();
-  }), z(
-    () => [w(e.totalElements), w(e.items)],
+  return J(() => {
+    const t = p.value;
+    t && H(t);
+  }), K(() => {
+    P();
+  }), Q(
+    () => [y(e.totalElements), y(e.items)],
     () => {
-      var c;
-      if (!t) return;
-      const r = H(w(e.totalElements), ((c = w(e.items)) == null ? void 0 : c.length) ?? null);
-      t.scroller.totalElements !== r && (t.scroller.updateTotalElements(r), t.scroller.currentElement > r - 1 && t.scroller.jumpToElement(r - 1), I() && h(), t.scroller.syncScrollbar());
+      var l;
+      if (!r) return;
+      const t = W(y(e.totalElements), ((l = y(e.items)) == null ? void 0 : l.length) ?? null);
+      if ((b ? r.scroller.itemCount : r.scroller.totalElements) !== t) {
+        if (b) {
+          const u = p.value;
+          P(), u && H(u);
+          return;
+        }
+        r.scroller.updateTotalElements(t), r.scroller.currentElement > t - 1 && r.scroller.jumpToElement(t - 1), j() && v(), r.scroller.syncScrollbar();
+      }
     }
   ), {
-    containerRef: m,
-    scroller: n,
-    render: h,
-    jumpToElement: (r) => t ? (t.scroller.jumpToElement(r), h()) : null,
-    scrollToPercentage: (r) => t ? (t.scroller.handleScrollPercentage(r), h()) : null,
-    reset: () => t ? (t.scroller.reset(), h()) : null,
-    recalculate: () => t ? (t.scroller.clearAllCaches(), h()) : null
+    containerRef: p,
+    scroller: o,
+    render: v,
+    jumpToElement: (t) => r ? (r.scroller.jumpToElement(t), v()) : null,
+    jumpToItem: (t, n = 0) => r ? (r.scroller.jumpToItem(t, n), v()) : null,
+    scrollToPercentage: (t) => r ? (r.scroller.handleScrollPercentage(t), v()) : null,
+    reset: () => r ? (r.scroller.reset(), v()) : null,
+    recalculate: () => r ? (r.scroller.clearAllCaches(), v()) : null
   };
 }
-const le = D({
+const me = Z({
   name: "CeriousScroll",
   props: {
     /** Total item count. Falls back to `items.length` when omitted. */
@@ -166,50 +198,51 @@ const le = D({
     /** Emitted once the underlying engine instance is ready (and after recreation). */
     ready: (e) => !0
   },
-  setup(e, { slots: o, emit: l, expose: y }) {
-    const m = (t, f) => {
+  setup(e, { slots: c, emit: s, expose: w }) {
+    const p = (r, d) => {
       var T;
-      return e.renderItem ? e.renderItem(t, f) : (T = o.item) == null ? void 0 : T.call(o, { item: t, index: f });
-    }, n = Z({
+      return e.renderItem ? e.renderItem(r, d) : (T = c.item) == null ? void 0 : T.call(c, { item: r, index: d });
+    }, o = ne({
       totalElements: () => e.totalElements,
       items: () => e.items,
-      getItem: e.getItem ? (t) => e.getItem(t) : void 0,
-      renderItem: m,
+      getItem: e.getItem ? (r) => e.getItem(r) : void 0,
+      renderItem: p,
       // Table mode: declarative header. Render the `#header` slot (a <tr> of
       // <th>s) into the engine's <thead>. `undefined` when no slot is provided.
-      renderHeader: o.header ? () => o.header() : void 0,
+      renderHeader: c.header ? () => c.header() : void 0,
       // Engine options are consumed at creation; reading the prop once matches
       // that contract (remount via `:key` to apply new engine options).
       options: e.options,
       autoRender: () => e.autoRender,
-      onViewportChange: (t) => l("viewport-change", t),
-      onMeasuredViewport: (t) => l("measured-viewport", t),
-      onReady: (t) => l("ready", t)
+      onViewportChange: (r) => s("viewport-change", r),
+      onMeasuredViewport: (r) => s("measured-viewport", r),
+      onReady: (r) => s("ready", r)
     });
-    return y({
+    return w({
       /** The underlying engine instance (`null` before mount). */
-      scroller: n.scroller,
-      render: n.render,
-      jumpToElement: n.jumpToElement,
-      scrollToPercentage: n.scrollToPercentage,
-      reset: n.reset,
-      recalculate: n.recalculate
+      scroller: o.scroller,
+      render: o.render,
+      jumpToElement: o.jumpToElement,
+      jumpToItem: o.jumpToItem,
+      scrollToPercentage: o.scrollToPercentage,
+      reset: o.reset,
+      recalculate: o.recalculate
     }), () => {
-      var t;
-      return A(
+      var r;
+      return V(
         "div",
         {
-          ref: n.containerRef,
+          ref: o.containerRef,
           // User-supplied class/style/attrs fall through and merge onto this root.
           style: { position: "relative", overflow: "hidden" }
         },
-        (t = o.default) == null ? void 0 : t.call(o)
+        (r = c.default) == null ? void 0 : r.call(c)
       );
     };
   }
 });
 export {
-  le as CeriousScroll,
-  ue as CeriousScrollEngine,
-  Z as useCeriousScroll
+  me as CeriousScroll,
+  pe as CeriousScrollEngine,
+  ne as useCeriousScroll
 };

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

@@ -1,6 +1,13 @@
 import { MaybeRefOrGetter, Ref, VNodeChild } from 'vue';
-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 Vue-owned Masonry rendering. */
+export type CeriousScrollOptions = Omit<CoreCeriousScrollOptions, 'masonry'> & {
+    masonry?: Omit<MasonryOptions, 'renderItem'> & {
+        /** Accepted for backward compatibility; Vue supplies the active renderer. */
+        renderItem?: MasonryOptions['renderItem'];
+    };
+};
 export interface UseCeriousScrollOptions<TItem = unknown> {
     /** Total number of items. Falls back to `items.length` when omitted. */
     totalElements?: MaybeRefOrGetter<number | null | undefined>;
@@ -35,6 +42,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/vue-cerious-scroll",
-  "version": "1.0.7",
-  "description": "Vue 3 bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
+  "version": "1.1.1",
+  "description": "Vue 3 bindings for CeriousScroll — virtualized lists, native tables, and Masonry grids",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -45,6 +45,7 @@
     "large-lists",
     "data-grid",
     "variable-height",
+    "masonry",
     "o1-memory",
     "cerious-scroll"
   ],
@@ -57,7 +58,7 @@
     "demo:build": "vite build --config demo/vite.config.ts"
   },
   "dependencies": {
-    "@ceriousdevtech/cerious-scroll": "^1.0.8"
+    "@ceriousdevtech/cerious-scroll": "^1.1.1"
   },
   "peerDependencies": {
     "vue": "^3.3.0"