@ipxjs/refract 0.11.0 → 0.12.0

package/README.md

@@ -1,6 +1,8 @@
 ![](assets/lens-syntax-refract.svg "=x200")
 
-# Refract
+[Info](https://refract.ipx.dev) | [Docs](https://refract.ipx.dev/docs)
+
+# Refract 
 
 A minimal React-like virtual DOM library, written in TypeScript with split entrypoints
 so you can keep bundles small and targeted.
@@ -94,9 +96,13 @@ Supported compat APIs include:
 - `forwardRef`, `cloneElement`, `Children`, `isValidElement`
 - `useLayoutEffect`, `useInsertionEffect`, `useId`
 - `useSyncExternalStore`, `useImperativeHandle`
+- `use` — suspends on Promise (with a `promiseCache` WeakMap) or reads a context object
+- `Suspense` — renders a fallback subtree while a child suspends
 - `createPortal`
 - `createRoot`, `flushSync`, `unstable_batchedUpdates`
+- `findDOMNode` stub (returns `null`; prevents crashes from libraries like `react-transition-group` v4)
 - `jsx/jsxs/jsxDEV` runtime entrypoints
+- `$$typeof` stamped on every VNode (`Symbol.for("react.element")`) so `react-is` helpers work
 - 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:
@@ -121,10 +127,10 @@ 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
+Compatibility status (last verified February 22, 2026):
+- `yarn test`: 14 files passed, 91 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
+- Verified behaviors include `forwardRef`, portals, `createRoot`, JSX runtimes, `useSyncExternalStore`, `flushSync`, react-router tree construction/dispatcher bridging, `React.use` (Promise + context), and Suspense boundary fallback rendering
 
 ## API
 
@@ -318,6 +324,7 @@ How Refract compares to React and Preact:
 | useId                          | Yes     | Yes   | Yes    |
 | useSyncExternalStore           | Yes     | Yes   | Yes    |
 | useImperativeHandle            | Yes     | Yes   | Yes    |
+| use                            | Yes⁶    | Yes   | No     |
 | useTransition / useDeferredValue | Partial⁵ | Yes | Partial⁷ |
 | **State & Data Flow**          |         |       |        |
 | Built-in state management      | Yes     | Yes   | Yes    |
@@ -330,7 +337,7 @@ How Refract compares to React and Preact:
 | className prop                 | Yes     | Yes   | Yes¹   |
 | dangerouslySetInnerHTML        | Yes     | Yes   | Yes    |
 | Portals                        | Yes     | Yes   | Yes    |
-| Suspense / lazy                | No⁸     | Yes   | Yes²   |
+| Suspense / lazy                | Partial⁸ | Yes  | Yes²   |
 | Error boundaries               | Yes³    | Yes   | Yes    |
 | Server-side rendering          | No      | Yes   | Yes    |
 | Hydration                      | No⁹     | Yes   | Yes    |
@@ -354,7 +361,7 @@ How Refract compares to React and Preact:
 ⁵ Refract exposes `useTransition` / `useDeferredValue` but currently runs both synchronously (no concurrent scheduling).
 ⁶ Available via opt-in compat entrypoints (`refract/compat/react*`) with partial React API parity.
 ⁷ Preact compatibility is provided through `preact/compat`.
-⁸ Compat exports `Suspense`/`lazy`, but full suspension/fallback semantics are not implemented.
+⁸ Compat `Suspense` renders a fallback while a child suspends (via `React.use` + `useState` boundary). `lazy` is exported but code-splitting semantics are limited.
 ⁹ `hydrateRoot` is exposed in compat, but currently performs client render rather than true SSR hydration.
 ¹⁰ `memo` is supported; `PureComponent` is compat-oriented and does not guarantee full React shallow-compare behavior.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipxjs/refract",
-  "version": "0.11.0",
+  "version": "0.12.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

@@ -16,6 +16,14 @@ export function unstable_batchedUpdates<T>(callback: () => T): T {
   return callback();
 }
 
+// findDOMNode was removed in React 19. react-transition-group v4 calls it
+// when no nodeRef prop is provided. Returning null avoids a hard crash; any
+// guarded usage (if node) degrades gracefully while unguarded usage (e.g.
+// CSSTransition without nodeRef) will silently skip the animation.
+export function findDOMNode(_instance: unknown): Element | null {
+  return null;
+}
+
 export function flushSync<T>(callback: () => T): T {
   const result = callback();
   flushPendingRenders();
@@ -34,6 +42,7 @@ export function unmountComponentAtNode(container: HTMLElement): boolean {
 
 const ReactDomCompat = {
   createPortal,
+  findDOMNode,
   flushSync,
   render: renderCompat,
   unstable_batchedUpdates,

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

@@ -2,6 +2,8 @@ import { createElement, Fragment } from "../createElement.js";
 import type { VNode, VNodeType } from "../types.js";
 import { resolveCompatType, getWrappedHandler } from "./react.js";
 
+const REACT_ELEMENT_TYPE = Symbol.for("react.element");
+
 type JsxProps = Record<string, unknown> | null | undefined;
 type JsxChild = VNode | string | number | boolean | null | undefined | JsxChild[];
 
@@ -45,6 +47,7 @@ function createJsxElement(type: VNodeType, rawProps: JsxProps, key?: string): Re
   } else {
     vnode = createElement(effectiveType as VNodeType, props, children as JsxChild);
   }
+  (vnode as any).$$typeof = REACT_ELEMENT_TYPE;
   return normalizeVNodeChildren(vnode);
 }
 

package/src/refract/compat/react.ts

@@ -1,10 +1,11 @@
-import { createElement as createElementImpl, Fragment } from "../createElement.js";
+import { createElement as createElementImpl, Fragment as InternalFragment } from "../createElement.js";
 import { memo } from "../memo.js";
 import { createContext as createContextImpl, setContextValue } from "../features/context.js";
 import {
   createRef,
   useErrorBoundary,
 } from "../features/hooks.js";
+import { currentFiber } from "../coreRenderer.js";
 import type { Component as RefractComponent, Props, VNode } from "../types.js";
 import {
   __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
@@ -41,6 +42,9 @@ export function forwardRef<T, P extends Record<string, unknown> = Record<string,
     return render(rest as unknown as P, ref ?? null);
   };
   (ForwardRefComponent as any).displayName = `ForwardRef(${(render as any).name || 'anonymous'})`;
+  // Stamp $$typeof so react-is.isForwardRef(element) works when this component
+  // is used as the VNode type.
+  (ForwardRefComponent as any).$$typeof = REACT_FORWARD_REF_TYPE;
   return ForwardRefComponent;
 }
 
@@ -269,7 +273,54 @@ PureComponent.prototype.isPureReactComponent = true;
 // Suspense / Lazy
 // ---------------------------------------------------------------------------
 
+// Cache for promises passed to use() — maps a Promise to its settled result
+// so subsequent renders can return the value instead of throwing again.
+type PromiseResult<T> =
+  | { status: 'pending' }
+  | { status: 'fulfilled'; value: T }
+  | { status: 'rejected'; reason: unknown };
+
+const promiseCache = new WeakMap<Promise<unknown>, PromiseResult<unknown>>();
+
+export function use<T>(value: Promise<T> | unknown): T {
+  if (value instanceof Promise) {
+    let result = promiseCache.get(value as Promise<unknown>) as PromiseResult<T> | undefined;
+    if (!result) {
+      result = { status: 'pending' };
+      promiseCache.set(value as Promise<unknown>, result as PromiseResult<unknown>);
+      (value as Promise<T>).then(
+        (v) => { (result as any).status = 'fulfilled'; (result as any).value = v; },
+        (e) => { (result as any).status = 'rejected'; (result as any).reason = e; },
+      );
+    }
+    if (result.status === 'fulfilled') return (result as { status: 'fulfilled'; value: T }).value;
+    if (result.status === 'rejected') throw (result as { status: 'rejected'; reason: unknown }).reason;
+    throw value; // pending — triggers Suspense boundary
+  }
+  // Treat non-Promise values as context objects (React 19 use(Context) pattern).
+  return useContext(value as unknown) as T;
+}
+
+// Suspense is a real component so it can use useState to toggle between the
+// fallback and live children, and so the renderer can attach a
+// _suspenseHandler to its fiber for thrown-promise recovery.
 export function Suspense(props: { children?: unknown; fallback?: unknown }): unknown {
+  const [suspended, setSuspended] = useState(false);
+
+  // Register the promise handler on this render's fiber so that any
+  // descendant that throws a Promise can find and invoke it.
+  const fiber = currentFiber;
+  if (fiber) {
+    fiber._suspenseHandler = (promise: Promise<unknown>) => {
+      setSuspended(true);
+      promise.then(
+        () => setSuspended(false),
+        () => setSuspended(false),
+      );
+    };
+  }
+
+  if (suspended) return props.fallback ?? null;
   return props.children ?? null;
 }
 
@@ -421,6 +472,8 @@ export function resolveCompatType(type: unknown): unknown {
     };
     (wrappedForwardRef as any).displayName = exoticType.displayName
       ?? `ForwardRef(${(render as any).name || "anonymous"})`;
+    // Preserve $$typeof on the wrapper so react-is.isForwardRef(element) works.
+    (wrappedForwardRef as any).$$typeof = REACT_FORWARD_REF_TYPE;
     exoticTypeCache.set(type as object, wrappedForwardRef);
     return wrappedForwardRef;
   }
