@ipxjs/refract 0.3.1 → 0.4.1

package/README.md

@@ -3,7 +3,7 @@
 # Refract
 
 A minimal React-like virtual DOM library, written in TypeScript with split entrypoints
-so you can keep bundles small and targetetd.
+so you can keep bundles small and targeted.
 
 Refract implements the core ideas behind React in TypeScript
 - a virtual DOM
@@ -82,6 +82,44 @@ yarn test
 - `refract/full` -- complete API including hooks, context, memo, sanitizer defaults, and devtools integration
 - `refract` -- alias of `refract/full` for backward compatibility
 - Feature entrypoints for custom bundles: `refract/hooks`, `refract/context`, `refract/memo`, `refract/security`, `refract/devtools`
+- Optional React-compat entrypoints (opt-in): `refract/compat/react`, `refract/compat/react-dom`, `refract/compat/react-dom/client`, `refract/compat/react/jsx-runtime`, `refract/compat/react/jsx-dev-runtime`
+
+### React Ecosystem Compatibility (Opt-in)
+
+Refract now includes an opt-in compatibility layer so you can alias React imports
+for selected ecosystem libraries (for example MUI, `react-router-dom`, and
+`@dnd-kit`) without inflating the default `refract/core` path.
+
+Supported compat APIs include:
+- `forwardRef`, `cloneElement`, `Children`, `isValidElement`
+- `useLayoutEffect`, `useInsertionEffect`, `useId`
+- `useSyncExternalStore`, `useImperativeHandle`
+- `createPortal`
+- `createRoot`, `flushSync`, `unstable_batchedUpdates`
+- `jsx/jsxs/jsxDEV` runtime entrypoints
+- React hook dispatcher bridge internals (`__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE`) with optional `registerExternalReactModule(...)` for mixed-runtime environments (tests/Node)
+
+Example Vite aliases:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      react: "refract/compat/react",
+      "react-dom": "refract/compat/react-dom",
+      "react-dom/client": "refract/compat/react-dom/client",
+      "react/jsx-runtime": "refract/compat/react/jsx-runtime",
+      "react/jsx-dev-runtime": "refract/compat/react/jsx-dev-runtime",
+    },
+  },
+});
+```
+
+The compat layer is intentionally separate from core so users who do not need
+React ecosystem compatibility keep the smallest and fastest Refract bundles.
 
 ## API
 
@@ -181,20 +219,20 @@ The values below are from a local run on February 15, 2026.
 
 | Framework                  | JS bundle (raw) | JS bundle (gzip) |
 |---------------------------|----------------:|-----------------:|
-| Refract (`core`)          | 7.46 kB         | 2.93 kB          |
-| Refract (`core+hooks`)    | 8.75 kB         | 3.38 kB          |
-| Refract (`core+context`)  | 7.94 kB         | 3.15 kB          |
-| Refract (`core+memo`)     | 8.09 kB         | 3.15 kB          |
-| Refract (`core+security`) | 8.51 kB         | 3.29 kB          |
-| Refract (`refract`)       | 13.55 kB        | 5.04 kB          |
+| 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          |
 | 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 20.3x smaller than React,
-and the full `refract` entrypoint is about 11.8x smaller.
+From this snapshot, Refract `core` gzip JS is about 18.8x smaller than React,
+and the full `refract` entrypoint is about 11.1x smaller.
 
 ### Component Combination Benchmarks (Vitest)
 
@@ -204,13 +242,13 @@ Higher `hz` is better.
 
 | Component usage profile | Mount (hz) | Mount vs base | Reconcile (hz) | Reconcile vs base |
 |-------------------------|------------|---------------|----------------|-------------------|
-| `base` | 5209.15 | baseline | 4432.98 | baseline |
-| `memo` | 5924.46 | +13.7% | 5367.20 | +21.1% |
-| `context` | 3457.71 | -33.6% | 5243.29 | +18.3% |
-| `fragment` | 5189.17 | -0.4% | 3964.90 | -10.6% |
-| `keyed` | 6084.45 | +16.8% | 5037.30 | +13.6% |
-| `memo+context` | 6113.94 | +17.4% | 5347.56 | +20.6% |
-| `memo+context+keyed` | 6040.74 | +16.0% | 5088.81 | +14.8% |
+| `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% |
 
 In this run, `memo+context` was the fastest mount profile, while
 `memo` was the fastest reconcile profile.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ipxjs/refract",
