@assistant-ui/tap 0.5.13 → 0.6.0

package/src/__tests__/lifecycle/lifecycle.mount-unmount.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
-import { tapEffect } from "../../hooks/tap-effect";
-import { tapState } from "../../hooks/tap-state";
+import { useEffect } from "../../hooks/useEffect";
+import { useState } from "../../hooks/useState";
 import { createTestResource, renderTest, unmountResource } from "../test-utils";
 import {
   renderResourceFiber,
@@ -13,8 +13,7 @@ describe("Lifecycle - Mount/Unmount", () => {
     const effects = [vi.fn(), vi.fn(), vi.fn()];
 
     const resource = createTestResource(() => {
-      // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
-      effects.forEach((fn) => tapEffect(fn));
+      effects.forEach((fn) => useEffect(fn));
       return null;
     });
 
@@ -30,17 +29,15 @@ describe("Lifecycle - Mount/Unmount", () => {
 
     const resource = createTestResource(() => {
       cleanups.forEach((cleanup) => {
-        tapEffect(() => cleanup);
+        useEffect(() => cleanup);
       });
       return null;
     });
 
     renderTest(resource, undefined);
-    // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
     cleanups.forEach((fn) => expect(fn).not.toHaveBeenCalled());
 
     unmountResource(resource);
-    // biome-ignore lint/suspicious/useIterableCallbackReturn: forEach callback intentionally has no return
     cleanups.forEach((fn) => expect(fn).toHaveBeenCalledTimes(1));
   });
 
@@ -48,9 +45,9 @@ describe("Lifecycle - Mount/Unmount", () => {
     const order: number[] = [];
 
     const resource = createTestResource(() => {
-      tapEffect(() => () => order.push(1));
-      tapEffect(() => () => order.push(2));
-      tapEffect(() => () => order.push(3));
+      useEffect(() => () => order.push(1));
+      useEffect(() => () => order.push(2));
+      useEffect(() => () => order.push(3));
       return null;
     });
 
@@ -67,11 +64,11 @@ describe("Lifecycle - Mount/Unmount", () => {
 
     const resource = createTestResource((props: number) => {
       renderCount++;
-      const [state, _setState] = tapState({ count: 0 });
+      const [state, _setState] = useState({ count: 0 });
       setState = _setState;
 
       // Simple effect that tracks runs
-      tapEffect(() => {
+      useEffect(() => {
         effectRunCount++;
       });
 
@@ -103,18 +100,18 @@ describe("Lifecycle - Mount/Unmount", () => {
     const log: string[] = [];
 
     const resource = createTestResource(() => {
-      const [mounted, setMounted] = tapState(false);
+      const [mounted, setMounted] = useState(false);
 
       log.push("render");
 
-      tapEffect(() => {
+      useEffect(() => {
         log.push("effect-1");
         setMounted(true);
 
         return () => log.push("cleanup-1");
       });
 
-      tapEffect(() => {
+      useEffect(() => {
         log.push("effect-2");
         return () => log.push("cleanup-2");
       });
@@ -131,8 +128,7 @@ describe("Lifecycle - Mount/Unmount", () => {
     // After commit: initial render + effects
     expect(log).toEqual(["render", "effect-1", "effect-2"]);
 
-    // The setState in effect schedules a re-render
-    // With the new architecture, we need to manually trigger it
+    // The setState in effect schedules a re-render; trigger it manually
     const ctx2 = renderResourceFiber(resource, undefined);
     commitResourceFiber(resource, ctx2);
 
@@ -161,10 +157,10 @@ describe("Lifecycle - Mount/Unmount", () => {
     const goodCleanup = vi.fn();
 
     const resource = createTestResource(() => {
-      tapEffect(() => () => {
+      useEffect(() => () => {
         throw error;
       });
-      tapEffect(() => goodCleanup);
+      useEffect(() => goodCleanup);
       return null;
     });
 
@@ -181,7 +177,7 @@ describe("Lifecycle - Mount/Unmount", () => {
 
     const resource = createTestResource(() => {
       if (!skipEffect) {
-        tapEffect(() => cleanup);
+        useEffect(() => cleanup);
       }
       return null;
     });
@@ -197,7 +193,7 @@ describe("Lifecycle - Mount/Unmount", () => {
     const cleanup = vi.fn();
 
     const resource = createTestResource(() => {
-      tapEffect(() => {
+      useEffect(() => {
         effect();
         return cleanup;
       });

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

@@ -2,17 +2,17 @@ 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/use-resource";
-import { tapState } from "../../hooks/tap-state";
+import { useResource } from "../../react/hooks";
+import { useState as useResourceState } from "../../hooks/useState";
 
 const ShouldNeverFallback = () => {
   throw new Error("should never fallback");
 };
 
 describe("Concurrent Mode with useResource", () => {
-  it("should not commit tapState updates when render is discarded", async () => {
-    const TestResource = resource(() => {
-      return tapState(false);
+  it("should not commit useResourceState updates when render is discarded", async () => {
+    const TestResource = resource(function TestResource() {
+      return useResourceState(false);
     });
 
     let resolve: (value: number) => void;
@@ -76,7 +76,7 @@ describe("Concurrent Mode with useResource", () => {
     expect(screen.getByTestId("message").textContent).toBe("hello");
   });
 
-  it("react should not commit tapState updates when render is discarded", async () => {
+  it("react should not commit useResourceState updates when render is discarded", async () => {
     let resolve: (value: number) => void;
 
     const suspendPromise = new Promise<number>((r) => {
@@ -142,7 +142,7 @@ describe("Concurrent Mode with useResource", () => {
     let resolve: () => void;
     let shouldSuspend = false;
 
-    const TestResource = resource((props: { id: number }) => {
+    const TestResource = resource(function TestResource(props: { id: number }) {
       if (shouldSuspend) {
         throw new Promise<void>((r) => {
           resolve = r;

package/src/__tests__/react/react-shim.test.tsx

@@ -0,0 +1,65 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, act, cleanup } from "@testing-library/react";
+import {
+  createTestResource,
+  renderTest,
+  cleanupAllResources,
+  getCommittedOutput,
+  waitForNextTick,
+} from "../test-utils";
+import { useState, useEffect } from "../../react-shim";
+
+describe("@assistant-ui/tap/react-shim", () => {
+  afterEach(() => {
+    cleanupAllResources();
+    cleanup();
+  });
+
+  describe("inside a tap resource", () => {
+    it("useState routes to useState and useEffect to useEffect", async () => {
+      let setCount: ((n: number) => void) | null = null;
+      const effectLog: number[] = [];
+
+      const testFiber = createTestResource(() => {
+        const [count, set] = useState(0);
+        useEffect(() => {
+          setCount = set;
+          effectLog.push(count);
+        }, [count]);
+        return count;
+      });
+
+      renderTest(testFiber, undefined);
+      expect(getCommittedOutput(testFiber)).toBe(0);
+      expect(effectLog).toEqual([0]);
+
+      setCount!(5);
+      await waitForNextTick();
+      expect(getCommittedOutput(testFiber)).toBe(5);
+      expect(effectLog).toEqual([0, 5]);
+    });
+  });
+
+  describe("inside a React component", () => {
+    it("useState routes to React.useState", () => {
+      function Counter() {
+        const [count, setCount] = useState(0);
+        return (
+          <button
+            type="button"
+            data-testid="btn"
+            onClick={() => setCount(count + 1)}
+          >
+            {count}
+          </button>
+        );
+      }
+
+      render(<Counter />);
+      const btn = screen.getByTestId("btn");
+      expect(btn.textContent).toBe("0");
+      act(() => btn.click());
+      expect(btn.textContent).toBe("1");
+    });
+  });
+});

package/src/__tests__/react/useResource.test.tsx

@@ -0,0 +1,172 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, act, cleanup } from "@testing-library/react";
+import {
+  createTestResource,
+  renderTest,
+  cleanupAllResources,
+} from "../test-utils";
+import { resource } from "../../core/resource";
+import { withKey } from "../../core/withKey";
+import { useState } from "react";
+import { useState as useResourceState } from "../../hooks/useState";
+import { useEffect as useResourceEffect } from "../../hooks/useEffect";
+import {
+  useResource,
+  useResources,
+  useResourceRoot,
+  flushResourcesSync,
+} from "../../index";
+
+describe("@assistant-ui/tap/react resource API", () => {
+  afterEach(() => {
+    cleanupAllResources();
+    cleanup();
+  });
+
+  describe("useResource", () => {
+    it("routes to useResource inside a tap resource", () => {
+      const Child = resource(function Child(props: { n: number }) {
+        return props.n * 2;
+      });
+      const parent = createTestResource(() => useResource(Child({ n: 21 })));
+      expect(renderTest(parent, undefined)).toBe(42);
+    });
+
+    it("routes to the React bridge inside a component", () => {
+      const CounterResource = resource(function CounterResource() {
+        const [count, setCount] = useResourceState(0);
+        return { count, setCount };
+      });
+
+      let api: { count: number; setCount: (n: number) => void } | null = null;
+      function App() {
+        api = useResource(CounterResource());
+        return <div data-testid="count">{api.count}</div>;
+      }
+
+      render(<App />);
+      expect(screen.getByTestId("count").textContent).toBe("0");
+      act(() => api!.setCount(3));
+      expect(screen.getByTestId("count").textContent).toBe("3");
+    });
+  });
+
+  describe("useResources", () => {
+    it("hosts a keyed list inside a tap resource", () => {
+      const Item = resource(function Item(p: { n: number }) {
+        return p.n * 10;
+      });
+      const parent = createTestResource(() =>
+        useResources(() => [
+          withKey("a", Item({ n: 1 })),
+          withKey("b", Item({ n: 2 })),
+        ]),
+      );
+      expect(renderTest(parent, undefined)).toEqual([10, 20]);
+    });
+
+    it("hosts a keyed list inside a React component and tracks deps", () => {
+      const Item = resource(function Item(p: { n: number }) {
+        const [v] = useResourceState(p.n * 10);
+        return v;
+      });
+
+      let setCount: (n: number) => void = () => {};
+      function App() {
+        const [count, setCountState] = useState(2);
+        setCount = setCountState;
+        const items = useResources(
+          () =>
+            Array.from({ length: count }, (_, i) =>
+              withKey(i, Item({ n: i + 1 })),
+            ),
+          [count],
+        );
+        return <div data-testid="list">{items.join(",")}</div>;
+      }
+
+      render(<App />);
+      expect(screen.getByTestId("list").textContent).toBe("10,20");
+      act(() => setCount(3));
+      expect(screen.getByTestId("list").textContent).toBe("10,20,30");
+    });
+  });
+
+  describe("useResourceRoot", () => {
+    it("exposes a subscribable inside a tap resource", () => {
+      const Root = resource(function Root() {
+        const [n] = useResourceState(7);
+        return n;
+      });
+      const parent = createTestResource(() =>
+        useResourceRoot(Root()).getValue(),
+      );
+      expect(renderTest(parent, undefined)).toBe(7);
+    });
+
+    // A root is push-based: host it in one place and observe it via getValue/
+    // subscribe elsewhere. (Hosting AND re-rendering off its own value in the same
+    // component self-feeds, since useResourceHost re-renders the root on every host render
+    // and the root notifies on output change — so this test observes the store
+    // directly rather than through a same-component useSyncExternalStore.)
+    it("hosts a subscribable root inside a React component", () => {
+      const CounterRoot = resource(function CounterRoot() {
+        const [count, setCount] = useResourceState(0);
+        return { count, setCount };
+      });
+
+      let store: ReturnType<
+        typeof useResourceRoot<{
+          count: number;
+          setCount: (n: number) => void;
+        }>
+      > | null = null;
+      function App() {
+        store = useResourceRoot(CounterRoot());
+        return null;
+      }
+
+      render(<App />);
+      expect(store!.getValue().count).toBe(0);
+
+      let notified = 0;
+      const unsubscribe = store!.subscribe(() => {
+        notified++;
+      });
+
+      // The root drives updates through tap's own (macrotask) scheduler, so flush
+      // synchronously to observe.
+      flushResourcesSync(() => store!.getValue().setCount(5));
+      expect(store!.getValue().count).toBe(5);
+      expect(notified).toBeGreaterThan(0);
+
+      unsubscribe();
+    });
+  });
+
+  describe("useResource key remount (React bridge)", () => {
+    it("remounts the hosted resource when the element key changes", () => {
+      const mounts: number[] = [];
+      const Keyed = resource(function Keyed(p: { id: number }) {
+        // oxlint-disable-next-line react/exhaustive-deps -- capture the mount id once per fiber to assert remount on key change
+        useResourceEffect(() => void mounts.push(p.id), []);
+        return p.id;
+      });
+
+      let setId: (n: number) => void = () => {};
+      function App() {
+        const [id, setIdState] = useState(1);
+        setId = setIdState;
+        const out = useResource(withKey(id, Keyed({ id })));
+        return <div data-testid="keyed">{out}</div>;
+      }
+
+      render(<App />);
+      expect(screen.getByTestId("keyed").textContent).toBe("1");
+      expect(mounts).toEqual([1]);
+      act(() => setId(2));
+      expect(screen.getByTestId("keyed").textContent).toBe("2");
+      expect(mounts).toEqual([1, 2]);
+    });
+  });
+});

package/src/__tests__/react-dispatcher.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, afterEach } from "vitest";
+import * as React from "react";
+// react/compiler-runtime exports `c` (= useMemoCache) at runtime but ships no types for it.
+// @ts-expect-error -- runtime-only export
+import { c as _c } from "react/compiler-runtime";
+import { renderResourceFiber } from "../core/ResourceFiber";
+import {
+  createTestResource,
+  renderTest,
+  getCommittedOutput,
+  cleanupAllResources,
+  waitForNextTick,
+} from "./test-utils";
+
+// These resources author their hooks with the *real* `react` module (no shim, no
+// build transform). tap's React dispatcher, installed around every resource body
+// render, is what routes them to tap.
+describe("react dispatcher", () => {
+  afterEach(() => {
+    cleanupAllResources();
+  });
+
+  it("routes React.useState to tap state", async () => {
+    let set!: (n: number) => void;
+    const fiber = createTestResource(() => {
+      const [n, setN] = React.useState(10);
+      set = setN;
+      return n;
+    });
+
+    expect(renderTest(fiber, undefined)).toBe(10);
+    set(42);
+    await waitForNextTick();
+    expect(getCommittedOutput(fiber)).toBe(42);
+  });
+
+  it("routes React.useMemo with deps memoization", () => {
+    let runs = 0;
+    const fiber = createTestResource((p: { x: number }) =>
+      React.useMemo(() => {
+        runs++;
+        return p.x * 2;
+      }, [p.x]),
+    );
+
+    expect(renderTest(fiber, { x: 2 })).toBe(4);
+    expect(runs).toBe(1);
+    renderTest(fiber, { x: 2 }); // same dep -> memoized
+    expect(runs).toBe(1);
+    expect(renderTest(fiber, { x: 3 })).toBe(6);
+    expect(runs).toBe(2);
+  });
+
+  it("backs react/compiler-runtime's useMemoCache so compiled resources work", () => {
+    const SENTINEL = Symbol.for("react.memo_cache_sentinel");
+    const fiber = createTestResource(() => {
+      // exactly what React Compiler emits: const $ = _c(n)
+      const $ = _c(3);
+      if ($[0] === SENTINEL) $[0] = "computed-once";
+      return $[0];
+    });
+
+    expect(renderTest(fiber, undefined)).toBe("computed-once");
+    // re-render: the cache persists across renders, slot already filled
+    expect(renderTest(fiber, undefined)).toBe("computed-once");
+  });
+
+  it("throws for a hook tap does not implement", () => {
+    const fiber = createTestResource(() => React.useId());
+    // render directly: a mid-render throw must not leave a tracked, unmounted
+    // fiber for `cleanupAllResources` to choke on.
+    expect(() => renderResourceFiber(fiber, undefined)).toThrow();
+  });
+});

package/src/__tests__/rules/rules.hook-count.test.ts

@@ -1,17 +1,18 @@
+/* oxlint-disable react/rules-of-hooks -- tests deliberately exercise conditional/nested hook patterns */
 import { describe, it, expect } from "vitest";
-import { tapEffect } from "../../hooks/tap-effect";
-import { tapState } from "../../hooks/tap-state";
+import { useEffect } from "../../hooks/useEffect";
+import { useState } from "../../hooks/useState";
 import { createTestResource, renderTest } from "../test-utils";
 import { renderResourceFiber } from "../../core/ResourceFiber";
 
 describe("Rules of Hooks - Hook Count", () => {
   it("should establish hook count on first render", () => {
     const resource = createTestResource(() => {
-      const [a] = tapState(1);
-      const [b] = tapState(2);
-      const [c] = tapState(3);
-      tapEffect(() => {});
-      tapEffect(() => {});
+      const [a] = useState(1);
+      const [b] = useState(2);
+      const [c] = useState(3);
+      useEffect(() => {});
+      useEffect(() => {});
 
       return { a, b, c };
     });
@@ -29,11 +30,11 @@ describe("Rules of Hooks - Hook Count", () => {
     let addExtraHook = false;
 
     const resource = createTestResource(() => {
-      tapState(1);
-      tapState(2);
+      useState(1);
+      useState(2);
 
       if (addExtraHook) {
-        tapState(3); // Extra hook
+        useState(3); // Extra hook
       }
 
       return null;
@@ -54,13 +55,13 @@ describe("Rules of Hooks - Hook Count", () => {
     let skipHook = false;
 
     const resource = createTestResource(() => {
-      tapState(1);
+      useState(1);
 
       if (!skipHook) {
-        tapState(2);
+        useState(2);
       }
 
-      tapState(3);
+      useState(3);
       return null;
     });
 
@@ -79,11 +80,11 @@ describe("Rules of Hooks - Hook Count", () => {
     let includeEffect = true;
 
     const resource = createTestResource(() => {
-      tapState(1);
-      tapState(2);
+      useState(1);
+      useState(2);
 
       if (includeEffect) {
-        tapEffect(() => {});
+        useEffect(() => {});
       }
       return null;
     });
@@ -114,7 +115,7 @@ describe("Rules of Hooks - Hook Count", () => {
 
     const resource = createTestResource(() => {
       for (let i = 0; i < hookCount; i++) {
-        tapState(i);
+        useState(i);
       }
       return null;
     });
@@ -134,9 +135,9 @@ describe("Rules of Hooks - Hook Count", () => {
 
     const resource = createTestResource(() => {
       renderCount++;
-      const [a] = tapState(1);
-      const [b] = tapState(2);
-      tapEffect(() => {});
+      const [a] = useState(1);
+      const [b] = useState(2);
+      useEffect(() => {});
 
       return { a, b, renderCount };
     });
@@ -151,16 +152,16 @@ describe("Rules of Hooks - Hook Count", () => {
 
   it("should track count separately for different resource instances", () => {
     const resource1 = createTestResource(() => {
-      tapState(1);
-      tapState(2);
+      useState(1);
+      useState(2);
       return "two hooks";
     });
 
     const resource2 = createTestResource(() => {
-      tapState(1);
-      tapState(2);
-      tapState(3);
-      tapEffect(() => {});
+      useState(1);
+      useState(2);
+      useState(3);
+      useEffect(() => {});
       return "four hooks";
     });
 
@@ -177,14 +178,14 @@ describe("Rules of Hooks - Hook Count", () => {
     let useExtraHooks = false;
 
     const useFeature = () => {
-      tapState("feature");
+      useState("feature");
       if (useExtraHooks) {
-        tapState("extra");
+        useState("extra");
       }
     };
 
     const resource = createTestResource(() => {
-      tapState("main");
+      useState("main");
       useFeature();
       return null;
     });