react-snapshot-bridge 1.1.2 → 1.2.1

package/README.md

@@ -46,13 +46,21 @@ Peer dependency: `react >= 16.3` (when `getSnapshotBeforeUpdate` was introduced)
 import { useRef, useState } from "react";
 import { SnapshotBeforeUpdate } from "react-snapshot-bridge";
 
+type Message = { id: number; text: string };
+
 function ChatList() {
   const scrollerRef = useRef<HTMLDivElement>(null);
-  const [messages, setMessages] = useState<string[]>(["hi"]);
+  const nextId = useRef(1);
+  const [messages, setMessages] = useState<Message[]>([{ id: 0, text: "hi" }]);
 
   return (
     <>
-      <button onClick={() => setMessages((m) => ["new message", ...m])}>
+      <button
+        onClick={() => {
+          const id = nextId.current++;
+          setMessages((m) => [{ id, text: "new message" }, ...m]);
+        }}
+      >
         Prepend
       </button>
 
@@ -66,9 +74,12 @@ function ChatList() {
           el.scrollTop = el.scrollHeight - prevDistanceFromBottom;
         }}
       >
-        <div ref={scrollerRef} style={{ height: 200, overflow: "auto" }}>
-          {messages.map((msg, i) => (
-            <div key={i}>{msg}</div>
+        <div
+          ref={scrollerRef}
+          style={{ height: 200, overflow: "auto", overflowAnchor: "none" }}
+        >
+          {messages.map((msg) => (
+            <div key={msg.id}>{msg.text}</div>
           ))}
         </div>
       </SnapshotBeforeUpdate>
@@ -79,26 +90,32 @@ function ChatList() {
 
 Without the wrapper, every prepend visually shifts the user's content down. With it, the visible content stays anchored.
 
+Give each row a stable `id`. An index key makes React reuse the existing nodes from the top, so a prepend is reconciled like an append and this anchor no longer matches what the reader is looking at.
+
+`overflow-anchor: none` turns off the browser's own scroll anchoring. Without that, Chrome and Safari often keep the same row in view by themselves, and the jump this wrapper corrects stays hidden.
+
 ## Capturing multiple values
 
 `capture` returns a single value, but that value can be **any shape** — including an object. This is the recommended way to forward multiple pieces of state in one commit, and it keeps the API surface minimal and type-safe.
 
 The example below combines two ideas at once:
 
-1. Capture two DOM-derived values (`distanceFromBottom`, `wasAtBottom`) into one snapshot.
+1. Capture the scroll anchor (`anchorFromBottom`, the same `scrollHeight - scrollTop` value as the quick start) and whether the reader was already at the bottom.
 2. Track the **previous** message count with a ref (synced at the end of `apply`), read the **current** `messages` in `apply` via closure, and read DOM in `capture` before the commit mutates it.
 
 ```tsx
-import { useRef, useState } from "react";
+import { useRef } from "react";
 import { SnapshotBeforeUpdate } from "react-snapshot-bridge";
 
+type Message = { id: number; text: string };
+
 type Snap = {
-  distanceFromBottom: number;
+  anchorFromBottom: number;
   wasAtBottom: boolean;
   previousMessageCount: number;
 };
 
-function ChatList({ messages }: { messages: string[] }) {
+function ChatList({ messages }: { messages: Message[] }) {
   const scrollerRef = useRef<HTMLDivElement>(null);
   const prevMessageCountRef = useRef(messages.length);
 
@@ -106,32 +123,35 @@ function ChatList({ messages }: { messages: string[] }) {
     <SnapshotBeforeUpdate<Snap>
       capture={() => {
         const el = scrollerRef.current!;
-        const distanceFromBottom =
-          el.scrollHeight - el.scrollTop - el.clientHeight;
+        const anchorFromBottom = el.scrollHeight - el.scrollTop;
+        const gapBelowViewport = anchorFromBottom - el.clientHeight;
         return {
-          distanceFromBottom,
-          wasAtBottom: distanceFromBottom < 16,
+          anchorFromBottom,
+          wasAtBottom: gapBelowViewport < 16,
           // Still the count from the end of the last `apply` (or initial render).
           previousMessageCount: prevMessageCountRef.current,
         };
       }}
-      apply={({ distanceFromBottom, wasAtBottom, previousMessageCount }) => {
+      apply={({ anchorFromBottom, wasAtBottom, previousMessageCount }) => {
         const el = scrollerRef.current!;
         const grewAtTop = messages.length > previousMessageCount;
 
         if (wasAtBottom) {
           el.scrollTop = el.scrollHeight; // stick to bottom for new arrivals
         } else if (grewAtTop) {
-          el.scrollTop = el.scrollHeight - distanceFromBottom; // anchor existing content
+          el.scrollTop = el.scrollHeight - anchorFromBottom; // anchor existing content
         }
 
         // Next `capture` reads this as the "previous" count for that commit.
         prevMessageCountRef.current = messages.length;
       }}
     >
-      <div ref={scrollerRef} style={{ height: 200, overflow: "auto" }}>
-        {messages.map((msg, i) => (
-          <div key={i}>{msg}</div>
+      <div
+        ref={scrollerRef}
+        style={{ height: 200, overflow: "auto", overflowAnchor: "none" }}
+      >
+        {messages.map((msg) => (
+          <div key={msg.id}>{msg.text}</div>
         ))}
       </div>
     </SnapshotBeforeUpdate>
@@ -143,13 +163,14 @@ function ChatList({ messages }: { messages: string[] }) {
 
 ## API
 
-### `<SnapshotBeforeUpdate<T> capture apply enabled?>{children?}</SnapshotBeforeUpdate>`
+### `<SnapshotBeforeUpdate<T> capture apply enabled? deps?>{children?}</SnapshotBeforeUpdate>`
 
 | Prop       | Type                    | Required | Description                                                                                                                |
 | ---------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `capture`  | `() => T`               | yes      | Called synchronously **before** DOM mutation. Return value is forwarded to `apply`.                                        |
+| `capture`  | `() => T`               | yes      | Called synchronously **before** DOM mutation. Return value, including `undefined`, is forwarded to `apply`.                 |
 | `apply`    | `(snapshot: T) => void` | yes      | Called synchronously **after** DOM mutation, before paint. Receives the value from `capture`.                              |
 | `enabled`  | `boolean`               | no       | Defaults to `true`. When `false`, both `capture` and `apply` are skipped for that commit. Missed updates are not replayed. |
+| `deps`     | `readonly unknown[]`    | no       | Optional dependency array, compared shallowly (`Object.is`) against the previous commit. When provided, both callbacks run only on commits where at least one entry changed. When omitted, they run on every update. |
 | `children` | `React.ReactNode`       | no       | Optional. When provided, rendered as-is (wrapper pattern). When omitted, renders nothing.                                  |
 
 The generic `T` is inferred from `capture`'s return type — you usually don't need to specify it.
@@ -224,8 +245,10 @@ The captured value is forwarded to `componentDidUpdate`, which calls `apply`. Fr
 - **Updates run before DOM mutation for that commit.** After mount, whenever the bridge commits an update, `capture` runs in the **before mutation** phase: before the DOM reflects that commit's output and before the browser paints that update. That is the timing slot this library occupies (see [How it works](#how-it-works)).
 - **Requires a re-render in the right place.** If a `React.memo` (or `shouldComponentUpdate`) ancestor short-circuits the render, or the bridge is placed as a sibling of a different component that updates on its own, neither callback will fire. See [Where to place it](#where-to-place-it).
 - **`enabled={false}` does not buffer updates.** Updates that occur while disabled are silently dropped. There is no "catch up" call when you re-enable the bridge — the next regular update is what triggers `capture`/`apply` again.
+- **`deps={[]}` differs from `useEffect`.** Because an empty array never changes and this lifecycle never runs on mount, `deps={[]}` means "never run after mount" — not "run once on mount" as it would with `useEffect`. Use a populated `deps` array (e.g. `[messages.length]`) to gate by meaningful changes.
 - **Concurrent rendering safe.** React 18+ concurrent features may discard render results, but the commit phase itself is synchronous, so `capture`/`apply` always run as a paired set.
 - **SSR safe.** Lifecycle methods don't run during `renderToString` / `renderToPipeableStream`, so the bridge is a no-op on the server.
+- **Client Component.** The package entry starts with `'use client'`. In the Next.js App Router, render it from a Client Component. `capture` and `apply` are functions, so a Server Component cannot pass them into this wrapper.
 - **React 19.** Class components and `getSnapshotBeforeUpdate` are not deprecated in React 19. This library remains compatible.
 
 ## License

package/dist/index.cjs

@@ -1,20 +1,31 @@
+'use client';
 'use strict';
 
 var react = require('react');
 
+// src/_utils/checkIsDepsEqual.ts
+function checkIsDepsEqual(prev, next) {
+  if (prev === void 0 || next === void 0) return false;
+  if (prev.length !== next.length) return false;
+  for (let i = 0; i < prev.length; i++) {
+    if (!Object.is(prev[i], next[i])) return false;
+  }
+  return true;
+}
+var checkIsDepsEqual_default = checkIsDepsEqual;
+
 // src/SnapshotBeforeUpdate.tsx
 var SKIP = /* @__PURE__ */ Symbol("react-snapshot-bridge-skip");
 var SnapshotBeforeUpdate = class extends react.Component {
-  getSnapshotBeforeUpdate() {
-    if (this.props.enabled === false) {
+  getSnapshotBeforeUpdate(prevProps) {
+    if (this.props.enabled === false) return SKIP;
+    if (this.props.deps !== void 0 && checkIsDepsEqual_default(prevProps.deps, this.props.deps))
       return SKIP;
-    }
-    return this.props.capture();
+    return { value: this.props.capture() };
   }
   componentDidUpdate(_prevProps, _prevState, snapshot) {
-    if (this.props.enabled === false) return;
     if (snapshot === SKIP) return;
-    this.props.apply(snapshot);
+    this.props.apply(snapshot.value);
   }
   render() {
     return this.props.children ?? null;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/SnapshotBeforeUpdate.tsx"],"names":["Component"],"mappings":";;;;;AAQA,IAAM,IAAA,0BAAc,4BAA4B,CAAA;AA0CzC,IAAM,oBAAA,GAAN,cAAgDA,eAAA,CAGrD;AAAA,EACS,uBAAA,GAA6B;AACpC,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,OAAA,KAAY,KAAA,EAAO;AAChC,MAAA,OAAO,IAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA,CAAK,MAAM,OAAA,EAAQ;AAAA,EAC5B;AAAA,EAES,kBAAA,CACP,UAAA,EACA,UAAA,EACA,QAAA,EACM;AACN,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,OAAA,KAAY,KAAA,EAAO;AAClC,IAAA,IAAK,aAAiC,IAAA,EAAM;AAE5C,IAAA,IAAA,CAAK,KAAA,CAAM,MAAM,QAAQ,CAAA;AAAA,EAC3B;AAAA,EAES,MAAA,GAAoB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAM,QAAA,IAAY,IAAA;AAAA,EAChC;AACF","file":"index.cjs","sourcesContent":["import type { ReactNode } from 'react';\nimport { Component } from 'react';\n\ntype EmptyState = Record<string, never>;\n\n/**\n * Symbol used to indicate that the snapshot should be skipped.\n */\nconst SKIP = Symbol('react-snapshot-bridge-skip');\ntype Skip = typeof SKIP;\n\nexport interface SnapshotBeforeUpdateProps<T> {\n  /**\n   * Runs synchronously **before** the DOM is mutated for this commit.\n   * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.\n   */\n  capture: () => T;\n\n  /**\n   * Runs synchronously **after** the DOM is mutated, before the browser paints.\n   * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.\n   */\n  apply: (snapshot: T) => void;\n\n  /**\n   * When `false`, both `capture` and `apply` are skipped for that commit.\n   * Evaluated against the **current** props at commit time, so toggling\n   * `true` -> `false` skips both callbacks for that update, and `false` -> `true`\n   * runs both as usual on the next update. Defaults to `true`.\n   *\n   * Updates that occur while disabled are not buffered or replayed later.\n   */\n  enabled?: boolean;\n\n  /**\n   * Optional children. When provided, this component acts as a wrapper and\n   * renders its children. When omitted, it renders nothing and you can place\n   * it as a sibling next to the elements you care about.\n   */\n  children?: ReactNode;\n}\n\n/**\n * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees\n * built with function components.\n *\n * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`\n * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}\n * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.\n */\nexport class SnapshotBeforeUpdate<T = unknown> extends Component<\n  SnapshotBeforeUpdateProps<T>,\n  EmptyState\n> {\n  override getSnapshotBeforeUpdate(): T {\n    if (this.props.enabled === false) {\n      return SKIP as unknown as T;\n    }\n    return this.props.capture();\n  }\n\n  override componentDidUpdate(\n    _prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n    _prevState: Readonly<EmptyState>,\n    snapshot: T,\n  ): void {\n    if (this.props.enabled === false) return;\n    if ((snapshot as unknown as Skip) === SKIP) return;\n\n    this.props.apply(snapshot);\n  }\n\n  override render(): ReactNode {\n    return this.props.children ?? null;\n  }\n}\n"]}
+{"version":3,"sources":["../src/_utils/checkIsDepsEqual.ts","../src/SnapshotBeforeUpdate.tsx"],"names":["Component"],"mappings":";;;;;AAAA,SAAS,gBAAA,CACP,MACA,IAAA,EACS;AACT,EAAA,IAAI,IAAA,KAAS,MAAA,IAAa,IAAA,KAAS,MAAA,EAAW,OAAO,KAAA;AACrD,EAAA,IAAI,IAAA,CAAK,MAAA,KAAW,IAAA,CAAK,MAAA,EAAQ,OAAO,KAAA;AACxC,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,IAAA,CAAK,QAAQ,CAAA,EAAA,EAAK;AACpC,IAAA,IAAI,CAAC,MAAA,CAAO,EAAA,CAAG,IAAA,CAAK,CAAC,GAAG,IAAA,CAAK,CAAC,CAAC,CAAA,EAAG,OAAO,KAAA;AAAA,EAC3C;AACA,EAAA,OAAO,IAAA;AACT;AAEA,IAAO,wBAAA,GAAQ,gBAAA;;;ACHf,IAAM,IAAA,0BAAc,4BAA4B,CAAA;AA2DzC,IAAM,oBAAA,GAAN,cAAgDA,eAAA,CAIrD;AAAA,EACS,wBACP,SAAA,EACyB;AACzB,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,OAAA,KAAY,KAAA,EAAO,OAAO,IAAA;AAEzC,IAAA,IAAI,IAAA,CAAK,MAAM,IAAA,KAAS,MAAA,IAAa,yBAAiB,SAAA,CAAU,IAAA,EAAM,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA;AACnF,MAAA,OAAO,IAAA;AAET,IAAA,OAAO,EAAE,KAAA,EAAO,IAAA,CAAK,KAAA,CAAM,SAAQ,EAAE;AAAA,EACvC;AAAA,EAES,kBAAA,CACP,UAAA,EACA,UAAA,EACA,QAAA,EACM;AACN,IAAA,IAAI,aAAa,IAAA,EAAM;AAEvB,IAAA,IAAA,CAAK,KAAA,CAAM,KAAA,CAAM,QAAA,CAAS,KAAK,CAAA;AAAA,EACjC;AAAA,EAES,MAAA,GAAoB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAM,QAAA,IAAY,IAAA;AAAA,EAChC;AACF","file":"index.cjs","sourcesContent":["function checkIsDepsEqual(\n  prev: readonly unknown[] | undefined,\n  next: readonly unknown[] | undefined,\n): boolean {\n  if (prev === undefined || next === undefined) return false;\n  if (prev.length !== next.length) return false;\n  for (let i = 0; i < prev.length; i++) {\n    if (!Object.is(prev[i], next[i])) return false;\n  }\n  return true;\n}\n\nexport default checkIsDepsEqual;\n","import type { ReactNode } from 'react';\nimport { Component } from 'react';\nimport checkIsDepsEqual from './_utils/checkIsDepsEqual';\n\ntype EmptyState = Record<string, never>;\n\n/**\n * Symbol used to indicate that the snapshot should be skipped.\n */\nconst SKIP = Symbol('react-snapshot-bridge-skip');\ntype Skip = typeof SKIP;\n\n/**\n * React logs an error when `getSnapshotBeforeUpdate` returns `undefined`.\n * Boxing the value lets `capture` return `undefined` and still forward it to `apply`.\n */\ntype BoxedSnapshot<T> = {\n  readonly value: T;\n};\n\nexport interface SnapshotBeforeUpdateProps<T> {\n  /**\n   * Runs synchronously **before** the DOM is mutated for this commit.\n   * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.\n   * `undefined` is a valid snapshot and is forwarded unchanged.\n   */\n  capture: () => T;\n\n  /**\n   * Runs synchronously **after** the DOM is mutated, before the browser paints.\n   * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.\n   */\n  apply: (snapshot: T) => void;\n\n  /**\n   * When `false`, both `capture` and `apply` are skipped for that commit.\n   * Evaluated against the **current** props at commit time, so toggling\n   * `true` -> `false` skips both callbacks for that update, and `false` -> `true`\n   * runs both as usual on the next update. Defaults to `true`.\n   *\n   * Updates that occur while disabled are not buffered or replayed later.\n   */\n  enabled?: boolean;\n\n  /**\n   * Optional dependency array, compared shallowly (`Object.is`) against the\n   * previous commit. When provided, both `capture` and `apply` run only on the\n   * commit where at least one entry changed; commits with unchanged `deps` are\n   * skipped. When omitted, both callbacks run on every update (default).\n   */\n  deps?: readonly unknown[];\n\n  /**\n   * Optional children. When provided, this component acts as a wrapper and\n   * renders its children. When omitted, it renders nothing and you can place\n   * it as a sibling next to the elements you care about.\n   */\n  children?: ReactNode;\n}\n\n/**\n * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees\n * built with function components.\n *\n * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`\n * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}\n * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.\n */\nexport class SnapshotBeforeUpdate<T = unknown> extends Component<\n  SnapshotBeforeUpdateProps<T>,\n  EmptyState,\n  BoxedSnapshot<T> | Skip\n> {\n  override getSnapshotBeforeUpdate(\n    prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n  ): BoxedSnapshot<T> | Skip {\n    if (this.props.enabled === false) return SKIP;\n\n    if (this.props.deps !== undefined && checkIsDepsEqual(prevProps.deps, this.props.deps))\n      return SKIP;\n\n    return { value: this.props.capture() };\n  }\n\n  override componentDidUpdate(\n    _prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n    _prevState: Readonly<EmptyState>,\n    snapshot: BoxedSnapshot<T> | Skip,\n  ): void {\n    if (snapshot === SKIP) return;\n\n    this.props.apply(snapshot.value);\n  }\n\n  override render(): ReactNode {\n    return this.props.children ?? null;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -1,10 +1,23 @@
 import { Component, ReactNode } from 'react';
 
 type EmptyState = Record<string, never>;
+/**
+ * Symbol used to indicate that the snapshot should be skipped.
+ */
+declare const SKIP: unique symbol;
+type Skip = typeof SKIP;
+/**
+ * React logs an error when `getSnapshotBeforeUpdate` returns `undefined`.
+ * Boxing the value lets `capture` return `undefined` and still forward it to `apply`.
+ */
+type BoxedSnapshot<T> = {
+    readonly value: T;
+};
 interface SnapshotBeforeUpdateProps<T> {
     /**
      * Runs synchronously **before** the DOM is mutated for this commit.
      * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.
+     * `undefined` is a valid snapshot and is forwarded unchanged.
      */
     capture: () => T;
     /**
@@ -21,6 +34,13 @@ interface SnapshotBeforeUpdateProps<T> {
      * Updates that occur while disabled are not buffered or replayed later.
      */
     enabled?: boolean;
+    /**
+     * Optional dependency array, compared shallowly (`Object.is`) against the
+     * previous commit. When provided, both `capture` and `apply` run only on the
+     * commit where at least one entry changed; commits with unchanged `deps` are
+     * skipped. When omitted, both callbacks run on every update (default).
+     */
+    deps?: readonly unknown[];
     /**
      * Optional children. When provided, this component acts as a wrapper and
      * renders its children. When omitted, it renders nothing and you can place
@@ -36,9 +56,9 @@ interface SnapshotBeforeUpdateProps<T> {
  * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}
  * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.
  */
-declare class SnapshotBeforeUpdate<T = unknown> extends Component<SnapshotBeforeUpdateProps<T>, EmptyState> {
-    getSnapshotBeforeUpdate(): T;
-    componentDidUpdate(_prevProps: Readonly<SnapshotBeforeUpdateProps<T>>, _prevState: Readonly<EmptyState>, snapshot: T): void;
+declare class SnapshotBeforeUpdate<T = unknown> extends Component<SnapshotBeforeUpdateProps<T>, EmptyState, BoxedSnapshot<T> | Skip> {
+    getSnapshotBeforeUpdate(prevProps: Readonly<SnapshotBeforeUpdateProps<T>>): BoxedSnapshot<T> | Skip;
+    componentDidUpdate(_prevProps: Readonly<SnapshotBeforeUpdateProps<T>>, _prevState: Readonly<EmptyState>, snapshot: BoxedSnapshot<T> | Skip): void;
     render(): ReactNode;
 }
 

package/dist/index.d.ts

@@ -1,10 +1,23 @@
 import { Component, ReactNode } from 'react';
 
 type EmptyState = Record<string, never>;
+/**
+ * Symbol used to indicate that the snapshot should be skipped.
+ */
+declare const SKIP: unique symbol;
+type Skip = typeof SKIP;
+/**
+ * React logs an error when `getSnapshotBeforeUpdate` returns `undefined`.
+ * Boxing the value lets `capture` return `undefined` and still forward it to `apply`.
+ */
+type BoxedSnapshot<T> = {
+    readonly value: T;
+};
 interface SnapshotBeforeUpdateProps<T> {
     /**
      * Runs synchronously **before** the DOM is mutated for this commit.
      * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.
+     * `undefined` is a valid snapshot and is forwarded unchanged.
      */
     capture: () => T;
     /**
@@ -21,6 +34,13 @@ interface SnapshotBeforeUpdateProps<T> {
      * Updates that occur while disabled are not buffered or replayed later.
      */
     enabled?: boolean;
+    /**
+     * Optional dependency array, compared shallowly (`Object.is`) against the
+     * previous commit. When provided, both `capture` and `apply` run only on the
+     * commit where at least one entry changed; commits with unchanged `deps` are
+     * skipped. When omitted, both callbacks run on every update (default).
+     */
+    deps?: readonly unknown[];
     /**
      * Optional children. When provided, this component acts as a wrapper and
      * renders its children. When omitted, it renders nothing and you can place
@@ -36,9 +56,9 @@ interface SnapshotBeforeUpdateProps<T> {
  * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}
  * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.
  */
-declare class SnapshotBeforeUpdate<T = unknown> extends Component<SnapshotBeforeUpdateProps<T>, EmptyState> {
-    getSnapshotBeforeUpdate(): T;
-    componentDidUpdate(_prevProps: Readonly<SnapshotBeforeUpdateProps<T>>, _prevState: Readonly<EmptyState>, snapshot: T): void;
+declare class SnapshotBeforeUpdate<T = unknown> extends Component<SnapshotBeforeUpdateProps<T>, EmptyState, BoxedSnapshot<T> | Skip> {
+    getSnapshotBeforeUpdate(prevProps: Readonly<SnapshotBeforeUpdateProps<T>>): BoxedSnapshot<T> | Skip;
+    componentDidUpdate(_prevProps: Readonly<SnapshotBeforeUpdateProps<T>>, _prevState: Readonly<EmptyState>, snapshot: BoxedSnapshot<T> | Skip): void;
     render(): ReactNode;
 }
 

package/dist/index.js

@@ -1,18 +1,29 @@
+'use client';
 import { Component } from 'react';
 
+// src/_utils/checkIsDepsEqual.ts
+function checkIsDepsEqual(prev, next) {
+  if (prev === void 0 || next === void 0) return false;
+  if (prev.length !== next.length) return false;
+  for (let i = 0; i < prev.length; i++) {
+    if (!Object.is(prev[i], next[i])) return false;
+  }
+  return true;
+}
+var checkIsDepsEqual_default = checkIsDepsEqual;
+
 // src/SnapshotBeforeUpdate.tsx
 var SKIP = /* @__PURE__ */ Symbol("react-snapshot-bridge-skip");
 var SnapshotBeforeUpdate = class extends Component {
-  getSnapshotBeforeUpdate() {
-    if (this.props.enabled === false) {
+  getSnapshotBeforeUpdate(prevProps) {
+    if (this.props.enabled === false) return SKIP;
+    if (this.props.deps !== void 0 && checkIsDepsEqual_default(prevProps.deps, this.props.deps))
       return SKIP;
-    }
-    return this.props.capture();
+    return { value: this.props.capture() };
   }
   componentDidUpdate(_prevProps, _prevState, snapshot) {
-    if (this.props.enabled === false) return;
     if (snapshot === SKIP) return;
-    this.props.apply(snapshot);
+    this.props.apply(snapshot.value);
   }
   render() {
     return this.props.children ?? null;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/SnapshotBeforeUpdate.tsx"],"names":[],"mappings":";;;AAQA,IAAM,IAAA,0BAAc,4BAA4B,CAAA;AA0CzC,IAAM,oBAAA,GAAN,cAAgD,SAAA,CAGrD;AAAA,EACS,uBAAA,GAA6B;AACpC,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,OAAA,KAAY,KAAA,EAAO;AAChC,MAAA,OAAO,IAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA,CAAK,MAAM,OAAA,EAAQ;AAAA,EAC5B;AAAA,EAES,kBAAA,CACP,UAAA,EACA,UAAA,EACA,QAAA,EACM;AACN,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,OAAA,KAAY,KAAA,EAAO;AAClC,IAAA,IAAK,aAAiC,IAAA,EAAM;AAE5C,IAAA,IAAA,CAAK,KAAA,CAAM,MAAM,QAAQ,CAAA;AAAA,EAC3B;AAAA,EAES,MAAA,GAAoB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAM,QAAA,IAAY,IAAA;AAAA,EAChC;AACF","file":"index.js","sourcesContent":["import type { ReactNode } from 'react';\nimport { Component } from 'react';\n\ntype EmptyState = Record<string, never>;\n\n/**\n * Symbol used to indicate that the snapshot should be skipped.\n */\nconst SKIP = Symbol('react-snapshot-bridge-skip');\ntype Skip = typeof SKIP;\n\nexport interface SnapshotBeforeUpdateProps<T> {\n  /**\n   * Runs synchronously **before** the DOM is mutated for this commit.\n   * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.\n   */\n  capture: () => T;\n\n  /**\n   * Runs synchronously **after** the DOM is mutated, before the browser paints.\n   * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.\n   */\n  apply: (snapshot: T) => void;\n\n  /**\n   * When `false`, both `capture` and `apply` are skipped for that commit.\n   * Evaluated against the **current** props at commit time, so toggling\n   * `true` -> `false` skips both callbacks for that update, and `false` -> `true`\n   * runs both as usual on the next update. Defaults to `true`.\n   *\n   * Updates that occur while disabled are not buffered or replayed later.\n   */\n  enabled?: boolean;\n\n  /**\n   * Optional children. When provided, this component acts as a wrapper and\n   * renders its children. When omitted, it renders nothing and you can place\n   * it as a sibling next to the elements you care about.\n   */\n  children?: ReactNode;\n}\n\n/**\n * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees\n * built with function components.\n *\n * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`\n * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}\n * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.\n */\nexport class SnapshotBeforeUpdate<T = unknown> extends Component<\n  SnapshotBeforeUpdateProps<T>,\n  EmptyState\n> {\n  override getSnapshotBeforeUpdate(): T {\n    if (this.props.enabled === false) {\n      return SKIP as unknown as T;\n    }\n    return this.props.capture();\n  }\n\n  override componentDidUpdate(\n    _prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n    _prevState: Readonly<EmptyState>,\n    snapshot: T,\n  ): void {\n    if (this.props.enabled === false) return;\n    if ((snapshot as unknown as Skip) === SKIP) return;\n\n    this.props.apply(snapshot);\n  }\n\n  override render(): ReactNode {\n    return this.props.children ?? null;\n  }\n}\n"]}
+{"version":3,"sources":["../src/_utils/checkIsDepsEqual.ts","../src/SnapshotBeforeUpdate.tsx"],"names":[],"mappings":";;;AAAA,SAAS,gBAAA,CACP,MACA,IAAA,EACS;AACT,EAAA,IAAI,IAAA,KAAS,MAAA,IAAa,IAAA,KAAS,MAAA,EAAW,OAAO,KAAA;AACrD,EAAA,IAAI,IAAA,CAAK,MAAA,KAAW,IAAA,CAAK,MAAA,EAAQ,OAAO,KAAA;AACxC,EAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,IAAA,CAAK,QAAQ,CAAA,EAAA,EAAK;AACpC,IAAA,IAAI,CAAC,MAAA,CAAO,EAAA,CAAG,IAAA,CAAK,CAAC,GAAG,IAAA,CAAK,CAAC,CAAC,CAAA,EAAG,OAAO,KAAA;AAAA,EAC3C;AACA,EAAA,OAAO,IAAA;AACT;AAEA,IAAO,wBAAA,GAAQ,gBAAA;;;ACHf,IAAM,IAAA,0BAAc,4BAA4B,CAAA;AA2DzC,IAAM,oBAAA,GAAN,cAAgD,SAAA,CAIrD;AAAA,EACS,wBACP,SAAA,EACyB;AACzB,IAAA,IAAI,IAAA,CAAK,KAAA,CAAM,OAAA,KAAY,KAAA,EAAO,OAAO,IAAA;AAEzC,IAAA,IAAI,IAAA,CAAK,MAAM,IAAA,KAAS,MAAA,IAAa,yBAAiB,SAAA,CAAU,IAAA,EAAM,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA;AACnF,MAAA,OAAO,IAAA;AAET,IAAA,OAAO,EAAE,KAAA,EAAO,IAAA,CAAK,KAAA,CAAM,SAAQ,EAAE;AAAA,EACvC;AAAA,EAES,kBAAA,CACP,UAAA,EACA,UAAA,EACA,QAAA,EACM;AACN,IAAA,IAAI,aAAa,IAAA,EAAM;AAEvB,IAAA,IAAA,CAAK,KAAA,CAAM,KAAA,CAAM,QAAA,CAAS,KAAK,CAAA;AAAA,EACjC;AAAA,EAES,MAAA,GAAoB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAM,QAAA,IAAY,IAAA;AAAA,EAChC;AACF","file":"index.js","sourcesContent":["function checkIsDepsEqual(\n  prev: readonly unknown[] | undefined,\n  next: readonly unknown[] | undefined,\n): boolean {\n  if (prev === undefined || next === undefined) return false;\n  if (prev.length !== next.length) return false;\n  for (let i = 0; i < prev.length; i++) {\n    if (!Object.is(prev[i], next[i])) return false;\n  }\n  return true;\n}\n\nexport default checkIsDepsEqual;\n","import type { ReactNode } from 'react';\nimport { Component } from 'react';\nimport checkIsDepsEqual from './_utils/checkIsDepsEqual';\n\ntype EmptyState = Record<string, never>;\n\n/**\n * Symbol used to indicate that the snapshot should be skipped.\n */\nconst SKIP = Symbol('react-snapshot-bridge-skip');\ntype Skip = typeof SKIP;\n\n/**\n * React logs an error when `getSnapshotBeforeUpdate` returns `undefined`.\n * Boxing the value lets `capture` return `undefined` and still forward it to `apply`.\n */\ntype BoxedSnapshot<T> = {\n  readonly value: T;\n};\n\nexport interface SnapshotBeforeUpdateProps<T> {\n  /**\n   * Runs synchronously **before** the DOM is mutated for this commit.\n   * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.\n   * `undefined` is a valid snapshot and is forwarded unchanged.\n   */\n  capture: () => T;\n\n  /**\n   * Runs synchronously **after** the DOM is mutated, before the browser paints.\n   * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.\n   */\n  apply: (snapshot: T) => void;\n\n  /**\n   * When `false`, both `capture` and `apply` are skipped for that commit.\n   * Evaluated against the **current** props at commit time, so toggling\n   * `true` -> `false` skips both callbacks for that update, and `false` -> `true`\n   * runs both as usual on the next update. Defaults to `true`.\n   *\n   * Updates that occur while disabled are not buffered or replayed later.\n   */\n  enabled?: boolean;\n\n  /**\n   * Optional dependency array, compared shallowly (`Object.is`) against the\n   * previous commit. When provided, both `capture` and `apply` run only on the\n   * commit where at least one entry changed; commits with unchanged `deps` are\n   * skipped. When omitted, both callbacks run on every update (default).\n   */\n  deps?: readonly unknown[];\n\n  /**\n   * Optional children. When provided, this component acts as a wrapper and\n   * renders its children. When omitted, it renders nothing and you can place\n   * it as a sibling next to the elements you care about.\n   */\n  children?: ReactNode;\n}\n\n/**\n * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees\n * built with function components.\n *\n * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`\n * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}\n * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.\n */\nexport class SnapshotBeforeUpdate<T = unknown> extends Component<\n  SnapshotBeforeUpdateProps<T>,\n  EmptyState,\n  BoxedSnapshot<T> | Skip\n> {\n  override getSnapshotBeforeUpdate(\n    prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n  ): BoxedSnapshot<T> | Skip {\n    if (this.props.enabled === false) return SKIP;\n\n    if (this.props.deps !== undefined && checkIsDepsEqual(prevProps.deps, this.props.deps))\n      return SKIP;\n\n    return { value: this.props.capture() };\n  }\n\n  override componentDidUpdate(\n    _prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n    _prevState: Readonly<EmptyState>,\n    snapshot: BoxedSnapshot<T> | Skip,\n  ): void {\n    if (snapshot === SKIP) return;\n\n    this.props.apply(snapshot.value);\n  }\n\n  override render(): ReactNode {\n    return this.props.children ?? null;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-snapshot-bridge",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "Use React's class-only `getSnapshotBeforeUpdate` lifecycle from function components.",
   "keywords": [
     "react",