@assistant-ui/tap 0.6.0 → 0.7.1

package/src/__tests__/parity/describeParity.tsx

@@ -0,0 +1,217 @@
+/**
+ * Differential parity harness.
+ *
+ * tap's hooks are React's hooks (imported from "react" and resolved through
+ * the dispatcher inside resource renders), so the same scenario body can run
+ * in four environments:
+ *
+ *  1. react         - as a component under <StrictMode>
+ *  2. bridge        - as a resource hosted via useResource inside <StrictMode>
+ *  3. tapRoot       - inside useTapRoot(function Root() {...}) in a component
+ *  4. createTapRoot - as a resource under createTapRoot (no React host)
+ *
+ * Each test runs the scenario in the react environment to capture the
+ * expected event log, then asserts the tap environments produce the identical
+ * log. React is the source of truth; there are no hand-maintained expected
+ * sequences to drift.
+ *
+ * The whole suite runs twice via vitest projects: once with NODE_ENV=test
+ * (dev React build, StrictMode double-invocation, tap devStrictMode) and once
+ * with NODE_ENV=production (prod React build, StrictMode inert, tap strict
+ * emulation off). React's prod build throws on act(), so this harness avoids
+ * act entirely: renders and event-handler updates are forced with flushSync /
+ * flushTapSync, and async work (passive effects, schedulers, promises) is
+ * absorbed by settling on a timer.
+ */
+import { describe, it, expect } from "vitest";
+import { createElement, StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { resource } from "../../core/resource";
+import { createTapRoot } from "../../core/createTapRoot";
+import { flushTapSync } from "../../core/scheduler";
+import { useResource } from "../../hooks/useResource";
+import { useTapRoot } from "../../hooks/useTapRoot";
+
+/** Mirrors tap's core/helpers/env so scenarios can branch on the mode. */
+export const isDevMode = process.env.NODE_ENV !== "production";
+
+// We deliberately do not use act(): it does not exist in prod React builds.
+// Silence the dev-build "not wrapped in act" warning machinery.
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = false;
+
+export type Log = (event: string) => void;
+
+export type DriveContext = {
+  /** Latest value returned by the scenario body. */
+  api: () => any;
+  /** Dispatch an update like an event handler would, then settle. */
+  act: (fn: () => void) => Promise<void>;
+  /** Wait for async work (promises, scheduler flushes) to settle. */
+  settle: () => Promise<void>;
+};
+
+export type TapEnv = "bridge" | "tapRoot" | "createTapRoot";
+export const TAP_ENVS = ["bridge", "tapRoot", "createTapRoot"] as const;
+
+export type Scenario = {
+  name: string;
+  use: (log: Log) => any;
+  drive?: (ctx: DriveContext) => void | Promise<void>;
+  unmountAtEnd?: boolean;
+  /**
+   * Documented divergences, keyed by tap environment:
+   * - "multiset": same events must occur, order may differ. Used for the
+   *   bridge, where a dispatch rides through the host's React reducer so the
+   *   eager invocation of an impure updater is deferred to the host's next
+   *   render. Invocation multiset and final state must still match React.
+   * - "skip": environment intentionally not compared (assert the divergent
+   *   behavior in a dedicated test instead).
+   */
+  divergence?: Partial<Record<TapEnv, "multiset" | "skip">>;
+};
+
+// Settle until two consecutive windows pass without new events, so delayed
+// timers under suite load (parallel test files compete for CPU) cannot
+// truncate a log.
+const makeSettle = (events: string[]) => async () => {
+  let quiet = 0;
+  while (quiet < 2) {
+    const prev = events.length;
+    await new Promise<void>((r) => setTimeout(r, 20));
+    quiet = events.length === prev ? quiet + 1 : 0;
+  }
+};
+
+type Host = {
+  api: () => any;
+  /** Synchronously flush an event-handler-style update. */
+  flush: (fn: () => void) => void;
+  unmount: () => void;
+};
+
+/** Shared React host for the react, bridge and tapRoot environments. */
+const mountReactHost = (
+  useProbeBody: (log: Log) => () => any,
+  log: Log,
+): Host => {
+  let api: () => any = () => undefined;
+  function Probe() {
+    api = useProbeBody(log);
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  // createElement instead of JSX so the harness is independent of the
+  // dev/prod jsx runtime split (jsxDEV does not exist in prod builds).
+  flushSync(() =>
+    root.render(createElement(StrictMode, null, createElement(Probe))),
+  );
+  return {
+    api: () => api(),
+    flush: (fn) => flushSync(fn),
+    unmount: () => flushSync(() => root.unmount()),
+  };
+};
+
+const mountEnv = (
+  env: "react" | TapEnv,
+  scenario: Scenario,
+  log: Log,
+): Host => {
+  switch (env) {
+    case "react":
+      return mountReactHost((log) => {
+        const value = scenario.use(log);
+        return () => value;
+      }, log);
+    case "bridge": {
+      const useScenario = (props: { log: Log }) => scenario.use(props.log);
+      const Scenario = resource(useScenario);
+      return mountReactHost((log) => {
+        const value = useResource(Scenario({ log }));
+        return () => value;
+      }, log);
+    }
+    case "tapRoot": {
+      const host = mountReactHost((log) => {
+        const root = useTapRoot(function Root() {
+          return scenario.use(log);
+        });
+        return () => root.getValue();
+      }, log);
+      // Updates inside the tap root are scheduled by tap, not React.
+      return { ...host, flush: (fn) => flushTapSync(fn) };
+    }
+    case "createTapRoot": {
+      const root = createTapRoot(function Root() {
+        return scenario.use(log);
+      });
+      return {
+        api: () => root.getValue(),
+        flush: (fn) => flushTapSync(fn),
+        unmount: () => root.unmount(),
+      };
+    }
+  }
+};
+
+export const runScenario = async (
+  env: "react" | TapEnv,
+  scenario: Scenario,
+): Promise<string[]> => {
+  const events: string[] = [];
+  // The run ends before the host is torn down; stop logging so the teardown's
+  // effect cleanups don't leak into the captured log.
+  let done = false;
+  const log: Log = (e) => void (done || events.push(e));
+  const settle = makeSettle(events);
+
+  const host = mountEnv(env, scenario, log);
+  await settle();
+  await scenario.drive?.({
+    api: host.api,
+    act: async (fn) => {
+      host.flush(fn);
+      await settle();
+    },
+    settle,
+  });
+  await settle();
+  if (scenario.unmountAtEnd) {
+    host.unmount();
+    await settle();
+  }
+  done = true;
+  if (!scenario.unmountAtEnd) host.unmount();
+  return events;
+};
+
+/**
+ * Generates a describe block per scenario asserting each tap environment
+ * produces the exact event log React produces. The react run is shared
+ * across the three comparisons.
+ */
+export const describeParity = (scenarios: Scenario[]) => {
+  for (const scenario of scenarios) {
+    describe(scenario.name, () => {
+      let reactLog: Promise<string[]> | undefined;
+      const getReactLog = () => (reactLog ??= runScenario("react", scenario));
+
+      for (const env of TAP_ENVS) {
+        const divergence = scenario.divergence?.[env];
+        if (divergence === "skip") continue;
+
+        it(`${env} matches react`, async () => {
+          const expected = await getReactLog();
+          expect(expected.length).toBeGreaterThan(0);
+          const actual = await runScenario(env, scenario);
+          if (divergence === "multiset") {
+            expect([...actual].sort()).toEqual([...expected].sort());
+          } else {
+            expect(actual).toEqual(expected);
+          }
+        });
+      }
+    });
+  }
+};

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

@@ -0,0 +1,375 @@
+/**
+ * Adversarial parity scenarios: each one was designed to break the
+ * React/tap equivalence and survived. Anything that diverged instead is
+ * documented in parity.divergences.test.tsx.
+ */
+/* 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: "reducer closing over another reducer's state, batched cross-dispatch",
+    use: (log) => {
+      const [value, dispatch] = useReducer((s: number, a: number) => {
+        log(`r1 s=${s} a=${a}`);
+        return s + a;
+      }, 1);
+      const [value2, dispatch2] = useReducer((a: number, b: number) => {
+        log(`r2 a=${a} b=${b} value=${value}`);
+        return a + b * value;
+      }, 0);
+      log(`render v=${value} v2=${value2}`);
+      return { dispatch, dispatch2 };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().dispatch2(10));
+      await act(() => {
+        api().dispatch(1);
+        api().dispatch2(10);
+      });
+      await act(() => {
+        api().dispatch2(1);
+        api().dispatch(5);
+        api().dispatch2(2);
+      });
+    },
+  },
+  {
+    name: "reducer closing over useState value updated in the same batch",
+    use: (log) => {
+      const [mode, setMode] = useState(1);
+      const [total, add] = useReducer((s: number, n: number) => {
+        log(`reducer s=${s} n=${n} mode=${mode}`);
+        return s + n * mode;
+      }, 0);
+      log(`render mode=${mode} total=${total}`);
+      return { setMode, add };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => {
+        api().add(10);
+        api().setMode(100);
+        api().add(10);
+      });
+      await act(() => api().add(1));
+    },
+  },
+  {
+    name: "same reducer dispatched three times in one batch",
+    use: (log) => {
+      const [state, dispatch] = useReducer((s: number, a: number) => {
+        log(`reducer s=${s} a=${a}`);
+        return s * 2 + a;
+      }, 1);
+      log(`render ${state}`);
+      return { dispatch };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => {
+        api().dispatch(1);
+        api().dispatch(2);
+        api().dispatch(3);
+      });
+    },
+  },
+  {
+    name: "mixed eager setState and lazy useReducer dispatch ordering",
+    use: (log) => {
+      const [a, setA] = useState(0);
+      const [b, dispatchB] = useReducer((s: number, n: number) => {
+        log(`reducerB s=${s} n=${n}`);
+        return s + n;
+      }, 0);
+      log(`render a=${a} b=${b}`);
+      return {
+        run: () => {
+          setA((prev) => {
+            log(`updaterA prev=${prev}`);
+            return prev + 1;
+          });
+          dispatchB(10);
+          setA((prev) => {
+            log(`updaterA2 prev=${prev}`);
+            return prev + 1;
+          });
+        },
+      };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().run());
+    },
+  },
+  {
+    name: "render-phase updates chain until they settle",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      if (count < 3) setCount(count + 1);
+    },
+  },
+  {
+    name: "render-phase updater chain with a guard converges",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      if (count < 5) {
+        setCount((c) => c + 1);
+      }
+    },
+  },
+  {
+    name: "render-phase updater functions apply in order",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      if (count === 0) {
+        setCount((c) => {
+          log(`updater1 c=${c}`);
+          return c + 1;
+        });
+        setCount((c) => {
+          log(`updater2 c=${c}`);
+          return c + 10;
+        });
+      }
+    },
+  },
+  {
+    name: "render-phase setState to the same value runs one extra pass",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      const dispatched = useRef(false);
+      log(`render ${count}`);
+      if (!dispatched.current) {
+        dispatched.current = true;
+        setCount(0);
+      }
+    },
+  },
+  {
+    name: "render-phase adjustment derives one state from another across updates",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      const [doubled, setDoubled] = useState(0);
+      log(`render n=${n} doubled=${doubled}`);
+      if (doubled !== n * 2) setDoubled(n * 2);
+      return { bump: () => setN((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().bump());
+      await act(() => api().bump());
+    },
+  },
+  {
+    name: "render-phase dispatch to a useReducer during render",
+    use: (log) => {
+      const [count, dispatch] = useReducer((s: number, a: number) => {
+        log(`reducer s=${s} a=${a}`);
+        return s + a;
+      }, 0);
+      log(`render ${count}`);
+      if (count === 0) dispatch(5);
+    },
+  },
+  {
+    name: "setState inside a useMemo body is a render-phase update",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      useMemo(() => {
+        if (count === 0) setCount(1);
+        return null;
+      }, [count]);
+      log(`render ${count}`);
+    },
+  },
+  {
+    name: "bail-then-revert in one batch forces a render with the same state",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      return {
+        bounce: () => {
+          setCount(1);
+          setCount(0);
+        },
+      };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().bounce());
+      await act(() => api().bounce());
+    },
+  },
+  {
+    name: "NaN and negative zero: Object.is semantics for bailout",
+    use: (log) => {
+      const [value, setValue] = useState<number>(0);
+      log(`render ${Number.isNaN(value) ? "NaN" : value}`);
+      return { set: (n: number) => setValue(n) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().set(NaN));
+      await act(() => api().set(-0));
+      await act(() => api().set(0));
+    },
+  },
+  {
+    name: "NaN in deps: memo and effect do not refire",
+    use: (log) => {
+      const [, force] = useReducer((c: number) => c + 1, 0);
+      const dep = NaN;
+      useMemo(() => {
+        log("memo");
+        return null;
+      }, [dep]);
+      useEffect(() => {
+        log("effect");
+      }, [dep]);
+      log("render");
+      return { force };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().force());
+    },
+  },
+  {
+    name: "setState/dispatch function identity is stable across renders",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      const [, dispatch] = useReducer((s: number) => s + 1, 0);
+      const firstSet = useRef(setCount);
+      const firstDispatch = useRef(dispatch);
+      log(
+        `render ${count} set-stable=${firstSet.current === setCount} dispatch-stable=${firstDispatch.current === dispatch}`,
+      );
+      return { inc: () => setCount((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().inc());
+    },
+  },
+  {
+    name: "ref mutation during render observes strict double-render",
+    use: (log) => {
+      const renders = useRef(0);
+      renders.current++;
+      const [count, setCount] = useState(0);
+      log(`render count=${count} renders=${renders.current}`);
+      return { inc: () => setCount((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().inc());
+    },
+  },
+  {
+    name: "two dispatches in separate microtasks batch into one render",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      return { inc: () => setCount((c) => c + 1) };
+    },
+    drive: async ({ api, settle }) => {
+      api().inc();
+      await Promise.resolve();
+      api().inc();
+      await settle();
+    },
+  },
+  {
+    name: "two dispatches in separate macrotasks render separately",
+    use: (log) => {
+      const [count, setCount] = useState(0);
+      log(`render ${count}`);
+      return { inc: () => setCount((c) => c + 1) };
+    },
+    drive: async ({ api, settle }) => {
+      api().inc();
+      await new Promise((r) => setTimeout(r, 10));
+      api().inc();
+      await settle();
+    },
+  },
+  {
+    name: "update render: cleanup/setup ordering across two effects",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      useEffect(() => {
+        log(`setup-1 n=${n}`);
+        return () => log(`cleanup-1 n=${n}`);
+      }, [n]);
+      useEffect(() => {
+        log(`setup-2 n=${n}`);
+        return () => log(`cleanup-2 n=${n}`);
+      }, [n]);
+      return { bump: () => setN((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().bump());
+    },
+  },
+  {
+    name: "effect deps array grows between renders",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      const deps = n === 0 ? [1] : [1, 2];
+      useEffect(() => {
+        log(`effect n=${n}`);
+        return () => log(`cleanup n=${n}`);
+      }, deps);
+      log(`render ${n}`);
+      return { bump: () => setN((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().bump());
+    },
+  },
+  {
+    name: "dispatch from an effect cleanup on deps change",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      const [extra, bumpExtra] = useReducer((c: number) => c + 1, 0);
+      log(`render n=${n} extra=${extra}`);
+      useEffect(() => {
+        log(`setup n=${n}`);
+        return () => {
+          log(`cleanup n=${n}`);
+          bumpExtra();
+        };
+      }, [n]);
+      return { bump: () => setN((c) => c + 1) };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().bump());
+    },
+  },
+  {
+    name: "cascading updates: effect chain until fixpoint",
+    use: (log) => {
+      const [n, setN] = useState(0);
+      log(`render ${n}`);
+      useEffect(() => {
+        log(`effect ${n}`);
+        if (n < 3) setN(n + 1);
+      }, [n]);
+    },
+    drive: ({ settle }) => settle(),
+  },
+  {
+    name: "memo depending on reducer state recomputes exactly once per change",
+    use: (log) => {
+      const [n, dispatch] = useReducer((s: number, a: number) => s + a, 0);
+      const doubled = useMemo(() => {
+        log(`memo n=${n}`);
+        return n * 2;
+      }, [n]);
+      log(`render n=${n} doubled=${doubled}`);
+      return { dispatch };
+    },
+    drive: async ({ api, act }) => {
+      await act(() => api().dispatch(1));
+      await act(() => api().dispatch(0));
+    },
+  },
+];
+
+describeParity(scenarios);