react-motion-gallery 2.0.75 → 2.0.77

package/README.md

@@ -11,15 +11,19 @@ This table reports local gzip measurements for selected runtime surfaces. Type-o
 <!-- bundle-size:start -->
 | Surface | JS gzip |
 | --- | --- |
-| `Entries` | 12.2kB |
-| `entries/cache` | 16.9kB |
+| `Entries` | 12.3kB |
+| `entries/cache` | 17.0kB |
 | `FullscreenThumbnailSlider` | 20.3kB |
 | `GalleryCore` | 2.6kB |
-| `Grid` | 6.4kB |
+| `Grid` | 5.4kB |
 | `grid/ready` | 323.0B |
 | `grid/lazy-load` | 3.3kB |
-| `Masonry` | 7.2kB |
+| `grid/fullscreen` | 1.6kB |
+| `Masonry` | 4.2kB |
 | `masonry/ready` | 323.0B |
+| `masonry/fullscreen` | 1.1kB |
+| `masonry/measured` | 7.2kB |
+| `masonry/measured/ready` | 323.0B |
 | `masonry/lazy-load` | 3.3kB |
 | `Skeleton base` | 8.9kB |
 | `skeleton/cache/base` | 13.6kB |
@@ -28,8 +32,10 @@ This table reports local gzip measurements for selected runtime surfaces. Type-o
 | `skeleton/slider/restore` | 25.2kB |
 | `skeleton/grid` | 11.2kB |
 | `skeleton/cache/grid` | 16.0kB |
-| `skeleton/masonry` | 20.1kB |
-| `skeleton/cache/masonry` | 25.3kB |
+| `skeleton/masonry` | 4.4kB |
+| `skeleton/cache/masonry` | 4.4kB |
+| `skeleton/masonry/structured` | 20.2kB |
+| `skeleton/cache/masonry/structured` | 25.3kB |
 | `Slider core` | 19.0kB |
 | `slider/ready` | 894.0B |
 | `slider/arrows` | 1.2kB |
@@ -49,11 +55,11 @@ This table reports local gzip measurements for selected runtime surfaces. Type-o
 | `fullscreen/controls` | 173.0B |
 | `fullscreen/captions` | 13.2kB |
 | `fullscreen/zoom-pan` | 12.4kB |
-| `fullscreen/video` | 16.4kB |
+| `fullscreen/video` | 16.5kB |
 | `fullscreen/lazy-load` | 13.2kB |
 | `fullscreen/crossfade` | 181.0B |
 | `fullscreen/thumbnails` | 160.0B |
-| `Video` | 12.7kB |
+| `Video` | 12.8kB |
 | `ZoomPanImage` | 11.0kB |
 | `zoomPan/hover` | 124.0B |
 | `media / toMediaItems` | 260.0B |
@@ -64,10 +70,15 @@ This table reports local gzip measurements for selected runtime surfaces. Type-o
 
 ## Installation
 
-Install the package, then add the optional video peers only if you use `Video`.
+Install the package:
 
 ```bash
 npm install react-motion-gallery
+```
+
+If you use `Video` or fullscreen video playback, also install the optional Plyr peers:
+
+```bash
 npm install plyr plyr-react
 ```
 
