@wular/pnext 0.0.19 → 0.0.20

package/src/compat/next/font/cache.ts

@@ -9,15 +9,17 @@
 // Nothing here is used by `pnext build`, which owns the directory it just wiped.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { mkdir, stat } from 'node:fs/promises'
-import { createHash } from 'node:crypto'
 import path from 'node:path'
 import type { ResolvedConfig } from '../../../config'
 import { restartCacheEnabled } from '../../../dev/restart/enabled'
+import { frameworkFingerprint } from '../../../runtime/fingerprint'
 import { writeFileAtomic } from '../../../utils/fs'
 import type { MetadataLink } from '../../../types'
 
 export interface PersistableFont {
   css: string
+  /** Whether the resolution shipped a size-adjusted fallback face (Next's `next-size-adjust` meta). */
+  sizeAdjust: boolean
   preloads: MetadataLink[]
   usesFonts: boolean
   files: string[]
@@ -34,13 +36,13 @@ interface Entry extends PersistableFont {
 
 interface IndexFile {
   version: number
-  /** Content hash of the font runtime, so an upgrade never serves its output. */
+  /** pnext's generation, so an upgrade never serves the previous framework's output. */
   runtime: string
   fonts: Record<string, Entry>
 }
 
 /** Bumped whenever a record's shape changes; an older index is simply ignored. */
-const INDEX_VERSION = 1
+const INDEX_VERSION = 2
 
 interface FontIndex {
   file: string
@@ -150,22 +152,8 @@ function serializeIndex(fonts: Map<string, Entry>) {
   } satisfies IndexFile)
 }
 
-// The CSS a resolution emits is shaped entirely by this directory's sources, so
-// editing the font runtime must retire its records the same way editing a font
-// does. Four small files, once per process.
-let fingerprint: string | undefined
-
-function runtimeFingerprint() {
-  if (fingerprint !== undefined) return fingerprint
-  const hash = createHash('sha256')
-  for (const entry of ['runtime.ts', 'google.ts', 'local.ts', 'shared.ts']) {
-    const file = new URL(entry, import.meta.url).pathname
-    try {
-      hash.update(`${entry}:${Bun.hash(readFileSync(file)).toString(36)}\0`)
-    } catch {
-      // ignore unreadable entries
-    }
-  }
-  fingerprint = hash.digest('hex').slice(0, 16)
-  return fingerprint
-}
+// A recorded resolution IS framework output - its css, its preloads, its emitted file names - so it
+// follows pnext's generation, the same one every other compiled artifact is keyed on. Never a
+// hand-picked file list: this hashed four files in this directory and was blind to every other
+// source the resolution reads (utils/code, the asset emitter, this file's own record rule).
+const runtimeFingerprint = () => frameworkFingerprint()

package/src/compat/next/font/runtime.ts

@@ -37,6 +37,8 @@ export type {
 
 interface FontScope {
   fonts: Map<string, FontDefinition>
+  /** Set once a resolved font in this render shipped a size-adjusted fallback face. */
+  sizeAdjust?: boolean
 }
 
 interface FontDefinition {
@@ -61,6 +63,8 @@ export interface ResolvedFontAssets {
 
 interface ResolvedFont {
   css: string
+  /** Whether this font emitted a size-adjusted fallback face (drives Next's `next-size-adjust` meta). */
+  sizeAdjust: boolean
   /** Preloadable font links (empty when `preload:false`). Delivered via the
    * `Link` response header in prod, not as HTML `<link>` tags. */
   preloads: MetadataLink[]
@@ -174,6 +178,7 @@ export async function fontAssets(
   // tags). Stash them on the request work unit; the response finalizer
   // (registerFontResponseFinalizer) reads them back and sets the header.
   stashHeaderPreloads(preloads)
+  if (resolved.some(font => font.sizeAdjust)) scope.sizeAdjust = true
 
   const usesFonts = resolved.some(font => font.usesFonts)
   return {
@@ -211,6 +216,19 @@ export function fontPreloadDomScript(): string {
   )
 }
 
+/**
+ * Next's `<meta name="next-size-adjust">` marker, emitted once per document whenever any next/font in
+ * the render shipped a metrics-adjusted fallback face (`appUsingSizeAdjustment`). The flag lives on the
+ * render's own font scope, so it can neither leak across requests nor depend on a work unit a
+ * build-time render does not have.
+ */
+export function fontSizeAdjustMeta(): string {
+  // Byte-for-byte with Next, empty `content` included.
+  return fontStorage.getStore()?.sizeAdjust === true
+    ? '<meta name="next-size-adjust" content=""/>'
+    : ''
+}
+
 function stashHeaderPreloads(preloads: MetadataLink[]): void {
   if (preloads.length === 0) return
   const unit = getWorkUnit()
@@ -463,6 +481,7 @@ async function resolveGoogleFont(
 
   return {
     usesFonts: emitted.length > 0,
+    sizeAdjust: adjustFontFallback,
     css: scopedCss,
     preloads: emitted
       .filter(item => item.preloadFontFile)
@@ -517,6 +536,7 @@ async function resolveLocalFont(
 
   return {
     usesFonts: emitted.length > 0,
+    sizeAdjust: adjustFontFallback,
     css: [
       ...faceCss,
       adjustFontFallback ? fallbackFaceCss(request.fontFamily) : '',

package/src/compat/next/legacy-request-apis.ts

@@ -1,10 +1,12 @@
 // Next 15's transitional sync request APIs, behind compat.next.legacyRequestAPIs. cookies()/headers()/
 // draftMode() still return a Promise, but that promise also carries the resolved value's surface, so
-// Next-14-era code (`cookies().get('x')`) keeps working while it migrates to `await`. Each sync access
-// logs Next's sync-dynamic-apis deprecation warning, deduped by userland callsite.
+// Next-14-era code (`cookies().get('x')`) keeps working while it migrates to `await`. `params` and
+// `searchParams` get the same treatment (`params.creator` without `await`). Each sync access logs
+// Next's sync-dynamic-apis deprecation warning, deduped by userland callsite.
 //
 // Nothing here is reachable — or even allocated — when the option is off.
 
+import { legacyRequestAPIs } from '../../request/context'
 import { currentRenderCacheMeta } from '../cache/revalidate'
 
 const PROMISE_PROPS = new Set<PropertyKey>(['then', 'catch', 'finally', 'constructor'])
@@ -29,7 +31,7 @@ export function withSyncAccess<T extends object>(
           ? (own as (...args: unknown[]) => unknown).bind(target)
           : own
       }
-      warnSyncAccess(api, prop)
+      warnSyncApiAccess(api, prop)
       const source = resolve() as object
       const read: unknown = Reflect.get(source, prop, source)
       return typeof read === 'function'
@@ -39,18 +41,52 @@ export function withSyncAccess<T extends object>(
   })
 }
 
-function warnSyncAccess(api: string, prop: PropertyKey): void {
+/**
+ * Give a settled `params`/`searchParams` promise the resolved object's own keys, so Next-14 code
+ * (`function Layout({ params }) { params.creator }`) reads them without `await`. Keys the promise
+ * already answers for (then/catch/status/value/constructor/...) stay the promise's — Next skips them
+ * too — and the promise itself is returned, never a copy or a Proxy: callers hand it to `use()`.
+ */
+export function withSyncProps<T extends object>(
+  promise: Promise<T>,
+  kind: 'params' | 'searchParams',
+  value: T,
+): Promise<T> {
+  if (!legacyRequestAPIs()) return promise
+  for (const key of Object.keys(value)) {
+    if (key in promise) continue
+    void Object.defineProperty(promise, key, {
+      get() {
+        warnSyncPropAccess(kind, key)
+        return (value as Record<string, unknown>)[key]
+      },
+      enumerable: true,
+      configurable: true,
+    })
+  }
+  return promise
+}
+
+function warnSyncApiAccess(api: string, prop: PropertyKey): void {
   const expression =
     prop === Symbol.iterator
       ? `\`...${api}()\` or similar iteration`
       : `\`${api}().${String(prop)}\``
+  warnSyncAccess(expression, `${api}()`, 'value')
+}
+
+function warnSyncPropAccess(kind: string, key: string): void {
+  warnSyncAccess(`\`${kind}.${key}\``, kind, 'properties')
+}
+
+function warnSyncAccess(expression: string, subject: string, noun: 'value' | 'properties'): void {
   const route = currentRenderCacheMeta()?.route
   const key = `${route ?? ''}|${expression}|${callsite()}`
   if (warned.has(key)) return
   warned.add(key)
   console.warn(
     `${route ? `Route "${route}" ` : 'This route '}used ${expression}. ` +
-      `\`${api}()\` should be awaited before using its value. ` +
+      `\`${subject}\` should be awaited before using its ${noun}. ` +
       'Learn more: https://nextjs.org/docs/messages/sync-dynamic-apis',
   )
 }

package/src/compat/next/script.tsx

@@ -2,7 +2,12 @@
 import type { JSX } from 'preact'
 import { escapeHtml } from '../../utils/html'
 import { getNextConfig } from './config-loader'
-import { registerResourceHint } from '../../render/resource-hints'
+import {
+  clearRenderBuffer,
+  registerResourceHint,
+  renderBuffer,
+  takeRenderBuffer,
+} from '../../render/resource-hints'
 
 export type ScriptStrategy = 'beforeInteractive' | 'afterInteractive' | 'lazyOnload' | 'worker'
 
@@ -195,20 +200,15 @@ export interface DeferredScript {
 }
 
 function deferredScripts() {
-  const holder = globalThis as { __PNEXT_DEFERRED_SCRIPTS__?: DeferredScript[] }
-  holder.__PNEXT_DEFERRED_SCRIPTS__ ??= []
-  return holder.__PNEXT_DEFERRED_SCRIPTS__
+  return renderBuffer<DeferredScript>('deferred')
 }
 
 export function clearDeferredScripts() {
-  ;(globalThis as { __PNEXT_DEFERRED_SCRIPTS__?: DeferredScript[] }).__PNEXT_DEFERRED_SCRIPTS__ = []
+  clearRenderBuffer('deferred')
 }
 
 export function takeDeferredScripts() {
-  const holder = globalThis as { __PNEXT_DEFERRED_SCRIPTS__?: DeferredScript[] }
-  const scripts = holder.__PNEXT_DEFERRED_SCRIPTS__ ?? []
-  holder.__PNEXT_DEFERRED_SCRIPTS__ = []
-  return scripts
+  return takeRenderBuffer<DeferredScript>('deferred')
 }
 
 // Like scriptAttrs, but building a raw name -> value map (for
@@ -248,16 +248,13 @@ export interface HeadScript {
   content?: string
 }
 
-// The renderer replaces the resource-hints array with a fresh `[]` at the start
-// of every render (clearResourceHints). Keying the executed-set off that array
-// via a WeakMap gives us a dedup scope that lives exactly one render and is
-// garbage-collected with it — no cross-request leakage.
+// The resource-hints buffer is per render (render/resource-hints). Keying the executed-set off that
+// array via a WeakMap gives us a dedup scope that lives exactly one render and is garbage-collected
+// with it — no cross-request leakage.
 const scriptDedupRegistry = new WeakMap<object, Set<string>>()
 
 function executedScriptKeys(): Set<string> {
-  const holder = globalThis as { __PNEXT_RESOURCE_HINTS__?: object }
-  holder.__PNEXT_RESOURCE_HINTS__ ??= []
-  const arr = holder.__PNEXT_RESOURCE_HINTS__
+  const arr = renderBuffer<unknown>('hints')
   let keys = scriptDedupRegistry.get(arr)
   if (!keys) {
     keys = new Set<string>()
@@ -267,20 +264,15 @@ function executedScriptKeys(): Set<string> {
 }
 
 function headScripts() {
-  const holder = globalThis as { __PNEXT_HEAD_SCRIPTS__?: HeadScript[] }
-  holder.__PNEXT_HEAD_SCRIPTS__ ??= []
-  return holder.__PNEXT_HEAD_SCRIPTS__
+  return renderBuffer<HeadScript>('head')
 }
 
 export function clearHeadScripts() {
-  ;(globalThis as { __PNEXT_HEAD_SCRIPTS__?: HeadScript[] }).__PNEXT_HEAD_SCRIPTS__ = []
+  clearRenderBuffer('head')
 }
 
 export function takeHeadScripts() {
-  const holder = globalThis as { __PNEXT_HEAD_SCRIPTS__?: HeadScript[] }
-  const scripts = holder.__PNEXT_HEAD_SCRIPTS__ ?? []
-  holder.__PNEXT_HEAD_SCRIPTS__ = []
-  return scripts
+  return takeRenderBuffer<HeadScript>('head')
 }
 
 export function renderHeadScripts() {

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

@@ -3,6 +3,7 @@
 // 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 './style-values'
 import {
   Component,
   Fragment,

package/src/compat/react/client.ts

@@ -1,3 +1,14 @@
+import './style-values'
+import ReactCompat from './preact'
+import { attachReactInternals } from './internals'
+
+attachReactInternals(ReactCompat)
+
+export {
+  ReactSharedInternals as __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+  ReactClientInternals as __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+} from './internals'
+
 export {
   Children,
   Component,

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

@@ -6,7 +6,7 @@
  * server response-finalization pipeline.
  */
 import ReactCompat from 'preact/compat'
-import { useActionState } from './preact'
+import { useActionState, useSyncExternalStore } from './preact'
 
 const ReactDomCompat = Object.assign(ReactCompat, {
   preload,
@@ -27,6 +27,10 @@ export const flushSync = ReactCompat.flushSync
 export const unmountComponentAtNode = ReactCompat.unmountComponentAtNode
 export const unstable_batchedUpdates = ReactCompat.unstable_batchedUpdates
 export const version = ReactCompat.version
+export {
+  ReactDOMSharedInternals as __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+  ReactDOMSharedInternals as __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+} from './internals'
 
 function noOpRecordResourceHint() {
   // intentionally empty: client bundles do not build response headers.
@@ -106,7 +110,12 @@ function subscribe(listener: () => void) {
 }
 
 export function useFormStatus(): FormStatus {
-  ReactCompat.useSyncExternalStore(subscribe, () => storeVersion)
+  // No submission is ever in flight during a server render, so the counter is its own server value.
+  useSyncExternalStore(
+    subscribe,
+    () => storeVersion,
+    () => storeVersion,
+  )
   return pendingStack.length > 0 ? pendingStack[pendingStack.length - 1]! : NOT_PENDING
 }
 

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

@@ -11,4 +11,8 @@ delete ReactDomServer.useFormStatus
 delete ReactDomServer.requestFormReset
 
 export { preconnect, prefetchDNS, preinit, preload, version }
+export {
+  ReactDOMSharedInternals as __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+  ReactDOMSharedInternals as __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+} from './internals'
 export default ReactDomServer

package/src/compat/react/dom.ts

@@ -14,7 +14,7 @@
  *   uncontrolled forms after a successful action itself.
  */
 import ReactCompat from 'preact/compat'
-import { useActionState } from './preact'
+import { useActionState, useSyncExternalStore } from './preact'
 import { registerResourceHint } from '../../render/resource-hints'
 
 const ReactDomCompat = Object.assign(ReactCompat, {
@@ -36,6 +36,10 @@ export const flushSync = ReactCompat.flushSync
 export const unmountComponentAtNode = ReactCompat.unmountComponentAtNode
 export const unstable_batchedUpdates = ReactCompat.unstable_batchedUpdates
 export const version = ReactCompat.version
+export {
+  ReactDOMSharedInternals as __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+  ReactDOMSharedInternals as __DOM_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+} from './internals'
 
 export function preload(
   href: string,
@@ -143,7 +147,12 @@ function subscribe(listener: () => void) {
 }
 
 export function useFormStatus(): FormStatus {
-  ReactCompat.useSyncExternalStore(subscribe, () => storeVersion)
+  // No submission is ever in flight during a server render, so the counter is its own server value.
+  useSyncExternalStore(
+    subscribe,
+    () => storeVersion,
+    () => storeVersion,
+  )
   return pendingStack.length > 0 ? pendingStack[pendingStack.length - 1]! : NOT_PENDING
 }
 

package/src/compat/react/internals.ts

@@ -0,0 +1,65 @@
+// React publishes its shared internals as a well-known export, and packages that reach into it read
+// fields at MODULE scope - `var ReactCurrentOwner = React.__SECRET_INTERNALS_….ReactCurrentOwner` in
+// react-reconciler, which every custom renderer (react-konva, react-three-fiber, react-pdf, ink) pulls
+// in. preact has no equivalent, so the whole import crashes with a TypeError before a single component
+// renders. The shim publishes React's shape with inert slots: reads resolve, and nothing pretends to be
+// driving a render (real React's slots are null outside one too).
+
+// Field-for-field react@18.3.1 and react@19.2.8, no more: an invented field is weight in every bundle
+// and a lie to whatever reads it.
+export const ReactSharedInternals = {
+  ReactCurrentDispatcher: { current: null },
+  ReactCurrentBatchConfig: { transition: null },
+  ReactCurrentOwner: { current: null },
+  ReactCurrentActQueue: { current: null, isBatchingLegacy: false, didScheduleLegacyUpdate: false },
+  ReactDebugCurrentFrame: { getCurrentStack: null },
+}
+
+/** React 19 renamed both the export and every field (`__CLIENT_INTERNALS_…`). */
+export const ReactClientInternals = {
+  H: null,
+  A: null,
+  T: null,
+  S: null,
+  actQueue: null,
+  asyncTransitions: 0,
+  isBatchingLegacy: false,
+  didScheduleLegacyUpdate: false,
+  didUsePromise: false,
+  thrownErrors: [],
+  getCurrentStack: null,
+  recentlyCreatedOwnerStacks: 0,
+}
+
+/**
+ * react-dom's own internals, under both its React 18 (`usingClientEntryPoint`/`Events`) and React 19
+ * (`d`/`p`/`findDOMNode`) shapes. Named exports only: the `react`/`react-dom` shims share ONE
+ * preact/compat default object, so attaching a react-dom shape to it would shadow react's. Namespace
+ * and CJS-interop reads - how react-dom internals are read in practice - resolve the named export.
+ */
+export const ReactDOMSharedInternals = {
+  usingClientEntryPoint: false,
+  Events: null,
+  d: {},
+  p: 0,
+  findDOMNode: null,
+}
+
+const REACT_18_KEY = '__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED'
+const REACT_19_KEY = '__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE'
+
+/**
+ * Attach both react internals keys to a shim's default export object. preact/compat already publishes
+ * a one-field `ReactCurrentDispatcher`-only object under the React 18 key and reads that dispatcher for
+ * its own `readContext`, so its live slots are folded IN rather than replaced - and folded into the
+ * exported object, keeping one identity for consumers that capture a slot by reference.
+ */
+export function attachReactInternals<Target extends object>(target: Target): Target {
+  const slots = target as Record<string, Record<string, unknown> | undefined>
+  if (slots[REACT_18_KEY]) Object.assign(ReactSharedInternals, slots[REACT_18_KEY])
+  if (slots[REACT_19_KEY]) Object.assign(ReactClientInternals, slots[REACT_19_KEY])
+  return Object.assign(target, {
+    [REACT_18_KEY]: ReactSharedInternals,
+    [REACT_19_KEY]: ReactClientInternals,
+  })
+}

package/src/compat/react/parity.ts

@@ -50,6 +50,7 @@ if (!pnextOptions[react19RefCompatInstalled]) {
     suspenseParity?.beforeThrowSafety(vnode)
     applyPrimitiveThrowSafety(vnode)
     suspenseParity?.afterThrowSafety(vnode)
+    applyStrayDocumentChildren(vnode)
     applyReactTextSeparators(vnode)
   }
   pnextOptions[react19RefCompatInstalled] = true
@@ -77,6 +78,52 @@ if (!pnextOptions[react19RefCompatInstalled]) {
   }
 }
 
+// A root layout may render children directly under `<html>` alongside `<body>` - `<GoogleAnalytics/>`,
+// a `<Script>`, an analytics island. React renders them in place and the browser's parser hoists the
+// result into `<body>`; pnext's document reader keeps only the `<head>`/`<body>` children, so anything
+// else was dropped and never ran (no resource hints, no hydration). Relocate strays to the front of
+// `<body>` - the position the parser would have given them - so the component renders exactly once.
+function applyStrayDocumentChildren(vnode: VNode) {
+  // Server-only: the client never re-reads the document layout (see applyReactTextSeparators).
+  if (process.browser || typeof window !== 'undefined') return
+  if (vnode.type !== 'html') return
+  const props = vnode.props as Record<string, unknown>
+  const children = props.children
+  if (!Array.isArray(children)) return
+
+  const kept: unknown[] = []
+  const stray: unknown[] = []
+  let body: VNode | undefined
+  for (const child of children as unknown[]) {
+    const type = isElementVNode(child) ? child.type : undefined
+    if (type === 'body') body = child as VNode
+    if (type === 'head' || type === 'body' || !mayRenderContent(child)) {
+      kept.push(child)
+      continue
+    }
+    stray.push(child)
+  }
+  if (!body || stray.length === 0) return
+
+  const bodyProps = body.props as Record<string, unknown>
+  const bodyChildren: unknown = bodyProps.children
+  bodyProps.children = [
+    ...stray,
+    ...(Array.isArray(bodyChildren) ? (bodyChildren as unknown[]) : [bodyChildren]),
+  ]
+  props.children = kept
+}
+
+function isElementVNode(value: unknown): value is VNode {
+  return typeof value === 'object' && value !== null && 'type' in value
+}
+
+// Nullish/boolean children and JSX whitespace render nothing, so leaving them under `<html>` is free.
+function mayRenderContent(child: unknown) {
+  if (child == null || typeof child === 'boolean') return false
+  return typeof child === 'string' ? child.trim() !== '' : true
+}
+
 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

package/src/compat/react/preact.ts

@@ -80,11 +80,42 @@ function applyAsyncClientComponent(vnode: VNode) {
   vnode.type = wrapper
 }
 
+// Captured before the augmentation below overwrites the key, or the wrapper would recurse.
+const preactUseSyncExternalStore = ReactCompat.useSyncExternalStore
+
+// preact/compat ignores getServerSnapshot; React uses it for every server render, so without this
+// the client-SSR pass calls the browser snapshot (and app stores touch `window`).
+function serverSnapshotAware<Snapshot>(
+  subscribe: (onStoreChange: () => void) => () => void,
+  getSnapshot: () => Snapshot,
+  getServerSnapshot?: () => Snapshot,
+): Snapshot {
+  if (typeof window === 'undefined') {
+    if (!getServerSnapshot)
+      throw new Error(
+        'Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.',
+      )
+    return getServerSnapshot()
+  }
+  return preactUseSyncExternalStore(subscribe, getSnapshot)
+}
+
+// The browser build folds `process.browser` to true, so it ships preact's function verbatim and
+// tree-shakes the wrapper - the server-only text never reaches the client. Purely a size win: the
+// wrapper is already correct in a browser, so an undefined `process.browser` only costs bytes.
+export const useSyncExternalStore: typeof serverSnapshotAware = process.browser
+  ? preactUseSyncExternalStore
+  : serverSnapshotAware
+
 // React 19 APIs preact/compat lacks - use(), useActionState, useOptimistic (imported above) - 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 })
 
+// `React.useSyncExternalStore` needs the wrapper for the same reason the named export does. The
+// browser folds this to `if (false)` and drops it: preact's own property is already correct there.
+if (!process.browser) ReactCompat.useSyncExternalStore = useSyncExternalStore
+
 export const Children = ReactCompat.Children
 export const Component = ReactCompat.Component
 export const Fragment = ReactCompat.Fragment
@@ -130,5 +161,4 @@ 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

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

@@ -43,6 +43,10 @@ export {
   version,
 } from './preact'
 export { cache } from '../../api/cache'
+export {
+  ReactSharedInternals as __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+  ReactClientInternals as __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+} from './internals'
 
 import { ViewTransition, addTransitionType } from './view-transition'
 export { ViewTransition, addTransitionType }
@@ -60,7 +64,9 @@ export function cacheSignal(): AbortSignal | null {
   return currentCacheSignal()
 }
 
+import './style-values'
 import ReactCompat from './preact'
+import { attachReactInternals } from './internals'
 import { cache as serverCache } from '../../api/cache'
 
 const ReactServer = { ...ReactCompat } as typeof ReactCompat & {
@@ -80,5 +86,6 @@ delete (ReactServer as { useSyncExternalStore?: unknown }).useSyncExternalStore
 ReactServer.cache = serverCache
 ReactServer.cacheSignal = cacheSignal
 Object.assign(ReactServer, { ViewTransition, addTransitionType })
+attachReactInternals(ReactServer)
 
 export default ReactServer

package/src/compat/react/server.ts

@@ -1,5 +1,14 @@
+import './style-values'
 import ReactCompat from './preact'
+import { attachReactInternals } from './internals'
 import { cache as serverCache } from '../../api/cache'
+
+attachReactInternals(ReactCompat)
+
+export {
+  ReactSharedInternals as __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
+  ReactClientInternals as __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
+} from './internals'
 import { currentPrerenderScope } from '../../render/ppr'
 import { currentCacheSignal } from '../../request/cache'
 
@@ -91,10 +100,15 @@ function useTransition(): [false, (callback: () => void) => void] {
 
 function useSyncExternalStore<Snapshot>(
   _subscribe: (onStoreChange: () => void) => () => void,
-  getSnapshot: () => Snapshot,
+  _getSnapshot: () => Snapshot,
   getServerSnapshot?: () => Snapshot,
 ): Snapshot {
-  return getServerSnapshot ? getServerSnapshot() : getSnapshot()
+  // Falling back to getSnapshot here is the same hazard: this layer only ever renders on the server.
+  if (!getServerSnapshot)
+    throw new Error(
+      'Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.',
+    )
+  return getServerSnapshot()
 }
 
 function useContext<Value>(context: Parameters<typeof ReactCompat.useContext<Value>>[0]): Value {