@design-edito/tools 0.5.5 → 0.5.7

package/components/ListLoader/index.d.ts

@@ -66,4 +66,4 @@ export type Props<T> = Omit<ControlledProps<T>, 'itemsPages' | 'loadingPages' |
  * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
  *   is in use.
  */
-export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;
+export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;

package/components/ListLoader/index.js

@@ -25,7 +25,7 @@ import { rangeBetween } from './utils.js';
  * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
  *   is in use.
  */
-export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
+export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
     const [itemsPages, setItemsPages] = useState(new Map());
     const [loadingPages, setLoadingPages] = useState(new Set());
     const [internalPages, setInternalPages] = useState([
@@ -142,5 +142,5 @@ export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dro
     const controlledItemsPages = new Map(Array
         .from(itemsPages)
         .map(([page, { items }]) => [page, items]));
-    return _jsx(ControlledListLoader, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClicked: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible });
+    return _jsx(ControlledListLoader, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClicked: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible, threshold: threshold, root: root, rootMargin: rootMargin });
 };

package/components/Paginator/index.d.ts

@@ -32,6 +32,10 @@ type DirectionState = 'forwards' | 'backwards' | null;
  * trigger it again.
  * @property onPagesChanged - Called after any page's {@link PageState} changed,
  * with a flat array of every page's state, ordered by position.
+ * @property onPageElementsChanged - Called with the page slot elements, in order,
+ * whenever the observed set changes. Unlike the other handlers it *does* fire on
+ * mount: the elements don't exist before it, so their appearance is the change.
+ * Lets a parent measure the pages without reaching into this component's DOM.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - Each direct child is treated as an individual page slot.
  */
@@ -39,6 +43,7 @@ export type Props = PropsWithChildren<WithClassName<{
     thresholdOffsetPercent?: number;
     onDirectionChanged?: (direction: DirectionState) => void;
     onPagesChanged?: (pages: PageState[]) => void;
+    onPageElementsChanged?: (pageElements: HTMLElement[]) => void;
 }>>;
 /**
  * A scroll-driven pagination component that tracks which child page is currently

package/components/Paginator/index.js

@@ -27,7 +27,7 @@ import cssModule from './styles.module.css';
  * - `currCount` on each {@link PageState} increments each time a page transitions
  *   into the `'curr'` position, making it useful as a re-entry counter.
  */
