@ipxjs/refract 0.4.1 → 0.5.1

package/README.md

@@ -215,24 +215,24 @@ image requests blocked.
 
 ### Bundle Size Snapshot
 
-The values below are from a local run on February 15, 2026.
+The values below are from a local run on February 16, 2026.
 
 | Framework                  | JS bundle (raw) | JS bundle (gzip) |
 |---------------------------|----------------:|-----------------:|
-| Refract (`core`)          | 8.36 kB         | 3.16 kB          |
-| Refract (`core+hooks`)    | 9.76 kB         | 3.65 kB          |
-| Refract (`core+context`)  | 8.85 kB         | 3.38 kB          |
-| Refract (`core+memo`)     | 9.03 kB         | 3.39 kB          |
-| Refract (`core+security`) | 9.27 kB         | 3.46 kB          |
-| Refract (`refract`)       | 14.64 kB        | 5.34 kB          |
+| Refract (`core`)          | 8.62 kB         | 3.24 kB          |
+| Refract (`core+hooks`)    | 10.28 kB        | 3.85 kB          |
+| Refract (`core+context`)  | 9.12 kB         | 3.47 kB          |
+| Refract (`core+memo`)     | 9.29 kB         | 3.48 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          |
 
 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.
 
-From this snapshot, Refract `core` gzip JS is about 18.8x smaller than React,
-and the full `refract` entrypoint is about 11.1x smaller.
+From this snapshot, Refract `core` gzip JS is about 18.4x smaller than React,
+and the full `refract` entrypoint is about 10.7x smaller.
 
 ### Component Combination Benchmarks (Vitest)
 
@@ -242,16 +242,16 @@ Higher `hz` is better.
 
 | Component usage profile | Mount (hz) | Mount vs base | Reconcile (hz) | Reconcile vs base |
 |-------------------------|------------|---------------|----------------|-------------------|
