what-react 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "what-react",
+  "version": "0.1.0",
+  "description": "React compatibility layer for What Framework — use React packages with signals under the hood",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./dom": "./src/dom.js",
+    "./jsx-runtime": "./src/jsx-runtime.js",
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.js",
+    "./vite": "./src/vite-plugin.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "react",
+    "compat",
+    "what",
+    "framework",
+    "signals",
+    "compatibility"
+  ],
+  "peerDependencies": {
+    "what-core": "^0.5.3"
+  },
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zvndev/what-fw"
+  },
+  "bugs": {
+    "url": "https://github.com/zvndev/what-fw/issues"
+  },
+  "homepage": "https://whatframework.dev"
+}

package/src/dom.js

@@ -0,0 +1,116 @@
+/**
+ * what-react/dom — ReactDOM compatibility layer
+ *
+ * Implements ReactDOM's public API using What's mount() and rendering.
+ */
+
+import { mount as whatMount, h, Fragment } from 'what-core';
+import { flushSync as whatFlushSync } from 'what-core';
+
+// ---- createRoot (React 18) ----
+
+export function createRoot(container) {
+  let unmount = null;
+
+  return {
+    render(element) {
+      if (unmount) unmount();
+      unmount = whatMount(element, container);
+    },
+    unmount() {
+      if (unmount) {
+        unmount();
+        unmount = null;
+      }
+      container.innerHTML = '';
+    },
+  };
+}
+
+// ---- hydrateRoot ----
+// Basic implementation — mounts fresh (true hydration would reuse existing DOM)
+
+export function hydrateRoot(container, initialChildren) {
+  const root = createRoot(container);
+  root.render(initialChildren);
+  return root;
+}
+
+// ---- render (React 17 legacy) ----
+
+export function render(element, container, callback) {
+  const root = createRoot(container);
+  root.render(element);
+  if (callback) queueMicrotask(callback);
+  return root;
+}
+
+// ---- unmountComponentAtNode (React 17 legacy) ----
+
+export function unmountComponentAtNode(container) {
+  container.innerHTML = '';
+  return true;
+}
+
+// ---- createPortal ----
+
+export function createPortal(children, container, key) {
+  // Create a vnode that the core reconciler recognizes as a portal.
+  // Core's createDOM routes '__portal' tagged vnodes to the internal portal handler,
+  // which renders children into the target container and returns a placeholder comment.
+  const portal = {
+    tag: '__portal',
+    props: { container, key },
+    children: Array.isArray(children) ? children : [children],
+    key: key || null,
+    _vnode: true,
+  };
+
+  return portal;
+}
+
+// ---- flushSync ----
+
+export function flushSync(fn) {
+  if (fn) fn();
+  whatFlushSync();
+}
+
+// ---- findDOMNode (deprecated but needed for legacy packages) ----
+
+export function findDOMNode(component) {
+  if (component == null) return null;
+  // If it's already a DOM node, return it
+  if (component instanceof HTMLElement) return component;
+  // Class component instance — look for _domNode or _container
+  if (component._domNode) return component._domNode;
+  // If the component has a ref attached, try that
+  if (component._ref?.current instanceof HTMLElement) return component._ref.current;
+  // what-c wrapper element — return the first child
+  if (component instanceof Element) return component;
+  return null;
+}
+
+// ---- batching ----
+
+export function unstable_batchedUpdates(fn) {
+  fn();
+}
+
+// ---- Version ----
+export const version = '18.3.1';
+
+// ---- Default export ----
+const ReactDOM = {
+  createRoot,
+  hydrateRoot,
+  render,
+  unmountComponentAtNode,
+  createPortal,
+  flushSync,
+  findDOMNode,
+  unstable_batchedUpdates,
+  version,
+};
+
+export default ReactDOM;

package/src/index.js