-export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesChanged, className, children }) => {
+export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesChanged, onPageElementsChanged, className, children }) => {
     // State, refs, effects
     const [pagesState, setPagesState] = useState(new Map());
     const [directionState, setDirectionState] = useState(null);
@@ -67,6 +67,7 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
         if (pagesRef.current === null)
             return;
         const pages = Array.from(pagesRef.current.children);
+        onPageElementsChanged?.(pages.filter(page => page instanceof HTMLElement));
         const observerRootMargin = `-${thresholdOffsetPercent ?? 0}%`
             + ' 0px'
             + ` -${100 - (thresholdOffsetPercent ?? 0)}%`

package/components/Scrllgngn/index.d.ts

@@ -1,17 +1,20 @@
 import { type PropsWithChildren, type FunctionComponent } from 'react';
 import type { WithClassName } from '../utils/types.js';
+import { type TrackedBlockContext, type ViewportOffset } from './utils.js';
 /**
  * Common properties shared by all block types.
  *
  * @property id - Optional stable identifier for the block. Used to consolidate
  * blocks with the same id across multiple pages into a single sticky block
  * displayed across those pages.
- * @property trackScroll - Whether scroll tracking is enabled for this block.
+ * @property onScrolled - Called with this block's {@link TrackedBlockContext} on
+ * every frame the scroll moved it, while it is displayed. Declaring it is what
+ * turns tracking on for the block — nothing is measured for a block without it.
  * @property children - Content rendered inside the block.
  */
 export type PropsCommonBlock = PropsWithChildren<{
     id?: string;
-    trackScroll?: boolean;
+    onScrolled?: (context: TrackedBlockContext) => void;
 }>;
 /**
  * A block that scrolls with the page content.
@@ -59,9 +62,17 @@ export type PropsPage = {
  *
  * @property pages - Ordered list of pages that compose the scrollytelling
  * sequence. Each page may contain any mix of {@link PropsBlock} variants.
- * @property thresholdOffsetPercent - Forwarded to the internal
- * {@link Paginator}. Defines the viewport offset percentage used to determine
- * which page is considered current.
+ * @property thresholdOffsetPercent - Where the threshold line sits, as a
+ * percentage of the **visible zone** — not of the viewport, so a threshold stays
+ * put under a sticky nav. It decides which page counts as current, and anchors
+ * every progression handed to a tracked block.
+ * @property viewportOffsetTop - How much of the top of the screen is covered by
+ * something else — a sticky nav, say — and should be kept out of the visible zone.
+ * A number means pixels; a string is any CSS length, `var()` and `clamp()`
+ * included, so the value can follow a breakpoint without JavaScript.
+ * @property viewportOffsetRight - Same, on the right edge.
+ * @property viewportOffsetBottom - Same, on the bottom edge.
+ * @property viewportOffsetLeft - Same, on the left edge.
  * @property stickyBlocksLazyLoadDistance - Number of pages around the current
  * page within which sticky blocks are mounted. Blocks outside this window are
  * unmounted to save resources. Defaults to `2`.
@@ -82,6 +93,10 @@ export type PropsPage = {
 export type Props = WithClassName<{
     pages?: PropsPage[];
     thresholdOffsetPercent?: number;
+    viewportOffsetTop?: ViewportOffset;
+    viewportOffsetRight?: ViewportOffset;
+    viewportOffsetBottom?: ViewportOffset;
+    viewportOffsetLeft?: ViewportOffset;
     stickyBlocksLazyLoadDistance?: number;
     forceStickBlocks?: 'before' | 'after' | 'both' | 'none';
     onPageChanged?: (currentPagePos: number, pageData?: PropsPage) => void;
@@ -122,6 +137,16 @@ export type Props = WithClassName<{
  * `-width` and `-height` for the component's own stylesheet. They are internal:
  * do not read or override them.
  *
+ * ### Visible zone
+ * Set any of the `viewportOffset*` props and the component stops treating the whole
+ * screen as available: the fixed layers are inset by those edges, the top / content
+ * / bottom detection observes the reduced box, and `thresholdOffsetPercent` reads as
+ * a percentage of it. With none of them set, everything behaves exactly as before.
+ *
+ * The four edges are echoed as `--lm-scrllgngn-viewport-offset-top`, `-right`,
+ * `-bottom` and `-left`, carrying the length as authored — pixels for a number, the
+ * string untouched otherwise.
+ *
  * ### Sticky block elements
  * Each lazy-loaded sticky block receives:
  * - `--active` modifier when the block's page range includes the current page.
@@ -129,10 +154,45 @@ export type Props = WithClassName<{
  * - An inline `z-index` derived from the block's position in the sorted stack
  * (overridden by {@link PropsStickyBlock.zIndex} if provided).
  *
+ * ### Scroll block elements
+ * Each scroll block sits in its own wrapper, whatever it does — a block that isn't
+ * tracked still gets one, so the DOM keeps the same shape either way.
+ *
+ * ### Tracked block elements
+ * A block declaring {@link PropsCommonBlock.onScrolled} also carries its
+ * {@link TrackedBlockContext} on its wrapper, for scrollytelling driven in CSS
+ * alone. Written straight to the element on the frames they change, so they never
+ * re-render the sequence.
+ *
+ * Progressions, as unitless `0`–`1` ratios:
+ * - `--lm-scrllgngn-block-current-page-progression-ratio`
+ * - `--lm-scrllgngn-block-display-zone-progression-ratio`
+ * - `--lm-scrllgngn-block-contiguous-display-zone-progression-ratio`
+ *
+ * Position, which only moves with the page:
+ * - `data-current-page`
+ * - `data-display-zone` — comma-separated page positions.
+ * - `data-index-of-current-page-in-display-zone`
+ * - `data-contiguous-display-zone`
+ * - `data-index-of-current-page-in-contiguous-display-zone`
+ *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A div wrapping the full scrollytelling structure: top-bound sentinel,
- * back-blocks layer, front-blocks layer, paginated scrolling content, and
- * bottom-bound sentinel.
+ * @returns A div wrapping the full scrollytelling structure: visible zone probe,
+ * top-bound sentinel, back-blocks layer, front-blocks layer, paginated scrolling
+ * content, and bottom-bound sentinel.
+ *
+ * @remarks
+ * A `viewportOffset*` given as a CSS length is resolved by CSS, not parsed: a hidden
+ * probe is inset by the four of them and observed, so `var()`, `clamp()` and
+ * breakpoint-dependent values all work, and any restyling that changes them is
+ * picked up as a resize. A change that moves the zone without altering its size —
+ * a top offset traded for an equal bottom one — is caught instead by a re-read every
+ * 100ms, which runs only while the component is on screen and only reaches state
+ * when the zone really moved.
+ *
+ * Tracking costs nothing until a block asks for it: with no `onScrolled` anywhere,
+ * the component never joins the shared scroll listener. Once it does, each frame
+ * measures only the pages the displayed tracked blocks span, not the whole sequence.
  */
 export declare const Scrllgngn: FunctionComponent<Props>;

package/components/Scrllgngn/index.js

@@ -1,12 +1,14 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState, useEffect } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { clss } from '../../agnostic/css/clss/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { Paginator } from '../Paginator/index.js';
 import { ResizeObserverComponent } from '../ResizeObserver/index.js';
