@assistant-ui/tap 0.6.0 → 0.7.1

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

@@ -8,13 +8,13 @@ import {
 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 { useState as useResourceState } from "../../react-hooks/useState";
+import { useEffect as useResourceEffect } from "../../react-hooks/useEffect";
 import {
   useResource,
   useResources,
-  useResourceRoot,
-  flushResourcesSync,
+  useTapRoot,
+  flushTapSync,
 } from "../../index";
 
 describe("@assistant-ui/tap/react resource API", () => {
@@ -25,18 +25,22 @@ describe("@assistant-ui/tap/react resource API", () => {
 
   describe("useResource", () => {
     it("routes to useResource inside a tap resource", () => {
-      const Child = resource(function Child(props: { n: number }) {
+      const useChild = (props: { n: number }) => {
         return props.n * 2;
-      });
+      };
+
+      const Child = resource(useChild);
       const parent = createTestResource(() => useResource(Child({ n: 21 })));
-      expect(renderTest(parent, undefined)).toBe(42);
+      expect(renderTest(parent)).toBe(42);
     });
 
     it("routes to the React bridge inside a component", () => {
-      const CounterResource = resource(function CounterResource() {
+      const useCounterResource = () => {
         const [count, setCount] = useResourceState(0);
         return { count, setCount };
-      });
+      };
+
+      const CounterResource = resource(useCounterResource);
 
       let api: { count: number; setCount: (n: number) => void } | null = null;
       function App() {
@@ -53,23 +57,27 @@ describe("@assistant-ui/tap/react resource API", () => {
 
   describe("useResources", () => {
     it("hosts a keyed list inside a tap resource", () => {
-      const Item = resource(function Item(p: { n: number }) {
+      const useItem = (p: { n: number }) => {
         return p.n * 10;
-      });
+      };
+
+      const Item = resource(useItem);
       const parent = createTestResource(() =>
         useResources(() => [
           withKey("a", Item({ n: 1 })),
           withKey("b", Item({ n: 2 })),
         ]),
       );
-      expect(renderTest(parent, undefined)).toEqual([10, 20]);
+      expect(renderTest(parent)).toEqual([10, 20]);
     });
 
     it("hosts a keyed list inside a React component and tracks deps", () => {
-      const Item = resource(function Item(p: { n: number }) {
+      const useItem = (p: { n: number }) => {
         const [v] = useResourceState(p.n * 10);
         return v;
-      });
+      };
+
+      const Item = resource(useItem);
 
       let setCount: (n: number) => void = () => {};
       function App() {
@@ -92,16 +100,19 @@ describe("@assistant-ui/tap/react resource API", () => {
     });
   });
 
-  describe("useResourceRoot", () => {
+  describe("useTapRoot", () => {
     it("exposes a subscribable inside a tap resource", () => {
-      const Root = resource(function Root() {
+      const useRoot = () => {
         const [n] = useResourceState(7);
         return n;
-      });
+      };
+
       const parent = createTestResource(() =>
-        useResourceRoot(Root()).getValue(),
+        useTapRoot(function Root() {
+          return useRoot();
+        }).getValue(),
       );
-      expect(renderTest(parent, undefined)).toBe(7);
+      expect(renderTest(parent)).toBe(7);
     });
 
     // A root is push-based: host it in one place and observe it via getValue/
@@ -110,19 +121,21 @@ describe("@assistant-ui/tap/react resource API", () => {
     // 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 useCounterRoot = () => {
         const [count, setCount] = useResourceState(0);
         return { count, setCount };
-      });
+      };
 
       let store: ReturnType<
-        typeof useResourceRoot<{
+        typeof useTapRoot<{
           count: number;
           setCount: (n: number) => void;
         }>
       > | null = null;
       function App() {
-        store = useResourceRoot(CounterRoot());
+        store = useTapRoot(function Root() {
+          return useCounterRoot();
+        });
         return null;
       }
 
@@ -136,7 +149,7 @@ describe("@assistant-ui/tap/react resource API", () => {
 
       // The root drives updates through tap's own (macrotask) scheduler, so flush
       // synchronously to observe.
-      flushResourcesSync(() => store!.getValue().setCount(5));
+      flushTapSync(() => store!.getValue().setCount(5));
       expect(store!.getValue().count).toBe(5);
       expect(notified).toBeGreaterThan(0);
 
@@ -147,11 +160,13 @@ describe("@assistant-ui/tap/react resource API", () => {
   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 }) {
+      const useKeyed = (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;
-      });
+      };
+
+      const Keyed = resource(useKeyed);
 
       let setId: (n: number) => void = () => {};
       function App() {

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

@@ -0,0 +1,233 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, act, cleanup } from "@testing-library/react";
+import { StrictMode, useEffect, useLayoutEffect } from "react";
+import { useState as useTapState } from "../../react-hooks/useState";
+import { useEffect as useTapEffect } from "../../react-hooks/useEffect";
+import { useTapHost } from "../../index";
+
+const countOf = (log: string[], entry: string) =>
+  log.filter((e) => e === entry).length;
+
+describe("useTapHost", () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("returns the resource value and re-renders on dispatch", () => {
+    let api!: { count: number; setCount: (n: number) => void };
+    function App() {
+      const { value } = useTapHost(function TapHost() {
+        const [count, setCount] = useTapState(0);
+        return { count, setCount };
+      });
+      api = value;
+      return <div data-testid="count">{value.count}</div>;
+    }
+
+    render(<App />);
+    expect(screen.getByTestId("count").textContent).toBe("0");
+    act(() => api.setCount(3));
+    expect(screen.getByTestId("count").textContent).toBe("3");
+  });
+
+  it("commits in the passive phase, before the effects of a consumer that mounts effects", () => {
+    const log: string[] = [];
+    function Child({ effects }: { effects: () => void }) {
+      useEffect(effects);
+      useLayoutEffect(() => {
+        log.push("child layout");
+      }, []);
+      useEffect(() => {
+        log.push("child effect");
+      }, []);
+      return null;
+    }
+    function App() {
+      const { effects } = useTapHost(function TapHost() {
+        useTapEffect(() => {
+          log.push("tap effect");
+        });
+        return null;
+      });
+      useEffect(() => {
+        log.push("host effect");
+      }, []);
+      return <Child effects={effects} />;
+    }
+
+    render(<App />);
+    // "child layout" first proves the commit is passive (does not block
+    // paint); "tap effect" before "child effect" proves the consumer's
+    // instance won the commit over the host's own fallback instance.
+    expect(log).toEqual([
+      "child layout",
+      "tap effect",
+      "child effect",
+      "host effect",
+    ]);
+  });
+
+  it("falls back to the host's own instance when no consumer mounts effects", () => {
+    const log: string[] = [];
+    function Child() {
+      useEffect(() => {
+        log.push("child effect");
+      }, []);
+      return null;
+    }
+    function App() {
+      useTapHost(function TapHost() {
+        useTapEffect(() => {
+          log.push("tap effect");
+        });
+        return null;
+      });
+      return <Child />;
+    }
+
+    render(<App />);
+    expect(log).toEqual(["child effect", "tap effect"]);
+  });
+
+  it("commits exactly once per pass with multiple consumers", () => {
+    const log: string[] = [];
+    let api!: { bump: () => void };
+    function Child({ effects }: { effects: () => void }) {
+      useEffect(effects);
+      return null;
+    }
+    function App() {
+      const { value, effects } = useTapHost(function TapHost() {
+        const [count, setCount] = useTapState(0);
+        useTapEffect(() => {
+          log.push("tap effect");
+        });
+        return { count, bump: () => setCount(count + 1) };
+      });
+      api = value;
+      return (
+        <>
+          <Child effects={effects} />
+          <Child effects={effects} />
+        </>
+      );
+    }
+
+    render(<App />);
+    expect(countOf(log, "tap effect")).toBe(1);
+
+    act(() => api.bump());
+    expect(countOf(log, "tap effect")).toBe(2);
+  });
+
+  it("hands responsibility to the next instance when the winner unmounts", () => {
+    const log: string[] = [];
+    let api!: { count: number; bump: () => void };
+    function Child({ name, effects }: { name: string; effects: () => void }) {
+      useEffect(effects);
+      useEffect(() => {
+        log.push(`${name} effect`);
+      });
+      return null;
+    }
+    function App({ showA }: { showA: boolean }) {
+      const { value, effects } = useTapHost(function TapHost() {
+        const [count, setCount] = useTapState(0);
+        useTapEffect(() => {
+          log.push(`tap effect ${count}`);
+          return () => {
+            log.push("tap cleanup");
+          };
+        });
+        return { count, bump: () => setCount(count + 1) };
+      });
+      api = value;
+      return (
+        <>
+          {showA && <Child name="a" effects={effects} />}
+          <Child name="b" effects={effects} />
+        </>
+      );
+    }
+
+    const { rerender } = render(<App showA={true} />);
+    expect(log).toEqual(["tap effect 0", "a effect", "b effect"]);
+
+    log.length = 0;
+    rerender(<App showA={false} />);
+    // The winner's unmount removes only its instance, not the resource: the
+    // no-deps tap effect re-fires as a cleanup/setup pair, not a final
+    // cleanup, and the commit still lands before b's own effect.
+    expect(log).toEqual(["tap cleanup", "tap effect 0", "b effect"]);
+
+    log.length = 0;
+    act(() => api.bump());
+    expect(api.count).toBe(1);
+    // Next in line (b) now commits, still ahead of its own effects.
+    expect(log).toEqual(["tap cleanup", "tap effect 1", "b effect"]);
+  });
+
+  it("unmounting the host cleans up exactly once", () => {
+    // effects consumers must be descendants of the host component, so
+    // they unmount with it and no flush can fire after the deletion.
+    const log: string[] = [];
+    function Child({ effects }: { effects: () => void }) {
+      useEffect(effects);
+      return null;
+    }
+    function HostComp() {
+      const { effects } = useTapHost(function TapHost() {
+        useTapEffect(() => {
+          log.push("tap effect");
+          return () => {
+            log.push("tap cleanup");
+          };
+        }, []);
+        return null;
+      });
+      return <Child effects={effects} />;
+    }
+    function App({ showHost }: { showHost: boolean }) {
+      return showHost ? <HostComp /> : null;
+    }
+
+    const { rerender } = render(<App showHost={true} />);
+    expect(log).toEqual(["tap effect"]);
+
+    rerender(<App showHost={false} />);
+    expect(log).toEqual(["tap effect", "tap cleanup"]);
+  });
+
+  it("remounts through a StrictMode effect cycle", () => {
+    const log: string[] = [];
+    let api!: { count: number; setCount: (n: number) => void };
+    function App() {
+      const { value } = useTapHost(function TapHost() {
+        const [count, setCount] = useTapState(0);
+        useTapEffect(() => {
+          log.push("tap mount");
+          return () => {
+            log.push("tap unmount");
+          };
+        }, []);
+        return { count, setCount };
+      });
+      api = value;
+      return <div data-testid="count">{value.count}</div>;
+    }
+
+    render(
+      <StrictMode>
+        <App />
+      </StrictMode>,
+    );
+    // setup, simulated unmount, setup: same as inlined hooks in StrictMode.
+    expect(countOf(log, "tap mount")).toBe(2);
+    expect(countOf(log, "tap unmount")).toBe(1);
+
+    act(() => api.setCount(5));
+    expect(screen.getByTestId("count").textContent).toBe("5");
+    expect(countOf(log, "tap mount")).toBe(2);
+    expect(countOf(log, "tap unmount")).toBe(1);
+  });
+});

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

@@ -28,7 +28,7 @@ describe("react dispatcher", () => {
       return n;
     });
 
-    expect(renderTest(fiber, undefined)).toBe(10);
+    expect(renderTest(fiber)).toBe(10);
     set(42);
     await waitForNextTick();
     expect(getCommittedOutput(fiber)).toBe(42);
@@ -60,15 +60,15 @@ describe("react dispatcher", () => {
       return $[0];
     });
 
-    expect(renderTest(fiber, undefined)).toBe("computed-once");
+    expect(renderTest(fiber)).toBe("computed-once");
     // re-render: the cache persists across renders, slot already filled
-    expect(renderTest(fiber, undefined)).toBe("computed-once");
+    expect(renderTest(fiber)).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();
+    expect(() => renderResourceFiber(fiber, [])).toThrow();
   });
 });

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

@@ -1,7 +1,7 @@
 /* oxlint-disable react/rules-of-hooks -- tests deliberately exercise conditional/nested hook patterns */
 import { describe, it, expect } from "vitest";
-import { useEffect } from "../../hooks/useEffect";
-import { useState } from "../../hooks/useState";
+import { useEffect } from "../../react-hooks/useEffect";
+import { useState } from "../../react-hooks/useState";
 import { createTestResource, renderTest } from "../test-utils";
 import { renderResourceFiber } from "../../core/ResourceFiber";
 
@@ -18,11 +18,11 @@ describe("Rules of Hooks - Hook Count", () => {
     });
 
     // First render establishes 5 hooks
-    renderTest(resource, undefined);
+    renderTest(resource);
 
     // Second render should work with same count
     expect(() => {
-      renderTest(resource, undefined);
+      renderTest(resource);
     }).not.toThrow();
   });
 
@@ -41,12 +41,12 @@ describe("Rules of Hooks - Hook Count", () => {
     });
 
     // First render with 2 hooks
-    renderResourceFiber(resource, undefined);
+    renderResourceFiber(resource, []);
 
     // Try to render with 3 hooks
     addExtraHook = true;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered more hooks than during the previous render",
     );
   });
@@ -66,12 +66,12 @@ describe("Rules of Hooks - Hook Count", () => {
     });
 
     // First render with 3 hooks
-    renderResourceFiber(resource, undefined);
+    renderResourceFiber(resource, []);
 
     // Try to render with 2 hooks
     skipHook = true;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered 2 hooks but expected 3",
     );
   });
@@ -89,11 +89,11 @@ describe("Rules of Hooks - Hook Count", () => {
       return null;
     });
 
-    renderResourceFiber(resource, undefined);
+    renderResourceFiber(resource, []);
 
     includeEffect = false;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered 2 hooks but expected 3",
     );
   });
@@ -104,10 +104,10 @@ describe("Rules of Hooks - Hook Count", () => {
       return "no hooks";
     });
 
-    renderTest(resource, undefined);
+    renderTest(resource);
 
     // Should allow multiple renders with zero hooks
-    expect(() => renderTest(resource, undefined)).not.toThrow();
+    expect(() => renderTest(resource)).not.toThrow();
   });
 
   it("should detect dynamic hook creation", () => {
@@ -120,12 +120,12 @@ describe("Rules of Hooks - Hook Count", () => {
       return null;
     });
 
-    renderResourceFiber(resource, undefined);
+    renderResourceFiber(resource, []);
 
     // Change hook count
     hookCount = 3;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered more hooks than during the previous render",
     );
   });
@@ -144,7 +144,7 @@ describe("Rules of Hooks - Hook Count", () => {
 
     // Multiple renders should all maintain same hook count
     for (let i = 0; i < 5; i++) {
-      expect(() => renderTest(resource, undefined)).not.toThrow();
+      expect(() => renderTest(resource)).not.toThrow();
     }
 
     expect(renderCount).toBe(5);
@@ -166,12 +166,12 @@ describe("Rules of Hooks - Hook Count", () => {
     });
 
     // Render both
-    renderTest(resource1, undefined);
-    renderTest(resource2, undefined);
+    renderTest(resource1);
+    renderTest(resource2);
 
     // Each should maintain its own count
-    expect(() => renderTest(resource1, undefined)).not.toThrow();
-    expect(() => renderTest(resource2, undefined)).not.toThrow();
+    expect(() => renderTest(resource1)).not.toThrow();
+    expect(() => renderTest(resource2)).not.toThrow();
   });
 
   it("should detect hook count changes in nested function calls", () => {
@@ -190,11 +190,11 @@ describe("Rules of Hooks - Hook Count", () => {
       return null;
     });
 
-    renderResourceFiber(resource, undefined);
+    renderResourceFiber(resource, []);
 
     useExtraHooks = true;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered more hooks than during the previous render",
     );
   });

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

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
-import { useEffect } from "../../hooks/useEffect";
-import { useState } from "../../hooks/useState";
+import { useEffect } from "../../react-hooks/useEffect";
+import { useState } from "../../react-hooks/useState";
 import { createTestResource, renderTest } from "../test-utils";
 import {
   renderResourceFiber,
@@ -23,13 +23,13 @@ describe("Rules of Hooks - Hook Order", () => {
     });
 
     // First render establishes order
-    renderTest(resource, undefined);
+    renderTest(resource);
 
     // Change condition
     condition = false;
 
     // Second render with different order should throw
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Hook order changed between renders",
     );
   });