@@ -0,0 +1,580 @@
+/**
+ * what-react — React compatibility layer for What Framework
+ *
+ * Implements React's public API using What's signals + reconciler.
+ * Alias "react" → "what-react" in your bundler to use React libraries.
+ *
+ * What's existing hooks already have positional tracking (hookIndex/hooks[]),
+ * so most hooks are thin re-exports. The main work is bridging createElement,
+ * forwardRef, Children, class components, and React-specific APIs.
+ */
+
+import {
+  h,
+  Fragment as WhatFragment,
+  signal,
+  effect,
+  computed,
+  batch,
+  flushSync as whatFlushSync,
+  untrack,
+  memo as whatMemo,
+  lazy as whatLazy,
+  Suspense as WhatSuspense,
+  ErrorBoundary as WhatErrorBoundary,
+  useState as whatUseState,
+  useEffect as whatUseEffect,
+  useMemo as whatUseMemo,
+  useCallback as whatUseCallback,
+  useRef as whatUseRef,
+  useContext as whatUseContext,
+  useReducer as whatUseReducer,
+  createContext as whatCreateContext,
+  onMount,
+  onCleanup,
+} from 'what-core';
+
+// ---- Re-export What's hooks with React-compatible names ----
+
+export const useState = whatUseState;
+export const useEffect = whatUseEffect;
+export const useMemo = whatUseMemo;
+export const useCallback = whatUseCallback;
+export const useRef = whatUseRef;
+export const useContext = whatUseContext;
+export const useReducer = whatUseReducer;
+export const createContext = whatCreateContext;
+export const Fragment = WhatFragment;
+export const Suspense = WhatSuspense;
+export const memo = whatMemo;
+export const lazy = whatLazy;
+
+// ---- Class component wrapper ----
+
+const classWrapperCache = new WeakMap();
+
+function isClassComponent(type) {
+  return (
+    typeof type === 'function' &&
+    (type.prototype?.isReactComponent || type.prototype?.render)
+  );
+}
+
+// Max re-renders per component per frame to prevent infinite loops
+const MAX_RENDERS_PER_FRAME = 50;
+
+function getClassWrapper(ClassComp) {
+  let wrapper = classWrapperCache.get(ClassComp);
+  if (wrapper) return wrapper;
+
+  wrapper = function ClassComponentWrapper(props) {
+    const instanceRef = whatUseRef(null);
+    const [renderCount, forceRender] = whatUseState(0);
+    const renderGuardRef = whatUseRef({ count: 0, frame: 0 });
+
+    // Render cycle guard — prevent infinite re-render loops
+    const currentFrame = renderGuardRef.current.frame;
+    if (typeof requestAnimationFrame !== 'undefined') {
+      renderGuardRef.current.count++;
+      if (renderGuardRef.current.count > MAX_RENDERS_PER_FRAME) {
+        console.error(`[what-react] Max re-renders exceeded for ${ClassComp.displayName || ClassComp.name || 'ClassComponent'}. Possible infinite loop.`);
+        return null;
+      }
+      // Reset count on next frame
+      if (renderGuardRef.current._raf === undefined) {
+        renderGuardRef.current._raf = requestAnimationFrame(() => {
+          renderGuardRef.current.count = 0;
+          renderGuardRef.current.frame++;
+          renderGuardRef.current._raf = undefined;
+        });
+      }
+    }
+
+    // Apply defaultProps
+    let mergedProps = props;
+    if (ClassComp.defaultProps) {
+      mergedProps = { ...ClassComp.defaultProps, ...props };
+    }
+
+    if (instanceRef.current === null) {
+      // Initialize state from constructor
+      const instance = new ClassComp(mergedProps);
+
+      // Apply getDerivedStateFromProps on initial render
+      if (ClassComp.getDerivedStateFromProps) {
+        const derived = ClassComp.getDerivedStateFromProps(mergedProps, instance.state);
+        if (derived !== null && derived !== undefined) {
+          instance.state = { ...instance.state, ...derived };
+        }
+      }
+
+      // Throttle forceUpdate — coalesce rapid setState calls
+      let updateScheduled = false;
+      instance._forceUpdate = () => {
+        if (!updateScheduled) {
+          updateScheduled = true;
+          queueMicrotask(() => {
+            updateScheduled = false;
+            forceRender(c => c + 1);
+          });
+        }
+      };
+      instanceRef.current = instance;
+    }
+
+    const instance = instanceRef.current;
+    instance.props = mergedProps;
+
+    // Apply getDerivedStateFromProps on every render (React semantics)
+    if (ClassComp.getDerivedStateFromProps) {
+      const derived = ClassComp.getDerivedStateFromProps(mergedProps, instance.state);
+      if (derived !== null && derived !== undefined) {
+        instance.state = { ...instance.state, ...derived };
+      }
+    }
+
+    // Static contextType support — inject this.context from nearest provider
+    if (ClassComp.contextType && ClassComp.contextType._whatContext) {
+      try {
+        instance.context = whatUseContext(ClassComp.contextType);
+      } catch (e) {
+        // Context not available — leave as undefined
+      }
+    }
+
+    // componentDidMount / componentWillUnmount lifecycle
+    whatUseEffect(() => {
+      instance._mounted = true;
+      if (instance.componentDidMount) {
+        instance.componentDidMount();
+      }
+      return () => {
+        instance._mounted = false;
+        if (instance.componentWillUnmount) {
+          instance.componentWillUnmount();
+        }
+      };
+    }, []);
+
+    // componentDidUpdate + getSnapshotBeforeUpdate
+    const prevRef = whatUseRef({ props: null, state: null, rendered: false, snapshot: undefined });
+    whatUseEffect(() => {
+      if (!prevRef.current.rendered) {
+        prevRef.current = { props: mergedProps, state: instance.state, rendered: true, snapshot: undefined };
+        return;
+      }
+      const prev = prevRef.current;
+      prevRef.current = { props: mergedProps, state: instance.state, rendered: true, snapshot: undefined };
+      if (instance.componentDidUpdate) {
+        instance.componentDidUpdate(prev.props, prev.state, prev.snapshot);
+      }
+    }, [mergedProps, renderCount]);
+
+    // getSnapshotBeforeUpdate — capture before DOM updates
+    // We approximate by calling it synchronously before render returns
+    if (instance.getSnapshotBeforeUpdate && prevRef.current.rendered) {
+      prevRef.current.snapshot = instance.getSnapshotBeforeUpdate(
+        prevRef.current.props, prevRef.current.state
+      );
+    }
+
+    return instance.render();
+  };
+
+  // Preserve static properties and displayName
+  wrapper.displayName = ClassComp.displayName || ClassComp.name || 'ClassComponent';
+  // Copy static properties (getDerivedStateFromProps, defaultProps, contextType, etc.)
+  for (const key of Object.getOwnPropertyNames(ClassComp)) {
+    if (key !== 'prototype' && key !== 'length' && key !== 'name' && key !== 'caller' && key !== 'arguments') {
+      try { wrapper[key] = ClassComp[key]; } catch (e) {}
+    }
+  }
+
+  classWrapperCache.set(ClassComp, wrapper);
+  return wrapper;
+}
+
+// ---- createElement ----
+
+export function createElement(type, props, ...children) {
+  if (props == null) props = {};
+
+  // Wrap class components so What's reconciler can call them as functions
+  if (isClassComponent(type)) {
+    type = getClassWrapper(type);
+  }
+
+  // React libraries sometimes pass children via props instead of as spread args
+  // (e.g., React Router's createElement(Router, { children, location, ... })).
+  // Move props.children into the spread children array so h() puts them
+  // in vnode.children — otherwise the reconciler overwrites props.children.
+  if (children.length === 0 && props.children !== undefined) {
+    const pc = props.children;
+    children = Array.isArray(pc) ? pc : [pc];
+    props = { ...props };
+    delete props.children;
+  }
+
+  // Normalize className → class, htmlFor → for for HTML elements
+  if (typeof type === 'string') {
+    if ('className' in props) {
+      props.class = props.className;
+      delete props.className;
+    }
+    if ('htmlFor' in props) {
+      props.for = props.htmlFor;
+      delete props.htmlFor;
+    }
+  }
+
+  // Keep ref in props — What's reconciler handles ref for HTML elements,
+  // and forwardRef components extract it from props. No need to strip.
+
+  const vnode = children.length <= 1
+    ? h(type, props, children[0])
+    : h(type, props, ...children);
+
+  // Alias tag → type so React libraries can access element.type
+  vnode.type = vnode.tag;
+
+  // Mirror children into props for React compat — React libraries read
+  // element.props.children (e.g., React Router's createRoutesFromChildren)
+  if (vnode.children.length > 0) {
+    vnode.props = { ...vnode.props };
+    vnode.props.children = vnode.children.length === 1
+      ? vnode.children[0]
+      : vnode.children;
+  }
+
+  return vnode;
+}
+
+// ---- forwardRef ----
+
+export function forwardRef(render) {
+  function ForwardRefComponent(props) {
+    const { ref, ...rest } = props;
+    return render(rest, ref || null);
+  }
+  ForwardRefComponent.displayName = render.displayName || render.name || 'ForwardRef';
+  ForwardRefComponent._forwardRef = true;
+  ForwardRefComponent.$$typeof = Symbol.for('react.forward_ref');
+  return ForwardRefComponent;
+}
+
+// ---- createRef ----
+
+export function createRef() {
+  return { current: null };
+}
+
+// ---- Children utilities ----
+
+export const Children = {
+  map(children, fn) {
+    if (children == null) return [];
+    const arr = Array.isArray(children) ? children : [children];
+    const result = [];
+    let index = 0;
+    for (const child of arr.flat(Infinity)) {
+      if (child == null || child === false || child === true) continue;
+      result.push(fn(child, index++));
+    }
+    return result;
+  },
+
+  forEach(children, fn) {
+    Children.map(children, fn);
+  },
+
+  count(children) {
+    if (children == null) return 0;
+    const arr = Array.isArray(children) ? children : [children];
+    return arr.flat(Infinity).filter(c => c != null && c !== false && c !== true).length;
+  },
+
+  toArray(children) {
+    if (children == null) return [];
+    const arr = Array.isArray(children) ? children : [children];
+    return arr.flat(Infinity).filter(c => c != null && c !== false && c !== true);
+  },
+
+  only(children) {
+    const arr = Children.toArray(children);
+    if (arr.length !== 1) {
+      throw new Error('React.Children.only expected to receive a single React element child.');
+    }
+    return arr[0];
+  },
+};
+
+// ---- cloneElement ----
+
+export function cloneElement(element, props, ...children) {
+  if (!element) return element;
+
+  // Handle both vnode objects and plain React-style elements
+  const tag = element.tag || element.type;
+  const oldProps = element.props || {};
+  const oldChildren = element.children || [];
+  const oldKey = element.key;
+  const oldRef = oldProps.ref;
+
+  if (!tag) return element;
+
+  const newProps = { ...oldProps, ...props };
+  // Preserve ref from old element if not overridden
+  if (props && props.ref !== undefined) {
+    newProps.ref = props.ref;
+  } else if (oldRef !== undefined) {
+    newProps.ref = oldRef;
+  }
+  const newChildren = children.length > 0 ? children : oldChildren;
+  const newKey = props?.key !== undefined ? props.key : oldKey;
+  if (newKey !== undefined) newProps.key = newKey;
+
+  return createElement(tag, newProps, ...([].concat(newChildren || [])));
+}
+
+// ---- createFactory (deprecated but used by some libraries) ----
+
+export function createFactory(type) {
+  const factory = createElement.bind(null, type);
+  factory.type = type;
+  return factory;
+}
+
+// ---- isValidElement ----
+
+export function isValidElement(object) {
+  return (
+    typeof object === 'object' &&
+    object !== null &&
+    (object._vnode === true || object.$$typeof !== undefined)
+  );
+}
+
+// ---- useLayoutEffect ----
+
+export function useLayoutEffect(fn, deps) {
+  return whatUseEffect(fn, deps);
+}
+
+// ---- useInsertionEffect ----
+// React 18 hook for CSS-in-JS libraries. Runs synchronously before layout effects.
+// We map it to useEffect since What doesn't have multi-phase commit.
+
+export function useInsertionEffect(fn, deps) {
+  return whatUseEffect(fn, deps);
+}
+
+// ---- useImperativeHandle ----
+
+export function useImperativeHandle(ref, createHandle, deps) {
+  useLayoutEffect(() => {
+    if (typeof ref === 'function') {
+      const handle = createHandle();
+      ref(handle);
+      return () => ref(null);
+    } else if (ref && typeof ref === 'object') {
+      const handle = createHandle();
+      ref.current = handle;
+      return () => { ref.current = null; };
+    }
+  }, deps);
+}
+
+// ---- useId ----
+let idCounter = 0;
+export function useId() {
+  const ref = whatUseRef(null);
+  if (ref.current === null) {
+    ref.current = ':w' + (++idCounter).toString(36) + ':';
+  }
+  return ref.current;
+}
+
+// ---- useDebugValue ----
+export function useDebugValue() {}
+
+// ---- useSyncExternalStore ----
+
+export function useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) {
+  const [value, setValue] = whatUseState(() => getSnapshot());
+  const snapshotRef = whatUseRef(getSnapshot());
+
+  whatUseEffect(() => {
+    const handleChange = () => {
+      const next = getSnapshot();
+      if (!Object.is(snapshotRef.current, next)) {
+        snapshotRef.current = next;
+        setValue(next);
+      }
+    };
+    handleChange();
+    return subscribe(handleChange);
+  }, [subscribe, getSnapshot]);
+
+  return value;
+}
+
+// ---- useTransition ----
+
+export function useTransition() {
+  const [isPending, setIsPending] = whatUseState(false);
+
+  function startTransitionFn(fn) {
+    setIsPending(true);
+    queueMicrotask(() => {
+      batch(() => {
+        fn();
+        setIsPending(false);
+      });
+    });
+  }
+
+  return [isPending, startTransitionFn];
+}
+
+// ---- useDeferredValue ----
+
+export function useDeferredValue(value) {
+  const [deferred, setDeferred] = whatUseState(value);
+
+  whatUseEffect(() => {
+    setDeferred(value);
+  }, [value]);
+
+  return deferred;
+}
+
+// ---- startTransition (module-level) ----
+
+export function startTransition(fn) {
+  queueMicrotask(() => {
+    batch(fn);
+  });
+}
+
+// ---- StrictMode ----
+
+export function StrictMode({ children }) {
+  return children;
+}
+
+// ---- Component / PureComponent ----
+// Use function constructors (not native classes) so that transpiled code
+// using Component.call(this, props) works alongside native class extends.
+
+export function Component(props) {
+  this.props = props;
+  this.state = {};
+  this._stateSignal = null;
+  this._mounted = false;
+  this._forceUpdate = null;
+}
+
+Component.prototype.isReactComponent = {};
+
+Component.prototype.setState = function(update, callback) {
+  const nextState = typeof update === 'function'
+    ? { ...this.state, ...update(this.state, this.props) }
+    : { ...this.state, ...update };
+
+  this.state = nextState;
+
+  if (this._forceUpdate) {
+    this._forceUpdate();
+  }
+
+  if (callback) {
+    queueMicrotask(callback);
+  }
+};
+
+Component.prototype.forceUpdate = function(callback) {
+  if (this._forceUpdate) {
+    this._forceUpdate();
+  }
+  if (callback) {
+    queueMicrotask(callback);
+  }
+};
+
+Component.prototype.render = function() {
+  return null;
+};
+
+export function PureComponent(props) {
+  Component.call(this, props);
+}
+
+PureComponent.prototype = Object.create(Component.prototype);
+PureComponent.prototype.constructor = PureComponent;
+PureComponent.prototype.isPureReactComponent = true;
+
+PureComponent.prototype.shouldComponentUpdate = function(nextProps, nextState) {
+  return !shallowEqual(this.props, nextProps) || !shallowEqual(this.state, nextState);
+};
+
+// ---- Internal helpers ----
+
+function shallowEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+// ---- React internals that some libraries check ----
+export const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = {
+  ReactCurrentOwner: { current: null },
+  ReactCurrentDispatcher: { current: null },
+};
+
+// ---- Version ----
+export const version = '18.3.1';
+
+// ---- Default export (import * as React from 'react') ----
+const React = {
+  useState: whatUseState,
+  useEffect: whatUseEffect,
+  useLayoutEffect,
+  useInsertionEffect,
+  useMemo: whatUseMemo,
+  useCallback: whatUseCallback,
+  useRef: whatUseRef,
+  useContext: whatUseContext,
+  useReducer: whatUseReducer,
+  useImperativeHandle,
+  useId,
+  useDebugValue,
+  useSyncExternalStore,
+  useTransition,
+  useDeferredValue,
+  createElement,
+  createContext: whatCreateContext,
+  createRef,
+  createFactory,
+  forwardRef,
+  cloneElement,
+  isValidElement,
+  Component,
+  PureComponent,
+  Fragment: WhatFragment,
+  Suspense: WhatSuspense,
+  StrictMode,
+  memo: whatMemo,
+  lazy: whatLazy,
+  Children,
+  startTransition,
+  version,
+  __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+};
+
+export default React;