+import { subscribe, unsubscribe } from '../ScrollListener/utils.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { scrllgngn as publicClassName } from '../public-classnames.js';
-import { consolidateStickyBlocks, lazyLoadedBlocks, toScreenCssProps } from './utils.js';
+import { blockDisplayZones, consolidateStickyBlocks, contextsAreEqual, lazyLoadedBlocks, measurePages, sameDiscretePart, scrollBlocksOf, scrollKey, stickyKey, toPaginatorThresholdPercent, toScreenCssProps, toThresholdY, toTrackedBlockContext, toTrackedBlockCssProps, toTrackedBlockDataAttributes, toViewportOffsetCssProps, toVisibleZoneRect, toVisibleZoneRootMargin, visibleZonePollInterval, visibleZonesAreEqual } from './utils.js';
 import cssModule from './styles.module.css';
 /**
  * Scrollytelling engine component. Orchestrates layered sticky blocks (`back`
@@ -43,6 +45,16 @@ import cssModule from './styles.module.css';
  * `-width` and `-height` for the component's own stylesheet. They are internal:
  * do not read or override them.
  *
+ * ### Visible zone
+ * Set any of the `viewportOffset*` props and the component stops treating the whole
+ * screen as available: the fixed layers are inset by those edges, the top / content
+ * / bottom detection observes the reduced box, and `thresholdOffsetPercent` reads as
+ * a percentage of it. With none of them set, everything behaves exactly as before.
+ *
+ * The four edges are echoed as `--lm-scrllgngn-viewport-offset-top`, `-right`,
+ * `-bottom` and `-left`, carrying the length as authored — pixels for a number, the
+ * string untouched otherwise.
+ *
  * ### Sticky block elements
  * Each lazy-loaded sticky block receives:
  * - `--active` modifier when the block's page range includes the current page.
@@ -50,13 +62,48 @@ import cssModule from './styles.module.css';
  * - An inline `z-index` derived from the block's position in the sorted stack
  * (overridden by {@link PropsStickyBlock.zIndex} if provided).
  *
+ * ### Scroll block elements
+ * Each scroll block sits in its own wrapper, whatever it does — a block that isn't
+ * tracked still gets one, so the DOM keeps the same shape either way.
+ *
+ * ### Tracked block elements
+ * A block declaring {@link PropsCommonBlock.onScrolled} also carries its
+ * {@link TrackedBlockContext} on its wrapper, for scrollytelling driven in CSS
+ * alone. Written straight to the element on the frames they change, so they never
+ * re-render the sequence.
+ *
+ * Progressions, as unitless `0`–`1` ratios:
+ * - `--lm-scrllgngn-block-current-page-progression-ratio`
+ * - `--lm-scrllgngn-block-display-zone-progression-ratio`
+ * - `--lm-scrllgngn-block-contiguous-display-zone-progression-ratio`
+ *
+ * Position, which only moves with the page:
+ * - `data-current-page`
+ * - `data-display-zone` — comma-separated page positions.
+ * - `data-index-of-current-page-in-display-zone`
+ * - `data-contiguous-display-zone`
+ * - `data-index-of-current-page-in-contiguous-display-zone`
+ *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A div wrapping the full scrollytelling structure: top-bound sentinel,
- * back-blocks layer, front-blocks layer, paginated scrolling content, and
- * bottom-bound sentinel.
+ * @returns A div wrapping the full scrollytelling structure: visible zone probe,
+ * top-bound sentinel, back-blocks layer, front-blocks layer, paginated scrolling
+ * content, and bottom-bound sentinel.
+ *
+ * @remarks
+ * A `viewportOffset*` given as a CSS length is resolved by CSS, not parsed: a hidden
+ * probe is inset by the four of them and observed, so `var()`, `clamp()` and
+ * breakpoint-dependent values all work, and any restyling that changes them is
+ * picked up as a resize. A change that moves the zone without altering its size —
+ * a top offset traded for an equal bottom one — is caught instead by a re-read every
+ * 100ms, which runs only while the component is on screen and only reaches state
+ * when the zone really moved.
+ *
+ * Tracking costs nothing until a block asks for it: with no `onScrolled` anywhere,
+ * the component never joins the shared scroll listener. Once it does, each frame
+ * measures only the pages the displayed tracked blocks span, not the whole sequence.
  */
