@assistant-ui/tap 0.5.14 → 0.6.0

package/src/core/context.ts

@@ -1,28 +1,50 @@
+import type { Context as ReactContext } from "react";
+
 const contextValue: unique symbol = Symbol("tap.Context");
-type Context<T> = {
+type TapContext<T> = {
   [contextValue]: T;
 };
 
-export const createResourceContext = <T>(defaultValue: T): Context<T> => {
+const asTap = <T>(context: ReactContext<T>): TapContext<T> =>
+  context as unknown as TapContext<T>;
+
+// A tap resource context is typed as a React `Context<T>` purely so React's
+// `use(context)` accepts it (the type is erased, so this adds no runtime react
+// dependency). At runtime it is only a branded `{ [contextValue]: T }` and is
+// not a usable React context — `use()` routes it to `useResourceContext()` via the brand.
+/**
+ * @deprecated experimental — the resource context API is not yet stable and may
+ * change or be removed in a future release.
+ */
+export const createResourceContext = <T>(defaultValue: T): ReactContext<T> => {
   return {
     [contextValue]: defaultValue,
-  };
+  } as unknown as ReactContext<T>;
+};
+
+export const isResourceContext = (value: unknown): boolean => {
+  return typeof value === "object" && value !== null && contextValue in value;
 };
 
+/**
+ * @deprecated experimental — the resource context API is not yet stable and may
+ * change or be removed in a future release.
+ */
 export const withContextProvider = <T, TResult>(
-  context: Context<T>,
+  context: ReactContext<T>,
   value: T,
   fn: () => TResult,
 ) => {
-  const previousValue = context[contextValue];
-  context[contextValue] = value;
+  const tapContext = asTap(context);
+  const previousValue = tapContext[contextValue];
+  tapContext[contextValue] = value;
   try {
     return fn();
   } finally {
-    context[contextValue] = previousValue;
+    tapContext[contextValue] = previousValue;
   }
 };
 
-export const tap = <T>(context: Context<T>) => {
-  return context[contextValue];
+export const useResourceContext = <T>(context: ReactContext<T>) => {
+  return asTap(context)[contextValue];
 };

package/src/core/createResourceRoot.ts

@@ -5,17 +5,17 @@ import {
   renderResourceFiber,
   commitResourceFiber,
 } from "./ResourceFiber";
-import { tapResourceRoot } from "../tapResourceRoot";
+import { useResourceRoot } from "../hooks/useResourceRoot";
 import { resource } from "./resource";
 import { isDevelopment } from "./helpers/env";
 import { flushResourcesSync, UpdateScheduler } from "./scheduler";
 import { createResourceFiberRoot } from "./helpers/root";
 
-const SubscribableResource = resource(tapResourceRoot);
+const SubscribableResource = resource(useResourceRoot);
 
 export const createResourceRoot = () => {
   const fiber = createResourceFiber<
-    tapResourceRoot.SubscribableResource<any>,
+    useResourceRoot.SubscribableResource<any>,
     ResourceElement<any>
   >(
     SubscribableResource,
@@ -44,7 +44,7 @@ export const createResourceRoot = () => {
 
       flushResourcesSync(() => commitResourceFiber(fiber, render));
 
-      return render.output;
+      return render.output as useResourceRoot.SubscribableResource<R>;
     },
     unmount: () => {
       unmountResourceFiber(fiber);

package/src/core/helpers/execution-context.ts

@@ -34,6 +34,10 @@ export function getCurrentResourceFiber(): ResourceFiber<unknown, unknown> {
   return currentResourceFiber;
 }
 
+export function peekResourceFiber(): ResourceFiber<unknown, unknown> | null {
+  return currentResourceFiber;
+}
+
 export function getDevStrictMode(enable: boolean) {
   if (!isDevelopment) return null;
   if (currentResourceFiber?.devStrictMode)

package/src/core/react-dispatcher.ts

@@ -0,0 +1,78 @@
+import * as React from "react";
+import { useState } from "../hooks/useState";
+import { useReducer } from "../hooks/useReducer";
+import { useRef } from "../hooks/useRef";
+import { useMemo } from "../hooks/useMemo";
+import { useCallback } from "../hooks/useCallback";
+import { useEffect } from "../hooks/useEffect";
+import { useEffectEvent } from "../hooks/useEffectEvent";
+import { use } from "../hooks/use";
+import { useMemoCache } from "../hooks/useMemoCache";
+
+// The dispatcher React reads while a resource renders, so hooks imported from
+// "react" route to tap with no build step. Hooks tap has no equivalent for are
+// intentionally absent: calling one throws, which is the intended "unsupported
+// in a resource" signal.
+const tapDispatcher = {
+  useState,
+  useReducer,
+  useRef,
+  useMemo,
+  useCallback,
+  useEffect,
+  useLayoutEffect: useEffect,
+  useInsertionEffect: useEffect,
+  useEffectEvent,
+  useContext: use,
+  use,
+  useMemoCache,
+};
+
+// React's live dispatcher slot differs by version: React 19 exposes it as `H` on
+// the client internals object; React 18 as `ReactCurrentDispatcher.current`.
+const internals =
+  (React as any)
+    .__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ??
+  (React as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
+
+const slot: { current: unknown } | null =
+  internals == null
+    ? null
+    : "H" in internals
+      ? {
+          get current() {
+            return internals.H;
+          },
+          set current(d) {
+            internals.H = d;
+          },
+        }
+      : "ReactCurrentDispatcher" in internals
+        ? {
+            get current() {
+              return internals.ReactCurrentDispatcher.current;
+            },
+            set current(d) {
+              internals.ReactCurrentDispatcher.current = d;
+            },
+          }
+        : null;
+
+/**
+ * Runs a resource body with tap's React dispatcher installed, so real React
+ * hooks called inside it (`import { useState } from "react"`) route to tap, then
+ * restores the previous dispatcher. If React's internal dispatcher slot can't be
+ * found (an unsupported React version), the body runs unchanged and `react`
+ * hooks inside it keep throwing React's "invalid hook call".
+ */
+export function withReactDispatcher<T>(render: () => T): T {
+  if (!slot) return render();
+
+  const previous = slot.current;
+  slot.current = tapDispatcher;
+  try {
+    return render();
+  } finally {
+    slot.current = previous;
+  }
+}

package/src/core/scheduler.ts

@@ -53,7 +53,7 @@ const flushScheduled = () => {
       if (flushDepth > MAX_FLUSH_LIMIT) {
         throw new Error(
           `Maximum update depth exceeded. This can happen when a resource ` +
-            `repeatedly calls setState inside tapEffect.`,
+            `repeatedly calls setState inside useEffect.`,
         );
       }
 

package/src/core/types.ts

@@ -1,4 +1,4 @@
-import type { tapEffect } from "../hooks/tap-effect";
+import type { useEffect } from "../hooks/useEffect";
 
 export type ResourceElement<R, P = any> = {
   readonly type: Resource<R, P>;
@@ -35,12 +35,12 @@ export type Cell =
     }
   | {
       readonly type: "effect";
-      cleanup: tapEffect.Destructor | undefined;
+      cleanup: useEffect.Destructor | undefined;
       deps: readonly unknown[] | null | undefined;
     };
 
 export interface EffectTask {
-  readonly effect: tapEffect.EffectCallback;
+  readonly effect: useEffect.EffectCallback;
   readonly deps: readonly unknown[] | undefined;
   readonly cell: Cell & { type: "effect" };
 }

package/src/hooks/index.ts

@@ -0,0 +1,12 @@
+export { useState } from "./useState";
+export { useReducer, useReducerWithDerivedState } from "./useReducer";
+export { useRef } from "./useRef";
+export { useMemo } from "./useMemo";
+export { useCallback } from "./useCallback";
+export { useEffect } from "./useEffect";
+export { useEffectEvent } from "./useEffectEvent";
+export { use } from "./use";
+export { useMemoCache } from "./useMemoCache";
+export { useResource } from "./useResource";
+export { useResources } from "./useResources";
+export { useResourceRoot } from "./useResourceRoot";

package/src/hooks/use.ts

@@ -0,0 +1,13 @@
+import { isResourceContext, useResourceContext } from "../core/context";
+
+/**
+ * Reads a resource context from inside a resource render, the tap equivalent of
+ * React's `use(Context)`. Only resource contexts are supported.
+ */
+export const use = (usable: unknown): unknown => {
+  if (!isResourceContext(usable))
+    throw new Error(
+      "A tap resource's `use()` only accepts a resource context.",
+    );
+  return useResourceContext(usable as never);
+};

package/src/hooks/useCallback.ts

@@ -0,0 +1,9 @@
+import { useMemo } from "./useMemo";
+
+export const useCallback = <T extends (...args: any[]) => any>(
+  fn: T,
+  deps: readonly unknown[],
+): T => {
+  // oxlint-disable-next-line react/exhaustive-deps -- user-provided dep array forwarded verbatim
+  return useMemo(() => fn, deps);
+};

package/src/hooks/{tap-effect.ts → useEffect.ts}

@@ -1,6 +1,6 @@
 import type { Cell } from "../core/types";
 import { depsShallowEqual } from "./utils/depsShallowEqual";
-import { tapHook, registerRenderMountTask } from "./utils/tapHook";
+import { useCell, registerRenderMountTask } from "./utils/useCell";
 
 const newEffect = (): Cell & { type: "effect" } => ({
   type: "effect",
@@ -8,26 +8,26 @@ const newEffect = (): Cell & { type: "effect" } => ({
   deps: null, // null means the effect has never been run
 });
 
-export namespace tapEffect {
+export namespace useEffect {
   export type Destructor = () => void;
   export type EffectCallback = () => Destructor | undefined;
 }
 
-export function tapEffect(effect: tapEffect.EffectCallback): void;
-export function tapEffect(
-  effect: tapEffect.EffectCallback,
+export function useEffect(effect: useEffect.EffectCallback): void;
+export function useEffect(
+  effect: useEffect.EffectCallback,
   deps: readonly unknown[],
 ): void;
-export function tapEffect(
-  effect: tapEffect.EffectCallback,
+export function useEffect(
+  effect: useEffect.EffectCallback,
   deps?: readonly unknown[],
 ): void {
-  const cell = tapHook("effect", newEffect);
+  const cell = useCell("effect", newEffect);
 
   if (deps && cell.deps && depsShallowEqual(cell.deps, deps)) return;
   if (cell.deps !== null && !!deps !== !!cell.deps)
     throw new Error(
-      "tapEffect called with and without dependencies across re-renders",
+      "useEffect called with and without dependencies across re-renders",
     );
 
   registerRenderMountTask(() => {

package/src/hooks/{tap-effect-event.ts → useEffectEvent.ts}

@@ -1,7 +1,7 @@
-import { tapRef } from "./tap-ref";
-import { tapEffect } from "./tap-effect";
+import { useRef } from "./useRef";
+import { useEffect } from "./useEffect";
 import { isDevelopment } from "../core/helpers/env";
-import { tapCallback } from "./tap-callback";
+import { useCallback } from "./useCallback";
 import { getCurrentResourceFiber } from "../core/helpers/execution-context";
 
 /**
@@ -13,27 +13,27 @@ import { getCurrentResourceFiber } from "../core/helpers/execution-context";
  *
  * @example
  * ```typescript
- * const handleClick = tapEffectEvent((value: string) => {
+ * const handleClick = useEffectEvent((value: string) => {
  *   console.log(value);
  * });
  * // handleClick reference is stable, but always calls the latest version
  * ```
  */
-export function tapEffectEvent<T extends (...args: any[]) => any>(
+export function useEffectEvent<T extends (...args: any[]) => any>(
   callback: T,
 ): T {
-  const callbackRef = tapRef(callback);
+  const callbackRef = useRef(callback);
 
   // TODO this effect needs to run before all userland effects
-  tapEffect(() => {
+  useEffect(() => {
     callbackRef.current = callback;
   });
 
   const fiber = getCurrentResourceFiber();
-  return tapCallback(
+  return useCallback(
     ((...args: Parameters<T>) => {
       if (isDevelopment && fiber.renderContext)
-        throw new Error("tapEffectEvent cannot be called during render");
+        throw new Error("useEffectEvent cannot be called during render");
       return callbackRef.current(...args);
     }) as T,
     [fiber],

package/src/hooks/{tap-memo.ts → useMemo.ts}

@@ -1,6 +1,6 @@
 import { isDevelopment } from "../core/helpers/env";
 import { getCurrentResourceFiber } from "../core/helpers/execution-context";
-import { tapReducerWithDerivedState } from "./tap-reducer";
+import { useReducerWithDerivedState } from "./useReducer";
 import { depsShallowEqual } from "./utils/depsShallowEqual";
 
 const memoReducer = () => {
@@ -9,9 +9,9 @@ const memoReducer = () => {
 
 type MemoState<T> = { value: T; deps: readonly unknown[] };
 
-export const tapMemo = <T>(fn: () => T, deps: readonly unknown[]): T => {
+export const useMemo = <T>(fn: () => T, deps: readonly unknown[]): T => {
   const fiber = getCurrentResourceFiber();
-  const [state] = tapReducerWithDerivedState(
+  const [state] = useReducerWithDerivedState(
     memoReducer,
     (state: MemoState<T> | null): MemoState<T> => {
       if (state && depsShallowEqual(state.deps, deps)) return state;

package/src/hooks/useMemoCache.ts

@@ -0,0 +1,25 @@
+import { useReducerWithDerivedState } from "./useReducer";
+
+const MEMO_CACHE_SENTINEL = Symbol.for("react.memo_cache_sentinel");
+
+/**
+ * Backs React Compiler's memo cache. Compiled output allocates it through
+ * `react/compiler-runtime`'s `c(size)` (`ReactSharedInternals.H.useMemoCache(size)`);
+ * a tap ref persists the array so compiled resources run without `"use no memo"`.
+ */
+export const useMemoCache = (size: number): unknown[] => {
+  // clone the memo value once per render
+  let cloned = false;
+  const [cache] = useReducerWithDerivedState(
+    () => [] as unknown[],
+    (arr) => {
+      if (cloned) return arr;
+      cloned = true;
+      return [...arr];
+    },
+    size,
+    (length) => Array.from({ length }).fill(MEMO_CACHE_SENTINEL),
+  );
+
+  return cache;
+};

package/src/hooks/{tap-reducer.ts → useReducer.ts}

@@ -2,7 +2,7 @@ import { isDevelopment } from "../core/helpers/env";
 import { getCurrentResourceFiber } from "../core/helpers/execution-context";
 import type { ReducerQueueEntry, ResourceFiber } from "../core/types";
 import { markCellDirty } from "../core/helpers/root";
-import { tapHook } from "./utils/tapHook";
+import { useCell } from "./utils/useCell";
 
 type Dispatch<A> = (action: A) => void;
 
@@ -28,13 +28,13 @@ const dispatchOnFiber = (
   });
 };
 
-function tapReducerImpl<S, A, I, R extends S>(
+function useReducerImpl<S, A, I, R extends S>(
   reducer: (state: S, action: A) => S,
   getDerivedState: ((state: S) => R) | undefined,
   initialArg: S | I,
   initFn: ((arg: I) => S) | undefined,
 ): [R, Dispatch<A>] {
-  const cell = tapHook("reducer", () => {
+  const cell = useCell("reducer", () => {
     const fiber = getCurrentResourceFiber();
 
     // First render: compute initial state
@@ -105,21 +105,21 @@ function tapReducerImpl<S, A, I, R extends S>(
   return [cell.workInProgress, cell.dispatch];
 }
 
-export function tapReducer<S, A>(
+export function useReducer<S, A>(
   reducer: (state: S, action: A) => S,
   initialState: S,
 ): [S, Dispatch<A>];
-export function tapReducer<S, A, I>(
+export function useReducer<S, A, I>(
   reducer: (state: S, action: A) => S,
   initialArg: I,
   init: (arg: I) => S,
 ): [S, Dispatch<A>];
-export function tapReducer<S, A, I>(
+export function useReducer<S, A, I>(
   reducer: (state: S, action: A) => S,
   initialArg: S | I,
   init?: (arg: I) => S,
 ): [S, Dispatch<A>] {
-  return tapReducerImpl(
+  return useReducerImpl(
     reducer,
     undefined,
     initialArg as S,
@@ -127,22 +127,34 @@ export function tapReducer<S, A, I>(
   );
 }
 
-export function tapReducerWithDerivedState<S, A, R extends S>(
+/**
+ * @deprecated experimental — a `getDerivedStateFromProps` replacement for
+ * resources: adjust state in response to props without setting during render.
+ * Tap-only for now (call it inside a resource render, not a React component) and
+ * may change before stabilizing.
+ */
+export function useReducerWithDerivedState<S, A, R extends S>(
   reducer: (state: S, action: A) => S,
   getDerivedState: (state: S) => R,
   initialState: S,
 ): [R, Dispatch<A>];
-export function tapReducerWithDerivedState<S, A, I, R extends S>(
+/**
+ * @deprecated experimental — a `getDerivedStateFromProps` replacement for
+ * resources: adjust state in response to props without setting during render.
+ * Tap-only for now (call it inside a resource render, not a React component) and
+ * may change before stabilizing.
+ */
+export function useReducerWithDerivedState<S, A, I, R extends S>(
   reducer: (state: S, action: A) => S,
   getDerivedState: (state: S) => R,
   initialArg: I,
   init: (arg: I) => S,
 ): [R, Dispatch<A>];
-export function tapReducerWithDerivedState<S, A, I, R extends S>(
+export function useReducerWithDerivedState<S, A, I, R extends S>(
   reducer: (state: S, action: A) => S,
   getDerivedState: (state: S) => R,
   initialArg: I,
   init?: (arg: I) => S,
 ): [R, Dispatch<A>] {
-  return tapReducerImpl(reducer, getDerivedState, initialArg, init);
+  return useReducerImpl(reducer, getDerivedState, initialArg, init);
 }

package/src/hooks/useRef.ts

@@ -0,0 +1,16 @@
+import { useState } from "./useState";
+
+export namespace useRef {
+  export interface RefObject<T> {
+    current: T;
+  }
+}
+
+export function useRef<T>(initialValue: T): useRef.RefObject<T>;
+export function useRef<T = undefined>(): useRef.RefObject<T | undefined>;
+export function useRef<T>(initialValue?: T): useRef.RefObject<T | undefined> {
+  const [state] = useState(() => ({
+    current: initialValue,
+  }));
+  return state;
+}

package/src/hooks/{tap-resource.ts → useResource.ts}

@@ -1,29 +1,29 @@
 import type { ExtractResourceReturnType, ResourceElement } from "../core/types";
-import { tapEffect } from "./tap-effect";
+import { useEffect } from "./useEffect";
 import {
   createResourceFiber,
   unmountResourceFiber,
   renderResourceFiber,
   commitResourceFiber,
 } from "../core/ResourceFiber";
-import { tapMemo } from "./tap-memo";
-import { tapRef } from "./tap-ref";
+import { useMemo } from "./useMemo";
+import { useRef } from "./useRef";
 import { getCurrentResourceFiber } from "../core/helpers/execution-context";
 
-export function tapResource<E extends ResourceElement<any, any>>(
+export function useResource<E extends ResourceElement<any, any>>(
   element: E,
 ): ExtractResourceReturnType<E>;
-export function tapResource<E extends ResourceElement<any, any>>(
+export function useResource<E extends ResourceElement<any, any>>(
   element: E,
   propsDeps: readonly unknown[],
 ): ExtractResourceReturnType<E>;
-export function tapResource<E extends ResourceElement<any, any>>(
+export function useResource<E extends ResourceElement<any, any>>(
   element: E,
   propsDeps?: readonly unknown[],
 ): ExtractResourceReturnType<E> {
   const parentFiber = getCurrentResourceFiber();
-  const versionRef = tapRef(0);
-  const fiber = tapMemo(() => {
+  const versionRef = useRef(0);
+  const fiber = useMemo(() => {
     void element.key;
     return createResourceFiber(element.type, parentFiber.root, () => {
       versionRef.current++;
@@ -32,15 +32,16 @@ export function tapResource<E extends ResourceElement<any, any>>(
   }, [element.type, element.key, parentFiber]);
 
   const result = propsDeps
-    ? tapMemo(
+    ? // oxlint-disable-next-line react/rules-of-hooks -- propsDeps presence is fixed per call site, so the conditional call order is stable
+      useMemo(
         () => renderResourceFiber(fiber, element.props),
-        // oxlint-disable-next-line tap-hooks/exhaustive-deps -- props identity replaced by user-provided deps
+        // oxlint-disable-next-line react/exhaustive-deps -- props identity replaced by user-provided deps
         [fiber, ...propsDeps, versionRef.current],
       )
     : renderResourceFiber(fiber, element.props);
 
-  tapEffect(() => () => unmountResourceFiber(fiber), [fiber]);
-  tapEffect(() => {
+  useEffect(() => () => unmountResourceFiber(fiber), [fiber]);
+  useEffect(() => {
     commitResourceFiber(fiber, result);
   }, [fiber, result]);