@@ -77,6 +88,12 @@ Import the stylesheet. The package uses CSS Modules internally, but consumers on
 import "react-motion-gallery/styles.css";
 ```
 
+Most examples in this README use hooks, event handlers, or browser-only behavior. In Next.js App Router, put those components in a client file with `"use client";`; server components can still prepare media data and pass it down.
+
+## License
+
+React Motion Gallery is licensed under `PolyForm-Noncommercial-1.0.0`. Non-commercial use is free. Commercial use requires a paid license; see [react-motion-gallery.com/license](https://react-motion-gallery.com/license).
+
 ## Overview
 
 Mental model:
@@ -160,21 +177,27 @@ Subpaths give bundlers a smaller graph than the root. Less JS to transfer, parse
 | `react-motion-gallery/grid` | `Grid`, `Grid.Item`, grid types |
 | `react-motion-gallery/grid/ready` | `useGridReady` |
 | `react-motion-gallery/grid/lazy-load` | `gridLazyLoad` |
+| `react-motion-gallery/grid/fullscreen` | `gridFullscreen` for Grid + `GalleryCore` |
 | `react-motion-gallery/masonry` | `Masonry`, `Masonry.Item`, masonry types |
 | `react-motion-gallery/masonry/ready` | `useMasonryReady` |
+| `react-motion-gallery/masonry/fullscreen` | `masonryFullscreen` for light Masonry + `GalleryCore` |
+| `react-motion-gallery/masonry/measured` | Measured `Masonry`, `Masonry.Item`, plugins/reveal/fullscreen types |
+| `react-motion-gallery/masonry/measured/ready` | `useMasonryReady` for measured masonry |
 | `react-motion-gallery/masonry/lazy-load` | `masonryLazyLoad` |
 | `react-motion-gallery/entries` | `Entries`, `flattenEntries`, entry media container helpers |
 | `react-motion-gallery/entries/cache` | `CachedEntries` with `entries.loading.cache` |
 | `react-motion-gallery/skeleton/base` | Standalone `Skeleton` and generic skeleton authoring types |
 | `react-motion-gallery/skeleton/slider` | `SliderSkeleton` and slider skeleton authoring types |
 | `react-motion-gallery/skeleton/grid` | `GridSkeleton` and grid skeleton authoring types |
-| `react-motion-gallery/skeleton/masonry` | `MasonrySkeleton` and masonry skeleton authoring types |
+| `react-motion-gallery/skeleton/masonry` | Lightweight `MasonrySkeleton` for dimensioned placeholders |
+| `react-motion-gallery/skeleton/masonry/structured` | Structured `MasonrySkeleton` and masonry skeleton authoring types |
 | `react-motion-gallery/skeleton/cache` | Server-safe skeleton cookie cache helpers and types |
 | `react-motion-gallery/skeleton/cache/provider` | Client `SkeletonCacheProvider` for SSR snapshots and client cookie refresh |
 | `react-motion-gallery/skeleton/cache/base` | `CachedSkeleton` with `cache` |
 | `react-motion-gallery/skeleton/cache/slider` | `CachedSliderSkeleton` with `cache` |
 | `react-motion-gallery/skeleton/cache/grid` | `CachedGridSkeleton` with `cache` |
-| `react-motion-gallery/skeleton/cache/masonry` | `CachedMasonrySkeleton` with `cache` |
+| `react-motion-gallery/skeleton/cache/masonry` | Lightweight `CachedMasonrySkeleton` |
+| `react-motion-gallery/skeleton/cache/masonry/structured` | Structured `CachedMasonrySkeleton` with `cache` |
 | `react-motion-gallery/skeleton/slider/restore` | `RestoredSliderSkeleton` with `restore` and optional `cache` |
 | `react-motion-gallery/fullscreen` | `useFullscreenController` and fullscreen types |
 | `react-motion-gallery/fullscreen/slider` | `fullscreenSlider` |
@@ -544,9 +567,9 @@ Wrap the client tree in `SkeletonCacheProvider`, then opt individual skeletons i
 
 import type { SkeletonCacheSnapshot } from "react-motion-gallery/skeleton/cache";
 import { SkeletonCacheProvider } from "react-motion-gallery/skeleton/cache/provider";
-import { CachedMasonrySkeleton as MasonrySkeleton } from "react-motion-gallery/skeleton/cache/masonry";
-import { Masonry } from "react-motion-gallery/masonry";
-import { useMasonryReady } from "react-motion-gallery/masonry/ready";
+import { CachedMasonrySkeleton as MasonrySkeleton } from "react-motion-gallery/skeleton/cache/masonry/structured";
+import { Masonry } from "react-motion-gallery/masonry/measured";
+import { useMasonryReady } from "react-motion-gallery/masonry/measured/ready";
 
 export function GalleryPageClient({
   skeletonCacheSnapshots,
@@ -784,6 +807,7 @@ export function BasicSlider() {
 | `scroll.strictSnaps` | `boolean` | `false` | Prevents one drag release from settling more than one snap away from where the drag started. Overrides `scroll.skipSnaps`. |
 | `scroll.freeScroll` | `boolean` | `false` | Enables free dragging instead of strict snapping. |
 | `scroll.loop` | `boolean` | `false` | Wraps around at the ends. |
+| `scroll.containScroll` | `boolean` | `false` | Clamps start/end snaps so non-looping variable-width or centered sliders do not leave excess empty space at the track edges. |
 
 `scroll.groupCells` affects the snap pages used by drag, wheel, arrows, dots, and imperative navigation. Use `true` for automatic fit-to-viewport grouping, or a count for explicit snap pages:
 
@@ -1303,8 +1327,8 @@ export function BasicGrid() {
 | `gap` | `number \| Record<string, number>` | `8` | Responsive grid gap. |
 | `rootClassName` | `string` | `—` | Class name for the grid root. |
 | `itemClassName` | `string` | `—` | Class name added to each wrapped grid item. |
-| `fullscreenTrigger` | `"item" \| "media"` | `"media"` | Opens fullscreen from the clicked media node or the entire item shell. |
-| `plugins` | `GridPlugin[]` | `[]` | Explicit first-party Grid features such as lazy-load. |
+| `fullscreenTrigger` | `"item" \| "media"` | `"media"` | When `gridFullscreen()` is active, opens fullscreen from the clicked media node or the entire item shell. |
+| `plugins` | `GridPlugin[]` | `[]` | Explicit first-party Grid features such as lazy-load and fullscreen. |
 | `reveal.renderReveal` | `({ active, containerProps }, content) => ReactNode` | `—` | Custom reveal wrapper. |
 | `reveal.staggerMs` | `number` | `60` | Reveal stagger for the fade-in. |
 | `reveal.durationMs` | `number` | `600` | Reveal fade duration. |
@@ -1318,17 +1342,19 @@ Import Grid plugins from their own subpaths and pass them to `plugins`.
 ```typescript
 import { Grid } from "react-motion-gallery/grid";
 import { gridLazyLoad } from "react-motion-gallery/grid/lazy-load";