-export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, onContentVisibilityChanged, className }) => {
+export const Scrllgngn = ({ pages, thresholdOffsetPercent, viewportOffsetTop, viewportOffsetRight, viewportOffsetBottom, viewportOffsetLeft, stickyBlocksLazyLoadDistance = 2, forceStickBlocks, onPageChanged, onContentVisibilityChanged, className }) => {
     // State
     const [topVisible, setTopVis] = useState(false);
     const [contentVisible, setCntVis] = useState(false);
@@ -64,12 +111,148 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     const [currentPagePos, setCurrentPagePos] = useState(0);
     const [stickyBlocks, setStickyBlocks] = useState(new Map());
     const [partialBoundingRect, setPartialBoundingRect] = useState();
+    const [visibleZone, setVisibleZone] = useState();
+    // Scroll tracking. Everything the per-frame pass reads lives in a ref: it is
+    // registered once with the shared scroll listener, and writes straight to the DOM
+    // rather than through state, which would re-render the whole sequence per frame.
+    const rootRef = useRef(null);
+    const subscriptionIdRef = useRef(randomHash(8));
+    const pageElementsRef = useRef([]);
+    const trackedBlocksRef = useRef(new Map());
+    const trackedWrappersRef = useRef(new Map());
+    const lastContextsRef = useRef(new Map());
+    const currentPagePosRef = useRef(currentPagePos);
+    const visibleZoneRef = useRef(visibleZone);
+    const probeRef = useRef(null);
     // Sticky blocks calculations
     useEffect(() => {
         setStickyBlocks(consolidateStickyBlocks(pages));
     }, [pages]);
     const lazyLoadedBackBlocks = lazyLoadedBlocks(stickyBlocks, 'back', currentPagePos, stickyBlocksLazyLoadDistance);
     const lazyLoadedFrontBlocks = lazyLoadedBlocks(stickyBlocks, 'front', currentPagePos, stickyBlocksLazyLoadDistance);
+    // Tracked blocks, keyed the same way their wrappers are
+    const displayZones = blockDisplayZones(pages);
+    const trackedBlocks = new Map();
+    for (const [blockId, block] of stickyBlocks) {
+        if (block.onScrolled === undefined)
+            continue;
+        trackedBlocks.set(stickyKey(blockId), {
+            displayZone: block.id === undefined
+                ? block.displayOnPages
+                : displayZones.get(block.id) ?? block.displayOnPages,
+            onScrolled: block.onScrolled
+        });
+    }
+    pages?.forEach((page, pagePos) => {
+        scrollBlocksOf(page).forEach((block, blockPos) => {
+            if (block.onScrolled === undefined)
+                return;
+            trackedBlocks.set(scrollKey(pagePos, blockPos), {
+                displayZone: block.id === undefined
+                    ? [pagePos]
+                    : displayZones.get(block.id) ?? [pagePos],
+                onScrolled: block.onScrolled
+            });
+        });
+    });
+    const hasTrackedBlocks = trackedBlocks.size > 0;
+    // Fx. no dep. - Keep what the per-frame pass reads in sync with the last render
+    useEffect(() => {
+        trackedBlocksRef.current = trackedBlocks;
+        currentPagePosRef.current = currentPagePos;
+        visibleZoneRef.current = visibleZone;
+    });
+    // Re-reads the probe, and only disturbs the render if the zone actually moved.
+    const readVisibleZone = useCallback(() => {
+        const probe = probeRef.current;
+        if (probe === null)
+            return;
+        const zone = toVisibleZoneRect(probe.getBoundingClientRect());
+        if (visibleZonesAreEqual(zone, visibleZoneRef.current))
+            return;
+        setVisibleZone(zone);
+    }, []);
+    // The per-frame pass: measure only the pages the displayed tracked blocks span,
+    // then hand each block its context — once, and only when something moved.
+    const handleScrolled = useCallback(() => {
+        const trackedBlocks = trackedBlocksRef.current;
+        const lastContexts = lastContextsRef.current;
+        const currentPage = currentPagePosRef.current;
+        const pending = [];
+        for (const [key, block] of trackedBlocks) {
+            if (block.displayZone.includes(currentPage))
+                pending.push([key, block, currentPage]);
+        }
+        // A block that just left the current page gets one last pass, on the page it was
+        // on: its progressions are clamped, so it lands on the edge it crossed instead of
+        // freezing part-way.
+        for (const [key, lastContext] of lastContexts) {
+            const block = trackedBlocks.get(key);
+            if (block === undefined) {
+                lastContexts.delete(key);
+                continue;
+            }
+            if (block.displayZone.includes(currentPage))
+                continue;
+            pending.push([key, block, lastContext.currentPage]);
+        }
+        if (pending.length === 0)
+            return;
+        const pagesToMeasure = new Set();
+        for (const [, block, page] of pending) {
+            pagesToMeasure.add(page);
+            for (const pagePos of block.displayZone)
+                pagesToMeasure.add(pagePos);
+        }
+        const thresholdY = toThresholdY(visibleZoneRef.current, thresholdOffsetPercent);
+        const metrics = measurePages(pageElementsRef.current, pagesToMeasure, thresholdY);
+        for (const [key, block, page] of pending) {
+            const context = toTrackedBlockContext(block.displayZone, page, metrics);
+            const lastContext = lastContexts.get(key);
+            if (contextsAreEqual(context, lastContext))
+                continue;
+            const wrapper = trackedWrappersRef.current.get(key);
+            if (wrapper !== undefined) {
+                for (const [name, value] of Object.entries(toTrackedBlockCssProps(context))) {
+                    wrapper.style.setProperty(name, value);
+                }
+                // Discrete values only move with the page, so they don't need a write per frame
+                if (!sameDiscretePart(context, lastContext)) {
+                    for (const [name, value] of Object.entries(toTrackedBlockDataAttributes(context))) {
+                        wrapper.setAttribute(name, value);
+                    }
+                }
+            }
+            block.onScrolled(context);
+            if (page === currentPage)
+                lastContexts.set(key, context);
+            else
+                lastContexts.delete(key);
+        }
+    }, [thresholdOffsetPercent]);
+    // Fx. dep. hasTrackedBlocks, handleScrolled - Join the shared scroll listener, and
+    // only then: no tracked block, no measurement pass at all.
+    useEffect(() => {
+        if (!hasTrackedBlocks)
+            return;
+        const subscriptionId = subscriptionIdRef.current;
+        subscribe(subscriptionId, {
+            rootRef,
+            onScrollStateChange: handleScrolled
+        });
+        return () => unsubscribe(subscriptionId);
+    }, [hasTrackedBlocks, handleScrolled]);
+    // Fx. dep. isOnScreen, readVisibleZone - Catch what the probe's ResizeObserver
+    // cannot: a restyle that moves the visible zone without resizing it, say a top
+    // offset traded for an equal bottom one. Only runs while the component is on
+    // screen, and only touches state when the zone actually moved.
+    const isOnScreen = topVisible || contentVisible || bottomVisible;
+    useEffect(() => {
+        if (!isOnScreen)
+            return;
+        const interval = window.setInterval(readVisibleZone, visibleZonePollInterval);
+        return () => window.clearInterval(interval);
+    }, [isOnScreen, readVisibleZone]);
     // Handlers
     useChangeDispatch(currentPagePos, pagePos => onPageChanged?.(pagePos, pages?.[pagePos]));
     useChangeDispatch(contentVisible, onContentVisibilityChanged);
@@ -82,6 +265,21 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
             return;
         setCurrentPagePos(curPagePos);
     };
+    const handlePageElementsChanged = elements => {
+        pageElementsRef.current = elements;
+    };
+    // Registers a block wrapper under the key its context is tracked by. Blocks come
+    // and go with lazy loading, so the map is kept clean on unmount rather than grown.
+    const registerWrapper = (key) => (element) => {
+        if (element === null)
+            trackedWrappersRef.current.delete(key);
+        else
+            trackedWrappersRef.current.set(key, element);
+    };
+    const handleProbeResized = ({ entry, boundingClientRect }) => {
+        probeRef.current = entry.target;
+        setVisibleZone(toVisibleZoneRect(boundingClientRect));
+    };
     const handleResize = ({ boundingClientRect }) => {
         if (partialBoundingRect === undefined
             || boundingClientRect.left !== partialBoundingRect.left
@@ -100,25 +298,31 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         'force-stick-blocks-after': forceStickBlocks === 'after',
         'force-stick-blocks-both': forceStickBlocks === 'both'
     }), className);
