@wular/pnext 0.0.1

package/src/compat/react/preact.ts

@@ -0,0 +1,522 @@
+import ReactCompat from 'preact/compat';
+import { options, type ComponentChildren, type ComponentType, type VNode } from 'preact';
+import { wrapComponentForPrimitiveThrows } from '../client/errors/primitive-throw';
+
+const reactForwardRefSymbol = Symbol.for('react.forward_ref');
+const react19RefCompatInstalled = Symbol.for('pnext.react19-ref-compat-installed');
+const reactTextSeparatorSymbol = Symbol.for('pnext.react-text-separator');
+
+type PNextPreactOptions = typeof options & {
+  [react19RefCompatInstalled]?: true;
+};
+
+type RefCompatibleComponent = ComponentType<Record<string, unknown>> & {
+  $$typeof?: symbol;
+  prototype?: { render?: unknown };
+};
+
+// preact's `options.vnode` is process-global and cannot be uninstalled, so its BEHAVIOR follows the
+// active extension host instead: one server process can serve a compat app and then a pure-core one, and
+// the core app must not inherit React parity it never asked for. Defaults to on - importing this module
+// IS compat being wired, and the client never resets.
+let reactCompatActive = true;
+
+/** Enable/disable the react-compat vnode parity pass (see reactCompatActive). */
+export function setReactCompatActive(active: boolean): void {
+  reactCompatActive = active;
+}
+
+const pnextOptions = options as PNextPreactOptions;
+if (!pnextOptions[react19RefCompatInstalled]) {
+  const previousVNode = options.vnode?.bind(options);
+  options.vnode = vnode => {
+    previousVNode?.(vnode);
+    if (!reactCompatActive) return;
+    applyReact19RefProp(vnode);
+    applyAsyncClientComponent(vnode);
+    applyPrimitiveThrowSafety(vnode);
+    applyThenableChildren(vnode);
+    applyReactTextSeparators(vnode);
+  };
+  pnextOptions[react19RefCompatInstalled] = true;
+
+  // Effect scheduling parity with React: preact/hooks flushes passive effects
+  // via requestAnimationFrame + setTimeout(35) (afterNextFrame), both governed
+  // by the page clock. React flushes them through its scheduler's
+  // MessageChannel, which fake-timer installations (Playwright's CDP clock in
+  // Next's own e2e suites) never intercept. Under an installed fake clock the
+  // rAF path loses its "before the next idle callback" ordering and
+  // Suspense-boundary promotions land after a test's post-drain DOM sample.
+  // Route the flush through a MessageChannel task so effect timing is
+  // clock-independent, like React's.
+  if ((process.browser || typeof window !== 'undefined') && typeof MessageChannel !== 'undefined') {
+    const queue: (() => void)[] = [];
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      for (const callback of queue.splice(0)) callback();
+    };
+    (options as { requestAnimationFrame?: (cb: () => void) => void }).requestAnimationFrame =
+      callback => {
+        queue.push(callback);
+        channel.port2.postMessage(null);
+      };
+  }
+}
+
+function applyReactTextSeparators(vnode: VNode) {
+  // Server-only. `process.browser` is a client-bundle define (true) and
+  // undefined on the server, so this body folds out of browser builds; the
+  // `typeof window` twin keeps the runtime check for unbundled consumers.
+  if (process.browser || typeof window !== 'undefined') return;
+  const props = vnode.props as Record<string, unknown>;
+  const children = props.children;
+  if (!Array.isArray(children) || children.length < 2) return;
+  const values = children as unknown[];
+
+  const separated: unknown[] = [];
+  let changed = false;
+  for (let index = 0; index < values.length; index += 1) {
+    const child = values[index];
+    separated.push(child);
+    if (!mayRenderText(child) || !mayRenderText(values[index + 1])) continue;
+    separated.push({
+      type: reactTextSeparatorSymbol,
+      props: { UNSTABLE_comment: ' ' },
+    });
+    changed = true;
+  }
+  if (changed) props.children = separated;
+}
+
+function mayRenderText(value: unknown) {
+  if (typeof value === 'string' || typeof value === 'number') return true;
+  if (!value || typeof value !== 'object' || !('type' in value)) return false;
+  return typeof (value as VNode).type !== 'string';
+}
+
+function applyThenableChildren(vnode: VNode) {
+  const props = vnode.props as Record<string, unknown>;
+  const children = props.children;
+  const resolved = thenableChildren(children);
+  if (resolved !== children) props.children = resolved;
+}
+
+function thenableChildren(value: unknown): unknown {
+  if (value && typeof (value as PromiseLike<unknown>).then === 'function') {
+    return ReactCompat.createElement(
+      ReactCompat.Suspense,
+      { fallback: null },
+      ReactCompat.createElement(ThenableChild, {
+        value: value as PromiseLike<ComponentChildren>,
+      }),
+    );
+  }
+  if (!Array.isArray(value)) return value;
+  let changed = false;
+  const children = value.map(child => {
+    const resolved = thenableChildren(child);
+    if (resolved !== child) changed = true;
+    return resolved;
+  });
+  return changed ? children : value;
+}
+
+function ThenableChild({ value }: { value: PromiseLike<ComponentChildren> }) {
+  return use(value);
+}
+
+const asyncClientComponents = new WeakMap<
+  ComponentType<Record<string, unknown>>,
+  ComponentType<Record<string, unknown>>
+>();
+
+function applyAsyncClientComponent(vnode: VNode) {
+  if ((!process.browser && typeof window === 'undefined') || typeof vnode.type !== 'function') return;
+  const component = vnode.type as ComponentType<Record<string, unknown>>;
+  if (component.constructor.name !== 'AsyncFunction') return;
+  const renderComponent = component as (props: Record<string, unknown>) => ComponentChildren;
+  let wrapper = asyncClientComponents.get(component);
+  if (!wrapper) {
+    wrapper = props => {
+      const [result] = ReactCompat.useState(() =>
+        Promise.resolve(renderComponent(props)),
+      );
+      return ReactCompat.createElement(
+        ReactCompat.Suspense,
+        { fallback: null },
+        ReactCompat.createElement(ThenableChild, { value: result }),
+      );
+    };
+    asyncClientComponents.set(component, wrapper);
+  }
+  vnode.type = wrapper;
+}
+
+function applyPrimitiveThrowSafety(vnode: VNode) {
+  // Client-only: this exists to stop a thrown undefined/null from crashing preact's OWN diff.js `e.then`
+  // suspense check during real preact diffing. The server's resolveServerTree is a custom RSC-style tree
+  // walker, not preact's diff - it never hits that crash, and wrapping component references there risks
+  // losing the symbol-keyed metadata resolveServerTree branches on.
+  if (!process.browser && typeof window === 'undefined') return;
+  if (typeof vnode.type !== 'function') return;
+  vnode.type = wrapComponentForPrimitiveThrows(vnode.type);
+}
+
+function applyReact19RefProp(vnode: VNode) {
+  if (!vnode.ref || typeof vnode.type !== 'function') return;
+  const component = vnode.type as RefCompatibleComponent;
+  if (component.prototype?.render || component.$$typeof === reactForwardRefSymbol) return;
+
+  vnode.props = { ...(vnode.props as Record<string, unknown>), ref: vnode.ref } as unknown as typeof vnode.props;
+  vnode.ref = null;
+}
+
+// React 19 APIs preact/compat lacks - use(), useActionState, useOptimistic (function declarations below,
+// hoisted) - must ALSO live on the default export: app code does `import React from 'react';
+// React.use(...)`, not only named imports. server.ts spreads this default into ReactServer, so the
+// augmentation covers both layers.
+export default Object.assign(ReactCompat, { use, useActionState, useOptimistic, useTransition });
+
+export const Children = ReactCompat.Children;
+export const Component = ReactCompat.Component;
+export const Fragment = ReactCompat.Fragment;
+export const PureComponent = ReactCompat.PureComponent;
+export const StrictMode = ReactCompat.StrictMode;
+export const Suspense = ReactCompat.Suspense;
+export const SuspenseList = ReactCompat.SuspenseList;
+export const cloneElement = ReactCompat.cloneElement;
+export const createContext = ReactCompat.createContext;
+export const createElement = ReactCompat.createElement;
+export const createFactory = ReactCompat.createFactory;
+export const createPortal = ReactCompat.createPortal;
+export const createRef = ReactCompat.createRef;
+export const findDOMNode = ReactCompat.findDOMNode;
+export const flushSync = ReactCompat.flushSync;
+export const forwardRef = ReactCompat.forwardRef;
+export const hydrate = ReactCompat.hydrate;
+export const isFragment = ReactCompat.isFragment;
+export const isMemo = ReactCompat.isMemo;
+export const isValidElement = ReactCompat.isValidElement;
+export const lazy = ReactCompat.lazy;
+export const memo = ReactCompat.memo;
+export const render = ReactCompat.render;
+export const startTransition = ReactCompat.startTransition;
+export const unmountComponentAtNode = ReactCompat.unmountComponentAtNode;
+export const unstable_batchedUpdates = ReactCompat.unstable_batchedUpdates;
+export const useCallback = ReactCompat.useCallback;
+export const useContext = ReactCompat.useContext;
+export const useDebugValue = ReactCompat.useDebugValue;
+export const useDeferredValue = ReactCompat.useDeferredValue;
+export const useEffect = ReactCompat.useEffect;
+export const useId = ReactCompat.useId;
+export const useImperativeHandle = ReactCompat.useImperativeHandle;
+export const useInsertionEffect = ReactCompat.useInsertionEffect;
+export const useLayoutEffect = ReactCompat.useLayoutEffect;
+export const useMemo = ReactCompat.useMemo;
+export const useReducer = ReactCompat.useReducer;
+export const useRef = ReactCompat.useRef;
+export const useState = ReactCompat.useState;
+export const useSyncExternalStore = ReactCompat.useSyncExternalStore;
+export const version = ReactCompat.version;
+
+// True when a preact hooks call would succeed (a component render is in flight). preact fires
+// options._render just before invoking a component and options.diffed after it commits; between the two,
+// hooks have a current component. Server-side tree resolution invokes some client components as plain
+// functions, outside any preact render, where hooks would throw - useActionState/useOptimistic fall back
+// to SSR-equivalent static values there instead.
+let renderInFlight = false;
+
+function hooksUsable(): boolean {
+  return renderInFlight;
+}
+
+{
+  const anyOptions = options as unknown as Record<string, unknown>;
+  const previousRender = anyOptions.__r as ((vnode: VNode) => void) | undefined;
+  anyOptions.__r = (vnode: VNode) => {
+    renderInFlight = true;
+    previousRender?.(vnode);
+  };
+  const previousDiffed = options.diffed?.bind(options);
+  options.diffed = vnode => {
+    renderInFlight = false;
+    previousDiffed?.(vnode);
+  };
+}
+
+/**
+ * React 19's useActionState, on preact hooks. Returns [state, dispatch, isPending]; dispatch(payload)
+ * runs `action(prevState, payload)` (async ok) and swaps the state when it settles. The returned dispatch
+ * is also valid as a `<form action={...}>` value - the pnext client runtime intercepts function form
+ * actions and calls them with the form's FormData. Queueing follows React: concurrent dispatches chain
+ * in order against the latest settled state rather than racing.
+ */
+export function useActionState<State, Payload = FormData>(
+  action: (state: Awaited<State>, payload: Payload) => State | Promise<State>,
+  initialState: Awaited<State>,
+  _permalink?: string,
+): [state: Awaited<State>, dispatch: (payload: Payload) => void, isPending: boolean] {
+  // Server resolve may invoke a client component as a plain function (no
+  // preact render context, so hooks throw). SSR output for useActionState is
+  // always the (possibly progressively-updated) initial state with a dispatch
+  // that only works after hydration; fall back to exactly that. The dispatch
+  // carries form-state metadata so SSR can progressively enhance
+  // <form action={dispatch}>.
+  if (!hooksUsable()) {
+    const staticInitial = (consumeActionStateOverride() ?? { value: initialState })
+      .value as Awaited<State>;
+    const staticDispatch = (payload: Payload) =>
+      void Promise.resolve(action(staticInitial, payload));
+    tagFormStateDispatch(staticDispatch, action, staticInitial, _permalink);
+    return [staticInitial, staticDispatch, false];
+  }
+  const initialRef = ReactCompat.useRef<{ value: Awaited<State> } | null>(null);
+  if (!initialRef.current) {
+    // A progressive (no-JS) submission re-renders the page with the action's
+    // result as the form state; the server (and the inline hydration script)
+    // publish it via a consumed-once global override.
+    initialRef.current = {
+      value: (consumeActionStateOverride() ?? { value: initialState }).value as Awaited<State>,
+    };
+  }
+  const [state, setState] = ReactCompat.useState<Awaited<State>>(initialRef.current.value);
+  const [pending, setPending] = ReactCompat.useState(0);
+  const lastSettled = ReactCompat.useRef<Awaited<State>>(initialRef.current.value);
+  const chain = ReactCompat.useRef<Promise<unknown>>(Promise.resolve());
+  // A rejected action must surface to the nearest error boundary during an actual preact render (only
+  // diff() wraps component calls in the getDerivedStateFromError/componentDidCatch try/catch).
+  // preact/hooks' setState invokes a functional updater EAGERLY at call time, to bail out on an unchanged
+  // value, rather than deferring it to the render - so `setState(() => { throw error })` from inside an
+  // async .catch handler throws immediately in that microtask, outside any render call stack and outside
+  // any try/catch, producing an unhandled rejection instead of reaching the boundary. Stash the error in
+  // a ref and force a re-render instead; the throw then happens inside this hook's own render call.
+  const pendingError = ReactCompat.useRef<{ error: unknown } | null>(null);
+  const [, forceRender] = ReactCompat.useState(0);
+
+  const dispatch = ReactCompat.useCallback(
+    (payload: Payload) => {
+      setPending(count => count + 1);
+      // Chain in dispatch order against the latest settled state. A rejected
+      // action leaves the previous state in place (matching React, where the
+      // error propagates to the nearest error boundary via the transition) and
+      // must not poison the queue for later dispatches.
+      chain.current = chain.current.then(async () => {
+        try {
+          const redirectsBefore = actionRedirectCount();
+          const next = (await action(lastSettled.current, payload));
+          // A redirect renders the destination's initial form state even when
+          // the shared layout island itself survives the navigation.
+          if (next === undefined && actionRedirectCount() !== redirectsBefore) {
+            lastSettled.current = initialRef.current!.value;
+            setState(() => initialRef.current!.value);
+            return;
+          }
+          lastSettled.current = next;
+          setState(() => next);
+        } finally {
+          setPending(count => count - 1);
+        }
+      });
+      // React propagates action errors to the nearest error boundary (they
+      // are not catchable at the dispatch site). Stash it and force a render:
+      // a class error boundary in the tree catches the throw below; without
+      // one the uncaught render error reaches the window 'error' event, where
+      // the compat entry's error.js overlay picks it up.
+      chain.current = chain.current.catch(error => {
+        if (!process.browser && typeof window === 'undefined') return;
+        pendingError.current = { error };
+        forceRender(count => count + 1);
+      });
+    },
+    [action],
+  );
+
+  if (pendingError.current) {
+    const { error } = pendingError.current;
+    pendingError.current = null;
+    throw error;
+  }
+
+  tagFormStateDispatch(dispatch, action, state, _permalink);
+  return [state, dispatch, pending > 0];
+}
+
+/**
+ * Form-state metadata attached to a useActionState dispatch so the server
+ * renderer can progressively enhance <form action={dispatch}>: the underlying
+ * action (for its wire id), the state at render time (posted back in a hidden
+ * field so the server can run `action(state, formData)` without JS), and the
+ * optional permalink target.
+ */
+export interface FormStateDispatchMeta {
+  action: (state: never, payload: never) => unknown;
+  state: unknown;
+  permalink?: string;
+}
+
+function tagFormStateDispatch(
+  dispatch: (payload: never) => void,
+  action: (state: never, payload: never) => unknown,
+  state: unknown,
+  permalink?: string,
+) {
+  (dispatch as unknown as { $$pnextFormState?: FormStateDispatchMeta }).$$pnextFormState = {
+    action: action,
+    state,
+    ...(permalink !== undefined ? { permalink } : {}),
+  };
+}
+
+/**
+ * Consumed-once initial-state override for useActionState, published either by
+ * the server before re-rendering a page for a progressive form submission, or
+ * by the inline hydration script that mirrors it to the client.
+ */
+/** Redirect counter the action-client runtime bumps (see markActionRedirected). */
+function actionRedirectCount(): number {
+  return (globalThis as { __pnextActionRedirects?: number }).__pnextActionRedirects ?? 0;
+}
+
+export function consumeActionStateOverride(): { value: unknown } | undefined {
+  const holder = globalThis as { __PNEXT_ACTION_STATE__?: unknown };
+  if (!('__PNEXT_ACTION_STATE__' in holder)) return undefined;
+  const override = holder.__PNEXT_ACTION_STATE__;
+  if (
+    override !== null &&
+    typeof override === 'object' &&
+    'skip' in override &&
+    typeof override.skip === 'number' &&
+    override.skip > 0
+  ) {
+    override.skip--;
+    return undefined;
+  }
+  delete holder.__PNEXT_ACTION_STATE__;
+  return {
+    value:
+      override !== null && typeof override === 'object' && 'value' in override
+        ? override.value
+        : override,
+  };
+}
+
+/**
+ * React 19's useTransition, on preact hooks. preact/compat's own useTransition is a no-op stub that never
+ * tracks pending state, so an async transition callback's in-flight window is invisible. Track it with a
+ * counter: startTransition(cb) runs cb, and when cb returns a thenable holds `isPending` true until it
+ * settles. Concurrent transitions overlap, each incrementing and decrementing, so isPending stays true
+ * while ANY is in flight - matching React.
+ */
+export function useTransition(): [boolean, (callback: () => void | Promise<void>) => void] {
+  if (!hooksUsable()) return [false, callback => void callback()];
+  const [pending, setPending] = ReactCompat.useState(0);
+  const startTransition = ReactCompat.useCallback((callback: () => void | Promise<void>) => {
+    const mpaBefore = (globalThis as { __pnextMpaNavigation?: number }).__pnextMpaNavigation ?? 0;
+    let result: void | Promise<void>;
+    try {
+      result = callback();
+    } catch {
+      return;
+    }
+    const mpaAfter = (globalThis as { __pnextMpaNavigation?: number }).__pnextMpaNavigation ?? 0;
+    if (mpaAfter !== mpaBefore) {
+      setPending(count => count + 1);
+      return;
+    }
+    if (result && typeof (result as PromiseLike<unknown>).then === 'function') {
+      setPending(count => count + 1);
+      void Promise.resolve(result).finally(() => setPending(count => count - 1));
+    }
+  }, []);
+  return [pending > 0, startTransition];
+}
+
+/**
+ * React 19's useOptimistic, on preact hooks (simplified: the optimistic value
+ * resets whenever the passthrough (base) value changes on a rerender, which is
+ * when the real state has caught up).
+ */
+export function useOptimistic<State, Payload = State>(
+  passthrough: State,
+  reducer?: (state: State, payload: Payload) => State,
+): [State, (payload: Payload) => void] {
+  if (!hooksUsable()) return [passthrough, () => undefined];
+  const [optimistic, setOptimistic] = ReactCompat.useState<{ value: State } | null>(null);
+  const lastBase = ReactCompat.useRef(passthrough);
+  if (lastBase.current !== passthrough) {
+    lastBase.current = passthrough;
+    if (optimistic) setOptimistic(null);
+  }
+  const dispatch = ReactCompat.useCallback(
+    (payload: Payload) => {
+      setOptimistic(current => ({
+        value: reducer
+          ? reducer(current ? current.value : lastBase.current, payload)
+          : (payload as unknown as State),
+      }));
+    },
+    [reducer],
+  );
+  return [optimistic ? optimistic.value : passthrough, dispatch];
+}
+
+interface TrackedThenable<T> extends PromiseLike<T> {
+  status?: 'pending' | 'fulfilled' | 'rejected';
+  value?: T;
+  reason?: unknown;
+}
+
+// Replay state for use() in server components: the renderer replays a component
+// after a thrown thenable settles, and use() call N must resolve to the thenable
+// recorded on the previous attempt (the rerun creates a fresh promise).
+export interface UseThenableState {
+  thenables: TrackedThenable<unknown>[];
+}
+
+let activeUseState: UseThenableState | null = null;
+let activeUseIndex = 0;
+
+export function withUseThenableState<T>(state: UseThenableState, run: () => T): T {
+  const previousState = activeUseState;
+  const previousIndex = activeUseIndex;
+  activeUseState = state;
+  activeUseIndex = 0;
+  try {
+    return run();
+  } finally {
+    activeUseState = previousState;
+    activeUseIndex = previousIndex;
+  }
+}
+
+// React 19's use(): unwrap a thenable via suspense, or read a context.
+export function use<T>(usable: PromiseLike<T> | Parameters<typeof ReactCompat.useContext>[0]): T {
+  if (usable && typeof (usable as PromiseLike<T>).then === 'function') {
+    let thenable = usable as TrackedThenable<T>;
+    if (activeUseState) {
+      const index = activeUseIndex++;
+      const existing = activeUseState.thenables[index];
+      if (existing) thenable = existing as TrackedThenable<T>;
+      else activeUseState.thenables[index] = thenable;
+    }
+    if (thenable.status === 'fulfilled') return thenable.value as T;
+    if (thenable.status === 'rejected') throw thenable.reason;
+    if (thenable.status !== 'pending') {
+      thenable.status = 'pending';
+      thenable.then(
+        value => {
+          thenable.status = 'fulfilled';
+          thenable.value = value;
+        },
+        reason => {
+          thenable.status = 'rejected';
+          thenable.reason = reason;
+        },
+      );
+    }
+    // React use() protocol: suspend by throwing the thenable itself.
+    // eslint-disable-next-line @typescript-eslint/only-throw-error
+    throw thenable;
+  }
+  return ReactCompat.useContext(usable as Parameters<typeof ReactCompat.useContext>[0]) as T;
+}

