@design-edito/tools 0.5.6 → 0.5.7

package/agnostic/subtitles/srt-timecode-to-ms/index.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { srtTimecodeToMs } from './index.js';
+describe('srtTimecodeToMs', () => {
+    it('adds up hours, minutes, seconds and milliseconds', () => {
+        expect(srtTimecodeToMs('01:02:03,004')).toBe(3723004);
+    });
+    it('sits at zero for the start of a file', () => {
+        expect(srtTimecodeToMs('00:00:00,000')).toBe(0);
+    });
+    describe('the fractional field', () => {
+        it('reads a single digit as tenths of a second', () => {
+            expect(srtTimecodeToMs('00:00:01,5')).toBe(1500);
+        });
+        it('reads two digits as hundredths', () => {
+            expect(srtTimecodeToMs('00:00:01,05')).toBe(1050);
+        });
+        it('reads three digits as milliseconds', () => {
+            expect(srtTimecodeToMs('00:00:01,005')).toBe(1005);
+        });
+        it('drops precision the format does not carry', () => {
+            expect(srtTimecodeToMs('00:00:01,5009')).toBe(1500);
+        });
+    });
+    it('tolerates surrounding whitespace, as found around an arrow', () => {
+        expect(srtTimecodeToMs(' 00:00:02,000 ')).toBe(2000);
+    });
+    it('accepts hour counts beyond two digits', () => {
+        expect(srtTimecodeToMs('100:00:00,000')).toBe(360000000);
+    });
+    describe('refusing what is not a timecode', () => {
+        it('returns null on a dot separator, which SRT does not use', () => {
+            expect(srtTimecodeToMs('00:00:01.500')).toBeNull();
+        });
+        it('returns null on a missing field', () => {
+            expect(srtTimecodeToMs('00:01,000')).toBeNull();
+        });
+        it('returns null on plain text', () => {
+            expect(srtTimecodeToMs('Bonjour')).toBeNull();
+        });
+        it('returns null rather than zero, so a caller can tell the two apart', () => {
+            expect(srtTimecodeToMs('')).toBeNull();
+        });
+    });
+});

package/agnostic/time/dates/index.d.ts

@@ -1,2 +1,2 @@
-export * as formatDate from './format-date/index.js'
 export * as toFrenchRepublican from './to-french-republican/index.js'
+export * as formatDate from './format-date/index.js'

package/agnostic/time/dates/index.js

@@ -1,2 +1,2 @@
-export * as formatDate from './format-date/index.js'
 export * as toFrenchRepublican from './to-french-republican/index.js'
+export * as formatDate from './format-date/index.js'

package/components/ListLoader/index.controlled.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import type { ViewportObserverOptions, WithClassName } from '../utils/types.js';
 /**
  * Props for the {@link ControlledListLoader} component.
  *
@@ -26,9 +26,14 @@ import type { WithClassName } from '../utils/types.js';
  * @property autoLoadPrevWhenVisible - Wraps the leading load button in an
  * {@link IntersectionObserverComponent} and fires `onLoadPageClicked` when it enters the viewport.
  * @property autoLoadNextWhenVisible - Same, for the trailing load button.
+ * @property threshold - How much of a load button has to be in view before it
+ * counts as visible, forwarded to each observer.
+ * @property root - Their root. Defaults to the viewport.
+ * @property rootMargin - Grows or shrinks that root before measuring — the way to
+ * start loading a page before its button actually shows.
  * @property className - Additional class name(s) applied to the root element.
  */
-export type Props<T> = WithClassName<{
+export type Props<T> = WithClassName<ViewportObserverOptions & {
     pages: number[];
     firstPagePos: number;
     lastPagePos: number;
@@ -75,4 +80,4 @@ export type Props<T> = WithClassName<{
  * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
  * an earlier duplicate.
  */
-export declare const ControlledListLoader: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }: Props<T>) => ReactNode;
+export declare const ControlledListLoader: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin }: Props<T>) => ReactNode;

package/components/ListLoader/index.controlled.js

@@ -39,7 +39,7 @@ import cssModule from './styles.module.css';
  * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
  * an earlier duplicate.
  */
