@ipxjs/refract 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipxjs/refract",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A minimal React-like virtual DOM library with an optional React compat layer",
   "type": "module",
   "main": "src/refract/index.ts",

package/src/refract/compat/react-dom.ts

@@ -1,5 +1,6 @@
 import { createElement, Fragment } from "../createElement.js";
 import { flushPendingRenders } from "../coreRenderer.js";
+import { flushPassiveEffects } from "../hooksRuntime.js";
 import { setReactCompatEventMode } from "../dom.js";
 import { createPortal as createPortalImpl } from "../portal.js";
 import type { PortalChild } from "../portal.js";
@@ -18,6 +19,7 @@ export function unstable_batchedUpdates<T>(callback: () => T): T {
 export function flushSync<T>(callback: () => T): T {
   const result = callback();
   flushPendingRenders();
+  flushPassiveEffects();
   return result;
 }
 

package/src/refract/coreRenderer.ts

@@ -8,6 +8,7 @@ import {
   runAfterComponentRenderHandlers,
   runAfterCommitHandlers,
   runBeforeComponentRenderHandlers,
+  runBeforeRenderBatchHandlers,
   runCommitHandlers,
   runFiberCleanupHandlers,
   shouldBailoutComponent,
@@ -358,53 +359,65 @@ const MAX_NESTED_RENDERS = 50;
 const renderCounts = new Map<Node, number>();
 
 function flushRenders(): void {
-  flushScheduled = false;
-  // Snapshot and clear pendingContainers BEFORE processing,
-  // so effects that call scheduleRender during commit add to a fresh set.
-  const containers = [...pendingContainers];
-  pendingContainers.clear();
-  for (const container of containers) {
-    const currentRoot = roots.get(container);
-    if (!currentRoot) continue;
-
-    // Re-render guard: detect infinite loops (matches React's limit of 50)
-    const count = (renderCounts.get(container) ?? 0) + 1;
-    if (count > MAX_NESTED_RENDERS) {
-      renderCounts.delete(container);
-      throw new Error(
-        "Too many re-renders. Refract limits the number of renders to prevent an infinite loop.",
-      );
+  // Flush any pending passive effects from previous renders before
+  // starting new render work. This matches React's behavior: passive
+  // effects from render N are guaranteed to run before render N+1.
+  runBeforeRenderBatchHandlers();
+
+  // Keep flushScheduled true during processing to prevent duplicate
+  // microtask scheduling. Layout effects that call setState will add to
+  // pendingContainers, which we process in the next iteration of the
+  // while loop (synchronous cascade, protected by the render counter).
+  while (pendingContainers.size > 0) {
+    const containers = [...pendingContainers];
+    pendingContainers.clear();
+
+    for (const container of containers) {
+      const currentRoot = roots.get(container);
+      if (!currentRoot) continue;
+
+      // Re-render guard: detect infinite loops (matches React's limit of 50)
+      const count = (renderCounts.get(container) ?? 0) + 1;
+      if (count > MAX_NESTED_RENDERS) {
+        renderCounts.clear();
+        flushScheduled = false;
+        throw new Error(
+          "Too many re-renders. Refract limits the number of renders to prevent an infinite loop.",
+        );
+      }
+      renderCounts.set(container, count);
+
+      const newRoot: Fiber = {
+        type: currentRoot.type,
+        props: currentRoot.props,
+        key: currentRoot.key,
+        dom: currentRoot.dom,
+        parentDom: currentRoot.parentDom,
+        parent: null,
+        child: null,
+        sibling: null,
+        hooks: null,
+        alternate: currentRoot,
+        flags: UPDATE,
+      };
+      deletions = [];
+      isRendering = true;
+      performWork(newRoot);
+      isRendering = false;
+      const committedDeletions = deletions.slice();
+      commitRoot(newRoot);
+      runAfterCommitHandlers();
+      roots.set(container, newRoot);
+      runCommitHandlers(newRoot, committedDeletions);
     }
-    renderCounts.set(container, count);
-
-    const newRoot: Fiber = {
-      type: currentRoot.type,
-      props: currentRoot.props,
-      key: currentRoot.key,
-      dom: currentRoot.dom,
-      parentDom: currentRoot.parentDom,
-      parent: null,
-      child: null,
-      sibling: null,
-      hooks: null,
-      alternate: currentRoot,
-      flags: UPDATE,
-    };
-    deletions = [];
-    isRendering = true;
-    performWork(newRoot);
-    isRendering = false;
-    const committedDeletions = deletions.slice();
-    commitRoot(newRoot);
-    runAfterCommitHandlers();
-    roots.set(container, newRoot);
-    runCommitHandlers(newRoot, committedDeletions);
   }
 
-  // Reset counters when no more pending renders (loop resolved)
-  if (pendingContainers.size === 0) {
-    renderCounts.clear();
-  }
+  // All synchronous work complete (including layout effect cascades).
+  // Reset counter and allow new microtask scheduling.
+  // Deferred passive effects will trigger fresh flushRenders calls
+  // with their own counter scope.
+  renderCounts.clear();
+  flushScheduled = false;
 }
 
 export function flushPendingRenders(): void {

package/src/refract/features/hooks.ts

@@ -58,6 +58,7 @@ interface EffectHook extends Hook {
     deps: unknown[] | undefined;
     cleanup?: EffectCleanup;
     pending: boolean;
+    effectType: "insertion" | "layout" | "passive";
   };
 }
 
@@ -66,7 +67,7 @@ export function useEffect(effect: () => EffectCleanup, deps?: unknown[]): void {
   const fiber = currentFiber!;
 
   if (hook.state === undefined) {
-    hook.state = { effect, deps, cleanup: undefined, pending: true };
+    hook.state = { effect, deps, cleanup: undefined, pending: true, effectType: "passive" };
     markPendingEffects(fiber);
   } else {
     if (depsChanged(hook.state.deps, deps)) {
@@ -85,7 +86,7 @@ export function useLayoutEffect(effect: () => EffectCleanup, deps?: unknown[]):
   const fiber = currentFiber!;
 
   if (hook.state === undefined) {
-    hook.state = { effect, deps, cleanup: undefined, pending: true };
+    hook.state = { effect, deps, cleanup: undefined, pending: true, effectType: "layout" };
     markPendingLayoutEffects(fiber);
   } else {
     if (depsChanged(hook.state.deps, deps)) {
@@ -104,7 +105,7 @@ export function useInsertionEffect(effect: () => EffectCleanup, deps?: unknown[]
   const fiber = currentFiber!;
 
   if (hook.state === undefined) {
-    hook.state = { effect, deps, cleanup: undefined, pending: true };
+    hook.state = { effect, deps, cleanup: undefined, pending: true, effectType: "insertion" };
     markPendingInsertionEffects(fiber);
   } else {
     if (depsChanged(hook.state.deps, deps)) {

package/src/refract/full.ts

@@ -3,6 +3,7 @@ export { render } from "./render.js";
 export { memo } from "./memo.js";
 export { setHtmlSanitizer } from "./features/security.js";
 export { setDevtoolsHook, DEVTOOLS_GLOBAL_HOOK } from "./devtools.js";
+export { flushPassiveEffects } from "./hooksRuntime.js";
 export {
   useState,
   useEffect,

package/src/refract/hooksRuntime.ts

@@ -2,6 +2,7 @@ import type { Fiber } from "./types.js";
 import { reconcileChildren } from "./reconcile.js";
 import {
   registerAfterCommitHandler,
+  registerBeforeRenderBatchHandler,
   registerFiberCleanupHandler,
   registerRenderErrorHandler,
 } from "./runtimeExtensions.js";
@@ -9,6 +10,8 @@ import {
 const fibersWithPendingEffects = new Set<Fiber>();
 const fibersWithPendingLayoutEffects = new Set<Fiber>();
 const fibersWithPendingInsertionEffects = new Set<Fiber>();
+const deferredPassiveEffectFibers = new Set<Fiber>();
+let passiveFlushScheduled = false;
 
 export function markPendingEffects(fiber: Fiber): void {
   fibersWithPendingEffects.add(fiber);
@@ -26,18 +29,23 @@ function cleanupFiberEffects(fiber: Fiber): void {
   fibersWithPendingEffects.delete(fiber);
   fibersWithPendingLayoutEffects.delete(fiber);
   fibersWithPendingInsertionEffects.delete(fiber);
+  deferredPassiveEffectFibers.delete(fiber);
   if (!fiber.hooks) return;
 
   for (const hook of fiber.hooks) {
-    const state = hook.state as { cleanup?: () => void } | undefined;
+    const state = hook.state as { cleanup?: () => void; pending?: boolean } | undefined;
     if (state?.cleanup) {
       state.cleanup();
       state.cleanup = undefined;
     }
+    // Prevent deferred passive effects from running on unmounted fibers
+    if (state && "pending" in state) {
+      state.pending = false;
+    }
   }
 }
 
-function runPendingEffectsFor(fibers: Set<Fiber>): void {
+function runPendingEffectsFor(fibers: Set<Fiber>, effectType: string): void {
   for (const fiber of fibers) {
     if (!fiber.hooks) continue;
 
@@ -46,7 +54,9 @@ function runPendingEffectsFor(fibers: Set<Fiber>): void {
         effect?: () => void | (() => void);
         pending?: boolean;
         cleanup?: () => void;
+        effectType?: string;
       } | undefined;
+      if (state?.effectType !== effectType) continue;
       if (state?.pending && state.effect) {
         if (state.cleanup) state.cleanup();
         state.cleanup = state.effect() || undefined;
@@ -58,10 +68,30 @@ function runPendingEffectsFor(fibers: Set<Fiber>): void {
 }
 
 function runPendingEffects(): void {
-  // run in insertion -> layout -> passive order
-  runPendingEffectsFor(fibersWithPendingInsertionEffects);
-  runPendingEffectsFor(fibersWithPendingLayoutEffects);
-  runPendingEffectsFor(fibersWithPendingEffects);
+  // Insertion and layout effects run synchronously (matching React)
+  runPendingEffectsFor(fibersWithPendingInsertionEffects, "insertion");
+  runPendingEffectsFor(fibersWithPendingLayoutEffects, "layout");
+
+  // Passive effects (useEffect) are deferred until after the current
+  // synchronous work completes, matching React's behavior.
+  if (fibersWithPendingEffects.size > 0) {
+    for (const fiber of fibersWithPendingEffects) {
+      deferredPassiveEffectFibers.add(fiber);
+    }
+    fibersWithPendingEffects.clear();
+    if (!passiveFlushScheduled) {
+      passiveFlushScheduled = true;
+      setTimeout(flushPassiveEffects, 0);
+    }
+  }
+}
+
+export function flushPassiveEffects(): void {
+  passiveFlushScheduled = false;
+  if (deferredPassiveEffectFibers.size === 0) return;
+  const fibers = new Set(deferredPassiveEffectFibers);
+  deferredPassiveEffectFibers.clear();
+  runPendingEffectsFor(fibers, "passive");
 }
 
 function handleErrorBoundary(fiber: Fiber, error: unknown): boolean {
@@ -79,4 +109,5 @@ function handleErrorBoundary(fiber: Fiber, error: unknown): boolean {
 
 registerFiberCleanupHandler(cleanupFiberEffects);
 registerAfterCommitHandler(runPendingEffects);
+registerBeforeRenderBatchHandler(flushPassiveEffects);
 registerRenderErrorHandler(handleErrorBoundary);

package/src/refract/runtimeExtensions.ts

@@ -2,6 +2,7 @@ import type { Fiber } from "./types.js";
 
 type FiberCleanupHandler = (fiber: Fiber) => void;
 type AfterCommitHandler = () => void;
+type BeforeRenderBatchHandler = () => void;
 type RenderErrorHandler = (fiber: Fiber, error: unknown) => boolean;
 type CommitHandler = (rootFiber: Fiber, deletions: Fiber[]) => void;
 type ComponentBailoutHandler = (fiber: Fiber) => boolean;
@@ -10,6 +11,7 @@ type AfterComponentRenderHandler = (fiber: Fiber) => void;
 
 const fiberCleanupHandlers = new Set<FiberCleanupHandler>();
 const afterCommitHandlers = new Set<AfterCommitHandler>();
+const beforeRenderBatchHandlers = new Set<BeforeRenderBatchHandler>();
 const renderErrorHandlers = new Set<RenderErrorHandler>();
 const commitHandlers = new Set<CommitHandler>();
 const componentBailoutHandlers = new Set<ComponentBailoutHandler>();
@@ -32,6 +34,11 @@ export function registerAfterCommitHandler(handler: AfterCommitHandler): () => v
   return makeUnregister(afterCommitHandlers, handler);
 }
 
+export function registerBeforeRenderBatchHandler(handler: BeforeRenderBatchHandler): () => void {
+  beforeRenderBatchHandlers.add(handler);
+  return makeUnregister(beforeRenderBatchHandlers, handler);
+}
+
 export function registerRenderErrorHandler(handler: RenderErrorHandler): () => void {
   renderErrorHandlers.add(handler);
   return makeUnregister(renderErrorHandlers, handler);
@@ -69,6 +76,12 @@ export function runAfterCommitHandlers(): void {
   }
 }
 
+export function runBeforeRenderBatchHandlers(): void {
+  for (const handler of beforeRenderBatchHandlers) {
+    handler();
+  }
+}
+
 export function tryHandleRenderError(fiber: Fiber, error: unknown): boolean {
   for (const handler of renderErrorHandlers) {
     if (handler(fiber, error)) {

package/tests/compat.test.ts

@@ -54,7 +54,7 @@ describe("react compat", () => {
     expect(container.querySelector("span")!.id).toBe(ids[1]);
   });
 
-  it("runs insertion/layout/passive effects in commit order", () => {
+  it("runs insertion/layout effects synchronously, passive effects deferred", async () => {
     const root = createRoot(container);
     const calls: string[] = [];
 
@@ -72,6 +72,9 @@ describe("react compat", () => {
     }
 
     root.render(ReactCompat.createElement(App, null));
+    // Insertion and layout are synchronous; passive is deferred (like React)
+    expect(calls).toEqual(["insertion", "layout"]);
+    await waitForRender();
     expect(calls).toEqual(["insertion", "layout", "effect"]);
   });
 

package/tests/hooks.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, vi } from "vitest";
 import { createElement } from "../src/refract/createElement.js";
 import { render } from "../src/refract/render.js";
 import { useState, useEffect, useRef, useMemo, useCallback, useReducer } from "../src/refract/hooks.js";
+import { flushPassiveEffects } from "../src/refract/hooksRuntime.js";
 
 describe("hooks", () => {
   let container: HTMLDivElement;
@@ -73,13 +74,28 @@ describe("hooks", () => {
   });
 
   describe("useEffect", () => {
-    it("runs effect after render", () => {
+    it("runs effect after render (deferred)", async () => {
       const effectFn = vi.fn();
       function App() {
         useEffect(effectFn);
         return createElement("div", null);
       }
       render(createElement(App, null), container);
+      // Passive effects are deferred (like React)
+      expect(effectFn).not.toHaveBeenCalled();
+      await new Promise((r) => setTimeout(r, 10));
+      expect(effectFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("can be flushed synchronously with flushPassiveEffects", () => {
+      const effectFn = vi.fn();
+      function App() {
+        useEffect(effectFn);
+        return createElement("div", null);
+      }
+      render(createElement(App, null), container);
+      expect(effectFn).not.toHaveBeenCalled();
+      flushPassiveEffects();
       expect(effectFn).toHaveBeenCalledTimes(1);
     });
 
@@ -112,6 +128,8 @@ describe("hooks", () => {
         return createElement("span", null, String(value));
       }
       render(createElement(App, null), container);
+      // Flush initial passive effects
+      flushPassiveEffects();
       expect(effectFn).toHaveBeenCalledTimes(1);
 
       setValue(1);