package/src/compat/react/react-server.ts

@@ -0,0 +1,84 @@
+// True `react-server` condition entry - used ONLY for modules Next compiles under the react-server layer
+// proper: proxy/middleware and RSC/server-action graphs. Unlike ./server.ts, which keeps no-op hook stubs
+// as NAMED exports for pages/api backward compatibility, this module must NOT expose client hook APIs at
+// all: real React's react-server entry has no hook dispatcher, so useState/useEffect are absent from the
+// module's export list entirely, not merely undefined on the default object.
+export {
+  Children,
+  Component,
+  Fragment,
+  PureComponent,
+  StrictMode,
+  Suspense,
+  SuspenseList,
+  cloneElement,
+  createContext,
+  createElement,
+  createFactory,
+  createPortal,
+  createRef,
+  findDOMNode,
+  flushSync,
+  forwardRef,
+  hydrate,
+  isFragment,
+  isMemo,
+  isValidElement,
+  lazy,
+  memo,
+  render,
+  startTransition,
+  unmountComponentAtNode,
+  unstable_batchedUpdates,
+  useId,
+  useContext,
+  // React's own react-server entry exports these three alongside useId/use, so
+  // mirror it — a server component may legitimately call them.
+  useMemo,
+  useCallback,
+  useDebugValue,
+  use,
+  useActionState,
+  useOptimistic,
+  version,
+} from './preact';
+export { cache } from '../../api/cache';
+
+import { ViewTransition, addTransitionType } from './view-transition';
+export { ViewTransition, addTransitionType };
+
+import { currentPrerenderScope } from '../../ppr';
+import { currentCacheSignal } from '../../cache/context';
+
+// React.cacheSignal(): the AbortSignal for the current render. During a build
+// prerender it is the prerender scope's signal; during a request/dynamic render
+// it is the cache scope's. Null outside any render. Slow cache components bound
+// their polling on it (see cache-components ppr-partial-hydration).
+export function cacheSignal(): AbortSignal | null {
+  const prerender = currentPrerenderScope();
+  if (prerender) return prerender.signal;
+  return currentCacheSignal();
+}
+
+import ReactCompat from './preact';
+import { cache as serverCache } from '../../api/cache';
+
+const ReactServer = { ...ReactCompat } as typeof ReactCompat & {
+  cache: typeof serverCache;
+  cacheSignal: typeof cacheSignal;
+};
+delete (ReactServer as { useState?: unknown }).useState;
+delete (ReactServer as { useEffect?: unknown }).useEffect;
+delete (ReactServer as { useLayoutEffect?: unknown }).useLayoutEffect;
+delete (ReactServer as { useInsertionEffect?: unknown }).useInsertionEffect;
+delete (ReactServer as { useImperativeHandle?: unknown }).useImperativeHandle;
+delete (ReactServer as { useReducer?: unknown }).useReducer;
+delete (ReactServer as { useRef?: unknown }).useRef;
+delete (ReactServer as { useDeferredValue?: unknown }).useDeferredValue;
+delete (ReactServer as { useTransition?: unknown }).useTransition;
+delete (ReactServer as { useSyncExternalStore?: unknown }).useSyncExternalStore;
+ReactServer.cache = serverCache;
+ReactServer.cacheSignal = cacheSignal;
+Object.assign(ReactServer, { ViewTransition, addTransitionType });
+
+export default ReactServer;

