@ipxjs/refract 0.5.1 → 0.7.0

package/README.md

@@ -121,6 +121,11 @@ export default defineConfig({
 The compat layer is intentionally separate from core so users who do not need
 React ecosystem compatibility keep the smallest and fastest Refract bundles.
 
+Compatibility status (last verified February 17, 2026):
+- `yarn test`: 14 files passed, 85 tests passed
+- Compat-focused suites passed: `tests/compat.test.ts` (10), `tests/poc-compat.test.ts` (2), `tests/react-router-smoke.test.ts` (3)
+- Verified behaviors include `forwardRef`, portals, `createRoot`, JSX runtimes, `useSyncExternalStore`, `flushSync`, and react-router tree construction/dispatcher bridging
+
 ## API
 
 ### createElement(type, props, ...children)
@@ -215,21 +220,23 @@ image requests blocked.
 
 ### Bundle Size Snapshot
 
-The values below are from a local run on February 16, 2026.
+The values below are from a local run on February 17, 2026.
 
 | Framework                  | JS bundle (raw) | JS bundle (gzip) |
 |---------------------------|----------------:|-----------------:|
 | Refract (`core`)          | 8.62 kB         | 3.24 kB          |
-| Refract (`core+hooks`)    | 10.28 kB        | 3.85 kB          |
+| Refract (`core+hooks`)    | 10.27 kB        | 3.84 kB          |
 | Refract (`core+context`)  | 9.12 kB         | 3.47 kB          |
-| Refract (`core+memo`)     | 9.29 kB         | 3.48 kB          |
+| Refract (`core+memo`)     | 9.29 kB         | 3.47 kB          |
 | Refract (`core+security`) | 9.53 kB         | 3.54 kB          |
 | Refract (`refract`)       | 15.20 kB        | 5.55 kB          |
-| React                     | 189.74 kB       | 59.52 kB         |
-| Preact                    | 14.46 kB        | 5.95 kB          |
+| React                     | 189.74 kB       | 59.58 kB         |
+| Preact                    | 14.46 kB        | 5.96 kB          |
 
 Load-time metrics are machine-dependent, so the benchmark script prints a fresh
 per-run timing table (median, p95, min/max, sd) for every framework.
+The CI preset (`make bench-ci`, 40 measured + 5 warmup runs) also passed on
+February 17, 2026 with default guardrails (`DCL p95 <= 16ms`, `DCL sd <= 2ms`).
 
 From this snapshot, Refract `core` gzip JS is about 18.4x smaller than React,
 and the full `refract` entrypoint is about 10.7x smaller.
@@ -242,16 +249,16 @@ Higher `hz` is better.
 
 | Component usage profile | Mount (hz) | Mount vs base | Reconcile (hz) | Reconcile vs base |
 |-------------------------|------------|---------------|----------------|-------------------|
-| `base` | 5341.47 | baseline | 3932.98 | baseline |
-| `memo` | 5821.44 | +9.0% | 5202.62 | +32.3% |
-| `context` | 3960.70 | -25.9% | 5108.06 | +29.9% |
-| `fragment` | 4739.90 | -11.3% | 4114.70 | +4.6% |
-| `keyed` | 6008.81 | +12.5% | 4816.85 | +22.5% |
-| `memo+context` | 5670.29 | +6.2% | 5231.58 | +33.0% |
-| `memo+context+keyed` | 5813.60 | +8.8% | 4606.91 | +17.1% |
+| `base` | 6570.25 | baseline | 3413.29 | baseline |
+| `memo` | 7257.38 | +10.5% | 7541.91 | +120.9% |
+| `context` | 6427.45 | -2.2% | 7119.35 | +108.6% |
+| `fragment` | 5935.06 | -9.7% | 3437.54 | +0.7% |
+| `keyed` | 9022.55 | +37.3% | 6535.55 | +91.5% |
+| `memo+context` | 7015.37 | +6.8% | 6782.87 | +98.7% |
+| `memo+context+keyed` | 7992.82 | +21.7% | 6803.09 | +99.3% |
 
 In this run, `keyed` was the fastest mount profile, while
-`memo+context` was the fastest reconcile profile.
+`memo` was the fastest reconcile profile.
 
 ### Running the Benchmark
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipxjs/refract",
-  "version": "0.5.1",
+  "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/compat/react-jsx-runtime.ts

@@ -1,5 +1,6 @@
 import { createElement, Fragment } from "../createElement.js";
 import type { VNode, VNodeType } from "../types.js";
+import { isClassComponent, wrapClassComponent, getWrappedHandler } from "./react.js";
 
 type JsxProps = Record<string, unknown> | null | undefined;
 type JsxChild = VNode | string | number | boolean | null | undefined | JsxChild[];
@@ -18,6 +19,8 @@ function normalizeVNodeChildren(vnode: VNode): VNode {
 }
 
 function createJsxElement(type: VNodeType, rawProps: JsxProps, key?: string): ReturnType<typeof createElement> {
+  const effectiveType = isClassComponent(type) ? wrapClassComponent(type as Function) : type;
+  
   const props = { ...(rawProps ?? {}) };
   if (key !== undefined) {
     props.key = key;
@@ -25,13 +28,22 @@ function createJsxElement(type: VNodeType, rawProps: JsxProps, key?: string): Re
   const children = props.children as JsxChild | JsxChild[] | undefined;
   delete props.children;
 
+  // Wrap event handlers
+  if (typeof type === 'string') {
+    for (const key in props) {
+      if (key.startsWith('on') && typeof props[key] === 'function') {
+        props[key] = getWrappedHandler(props[key] as Function);
+      }
+    }
+  }
+
   let vnode: VNode;
   if (children === undefined) {
-    vnode = createElement(type, props);
+    vnode = createElement(effectiveType as VNodeType, props);
   } else if (Array.isArray(children)) {
-    vnode = createElement(type, props, ...(children as JsxChild[]));
+    vnode = createElement(effectiveType as VNodeType, props, ...(children as JsxChild[]));
   } else {
-    vnode = createElement(type, props, children as JsxChild);
+    vnode = createElement(effectiveType as VNodeType, props, children as JsxChild);
   }
   return normalizeVNodeChildren(vnode);
 }
@@ -44,4 +56,4 @@ export function jsxs(type: VNodeType, props: JsxProps, key?: string): ReturnType
   return createJsxElement(type, props, key);
 }
 
-export { Fragment };
+export { Fragment };

package/src/refract/compat/react.ts

@@ -1,10 +1,11 @@
-import { createElement, Fragment } from "../createElement.js";
+import { createElement as createElementImpl, Fragment } from "../createElement.js";
 import { memo } from "../memo.js";
-import { createContext } from "../features/context.js";
+import { createContext as createContextImpl } from "../features/context.js";
 import {
   createRef,
+  useErrorBoundary,
 } from "../features/hooks.js";
-import type { Component, Props, VNode } from "../types.js";
+import type { Component as RefractComponent, Props, VNode } from "../types.js";
 import {
   __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
   __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
@@ -31,8 +32,8 @@ function parseChildrenArgs(children: unknown[]): unknown {
 
 export function forwardRef<T, P extends Record<string, unknown> = Record<string, unknown>>(
   render: (props: P, ref: { current: T | null } | ((value: T | null) => void) | null) => VNode,
-): Component {
-  const ForwardRefComponent: Component = (props: Props) => {
+): RefractComponent {
+  const ForwardRefComponent: RefractComponent = (props: Props) => {
     const { ref, ...rest } = props as Props & { ref?: { current: T | null } | ((value: T | null) => void) | null };
     return render(rest as unknown as P, ref ?? null);
   };
@@ -199,7 +200,287 @@ export function useDeferredValue<T>(value: T, initialValue?: T): T {
   return resolveDispatcher().useDeferredValue(value, initialValue);
 }
 
-export { createElement, Fragment, createContext, memo };
+// ---------------------------------------------------------------------------
+// Context Wrapper
+// ---------------------------------------------------------------------------
+
+export function createContext<T>(defaultValue: T): any {
+  const ctx = createContextImpl(defaultValue) as any;
+  ctx._currentValue = defaultValue;
+  ctx._currentValue2 = defaultValue;
+  ctx.displayName = undefined;
+  ctx.Consumer = ctx;
+  if (ctx.Provider) {
+    ctx.Provider._context = ctx;
+  }
+  return ctx;
+}
+
+// ---------------------------------------------------------------------------
+// Class Component Support
+// ---------------------------------------------------------------------------
+
+export function Component(this: any, props: any, context?: any) {
+  this.props = props;
+  this.state = {};
+  this.context = context ?? undefined;
+  this._forceUpdate = null;
+}
+Component.prototype.setState = function (
+  this: any,
+  partial: any,
+  callback?: () => void,
+): void {
+  if (typeof partial === 'function') {
+    const result = partial(this.state, this.props);
+    if (result != null) {
+      this.state = { ...this.state, ...result };
+    }
+  } else {
+    this.state = { ...this.state, ...partial };
+  }
+  if (this._forceUpdate) {
+    this._forceUpdate();
+  }
+  if (callback) queueMicrotask(callback);
+};
+Component.prototype.forceUpdate = function (this: any, callback?: () => void): void {
+  if (this._forceUpdate) {
+    this._forceUpdate();
+  }
+  if (callback) queueMicrotask(callback);
+};
+Component.prototype.render = function (): unknown {
+  return null;
+};
+Component.prototype.isReactComponent = {};
+
+export function PureComponent(this: any, props: any) {
+  Component.call(this, props);
+}
+PureComponent.prototype = Object.create(Component.prototype);
+PureComponent.prototype.constructor = PureComponent;
+PureComponent.prototype.isPureReactComponent = true;
+
+// ---------------------------------------------------------------------------
+// Suspense / Lazy
+// ---------------------------------------------------------------------------
+
+export function Suspense(props: { children?: unknown; fallback?: unknown }): unknown {
+  return props.children ?? null;
+}
+
+export function lazy<T extends { default: (...args: any[]) => any }>(
+  factory: () => Promise<T>,
+): (props: any) => unknown {
+  let resolved: ((...args: any[]) => any) | null = null;
+  let promise: Promise<void> | null = null;
+  const LazyComponent = (props: any) => {
+    if (resolved) return createElementImpl(resolved as any, props);
+    if (!promise) {
+      promise = factory().then((mod) => {
+        resolved = mod.default;
+      });
+    }
+    throw promise;
+  };
+  return LazyComponent;
+}
+
+// ---------------------------------------------------------------------------
+// Class Wrapper Logic
+// ---------------------------------------------------------------------------
+
+const classWrapperCache = new WeakMap<Function, Function>();
+
+export function isClassComponent(type: unknown): boolean {
+  return (
+    typeof type === 'function' &&
+    (type as any).prototype != null &&
+    typeof (type as any).prototype.render === 'function'
+  );
+}
+
+export function wrapClassComponent(ClassComp: Function): (props: any) => unknown {
+  const cached = classWrapperCache.get(ClassComp);
+  if (cached) return cached as (props: any) => unknown;
+
+  const Ctor = ClassComp as any;
+  const hasErrorBoundary = typeof Ctor.getDerivedStateFromError === 'function';
+  const hasLifecycles =
+    typeof Ctor.prototype.componentDidMount === 'function' ||
+    typeof Ctor.prototype.componentDidUpdate === 'function';
+  const hasWillUnmount = typeof Ctor.prototype.componentWillUnmount === 'function';
+  const contextType = Ctor.contextType ?? null;
+
+  const Wrapper = (rawProps: any): unknown => {
+    const props = Ctor.defaultProps ? { ...Ctor.defaultProps, ...rawProps } : rawProps;
+    const [, setTick] = useState(0);
+    const forceUpdate = useCallback(() => setTick((t: number) => t + 1), []);
+    const instanceRef = useRef<any>(null);
+
+    if (!instanceRef.current) {
+      instanceRef.current = new (ClassComp as any)(props);
+    }
+    const instance = instanceRef.current;
+    instance.props = props;
+    instance._forceUpdate = forceUpdate;
+
+    if (contextType) {
+      instance.context = useContext(contextType);
+    }
+
+    if (typeof Ctor.getDerivedStateFromProps === 'function') {
+      const derived = Ctor.getDerivedStateFromProps(props, instance.state);
+      if (derived != null) {
+        instance.state = { ...instance.state, ...derived };
+      }
+    }
+
+    if (hasErrorBoundary) {
+      const [error, resetError] = useErrorBoundary();
+      if (error) {
+        const newState = Ctor.getDerivedStateFromError(error);
+        instance.state = { ...instance.state, ...newState };
+        if (typeof (instance as any).componentDidCatch === 'function') {
+          (instance as any).componentDidCatch(error, { componentStack: '' });
+        }
+        resetError();
+      }
+    }
+
+    if (hasLifecycles) {
+      const mountedRef = useRef(false);
+      const prevPropsRef = useRef<any>(null);
+      const prevStateRef = useRef<any>(null);
+
+      useLayoutEffect(() => {
+        if (!mountedRef.current) {
+          mountedRef.current = true;
+          if (typeof instance.componentDidMount === 'function') {
+            instance.componentDidMount();
+          }
+        } else {
+          if (typeof instance.componentDidUpdate === 'function') {
+            instance.componentDidUpdate(prevPropsRef.current, prevStateRef.current);
+          }
+        }
+        prevPropsRef.current = instance.props;
+        prevStateRef.current = { ...instance.state };
+      });
+    }
+
+    if (hasWillUnmount) {
+      useEffect(() => {
+        return () => {
+          instance.componentWillUnmount();
+        };
+      }, []);
+    }
+
+    return instance.render();
+  };
+
+  Object.defineProperty(Wrapper, 'name', {
+    value: (ClassComp as any).displayName || ClassComp.name || 'ClassWrapper',
+  });
+
+  classWrapperCache.set(ClassComp, Wrapper);
+  return Wrapper;
+}
+
+// ---------------------------------------------------------------------------
+// Event Wrapping
+// ---------------------------------------------------------------------------
+
+export function createSyntheticEvent(nativeEvent: Event) {
+  let isPropagationStopped = false;
+  let isDefaultPrevented = false;
+
+  const syntheticEvent = {
+    nativeEvent,
+    currentTarget: nativeEvent.currentTarget,
+    target: nativeEvent.target,
+    bubbles: nativeEvent.bubbles,
+    cancelable: nativeEvent.cancelable,
+    defaultPrevented: nativeEvent.defaultPrevented,
+    eventPhase: nativeEvent.eventPhase,
+    isTrusted: nativeEvent.isTrusted,
+    preventDefault: () => {
+      isDefaultPrevented = true;
+      nativeEvent.preventDefault();
+    },
+    isDefaultPrevented: () => isDefaultPrevented,
+    stopPropagation: () => {
+      isPropagationStopped = true;
+      nativeEvent.stopPropagation();
+    },
+    isPropagationStopped: () => isPropagationStopped,
+    persist: () => {},
+    timeStamp: nativeEvent.timeStamp,
+    type: nativeEvent.type,
+  };
+
+  return new Proxy(syntheticEvent, {
+    get: (target, prop) => {
+      if (prop in target) return (target as any)[prop];
+      const val = (nativeEvent as any)[prop];
+      if (typeof val === 'function') return val.bind(nativeEvent);
+      return val;
+    }
+  });
+}
+
+const wrappedHandlerCache = new WeakMap<Function, Function>();
+
+export function getWrappedHandler(handler: Function) {
+  if (wrappedHandlerCache.has(handler)) return wrappedHandlerCache.get(handler);
+
+  const wrapped = (nativeEvent: Event) => {
+    if ((nativeEvent as any).nativeEvent && typeof (nativeEvent as any).isPropagationStopped === 'function') {
+      return handler(nativeEvent);
+    }
+    const synthetic = createSyntheticEvent(nativeEvent);
+    return handler(synthetic);
+  };
+  wrappedHandlerCache.set(handler, wrapped);
+  return wrapped;
+}
+
+function normalizeChildrenSingle(vnode: any): any {
+  if (!vnode || !vnode.props) return vnode;
+  const c = vnode.props.children;
+  if (Array.isArray(c) && c.length === 1) {
+    vnode.props.children = c[0];
+  }
+  return vnode;
+}
+
+export function createElement(type: unknown, props?: unknown, ...children: unknown[]): VNode {
+  const effectiveType = isClassComponent(type) ? wrapClassComponent(type as Function) : type;
+
+  if (typeof type === 'string' && props && typeof props === 'object') {
+    const newProps = { ...props } as Record<string, unknown>;
+    let hasChanges = false;
+    for (const key in newProps) {
+      if (key.startsWith('on') && typeof newProps[key] === 'function') {
+         newProps[key] = getWrappedHandler(newProps[key] as Function);
+         hasChanges = true;
+      }
+    }
+    if (hasChanges) {
+        return normalizeChildrenSingle(createElementImpl(effectiveType as any, newProps, ...(children as any[])));
+    }
+  }
+
+  return normalizeChildrenSingle(createElementImpl(effectiveType as any, props as any, ...(children as any[])));
+}
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export { Fragment, memo };
 export {
   createRef,
   registerExternalReactModule,
@@ -212,6 +493,10 @@ export const version = "19.0.0-refract-compat";
 const ReactCompat = {
   Children,
   Fragment,
+  Component,
+  PureComponent,
+  Suspense,
+  lazy,
   createContext,
   createElement,
   cloneElement,
@@ -242,4 +527,4 @@ const ReactCompat = {
   __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
 };
 
-export default ReactCompat;
+export default ReactCompat;

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/dom.ts

@@ -146,7 +146,19 @@ export function applyProps(
         break;
       default:
         if (key.startsWith("on")) {
-          const event = key.slice(2).toLowerCase();
+          let event = key.slice(2).toLowerCase();
+          if (reactCompatEventMode && event === "change") {
+            const tagName = el.tagName;
+            if (tagName === "TEXTAREA") {
+              event = "input";
+            } else if (tagName === "INPUT") {
+              const type = (el as HTMLInputElement).type;
+              if (type !== "checkbox" && type !== "radio" && type !== "file") {
+                event = "input";
+              }
+            }
+          }
+
           if (oldProps[key]) {
             el.removeEventListener(event, getEventListener(oldProps[key]));
           }

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)) {
@@ -257,12 +258,17 @@ export function useSyncExternalStore<T>(
   // snapshots (e.g. zustand selectors returning store actions) as updaters.
   const [snapshot, setSnapshot] = useState<T>(() => getSnapshot());
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     const handleStoreChange = () => {
       setSnapshot(() => getSnapshot());
     };
     const unsubscribe = subscribe(handleStoreChange);
-    handleStoreChange();
+    
+    // Check if snapshot changed between render and effect
+    if (getSnapshot() !== snapshot) {
+      handleStoreChange();
+    }
+
     return () => {
       unsubscribe();
     };

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/createElement.test.ts

@@ -14,8 +14,8 @@ describe("createElement", () => {
   it("creates an element with string children as text nodes", () => {
     const vnode = createElement("span", null, "hello");
     expect(vnode.props.children).toHaveLength(1);
-    expect(vnode.props.children![0].type).toBe("TEXT");
-    expect(vnode.props.children![0].props.nodeValue).toBe("hello");
+    expect((vnode.props.children as unknown as any[])[0].type).toBe("TEXT");
+    expect((vnode.props.children as unknown as any[])[0].props.nodeValue).toBe("hello");
   });
 
   it("creates nested elements", () => {
@@ -27,8 +27,8 @@ describe("createElement", () => {
     );
     expect(vnode.type).toBe("div");
     expect(vnode.props.children).toHaveLength(2);
-    expect(vnode.props.children![0].type).toBe("img");
-    expect(vnode.props.children![1].type).toBe("span");
+    expect((vnode.props.children as unknown as any[])[0].type).toBe("img");
+    expect((vnode.props.children as unknown as any[])[1].type).toBe("span");
   });
 
   it("flattens array children", () => {
@@ -44,7 +44,7 @@ describe("createElement", () => {
   it("filters out null, undefined, and boolean children", () => {
     const vnode = createElement("div", null, null, undefined, false, true, "text");
     expect(vnode.props.children).toHaveLength(1);
-    expect(vnode.props.children![0].type).toBe("TEXT");
+    expect((vnode.props.children as unknown as any[])[0].type).toBe("TEXT");
   });
 
   it("retains function type for components (deferred)", () => {
@@ -60,7 +60,7 @@ describe("createElement", () => {
   it("converts numbers to text nodes", () => {
     const vnode = createElement("span", null, 42);
     expect(vnode.props.children).toHaveLength(1);
-    expect(vnode.props.children![0].props.nodeValue).toBe("42");
+    expect((vnode.props.children as unknown as any[])[0].props.nodeValue).toBe("42");
   });
 
   it("extracts key from props", () => {

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);

package/tests/poc-compat.test.ts

@@ -0,0 +1,69 @@
+
+import { describe, test, expect, vi } from "vitest";
+import { render } from "../src/refract/render.js";
+import { createElement } from "../src/refract/createElement.js";
+import { useSyncExternalStore, useState } from "../src/refract/compat/react.js";
+import { setReactCompatEventMode } from "../src/refract/dom.js";
+
+// Enable compat mode
+setReactCompatEventMode(true);
+
+describe("POC Compatibility", () => {
+  test("useSyncExternalStore basic subscription", async () => {
+    let listeners: (() => void)[] = [];
+    const store = {
+      value: 0,
+      subscribe(l: () => void) {
+        listeners.push(l);
+        return () => {
+          listeners = listeners.filter(x => x !== l);
+        };
+      },
+      getSnapshot() {
+        return store.value;
+      },
+      increment() {
+        store.value++;
+        listeners.forEach(l => l());
+      }
+    };
+
+    function StoreComponent() {
+      const val = useSyncExternalStore(store.subscribe, store.getSnapshot);
+      return createElement("div", {}, `Value: ${val}`);
+    }
+
+    const container = document.createElement("div");
+    render(createElement(StoreComponent, null), container);
+
+    expect(container.textContent).toBe("Value: 0");
+
+    store.increment();
+    // Wait for microtasks/updates
+    await new Promise(r => setTimeout(r, 0));
+    
+    expect(container.textContent).toBe("Value: 1");
+  });
+
+  test("onChange maps to input for text inputs", async () => {
+    const handleChange = vi.fn();
+
+    function InputComponent() {
+      return createElement("input", { type: "text", onChange: handleChange });
+    }
+
+    const container = document.createElement("div");
+    render(createElement(InputComponent, null), container);
+
+    const input = container.querySelector("input");
+    expect(input).not.toBeNull();
+
+    // Simulate input event (which React treats as change)
+    const event = new Event("input", { bubbles: true });
+    input?.dispatchEvent(event);
+
+    // In standard DOM, onChange doesn't fire on input, but React compat should handle this?
+    // If not implemented, this will fail, confirming the need for the fix.
+    expect(handleChange).toHaveBeenCalled();
+  });
+});

package/tests/react-router-smoke.test.ts

@@ -38,7 +38,7 @@ describe("react-router-dom compatibility smoke", () => {
       ),
     );
     expect(tree.type).toBe(MemoryRouter);
-    expect((tree.props.children as unknown[]).length).toBe(1);
+    expect(React.Children.count(tree.props.children)).toBe(1);
   });
 
   it("supports hook dispatcher bridging for externally-resolved React", async () => {