-  "version": "0.3.1",
-  "description": "A minimal React-like virtual DOM library focused on image rendering",
+  "version": "0.4.1",
+  "description": "A minimal React-like virtual DOM library with an optional React compat layer",
   "type": "module",
   "main": "src/refract/index.ts",
   "exports": {
@@ -12,7 +12,12 @@
     "./context": "./src/refract/features/context.ts",
     "./memo": "./src/refract/memo.ts",
     "./security": "./src/refract/features/security.ts",
-    "./devtools": "./src/refract/devtools.ts"
+    "./devtools": "./src/refract/devtools.ts",
+    "./compat/react": "./src/refract/compat/react.ts",
+    "./compat/react-dom": "./src/refract/compat/react-dom.ts",
+    "./compat/react-dom/client": "./src/refract/compat/react-dom-client.ts",
+    "./compat/react/jsx-runtime": "./src/refract/compat/react-jsx-runtime.ts",
+    "./compat/react/jsx-dev-runtime": "./src/refract/compat/react-jsx-dev-runtime.ts"
   },
   "scripts": {
     "dev": "vite demo",
@@ -25,6 +30,9 @@
   "devDependencies": {
     "@types/jsdom": "^27.0.0",
     "jsdom": "^28.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router-dom": "^7.13.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.18"

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

@@ -0,0 +1,27 @@
+import { createElement, Fragment } from "../createElement.js";
+import { render } from "../render.js";
+import { setReactCompatEventMode } from "../dom.js";
+
+setReactCompatEventMode(true);
+
+export interface RefractCompatRoot {
+  render(children: unknown): void;
+  unmount(): void;
+}
+
+export function createRoot(container: HTMLElement): RefractCompatRoot {
+  return {
+    render(children: unknown): void {
+      render(children as Parameters<typeof render>[0], container);
+    },
+    unmount(): void {
+      render(createElement(Fragment, null), container);
+    },
+  };
+}
+
+export function hydrateRoot(container: HTMLElement, children: unknown): RefractCompatRoot {
+  const root = createRoot(container);
+  root.render(children);
+  return root;
+}

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

@@ -0,0 +1,42 @@
+import { createElement, Fragment } from "../createElement.js";
+import { flushPendingRenders } from "../coreRenderer.js";
+import { setReactCompatEventMode } from "../dom.js";
+import { createPortal as createPortalImpl } from "../portal.js";
+import type { PortalChild } from "../portal.js";
+import { render } from "../render.js";
+
+setReactCompatEventMode(true);
+
+export function createPortal(children: PortalChild, container: Node, key?: string | number | null): ReturnType<typeof createPortalImpl> {
+  return createPortalImpl(children, container, key);
+}
+
+export function unstable_batchedUpdates<T>(callback: () => T): T {
+  return callback();
+}
+
+export function flushSync<T>(callback: () => T): T {
+  const result = callback();
+  flushPendingRenders();
+  return result;
+}
+
+export function renderCompat(vnode: unknown, container: HTMLElement): void {
+  render(vnode as Parameters<typeof render>[0], container);
+}
+
+export function unmountComponentAtNode(container: HTMLElement): boolean {
+  render(createElement(Fragment, null), container);
+  return true;
+}
+
+const ReactDomCompat = {
+  createPortal,
+  flushSync,
+  render: renderCompat,
+  unstable_batchedUpdates,
+  unmountComponentAtNode,
+};
+
+export { renderCompat as render };
+export default ReactDomCompat;

package/src/refract/compat/react-jsx-dev-runtime.ts

@@ -0,0 +1,15 @@
+import { Fragment, jsx } from "./react-jsx-runtime.js";
+import type { VNodeType } from "../types.js";
+
+type JsxProps = Record<string, unknown> | null | undefined;
+
+export function jsxDEV(
+  type: VNodeType,
+  props: JsxProps,
+  key?: string,
+): ReturnType<typeof jsx> {
+  return jsx(type, props, key);
+}
+
+export { Fragment };
+

package/src/refract/compat/react-jsx-runtime.ts

@@ -0,0 +1,32 @@
+import { createElement, Fragment } from "../createElement.js";
+import type { VNode, VNodeType } from "../types.js";
+
+type JsxProps = Record<string, unknown> | null | undefined;
+type JsxChild = VNode | string | number | boolean | null | undefined | JsxChild[];
+
+function createJsxElement(type: VNodeType, rawProps: JsxProps, key?: string): ReturnType<typeof createElement> {
+  const props = { ...(rawProps ?? {}) };
+  if (key !== undefined) {
+    props.key = key;
+  }
+  const children = props.children as JsxChild | JsxChild[] | undefined;
+  delete props.children;
+
+  if (children === undefined) {
+    return createElement(type, props);
+  }
+  if (Array.isArray(children)) {
+    return createElement(type, props, ...(children as JsxChild[]));
+  }
+  return createElement(type, props, children as JsxChild);
+}
+
+export function jsx(type: VNodeType, props: JsxProps, key?: string): ReturnType<typeof createElement> {
+  return createJsxElement(type, props, key);
+}
+
+export function jsxs(type: VNodeType, props: JsxProps, key?: string): ReturnType<typeof createElement> {
+  return createJsxElement(type, props, key);
+}
+
+export { Fragment };

package/src/refract/compat/react.ts

@@ -0,0 +1,238 @@
+import { createElement, Fragment } from "../createElement.js";
+import { memo } from "../memo.js";
+import { createContext } from "../features/context.js";
+import {
+  createRef,
+} from "../features/hooks.js";
+import type { Component, 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,
+  ensureHookDispatcherRuntime,
+  registerExternalReactModule,
+  resolveDispatcher,
+} from "./sharedInternals.js";
+
+const REACT_ELEMENT_TYPE = Symbol.for("react.element");
+type ElementChild = VNode | string | number | boolean | null | undefined | ElementChild[];
+
+ensureHookDispatcherRuntime();
+
+function normalizeChildren(children: unknown): unknown[] {
+  if (children === undefined) return [];
+  return Array.isArray(children) ? children : [children];
+}
+
+function parseChildrenArgs(children: unknown[]): unknown {
+  if (children.length === 0) return undefined;
+  if (children.length === 1) return children[0];
+  return children;
+}
+
+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) => {
+    const { ref, ...rest } = props as Props & { ref?: { current: T | null } | ((value: T | null) => void) | null };
+    return render(rest as unknown as P, ref ?? null);
+  };
+  return ForwardRefComponent;
+}
+
+export function isValidElement(value: unknown): value is VNode {
+  return !!value
+    && typeof value === "object"
+    && "type" in (value as Record<string, unknown>)
+    && "props" in (value as Record<string, unknown>);
+}
+
+export function cloneElement(
+  element: VNode,
+  props?: Record<string, unknown> | null,
+  ...children: unknown[]
+): VNode {
+  const mergedProps: Record<string, unknown> = {
+    ...element.props,
+    ...(props ?? {}),
+  };
+
+  if (children.length > 0) {
+    mergedProps.children = normalizeChildren(parseChildrenArgs(children)) as VNode[];
+  }
+
+  if (props?.key !== undefined) {
+    mergedProps.key = props.key;
+  } else if (element.key != null) {
+    mergedProps.key = element.key;
+  }
+
+  const nextChildren = normalizeChildren(mergedProps.children);
+  delete mergedProps.children;
+
+  return createElement(element.type, mergedProps, ...(nextChildren as ElementChild[]));
+}
+
+function childrenToArray(children: unknown): unknown[] {
+  if (children === undefined || children === null) return [];
+  if (!Array.isArray(children)) return [children];
+  const out: unknown[] = [];
+  const stack = [...children];
+  while (stack.length > 0) {
+    const child = stack.shift();
+    if (Array.isArray(child)) {
+      stack.unshift(...child);
+      continue;
+    }
+    if (child === undefined || child === null || typeof child === "boolean") {
+      continue;
+    }
+    out.push(child);
+  }
+  return out;
+}
+
+export const Children = {
+  map<T>(children: unknown, fn: (child: unknown, index: number) => T): T[] {
+    return childrenToArray(children).map(fn);
+  },
+  forEach(children: unknown, fn: (child: unknown, index: number) => void): void {
+    childrenToArray(children).forEach(fn);
+  },
+  count(children: unknown): number {
+    return childrenToArray(children).length;
+  },
+  toArray(children: unknown): unknown[] {
+    return childrenToArray(children);
+  },
+  only(children: unknown): unknown {
+    const array = childrenToArray(children);
+    if (array.length !== 1) {
+      throw new Error("React.Children.only expected to receive a single React element child.");
+    }
+    return array[0];
+  },
+};
+
+export function useState<T>(initial: T | (() => T)): [T, (value: T | ((prev: T) => T)) => void] {
+  return resolveDispatcher().useState(initial);
+}
+
+export function useEffect(effect: () => void | (() => void), deps?: unknown[]): void {
+  return resolveDispatcher().useEffect(effect, deps);
+}
+
+export function useLayoutEffect(effect: () => void | (() => void), deps?: unknown[]): void {
+  return resolveDispatcher().useLayoutEffect(effect, deps);
+}
+
+export function useInsertionEffect(effect: () => void | (() => void), deps?: unknown[]): void {
+  return resolveDispatcher().useInsertionEffect(effect, deps);
+}
+
+export function useRef<T>(initial: T): { current: T } {
+  return resolveDispatcher().useRef(initial);
+}
+
+export function useMemo<T>(factory: () => T, deps: unknown[]): T {
+  return resolveDispatcher().useMemo(factory, deps);
+}
+
+export function useCallback<T extends Function>(cb: T, deps: unknown[]): T {
+  return resolveDispatcher().useCallback(cb, deps) as T;
+}
+
+export function useReducer<S, A, I = S>(
+  reducer: (state: S, action: A) => S,
+  initialArg: I,
+  init?: (arg: I) => S,
+): [S, (action: A) => void] {
+  if (init) {
+    return resolveDispatcher().useReducer(reducer, initialArg, init) as [S, (action: A) => void];
+  }
+  return resolveDispatcher().useReducer(reducer, initialArg as unknown as S) as [S, (action: A) => void];
+}
+
+export function useSyncExternalStore<T>(
+  subscribe: (onStoreChange: () => void) => () => void,
+  getSnapshot: () => T,
+  getServerSnapshot?: () => T,
+): T {
+  return resolveDispatcher().useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+export function useImperativeHandle<T>(
+  ref: { current: T | null } | ((value: T | null) => void) | null | undefined,
+  create: () => T,
+  deps?: unknown[],
+): void {
+  return resolveDispatcher().useImperativeHandle(ref, create, deps);
+}
+
+export function useDebugValue(value: unknown): void {
+  return resolveDispatcher().useDebugValue(value);
+}
+
+export function useContext<T>(context: unknown): T {
+  return resolveDispatcher().useContext(context as never) as T;
+}
+
+export function useId(): string {
+  return resolveDispatcher().useId();
+}
+
+export function startTransition(callback: () => void): void {
+  callback();
+}
+
+export function useTransition(): [boolean, (callback: () => void) => void] {
+  return resolveDispatcher().useTransition();
+}
+
+export function useDeferredValue<T>(value: T, initialValue?: T): T {
+  return resolveDispatcher().useDeferredValue(value, initialValue);
+}
+
+export { createElement, Fragment, createContext, memo };
+export {
+  createRef,
+  registerExternalReactModule,
+  __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+  __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+};
+
+export const version = "19.0.0-refract-compat";
+
+const ReactCompat = {
+  Children,
+  Fragment,
+  createContext,
+  createElement,
+  cloneElement,
+  createRef,
+  forwardRef,
+  isValidElement,
+  memo,
+  registerExternalReactModule,
+  startTransition,
+  useCallback,
+  useContext,
+  useDebugValue,
+  useDeferredValue,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useInsertionEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  useTransition,
+  version,
+  $$typeof: REACT_ELEMENT_TYPE,
+  __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+  __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+};
+
+export default ReactCompat;