package/src/compat/react/router-shim.ts

@@ -0,0 +1,26 @@
+// Next's window.next router shim (COMPAT). Injected into the streamed document
+// body so legacy `window.next.router` callers (tests eval it, older libraries
+// poke it) see a pages-router-shaped surface: isReady, pathname/asPath/query
+// backed by the __PNEXT_PAGES_DATA__ JSON node the materialized pages wrappers
+// emit (fallback: location), and push/replace that prefer the soft-navigation
+// runtime (window.__PNEXT_ROUTER__) with a hard-navigation fallback.
+export function nextRouterShimScript(): string {
+  return (
+    '<script>window.next=window.next||{};window.next.version=window.next.version||"16.3.0";(function(){' +
+    'var r=window.next.router=window.next.router||{};' +
+    'function d(){try{var n=document.getElementById("__PNEXT_PAGES_DATA__");' +
+    'return n&&n.textContent?JSON.parse(n.textContent):null}catch(e){return null}}' +
+    'function q(){var s=d(),o={};if(s&&s.query){for(var k in s.query)o[k]=s.query[k]}' +
+    'new URLSearchParams(location.search).forEach(function(v,k){if(k!=="_rsc")o[k]=v});return o}' +
+    'r.isReady=true;r.isFallback=r.isFallback||false;' +
+    'if(!Object.getOwnPropertyDescriptor(r,"query"))Object.defineProperty(r,"query",{get:q,configurable:true});' +
+    'if(!Object.getOwnPropertyDescriptor(r,"pathname"))Object.defineProperty(r,"pathname",{get:function(){var s=d();return(s&&s.pathname)||location.pathname},configurable:true});' +
+    'if(!Object.getOwnPropertyDescriptor(r,"asPath"))Object.defineProperty(r,"asPath",{get:function(){return location.pathname+location.search},configurable:true});' +
+    'r.push=r.push||function(href){var s=String(href);' +
+    'if(window.__PNEXT_ROUTER__&&window.__PNEXT_ROUTER__.navigate){return window.__PNEXT_ROUTER__.navigate(s).then(function(){return true})}' +
+    'location.assign(s);return Promise.resolve(true)};' +
+    'r.replace=r.replace||function(href){location.replace(String(href));return Promise.resolve(true)};' +
+    'r.prefetch=r.prefetch||function(){return Promise.resolve(null)};' +
+    '})();</script>'
+  );
+}