-    const customCssProps = toScreenCssProps(partialBoundingRect);
-    return _jsx("div", { className: rootClss, "data-current-page-pos": currentPagePos, "data-current-page-id": pages?.[currentPagePos]?.id, style: { ...customCssProps }, children: _jsxs(ResizeObserverComponent, { onResized: handleResize, children: [_jsx("div", { className: c('top-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleTopBoundDetect }) }), _jsx("div", { className: c('back-blocks'), children: lazyLoadedBackBlocks.map((block, blockPos) => {
-                        const isActive = block.displayOnPages.includes(currentPagePos);
-                        const blockClss = c('back-block', {
-                            active: isActive,
-                            'lazy-loaded': !isActive
-                        });
-                        return _jsx("div", { className: blockClss, style: { zIndex: blockPos }, children: block.children });
-                    }) }), _jsx("div", { className: c('front-blocks'), children: lazyLoadedFrontBlocks.map((block, blockPos) => {
-                        const isActive = block.displayOnPages.includes(currentPagePos);
-                        const blockClss = c('front-block', {
-                            active: isActive,
-                            'lazy-loaded': !isActive
-                        });
-                        return _jsx("div", { className: blockClss, style: { zIndex: blockPos }, children: block.children });
-                    }) }), _jsx("div", { className: c('scrolling-content'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: thresholdOffsetPercent, onPagesChanged: handlePagesChanged, children: pages?.map(page => {
-                                const scrollBlocks = page.blocks
-                                    ?.filter(b => b.depth === 'scroll' || b.depth === undefined) ?? [];
-                                // eslint-disable-next-line @typescript-eslint/promise-function-async
-                                return _jsx(_Fragment, { children: scrollBlocks.map(b => b.children) });
-                            }) }) }) }), _jsx("div", { className: c('bottom-bound'), children: _jsx(IntersectionObserverComponent, { onIntersected: handleBtmBoundDetect }) })] }) });
+    const customCssProps = {
+        ...toScreenCssProps(partialBoundingRect, visibleZone),
+        ...toViewportOffsetCssProps({
+            top: viewportOffsetTop,
+            right: viewportOffsetRight,
+            bottom: viewportOffsetBottom,
+            left: viewportOffsetLeft
+        })
+    };
+    const visibleZoneRootMargin = toVisibleZoneRootMargin(visibleZone);
+    return _jsxs("div", { ref: rootRef, className: rootClss, "data-current-page-pos": currentPagePos, "data-current-page-id": pages?.[currentPagePos]?.id, style: { ...customCssProps }, children: [_jsx(ResizeObserverComponent, { className: c('viewport-probe'), onResized: handleProbeResized }), _jsxs(ResizeObserverComponent, { onResized: handleResize, children: [_jsx("div", { className: c('top-bound'), children: _jsx(IntersectionObserverComponent, { rootMargin: visibleZoneRootMargin, onIntersected: handleTopBoundDetect }) }), _jsx("div", { className: c('back-blocks'), children: lazyLoadedBackBlocks.map(([blockId, block], blockPos) => {
+                            const isActive = block.displayOnPages.includes(currentPagePos);
+                            const blockClss = c('back-block', {
+                                active: isActive,
+                                'lazy-loaded': !isActive
+                            });
+                            return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
+                        }) }), _jsx("div", { className: c('front-blocks'), children: lazyLoadedFrontBlocks.map(([blockId, block], blockPos) => {
+                            const isActive = block.displayOnPages.includes(currentPagePos);
+                            const blockClss = c('front-block', {
+                                active: isActive,
+                                'lazy-loaded': !isActive
+                            });
+                            return _jsx("div", { ref: registerWrapper(stickyKey(blockId)), className: blockClss, style: { zIndex: blockPos }, children: block.children }, blockId);
+                        }) }), _jsx("div", { className: c('scrolling-content'), children: _jsx(IntersectionObserverComponent, { rootMargin: visibleZoneRootMargin, onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: toPaginatorThresholdPercent(visibleZone, thresholdOffsetPercent), onPagesChanged: handlePagesChanged, onPageElementsChanged: handlePageElementsChanged, children: pages?.map((page, pagePos) => {
+                                    return _jsx(_Fragment, { children: scrollBlocksOf(page).map((block, blockPos) => _jsx("div", { ref: registerWrapper(scrollKey(pagePos, blockPos)), className: c('scroll-block'), children: block.children }, blockPos)) });
+                                }) }) }) }), _jsx("div", { className: c('bottom-bound'), children: _jsx(IntersectionObserverComponent, { rootMargin: visibleZoneRootMargin, onIntersected: handleBtmBoundDetect }) })] })] });
 };

