immerser-react 1.0.0

package/dist/immerser-react.js

@@ -0,0 +1,293 @@
+import { jsx } from "react/jsx-runtime";
+import ImmerserController, { InteractiveStyles, CroppedFullAbsoluteStyles, NotInteractiveStyles } from "immerser";
+import { createContext, useRef, useState, useCallback, useLayoutEffect, useEffect, useMemo, useContext, Fragment, Children, isValidElement, cloneElement } from "react";
+import classNames from "classnames";
+const ImmerserConfigContext = createContext(null);
+const ImmerserContext = createContext(null);
+const ImmerserSynchroContext = createContext({
+  activeSynchroId: null,
+  setActiveSynchroId: () => {
+  }
+});
+const useImmerserRegistry = () => {
+  const maskInnerNodesRef = useRef(/* @__PURE__ */ new Map());
+  const [layerIds, setLayerIds] = useState([]);
+  const [, setReadyVersion] = useState(0);
+  const isReady = layerIds.length > 0 && maskInnerNodesRef.current.size === layerIds.length && layerIds.every((layerId) => maskInnerNodesRef.current.has(layerId));
+  const registerLayer = useCallback((id) => {
+    setLayerIds((currentLayerIds) => {
+      if (currentLayerIds.includes(id)) {
+        return currentLayerIds;
+      }
+      return [...currentLayerIds, id];
+    });
+  }, []);
+  const unregisterLayer = useCallback((id) => {
+    setLayerIds((currentLayerIds) => currentLayerIds.filter((layerId) => layerId !== id));
+  }, []);
+  const registerMaskInner = useCallback((id, node) => {
+    if (node) {
+      if (maskInnerNodesRef.current.get(id) === node) {
+        return;
+      }
+      maskInnerNodesRef.current.set(id, node);
+    } else {
+      if (!maskInnerNodesRef.current.has(id)) {
+        return;
+      }
+      maskInnerNodesRef.current.delete(id);
+    }
+    setReadyVersion((version) => version + 1);
+  }, []);
+  return {
+    isReady,
+    layerIds,
+    maskInnerNodesRef,
+    registerLayer,
+    unregisterLayer,
+    registerMaskInner
+  };
+};
+const ImmerserProvider = ({ children, on, solidClassnamesByLayerId, selectorRoot, ...options }) => {
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const [activeSynchroId, setActiveSynchroId] = useState(null);
+  const [rendererRootNode, setRendererRootNode] = useState(null);
+  const activeIndexRef = useRef(activeIndex);
+  const controllerRef = useRef(null);
+  const latestControllerOptionsRef = useRef(options);
+  const immerserRegistry = useImmerserRegistry();
+  const layerIds = immerserRegistry.layerIds;
+  const { debug, fromViewportWidth, updateLocationHash, pagerThreshold, scrollAdjustDelay, scrollAdjustThreshold } = options;
+  const latestLayerIdsRef = useRef(layerIds);
+  latestControllerOptionsRef.current = options;
+  latestLayerIdsRef.current = layerIds;
+  function syncState(nextController) {
+    if (nextController.activeIndex === -1 && nextController.layerProgressArray.length === 0 && latestLayerIdsRef.current.length > 0 || activeIndexRef.current === nextController.activeIndex) {
+      return;
+    }
+    activeIndexRef.current = nextController.activeIndex;
+    setActiveIndex(nextController.activeIndex);
+  }
+  useLayoutEffect(() => {
+    return () => {
+      const controller = controllerRef.current;
+      if (!controller) {
+        return;
+      }
+      controller.destroy();
+      controllerRef.current = null;
+      if (activeIndexRef.current !== -1) {
+        activeIndexRef.current = -1;
+        setActiveIndex(-1);
+      }
+    };
+  }, [rendererRootNode, selectorRoot]);
+  useLayoutEffect(() => {
+    if (controllerRef.current || !rendererRootNode || !immerserRegistry.isReady) {
+      return;
+    }
+    const controller = new ImmerserController({
+      ...latestControllerOptionsRef.current,
+      // React renders masks and solid clones, so the core must only measure and drive them.
+      hasExternalRenderer: true,
+      on,
+      selectorRoot: selectorRoot ?? rendererRootNode.parentNode ?? document
+    });
+    controllerRef.current = controller;
+    controller.on("stateChange", syncState);
+    syncState(controller);
+  }, [rendererRootNode, selectorRoot, immerserRegistry.isReady]);
+  useLayoutEffect(() => {
+    var _a;
+    if (!immerserRegistry.isReady) {
+      return;
+    }
+    (_a = controllerRef.current) == null ? void 0 : _a.render();
+  }, [children, layerIds, immerserRegistry.isReady, solidClassnamesByLayerId]);
+  useEffect(() => {
+    var _a;
+    const nextOptions = latestControllerOptionsRef.current;
+    (_a = controllerRef.current) == null ? void 0 : _a.updateOptions(nextOptions);
+  }, [debug, fromViewportWidth, updateLocationHash, pagerThreshold, scrollAdjustDelay, scrollAdjustThreshold]);
+  const configContextValue = useMemo(
+    () => ({
+      layerIds,
+      registerLayer: immerserRegistry.registerLayer,
+      registerMaskInner: immerserRegistry.registerMaskInner,
+      setRendererRootNode,
+      solidClassnamesByLayerId,
+      unregisterLayer: immerserRegistry.unregisterLayer
+    }),
+    [
+      layerIds,
+      immerserRegistry.registerLayer,
+      immerserRegistry.registerMaskInner,
+      immerserRegistry.unregisterLayer,
+      solidClassnamesByLayerId
+    ]
+  );
+  const synchroContextValue = useMemo(
+    () => ({
+      activeSynchroId,
+      setActiveSynchroId
+    }),
+    [activeSynchroId]
+  );
+  return /* @__PURE__ */ jsx(ImmerserConfigContext.Provider, { value: configContextValue, children: /* @__PURE__ */ jsx(ImmerserContext.Provider, { value: activeIndex, children: /* @__PURE__ */ jsx(ImmerserSynchroContext.Provider, { value: synchroContextValue, children }) }) });
+};
+ImmerserProvider.displayName = "ImmerserProvider";
+const throwOutsideProviderError = (componentName) => {
+  const message = `${componentName} must be used inside <ImmerserProvider>.`;
+  throw new Error(message);
+};
+const useImmerserConfigContext = (componentName) => {
+  const context = useContext(ImmerserConfigContext);
+  if (!context) {
+    throwOutsideProviderError(componentName);
+  }
+  return context;
+};
+const ImmerserSolid = ({
+  as,
+  children,
+  className,
+  name,
+  style: _style,
+  ...rest
+}) => {
+  useImmerserConfigContext("ImmerserSolid");
+  const Component = as ?? "div";
+  return /* @__PURE__ */ jsx(Component, { ...rest, className, "data-immerser-solid": name, style: InteractiveStyles, children });
+};
+ImmerserSolid.displayName = "ImmerserSolid";
+const ImmerserSynchroLink = ({
+  className,
+  hoverClassName,
+  onMouseEnter,
+  onMouseLeave,
+  synchroId,
+  ...rest
+}) => {
+  const { activeSynchroId, setActiveSynchroId } = useContext(ImmerserSynchroContext);
+  function handleMouseEnter(event) {
+    setActiveSynchroId(synchroId);
+    onMouseEnter == null ? void 0 : onMouseEnter(event);
+  }
+  function handleMouseLeave(event) {
+    setActiveSynchroId((currentSynchroId) => currentSynchroId === synchroId ? null : currentSynchroId);
+    onMouseLeave == null ? void 0 : onMouseLeave(event);
+  }
+  return /* @__PURE__ */ jsx(
+    "a",
+    {
+      ...rest,
+      className: classNames(className, {
+        [hoverClassName]: activeSynchroId === synchroId
+      }),
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave
+    }
+  );
+};
+ImmerserSynchroLink.displayName = "ImmerserSynchroLink";
+const useImmerserContext = (componentName) => {
+  const context = useContext(ImmerserContext);
+  if (context === null) {
+    throwOutsideProviderError(componentName);
+  }
+  return context;
+};
+const ImmerserPager = ({
+  activeClassName,
+  className,
+  linkClassName,
+  as = "nav",
+  hoverClassName = "_hover",
+  renderLink,
+  ...rest
+}) => {
+  const { layerIds } = useImmerserConfigContext("ImmerserPager");
+  const activeIndex = useImmerserContext("ImmerserPager");
+  return /* @__PURE__ */ jsx(ImmerserSolid, { ...rest, as, className, "data-immerser-pager": "", name: "pager", children: layerIds.map((layerId, layerIndex) => {
+    const isActive = layerIndex === activeIndex;
+    if (renderLink) {
+      return /* @__PURE__ */ jsx(Fragment, { children: renderLink({ isActive, layerId, layerIndex }) }, layerId);
+    }
+    return /* @__PURE__ */ jsx(
+      ImmerserSynchroLink,
+      {
+        className: classNames(linkClassName, {
+          [activeClassName]: isActive
+        }),
+        href: `#${layerId}`,
+        hoverClassName,
+        synchroId: `pager-${layerIndex}`
+      },
+      layerId
+    );
+  }) });
+};
+ImmerserPager.displayName = "ImmerserPager";
+const renderSolidsForLayer = (children, solidClassnames = {}) => Children.map(children, (child) => {
+  if (child === null || child === void 0 || child === false) {
+    return child;
+  }
+  if (!isValidElement(child) || child.type !== ImmerserSolid && child.type !== ImmerserPager) {
+    throw new Error("ImmerserRoot accepts only ImmerserSolid or ImmerserPager as direct children.");
+  }
+  const name = child.props.name ?? "pager";
+  return cloneElement(child, {
+    className: classNames(child.props.className, solidClassnames[name])
+  });
+});
+const maskStyle = {
+  ...CroppedFullAbsoluteStyles
+};
+const ImmerserRoot = ({ children, style: _style, ...rest }) => {
+  const { layerIds, registerMaskInner, setRendererRootNode, solidClassnamesByLayerId } = useImmerserConfigContext("ImmerserRoot");
+  const rootRef = useRef(null);
+  useLayoutEffect(() => {
+    setRendererRootNode(rootRef.current);
+    return () => {
+      setRendererRootNode(null);
+    };
+  }, [setRendererRootNode]);
+  return /* @__PURE__ */ jsx("div", { ref: rootRef, ...rest, "data-immerser": "", style: NotInteractiveStyles, children: layerIds.map((layerId, layerIndex) => /* @__PURE__ */ jsx(
+    "div",
+    {
+      "aria-hidden": layerIndex === 0 ? void 0 : true,
+      "data-immerser-layer-id": layerId,
+      "data-immerser-mask": "",
+      style: maskStyle,
+      children: /* @__PURE__ */ jsx("div", { ref: (node) => registerMaskInner(layerId, node), "data-immerser-mask-inner": "", style: maskStyle, children: renderSolidsForLayer(children, solidClassnamesByLayerId[layerId]) })
+    },
+    layerId
+  )) });
+};
+ImmerserRoot.displayName = "ImmerserRoot";
+const ImmerserLayer = ({
+  as,
+  children,
+  id,
+  style: _style,
+  ...rest
+}) => {
+  const { registerLayer, unregisterLayer } = useImmerserConfigContext("ImmerserLayer");
+  const Component = as ?? "div";
+  useLayoutEffect(() => {
+    registerLayer(id);
+    return () => {
+      unregisterLayer(id);
+    };
+  }, [id, registerLayer, unregisterLayer]);
+  return /* @__PURE__ */ jsx(Component, { id, ...rest, "data-immerser-layer": true, children });
+};
+ImmerserLayer.displayName = "ImmerserLayer";
+export {
+  ImmerserLayer,
+  ImmerserPager,
+  ImmerserProvider,
+  ImmerserRoot,
+  ImmerserSolid,
+  ImmerserSynchroLink
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "immerser-react",
+  "version": "1.0.0",
+  "description": "React adapter for declaring Immerser markup with components.",
+  "type": "module",
+  "main": "./dist/immerser-react.cjs",
+  "module": "./dist/immerser-react.js",
+  "types": "./dist/immerser-react.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/immerser-react.d.ts",
+      "import": "./dist/immerser-react.js",
+      "require": "./dist/immerser-react.cjs",
+      "default": "./dist/immerser-react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/*.ts",
+    "src/*.tsx",
+    "src/context",
+    "src/utils",
+    "README.md"
+  ],
+  "keywords": [
+    "immerser",
+    "react",
+    "scroll",
+    "fixed",
+    "sticky"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/dubaua/immerser-react.git"
+  },
+  "author": {
+    "name": "Vladimir Lysov",
+    "email": "dubaua@gmail.com"
+  },
+  "license": "MIT",
+  "homepage": "https://dubaua.github.io/immerser-react/",
+  "sideEffects": false,
+  "scripts": {
+    "predev": "npm run build:lib && npm run build:types",
+    "dev": "vite --force --config src/example/vite.config.ts",
+    "build:readme": "node scripts/build-readme.js",
+    "build:lib": "vite build",
+    "build:types": "tsc --project tsconfig.types.json && api-extractor run --local",
+    "build:docs": "vite build --config src/example/vite.config.ts",
+    "build": "npm run build:readme && npm run build:lib && npm run build:types && npm run build:docs",
+    "typecheck": "tsc -b"
+  },
+  "dependencies": {
+    "classnames": "^2.5.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 <20.0.0",
+    "immerser": "^6.1.1"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.55.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.7.0",
+    "immerser": "^6.1.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "terser": "^5.48.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.4.0"
+  }
+}

