@wular/pnext 0.0.2 → 0.0.4

package/src/compat/next/link-validation-transform.ts

@@ -6,7 +6,11 @@
 // build-time-only dependency that also shipped into the deployed function. The gate is
 // module-record-shaped (does this file import next/link at all), so the AST is only ever materialized
 // for a file that really uses one.
-import { parseSync } from 'oxc-parser';
+// Lazy: the oxc-parser native binding costs ~12.6 MB RSS; load it only when a parse happens.
+const parseSync: typeof import('oxc-parser').parseSync = (...args) =>
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  loadNative(() => require('oxc-parser') as typeof import('oxc-parser')).parseSync(...args);
+import { loadNative } from '../../utils/native-require';
 import { rewriteFacts } from '../../resolve/scan-facts';
 
 const marker = '__pnextLegacyChildKind';

package/src/compat/next/link.tsx

@@ -1,18 +1,10 @@
-import {
-  Children,
-  cloneElement,
-  createElement,
-  forwardRef,
-  useContext,
-  useEffect,
-  useRef,
-  useState,
-  type MutableRefObject,
-  type ReactElement,
-  type ReactNode,
-  type Ref,
-} from 'preact/compat';
-import type { JSX } from 'preact';
+// preact core + hooks only (no preact/compat): this module rides in every compat app's first-page
+// bundle, and the lite client tier must not pull compat through it. Children.only/count are replaced
+// with toChildArray below; the ref arrives React-19-style as a prop (the parity vnode pass moves
+// vnode.ref into props for function components).
+import { cloneElement, h as createElement, toChildArray, type JSX } from 'preact';
+import { useContext, useEffect, useRef, useState } from 'preact/hooks';
+import type { MutableRefObject, ReactElement, ReactNode, Ref } from 'react';
 import { usePrefetchLifecycle } from '../../api/link';
 import { blockJavascriptUrl, isJavascriptUrl } from '../../api/router';
 import { applyTrailingSlash, routeHref, type SearchInput } from '../../routing/href';
@@ -78,28 +70,28 @@ export type LinkProps = Omit<JSX.HTMLAttributes<HTMLAnchorElement>, 'href' | 'on
   children?: ReactNode;
 };
 
-const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
-  {
-    href,
-    as,
-    prefetch = null,
-    unstable_dynamicOnHover,
-    replace,
-    scroll,
-    locale: _locale,
-    legacyBehavior,
-    passHref,
-    onClick,
-    onNavigate,
-    transitionTypes,
-    onPrefetchStart,
-    onPrefetchFinish,
-    __pnextLegacyChildKind,
-    children,
-    ...anchorProps
-  },
-  forwardedRef,
-) {
+// Ref arrives as a prop (React 19 style): the parity vnode pass moves vnode.ref into props for plain
+// function components, on both server and client, so forwardRef is unnecessary.
+function Link({
+  href,
+  as,
+  prefetch = null,
+  unstable_dynamicOnHover,
+  replace,
+  scroll,
+  locale: _locale,
+  legacyBehavior,
+  passHref,
+  onClick,
+  onNavigate,
+  transitionTypes,
+  onPrefetchStart,
+  onPrefetchFinish,
+  __pnextLegacyChildKind,
+  children,
+  ref: forwardedRef,
+  ...anchorProps
+}: LinkProps) {
   // `as` supersedes `href` for what the anchor actually points at (app router).
   const target = as == null ? href : as;
   // basePath: prefix in-app hrefs so the rendered anchor (and the soft-nav it
@@ -206,7 +198,7 @@ const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
     anchorAttributes,
     createElement(LinkStatusContext.Provider, { value: { pending: linkPending(statusToken) } }, children),
   ) as ReactElement;
-});
+}
 
 export default Link;
 export { Link };