@@ -46,12 +46,12 @@ describe("Rules of Hooks - Hook Order", () => {
       return null;
     });
 
-    renderTest(resource, undefined);
+    renderTest(resource);
 
     // Change to use different hook type
     addEffect = true;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Hook order changed between renders",
     );
   });
@@ -70,13 +70,13 @@ describe("Rules of Hooks - Hook Order", () => {
       return null;
     });
 
-    renderTest(resource, undefined);
+    renderTest(resource);
 
     // Change condition
     condition = false;
 
     // Should throw because hook count changed
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered 2 hooks but expected 3",
     );
   });
@@ -93,11 +93,11 @@ describe("Rules of Hooks - Hook Order", () => {
       return states;
     });
 
-    const result = renderTest(resource, undefined);
+    const result = renderTest(resource);
     expect(result).toEqual([1, 2, 3]);
 
     // Re-render should work fine
-    expect(() => renderResourceFiber(resource, undefined)).not.toThrow();
+    expect(() => renderResourceFiber(resource, [])).not.toThrow();
   });
 
   it("should throw when hooks in loops have inconsistent count", () => {
@@ -110,12 +110,12 @@ describe("Rules of Hooks - Hook Order", () => {
       return null;
     });
 
-    renderTest(resource, undefined);
+    renderTest(resource);
 
     // Change array length
     items = [1, 2];
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered 2 hooks but expected 3",
     );
   });
@@ -131,11 +131,11 @@ describe("Rules of Hooks - Hook Order", () => {
       return { a, b, c };
     });
 
-    const result = renderTest(resource, undefined);
+    const result = renderTest(resource);
     expect(result).toEqual({ a: 1, b: 2, c: 3 });
 
     // Re-render should maintain same order
-    const ctx = renderResourceFiber(resource, undefined);
+    const ctx = renderResourceFiber(resource, []);
     expect(() => commitResourceFiber(resource, ctx)).not.toThrow();
   });
 
@@ -153,13 +153,13 @@ describe("Rules of Hooks - Hook Order", () => {
       return a + b;
     });
 
-    const result1 = renderTest(resource, undefined);
+    const result1 = renderTest(resource);
     expect(result1).toBe(3);
 
     // Enable early return
     shouldReturn = true;
 
-    expect(() => renderResourceFiber(resource, undefined)).toThrow(
+    expect(() => renderResourceFiber(resource, [])).toThrow(
       "Rendered 1 hooks but expected 2",
     );
   });
@@ -187,6 +187,6 @@ describe("Rules of Hooks - Hook Order", () => {
       return count;
     });
 
-    renderTest(resource, undefined);
+    renderTest(resource);
   });
 });