@assistant-ui/tap 0.6.1 → 0.7.1

package/src/__tests__/parity/parity.basics.test.tsx

@@ -0,0 +1,281 @@
+/**
+ * Baseline parity scenarios: mount/render counts, strict-mode ghost
+ * invocations, memo caching, effect lifecycles, setState batching, async
+ * updates, unmount. Runs in dev and prod via the vitest projects.
+ */
+/* oxlint-disable react/exhaustive-deps -- intentional missing-dep patterns are part of the scenarios */
+import { useEffect, useMemo, useReducer, useRef, useState } from "react";
+import { describeParity, type Scenario } from "./describeParity";
+
+const scenarios: Scenario[] = [
+  {
+    name: "mount: render count, useState initializer ghost-invoked, first result kept",
+    use: (log) => {
+      const [a] = useState(() => {
+        log("init-a");
+        return 1;
+      });
+      const [b] = useState(() => {
+        log("init-b");
+        return 2;
+      });
+      log(`render a=${a} b=${b}`);
+    },
+  },
+  {
+    name: "useMemo: ghost-invoked when computing, cached across passes and re-renders",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      useMemo(() => {
+        log(`memo n=${n}`);
+        return n;
+      }, [n]);
+      log(`render n=${n}`);
+      useEffect(() => {
+        if (n === 0) setN(1);
+      }, [n]);
+    },
+  },
+  {
+    name: "useMemo: first returned instance is the one kept",
+    use: (log) => {
+      let instance = 0;
+      const obj = useMemo(() => ({ instance: ++instance }), []);
+      const first = useRef(obj);
+      log(`instance=${obj.instance} identity-stable=${first.current === obj}`);
+    },
+  },
+  {
+    name: "useReducer: initializer ghost-invoked, first result kept",
+    use: (log) => {
+      let initCount = 0;
+      const [state] = useReducer(
+        (s: number, a: number) => s + a,
+        0,
+        (arg: number) => {
+          initCount++;
+          log(`init-${initCount}`);
+          return arg + initCount * 10;
+        },
+      );
+      log(`render state=${state}`);
+    },
+  },
+  {
+    name: "useReducer: dispatch reducer ghost-invoked",
+    use: (log) => {
+      const countRef = useRef(0);
+      const [state, dispatch] = useReducer((s: number, _a: number) => {
+        countRef.current++;
+        const result = countRef.current * 100;
+        log(`reducer-${countRef.current} state=${s} -> ${result}`);
+        return result;
+      }, 0);
+      log(`render state=${state}`);
+      return { dispatch };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().dispatch(1));
+    },
+  },
+  {
+    name: "effects cycle mount, strict remount, deps",
+    use: (log) => {
+      const [n] = useState(0);
+      useEffect(() => {
+        log("e1-mount");
+        return () => log("e1-unmount");
+      });
+      useEffect(() => {
+        log("e2-mount");
+        return () => log("e2-unmount");
+      }, []);
+      useEffect(() => {
+        log(`e3-mount n=${n}`);
+        return () => log(`e3-unmount n=${n}`);
+      }, [n]);
+    },
+  },
+  {
+    name: "setState in effect",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        log(`effect ${count}`);
+        if (count === 0) setCount(1);
+        return () => log(`cleanup ${count}`);
+      }, [count]);
+    },
+  },
+  {
+    name: "event-handler setState: single re-render, updater ghost-invoked",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      return {
+        increment: () =>
+          setCount((prev) => {
+            log(`updater prev=${prev}`);
+            return prev + 1;
+          }),
+      };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().increment());
+    },
+  },
+  {
+    name: "event-handler setState: multiple setStates batch into one render",
+    use: (log) => {
+      const [a, setA] = useState(0);
+      const [b, setB] = useState(0);
+      log(`render a=${a} b=${b}`);
+      return {
+        both: () => {
+          setA(1);
+          setB(2);
+        },
+      };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().both());
+    },
+  },
+  {
+    name: "async setState from a promise scheduled in an effect",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        if (count === 0) {
+          void Promise.resolve().then(() => {
+            log("promise");
+            setCount(1);
+          });
+        }
+      }, [count]);
+    },
+    drive: ({ settle }) => settle(),
+  },
+  {
+    name: "async setState from a setTimeout scheduled in an effect",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        if (count === 0) {
+          // The cleanup matters: without it the strict double effect-mount
+          // schedules two timers, and whether their dispatches batch into one
+          // render is a race between the timer phase and the schedulers.
+          const timer = setTimeout(() => {
+            log("timeout");
+            setCount(1);
+          }, 5);
+          return () => clearTimeout(timer);
+        }
+        return undefined;
+      }, [count]);
+    },
+    drive: ({ settle }) => settle(),
+  },
+  {
+    name: "setState from the first strict effect mount survives its cleanup",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      const runs = useRef(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        runs.current++;
+        const n = runs.current;
+        log(`mount#${n} count=${count}`);
+        if (n === 1) setCount(1);
+        return () => log(`cleanup#${n}`);
+      }, []);
+    },
+  },
+  {
+    name: "setState from both strict effect mounts: last value wins",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      const runs = useRef(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        runs.current++;
+        const n = runs.current;
+        log(`mount#${n} count=${count}`);
+        setCount(n === 1 ? 1 : 2);
+        return () => log(`cleanup#${n}`);
+      }, []);
+    },
+  },
+  {
+    name: "updater setState from both strict effect mounts chains",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      const runs = useRef(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        runs.current++;
+        const n = runs.current;
+        setCount((prev) => {
+          log(`updater#${n} prev=${prev}`);
+          return prev + n;
+        });
+      }, []);
+    },
+  },
+  {
+    name: "useReducer: dispatching the same state",
+    use: (log) => {
+      const [state, dispatch] = useReducer((s: number) => s, 42);
+      log(`render ${state}`);
+      return { dispatch };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().dispatch(0));
+    },
+  },
+  {
+    name: "updater returning a different value per invocation",
+    divergence: { bridge: "multiset" },
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      const calls = useRef(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        log("effect mount");
+        setCount((prev) => {
+          calls.current++;
+          log(`updater call #${calls.current} with prev=${prev}`);
+          return calls.current === 1 ? 100 : 200;
+        });
+        return () => log("effect cleanup");
+      }, []);
+    },
+  },
+  {
+    name: "render-phase update: setState during render re-renders before committing",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      if (count === 0) setCount(1);
+    },
+  },
+  {
+    name: "unmount runs cleanups",
+    use: (log) => {
+      useEffect(() => {
+        log("mount-1");
+        return () => log("unmount-1");
+      }, []);
+      useEffect(() => {
+        log("mount-2");
+        return () => log("unmount-2");
+      }, []);
+    },
+    unmountAtEnd: true,
+  },
+];
+
+describeParity(scenarios);

