@ceriousdevtech/react-cerious-scroll 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+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.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/react-cerious-scroll`
+- `<CeriousScroll>` component — drop-in virtual scroll list for React 18+
+- `useCeriousScroll` hook for headless usage with custom container elements
+- React portal rendering for each row — rows live in the React tree so Context, providers, and refs work normally
+- Synchronous height measurement (no estimated heights, no correction passes)
+- Full TypeScript support with exported prop and hook 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,158 @@
+# @ceriousdevtech/react-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/react-cerious-scroll/)
+
+**React 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 React portals and committed synchronously, so every row's real height is measured (never estimated) — exactly the guarantee that makes CeriousScroll precise. Because rows stay in your React tree, **Context / providers work normally**.
+
+---
+
+## Installation
+
+```bash
+npm install @ceriousdevtech/react-cerious-scroll @ceriousdevtech/cerious-scroll
+```
+
+`react` and `react-dom` (>= 18) are peer dependencies.
+
+---
+
+## Demo
+
+**[Live demo →](https://ceriousdevtech.github.io/react-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 a `renderItem` render prop.
+
+```tsx
+import { CeriousScroll } from '@ceriousdevtech/react-cerious-scroll';
+
+const items = Array.from({ length: 1_000_000 }, (_, i) => ({ id: i, name: `Item ${i}` }));
+
+export function List() {
+  return (
+    <CeriousScroll
+      items={items}
+      renderItem={(item, index) => (
+        <div className="row">
+          {index} — {item.name}
+        </div>
+      )}
+      style={{ height: 480 }}
+    />
+  );
+}
+```
+
+Variable heights need no configuration — just render rows of whatever height; the
+engine measures each one.
+
+### Without a full array (huge / sparse data)
+
+```tsx
+<CeriousScroll
+  totalElements={100_000_000}
+  getItem={(index) => loadRow(index)}
+  renderItem={(row, index) => <Row data={row} index={index} />}
+  style={{ height: 600 }}
+/>
+```
+
+---
+
+## Hook
+
+`useCeriousScroll` gives you full control. Attach `containerRef` to your scroll
+element and render `portals` somewhere in your tree (they attach to their own DOM
+targets, so placement only affects which React Context they inherit).
+
+```tsx
+import { useCeriousScroll } from '@ceriousdevtech/react-cerious-scroll';
+
+function List() {
+  const { containerRef, portals } = useCeriousScroll({
+    items,
+    renderItem: (item, index) => <Row item={item} index={index} />,
+  });
+
+  return (
+    <div ref={containerRef} style={{ height: 480, position: 'relative', overflow: 'hidden' }}>
+      {portals}
+    </div>
+  );
+}
+```
+
+---
+
+## Component props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `renderItem` | `(item, index) => ReactNode` | **Required.** Renders one row. `item` is `undefined` if no data source is given. |
+| `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. |
+| `options` | `CeriousScrollOptions` | Engine options (keyboard/touch/wheel/scrollbar/etc.). 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. |
+| `onReady` | `(scroller) => void` | The underlying engine instance, once ready. |
+| `className` / `style` | — | Applied to the scroll container (set a height!). |
+
+### Imperative handle (via `ref`)
+
+```tsx
+const ref = useRef<CeriousScrollHandle>(null);
+// ref.current?.jumpToElement(500);
+// ref.current?.scrollToPercentage(50);
+// ref.current?.reset();
+// ref.current?.render();
+// ref.current?.recalculate(); // drop cached heights + re-measure (see Notes)
+// ref.current?.scroller;      // the raw engine
+```
+
+---
+
+## Notes
+
+- **No height estimation.** Rows are committed with `flushSync` 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 (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.
+- **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 `ref`, or from the hook 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,35 @@
+import { CSSProperties, ReactElement, Ref } from 'react';
+import { CeriousScroll as CeriousScrollEngine, MeasuredViewportRange } from '@ceriousdevtech/cerious-scroll';
+import { UseCeriousScrollOptions } from './use-cerious-scroll';
+export interface CeriousScrollProps<TItem = unknown> extends UseCeriousScrollOptions<TItem> {
+    /** Class applied to the scroll container. */
+    className?: string;
+    /**
+     * Inline styles for the scroll container. You must give the container a
+     * height (e.g. `style={{ height: 400 }}`) for scrolling to work.
+     */
+    style?: CSSProperties;
+    /** Forwarded to the scroll container for testing. */
+    'data-testid'?: string;
+}
+export interface CeriousScrollHandle {
+    /** The underlying engine instance (`null` before mount). */
+    scroller: CeriousScrollEngine | null;
+    render(): MeasuredViewportRange | null;
+    jumpToElement(index: number): MeasuredViewportRange | null;
+    scrollToPercentage(percentage: number): MeasuredViewportRange | null;
+    reset(): MeasuredViewportRange | null;
+    /**
+     * Discard all cached row heights and re-measure. Use only when the heights of
+     * already-rendered rows changed without their indices changing (e.g. a global
+     * density/layout switch) — not for routine cell edits.
+     */
+    recalculate(): MeasuredViewportRange | null;
+}
+/**
+ * High-performance virtual scroll list. Provide `items` (or `totalElements` +
+ * `getItem`) and a `renderItem` render prop; give the container a height.
+ */
+export declare const CeriousScroll: <TItem = unknown>(props: CeriousScrollProps<TItem> & {
+    ref?: Ref<CeriousScrollHandle>;
+}) => ReactElement;

package/dist/content-element.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DOM helpers shared by the React 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 React 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 J=require("react/jsx-runtime"),r=require("react"),H=require("react-dom"),K=require("react-dom/server"),_=require("@ceriousdevtech/cerious-scroll"),V="data-cerious-scroll-content",Q="data-cerious-scroll-row";function U(e){const l=e.querySelector(`[${V}]`);if(l)return l;const n=document.createElement("div");return n.setAttribute(V,""),n.style.position="relative",n.style.width="100%",n.style.height="100%",n.style.overflow="hidden",e.appendChild(n),n}function X(e,l){const n=u=>{const o=u.detail;o&&l({percentage:o.percentage,currentElement:o.currentElement,scrollOffset:o.scrollOffset,result:{element:o.result.element,offset:o.result.offset}})},a=u=>{const o=u.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",n),e.addEventListener("viewport-change",a),()=>{e.removeEventListener("cerious-viewport-change",n),e.removeEventListener("viewport-change",a)}}function Y(e,l){const n=typeof e=="number"?e:typeof l=="number"?l: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 D(e){var N;const l=r.useRef(null),n=r.useRef(null),a=r.useRef(new Map),u=r.useRef(null),[,o]=r.useReducer(t=>t+1,0),[q,y]=r.useState(null),E=r.useRef(e.renderItem),d=r.useRef(e.items??null),v=r.useRef(e.getItem),S=r.useRef(e.options),h=r.useRef(e.autoRender??!0),p=r.useRef(e.totalElements??null),O=r.useRef(e.onViewportChange),T=r.useRef(e.onMeasuredViewport),I=r.useRef(e.onReady);E.current=e.renderItem,d.current=e.items??null,v.current=e.getItem,S.current=e.options,h.current=e.autoRender??!0,p.current=e.totalElements??null,O.current=e.onViewportChange,T.current=e.onMeasuredViewport,I.current=e.onReady;const k=r.useCallback(t=>{const c=v.current;if(c)return c(t);const g=d.current;return g?g[t]:void 0},[]),s=r.useCallback(()=>{var w;const t=n.current;if(!t)return null;const{scroller:c,contentEl:g,container:C}=t,j=C.clientHeight||C.offsetHeight||0,b=[],i=(f,R)=>{const m=document.createElement("div");m.setAttribute(Q,String(f)),m.innerHTML=K.renderToStaticMarkup(r.createElement(r.Fragment,null,E.current(k(f),f))),R.appendChild(m),a.current.set(f,{el:R,mount:m}),b.push(m)},A=c.renderViewport(j,g,i),M=new Set(c.getRenderedIndices());return a.current.forEach((f,R)=>{M.has(R)||a.current.delete(R)}),b.forEach(f=>{f.textContent=""}),H.flushSync(o),(w=T.current)==null||w.call(T,A),A},[]),B=e.totalElements??((N=e.items)==null?void 0:N.length)??null;r.useEffect(()=>{var w,f;const t=l.current;if(!t)return;const c=U(t),g=S.current??{},C=g.onScroll,j={...g,onScroll:()=>{C==null||C(),h.current&&s()}},b=Y(p.current,((w=d.current)==null?void 0:w.length)??null),i=new _.CeriousScroll(t,b,j);u.current&&(i.currentElement=Math.min(u.current.currentElement,b-1),i.scrollOffset=u.current.scrollOffset,u.current=null),n.current={scroller:i,contentEl:c,container:t},y(i);const A=X(t,R=>{var m;(m=O.current)==null||m.call(O,R)});(f=I.current)==null||f.call(I,i);let M=0;return h.current&&(M=requestAnimationFrame(()=>s())),()=>{cancelAnimationFrame(M),A(),u.current={currentElement:i.currentElement,scrollOffset:i.scrollOffset},a.current.clear(),c.textContent="",i.detachScrollbar(t),i.dispose(),n.current=null,y(null)}},[B,s]),r.useEffect(()=>{if(!n.current||!h.current)return;const t=requestAnimationFrame(()=>s());return()=>cancelAnimationFrame(t)},[e.items,e.getItem]);const W=r.useCallback(t=>{const c=n.current;return c?(c.scroller.jumpToElement(t),s()):null},[s]),$=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]),G=r.useCallback(()=>{const t=n.current;return t?(t.scroller.clearAllCaches(),s()):null},[s]),P=d.current,F=!v.current&&P!=null?P.length:null,L=[];return a.current.forEach((t,c)=>{F!==null&&c>=F||L.push(H.createPortal(E.current(k(c),c),t.mount,String(c)))}),{containerRef:l,portals:L,scroller:q,render:s,jumpToElement:W,scrollToPercentage:$,reset:z,recalculate:G}}function Z(e,l){const{className:n,style:a,"data-testid":u,...o}=e,{containerRef:q,portals:y,scroller:E,render:d,jumpToElement:v,scrollToPercentage:S,reset:h,recalculate:p}=D(o);return r.useImperativeHandle(l,()=>({scroller:E,render:d,jumpToElement:v,scrollToPercentage:S,reset:h,recalculate:p}),[E,d,v,S,h,p]),J.jsx("div",{ref:q,className:n,"data-testid":u,style:{position:"relative",overflow:"hidden",...a},children:y})}const x=r.forwardRef(Z);Object.defineProperty(exports,"CeriousScrollEngine",{enumerable:!0,get:()=>_.CeriousScroll});exports.CeriousScroll=x;exports.useCeriousScroll=D;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @ceriousdevtech/react-cerious-scroll
+ *
+ * React bindings for the CeriousScroll virtual scrolling engine.
+ *
+ * Copyright (c) 2024-2026 Cerious DevTech LLC. All rights reserved.
+ */
+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 { 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,160 @@
+import { jsx as G } from "react/jsx-runtime";
+import { useRef as s, useReducer as J, useState as K, useCallback as S, useEffect as _, createElement as Q, Fragment as U, forwardRef as X, useImperativeHandle as Y } from "react";
+import { flushSync as Z, createPortal as x } from "react-dom";
+import { renderToStaticMarkup as ee } from "react-dom/server";
+import { CeriousScroll as te } from "@ceriousdevtech/cerious-scroll";
+import { CeriousScroll as Ee } from "@ceriousdevtech/cerious-scroll";
+const k = "data-cerious-scroll-content", re = "data-cerious-scroll-row";
+function ne(e) {
+  const c = e.querySelector(`[${k}]`);
+  if (c) return c;
+  const r = document.createElement("div");
+  return r.setAttribute(k, ""), r.style.position = "relative", r.style.width = "100%", r.style.height = "100%", r.style.overflow = "hidden", e.appendChild(r), r;
+}
+function oe(e, c) {
+  const r = (u) => {
+    const o = u.detail;
+    o && c({
+      percentage: o.percentage,
+      currentElement: o.currentElement,
+      scrollOffset: o.scrollOffset,
+      result: { element: o.result.element, offset: o.result.offset }
+    });
+  }, a = (u) => {
+    const o = u.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", r), e.addEventListener("viewport-change", a), () => {
+    e.removeEventListener("cerious-viewport-change", r), e.removeEventListener("viewport-change", a);
+  };
+}
+function ce(e, c) {
+  const r = typeof e == "number" ? e : typeof c == "number" ? c : void 0;
+  if (r === void 0 || Number.isNaN(r))
+    throw new Error("useCeriousScroll: provide `totalElements` or `items`.");
+  return Math.max(1, Math.floor(r));
+}
+function le(e) {
+  var q;
+  const c = s(null), r = s(null), a = s(/* @__PURE__ */ new Map()), u = s(null), [, o] = J((t) => t + 1, 0), [L, O] = K(null), p = s(e.renderItem), d = s(e.items ?? null), v = s(e.getItem), w = s(e.options), h = s(e.autoRender ?? !0), C = s(e.totalElements ?? null), b = s(e.onViewportChange), y = s(e.onMeasuredViewport), A = s(e.onReady);
+  p.current = e.renderItem, d.current = e.items ?? null, v.current = e.getItem, w.current = e.options, h.current = e.autoRender ?? !0, C.current = e.totalElements ?? null, b.current = e.onViewportChange, y.current = e.onMeasuredViewport, A.current = e.onReady;
+  const P = S((t) => {
+    const n = v.current;
+    if (n) return n(t);
+    const g = d.current;
+    return g ? g[t] : void 0;
+  }, []), l = S(() => {
+    var I;
+    const t = r.current;
+    if (!t) return null;
+    const { scroller: n, contentEl: g, container: R } = t, N = R.clientHeight || R.offsetHeight || 0, T = [], i = (f, E) => {
+      const m = document.createElement("div");
+      m.setAttribute(re, String(f)), m.innerHTML = ee(
+        Q(U, null, p.current(P(f), f))
+      ), E.appendChild(m), a.current.set(f, { el: E, mount: m }), T.push(m);
+    }, M = n.renderViewport(N, g, i), F = new Set(n.getRenderedIndices());
+    return a.current.forEach((f, E) => {
+      F.has(E) || a.current.delete(E);
+    }), T.forEach((f) => {
+      f.textContent = "";
+    }), Z(o), (I = y.current) == null || I.call(y, M), M;
+  }, []), $ = e.totalElements ?? ((q = e.items) == null ? void 0 : q.length) ?? null;
+  _(() => {
+    var I, f;
+    const t = c.current;
+    if (!t) return;
+    const n = ne(t), g = w.current ?? {}, R = g.onScroll, N = {
+      ...g,
+      onScroll: () => {
+        R == null || R(), h.current && l();
+      }
+    }, T = ce(C.current, ((I = d.current) == null ? void 0 : I.length) ?? null), i = new te(t, T, N);
+    u.current && (i.currentElement = Math.min(u.current.currentElement, T - 1), i.scrollOffset = u.current.scrollOffset, u.current = null), r.current = { scroller: i, contentEl: n, container: t }, O(i);
+    const M = oe(t, (E) => {
+      var m;
+      (m = b.current) == null || m.call(b, E);
+    });
+    (f = A.current) == null || f.call(A, i);
+    let F = 0;
+    return h.current && (F = requestAnimationFrame(() => l())), () => {
+      cancelAnimationFrame(F), M(), u.current = {
+        currentElement: i.currentElement,
+        scrollOffset: i.scrollOffset
+      }, a.current.clear(), n.textContent = "", i.detachScrollbar(t), i.dispose(), r.current = null, O(null);
+    };
+  }, [$, l]), _(() => {
+    if (!r.current || !h.current) return;
+    const t = requestAnimationFrame(() => l());
+    return () => cancelAnimationFrame(t);
+  }, [e.items, e.getItem]);
+  const B = S(
+    (t) => {
+      const n = r.current;
+      return n ? (n.scroller.jumpToElement(t), l()) : null;
+    },
+    [l]
+  ), D = S(
+    (t) => {
+      const n = r.current;
+      return n ? (n.scroller.handleScrollPercentage(t), l()) : null;
+    },
+    [l]
+  ), W = S(() => {
+    const t = r.current;
+    return t ? (t.scroller.reset(), l()) : null;
+  }, [l]), z = S(() => {
+    const t = r.current;
+    return t ? (t.scroller.clearAllCaches(), l()) : null;
+  }, [l]), j = d.current, H = !v.current && j != null ? j.length : null, V = [];
+  return a.current.forEach((t, n) => {
+    H !== null && n >= H || V.push(
+      x(p.current(P(n), n), t.mount, String(n))
+    );
+  }), {
+    containerRef: c,
+    portals: V,
+    scroller: L,
+    render: l,
+    jumpToElement: B,
+    scrollToPercentage: D,
+    reset: W,
+    recalculate: z
+  };
+}
+function se(e, c) {
+  const { className: r, style: a, "data-testid": u, ...o } = e, {
+    containerRef: L,
+    portals: O,
+    scroller: p,
+    render: d,
+    jumpToElement: v,
+    scrollToPercentage: w,
+    reset: h,
+    recalculate: C
+  } = le(o);
+  return Y(
+    c,
+    () => ({ scroller: p, render: d, jumpToElement: v, scrollToPercentage: w, reset: h, recalculate: C }),
+    [p, d, v, w, h, C]
+  ), /* @__PURE__ */ G(
+    "div",
+    {
+      ref: L,
+      className: r,
+      "data-testid": u,
+      style: { position: "relative", overflow: "hidden", ...a },
+      children: O
+    }
+  );
+}
+const de = X(se);
+export {
+  de as CeriousScroll,
+  Ee as CeriousScrollEngine,
+  le as useCeriousScroll
+};

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

@@ -0,0 +1,59 @@
+import { ReactNode, RefObject } from 'react';
+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?: number | null;
+    /** Optional items array (passed to `renderItem` as the first argument). */
+    items?: readonly TItem[] | null;
+    /** Optional getter for very large/sparse datasets (alternative to `items`). */
+    getItem?: (index: number) => TItem;
+    /** Renders a single row. `item` is `undefined` when no data source is given. */
+    renderItem: (item: TItem, index: number) => ReactNode;
+    /** Options forwarded to `new CeriousScroll(...)` (read once, at creation). */
+    options?: CeriousScrollOptions;
+    /** Automatically render after scroll/resize/data changes. Default: `true`. */
+    autoRender?: boolean;
+    /** 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. */
+    containerRef: RefObject<HTMLDivElement>;
+    /** React portals for the currently rendered rows. Render these in your tree. */
+    portals: ReactNode;
+    /** The underlying engine instance (`null` before mount / after unmount). */
+    scroller: 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 as React portals.
+ *
+ * Each row is rendered into an inner mount node that lives inside the engine's
+ * recyclable container and is committed synchronously via `flushSync`, so the
+ * engine measures the row's real height (no estimation). Rows stay in your
+ * React tree, so Context/providers work as usual.
+ */
+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,79 @@
+{
+  "name": "@ceriousdevtech/react-cerious-scroll",
+  "version": "1.0.1",
+  "description": "React 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/react-cerious-scroll#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ceriousdevtech/react-cerious-scroll.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ceriousdevtech/react-cerious-scroll/issues",
+    "email": "info@ceriousdevtech.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "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": "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",
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.0.1",
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.4",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11",
+    "vite-plugin-dts": "^4.3.0",
+    "vitest": "^2.1.8"
+  }
+}