@@ -451,7 +504,7 @@ export function resolveCompatType(type: unknown): unknown {
       if (Array.isArray(children)) {
         return children.length === 1
           ? children[0] as VNode
-          : createElementImpl(Fragment, null, ...(children as ElementChild[]));
+          : createElementImpl(InternalFragment, null, ...(children as ElementChild[]));
       }
       return children as VNode;
     };
@@ -533,6 +586,7 @@ function normalizeChildrenSingle(vnode: any): any {
 export function createElement(type: unknown, props?: unknown, ...children: unknown[]): VNode {
   const effectiveType = resolveCompatType(type);
 
+  let vnode: VNode;
   if (typeof type === 'string' && props && typeof props === 'object') {
     const newProps = { ...props } as Record<string, unknown>;
     let hasChanges = false;
@@ -543,18 +597,29 @@ export function createElement(type: unknown, props?: unknown, ...children: unkno
       }
     }
     if (hasChanges) {
-        return normalizeChildrenSingle(createElementImpl(effectiveType as any, newProps, ...(children as any[])));
+      vnode = normalizeChildrenSingle(createElementImpl(effectiveType as any, newProps, ...(children as any[])));
+    } else {
+      vnode = normalizeChildrenSingle(createElementImpl(effectiveType as any, props as any, ...(children as any[])));
     }
+  } else {
+    vnode = normalizeChildrenSingle(createElementImpl(effectiveType as any, props as any, ...(children as any[])));
   }
 
-  return normalizeChildrenSingle(createElementImpl(effectiveType as any, props as any, ...(children as any[])));
+  // Stamp $$typeof so react-is.isValidElement / isFragment / isForwardRef etc.
+  // work correctly on VNodes produced by the compat layer.
+  (vnode as any).$$typeof = REACT_ELEMENT_TYPE;
+  return vnode;
 }
 
 // ---------------------------------------------------------------------------
 // Export
 // ---------------------------------------------------------------------------
 