package/src/jsx-dev-runtime.js

@@ -0,0 +1,6 @@
+/**
+ * what-react/jsx-dev-runtime — JSX development runtime
+ * Same as jsx-runtime but with development warnings.
+ */
+
+export { jsx, jsxs, jsxDEV, Fragment } from './jsx-runtime.js';

package/src/jsx-runtime.js

@@ -0,0 +1,38 @@
+/**
+ * what-react/jsx-runtime — JSX automatic runtime
+ *
+ * When React libraries are compiled with the automatic JSX runtime,
+ * they import jsx/jsxs from 'react/jsx-runtime' instead of calling
+ * React.createElement. This module provides those functions.
+ */
+
+import { createElement } from './index.js';
+import { Fragment } from 'what-core';
+
+export { Fragment };
+
+export function jsx(type, props, key) {
+  if (key !== undefined) {
+    props = { ...props, key };
+  }
+
+  // Extract children from props (automatic runtime puts children in props)
+  const { children, ...rest } = props || {};
+
+  if (children === undefined) {
+    return createElement(type, rest);
+  }
+
+  if (Array.isArray(children)) {
+    return createElement(type, rest, ...children);
+  }
+
+  return createElement(type, rest, children);
+}
+
+// jsxs is the same as jsx — React uses it for static children optimization
+// but we don't need that distinction
+export const jsxs = jsx;
+
+// Development version
+export const jsxDEV = jsx;