-| `base` | 5068.40 | baseline | 4144.37 | baseline |
-| `memo` | 5883.23 | +16.1% | 5154.56 | +24.4% |
-| `context` | 3521.54 | -30.5% | 5063.92 | +22.2% |
-| `fragment` | 4880.23 | -3.7% | 4079.08 | -1.6% |
-| `keyed` | 5763.70 | +13.7% | 4844.23 | +16.9% |
-| `memo+context` | 6173.01 | +21.8% | 5144.98 | +24.1% |
-| `memo+context+keyed` | 5606.73 | +10.6% | 4732.23 | +14.2% |
+| `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% |
 
-In this run, `memo+context` was the fastest mount profile, while
-`memo` was the fastest reconcile profile.
+In this run, `keyed` was the fastest mount profile, while
+`memo+context` was the fastest reconcile profile.
 
 ### Running the Benchmark
 
@@ -301,24 +301,27 @@ How Refract compares to React and Preact:
 | **Hooks**                      |         |       |        |
 | useState                       | Yes     | Yes   | Yes    |
 | useEffect                      | Yes     | Yes   | Yes    |
-| useLayoutEffect                | No      | Yes   | Yes    |
+| useLayoutEffect                | Yes     | Yes   | Yes    |
+| useInsertionEffect             | Yes     | Yes   | Yes    |
 | useRef                         | Yes     | Yes   | Yes    |
 | useMemo / useCallback          | Yes     | Yes   | Yes    |
 | useReducer                     | Yes     | Yes   | Yes    |
 | useContext                     | Yes     | Yes   | Yes    |
-| useId                          | No      | Yes   | Yes    |
-| useTransition / useDeferredValue | No    | Yes   | No     |
+| useId                          | Yes     | Yes   | Yes    |
+| useSyncExternalStore           | Yes     | Yes   | Yes    |
+| useImperativeHandle            | Yes     | Yes   | Yes    |
+| useTransition / useDeferredValue | Partial⁵ | Yes | Partial⁷ |
 | **State & Data Flow**          |         |       |        |
 | Built-in state management      | Yes     | Yes   | Yes    |
 | Context API                    | Yes     | Yes   | Yes    |
 | Refs (createRef / ref prop)    | Yes     | Yes   | Yes    |
-| forwardRef                     | No      | Yes   | Yes    |
+| forwardRef                     | Yes⁶    | Yes   | Yes    |
 | **Rendering**                  |         |       |        |
 | Event handling                 | Yes     | Yes   | Yes    |
 | Style objects                  | Yes     | Yes   | Yes    |
 | className prop                 | Yes     | Yes   | Yes¹   |
 | dangerouslySetInnerHTML        | Yes     | Yes   | Yes    |
-| Portals                        | No      | Yes   | Yes    |
+| Portals                        | Yes     | Yes   | Yes    |
 | Suspense / lazy                | No      | Yes   | Yes²   |
 | Error boundaries               | Yes³    | Yes   | Yes    |
 | Server-side rendering          | No      | Yes   | Yes    |
@@ -333,13 +336,16 @@ How Refract compares to React and Preact:
 | memo / PureComponent           | Yes     | Yes   | Yes    |
 | **Ecosystem**                  |         |       |        |
 | DevTools                       | Basic (hook API) | Yes   | Yes    |
-| React compatibility layer      | N/A     | N/A   | Yes    |
-| **Bundle Size (gzip, JS)**     | ~2.9-5.0 kB⁴ | ~59.5 kB | ~6.0 kB |
+| React compatibility layer      | Yes⁶    | N/A   | Yes⁷   |
+| **Bundle Size (gzip, JS)**     | ~3.2-5.6 kB⁴ | ~59.5 kB | ~6.0 kB |
 
 ¹ Preact supports both `class` and `className`.
 ² Preact has partial Suspense support via `preact/compat`.
 ³ Refract uses the `useErrorBoundary` hook rather than class-based error boundaries.
 ⁴ Refract size depends on entrypoint (`refract/core` vs `refract` full).
+⁵ Refract exposes `useTransition` / `useDeferredValue` but currently runs both synchronously (no concurrent scheduling).
+⁶ Available via opt-in compat entrypoints (`refract/compat/react*`).
+⁷ Preact compatibility is provided through `preact/compat`.
 
 ## License
 

package/package.json

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

@@ -4,6 +4,19 @@ import type { VNode, VNodeType } from "../types.js";
 type JsxProps = Record<string, unknown> | null | undefined;
 type JsxChild = VNode | string | number | boolean | null | undefined | JsxChild[];
 
+// React compat: normalize props.children on the returned VNode so that
+// a single child is stored directly (not in an array).  Libraries like
+// MUI access `props.children.props` expecting a single React element.
+// Refract's core createElement always stores children as an array, but
+// the renderer's normalizeChildrenProp handles both formats, so this is safe.
+function normalizeVNodeChildren(vnode: VNode): VNode {
+  const c = vnode.props.children;
+  if (Array.isArray(c) && c.length === 1) {
+    vnode.props.children = c[0];
+  }
+  return vnode;
+}
+
 function createJsxElement(type: VNodeType, rawProps: JsxProps, key?: string): ReturnType<typeof createElement> {
   const props = { ...(rawProps ?? {}) };
   if (key !== undefined) {
@@ -12,13 +25,15 @@ function createJsxElement(type: VNodeType, rawProps: JsxProps, key?: string): Re
   const children = props.children as JsxChild | JsxChild[] | undefined;
   delete props.children;
 
+  let vnode: VNode;
   if (children === undefined) {
-    return createElement(type, props);
-  }
-  if (Array.isArray(children)) {
-    return createElement(type, props, ...(children as JsxChild[]));
+    vnode = createElement(type, props);
+  } else if (Array.isArray(children)) {
+    vnode = createElement(type, props, ...(children as JsxChild[]));
+  } else {
+    vnode = createElement(type, props, children as JsxChild);
   }
-  return createElement(type, props, children as JsxChild);
+  return normalizeVNodeChildren(vnode);
 }
 
 export function jsx(type: VNodeType, props: JsxProps, key?: string): ReturnType<typeof createElement> {

package/src/refract/compat/react.ts

@@ -36,6 +36,7 @@ export function forwardRef<T, P extends Record<string, unknown> = Record<string,
     const { ref, ...rest } = props as Props & { ref?: { current: T | null } | ((value: T | null) => void) | null };
     return render(rest as unknown as P, ref ?? null);
   };
+  (ForwardRefComponent as any).displayName = `ForwardRef(${(render as any).name || 'anonymous'})`;
   return ForwardRefComponent;
 }
 
@@ -69,7 +70,13 @@ export function cloneElement(
   const nextChildren = normalizeChildren(mergedProps.children);
   delete mergedProps.children;
 
-  return createElement(element.type, mergedProps, ...(nextChildren as ElementChild[]));
+  const vnode = createElement(element.type, mergedProps, ...(nextChildren as ElementChild[]));
+  // React compat: single child should not be wrapped in array
+  const c = vnode.props.children;
+  if (Array.isArray(c) && c.length === 1) {
+    vnode.props.children = c[0];
+  }
+  return vnode;
 }
 
 function childrenToArray(children: unknown): unknown[] {

package/src/refract/coreRenderer.ts

@@ -17,6 +17,9 @@ import {
 /** Module globals for hook system */
 export let currentFiber: Fiber | null = null;
 
+/** True while performWork() is executing (render phase) */
+export let isRendering = false;
+
 /** Store root fiber per container */
 const roots = new WeakMap<Node, Fiber>();
 let deletions: Fiber[] = [];
@@ -43,7 +46,9 @@ export function renderFiber(vnode: VNode, container: Node): void {
     flags: UPDATE,
   };
   deletions = [];
+  isRendering = true;
   performWork(rootFiber);
+  isRendering = false;
   const committedDeletions = deletions.slice();
   commitRoot(rootFiber);
   runAfterCommitHandlers();
@@ -51,15 +56,16 @@ export function renderFiber(vnode: VNode, container: Node): void {
   runCommitHandlers(rootFiber, committedDeletions);
 }
 
-/** Depth-first work loop: call components, diff children */
-function performWork(fiber: Fiber): void {
+/** Process a single fiber: call component, diff children.
+ *  Returns true if bailed out (children should be skipped). */
+function processWorkUnit(fiber: Fiber): boolean {
   const isComponent = typeof fiber.type === "function";
   const isFragment = fiber.type === Fragment;
   const isPortal = fiber.type === Portal;
 
   if (isComponent) {
     if (fiber.alternate && fiber.flags === UPDATE && shouldBailoutComponent(fiber)) {
-      return advanceWork(fiber);
+      return true;
     }
 
     currentFiber = fiber;
@@ -95,13 +101,35 @@ function performWork(fiber: Fiber): void {
     }
   }
 
-  // Traverse: child first, then sibling, then uncle
-  if (fiber.child) {
-    performWork(fiber.child);
-    return;
-  }
+  return false;
+}
+
+/** Iterative depth-first work loop (avoids stack overflow on deep trees) */
+function performWork(rootFiber: Fiber): void {
+  let fiber: Fiber | null = rootFiber;
+
+  while (fiber) {
+    const bailedOut = processWorkUnit(fiber);
+
+    // Descend to child unless bailed out
+    if (!bailedOut && fiber.child) {
+      fiber = fiber.child;
+      continue;
+    }
 
-  advanceWork(fiber);
+    // No child or bailed out — walk up to find next sibling
+    if (fiber === rootFiber) break;
+    while (fiber) {
+      if (fiber.sibling) {
+        fiber = fiber.sibling;
+        break;
+      }
+      fiber = fiber.parent;
+      if (!fiber || fiber === rootFiber) {
+        fiber = null;
+      }
+    }
+  }
 }
 
 type RenderedChild = VNode | string | number | boolean | null | undefined | RenderedChild[];
@@ -139,17 +167,6 @@ function isPortalFiber(fiber: Fiber): boolean {
   return fiber.type === Portal;
 }
 
-function advanceWork(fiber: Fiber): void {
-  let next: Fiber | null = fiber;
-  while (next) {
-    if (next.sibling) {
-      performWork(next.sibling);
-      return;
-    }
-    next = next.parent;
-  }
-}
-
 /** Find the next DOM sibling for insertion (skips siblings being placed/moved) */
 function getNextDomSibling(fiber: Fiber): Node | null {
   let sib: Fiber | null = fiber.sibling;
@@ -266,9 +283,15 @@ function commitWork(fiber: Fiber): void {
     }
   }
 
-  // Handle ref prop
+  // Handle ref prop — only on mount or when ref changes (like React)
   if (fiber.dom && fiber.props.ref) {
-    setRef(fiber.props.ref, fiber.dom);
+    const oldRef = fiber.alternate?.props.ref;
+    if (fiber.flags & PLACEMENT || fiber.props.ref !== oldRef) {
+      if (oldRef && oldRef !== fiber.props.ref) {
+        setRef(oldRef, null);
+      }
+      setRef(fiber.props.ref, fiber.dom);
+    }
   }
 
   fiber.flags = 0;
@@ -331,12 +354,29 @@ export function scheduleRender(fiber: Fiber): void {
   }
 }
 
+const MAX_NESTED_RENDERS = 50;
+const renderCounts = new Map<Node, number>();
+
 function flushRenders(): void {
   flushScheduled = false;
-  for (const container of pendingContainers) {
+  // 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.",
+      );
+    }
+    renderCounts.set(container, count);
+
     const newRoot: Fiber = {
       type: currentRoot.type,
       props: currentRoot.props,
@@ -351,14 +391,20 @@ function flushRenders(): void {
       flags: UPDATE,
     };
     deletions = [];
+    isRendering = true;
     performWork(newRoot);
+    isRendering = false;
     const committedDeletions = deletions.slice();
     commitRoot(newRoot);
     runAfterCommitHandlers();
     roots.set(container, newRoot);
     runCommitHandlers(newRoot, committedDeletions);
   }
-  pendingContainers.clear();
+
+  // Reset counters when no more pending renders (loop resolved)
+  if (pendingContainers.size === 0) {
+    renderCounts.clear();
+  }
 }
 
 export function flushPendingRenders(): void {

package/src/refract/dom.ts

@@ -120,7 +120,11 @@ export function applyProps(
         break;
       }
       case "className":
-        el.setAttribute("class", newProps[key] as string);
+        if (newProps[key] == null || newProps[key] === false) {
+          el.removeAttribute("class");
+        } else {
+          el.setAttribute("class", String(newProps[key]));
+        }
         break;
       case "style":
         if (typeof newProps[key] === "object" && newProps[key] !== null) {
@@ -148,11 +152,18 @@ export function applyProps(
           }
           el.addEventListener(event, getEventListener(newProps[key]));
         } else {
-          if (unsafeUrlPropChecker(key, newProps[key])) {
+          const value = newProps[key];
+          if (unsafeUrlPropChecker(key, value)) {
             el.removeAttribute(key);
             continue;
           }
-          el.setAttribute(key, String(newProps[key]));
+          if (value == null || value === false) {
+            el.removeAttribute(key);
+          } else if (value === true) {
+            el.setAttribute(key, "true");
+          } else {
+            el.setAttribute(key, String(value));
+          }
         }
         break;
     }

package/src/refract/features/context.ts

@@ -20,7 +20,11 @@ export function createContext<T>(defaultValue: T): Context<T> {
     fiber._contexts.set(id, props.value);
 
     const children = props.children ?? [];
-    return children.length === 1 ? children[0] : createElement(Fragment, null, ...children);
+    if (Array.isArray(children)) {
+      return children.length === 1 ? children[0] : createElement(Fragment, null, ...children);
+    }
+    // Single child (React compat: children may be a VNode, not an array)
+    return children;
   };
 
   return { Provider, _id: id, _defaultValue: defaultValue };

package/src/refract/features/hooks.ts

@@ -33,15 +33,21 @@ export function useState<T>(initial: T | (() => T)): [T, (value: T | ((prev: T)
   }
   hook.queue = [];
 
-  const setState = (value: T | ((prev: T) => T)) => {
-    const action = typeof value === "function"
-      ? value as (prev: T) => T
-      : () => value;
-    (hook.queue as ((prev: T) => T)[]).push(action);
-    scheduleRender(fiber);
-  };
+  // Create a stable setter that is reused across renders (like React)
+  if (!hook._setter) {
+    hook._setter = (value: T | ((prev: T) => T)) => {
+      const action = typeof value === "function"
+        ? value as (prev: T) => T
+        : () => value;
+      (hook.queue as ((prev: T) => T)[]).push(action);
+      scheduleRender(hook._fiber!);
+    };
+  }
+  // Update fiber reference each render so the setter always schedules
+  // against the current fiber (fibers are recreated on re-render)
+  hook._fiber = fiber;
 
-  return [hook.state as T, setState];
+  return [hook.state as T, hook._setter as (value: T | ((prev: T) => T)) => void];
 }
 
 type EffectCleanup = void | (() => void);
@@ -162,15 +168,33 @@ export function useReducer<S, A, I>(
   initialArg: S | I,
   init?: (arg: I) => S,
 ): [S, (action: A) => void] {
-  const [state, setState] = useState<S>(() => (
-    init
-      ? init(initialArg as I)
-      : initialArg as S
-  ));
-  const dispatch = (action: A) => {
-    setState((prev) => reducer(prev, action));
-  };
-  return [state, dispatch];
+  const hook = getHook();
+  const fiber = currentFiber!;
+
+  if (hook.queue === undefined) {
+    hook.state = init ? init(initialArg as I) : initialArg as S;
+    hook.queue = [];
+  }
+
+  // Process queued actions
+  for (const action of hook.queue as A[]) {
+    hook.state = reducer(hook.state as S, action);
+  }
+  hook.queue = [];
+
+  // Store current reducer ref (may change between renders)
+  hook._reducer = reducer;
+
+  // Create stable dispatch (like React)
+  if (!hook._dispatch) {
+    hook._dispatch = (action: A) => {
+      (hook.queue as A[]).push(action);
+      scheduleRender(hook._fiber!);
+    };
+  }
+  hook._fiber = fiber;
+
+  return [hook.state as S, hook._dispatch as (action: A) => void];
 }
 
 export function createRef<T = unknown>(): { current: T | null } {
@@ -229,11 +253,13 @@ export function useSyncExternalStore<T>(
   getSnapshot: () => T,
   _getServerSnapshot?: () => T,
 ): T {
-  const [snapshot, setSnapshot] = useState<T>(getSnapshot());
+  // Wrap in arrow functions to prevent useState from treating function-valued
+  // snapshots (e.g. zustand selectors returning store actions) as updaters.
+  const [snapshot, setSnapshot] = useState<T>(() => getSnapshot());
 
   useEffect(() => {
     const handleStoreChange = () => {
-      setSnapshot(getSnapshot());
+      setSnapshot(() => getSnapshot());
     };
     const unsubscribe = subscribe(handleStoreChange);
     handleStoreChange();

package/src/refract/types.ts

@@ -7,7 +7,7 @@ export type VNodeType = string | symbol | Component;
 /** Props passed to elements and components */
 export interface Props {
   [key: string]: unknown;
-  children?: VNode[];
+  children?: VNode[] | VNode;
   key?: string | number;
 }
 
@@ -27,6 +27,10 @@ export const DELETION = 4;
 export interface Hook {
   state: unknown;
   queue?: unknown[];
+  _setter?: Function;
+  _dispatch?: Function;
+  _reducer?: Function;
+  _fiber?: Fiber;
 }
 
 /** Internal fiber node — represents a mounted VNode */