@@ -241,6 +233,10 @@ function renderLegacyChild(
   const isDev = process.env.NODE_ENV !== 'production';
   const isServer = !process.browser && typeof window === 'undefined';
 
+  // A React.lazy payload passed directly (not wrapped in JSX) never resolves to
+  // a single element child; Next reports it specifically instead of Children.only.
+  if (isLazyComponent(children)) throw unsupportedLegacyChildError();
+
   if (children == null || children === false) {
     if (isDev) {
       throw validationError(
@@ -253,10 +249,10 @@ function renderLegacyChild(
 
   // A bare string/number child renders its own <a> (Next's legacy behavior).
   if (typeof children === 'string' || typeof children === 'number') {
-    return createElement('a', { ...anchorAttributes, href: resolvedHref }, children);
+    return createElement('a', { ...anchorAttributes, href: resolvedHref }, children) as unknown as ReactElement;
   }
 
-  const count = Children.count(children);
+  const count = toChildArray(children as JSX.Element).length;
   if (count > 1) {
     if (isDev) {
       throw validationError(
@@ -267,7 +263,7 @@ function renderLegacyChild(
     return childrenOnlyOrThrow(children);
   }
 
-  const child = Children.only(children) as ReactElement<Record<string, unknown>>;
+  const child = childrenOnlyOrThrow(children) as ReactElement<Record<string, unknown>>;
   const kind =
     annotatedKind ??
     (isAsyncFunctionComponent(child.type)
@@ -313,7 +309,7 @@ function renderLegacyChild(
     childProps['data-pnext-replace'] = anchorAttributes['data-pnext-replace'];
     childProps['data-pnext-scroll'] = anchorAttributes['data-pnext-scroll'];
   }
-  return cloneElement(child, childProps);
+  return cloneElement(child as never, childProps) as ReactElement;
 }
 
 function reportUnsupportedServerChild(kind: LegacyChildKind, isDev: boolean) {
@@ -353,17 +349,16 @@ function validationError(message: string, digest: string) {
   return Object.assign(new Error(message), { digest });
 }
 
-// preact/compat's `Children.only` throws a bare string ("Children.only")
-// instead of an Error, and its message doesn't match React's. Production
-// builds (no dev-mode validation) fall through to native Children.only
-// semantics for the no-children/multiple-children cases, so reproduce React's
-// exact wording here rather than surfacing preact's own throw.
+// React.Children.only semantics on preact core: exactly one element child, with
+// React's exact error wording for the no-children/multiple-children cases.
 function childrenOnlyOrThrow(children: ReactNode): ReactElement {
-  try {
-    return Children.only(children) as ReactElement;
-  } catch {
-    throw new Error('React.Children.only expected to receive a single React element child.');
-  }
+  const array = toChildArray(children as JSX.Element);
+  if (array.length === 1 && isValidElementLike(array[0])) return array[0] as ReactElement;
+  throw new Error('React.Children.only expected to receive a single React element child.');
+}
+
+function isValidElementLike(value: unknown) {
+  return value !== null && typeof value === 'object' && 'type' in value;
 }
 
 function isAsyncFunctionComponent(type: unknown) {
@@ -373,11 +368,9 @@ function isAsyncFunctionComponent(type: unknown) {
 }
 
 function isLazyComponent(type: unknown) {
-  return (
-    type !== null &&
-    typeof type === 'object' &&
-    (type as { $$typeof?: unknown }).$$typeof === Symbol.for('react.lazy')
-  );
+  if (type === null || (typeof type !== 'object' && typeof type !== 'function')) return false;
+  const marked = type as { $$typeof?: unknown } & Record<symbol, unknown>;
+  return marked.$$typeof === Symbol.for('react.lazy') || marked[Symbol.for('pnext.lazy')] === true;
 }
 
 function isServerComponent(type: unknown) {
@@ -413,7 +406,7 @@ function assignRef(ref: Ref<HTMLAnchorElement> | undefined, node: HTMLAnchorElem
     ref(node);
     return;
   }
-  (ref as MutableRefObject<HTMLAnchorElement | null>).current = node;
+  ref.current = node;
 }
 
 function hrefString(href: string | URL | UrlObject) {

package/src/compat/pages/client-plugin.ts

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { build as esbuild, type Loader, type OnLoadResult, type Plugin } from 'esbuild';
+import type { Loader, OnLoadResult, Plugin } from 'esbuild';
+import { build as esbuild } from '../../utils/esbuild';
 import type { ResolvedConfig } from '../../config';
 import { applyClientSourceTransforms, getBundlerExtensions } from '../../extensions';
 

package/src/compat/react/action-state.ts

@@ -0,0 +1,159 @@
+import { useCallback, useRef, useState } from 'preact/hooks';
+import { hooksUsable } from './hooks-extra';
+
+/**
+ * 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 = 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] = useState<Awaited<State>>(initialRef.current.value);
+  const [pending, setPending] = useState(0);
+  const lastSettled = useRef<Awaited<State>>(initialRef.current.value);
+  const chain = 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 = useRef<{ error: unknown } | null>(null);
+  const [, forceRender] = useState(0);
+
+  const dispatch = 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,
+  };
+}
+

package/src/compat/react/client-lite.ts

@@ -0,0 +1,74 @@
+// Lite client `react` alias for compat apps whose client graph provably never suspends and only uses
+// the core-preact-equivalent React surface (see clientCompatSurface in src/client/compat-surface.ts).
+// Everything here is backed by preact core + preact/hooks, so the bundle ships no preact/compat. The
+// parity import wires the same vnode pass (React 19 ref prop, primitive-throw safety) as the full shim.
+import './parity';
+import {
+  Component,
+  Fragment,
+  cloneElement,
+  createContext,
+  createElement,
+  createRef,
+  isValidElement,
+} from 'preact';
+import {
+  useCallback,
+  useContext,
+  useDebugValue,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from 'preact/hooks';
+import { useOptimistic, useTransition } from './hooks-extra';
+import { useActionState } from './action-state';
+
+export {
+  Component,
+  Fragment,
+  cloneElement,
+  createContext,
+  createElement,
+  createRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useDebugValue,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useActionState,
+  useOptimistic,
+  useTransition,
+};
+export { ViewTransition, addTransitionType } from './view-transition';
+
+// Same passthrough semantics preact/compat gives these.
+export const StrictMode = Fragment;
+export const startTransition = (callback: () => void) => callback();
+export const useDeferredValue = <T>(value: T): T => value;
+export const useInsertionEffect = useLayoutEffect;
+export const version = '19.0.0';
+
+export function cache<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  return (...args: Args) => fn(...args);
+}
+
+export function cacheSignal() {
+  return null;
+}
+
+// No default export: the surface scan already forces the full tier for any app doing
+// `import React from 'react'`, and a default object here would pin every export against treeshaking.

package/src/compat/react/hooks-extra.ts

@@ -0,0 +1,92 @@
+import { options, type VNode } from 'preact';
+import { useCallback, useRef, useState } from 'preact/hooks';
+
+// React 19 hooks (use, useActionState, useOptimistic, useTransition) implemented directly on
+// preact/hooks so a suspense-free client bundle can ship them without preact/compat. The full shim
+// re-exports these same functions - one implementation, both surfaces.
+
+// 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;
+
+export 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 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] = useState(0);
+  const startTransition = 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] = useState<{ value: State } | null>(null);
+  const lastBase = useRef(passthrough);
+  if (lastBase.current !== passthrough) {
+    lastBase.current = passthrough;
+    if (optimistic) setOptimistic(null);
+  }
+  const dispatch = 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];
+}
+

package/src/compat/react/parity.ts

@@ -0,0 +1,128 @@
+import { options, 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;
+}
+
+// Suspense-dependent parity (thenable children, async client components) needs preact/compat, which a
+// suspense-free client bundle never ships. The full shim registers it on import; the lite path leaves
+// the slot empty and its bundle drops preact/compat entirely. Two phases: async-component wrapping must
+// see the raw component (before primitive-throw wraps it); thenable children run after.
+interface SuspenseParity {
+  beforeThrowSafety(vnode: VNode): void;
+  afterThrowSafety(vnode: VNode): void;
+}
+
+let suspenseParity: SuspenseParity | undefined;
+
+export function setSuspenseParity(pass: SuspenseParity): void {
+  suspenseParity = pass;
+}
+
+const pnextOptions = options as PNextPreactOptions;
+if (!pnextOptions[react19RefCompatInstalled]) {
+  const previousVNode = options.vnode?.bind(options);
+  options.vnode = vnode => {
+    previousVNode?.(vnode);
+    if (!reactCompatActive) return;
+    applyReact19RefProp(vnode);
+    suspenseParity?.beforeThrowSafety(vnode);
+    applyPrimitiveThrowSafety(vnode);
+    suspenseParity?.afterThrowSafety(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 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;
+}