@assistant-ui/tap 0.6.0 → 0.7.1

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

@@ -1,10 +1,9 @@
-import { isDevelopment } from "./env";
 import type { ResourceFiber } from "../types";
 
 let currentResourceFiber: ResourceFiber<any, any> | null = null;
 
-export function withResourceFiber<R, P>(
-  fiber: ResourceFiber<R, P>,
+export function withResourceFiber<R, A extends readonly unknown[]>(
+  fiber: ResourceFiber<R, A>,
   fn: () => void,
 ): void {
   fiber.currentIndex = 0;
@@ -27,21 +26,13 @@ export function withResourceFiber<R, P>(
     currentResourceFiber = previousContext;
   }
 }
-export function getCurrentResourceFiber(): ResourceFiber<unknown, unknown> {
+export function getCurrentResourceFiber(): ResourceFiber<unknown> {
   if (!currentResourceFiber) {
     throw new Error("No resource fiber available");
   }
   return currentResourceFiber;
 }
 
-export function peekResourceFiber(): ResourceFiber<unknown, unknown> | null {
+export function peekResourceFiber(): ResourceFiber<unknown> | null {
   return currentResourceFiber;
 }
-
-export function getDevStrictMode(enable: boolean) {
-  if (!isDevelopment) return null;
-  if (currentResourceFiber?.devStrictMode)
-    return currentResourceFiber.isFirstRender ? "child" : "root";
-
-  return enable ? "root" : null;
-}

package/src/core/helpers/root.ts

@@ -1,4 +1,9 @@
-import type { Cell, ResourceFiber, ResourceFiberRoot } from "../types";
+import type {
+  Cell,
+  ChangelogRecord,
+  ResourceFiber,
+  ResourceFiberRoot,
+} from "../types";
 
 export const createResourceFiberRoot = (
   dispatchUpdate: (cb: () => boolean) => void,
@@ -8,19 +13,17 @@ export const createResourceFiberRoot = (
     committedVersion: 0,
     dispatchUpdate,
     changelog: [],
-    dirtyCells: [],
+    dirtyCells: new Set(),
   };
 };
 
 export const commitRoot = (root: ResourceFiberRoot): void => {
   for (const cell of root.dirtyCells) {
-    cell.dirty = false;
-    cell.queue.clear();
     cell.current = cell.workInProgress;
   }
   root.committedVersion = root.version;
   root.changelog.length = 0;
-  root.dirtyCells.length = 0;
+  root.dirtyCells.clear();
 };
 
 export const setRootVersion = (
@@ -31,11 +34,13 @@ export const setRootVersion = (
   root.version = version;
   if (rollback) {
     for (const cell of root.dirtyCells) {
-      cell.dirty = false;
-      cell.queue.clear();
+      if (cell.queue !== null) {
+        for (const record of cell.queue) record.queued = false;
+        cell.queue = null;
+      }
       cell.workInProgress = cell.current;
     }
-    root.dirtyCells.length = 0;
+    root.dirtyCells.clear();
 
     if (version === root.committedVersion) {
       root.changelog.length = 0;
@@ -49,19 +54,26 @@ export const setRootVersion = (
         root.changelog.pop();
       }
 
-      root.changelog.forEach((apply) => apply());
+      root.changelog.forEach(applyChangelogRecord);
       commitRoot(root);
     }
   }
 };
 
+export const applyChangelogRecord = (record: ChangelogRecord): void => {
+  markCellDirty(record.fiber, record.cell);
+  if (!record.queued) {
+    record.queued = true;
+    (record.cell.queue ??= []).push(record);
+  }
+};
+
 export const markCellDirty = (
   fiber: ResourceFiber<any, any>,
   cell: Cell & { type: "reducer" },
 ): void => {
-  if (!cell.dirty) {
-    cell.dirty = true;
+  if (!fiber.root.dirtyCells.has(cell)) {
     fiber.markDirty?.();
-    fiber.root.dirtyCells.push(cell);
+    fiber.root.dirtyCells.add(cell);
   }
 };

package/src/core/react-dispatcher.ts

@@ -1,13 +1,14 @@
-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";
+import React from "react";
+
+import { useState } from "../react-hooks/useState";
+import { useReducer } from "../react-hooks/useReducer";
+import { useRef } from "../react-hooks/useRef";
+import { useMemo } from "../react-hooks/useMemo";
+import { useCallback } from "../react-hooks/useCallback";
+import { useEffect } from "../react-hooks/useEffect";
+import { useEffectEvent } from "../react-hooks/useEffectEvent";
+import { use } from "../react-hooks/use";
+import { useMemoCache } from "../react-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
@@ -30,10 +31,10 @@ const tapDispatcher = {
 
 // 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 ReactRuntime = React as any;
 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;
+  ReactRuntime.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE ??
+  ReactRuntime.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
 
 const slot: { current: unknown } | null =
   internals == null

package/src/core/resource.ts

@@ -1,22 +1,7 @@
-import type { ResourceElement } from "./types";
-import { fnSymbol } from "./helpers/callResourceFn";
+import type { Resource, ResourceElement } from "./types";
 
-export function resource<R>(fn: () => R): () => ResourceElement<R, undefined>;
-export function resource<R, P>(
-  fn: (props: P) => R,
-): (props: P) => ResourceElement<R, P>;
-export function resource<R, P>(
-  fn: (props?: P) => R,
-): (props?: P) => ResourceElement<R, P | undefined>;
-export function resource<R, P = undefined>(fn: (props: P) => R) {
-  const type = (props?: P) => {
-    return {
-      type,
-      props: props!,
-    } satisfies ResourceElement<R, P>;
-  };
-
-  type[fnSymbol] = fn;
-
-  return type;
+export function resource<R, A extends readonly unknown[]>(
+  hook: (...args: A) => R,
+): Resource<R, A> {
+  return (...args: A): ResourceElement<R, A> => ({ hook, args });
 }

package/src/core/scheduler.ts

@@ -92,7 +92,7 @@ const scheduleMacrotask = (() => {
   return () => setTimeout(flushScheduled, 0);
 })();
 
-export const flushResourcesSync = <T>(callback: () => T): T => {
+export const flushTapSync = <T>(callback: () => T): T => {
   const prev = flushState;
   flushState = {
     schedulers: new Set([]),

package/src/core/types.ts

@@ -1,13 +1,15 @@
-import type { useEffect } from "../hooks/useEffect";
-
-export type ResourceElement<R, P = any> = {
-  readonly type: Resource<R, P>;
-  readonly props: P;
+export type ResourceElement<R, A extends readonly unknown[] = any[]> = {
+  readonly hook: (...args: A) => R;
+  readonly args: Readonly<A>;
   readonly key?: string | number;
 };
 
-export type Resource<R, P> = (props: P) => ResourceElement<R, P>;
-export type ContravariantResource<R, P> = (props: P) => ResourceElement<R>;
+export type Resource<R, A extends readonly unknown[] = any[]> = (
+  ...args: A
+) => ResourceElement<R, A>;
+export type ContravariantResource<R, A extends readonly unknown[] = any[]> = (
+  ...args: A
+) => ResourceElement<R>;
 
 export type ExtractResourceReturnType<T> =
   T extends ResourceElement<infer R, any>
@@ -16,10 +18,13 @@ export type ExtractResourceReturnType<T> =
       ? R
       : never;
 
-export interface ReducerQueueEntry {
+export interface ChangelogRecord {
+  readonly fiber: ResourceFiber<any, any>;
+  readonly cell: Cell & { type: "reducer" };
   readonly action: any;
   hasEagerState: boolean;
   eagerState: any;
+  queued: boolean;
 }
 
 export type Cell =
@@ -27,48 +32,49 @@ export type Cell =
       readonly type: "reducer";
       readonly dispatch: (action: any) => void;
 
-      readonly queue: Set<ReducerQueueEntry>;
-      dirty: boolean;
+      queue: ChangelogRecord[] | null;
+      renderQueue: any[] | null;
+
       workInProgress: any;
       current: any;
       reducer: (state: any, action: any) => any;
     }
   | {
       readonly type: "effect";
-      cleanup: useEffect.Destructor | undefined;
+      cleanup: (() => void) | undefined;
       deps: readonly unknown[] | null | undefined;
     };
 
 export interface EffectTask {
-  readonly effect: useEffect.EffectCallback;
-  readonly deps: readonly unknown[] | undefined;
-  readonly cell: Cell & { type: "effect" };
+  readonly cleanup: () => void;
+  readonly setup: () => void;
 }
 
 export interface RenderResult {
-  readonly output: any;
-  readonly props: any;
-  readonly effectTasks: (() => void)[];
+  value: any;
+  effectTasks: EffectTask[];
 }
 
 export interface ResourceFiberRoot {
   version: number;
   committedVersion: number;
-  readonly changelog: (() => void)[];
+  readonly changelog: ChangelogRecord[];
 
   readonly dispatchUpdate: (callback: () => boolean) => void;
-  readonly dirtyCells: (Cell & { type: "reducer" })[];
+  readonly dirtyCells: Set<Cell & { type: "reducer" }>;
 }
 
-export interface ResourceFiber<R, P> {
+export interface ResourceFiber<R, A extends readonly unknown[] = any[]> {
   readonly root: ResourceFiberRoot;
-  readonly type: Resource<R, P>;
+  readonly hook: (...args: A) => R;
   readonly markDirty: (() => void) | undefined;
   readonly devStrictMode: "root" | "child" | null;
 
   cells: Cell[];
   currentIndex: number;
 
+  renderPendingCells: Set<Cell & { type: "reducer" }> | null;
+
   renderContext: RenderResult | undefined; // set during render
 
   isMounted: boolean;

package/src/hooks/useResource.ts

@@ -1,49 +1,40 @@
 import type { ExtractResourceReturnType, ResourceElement } from "../core/types";
-import { useEffect } from "./useEffect";
 import {
-  createResourceFiber,
   unmountResourceFiber,
   renderResourceFiber,
   commitResourceFiber,
 } from "../core/ResourceFiber";
-import { useMemo } from "./useMemo";
-import { useRef } from "./useRef";
-import { getCurrentResourceFiber } from "../core/helpers/execution-context";
+import { useResourceFiberHost } from "./utils/useResourceFiberHostUtils";
+import { useEffect, useMemo } from "react";
+import { useRenderMemo } from "./utils/useRenderMemo";
 
-export function useResource<E extends ResourceElement<any, any>>(
+export function useResource<E extends ResourceElement<any, any[]>>(
   element: E,
 ): ExtractResourceReturnType<E>;
-export function useResource<E extends ResourceElement<any, any>>(
+export function useResource<E extends ResourceElement<any, any[]>>(
   element: E,
-  propsDeps: readonly unknown[],
+  argsDeps: readonly unknown[],
 ): ExtractResourceReturnType<E>;
-export function useResource<E extends ResourceElement<any, any>>(
+export function useResource<E extends ResourceElement<any, any[]>>(
   element: E,
-  propsDeps?: readonly unknown[],
+  argsDeps?: readonly unknown[],
 ): ExtractResourceReturnType<E> {
-  const parentFiber = getCurrentResourceFiber();
-  const versionRef = useRef(0);
+  const { version, createFiber } = useResourceFiberHost();
   const fiber = useMemo(() => {
-    void element.key;
-    return createResourceFiber(element.type, parentFiber.root, () => {
-      versionRef.current++;
-      parentFiber.markDirty?.();
-    });
-  }, [element.type, element.key, parentFiber]);
+    return createFiber(element.hook, element.key);
+  }, [element.hook, element.key, createFiber]);
 
-  const result = propsDeps
-    ? // 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 react/exhaustive-deps -- props identity replaced by user-provided deps
-        [fiber, ...propsDeps, versionRef.current],
-      )
-    : renderResourceFiber(fiber, element.props);
+  const identity = argsDeps ?? [element.args];
+
+  const result = useRenderMemo(
+    () => renderResourceFiber(fiber, element.args),
+    [fiber, version, ...identity],
+  );
 
   useEffect(() => () => unmountResourceFiber(fiber), [fiber]);
   useEffect(() => {
     commitResourceFiber(fiber, result);
   }, [fiber, result]);
 
-  return result.output;
+  return result.value;
 }

package/src/hooks/useResources.ts

@@ -4,41 +4,24 @@ import type {
   ResourceElement,
   ResourceFiber,
 } from "../core/types";
-import { useEffect } from "./useEffect";
-import { useMemo } from "./useMemo";
-import { useCallback } from "./useCallback";
 import {
-  createResourceFiber,
   unmountResourceFiber,
   renderResourceFiber,
   commitResourceFiber,
 } from "../core/ResourceFiber";
-import { useRef } from "./useRef";
-import { getCurrentResourceFiber } from "../core/helpers/execution-context";
+import { useResourceFiberHost } from "./utils/useResourceFiberHostUtils";
+import { useCallback, useEffect, useMemo } from "react";
+import { useRenderMemo } from "./utils/useRenderMemo";
 
 type FiberState = {
-  fiber: ResourceFiber<unknown, unknown>;
-  next:
-    | RenderResult
-    | [ResourceFiber<unknown, unknown>, RenderResult]
-    | "delete";
+  fiber: ResourceFiber<unknown>;
+  next: RenderResult | [ResourceFiber<unknown>, RenderResult] | "delete";
 };
 
-export function useResources<E extends ResourceElement<any, any>>(
+export function useResources<E extends ResourceElement<any, any[]>>(
   getElements: () => readonly E[],
   getElementsDeps?: readonly unknown[],
 ): ExtractResourceReturnType<E>[] {
-  const versionRef = useRef(0);
-  const version = versionRef.current;
-
-  const parentFiber = useMemo(() => getCurrentResourceFiber(), []);
-  const markDirty = useMemo(
-    () => () => {
-      versionRef.current++;
-      parentFiber.markDirty?.();
-    },
-    [parentFiber],
-  );
   const fibers = useMemo(() => new Map<string | number, FiberState>(), []);
 
   const getElementsMemo = getElementsDeps
@@ -48,7 +31,8 @@ export function useResources<E extends ResourceElement<any, any>>(
 
   // Process each element
 
-  const res = useMemo(() => {
+  const { version, createFiber } = useResourceFiberHost();
+  const res = useRenderMemo(() => {
     void version;
 
     const elementsArray = getElementsMemo();
@@ -73,31 +57,23 @@ export function useResources<E extends ResourceElement<any, any>>(
 
       let state = fibers.get(elementKey);
       if (!state) {
-        const fiber = createResourceFiber(
-          element.type,
-          parentFiber.root,
-          markDirty,
-        );
-        const result = renderResourceFiber(fiber, element.props);
+        const fiber = createFiber(element.hook, element.key);
+        const result = renderResourceFiber(fiber, element.args);
         state = {
           fiber,
           next: result,
         };
         newCount++;
         fibers.set(elementKey, state);
-        results.push(result.output);
-      } else if (state.fiber.type !== element.type) {
-        const fiber = createResourceFiber(
-          element.type,
-          parentFiber.root,
-          markDirty,
-        );
-        const result = renderResourceFiber(fiber, element.props);
+        results.push(result.value);
+      } else if (state.fiber.hook !== element.hook) {
+        const fiber = createFiber(element.hook, element.key);
+        const result = renderResourceFiber(fiber, element.args);
         state.next = [fiber, result];
-        results.push(result.output);
+        results.push(result.value);
       } else {
-        state.next = renderResourceFiber(state.fiber, element.props);
-        results.push(state.next.output);
+        state.next = renderResourceFiber(state.fiber, element.args);
+        results.push(state.next.value);
       }
     }
 
@@ -111,7 +87,7 @@ export function useResources<E extends ResourceElement<any, any>>(
     }
 
     return results;
-  }, [getElementsMemo, version, parentFiber, markDirty, fibers]);
+  }, [getElementsMemo, fibers, createFiber, version]);
 
   // Cleanup on unmount
   useEffect(() => {

package/src/hooks/useTapHost.ts

@@ -0,0 +1,60 @@
+import {
+  unmountResourceFiber,
+  renderResourceFiber,
+  commitResourceFiber,
+} from "../core/ResourceFiber";
+import { useResourceFiberHost } from "./utils/useResourceFiberHostUtils";
+import { useEffect, useMemo } from "react";
+
+export namespace useTapHost {
+  export interface Result<R> {
+    /**
+     * The current render output of the host resource.
+     */
+    value: R;
+
+    /**
+     * Commits the host's pending render result. Pass to a deps-less
+     * useEffect in a descendant component to land the commit ahead of
+     * the descendants' own effects; the first instance to run wins. A
+     * plain callback (not a hook) so React Compiler can compile the
+     * consumer; its identity changes on every host render.
+     */
+    effects: () => void;
+  }
+}
+
+const useHostRender = <R>(render: () => R): R => render();
+
+export const useTapHost = <R>(callback: () => R): useTapHost.Result<R> => {
+  const { createFiber } = useResourceFiberHost();
+  const fiber = useMemo(
+    () => createFiber(useHostRender<R>, undefined),
+    [createFiber],
+  );
+
+  const render = renderResourceFiber(fiber, [callback]);
+
+  useEffect(() => {
+    return () => {
+      unmountResourceFiber(fiber);
+    };
+  }, [fiber]);
+
+  let renderCommitted = false;
+  const effects = () => {
+    // !isMounted: StrictMode/Activity replays effects without a re-render
+    // after unmounting the fiber; the replay must recommit it.
+    if (renderCommitted && fiber.isMounted) return;
+    renderCommitted = true;
+
+    commitResourceFiber(fiber, render);
+  };
+
+  useEffect(effects);
+
+  return {
+    value: render.value as R,
+    effects,
+  };
+};

package/src/hooks/useTapRoot.ts

@@ -0,0 +1,135 @@
+import {
+  commitResourceFiber,
+  createResourceFiber,
+  renderResourceFiber,
+  unmountResourceFiber,
+} from "../core/ResourceFiber";
+import { UpdateScheduler } from "../core/scheduler";
+import { isDevelopment } from "../core/helpers/env";
+import {
+  commitRoot,
+  createResourceFiberRoot,
+  setRootVersion,
+} from "../core/helpers/root";
+import { useEffect, useEffectEvent, useMemo, useRef } from "react";
+import { useDevStrictMode } from "./utils/useDevStrictMode";
+
+export namespace useTapRoot {
+  export type Unsubscribe = () => void;
+
+  export interface Root<R> {
+    /**
+     * Get the current value of the root.
+     */
+    getValue(): R;
+
+    /**
+     * Subscribe to the root.
+     */
+    subscribe(listener: () => void): Unsubscribe;
+  }
+}
+
+const useHostRoot = <R>(render: () => R): R => render();
+
+export const useTapRoot = <R>(render: () => R): useTapRoot.Root<R> => {
+  const scheduler = useMemo(
+    () => new UpdateScheduler(() => handleUpdate()),
+    [],
+  );
+  const queue = useMemo(() => [] as (() => boolean)[], []);
+
+  const getDevStrictMode = useDevStrictMode();
+  const fiber = useMemo(() => {
+    const root = createResourceFiberRoot((callback) => {
+      if (!scheduler.isDirty && !callback()) return;
+
+      setRootVersion(root, root.committedVersion + root.changelog.length);
+      queue.push(callback);
+      scheduler.markDirty();
+    });
+    return createResourceFiber(
+      useHostRoot<R>,
+      root,
+      undefined,
+      getDevStrictMode(),
+    );
+  }, [queue, scheduler, getDevStrictMode]);
+
+  const drainedCount = fiber.root.version - fiber.root.committedVersion;
+  const render2 = renderResourceFiber(fiber, [render]);
+
+  const isMountedRef = useRef(false);
+  const committedArgsRef = useRef([render] as const);
+  const valueRef = useRef<R>(render2.value);
+  const subscribers = useMemo(() => new Set<() => void>(), []);
+
+  const publish = (output: R) => {
+    if (scheduler.isDirty || valueRef.current === output) return;
+    valueRef.current = output;
+    subscribers.forEach((listener) => listener());
+  };
+
+  const handleUpdate = useEffectEvent(() => {
+    setRootVersion(fiber.root, fiber.root.committedVersion);
+
+    queue.forEach((callback) => {
+      if (isDevelopment && fiber.devStrictMode) {
+        callback();
+      }
+
+      callback();
+    });
+
+    setRootVersion(
+      fiber.root,
+      fiber.root.committedVersion + fiber.root.changelog.length,
+    );
+
+    if (isDevelopment && fiber.devStrictMode) {
+      void renderResourceFiber(fiber, committedArgsRef.current);
+    }
+
+    const render = renderResourceFiber(fiber, committedArgsRef.current);
+
+    if (scheduler.isDirty)
+      throw new Error("Scheduler is dirty, this should never happen");
+
+    commitRoot(fiber.root);
+    queue.length = 0;
+
+    if (isMountedRef.current) {
+      commitResourceFiber(fiber, render);
+    }
+
+    publish(render.value);
+  });
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      unmountResourceFiber(fiber);
+    };
+  }, [fiber]);
+
+  useEffect(() => {
+    committedArgsRef.current = [render];
+    commitRoot(fiber.root);
+    queue.splice(0, drainedCount);
+    commitResourceFiber(fiber, render2);
+
+    publish(render2.value);
+  });
+
+  return useMemo(
+    () => ({
+      getValue: () => valueRef.current,
+      subscribe: (listener: () => void) => {
+        subscribers.add(listener);
+        return () => subscribers.delete(listener);
+      },
+    }),
+    [subscribers],
+  );
+};