@ceriousdevtech/vue-cerious-scroll 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+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.0.1] - 2026-06-01
+
+### Changed
+- Verified compatibility with `@ceriousdevtech/cerious-scroll` 1.0.2
+
+### Dependencies
+- Peer dependency `@ceriousdevtech/cerious-scroll` tested against `^1.0.2` (range `^1.0.1` already satisfies this)
+
+---
+
+## [1.0.0] - 2026-02-02
+
+### Added
+- Initial release of `@ceriousdevtech/vue-cerious-scroll`
+- `<CeriousScroll>` component — drop-in virtual scroll list for Vue 3.3+
+- `useCeriousScroll` composable for headless usage with custom container elements
+- Synchronous `render()` rendering for each row — rows run with the app's `appContext` so globally registered components, directives, and plugins work normally
+- Synchronous height measurement (no estimated heights, no correction passes)
+- Full TypeScript support with exported prop and composable types
+- Peer dependency on `@ceriousdevtech/cerious-scroll` core engine

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024–2026 Cerious DevTech LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# @ceriousdevtech/vue-cerious-scroll
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://ceriousdevtech.github.io/vue-cerious-scroll/)
+
+**Vue 3 bindings for [Cerious Scroll™](https://www.npmjs.com/package/@ceriousdevtech/cerious-scroll)** — high-performance virtual scrolling with **O(1) memory**, consistent **60 FPS+**, and **native variable-height support with no height estimation**.
+
+Rows are rendered into the engine's own measured containers via Vue's synchronous `render()`, so every row's real height is measured (never estimated) — exactly the guarantee that makes CeriousScroll precise. Rows are rendered with your app's `appContext`, so **globally registered components, directives, and installed plugins work normally** inside each row.
+
+---
+
+## Installation
+
+```bash
+npm install @ceriousdevtech/vue-cerious-scroll @ceriousdevtech/cerious-scroll
+```
+
+`vue` (>= 3.3) is a peer dependency.
+
+---
+
+## Demo
+
+**[Live demo →](https://ceriousdevtech.github.io/vue-cerious-scroll/)** — 100,000 rows, fixed/variable-height toggle, imperative jump-to-row, and live viewport stats.
+
+To run locally:
+
+```bash
+npm install
+npm run demo        # dev server with HMR
+npm run demo:build  # production build to demo/dist
+```
+
+The demo imports the wrapper by its package name, aliased to the library source,
+so edits to `src/` are reflected live.
+
+---
+
+## Quick start (component)
+
+Give the container a height; provide `items` and an `#item` scoped slot.
+
+```vue
+<script setup lang="ts">
+import { CeriousScroll } from '@ceriousdevtech/vue-cerious-scroll';
+
+const items = Array.from({ length: 1_000_000 }, (_, i) => ({ id: i, name: `Item ${i}` }));
+</script>
+
+<template>
+  <CeriousScroll :items="items" :style="{ height: '480px' }">
+    <template #item="{ item, index }">
+      <div class="row">{{ index }} — {{ item.name }}</div>
+    </template>
+  </CeriousScroll>
+</template>
+```
+
+Variable heights need no configuration — just render rows of whatever height; the
+engine measures each one.
+
+### Without a full array (huge / sparse data)
+
+```vue
+<CeriousScroll
+  :total-elements="100_000_000"
+  :get-item="(index) => loadRow(index)"
+  :style="{ height: '600px' }"
+>
+  <template #item="{ item, index }">
+    <Row :data="item" :index="index" />
+  </template>
+</CeriousScroll>
+```
+
+---
+
+## Composable
+
+`useCeriousScroll` gives you full control. Attach `containerRef` to your scroll
+element; the composable renders the rows imperatively into the engine's measured
+containers.
+
+```vue
+<script setup lang="ts">
+import { h } from 'vue';
+import { useCeriousScroll } from '@ceriousdevtech/vue-cerious-scroll';
+
+const { containerRef } = useCeriousScroll({
+  items,
+  renderItem: (item, index) => h('div', { class: 'row' }, `${index} — ${item.name}`),
+});
+</script>
+
+<template>
+  <div ref="containerRef" style="height: 480px; position: relative; overflow: hidden" />
+</template>
+```
+
+> `renderItem` returns a Vue `VNodeChild` (use `h(...)`, or render JSX/TSX).
+
+---
+
+## Component props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `items` | `readonly TItem[]` | Optional data array. `totalElements` defaults to `items.length`. |
+| `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. |
+| `autoRender` | `boolean` | Re-render on scroll/resize/data changes. Default `true`. |
+
+The row is provided by the **`#item` scoped slot** (`{ item, index }`) or the
+`render-item` prop. Apply `class` / `style` directly to the component — they fall
+through onto the scroll container (set a height!).
+
+### Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `viewport-change` | `CeriousViewportChangeDetail` | Normalized viewport-change (wheel/touch/keyboard/scrollbar). |
+| `measured-viewport` | `MeasuredViewportRange` | Measured range after each render pass. |
+| `ready` | `CeriousScrollEngine` | The underlying engine instance, once ready. |
+
+### Imperative API (via template `ref`)
+
+```ts
+const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
+// scroll.value?.jumpToElement(500);
+// scroll.value?.scrollToPercentage(50);
+// scroll.value?.reset();
+// scroll.value?.render();
+// scroll.value?.recalculate(); // drop cached heights + re-measure (see Notes)
+// scroll.value?.scroller;      // the raw engine
+```
+
+---
+
+## Notes
+
+- **No height estimation.** Rows are committed with Vue's synchronous `render()`
+  so the engine measures real `offsetHeight`. Later size changes are picked up by
+  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
+  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.
+- **If every rendered row's height changes at once** (e.g. a density/layout
+  switch) the cached heights become stale and rows can misalign until the next
+  scroll. Call `recalculate()` (on the template `ref`, or from the composable
+  result) right after the change to drop the height cache and re-measure. Don't
+  call it on routine edits — a single cell edit keeps its row's size, and the
+  engine's built-in `ResizeObserver` picks up any incidental resize on its own.
+
+---
+
+## License
+
+Licensed by **Cerious DevTech LLC** under the **MIT License** (see `LICENSE-MIT`).
+
+📧 info@ceriousdevtech.com

package/dist/cerious-scroll.d.ts

@@ -0,0 +1,102 @@
+import { PropType, VNodeChild } from 'vue';
+import { CeriousScrollOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { CeriousViewportChangeDetail } from './viewport-change';
+/**
+ * High-performance virtual scroll list. Provide `items` (or `total-elements` +
+ * `get-item`) and either an `#item` scoped slot or a `render-item` prop; give
+ * the container a height (e.g. `:style="{ height: '400px' }"`).
+ *
+ * Imperative methods (`render`, `jumpToElement`, `scrollToPercentage`, `reset`,
+ * `recalculate`) and the underlying `scroller` are available via a template ref.
+ *
+ * ```vue
+ * <CeriousScroll :items="items" :style="{ height: '400px' }">
+ *   <template #item="{ item, index }">
+ *     <div class="row">{{ index }} — {{ item.name }}</div>
+ *   </template>
+ * </CeriousScroll>
+ * ```
+ */
+export declare const CeriousScroll: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    /** Total item count. Falls back to `items.length` when omitted. */
+    totalElements: {
+        type: PropType<number | null>;
+        default: null;
+    };
+    /** Optional items array (passed to the row template as `item`). */
+    items: {
+        type: PropType<readonly unknown[] | null>;
+        default: null;
+    };
+    /** Optional lazy getter for very large/sparse datasets (alternative to `items`). */
+    getItem: {
+        type: PropType<(index: number) => unknown>;
+        default: undefined;
+    };
+    /** Render prop alternative to the `#item` scoped slot. */
+    renderItem: {
+        type: PropType<(item: unknown, index: number) => VNodeChild>;
+        default: undefined;
+    };
+    /** Options forwarded to `new CeriousScroll(...)` (read once, at creation). */
+    options: {
+        type: PropType<CeriousScrollOptions>;
+        default: undefined;
+    };
+    /** Automatically render after scroll/resize/data changes. Default: `true`. */
+    autoRender: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    /** Normalized viewport-change payload (wheel/touch/keyboard/scrollbar). */
+    'viewport-change': (_detail: CeriousViewportChangeDetail) => true;
+    /** Measured range after each render pass. */
+    'measured-viewport': (_range: MeasuredViewportRange) => true;
+    /** Emitted once the underlying engine instance is ready (and after recreation). */
+    ready: (_scroller: unknown) => true;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    /** Total item count. Falls back to `items.length` when omitted. */
+    totalElements: {
+        type: PropType<number | null>;
+        default: null;
+    };
+    /** Optional items array (passed to the row template as `item`). */
+    items: {
+        type: PropType<readonly unknown[] | null>;
+        default: null;
+    };
+    /** Optional lazy getter for very large/sparse datasets (alternative to `items`). */
+    getItem: {
+        type: PropType<(index: number) => unknown>;
+        default: undefined;
+    };
+    /** Render prop alternative to the `#item` scoped slot. */
+    renderItem: {
+        type: PropType<(item: unknown, index: number) => VNodeChild>;
+        default: undefined;
+    };
+    /** Options forwarded to `new CeriousScroll(...)` (read once, at creation). */
+    options: {
+        type: PropType<CeriousScrollOptions>;
+        default: undefined;
+    };
+    /** Automatically render after scroll/resize/data changes. Default: `true`. */
+    autoRender: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    "onViewport-change"?: ((_detail: CeriousViewportChangeDetail) => any) | undefined;
+    "onMeasured-viewport"?: ((_range: MeasuredViewportRange) => any) | undefined;
+    onReady?: ((_scroller: unknown) => any) | undefined;
+}>, {
+    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/content-element.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DOM helpers shared by the Vue bindings.
+ *
+ * Copyright (c) 2024-2026 Cerious DevTech LLC. All rights reserved.
+ */
+/** Attribute marking the dedicated content element rows are rendered into. */
+export declare const CONTENT_ATTR = "data-cerious-scroll-content";
+/** Attribute marking the inner mount node Vue renders each row into. */
+export declare const ROW_ATTR = "data-cerious-scroll-row";
+/**
+ * Ensure a dedicated, recyclable content element exists inside `container`.
+ *
+ * CeriousScroll renders/recycles row containers (clearing them with
+ * `textContent`/`innerHTML`) inside this element, while the native scrollbar
+ * and event listeners stay attached to the outer `container`. Keeping them
+ * separate prevents the scrollbar DOM from being wiped during rendering.
+ */
+export declare function ensureContentElement(container: HTMLElement): HTMLElement;

package/dist/index.cjs

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @ceriousdevtech/vue-cerious-scroll
+ *
+ * Vue 3 bindings for the CeriousScroll virtual scrolling engine.
+ *
+ * Copyright (c) 2024-2026 Cerious DevTech LLC. All rights reserved.
+ */
+export { CeriousScroll } from './cerious-scroll';
+export { useCeriousScroll } from './use-cerious-scroll';
+export type { UseCeriousScrollOptions, UseCeriousScrollResult, } 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';

package/dist/index.js

@@ -0,0 +1,189 @@
+import { getCurrentInstance as P, ref as _, shallowRef as x, onMounted as F, onBeforeUnmount as L, watch as $, toValue as h, render as O, effectScope as q, watchEffect as B, isVNode as H, h as M, Fragment as U, defineComponent as W } from "vue";
+import { CeriousScroll as z } from "@ceriousdevtech/cerious-scroll";
+import { CeriousScroll as oe } from "@ceriousdevtech/cerious-scroll";
+const A = "data-cerious-scroll-content", D = "data-cerious-scroll-row";
+function G(e) {
+  const s = e.querySelector(`[${A}]`);
+  if (s) return s;
+  const n = document.createElement("div");
+  return n.setAttribute(A, ""), n.style.position = "relative", n.style.width = "100%", n.style.height = "100%", n.style.overflow = "hidden", e.appendChild(n), n;
+}
+function J(e, s) {
+  const n = (o) => {
+    const r = o.detail;
+    r && s({
+      percentage: r.percentage,
+      currentElement: r.currentElement,
+      scrollOffset: r.scrollOffset,
+      result: { element: r.result.element, offset: r.result.offset }
+    });
+  }, a = (o) => {
+    const r = o.detail;
+    r && s({
+      percentage: r.percentage,
+      currentElement: r.element,
+      scrollOffset: r.scrollOffset,
+      result: { element: r.element, offset: r.scrollOffset }
+    });
+  };
+  return e.addEventListener("cerious-viewport-change", n), e.addEventListener("viewport-change", a), () => {
+    e.removeEventListener("cerious-viewport-change", n), e.removeEventListener("viewport-change", a);
+  };
+}
+function V(e, s) {
+  const n = typeof e == "number" ? e : typeof s == "number" ? s : 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 K(e) {
+  var I;
+  const s = (I = P()) == null ? void 0 : I.appContext, n = _(null), a = x(null);
+  let o = null;
+  const r = /* @__PURE__ */ new Map();
+  let c = null;
+  const C = () => h(e.autoRender) ?? !0, y = (t) => {
+    if (e.getItem) return e.getItem(t);
+    const l = h(e.items);
+    return l ? l[t] : void 0;
+  }, N = (t, l) => {
+    const u = s ?? null, f = q(!0);
+    return f.run(
+      () => B(
+        () => {
+          const E = e.renderItem(y(t), t), m = Array.isArray(E) ? E : [E];
+          for (const w of m)
+            H(w) && (w.appContext = u);
+          const i = M(U, m);
+          i.appContext = u, O(i, l);
+        },
+        { flush: "sync" }
+      )
+    ), () => f.stop();
+  }, S = (t) => {
+    t.stop(), O(null, t.mount), t.mount.remove();
+  }, v = () => {
+    var w;
+    if (!o) return null;
+    const { scroller: t, contentEl: l, container: u } = o, f = u.clientHeight || u.offsetHeight || 0, E = (d, g) => {
+      const p = document.createElement("div");
+      p.setAttribute(D, String(d)), g.appendChild(p);
+      const R = N(d, p);
+      r.set(d, { el: g, mount: p, stop: R });
+    }, m = t.renderViewport(f, l, E), i = new Set(t.getRenderedIndices());
+    return r.forEach((d, g) => {
+      i.has(g) || (S(d), r.delete(g));
+    }), (w = e.onMeasuredViewport) == null || w.call(e, m), m;
+  }, T = (t) => {
+    if (!o) return;
+    const l = o;
+    o = null, l.unsubscribe(), t && (c = {
+      currentElement: l.scroller.currentElement,
+      scrollOffset: l.scroller.scrollOffset
+    }), r.forEach((u) => S(u)), r.clear(), l.contentEl.textContent = "", l.scroller.detachScrollbar(l.container), l.scroller.dispose(), a.value = null;
+  }, b = (t) => {
+    var d, g;
+    const l = G(t), u = e.options ?? {}, f = u.onScroll, E = {
+      ...u,
+      onScroll: () => {
+        f == null || f(), C() && v();
+      }
+    }, m = V(h(e.totalElements), ((d = h(e.items)) == null ? void 0 : d.length) ?? null), i = new z(t, m, E);
+    c && (i.currentElement = Math.min(c.currentElement, m - 1), i.scrollOffset = c.scrollOffset, c = null);
+    const w = J(t, (p) => {
+      var R;
+      (R = e.onViewportChange) == null || R.call(e, p);
+    });
+    o = { scroller: i, contentEl: l, container: t, unsubscribe: w }, a.value = i, (g = e.onReady) == null || g.call(e, i), C() && requestAnimationFrame(() => v());
+  }, j = () => {
+    T(!0);
+    const t = n.value;
+    t && b(t);
+  };
+  return F(() => {
+    const t = n.value;
+    t && b(t);
+  }), L(() => {
+    T(!1);
+  }), $(
+    () => [h(e.totalElements), h(e.items)],
+    () => {
+      var l;
+      if (!o) return;
+      const t = V(h(e.totalElements), ((l = h(e.items)) == null ? void 0 : l.length) ?? null);
+      o.scroller.totalElements !== t && j();
+    }
+  ), {
+    containerRef: n,
+    scroller: a,
+    render: v,
+    jumpToElement: (t) => o ? (o.scroller.jumpToElement(t), v()) : null,
+    scrollToPercentage: (t) => o ? (o.scroller.handleScrollPercentage(t), v()) : null,
+    reset: () => o ? (o.scroller.reset(), v()) : null,
+    recalculate: () => o ? (o.scroller.clearAllCaches(), v()) : null
+  };
+}
+const te = W({
+  name: "CeriousScroll",
+  props: {
+    /** Total item count. Falls back to `items.length` when omitted. */
+    totalElements: { type: Number, default: null },
+    /** Optional items array (passed to the row template as `item`). */
+    items: { type: Array, default: null },
+    /** Optional lazy getter for very large/sparse datasets (alternative to `items`). */
+    getItem: { type: Function, default: void 0 },
+    /** Render prop alternative to the `#item` scoped slot. */
+    renderItem: {
+      type: Function,
+      default: void 0
+    },
+    /** Options forwarded to `new CeriousScroll(...)` (read once, at creation). */
+    options: { type: Object, default: void 0 },
+    /** Automatically render after scroll/resize/data changes. Default: `true`. */
+    autoRender: { type: Boolean, default: !0 }
+  },
+  emits: {
+    /** Normalized viewport-change payload (wheel/touch/keyboard/scrollbar). */
+    "viewport-change": (e) => !0,
+    /** Measured range after each render pass. */
+    "measured-viewport": (e) => !0,
+    /** Emitted once the underlying engine instance is ready (and after recreation). */
+    ready: (e) => !0
+  },
+  setup(e, { slots: s, emit: n, expose: a }) {
+    const o = (c, C) => {
+      var y;
+      return e.renderItem ? e.renderItem(c, C) : (y = s.item) == null ? void 0 : y.call(s, { item: c, index: C });
+    }, r = K({
+      totalElements: () => e.totalElements,
+      items: () => e.items,
+      getItem: e.getItem ? (c) => e.getItem(c) : void 0,
+      renderItem: o,
+      // 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: (c) => n("viewport-change", c),
+      onMeasuredViewport: (c) => n("measured-viewport", c),
+      onReady: (c) => n("ready", c)
+    });
+    return a({
+      /** The underlying engine instance (`null` before mount). */
+      scroller: r.scroller,
+      render: r.render,
+      jumpToElement: r.jumpToElement,
+      scrollToPercentage: r.scrollToPercentage,
+      reset: r.reset,
+      recalculate: r.recalculate
+    }), () => M("div", {
+      ref: r.containerRef,
+      // User-supplied class/style/attrs fall through and merge onto this root.
+      style: { position: "relative", overflow: "hidden" }
+    });
+  }
+});
+export {
+  te as CeriousScroll,
+  oe as CeriousScrollEngine,
+  K as useCeriousScroll
+};

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

@@ -0,0 +1,61 @@
+import { MaybeRefOrGetter, Ref, VNodeChild } from 'vue';
+import { CeriousScroll as CeriousScrollEngine, CeriousScrollOptions, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { CeriousViewportChangeDetail } from './viewport-change';
+export interface UseCeriousScrollOptions<TItem = unknown> {
+    /** Total number of items. Falls back to `items.length` when omitted. */
+    totalElements?: MaybeRefOrGetter<number | null | undefined>;
+    /** Optional items array (passed to `renderItem` as the first argument). */
+    items?: MaybeRefOrGetter<readonly TItem[] | null | undefined>;
+    /** Optional getter for very large/sparse datasets (alternative to `items`). */
+    getItem?: (index: number) => TItem;
+    /** Renders a single row to a Vue VNode. `item` is `undefined` with no data source. */
+    renderItem: (item: TItem, index: number) => VNodeChild;
+    /** Options forwarded to `new CeriousScroll(...)` (read once, at creation). */
+    options?: CeriousScrollOptions;
+    /** Automatically render after scroll/resize/data changes. Default: `true`. */
+    autoRender?: MaybeRefOrGetter<boolean | undefined>;
+    /** Invoked with the normalized viewport-change payload. */
+    onViewportChange?: (detail: CeriousViewportChangeDetail) => void;
+    /** Invoked with the measured range after each render pass. */
+    onMeasuredViewport?: (range: MeasuredViewportRange) => void;
+    /** Invoked once the underlying engine instance is ready (and after recreation). */
+    onReady?: (scroller: CeriousScrollEngine) => void;
+}
+export interface UseCeriousScrollResult {
+    /** Attach to the scroll container element (`<div :ref="containerRef">`). */
+    containerRef: Ref<HTMLElement | null>;
+    /** The underlying engine instance (`null` before mount / after unmount). */
+    scroller: Ref<CeriousScrollEngine | null>;
+    /** Imperatively trigger a render pass. */
+    render: () => MeasuredViewportRange | null;
+    /** Jump to an element index, then render. */
+    jumpToElement: (index: number) => MeasuredViewportRange | null;
+    /** Scroll to a percentage (0..100), then render. */
+    scrollToPercentage: (percentage: number) => MeasuredViewportRange | null;
+    /** Reset to the top, then render. */
+    reset: () => MeasuredViewportRange | null;
+    /**
+     * Discard all cached row heights and re-measure the viewport.
+     *
+     * Call this only when the heights of rows you've *already rendered* may have
+     * changed without their indices changing — e.g. a global font/density change,
+     * or swapping every row to a different layout. This forces a synchronous
+     * re-measure (one `offsetHeight` read per visible row), so do NOT call it on
+     * routine edits: a single cell edit doesn't need it (its row keeps its size,
+     * and the engine's ResizeObserver picks up any incidental resize on its own).
+     */
+    recalculate: () => MeasuredViewportRange | null;
+}
+/**
+ * Bind a CeriousScroll engine to a container and render rows with Vue.
+ *
+ * Each row is rendered into an inner mount node (which lives inside the engine's
+ * recyclable container) via Vue's synchronous `render(vnode, el)`, so the engine
+ * measures the row's real height — no estimation. Because rendering is
+ * synchronous, no `flushSync`-style escape hatch is needed.
+ *
+ * Rows are rendered with the host component's `appContext`, so globally
+ * registered components, directives, and installed plugins are available inside
+ * each row.
+ */
+export declare function useCeriousScroll<TItem = unknown>(opts: UseCeriousScrollOptions<TItem>): UseCeriousScrollResult;

package/dist/viewport-change.d.ts

@@ -0,0 +1,25 @@
+import { ScrollResult } from '@ceriousdevtech/cerious-scroll';
+/**
+ * Normalized payload for viewport changes emitted by CeriousScroll.
+ *
+ * Mirrors the `cerious-viewport-change` CustomEvent dispatched on wheel/touch/
+ * keyboard navigation, and normalizes the native scrollbar's `viewport-change`
+ * event into the same shape.
+ */
+export interface CeriousViewportChangeDetail {
+    /** Scroll percentage from 0..100. */
+    percentage: number;
+    /** Current top-most element index tracked by CeriousScroll. */
+    currentElement: number;
+    /** Pixel offset within `currentElement`. */
+    scrollOffset: number;
+    /** Scroll operation result (element + offset). */
+    result: ScrollResult;
+}
+/**
+ * Subscribe to both viewport-change events emitted by CeriousScroll and invoke
+ * `callback` with a normalized {@link CeriousViewportChangeDetail}.
+ *
+ * @returns An unsubscribe function.
+ */
+export declare function subscribeViewportChange(container: HTMLElement, callback: (detail: CeriousViewportChangeDetail) => void): () => void;

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@ceriousdevtech/vue-cerious-scroll",
+  "version": "1.0.1",
+  "description": "Vue 3 bindings for CeriousScroll — high-performance virtual scrolling with O(1) memory and no height estimation",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "Cerious DevTech LLC <info@ceriousdevtech.com>",
+  "homepage": "https://github.com/ceriousdevtech/vue-cerious-scroll#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ceriousdevtech/vue-cerious-scroll.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ceriousdevtech/vue-cerious-scroll/issues",
+    "email": "info@ceriousdevtech.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "virtual-scroll",
+    "virtual-scrolling",
+    "infinite-scroll",
+    "performance",
+    "large-lists",
+    "data-grid",
+    "variable-height",
+    "o1-memory",
+    "cerious-scroll"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "vue-tsc --noEmit",
+    "demo": "vite --config demo/vite.config.ts",
+    "demo:build": "vite build --config demo/vite.config.ts"
+  },
+  "peerDependencies": {
+    "@ceriousdevtech/cerious-scroll": "^1.0.1",
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@ceriousdevtech/cerious-scroll": "^1.0.1",
+    "@types/node": "^22.10.2",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11",
+    "vite-plugin-dts": "^4.3.0",
+    "vitest": "^2.1.8",
+    "vue": "^3.5.13",
+    "vue-router": "^4.6.4",
+    "vue-tsc": "^2.1.10"
+  }
+}