package/src/__tests__/parity/parity.divergences.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * The remaining (deliberate or structural) divergences between React and
+ * tap; see DIVERGENCES.md for the full rationale. Each test pins the CURRENT
+ * behavior of BOTH sides so a change in either direction is caught:
+ *
+ *  - tap's eager dispatch bailout is more aggressive than React's: no stale
+ *    lanes, so a same-value dispatch right after an update skips the render
+ *    React still does, and no-change renders commit no-deps effects.
+ *  - Bridge dispatches ride the host's React reducer: a fully bailable
+ *    dispatch renders the host once where React and tap roots render nothing.
+ *  - useLayoutEffect collapses onto useEffect (no layout phase).
+ *  - Dispatch after unmount applies, like an Activity hide: tap cannot
+ *    distinguish a hide from a deletion. Do NOT add an isMounted guard.
+ */
+/* oxlint-disable react/exhaustive-deps -- intentional missing-dep patterns are part of the scenarios */
+import { describe, it, expect } from "vitest";
+import { useEffect, useLayoutEffect, useReducer, useState } from "react";
+import {
+  isDevMode,
+  runScenario,
+  TAP_ENVS,
+  type Scenario,
+} from "./describeParity";
+
+const countOf = (events: string[], entry: string) =>
+  events.filter((e) => e === entry).length;
+
+/** Body invocations per committed render pass (dev double-invokes). */
+const perRender = isDevMode ? 2 : 1;
+
+describe("divergence: eager dispatch bailout is more aggressive than React's", () => {
+  it("same-value dispatch right after an update: React renders once more; tap roots bail", async () => {
+    // React's eager bailout needs idle lanes on the fiber AND its alternate;
+    // a committed update leaves the alternate's lanes stale, so the next
+    // same-value dispatch still renders (a bailout render that clears them).
+    // tap bails on Object.is equality whenever its batch is empty: strictly
+    // fewer renders, identical state. Matching React exactly takes a lanes
+    // emulation (dirty bit + bailout-render detection + effect suppression +
+    // args guard); it was implemented and reverted as not worth the hot-path
+    // complexity, since only impure updaters and render bodies can observe
+    // the difference.
+    const scenario: Scenario = {
+      name: "",
+      use: (log) => {
+        const [count, setCount] = useState(0);
+        log(`render ${count}`);
+        return { set: (n: number) => setCount(n) };
+      },
+      drive: async ({ api, act }) => {
+        await act(() => api().set(1));
+        await act(() => api().set(1));
+      },
+    };
+
+    const react = await runScenario("react", scenario);
+    expect(countOf(react, "render 1")).toBe(2 * perRender);
+
+    for (const env of ["tapRoot", "createTapRoot"] as const) {
+      const tap = await runScenario(env, scenario);
+      expect(countOf(tap, "render 1")).toBe(perRender);
+    }
+
+    const bridge = await runScenario("bridge", scenario);
+    expect(bridge).toEqual(react);
+  });
+
+  it("no-change render: React strips no-deps effects (bailoutHooks); tap commits them", async () => {
+    // Consistent with tap's whole-tree re-renders, which refire no-deps
+    // effects on every update anyway.
+    const scenario: Scenario = {
+      name: "",
+      use: (log) => {
+        const [state, dispatch] = useReducer((s: number) => s, 42);
+        log(`render ${state}`);
+        useEffect(() => {
+          log("effect");
+          return () => log("cleanup");
+        });
+        return { dispatch };
+      },
+      drive: async ({ api, act }) => {
+        await act(() => api().dispatch(0));
+      },
+    };
+
+    const react = await runScenario("react", scenario);
+
+    for (const env of TAP_ENVS) {
+      const tap = await runScenario(env, scenario);
+      expect(countOf(tap, "render 42")).toBe(countOf(react, "render 42"));
+      expect(countOf(tap, "effect")).toBe(countOf(react, "effect") + 1);
+      expect(countOf(tap, "cleanup")).toBe(countOf(react, "cleanup") + 1);
+    }
+  });
+});
+
+describe("divergence: fully-bailable dispatch renders the bridge host once", () => {
+  const scenario: Scenario = {
+    name: "",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      return { set: (n: number) => setCount(n) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().set(0));
+    },
+  };
+
+  it("React and tap roots bail without rendering; the bridge renders once", async () => {
+    const react = await runScenario("react", scenario);
+    expect(countOf(react, "render 0")).toBe(perRender);
+
+    for (const env of ["tapRoot", "createTapRoot"] as const) {
+      const tap = await runScenario(env, scenario);
+      expect(tap).toEqual(react);
+    }
+
+    const bridge = await runScenario("bridge", scenario);
+    expect(countOf(bridge, "render 0")).toBe(2 * perRender);
+  });
+});
+
+describe("divergence: dispatch from an unmount cleanup applies (Activity semantics)", () => {
+  const scenario: Scenario = {
+    name: "",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        log(`mount ${count}`);
+        return () => {
+          log(`cleanup ${count}`);
+          setCount(99);
+        };
+      }, []);
+    },
+    unmountAtEnd: true,
+  };
+
+  it("React drops it (deletion); tap roots apply it like an Activity hide", async () => {
+    const react = await runScenario("react", scenario);
+    const bridge = await runScenario("bridge", scenario);
+    expect(bridge).toEqual(react);
+
+    if (isDevMode) {
+      // In dev the strict remount cycle runs the cleanup while still mounted,
+      // so even React renders 99 during mount.
+      expect(react).toContain("render 99");
+    } else {
+      expect(react).not.toContain("render 99");
+    }
+
+    for (const env of ["tapRoot", "createTapRoot"] as const) {
+      const tap = await runScenario(env, scenario);
+      if (isDevMode) {
+        // The strict remount cycle already set 99 while mounted; the unmount
+        // dispatch then bails eagerly on equality, masking the divergence.
+        expect(tap).toEqual(react);
+      } else {
+        // tap cannot distinguish this deletion from an Activity-style hide,
+        // so the update applies and the (pure) render runs; effects stay off.
+        expect(tap).toEqual([...react, "render 99"]);
+      }
+    }
+  });
+});
+
+describe("divergence: useLayoutEffect is an alias for useEffect", () => {
+  const scenario: Scenario = {
+    name: "",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      useEffect(() => {
+        log(`passive n=${n}`);
+        return () => log(`passive-cleanup n=${n}`);
+      }, [n]);
+      useLayoutEffect(() => {
+        log(`layout n=${n}`);
+        return () => log(`layout-cleanup n=${n}`);
+      }, [n]);
+      return { bump: () => setN((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().bump());
+    },
+  };
+
+  it("React runs the layout phase first; tap runs call order", async () => {
+    const react = await runScenario("react", scenario);
+    expect(react.slice(-4)).toEqual([
+      "layout-cleanup n=0",
+      "layout n=1",
+      "passive-cleanup n=0",
+      "passive n=1",
+    ]);
+
+    for (const env of TAP_ENVS) {
+      const tap = await runScenario(env, scenario);
+      expect(tap.slice(-4)).toEqual([
+        "passive-cleanup n=0",
+        "layout-cleanup n=0",
+        "passive n=1",
+        "layout n=1",
+      ]);
+    }
+  });
+});

package/src/__tests__/parity/parity.smoke.test.tsx

@@ -0,0 +1,43 @@
+/* oxlint-disable react/exhaustive-deps -- intentional patterns are part of the scenarios */
+import { describe, it, expect } from "vitest";
+import { useEffect, useState } from "react";
+import {
+  describeParity,
+  isDevMode,
+  runScenario,
+  type Scenario,
+} from "./describeParity";
+
+describe("harness smoke", () => {
+  it("runs against the React build matching the project mode", () => {
+    expect(process.env.NODE_ENV === "production").toBe(!isDevMode);
+  });
+
+  it("react env observes StrictMode double render only in dev", async () => {
+    const scenario: Scenario = {
+      name: "",
+      use: (log) => log("render"),
+    };
+    const events = await runScenario("react", scenario);
+    expect(events).toEqual(isDevMode ? ["render", "render"] : ["render"]);
+  });
+});
+
+describeParity([
+  {
+    name: "smoke: mount, effect, event-handler setState",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      useEffect(() => {
+        log(`effect ${count}`);
+        return () => log(`cleanup ${count}`);
+      }, [count]);
+      return { increment: () => setCount((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().increment());
+    },
+    unmountAtEnd: true,
+  },
+]);

package/src/__tests__/react/concurrent-mode.test.tsx

@@ -2,8 +2,8 @@ import { describe, it, expect } from "vitest";
 import { render, screen, act } from "@testing-library/react";
 import { Suspense, startTransition, use, useState } from "react";
 import { resource } from "../../core/resource";
-import { useResource } from "../../react/hooks";
-import { useState as useResourceState } from "../../hooks/useState";
+import { useResource } from "../../index";
+import { useState as useResourceState } from "../../react-hooks/useState";
 
 const ShouldNeverFallback = () => {
   throw new Error("should never fallback");
@@ -11,9 +11,11 @@ const ShouldNeverFallback = () => {
 
 describe("Concurrent Mode with useResource", () => {
   it("should not commit useResourceState updates when render is discarded", async () => {
-    const TestResource = resource(function TestResource() {
+    const useTestResource = () => {
       return useResourceState(false);
-    });
+    };
+
+    const TestResource = resource(useTestResource);
 
     let resolve: (value: number) => void;
 
@@ -142,14 +144,16 @@ describe("Concurrent Mode with useResource", () => {
     let resolve: () => void;
     let shouldSuspend = false;
 
-    const TestResource = resource(function TestResource(props: { id: number }) {
+    const useTestResource = (props: { id: number }) => {
       if (shouldSuspend) {
         throw new Promise<void>((r) => {
           resolve = r;
         });
       }
       return { value: `content-${props.id}` };
-    });
+    };
+
+    const TestResource = resource(useTestResource);
 
     function Inner({ id }: { id: number }) {
       const result = useResource(TestResource({ id }));