package/src/compat/react/server-component-use.ts

@@ -0,0 +1,48 @@
+// use() replay for server components (COMPAT - react).
+//
+// React 19's use() suspends a synchronous component by throwing a thenable; once the thenable settles
+// the renderer replays the component from the top, and use() call N must resolve to the thenable it
+// recorded on the previous attempt, since the rerun creates fresh promises. preact has no such
+// machinery, so this wraps a single server-component invocation with that replay loop:
+//
+//   - a fresh UseThenableState tracks the thenables use() sees, indexed by call order.
+//   - the invocation runs inside that state scope. If a synchronous component throws the thenable use()
+//     suspended on, it is awaited and the component replays with the SAME state, so the next attempt's
+//     use() call reads the now-settled tracked thenable and returns its value.
+//   - a non-thenable throw propagates unchanged.
+//   - an async component returns a promise and awaits its own use() promises, so it needs no replay.
+//
+// Registered onto renderExtensions.wrapServerComponentInvoke; a pure-core app keeps the pass-through
+// default and never loads this module.
+
+import { withUseThenableState, type UseThenableState } from './preact';
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as PromiseLike<unknown>).then === 'function'
+  );
+}
+
+/**
+ * Run a server-component invocation with use()-replay support. Synchronous
+ * components that suspend via use() are awaited and replayed against the same
+ * thenable state; async components (and plain returns) pass through.
+ */
+export function invokeServerComponentWithUse<T>(invoke: () => T): T {
+  const state: UseThenableState = { thenables: [] };
+
+  const attempt = (): T => {
+    try {
+      return withUseThenableState(state, invoke);
+    } catch (error) {
+      // A pending use() thenable suspends the component: await it, then replay
+      // with the same state so the settled thenable resolves in place.
+      if (isThenable(error)) return Promise.resolve(error).then(attempt, attempt) as T;
+      throw error;
+    }
+  };
+
+  return attempt();
+}