+import { gridFullscreen } from "react-motion-gallery/grid/fullscreen";
 
-<Grid plugins={[gridLazyLoad({ spinner: true })]}>{items}</Grid>;
+<Grid plugins={[gridLazyLoad({ spinner: true }), gridFullscreen()]}>{items}</Grid>;
 ```
 
 | Import | Factory | Notes |
 | --- | --- | --- |
 | `react-motion-gallery/grid/lazy-load` | `gridLazyLoad(options)` | Rewrites trackable image `src` values into `data-rmg-lazy-src`, reveals them on viewport intersection, then fades them in after decode and spinner exit. |
+| `react-motion-gallery/grid/fullscreen` | `gridFullscreen()` | Opens `GalleryCore` fullscreen from Grid items without adding fullscreen code to the default grid import. |
 
 `gridLazyLoad()` enables lazy loading by default. Pass `{ enabled: false }` to make the plugin inert.
 
-Grid fullscreen behavior is provided by `GalleryCore` and `useFullscreenController`; Grid itself does not expose a ref-based imperative API.
+Grid fullscreen behavior is provided by `GalleryCore`, `useFullscreenController`, and the opt-in `gridFullscreen()` plugin. Grid itself does not expose a ref-based imperative API.
 
 Wrap a card in `Grid.Item` when it should span tracks or needs wrapper styling:
 
@@ -1422,18 +1448,29 @@ function GridWithSkeleton({ images }: { images: { src: string; alt: string }[] }
 ```typescript
 import { Masonry } from "react-motion-gallery";
 