-export const ControlledListLoader = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }) => {
+export const ControlledListLoader = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin }) => {
     const inBoundsPages = pages.filter(pagePos => pagePos >= firstPagePos && pagePos <= lastPagePos);
     const filteredItems = Array.from(itemsPages)
         .filter(([pagePos]) => inBoundsPages.includes(pagePos))
@@ -85,7 +85,7 @@ export const ControlledListLoader = ({ className, pages, firstPagePos, lastPageP
             || (kind === 'next' && autoLoadNextWhenVisible === true);
         if (!autoLoads)
             return button;
-        return _jsx(IntersectionObserverComponent, { className: c('load-observer', kind), onIntersected: ({ ioEntry }) => {
+        return _jsx(IntersectionObserverComponent, { className: c('load-observer', kind), threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: ({ ioEntry }) => {
                 if (ioEntry?.isIntersecting !== true)
                     return;
                 onLoadPageClicked?.(pagePos);

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/Scrllgngn/index.d.ts

@@ -1,6 +1,6 @@
 import { type PropsWithChildren, type FunctionComponent } from 'react';
 import type { WithClassName } from '../utils/types.js';
-import { type TrackedBlockContext } from './utils.js';
+import { type TrackedBlockContext, type ViewportOffset } from './utils.js';
 /**
  * Common properties shared by all block types.
  *
@@ -62,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`.
@@ -85,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;
@@ -125,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.
@@ -156,11 +178,19 @@ export type Props = WithClassName<{
  *
  * @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.

package/components/Scrllgngn/index.js

@@ -8,7 +8,7 @@ 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 { blockDisplayZones, consolidateStickyBlocks, contextsAreEqual, lazyLoadedBlocks, measurePages, sameDiscretePart, scrollBlocksOf, scrollKey, stickyKey, toScreenCssProps, toTrackedBlockContext, toTrackedBlockCssProps, toTrackedBlockDataAttributes } 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`
@@ -45,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.
@@ -76,16 +86,24 @@ import cssModule from './styles.module.css';
  *
  * @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);
@@ -93,6 +111,7 @@ 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.
@@ -103,6 +122,8 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     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));
@@ -139,7 +160,18 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
     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(() => {
@@ -172,7 +204,8 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
             for (const pagePos of block.displayZone)
                 pagesToMeasure.add(pagePos);
         }
-        const metrics = measurePages(pageElementsRef.current, pagesToMeasure, thresholdOffsetPercent);
+        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);
@@ -209,6 +242,17 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         });
         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);
@@ -232,6 +276,10 @@ export const Scrllgngn = ({ pages, thresholdOffsetPercent, stickyBlocksLazyLoadD
         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
@@ -250,22 +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", { ref: rootRef, 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(([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, { onIntersected: handleCntDetect, children: _jsx(Paginator, { thresholdOffsetPercent: 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, { 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 */

package/components/Scrllgngn/utils.d.ts

@@ -48,10 +48,16 @@ export declare function lazyLoadedBlocks(blocks: Map<string, ConsolidatedStickyB
  * never inherit the same names from an ancestor component. `initial` leaves them
  * behaving exactly as an unset variable would, without opening the hole.
  *
+ * The public set describes the component's own box and nothing else. The private
+ * one is narrowed to what the fixed layers may actually occupy — the component's
+ * box **intersected** with the visible zone — so a viewport offset pushes them off
+ * whatever covers that edge without the stylesheet doing arithmetic.
+ *
  * @param rect - The measured bounding rect, absent until the first resize lands.
+ * @param zone - The measured visible zone, absent until the probe reports.
  * @returns The custom properties, keyed by their full name.
  */
-export declare function toScreenCssProps(rect?: ScreenRect): Record<string, string>;
+export declare function toScreenCssProps(rect?: ScreenRect, zone?: VisibleZoneRect): Record<string, string>;
 /**
  * Where one tracked block stands in the scroll, as handed to its `onScrolled`.
  *
@@ -119,11 +125,11 @@ export declare function contiguousRunContaining(zone: number[], page: number): n
  *
  * @param pageElements - Every page slot, indexed by position.
  * @param pagePositions - The positions worth measuring.
- * @param thresholdOffsetPercent - The same offset the internal `Paginator` uses,
- * as a percentage of the viewport height.
+ * @param thresholdY - The threshold line, in pixels from the viewport top. See
+ * {@link toThresholdY}.
  * @returns The metrics of each measurable page, keyed by position.
  */
-export declare function measurePages(pageElements: HTMLElement[], pagePositions: Iterable<number>, thresholdOffsetPercent?: number): Map<number, PageScrollMetrics>;
+export declare function measurePages(pageElements: HTMLElement[], pagePositions: Iterable<number>, thresholdY: number): Map<number, PageScrollMetrics>;
 /**
  * Assembles what one tracked block is told about the scroll.
  *
@@ -185,3 +191,80 @@ export declare function scrollKey(pagePos: number, blockPos: number): string;
  * @returns Its scroll blocks, in order. `depth` left out means `'scroll'`.
  */
 export declare function scrollBlocksOf(page: PropsPage): PropsBlock[];
+/** How much of each viewport edge is covered by something else, in pixels. */
+export type VisibleZoneRect = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    width: number;
+    height: number;
+};
+/** A length as authored: a bare number means pixels, a string is CSS's problem. */
+export type ViewportOffset = number | string;
+/** The four edges, as authored on the component. */
+export type ViewportOffsets = {
+    top?: ViewportOffset;
+    right?: ViewportOffset;
+    bottom?: ViewportOffset;
+    left?: ViewportOffset;
+};
+/**
+ * Builds the custom properties carrying the visible zone's insets.
+ *
+ * They are emitted whatever the props hold, `0px` standing in for an edge left
+ * unset: the probe and the fixed layers position themselves against them, and an
+ * absent name would let an enclosing component's value inherit through.
+ *
+ * @param offsets - The edges as authored.
+ * @returns The custom properties, keyed by their full name.
+ */
+export declare function toViewportOffsetCssProps(offsets: ViewportOffsets): Record<string, string>;
+/**
+ * Reads the visible zone off the probe element.
+ *
+ * The probe is fixed and inset by the four offsets, so its rect *is* the zone —
+ * which is how a `var()`, a `clamp()` or a breakpoint-dependent length reaches
+ * JavaScript without anyone parsing a CSS length.
+ *
+ * @param probeRect - The probe's bounding rect.
+ * @returns The zone, as insets from each viewport edge plus its own size.
+ */
+export declare function toVisibleZoneRect(probeRect: DOMRect): VisibleZoneRect;
+/**
+ * Shrinks an {@link IntersectionObserver} root down to the visible zone.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @returns A `rootMargin`, or `undefined` to leave the observer on the full
+ * viewport.
+ */
+export declare function toVisibleZoneRootMargin(zone?: VisibleZoneRect): string | undefined;
+/**
+ * Places the threshold line, in pixels from the viewport top.
+ *
+ * `thresholdOffsetPercent` reads as a percentage **of the visible zone**, not of
+ * the viewport: a threshold at 50% has to sit halfway down what the reader can
+ * actually see, or it lands under whatever covers the top of the screen.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The line's distance from the viewport top.
+ */
+export declare function toThresholdY(zone?: VisibleZoneRect, thresholdOffsetPercent?: number): number;
+/**
+ * Restates the threshold as the percentage of the **viewport** an
+ * {@link IntersectionObserver} needs, since that is the only frame `rootMargin`
+ * knows.
+ *
+ * With no offsets set the zone spans the viewport and the number comes back
+ * unchanged, so nothing moves for a component that never asked for any of this.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The equivalent viewport percentage, to hand to the internal `Paginator`.
+ */
+export declare function toPaginatorThresholdPercent(zone?: VisibleZoneRect, thresholdOffsetPercent?: number): number | undefined;
+/** How often the visible zone is re-read while the component is on screen, in ms. */
+export declare const visibleZonePollInterval = 100;
+/** Whether two zones hold the same six measurements. */
+export declare function visibleZonesAreEqual(a?: VisibleZoneRect, b?: VisibleZoneRect): boolean;