package/src/use-sync-external-store-with-selector.js

@@ -0,0 +1,79 @@
+/**
+ * ESM shim for use-sync-external-store/with-selector
+ * Used by react-redux. Provides useSyncExternalStoreWithSelector
+ * which wraps useSyncExternalStore with selector + isEqual support.
+ */
+import { useSyncExternalStore, useRef, useEffect, useMemo, useDebugValue } from './index.js';
+
+export function useSyncExternalStoreWithSelector(
+  subscribe,
+  getSnapshot,
+  getServerSnapshot,
+  selector,
+  isEqual
+) {
+  const instRef = useRef(null);
+  if (instRef.current === null) {
+    instRef.current = { hasValue: false, value: null };
+  }
+  const inst = instRef.current;
+
+  const [getSelection, getServerSelection] = useMemo(() => {
+    let hasMemo = false;
+    let memoizedSnapshot;
+    let memoizedSelection;
+
+    const memoizedSelector = (nextSnapshot) => {
+      if (!hasMemo) {
+        hasMemo = true;
+        memoizedSnapshot = nextSnapshot;
+        const nextSelection = selector(nextSnapshot);
+        if (isEqual !== undefined && inst.hasValue) {
+          const currentSelection = inst.value;
+          if (isEqual(currentSelection, nextSelection)) {
+            memoizedSelection = currentSelection;
+            return currentSelection;
+          }
+        }
+        memoizedSelection = nextSelection;
+        return nextSelection;
+      }
+
+      const prevSnapshot = memoizedSnapshot;
+      const prevSelection = memoizedSelection;
+
+      if (Object.is(prevSnapshot, nextSnapshot)) {
+        return prevSelection;
+      }
+
+      const nextSelection = selector(nextSnapshot);
+
+      if (isEqual !== undefined && isEqual(prevSelection, nextSelection)) {
+        memoizedSnapshot = nextSnapshot;
+        return prevSelection;
+      }
+
+      memoizedSnapshot = nextSnapshot;
+      memoizedSelection = nextSelection;
+      return nextSelection;
+    };
+
+    const getSnapshotWithSelector = () => memoizedSelector(getSnapshot());
+    const getServerSnapshotWithSelector = getServerSnapshot === undefined
+      ? undefined
+      : () => memoizedSelector(getServerSnapshot());
+
+    return [getSnapshotWithSelector, getServerSnapshotWithSelector];
+  }, [getSnapshot, getServerSnapshot, selector, isEqual]);
+
+  const value = useSyncExternalStore(subscribe, getSelection, getServerSelection);
+
+  useEffect(() => {
+    inst.hasValue = true;
+    inst.value = value;
+  }, [value]);
+
+  useDebugValue(value);
+
+  return value;
+}