-const cards = [280, 360, 220, 420, 300, 340];
+const images = [
+  { src: "https://picsum.photos/id/1018/1200/1600", width: 1200, height: 1600 },
+  { src: "https://picsum.photos/id/1025/1200/900", width: 1200, height: 900 },
+  { src: "https://picsum.photos/id/1036/1200/1500", width: 1200, height: 1500, span: { 0: 1, 1100: 2 } },
+  { src: "https://picsum.photos/id/1041/1200/800", width: 1200, height: 800 },
+];
 
 export function BasicMasonry() {
   return (
     <Masonry columns={{ 0: 1, 700: 2, 1100: 3 }} gap={{ 0: 12, 1100: 20 }}>
-      {cards.map((height, index) => (
-        <img
-          key={index}
-          src={`https://picsum.photos/seed/masonry-${index}/1000/${height * 3}`}
-          alt={`Masonry item ${index + 1}`}
-          style={{ width: "100%", height, objectFit: "cover", borderRadius: 12 }}
-        />
+      {images.map((image, index) => (
+        <Masonry.Item
+          key={image.src}
+          width={image.width}
+          height={image.height}
+          span={image.span}
+        >
+          <img
+            src={image.src}
+            alt={`Masonry item ${index + 1}`}
+            style={{ width: "100%", height: "100%", objectFit: "cover", borderRadius: 12 }}
+          />
+        </Masonry.Item>
       ))}
     </Masonry>
   );
@@ -1444,7 +1481,7 @@ export function BasicMasonry() {
 
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
-| `children` | `React.ReactNode` | `—` | Masonry items rendered in order. Wrap individual cards in `Masonry.Item` when they need custom spans or wrapper props. |
+| `children` | `React.ReactNode` | `—` | Dimensioned masonry items. Each item should be wrapped in `Masonry.Item`. |
 | `breakpoints` | `Record<string, number>` | `xs: 0, sm: 600, md: 900, lg: 1200, xl: 1536` | Used to resolve responsive columns and gaps. |
 
 ### Masonry.Item props
@@ -1452,6 +1489,8 @@ export function BasicMasonry() {
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `children` | `React.ReactNode` | `—` | The masonry card content. |
+| `width` | `number` | `—` | Intrinsic item width used for aspect-ratio layout. |
+| `height` | `number` | `—` | Intrinsic item height used for aspect-ratio layout. |
 | `span` | `number \| "full" \| Record<string, number \| "full">` | `1` | Per-item track span. `"full"` resolves to the active column count and numeric values clamp to the current track count. |
 | `className` | `string` | `—` | Extra class name merged onto the masonry item wrapper. |
 | `style` | `React.CSSProperties` | `—` | Inline styles merged onto the masonry item wrapper. |
@@ -1463,41 +1502,41 @@ export function BasicMasonry() {
 | `columns` | `number \| Record<string, number>` | `—` | Responsive column count. |
 | `gap` | `number \| Record<string, number>` | `—` | Responsive gap between columns and items. |
 | `placement` | `"balanced" \| "roundRobin" \| "horizontalOrder"` | `"balanced"` | `balanced` packs into the shortest fitting column group, `roundRobin` cycles start columns deterministically, and `horizontalOrder` preserves a stronger left-to-right scan when spans are involved. |
-| `fullscreenTrigger` | `"item" \| "media"` | `"media"` | Opens fullscreen from the clicked media node or the entire masonry item shell. |
-| `itemWrapClassName` | `string` | `—` | Class name added to the masonry item wrapper. |
-| `itemWrapStyle` | `React.CSSProperties` | `—` | Inline styles applied to the masonry item wrapper. |
 | `as` | `React.ElementType` | `"div"` | Root HTML element or custom component. |
 | `rootRef` | `React.Ref<HTMLDivElement>` | `—` | Ref to the masonry root. |
 | `classNames.root` | `string` | `—` | Root class name. |
-| `classNames.column` | `string` | `—` | Retained for backwards compatibility with the legacy column-wrapper renderer. |
 | `classNames.item` | `string` | `—` | Item class name. |
-| `plugins` | `MasonryPlugin[]` | `[]` | Explicit first-party Masonry features such as lazy-load. |
-| `reveal.renderReveal` | `({ active, containerProps }, content) => ReactNode` | `—` | Custom reveal wrapper. |
+| `plugins` | `MasonryPlugin[]` | `[]` | Opt-in light Masonry plugins, currently `masonryFullscreen()` from `react-motion-gallery/masonry/fullscreen`. |
 | `reveal.staggerMs` | `number` | `160` | Reveal stagger for the fade-in. |
 | `reveal.durationMs` | `number` | `600` | Reveal fade duration. |
 | `reveal.easing` | `string` | `"cubic-bezier(.2,.7,.2,1)"` | Reveal fade easing. |
-| `reveal.staggerLimit` | `number` | `—` | Optional cap on how many items stagger. |
+| `reveal.disabled` | `boolean` | `false` | Disables the built-in reveal classes. |
+| `revealReady` | `boolean` | `true` | Holds the reveal until external loading or viewport orchestration is ready. |
 
 ### Masonry plugins
 
-Import Masonry plugins from their own subpaths and pass them to `plugins`.
+Import Masonry plugins from their own subpaths and pass them to `plugins`. The default dimensioned core supports the fullscreen bridge through an opt-in subpath.
 
 ```typescript
+import { GalleryCore } from "react-motion-gallery/core";
 import { Masonry } from "react-motion-gallery/masonry";
-import { masonryLazyLoad } from "react-motion-gallery/masonry/lazy-load";
+import { masonryFullscreen } from "react-motion-gallery/masonry/fullscreen";
 
-<Masonry plugins={[masonryLazyLoad({ spinner: true })]}>{items}</Masonry>;
+<GalleryCore layout="masonry" fullscreenItems={items}>
+  <Masonry plugins={[masonryFullscreen()]}>{children}</Masonry>
+</GalleryCore>;
 ```
 
 | Import | Factory | Notes |
 | --- | --- | --- |
+| `react-motion-gallery/masonry/fullscreen` | `masonryFullscreen()` | Opens `GalleryCore` fullscreen from light dimensioned Masonry items without adding fullscreen code to the default masonry import. |
 | `react-motion-gallery/masonry/lazy-load` | `masonryLazyLoad(options)` | Uses the same image shell behavior as Slider: trackable image `src` values move into `data-rmg-lazy-src`, real images load on intersection, and items fade in after decode and spinner exit. |
 
-`masonryLazyLoad()` enables lazy loading by default. Pass `{ enabled: false }` to make the plugin inert.
+`masonryLazyLoad()` is for measured Masonry and enables lazy loading by default. Pass `{ enabled: false }` to make the plugin inert.
 
-Masonry already accepts arbitrary React children, including text-containing JSX. The wrapper props are only for styling the built-in masonry item shell.
+Measured Masonry accepts arbitrary React children, including text-containing JSX. The wrapper props are only for styling the built-in masonry item shell.
 
-Wrap a card in `Masonry.Item` when it needs its own span, wrapper `className`, or wrapper `style`:
+In the measured subpath, wrap a card in `Masonry.Item` when it needs its own span, wrapper `className`, or wrapper `style`:
 
 ```typescript
 <Masonry
@@ -1522,18 +1561,23 @@ Choose a placement based on what should feel stable:
 
 Masonry no longer owns loading UI. Use `useMasonryReady` and wrap Masonry with `MasonrySkeleton`, the same composition pattern used by Slider and Grid.
 
-Masonry skeletons live in `react-motion-gallery/skeleton/masonry` and can use a structured `layout` spec with the same inner node vocabulary as Grid skeletons, including `text` nodes and `itemWrapStyle`.
+The default Masonry import is dimensioned and lightweight, with built-in reveal timing and opt-in fullscreen through `react-motion-gallery/masonry/fullscreen`. For arbitrary measured card heights, measured lazy-load plugins, and structured skeleton text, import from `react-motion-gallery/masonry/measured` and `react-motion-gallery/skeleton/masonry/structured`.
+
+Lightweight Masonry skeletons live in `react-motion-gallery/skeleton/masonry` and mirror dimensioned `Masonry.Item` data with `items`, `ratios`, or `heightsPx`.
+
+Structured Masonry skeletons live in `react-motion-gallery/skeleton/masonry/structured` and can use a `layout` spec with the same inner node vocabulary as Grid skeletons, including `text` nodes and `itemWrapStyle`.
 
 Live Masonry content mounts invisibly until the current item set has completed an initial measurement pass. The Skeleton wrapper stays visible during that handoff, so the first revealed layout is based on measured DOM geometry rather than approximate height hints.
 
 `layout.slots` gives Masonry the same per-card override escape hatch that slider skeletons have. Use a slot when one card needs a different placeholder tree, wrapper styling, span, or outer height. `slot.span` can override the corresponding `Masonry.Item` span for the placeholder, `slot.ratio` maps to Masonry's card-height rhythm, and `slot.heightPx` lets you pin a specific shell height when you need an exact placeholder.
 
 ```typescript
-import { Masonry, useMasonryReady } from "react-motion-gallery";
+import { Masonry } from "react-motion-gallery/masonry/measured";
+import { useMasonryReady } from "react-motion-gallery/masonry/measured/ready";
 import {
   MasonrySkeleton,
   type MasonrySkeletonSpec,
-} from "react-motion-gallery/skeleton/masonry";
+} from "react-motion-gallery/skeleton/masonry/structured";
 
 const masonrySkeleton: MasonrySkeletonSpec = {
   ratios: [118, 126, 102, 146],
@@ -1675,6 +1719,37 @@ export function EntryGallery() {
 }
 ```
 
+For common entry media layouts, the exported helper factories can own `renderMediaContainer` for you. Use the slider, grid, or masonry helper that matches `entries.mediaLayout`, then keep custom card and media rendering focused on your data shape.
+
+```typescript
+import {
+  Entries,
+  createEntriesGridMedia,
+  type EntriesOptions,
+} from "react-motion-gallery/entries";
+
+const renderEntryGridMedia = createEntriesGridMedia({
+  gridObject: {
+    columns: { 0: 1, 760: 2 },
+    gap: { 0: 10, 760: 14 },
+  },
+});
+
+export function EntryGrid({ entries }: { entries: EntriesOptions["items"] }) {
+  return (
+    <Entries
+      entries={{
+        items: entries,
+        mediaLayout: "grid",
+      }}
+      renderMediaContainer={renderEntryGridMedia}
+    />
+  );
+}
+```
+
+The same pattern works with `createEntriesSliderMedia()` and `createEntriesMasonryMedia()`. Import from `react-motion-gallery/entries/cache` instead when the entry loading skeleton also uses `loading.cache`.
+
 ### Entry loading, decode, and reveal flow
 
 When `loading.enabled` is true, entries use two viewport gates instead of one generic fade-in. `loading.nearMargin` marks a row as near the viewport, mounts the real entry content, and starts the entry media work early. `loading.viewMargin` and `loading.threshold` record when the row has actually entered view.
@@ -1888,6 +1963,7 @@ export function StandaloneFullscreen() {
 import * as React from "react";
 import { GalleryCore, Slider, useFullscreenController } from "react-motion-gallery";
 import { fullscreenSlider } from "react-motion-gallery/fullscreen/slider";
+import { sliderFullscreen } from "react-motion-gallery/slider/fullscreen";
 
 const slides = [
   "https://picsum.photos/id/1015/1600/900",
@@ -1907,7 +1983,7 @@ function FullscreenAddon() {
 export function SliderWithFullscreen() {
   return (
     <GalleryCore layout="slider" fullscreenItems={slides}>
-      <Slider>
+      <Slider plugins={[sliderFullscreen()]}>
         {slides.map((src, index) => (
           <img key={src} src={src} alt={`Slide ${index + 1}`} style={{ width: "100%" }} />
         ))}
@@ -2088,6 +2164,8 @@ The hook returns additional refs and setters for the internal fullscreen runtime
 | `slider.friction` | `number` | `0.68` | Fullscreen slider friction. |
 | `slider.direction` | `"ltr" \| "rtl"` | `"ltr"` | Fullscreen slider interaction direction. |
 | `slider.gap` | `number \| Record<string, number>` | `0` | Responsive pixel gap between fullscreen slides. Named keys resolve from `GalleryCore.breakpoints`. |
+| `slider.skipSnaps` | `boolean \| { enabled?: boolean; threshold?: number }` | `false` | Allows fullscreen drag momentum to skip snap points. Object form matches the base slider `scroll.skipSnaps` behavior. |
+| `slider.strictSnaps` | `boolean` | `false` | Prevents one fullscreen drag release from settling more than one snap away from where the drag started. Overrides `slider.skipSnaps`. |
 | `zoom.clickZoomLevel` | `number` | `2.5` | Zoom level used for click-to-zoom. |
 | `zoom.maxZoomLevel` | `number` | `3` | Maximum allowed zoom level. |
 | `zoom.panDuration` | `number` | `43` | Pan settling duration. |
@@ -2095,6 +2173,7 @@ The hook returns additional refs and setters for the internal fullscreen runtime
 | `effects.introDuration` | `number \| { transform?: number; fade?: number }` | `{ transform: 300, fade: 500 }` | Open and close intro timing. A scalar applies to both paths. Use `transform` for scale/FLIP handoffs and `fade` for opacity-only paths. |
 | `effects.introEasing` | `string \| { transform?: string; fade?: string }` | `"cubic-bezier(.4,0,.22,1)"` | Open and close intro easing. A scalar applies to both paths. Object keys mirror `introDuration`. |
 | `effects.introFade` | `boolean` | `false` | Forces fade intro behavior. |
+| `effects.introStickyNavSelector` | `string` | `—` | Selector for a sticky navigation element that may cover the source image during scale intro or close path calculations. |
 | `effects.crossfade.controls` | `boolean` | `false` | Uses crossfade transitions for fullscreen arrow navigation and animated slide requests. Also enables wheel crossfade unless `effects.crossfade.wheel` is provided. |
 | `effects.crossfade.drag` | `boolean` | `false` | Scrubs adjacent fullscreen slides with crossfade during drag instead of moving the track. |
 | `effects.crossfade.wheel` | `boolean \| CrossFadeWheelOptions` | `effects.crossfade.controls` | Uses wheel or touchpad travel as a one-slide-at-a-time fullscreen crossfade gesture. Set `false` to keep arrow crossfades while using normal wheel scrolling. |