@wular/pnext 0.0.7 → 0.0.9

package/src/client/entry.ts

@@ -56,7 +56,8 @@ interface ClientEntryOptions {
   shellLayoutOrder?: string[]
   /**
    * Dev split: the served URL a deferred dynamic reference loads from instead
-   * of bundling its target into this entry (see buildClientDynamicChunk).
+   * of bundling its target into this entry: the dev split emits that reference as
+   * its own entry point of the same build (see buildClientEntry).
    */
   deferredDynamicHref?: (reference: ClientReference) => string | undefined
 }
@@ -91,7 +92,9 @@ function islandContextModulePath() {
 // Wire-marker revival shared with the server encoder (utils/serialize.ts):
 // island props carrying a CYCLE travel as `$$pnext_ref` back-references.
 function staticSlotsModulePath() {
-  return path.join(import.meta.dirname, '../render/static-slots.ts')
+  // The preact-free half: entries import it eagerly, so it must not drag preact into a
+  // visible-dynamic entry's static graph.
+  return path.join(import.meta.dirname, '../render/static-slots-revive.ts')
 }
 
 function serializeModulePath() {
@@ -291,15 +294,17 @@ import { isActionError } from ${JSON.stringify(actionClientModulePath())};`,
 function propsParserSource(nextCompat?: boolean) {
   const revive = nextCompat ? 'reviveSerializedErrorRefs' : 'reviveSerializedRefs'
   return `
-import { ${revive} as __pnextReviveSerializedRefs } from ${JSON.stringify(serializeModulePath())};
+import { ${revive} as __pnextReviveSerializedRefs, hasPromiseProps as __pnextHasPromiseProps, revivePromiseMarkers as __pnextRevivePromiseMarkers } from ${JSON.stringify(serializeModulePath())};
 import { hasIslandStaticSlots as __pnextHasIslandSlots, reviveIslandStaticSlots as __pnextReviveIslandSlots } from ${JSON.stringify(staticSlotsModulePath())};
 // Element-valued props: the wire carries a \`$$pnext_slot\` id per element and the server rendered it
 // inside a matching \`pnext-static-slot\` host, adopted here exactly like element children. Islands
 // with no element props skip the walk on a substring test of the raw attribute.
-function islandProps(raw, root, toChildren) {
+// \`h\` is threaded in rather than imported by the slot reviver: that would put preact in the static
+// graph of entries (visible-dynamic) that otherwise only lazy-import it.
+function islandProps(raw, root, toChildren, h) {
   const props = parseIslandProps(raw);
   if (!__pnextHasIslandSlots(raw)) return props;
-  return __pnextReviveIslandSlots(props, root, toChildren);
+  return __pnextReviveIslandSlots(props, root, toChildren, h);
 }
 function parseIslandProps(raw) {
   const props = JSON.parse(raw || '{}');${
@@ -313,25 +318,72 @@ function parseIslandProps(raw) {
   // rebuilds plain objects, so resolving first would restore identity onto
   // objects the revival then replaces).
   const revived = __pnextReviveSerializedRefs(${nextCompat ? 'actions ? actions.reviveProps(props) : props' : 'props'});
-  // Promise props (page params/searchParams of client slot pages) travel as
-  // markers; revive them into PRE-FULFILLED promises (React use() protocol:
-  // status/value readable synchronously). A bare Promise.resolve would make
-  // use() suspend during hydration, and a suspended hydration re-render
-  // appends fragment siblings instead of reusing the server DOM.
-  for (const key of Object.keys(revived)) {
-    const value = revived[key];
-    if (value && typeof value === 'object' && '__pnextPromise' in value) {
-      revived[key] = pnextFulfilled(value.__pnextPromise);
+  // Promise props travel as markers, at the top level (a client slot page's params/searchParams) and
+  // nested in plain containers (a dehydrated react-query state's pending-query promise). Revive both
+  // into pre-fulfilled promises - see revivePromiseMarkers. The deep walk is gated on a substring
+  // test of the raw attribute, so an island with no promise props pays one indexOf.
+  return __pnextHasPromiseProps(raw || '') ? __pnextRevivePromiseMarkers(revived) : revived;
+}
+`
+}
+
+/** Island hosts pnext emits as `display:contents` custom elements (renderer + compat dynamic). */
+const MEASURED_HOST_TAGS = ['pnext-client', 'pnext-dynamic', 'pnext-static-children']
+
+/**
+ * A `display:contents` host has no CSS box, so an island child measuring its
+ * parentElement (getBoundingClientRect/offsetWidth, or a ResizeObserver on it)
+ * sees 0x0 and never resizes — under Next that parent is the app's real
+ * container. Upgrading the hosts to custom elements lets their measurement
+ * surface delegate to the nearest ancestor that does have a box.
+ */
+export function hostMeasureSource() {
+  return `
+function pnextInstallHostMeasure() {
+  if (typeof customElements === 'undefined' || window.__PNEXT_HOST_MEASURE__) return;
+  window.__PNEXT_HOST_MEASURE__ = true;
+  const box = el =>
+    el.style.display === 'contents' || getComputedStyle(el).display === 'contents'
+      ? el.parentElement
+      : null;
+  class PnextHost extends HTMLElement {
+    getBoundingClientRect() {
+      const target = box(this);
+      return target ? target.getBoundingClientRect() : super.getBoundingClientRect();
+    }
+    getClientRects() {
+      const target = box(this);
+      return target ? target.getClientRects() : super.getClientRects();
     }
   }
-  return revived;
-}
-function pnextFulfilled(value) {
-  const promise = Promise.resolve(value);
-  promise.status = 'fulfilled';
-  promise.value = value;
-  return promise;
+  for (const key of ['clientWidth', 'clientHeight', 'offsetWidth', 'offsetHeight', 'offsetTop', 'offsetLeft']) {
+    Object.defineProperty(PnextHost.prototype, key, {
+      configurable: true,
+      get() {
+        const target = box(this);
+        return target ? target[key] : 0;
+      },
+    });
+  }
+  for (const tag of ${JSON.stringify(MEASURED_HOST_TAGS)}) {
+    if (!customElements.get(tag)) customElements.define(tag, class extends PnextHost {});
+  }
+  // Observing the same element twice is a single native observation, so
+  // redirecting host -> parent dedupes on its own.
+  const observed = target => (target instanceof PnextHost ? (box(target) ?? target) : target);
+  const NativeResizeObserver = window.ResizeObserver;
+  if (NativeResizeObserver) {
+    window.ResizeObserver = class extends NativeResizeObserver {
+      observe(target, options) {
+        super.observe(observed(target), options);
+      }
+      unobserve(target) {
+        super.unobserve(observed(target));
+      }
+    };
+  }
 }
+pnextInstallHostMeasure();
 `
 }
 
@@ -608,41 +660,6 @@ export interface ClientRuntimeFacts {
 /** Module specifier the generated route stubs import their runtime from. */
 export const CLIENT_RUNTIME_MODULE = 'pnext-client-runtime'
 
-/** Dev split: single-instance vendor modules the entry shares with on-demand chunks. */
-export const DYN_SHARED_GLOBAL = '__PNEXT_DYN_SHARED__'
-export function dynSharedSpecifiers(nextCompat?: boolean) {
-  return nextCompat
-    ? [
-        'preact',
-        'preact/hooks',
-        'preact/compat',
-        'preact/compat/client',
-        'preact/jsx-runtime',
-        'preact/jsx-dev-runtime',
-      ]
-    : ['preact', 'preact/hooks', 'preact/jsx-runtime']
-}
-
-// A separately-built dynamic chunk must render with THIS entry's preact (hooks
-// dispatch through the renderer's own `options`), so the entry publishes its
-// vendor namespaces for the chunk build's shared-vendor shims to read. Emitted
-// whenever the dev split is armed: dynamic() calls inside 'use client' modules
-// are rewritten mid-build (pipeline), after this source is generated.
-function dynSharedTableSource(
-  nextCompat?: boolean,
-  deferredDynamicHref?: (reference: ClientReference) => string | undefined,
-) {
-  if (!deferredDynamicHref) return ''
-  const specifiers = dynSharedSpecifiers(nextCompat)
-  const imports = specifiers.map(
-    (specifier, index) => `import * as __pnextDynShared${index} from ${JSON.stringify(specifier)};`,
-  )
-  const entries = specifiers.map(
-    (specifier, index) => `${JSON.stringify(specifier)}: __pnextDynShared${index}`,
-  )
-  return `${imports.join('\n')}\nwindow.${DYN_SHARED_GLOBAL} = { ${entries.join(', ')} };\n`
-}
-
 export function clientRuntimeFacts(
   routes: { route: RouteFacts; shell?: boolean }[],
   nextCompat?: boolean,
@@ -685,6 +702,7 @@ ${revival ? layoutSegmentHelperSource(nextCompat) : ''}
 ${revival ? propsParserSource(nextCompat) : ''}
 ${revival ? islandHelpersSource(facts) : ''}
 ${islandCssHelperSource()}
+${revival ? hostMeasureSource() : ''}
 ${mountLifecycleSource(nextCompat)}
 
 export function bootstrapRoute(config) {
@@ -785,7 +803,6 @@ export function clientEntrySource(options: ClientEntryOptions) {
 import { bootstrapRoute${needsCss ? ', loadIslandCss' : ''} } from ${JSON.stringify(CLIENT_RUNTIME_MODULE)};
 ${pageFile ? `import Page from ${JSON.stringify(pageFile)};` : ''}
 ${imports}
-${dynSharedTableSource(nextCompat, options.deferredDynamicHref)}
 ${routerImportSource(facts)}
 ${boundaryImportSource(nextCompat, hasErrorBoundary(facts), !notFoundFile)}
 
@@ -887,11 +904,11 @@ function visibleDynamicIslandEntrySource(
 
   return `
 ${nextCompat ? "import { options as __pnextPreactOptions } from 'preact';" : ''}
-${dynSharedTableSource(nextCompat, deferredDynamicHref)}
 ${islandCssHelperSource()}
 ${routerImportSource(facts)}
 ${boundaryImportSource(nextCompat, boundary, boundary && !notFoundFile)}
 ${layoutSegmentHelperSource(nextCompat)}
+${hostMeasureSource()}
 ${mountLifecycleSource(nextCompat)}
 const islands = [
   ${islandManifest}
@@ -957,7 +974,9 @@ function observeVisibleIsland(root, island) {
 }
 
 function visibleTarget(root) {
-  const rect = root.getBoundingClientRect();
+  // The host's OWN box: hostMeasureSource delegates the patched one to the
+  // parent, and IntersectionObserver never fires for a display:contents target.
+  const rect = Element.prototype.getBoundingClientRect.call(root);
   if (rect.width || rect.height) return root;
   return root.parentElement ?? root;
 }
@@ -978,7 +997,7 @@ async function mountIslandTree(root, island) {
   ]);
 ${facts.suspense !== false ? '  islandBoundary = Suspense;\n' : ''}  const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
-  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node)), await staticChildren(h, source, island.id));
+  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
   const wrapped = ${facts.suspense !== false ? 'h(Suspense, { fallback: null }, pnextClientBoundary(h, vnode))' : 'pnextClientBoundary(h, vnode)'};
   if (source !== root) adoptPreserved(render, root, wrapped);
   else mount(hydrate, render, root, wrapped);
@@ -991,7 +1010,7 @@ async function mountIslandTree(root, island) {
   const [{ h, hydrate, render }, Component] = await Promise.all([import('preact'), island.load()]);
   const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
-  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node)), await staticChildren(h, source, island.id));
+  const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
   if (source !== root) adoptPreserved(render, root, vnode);
   else mount(hydrate, render, root, vnode);
 }`
@@ -1077,7 +1096,7 @@ async function domNode(h, node) {
     if (!island) return h(element.localName, domProps(element), await domChildren(h, element));
     const Component = island.Component ?? await island.load();
     const rawProps = element.getAttribute('data-pnext-props') ?? '{}';
-    const vnode = islandVNode(h, Component, await islandProps(rawProps, element, node => domChildren(h, node)), await staticChildren(h, element, island.id));
+    const vnode = islandVNode(h, Component, await islandProps(rawProps, element, node => domChildren(h, node), h), await staticChildren(h, element, island.id));
     return ${nextCompat ? 'islandBoundary ? h(islandBoundary, { fallback: null }, pnextClientBoundary(h, vnode)) : pnextClientBoundary(h, vnode)' : 'vnode'};
   }
 
@@ -1364,7 +1383,7 @@ async function mountIslandTree(root, island) {
     // Preserved across a soft navigation: re-render in place with the incoming
     // document's props/children so component state survives while the routed
     // content under the island updates.
-    const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, incoming, domChildren)', 'await staticChildren(incoming, island.id)', 'root', nextCompat)};
+    const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, incoming, domChildren, h)', 'await staticChildren(incoming, island.id)', 'root', nextCompat)};
     render(${wrapInBoundary('vnode', nextCompat)}, root);
     pnextMountedRoots.add(root);
     return;
@@ -1375,7 +1394,7 @@ async function mountIslandTree(root, island) {
     root.replaceChildren(...incoming.childNodes);
     root.__pnextLive = undefined;
   }
-  const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, root, domChildren)', 'await staticChildren(root, island.id)', 'root', nextCompat)};
+  const vnode = ${islandVNodeExpr('Component', 'await islandProps(rawProps, root, domChildren, h)', 'await staticChildren(root, island.id)', 'root', nextCompat)};
   mount(root, ${wrapInBoundary('vnode', nextCompat)});
 }
 
@@ -1448,7 +1467,7 @@ async function domNode(node) {
         : ''
     }
     const Component = island.Component ?? await island.load();
-    return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren)', 'children', 'element', nextCompat), nextCompat)};
+    return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren, h)', 'children', 'element', nextCompat), nextCompat)};
   }
 
   if (Page && element.id === 'pnext-page') {
@@ -1487,7 +1506,9 @@ ${
   visibleIslands
     ? `
 function visibleTarget(root) {
-  const rect = root.getBoundingClientRect();
+  // The host's OWN box: hostMeasureSource delegates the patched one to the
+  // parent, and IntersectionObserver never fires for a display:contents target.
+  const rect = Element.prototype.getBoundingClientRect.call(root);
   if (rect.width || rect.height) return root;
   return root.parentElement ?? root;
 }

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

@@ -746,13 +746,10 @@ async function emitFontBytes(
   // Next's loader names emitted files `[hash]-s.p.[ext]`: `-s` when a
   // size-adjust fallback font is used, `.p` when the font is preloaded.
   const filename = `${hash}${emit.adjustFontFallback ? '-s' : ''}${emit.preload ? '.p' : ''}.${ext}`
-  // Served from `/_next/static/media/` (files under public/ map 1:1 to the URL
-  // path). Dev stashes under cache/ but keeps the same relative layout.
+  // Served from `/_next/static/media/` — files under the out dir's public/ map 1:1 to the URL path,
+  // which is the only place dev and build both look them up.
   const mediaSegments = ['_next', 'static', 'media']
-  const outRoot = context.dev
-    ? path.join(context.config.outPath, 'cache')
-    : path.join(context.config.outPath, 'public')
-  const outDir = path.join(outRoot, ...mediaSegments)
+  const outDir = path.join(context.config.outPath, 'public', ...mediaSegments)
   const file = path.join(outDir, filename)
   await mkdir(outDir, { recursive: true })
   if (!existsSync(file)) {

package/src/dev/server.ts

@@ -1,10 +1,8 @@
 import { existsSync, readFileSync, statSync } from 'node:fs'
-import { createHash } from 'node:crypto'
 import { readFile, readdir, rm, stat, watch } from 'node:fs/promises'
 import path from 'node:path'
 import {
   DEFERRED_DYNAMIC_SIDECAR,
-  buildClientDynamicChunk,
   buildClientEntry,
   deferredDynamicRefById,
   prebuiltRuntimeDir,
@@ -478,14 +476,14 @@ export async function startDevServer(options: DevServerOptions) {
 
       const dynChunkMatch = /^\/__pnext\/client-dyn\/([A-Za-z0-9-]+)\.js$/.exec(url.pathname)
       if (dynChunkMatch?.[1]) {
-        const found = findDeferredDynamicReference(routes, dynChunkMatch[1])
-        if (!found)
+        const id = dynChunkMatch[1]
+        const file = await profileDevStep(profile, `client dyn chunk ${id}`, () =>
+          devDynamicEntryFile(config, routes, id, url.searchParams.get('r')),
+        )
+        if (!file)
           return finish(
             applyProxyResponse(new Response('not found', { status: 404 }), proxyResponse),
           )
-        const file = await profileDevStep(profile, `client dyn chunk ${dynChunkMatch[1]}`, () =>
-          buildDevDynamicChunk(config, found.route, found.reference, devImportVersion),
-        )
         return finish(
           applyProxyResponse(
             devResponse(await readFile(file), 'text/javascript; charset=utf-8'),
@@ -493,15 +491,6 @@ export async function startDevServer(options: DevServerOptions) {
           ),
         )
       }
-      const dynSharedChunk = /^\/__pnext\/client-dyn\/chunks\/(.+\.js)$/.exec(url.pathname)
-      if (dynSharedChunk?.[1]) {
-        const chunkFile = dynChunkFiles.get(dynSharedChunk[1])
-        if (chunkFile && existsSync(chunkFile))
-          return finish(
-            applyProxyResponse(devChunkResponse(await readFile(chunkFile)), proxyResponse),
-          )
-        return finish(applyProxyResponse(new Response('not found', { status: 404 }), proxyResponse))
-      }
 
       const clientMatch = /^\/__pnext\/client\/(.+)\.js$/.exec(url.pathname)
       if (clientMatch?.[1]) {
@@ -1081,48 +1070,32 @@ function findDeferredDynamicReference(routes: RouteManifestEntry[], id: string)
     if (reference) return { route, reference }
   }
   const registered = deferredDynamicRefById(id)
-  if (registered) return { route: undefined, reference: { id, ...registered } }
+  if (registered)
+    return {
+      route: routes.find(item => item.id === registered.routeId),
+      reference: { id, ...registered },
+    }
   return undefined
 }
 
-// On-demand dynamic chunk builds: keyed by (id, dev import version) so a save
-// invalidates; chunk files index feeds /__pnext/client-dyn/chunks/ requests.
-const dynChunkBuilds = new Map<string, Promise<string>>()
-const dynChunkFiles = new Map<string, string>()
-
-async function buildDevDynamicChunk(
+/**
+ * The on-demand output of a deferred reference: an entry point of its route's own
+ * client build, so it is emitted (and chunk-split against that entry) by the build
+ * the route's bundle already runs. `r` names that route; a reference the scan or
+ * the registry can place needs no query.
+ */
+async function devDynamicEntryFile(
   config: ResolvedConfig,
-  route: RouteManifestEntry | undefined,
-  reference: { id: string; file: string; exportName: string },
-  devImportVersion: string,
+  routes: RouteManifestEntry[],
+  id: string,
+  routeId: string | null,
 ) {
-  const key = `${reference.id}\0${devImportVersion}`
-  const existing = dynChunkBuilds.get(key)
-  if (existing) return existing
-  const outDir = path.join(
-    config.outPath,
-    'cache',
-    'client-dyn',
-    `${reference.id}-${createHash('sha1').update(devImportVersion).digest('hex').slice(0, 8)}`,
-  )
-  const build = (async () => {
-    const outfile = path.join(outDir, `${reference.id}.js`)
-    if (!existsSync(outfile)) {
-      await buildClientDynamicChunk({ config, route, reference, outDir })
-    }
-    const chunksDir = path.join(outDir, 'chunks')
-    if (existsSync(chunksDir)) {
-      for (const entry of await readdir(chunksDir)) {
-        if (entry.endsWith('.js')) dynChunkFiles.set(entry, path.join(chunksDir, entry))
-      }
-    }
-    return outfile
-  })().catch(error => {
-    dynChunkBuilds.delete(key)
-    throw error
-  })
-  dynChunkBuilds.set(key, build)
-  return build
+  const scoped = routeId ? routes.find(route => route.id === routeId) : undefined
+  const route = scoped ?? findDeferredDynamicReference(routes, id)?.route
+  if (!route) return undefined
+  const outDir = path.dirname(await buildDevClient(config, route))
+  const file = path.join(outDir, `${id}.js`)
+  return isInside(outDir, file) && existsSync(file) ? file : undefined
 }
 
 /** A cached entry never re-ran the pipeline rewrite: recover its chunk-id map. */
@@ -1130,7 +1103,7 @@ async function loadDeferredDynamicSidecar(outDir: string) {
   try {
     const parsed = JSON.parse(
       await readFile(path.join(outDir, DEFERRED_DYNAMIC_SIDECAR), 'utf8'),
-    ) as Record<string, { file: string; exportName: string }>
+    ) as Record<string, { file: string; exportName: string; routeId?: string }>
     for (const [id, ref] of Object.entries(parsed)) {
       if (ref?.file && ref.exportName) registerDeferredDynamicRef(id, ref)
     }

package/src/render/renderer.ts

@@ -6140,34 +6140,39 @@ async function serializablePromiseProps(props: ServerVNodeProps): Promise<Server
     next[key] =
       key === 'children'
         ? value
-        : isPromise(value)
+        : isPromise(value) && isHangingPromise(value)
           ? // A fallback shell's params/searchParams promise HANGS: awaiting it
             // here rejects with PostponeError outside every <Suspense>, which
             // destroys the whole partial shell (no shell -> no segment
             // artifacts). Emit the placeholder instead; withRequestRouteParams
             // re-stamps it with the serving request's values.
-            isHangingPromise(value)
-            ? placeholderPromiseMarker(key)
-            : promiseMarker(await value)
+            placeholderPromiseMarker(key)
           : await deepResolveNestedPromises(value)
   }
   return next
 }
 
 /**
- * A prop's own top-level value gets the promiseMarker treatment above, preserving pending-promise
- * semantics for use(). A Promise buried inside a nested object/array/Map/Set is not revived as a
- * live promise on the client, so there is no point wire-marking it - just await it in place so the
- * structure serializes instead of crashing the render.
+ * Await every Promise in a prop and replace it with a `promiseMarker`, at the top level (a page's
+ * params) and buried in a nested object/array/Map/Set alike (a react-query dehydrated state keeps
+ * its pending-query promise at `state.queries[n].promise`). The marker is what preserves PROMISE
+ * IDENTITY across the wire: the client revives it into a pre-fulfilled promise, so a consumer that
+ * calls `.then` on it - use(), react-query's tryResolveSync - still finds a thenable.
+ *
+ * A hanging promise (partial prerender) is never awaited - that would wedge the render - and a
+ * nested one has no re-stampable identity, so it settles as null exactly like a non-request-API
+ * hanging prop.
  */
 async function deepResolveNestedPromises(
   value: unknown,
   seen = new Map<object, unknown>(),
 ): Promise<unknown> {
-  if (isPromise(value)) return deepResolveNestedPromises(await value, seen)
+  if (isPromise(value)) {
+    if (isHangingPromise(value)) return promiseMarker(null)
+    return promiseMarker(await deepResolveNestedPromises(await value, seen))
+  }
   if (value === null || typeof value !== 'object') return value
-  const existing = seen.get(value)
-  if (existing !== undefined) return existing
+  if (seen.has(value)) return seen.get(value)
   if (Array.isArray(value)) {
     const items: unknown[] = []
     seen.set(value, items)
@@ -6432,18 +6437,58 @@ export async function renderActionReturnElement(
   return renderVNodeToString(h(Fragment, null, resolved))
 }
 
+/**
+ * preact's stream renderer builds the SHELL synchronously: a component that suspends with no
+ * <Suspense> registered above it escapes `start()` as this error instead of being awaited. The
+ * non-streaming path has no such limit (renderToStringAsync retries the suspension), so falling
+ * back to it keeps a suspending island - a react-query island reading a dehydrated promise, say -
+ * rendering exactly as it does on a non-streamed request.
+ */
+const SYNC_SUSPENSE_MESSAGE = 'Use "renderToStringAsync" for suspenseful rendering.'
+
+function isSyncSuspenseError(error: unknown): boolean {
+  return error instanceof Error && error.message === SYNC_SUSPENSE_MESSAGE
+}
+
+/** Sentinel: the shell suspended synchronously and must be re-rendered by the awaited path. */
+const SHELL_SUSPENDED = Symbol('pnext.shellSuspended')
+
 async function renderClientPageStreamShell(vnode: VNode, state: StreamState): Promise<string> {
-  return suspendingStreamScope.run(true, () => renderSuspendingStreamShell(vnode, state))
+  const shell = await suspendingStreamScope.run(true, () =>
+    renderSuspendingStreamShell(vnode, state),
+  )
+  if (shell !== SHELL_SUSPENDED) return shell
+  // Deliberately OUTSIDE the suspending-stream scope: that scope disables preact's error
+  // boundaries, and the awaited path needs them back on to match the non-streamed render exactly.
+  return renderVNodeToString(vnode, state)
 }
 
-async function renderSuspendingStreamShell(vnode: VNode, state: StreamState): Promise<string> {
+async function renderSuspendingStreamShell(
+  vnode: VNode,
+  state: StreamState,
+): Promise<string | typeof SHELL_SUSPENDED> {
   state.clientPageStream = true
-  const stream = actionSerializeScope.run(state, () => renderToReadableStream(vnode))
-  const reader = stream.getReader()
-  let first: Awaited<ReturnType<typeof reader.read>>
+  // The shell renders inside `new ReadableStream`'s start(), so a synchronous suspension throws
+  // out of the CONSTRUCTOR - the read below never happens. Both have to be guarded.
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+  let first: Awaited<ReturnType<NonNullable<typeof reader>['read']>>
   try {
+    const stream = actionSerializeScope.run(state, () => renderToReadableStream(vnode))
+    // preact hangs a SECOND promise off the stream - `allReady`, resolved when the whole render
+    // (shell + every suspended boundary) lands - and rejects BOTH it and the stream with the same
+    // error. Reading the stream owns one of them; nothing owns `allReady`, so a shell that fails
+    // reports an unhandled rejection on top of the failure the caller already handled. pnext never
+    // awaits full-render completion (the deferred tail below drains the reader instead), so the
+    // handler is a discard rather than a second error path.
+    void (stream as { allReady?: Promise<void> }).allReady?.catch(() => undefined)
+    reader = stream.getReader()
     first = await reader.read()
   } catch (error) {
+    if (isSyncSuspenseError(error)) {
+      state.clientPageStream = false
+      void reader?.cancel().catch(() => undefined)
+      return SHELL_SUSPENDED
+    }
     // A whole-page client route streams WITHOUT the ClientPageSsrBoundary (an error boundary
     // disables preact's stream suspense), so nothing tags a throw escaping this render. It came
     // from the client tree by construction, so tag it here - otherwise global-error would redact

package/src/render/slots.tsx

@@ -16,6 +16,7 @@ import {
   type SegmentMatch,
 } from '../routing/slots'
 import { toPosixPath } from '../utils/fs'
+import { PROMISE_MARKER_KEY, revivePromiseMarkers } from '../utils/serialize'
 import type { PageProps, RouteManifestEntry, RouteParamValue, ServerComponent } from '../types'
 
 interface SlotRenderOptions {
@@ -394,8 +395,6 @@ async function renderSlotComponent<Options extends SlotRenderOptions>(
   return h(Component as ComponentType<PageProps>, props)
 }
 
-const PROMISE_MARKER_KEY = '__pnextPromise'
-
 export function promiseMarker(value: unknown) {
   return { [PROMISE_MARKER_KEY]: value ?? null }
 }
@@ -418,17 +417,12 @@ export function promisePlaceholderJson(kind: 'params' | 'searchParams'): string
   return `{"${PROMISE_MARKER_KEY}":null,"${PROMISE_PLACEHOLDER_KEY}":"${kind}"}`
 }
 
-/** Revive promise markers into thenables for the SSR pass of an island. */
+/**
+ * Revive promise markers into thenables for the SSR pass of an island - the same walk the client
+ * entry runs, so a nested marker is a promise on both sides rather than a bare object on one.
+ */
 export function revivePromiseProps(props: Record<string, unknown>) {
-  const out: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(props)) {
-    if (value && typeof value === 'object' && PROMISE_MARKER_KEY in value) {
-      out[key] = Promise.resolve((value as Record<string, unknown>)[PROMISE_MARKER_KEY])
-    } else {
-      out[key] = value
-    }
-  }
-  return out
+  return revivePromiseMarkers({ ...props })
 }
 
 function slotPageProps<Options extends SlotRenderOptions>(

package/src/render/static-slots-revive.ts

@@ -0,0 +1,65 @@
+import type { h, VNode } from 'preact'
+
+// Client half of the static-slot protocol, split out of ./static-slots so it stays PREACT-FREE:
+// entries import it eagerly, and a visible-dynamic entry must not pull preact into its static graph
+// (preact declares no `sideEffects: false`, so even an unused binding keeps the chunk import alive).
+// `createElement` is therefore threaded in from the island mount, where preact is lazily imported.
+
+export const ISLAND_STATIC_SLOT_ATTRIBUTE = 'data-pnext-static-slot'
+export const ISLAND_STATIC_SLOT_MARKER = '$$pnext_slot'
+
+type Props = Record<string, unknown>
+
+/** Cheap gate on the raw props attribute so islands with no element props skip the revive walk. */
+export function hasIslandStaticSlots(raw: string) {
+  return raw.includes(ISLAND_STATIC_SLOT_MARKER)
+}
+
+/**
+ * Client mount: swap each `$$pnext_slot` marker for a `pnext-static-slot` host holding the matching
+ * server-rendered DOM, converted to vnodes by the entry's DOM walker (so nested islands inside the
+ * adopted subtree become real island vnodes and hydrate on their own). The content is static server
+ * markup - it never re-renders, same as element children.
+ */
+export async function reviveIslandStaticSlots(
+  props: Props,
+  root: ParentNode,
+  toChildren: (node: ParentNode) => unknown,
+  createElement: typeof h,
+): Promise<Props> {
+  return (await reviveSlots(props, root, toChildren, createElement, new Set())) as Props
+}
+
+async function reviveSlots(
+  value: unknown,
+  root: ParentNode,
+  toChildren: (node: ParentNode) => unknown,
+  createElement: typeof h,
+  seen: Set<object>,
+): Promise<unknown> {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return value
+  const marker = (value as Props)[ISLAND_STATIC_SLOT_MARKER]
+  if (typeof marker === 'string') {
+    const node = root.querySelector(`[${ISLAND_STATIC_SLOT_ATTRIBUTE}="${cssEscape(marker)}"]`)
+    // No server markup for this slot (the island never rendered the prop, or it was skipped for
+    // SSR): nothing to adopt, so the prop arrives null rather than as an empty host.
+    if (!node) return null
+    return createElement(
+      'pnext-static-slot',
+      { [ISLAND_STATIC_SLOT_ATTRIBUTE]: marker, style: { display: 'contents' } },
+      (await toChildren(node)) as VNode,
+    )
+  }
+  const proto = Object.getPrototypeOf(value) as object | null
+  if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) return value
+  seen.add(value)
+  const target = value as Props
+  for (const key of Object.keys(target)) {
+    target[key] = await reviveSlots(target[key], root, toChildren, createElement, seen)
+  }
+  return value
+}
+
+function cssEscape(value: string) {
+  return value.replace(/["\\]/g, '\\$&')
+}