package/src/ImmerserLayer.tsx

@@ -0,0 +1,49 @@
+import { useLayoutEffect, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from 'react';
+
+import type { DeniedStyleProp } from './types';
+import { useImmerserConfigContext } from './context/use-immerser-config-context';
+
+type Props<T extends ElementType = 'div'> = {
+  /** Element used for the layer; defaults to `div`. */
+  as?: T;
+  /** Layer content that defines the page section measured by the core controller. */
+  children?: ReactNode;
+  /** Stable layer id used for hash links, pager links and solid classname lookup.
+   * Must match a `solidClassnamesByLayerId` key. */
+  id: string;
+} & Omit<ComponentPropsWithoutRef<T>, 'as' | 'children' | 'id' | 'style'> &
+  DeniedStyleProp;
+
+/**
+ * Marks a real section as an immerser layer.
+ * The core uses these nodes to calculate layer bounds, progress and active index.
+ * Render one layer component for every scroll section that should drive solid class changes.
+ *
+ * @public
+ */
+export const ImmerserLayer = <T extends ElementType = 'div'>({
+  as,
+  children,
+  id,
+  style: _style,
+  ...rest
+}: Props<T>) => {
+  const { registerLayer, unregisterLayer } = useImmerserConfigContext('ImmerserLayer');
+  const Component = as ?? 'div';
+
+  useLayoutEffect(() => {
+    registerLayer(id);
+
+    return () => {
+      unregisterLayer(id);
+    };
+  }, [id, registerLayer, unregisterLayer]);
+
+  return (
+    <Component id={id} {...rest} data-immerser-layer>
+      {children}
+    </Component>
+  );
+};
+
+ImmerserLayer.displayName = 'ImmerserLayer';

package/src/ImmerserPager.tsx

@@ -0,0 +1,88 @@
+import classNames from 'classnames';
+import { Fragment, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from 'react';
+
+import { ImmerserSolid } from './ImmerserSolid';
+import { ImmerserSynchroLink } from './ImmerserSynchroLink';
+import { useImmerserConfigContext } from './context/use-immerser-config-context';
+import { useImmerserContext } from './context/use-immerser-context';
+
+type RenderLinkProps = {
+  isActive: boolean;
+  layerId: string;
+  layerIndex: number;
+};
+
+type DefaultModeProps = {
+  /** Classname applied to the generated link for the currently active layer. */
+  activeClassName: string;
+  /** Classname applied to each generated pager link. */
+  linkClassName: string;
+  /** Classname applied to generated link copies while any of them is hovered. */
+  hoverClassName?: string;
+  renderLink?: never;
+};
+
+type CustomRenderModeProps = {
+  /** Renders custom content for each configured layer. */
+  renderLink: (props: RenderLinkProps) => ReactNode;
+  activeClassName?: never;
+  linkClassName?: never;
+  hoverClassName?: never;
+};
+
+type Props<T extends ElementType = 'nav'> = {
+  /** Element used for the pager wrapper; defaults to `nav`. */
+  as?: T;
+} & (DefaultModeProps | CustomRenderModeProps) &
+  Omit<ComponentPropsWithoutRef<T>, 'activeClassName' | 'children' | 'style'>;
+
+/**
+ * Builds a pager solid inside `ImmerserRoot` from provider layer ids.
+ * Renders one link per DOM layer as a solid named `pager`, ordered by `ImmerserLayer` DOM order.
+ * Add `pager` classnames to layer configs when the pager needs per-layer visual changes.
+ * It mirrors core pager behavior in React so active state comes from context instead of DOM class mutation.
+ * In default mode each generated link receives `linkClassName`, `href="#layerId"`,
+ * `hoverClassName` with `_hover` as the default, and `synchroId="pager-${layerIndex}"`.
+ * Custom render mode receives `isActive`, `layerId` and `layerIndex`
+ * and does not add those generated-link props.
+ *
+ * @public
+ */
+export const ImmerserPager = ({
+  activeClassName,
+  className,
+  linkClassName,
+  as = 'nav',
+  hoverClassName = '_hover',
+  renderLink,
+  ...rest
+}: Props) => {
+  const { layerIds } = useImmerserConfigContext('ImmerserPager');
+  const activeIndex = useImmerserContext('ImmerserPager');
+
+  return (
+    <ImmerserSolid {...rest} as={as} className={className} data-immerser-pager="" name="pager">
+      {layerIds.map((layerId, layerIndex) => {
+        const isActive = layerIndex === activeIndex;
+
+        if (renderLink) {
+          return <Fragment key={layerId}>{renderLink({ isActive, layerId, layerIndex })}</Fragment>;
+        }
+
+        return (
+          <ImmerserSynchroLink
+            key={layerId}
+            className={classNames(linkClassName, {
+              [activeClassName]: isActive,
+            })}
+            href={`#${layerId}`}
+            hoverClassName={hoverClassName}
+            synchroId={`pager-${layerIndex}`}
+          />
+        );
+      })}
+    </ImmerserSolid>
+  );
+};
+
+ImmerserPager.displayName = 'ImmerserPager';

package/src/ImmerserProvider.tsx

@@ -0,0 +1,167 @@
+import ImmerserController, { type Options, type RuntimeOptions } from 'immerser';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+
+import { ImmerserConfigContext } from './context/immerser-config-context';
+import { ImmerserContext } from './context/immerser-context';
+import { ImmerserSynchroContext } from './context/immerser-synchro-context';
+
+import { useImmerserRegistry } from './utils/use-immerser-registry';
+
+type Props = {
+  /** React tree that declares an immerser root, its absolute solids and scroll layers. */
+  children?: ReactNode;
+  /**
+   * Initial event handlers registered when the core controller is created.
+   * Changing this prop does not update the current controller.
+   */
+  on?: Options['on'];
+  /** Parent node used for selector discovery. Changing it recreates the core controller. */
+  selectorRoot?: Options['selectorRoot'];
+  /**
+   * React-only per-layer solid modifiers keyed by layer id.
+   * This is intentionally not passed to the core controller, even though the core has a similarly named option.
+   * The React adapter uses it to render masked solid clones itself.
+   */
+  solidClassnamesByLayerId: Options['solidClassnamesByLayerId'];
+} & Partial<RuntimeOptions>;
+
+/**
+ * Owns the core `Immerser` controller lifecycle and shares its scroll state with React components.
+ * Provider props are adapter-specific props plus `Partial<RuntimeOptions>` from `immerser`.
+ * `RuntimeOptions` is the source of hot core options accepted by the React adapter.
+ * Event handlers passed through `on` are init-only and registered when the controller is created.
+ * `selectorRoot` recreates the core controller when changed.
+ * Runtime options are forwarded through `updateOptions`.
+ * See [core options docs](https://github.com/dubaua/immerser#options).
+ * `solidClassnamesByLayerId` keys must match `ImmerserLayer` ids.
+ * `solidClassnamesByLayerId` keeps the same shape as the constructor option,
+ * but the adapter uses it to render solid copies inside each layer mask and does not forward it as-is.
+ * Init-only and adapter-owned core options are not exposed:
+ * `autoMount`, `hasExternalScroll`, `hasExternalRenderer`, `pagerLinkActiveClassname`
+ * and the core `solidClassnamesByLayerId` contract.
+ * This keeps DOM measurement, mask rendering and scroll listeners in one place
+ * while the rest of the API stays declarative.
+ *
+ * @public
+ */
+export const ImmerserProvider = ({ children, on, solidClassnamesByLayerId, selectorRoot, ...options }: Props) => {
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const [activeSynchroId, setActiveSynchroId] = useState<string | null>(null);
+  const [rendererRootNode, setRendererRootNode] = useState<HTMLDivElement | null>(null);
+
+  const activeIndexRef = useRef(activeIndex);
+  const controllerRef = useRef<ImmerserController | null>(null);
+  const latestControllerOptionsRef = useRef(options);
+  const immerserRegistry = useImmerserRegistry();
+  const layerIds = immerserRegistry.layerIds;
+
+  const { debug, fromViewportWidth, updateLocationHash, pagerThreshold, scrollAdjustDelay, scrollAdjustThreshold } =
+    options;
+
+  const latestLayerIdsRef = useRef(layerIds);
+
+  latestControllerOptionsRef.current = options;
+  latestLayerIdsRef.current = layerIds;
+
+  function syncState(nextController: ImmerserController) {
+    if (
+      (nextController.activeIndex === -1 &&
+        nextController.layerProgressArray.length === 0 &&
+        latestLayerIdsRef.current.length > 0) ||
+      activeIndexRef.current === nextController.activeIndex
+    ) {
+      return;
+    }
+
+    activeIndexRef.current = nextController.activeIndex;
+    setActiveIndex(nextController.activeIndex);
+  }
+
+  useLayoutEffect(() => {
+    return () => {
+      const controller = controllerRef.current;
+
+      if (!controller) {
+        return;
+      }
+
+      controller.destroy();
+      controllerRef.current = null;
+
+      if (activeIndexRef.current !== -1) {
+        activeIndexRef.current = -1;
+        setActiveIndex(-1);
+      }
+    };
+  }, [rendererRootNode, selectorRoot]);
+
+  useLayoutEffect(() => {
+    if (controllerRef.current || !rendererRootNode || !immerserRegistry.isReady) {
+      return;
+    }
+
+    const controller = new ImmerserController({
+      ...latestControllerOptionsRef.current,
+      // React renders masks and solid clones, so the core must only measure and drive them.
+      hasExternalRenderer: true,
+      on,
+      selectorRoot: selectorRoot ?? rendererRootNode.parentNode ?? document,
+    });
+
+    controllerRef.current = controller;
+    controller.on('stateChange', syncState);
+    syncState(controller);
+  }, [rendererRootNode, selectorRoot, immerserRegistry.isReady]);
+
+  useLayoutEffect(() => {
+    if (!immerserRegistry.isReady) {
+      return;
+    }
+
+    controllerRef.current?.render();
+  }, [children, layerIds, immerserRegistry.isReady, solidClassnamesByLayerId]);
+
+  useEffect(() => {
+    const nextOptions = latestControllerOptionsRef.current;
+
+    controllerRef.current?.updateOptions(nextOptions);
+  }, [debug, fromViewportWidth, updateLocationHash, pagerThreshold, scrollAdjustDelay, scrollAdjustThreshold]);
+
+  const configContextValue = useMemo(
+    () => ({
+      layerIds,
+      registerLayer: immerserRegistry.registerLayer,
+      registerMaskInner: immerserRegistry.registerMaskInner,
+      setRendererRootNode,
+      solidClassnamesByLayerId,
+      unregisterLayer: immerserRegistry.unregisterLayer,
+    }),
+    [
+      layerIds,
+      immerserRegistry.registerLayer,
+      immerserRegistry.registerMaskInner,
+      immerserRegistry.unregisterLayer,
+      solidClassnamesByLayerId,
+    ],
+  );
+
+  // Keep the context value reference stable between provider renders.
+  // React state setters are stable, but the object literal is not.
+  const synchroContextValue = useMemo(
+    () => ({
+      activeSynchroId,
+      setActiveSynchroId,
+    }),
+    [activeSynchroId],
+  );
+
+  return (
+    <ImmerserConfigContext.Provider value={configContextValue}>
+      <ImmerserContext.Provider value={activeIndex}>
+        <ImmerserSynchroContext.Provider value={synchroContextValue}>{children}</ImmerserSynchroContext.Provider>
+      </ImmerserContext.Provider>
+    </ImmerserConfigContext.Provider>
+  );
+};
+
+ImmerserProvider.displayName = 'ImmerserProvider';