package/components/Scrllgngn/styles.module.css

@@ -1,5 +1,30 @@
 .root {
   position: relative;
+
+  /*
+  The visible zone's height, derived from the offsets rather than measured: CSS
+  already knows them, and reading them back from JS would only add a frame of lag.
+  */
+  --PRIVATE-viewport-height: calc(
+    100vh
+    - var(--PRIVATE-viewport-offset-top)
+    - var(--PRIVATE-viewport-offset-bottom)
+  );
+}
+
+/*
+Measured, never seen: its box is the visible zone, and observing it is how a CSS
+length written by the consumer — a var, a clamp, a breakpoint — reaches JavaScript.
+*/
+.viewport-probe {
+  position: fixed;
+  top: var(--PRIVATE-viewport-offset-top);
+  right: var(--PRIVATE-viewport-offset-right);
+  bottom: var(--PRIVATE-viewport-offset-bottom);
+  left: var(--PRIVATE-viewport-offset-left);
+  visibility: hidden;
+  pointer-events: none;
+  z-index: -1;
 }
 
 /* MAIN LAYOUTS (back / front blocks, scrolling content) */
@@ -30,7 +55,7 @@
   top: 0;
   left: 0;
   right: 0;
-  height: 100vh;
+  height: var(--PRIVATE-viewport-height);
 }
 
 /*
@@ -51,20 +76,20 @@ Force stick blocks option
 .root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .back-blocks,
 .root.root--bottom-visible.root--content-visible.root--force-stick-blocks-both .front-blocks {
   position: fixed;
-  top: 0;
+  top: var(--PRIVATE-viewport-offset-top);
   left: var(--PRIVATE-left);
   width: var(--PRIVATE-width);
-  height: 100vh;
+  height: var(--PRIVATE-viewport-height);
 }
 
 /* Scrllgngn leaving the viewport, blocks not fixed but have offset */
 .root.root--bottom-visible.root--content-visible .back-blocks,
 .root.root--bottom-visible.root--content-visible .front-blocks {
   position: absolute;
-  top: calc(var(--PRIVATE-height) - 100vh);
+  top: calc(var(--PRIVATE-height) - var(--PRIVATE-viewport-height));
   left: 0;
   right: 0;
-  height: 100vh;
+  height: var(--PRIVATE-viewport-height);
 }
 
 /* INDIVIDUAL FIXED BLOCKS */