-export { Fragment, memo };
+// Export the standard React fragment symbol so react-is.isFragment() works
+// correctly. The renderer recognises both this and the internal refract.fragment
+// symbol (see coreRenderer.ts REACT_FRAGMENT_TYPE).
+export const Fragment = Symbol.for("react.fragment");
+export { memo };
 export {
   createRef,
   registerExternalReactModule,
@@ -571,6 +636,7 @@ const ReactCompat = {
   PureComponent,
   Suspense,
   lazy,
+  use,
   createContext,
   createElement,
   cloneElement,

package/src/refract/coreRenderer.ts

@@ -208,7 +208,7 @@ function flattenRenderedChildren(raw: RenderedChild[]): VNode[] {
       continue;
     }
     if (typeof child === "object") {
-      const record = child as Record<string, unknown>;
+      const record = child as unknown as Record<string, unknown>;
       if ("type" in record && "props" in record) {
         const rawKey = record.key;
         result.push({

package/src/refract/hooksRuntime.ts

@@ -109,7 +109,24 @@ function handleErrorBoundary(fiber: Fiber, error: unknown): boolean {
   return false;
 }
 
+function handleSuspenseBoundary(fiber: Fiber, error: unknown): boolean {
+  if (!(error instanceof Promise)) return false;
+  let current: Fiber | null = fiber.parent;
+  while (current) {
+    if (current._suspenseHandler) {
+      current._suspenseHandler(error as Promise<unknown>);
+      reconcileChildren(fiber, []);
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+
 registerFiberCleanupHandler(cleanupFiberEffects);
 registerAfterCommitHandler(runPendingEffects);
 registerBeforeRenderBatchHandler(flushPassiveEffects);
+// Suspense must be registered before the error boundary so a thrown Promise
+// is caught by the nearest Suspense boundary before reaching any error boundary.
+registerRenderErrorHandler(handleSuspenseBoundary);
 registerRenderErrorHandler(handleErrorBoundary);

package/src/refract/types.ts

@@ -48,6 +48,7 @@ export interface Fiber {
   _contexts?: Map<number, unknown>;
   _objectContexts?: Map<object, unknown>;
   _errorHandler?: (error: unknown) => void;
+  _suspenseHandler?: (promise: Promise<unknown>) => void;
   alternate: Fiber | null;
   flags: number;
 }