package/src/vite-plugin.js

@@ -0,0 +1,195 @@
+/**
+ * what-react Vite Plugin — One-line React → What Framework migration
+ *
+ * Usage:
+ *   import { reactCompat } from 'what-react/vite';
+ *   export default defineConfig({ plugins: [reactCompat()] });
+ *
+ * This plugin aliases all React imports to what-react, configures JSX,
+ * and excludes React-ecosystem packages from Vite's pre-bundling to
+ * prevent dual module instances.
+ */
+import { createRequire } from 'module';
+import path from 'path';
+import fs from 'fs';
+
+// Common React ecosystem packages that import 'react' internally.
+// These must be excluded from Vite's optimizeDeps to prevent pre-bundling
+// with real React, which creates dual module instances.
+const KNOWN_REACT_PACKAGES = [
+  // State management
+  'zustand', 'jotai', 'valtio', 'mobx-react', 'mobx-react-lite',
+  'react-redux', 'redux', '@reduxjs/toolkit',
+  // Data fetching
+  '@tanstack/react-query', 'swr',
+  // Forms
+  'react-hook-form',
+  // UI component libraries
+  '@radix-ui', '@headlessui/react', 'antd', '@ant-design',
+  '@mui/material', '@mui/x-data-grid', '@chakra-ui/react',
+  // Tables & grids
+  '@tanstack/react-table', '@tanstack/table-core',
+  // Virtualization
+  '@tanstack/react-virtual', '@tanstack/virtual-core',
+  'react-window', 'react-virtualized',
+  // Animation
+  'framer-motion', 'motion', '@react-spring/web', 'react-spring',
+  // Drag and drop
+  '@dnd-kit/core', '@dnd-kit/sortable', 'react-dnd',
+  // Routing
+  'react-router', 'react-router-dom',
+  // Notifications
+  'react-hot-toast', 'react-toastify',
+  // Icons
+  'react-icons', '@heroicons/react',
+  // Misc
+  'react-markdown', 'react-helmet', 'react-helmet-async',
+  'react-i18next', 'react-error-boundary',
+  'react-select', 'react-datepicker',
+  // Internal shims
+  'use-sync-external-store', 'immer',
+];
+
+/**
+ * Resolve the directory of a package from the user's project
+ */
+function resolvePackageDir(packageName, fromDir) {
+  try {
+    const require = createRequire(fromDir + '/');
+    const resolved = require.resolve(packageName);
+    // Walk up from the resolved file to find the package root
+    let dir = path.dirname(resolved);
+    while (dir !== path.dirname(dir)) {
+      if (fs.existsSync(path.join(dir, 'package.json'))) {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        if (pkg.name === packageName) return dir;
+      }
+      dir = path.dirname(dir);
+    }
+    return path.dirname(resolved);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Auto-detect which React packages are installed in the project
+ */
+function detectInstalledReactPackages(projectRoot) {
+  const installed = [];
+  for (const pkg of KNOWN_REACT_PACKAGES) {
+    try {
+      const require = createRequire(projectRoot + '/');
+      require.resolve(pkg);
+      installed.push(pkg);
+    } catch {
+      // Not installed, skip
+    }
+  }
+  return installed;
+}
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.exclude] - Additional packages to exclude from pre-bundling
+ * @param {boolean} [options.autoDetect=true] - Auto-detect installed React packages to exclude
+ * @returns {import('vite').Plugin}
+ */
+export function reactCompat(options = {}) {
+  const { exclude = [], autoDetect = true } = options;
+
+  let compatDir;
+  let whatCorePath;
+  let whatCoreRenderPath;
+
+  return {
+    name: 'what-react-compat',
+    enforce: 'pre',
+
+    config(config, { command }) {
+      const root = config.root || process.cwd();
+
+      // Resolve what-react and what-core paths from installed packages
+      compatDir = resolvePackageDir('what-react', root);
+      // compatSrc = the directory containing index.js, jsx-runtime.js, dom.js, etc.
+      let compatSrc;
+      if (compatDir) {
+        compatSrc = path.join(compatDir, 'src');
+      } else {
+        // Fallback: this plugin file lives in src/ — use its directory directly
+        compatSrc = path.dirname(new URL(import.meta.url).pathname);
+        compatDir = path.dirname(compatSrc);
+      }
+
+      const whatCoreDir = resolvePackageDir('what-core', root);
+      if (whatCoreDir) {
+        whatCorePath = path.join(whatCoreDir, 'src', 'index.js');
+        whatCoreRenderPath = path.join(whatCoreDir, 'src', 'render.js');
+      } else {
+        // Fallback: resolve from what-react's peer dep
+        const whatCoreFromCompat = resolvePackageDir('what-core', compatDir);
+        if (whatCoreFromCompat) {
+          whatCorePath = path.join(whatCoreFromCompat, 'src', 'index.js');
+          whatCoreRenderPath = path.join(whatCoreFromCompat, 'src', 'render.js');
+        }
+      }
+
+      // Auto-detect installed React ecosystem packages
+      const autoExclude = autoDetect ? detectInstalledReactPackages(root) : [];
+      const allExclude = [
+        'what-core', 'what-react',
+        'react', 'react-dom',
+        ...autoExclude,
+        ...exclude,
+      ];
+      // Deduplicate
+      const uniqueExclude = [...new Set(allExclude)];
+
+      // Build alias map
+      const aliases = {
+        'react/jsx-runtime': path.join(compatSrc, 'jsx-runtime.js'),
+        'react/jsx-dev-runtime': path.join(compatSrc, 'jsx-dev-runtime.js'),
+        'react-dom/client': path.join(compatSrc, 'dom.js'),
+        'react-dom': path.join(compatSrc, 'dom.js'),
+        'react': path.join(compatSrc, 'index.js'),
+        // use-sync-external-store shims (needed by react-redux, zustand internals)
+        'use-sync-external-store/with-selector.js': path.join(compatSrc, 'use-sync-external-store-with-selector.js'),
+        'use-sync-external-store/with-selector': path.join(compatSrc, 'use-sync-external-store-with-selector.js'),
+        'use-sync-external-store/shim/with-selector.js': path.join(compatSrc, 'use-sync-external-store-with-selector.js'),
+        'use-sync-external-store/shim/with-selector': path.join(compatSrc, 'use-sync-external-store-with-selector.js'),
+        'use-sync-external-store/shim/index.js': path.join(compatSrc, 'index.js'),
+        'use-sync-external-store/shim': path.join(compatSrc, 'index.js'),
+      };
+
+      // Add what-core aliases if resolved
+      if (whatCorePath) {
+        aliases['what-framework/render'] = whatCoreRenderPath;
+        aliases['what-framework'] = whatCorePath;
+        aliases['what-core/render'] = whatCoreRenderPath;
+        aliases['what-core'] = whatCorePath;
+      }
+
+      return {
+        esbuild: {
+          jsx: 'automatic',
+          jsxImportSource: 'react', // aliased to what-react
+        },
+        resolve: {
+          alias: aliases,
+          dedupe: ['what-core'],
+        },
+        optimizeDeps: {
+          exclude: uniqueExclude,
+        },
+      };
+    },
+
+    configResolved(config) {
+      // Log what we set up
+      const excluded = config.optimizeDeps?.exclude?.length || 0;
+      console.log(`\n  ⚡ what-react compat active — ${excluded} packages excluded from pre-bundling\n`);
+    },
+  };
+}
+
+export default reactCompat;