@wular/pnext 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/pnext",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "A fast little framework for server-first React apps, fully compatible with Next.js",
   "type": "module",
   "bin": {

package/src/cli/dev.ts

@@ -86,7 +86,11 @@ function watchServerMemory(server: DevServerHandle) {
   if (!Number.isFinite(limitMb) || limitMb <= 0) return
   const limitBytes = limitMb * 1024 * 1024
   const timer = setInterval(() => {
-    const rss = process.memoryUsage.rss()
+    // Bun (<=1.3.x) lacks the `process.memoryUsage.rss` fast path Node provides.
+    const rss =
+      typeof process.memoryUsage.rss === 'function'
+        ? process.memoryUsage.rss()
+        : process.memoryUsage().rss
     if (rss < limitBytes) return
     clearInterval(timer)
     const usedMb = Math.round(rss / (1024 * 1024))

package/src/client/build.ts

@@ -35,8 +35,6 @@ import {
 } from '../resolve/imports'
 import {
   CLIENT_RUNTIME_MODULE,
-  DYN_SHARED_GLOBAL,
-  dynSharedSpecifiers,
   clientEntrySource,
   clientRuntimeFacts,
   clientRuntimeSource,
@@ -369,23 +367,60 @@ async function preparePrebuilt(
   }
 }
 
-/** The served URL of a deferred dynamic reference's on-demand chunk (dev split). */
-export function deferredDynamicChunkHref(reference: Pick<ClientReference, 'id'>) {
-  return `/__pnext/client-dyn/${reference.id}.js`
+/**
+ * The served URL of a deferred dynamic reference's on-demand output (dev split).
+ * `r` names the route whose build emitted it: two routes reaching the same island
+ * each bundle their own, and one route's copy chunk-splits against its own entry.
+ */
+export function deferredDynamicChunkHref(reference: Pick<ClientReference, 'id'>, routeId?: string) {
+  const query = routeId ? `?r=${encodeURIComponent(routeId)}` : ''
+  return `/__pnext/client-dyn/${reference.id}.js${query}`
+}
+
+/** Where the dev server serves this build's chunks from (see publicPath). */
+export const devClientPublicPath = '/__pnext/client'
+
+export interface DeferredDynamicEntry {
+  id: string
+  file: string
+}
+
+/**
+ * Every deferred reference this route's build must emit an output for: the ones
+ * the route scan named, plus the ones its own pipeline rewrite registered.
+ */
+function deferredDynamicEntries(route: RouteManifestEntry): DeferredDynamicEntry[] {
+  const entries = new Map<string, string>()
+  for (const reference of route.clientReferences) {
+    if (reference.dynamic && !ssrClientReference(reference)) {
+      entries.set(reference.id, reference.file)
+    }
+  }
+  for (const [id, ref] of deferredDynamicRouteRefs.get(route.id) ?? []) entries.set(id, ref.file)
+  return [...entries].map(([id, file]) => ({ id, file }))
 }
 
 export interface DeferredDynamicRef {
   file: string
   exportName: string
+  /** Entry that rewrote this reference: the build its output is emitted by. */
+  routeId?: string
 }
 
 // Process-level registry the dev chunk endpoint resolves ids through. Entries
 // come from the pipeline rewrite below and from each out-dir's sidecar (a
 // restart serving a cached entry never re-ran the rewrite).
 const deferredDynamicRefs = new Map<string, DeferredDynamicRef>()
+// Indexed by route as well: a route's build needs every reference it reached as
+// an entry point, and a rewrite only names them once the build has run.
+const deferredDynamicRouteRefs = new Map<string, Map<string, DeferredDynamicRef>>()
 
 export function registerDeferredDynamicRef(id: string, ref: DeferredDynamicRef) {
   deferredDynamicRefs.set(id, ref)
+  if (!ref.routeId) return
+  const refs = deferredDynamicRouteRefs.get(ref.routeId) ?? new Map<string, DeferredDynamicRef>()
+  deferredDynamicRouteRefs.set(ref.routeId, refs)
+  refs.set(id, ref)
 }
 
 export function deferredDynamicRefById(id: string) {
@@ -396,11 +431,11 @@ export function deferredDynamicRefById(id: string) {
 export const DEFERRED_DYNAMIC_SIDECAR = 'dyn-refs.json'
 
 /** Dev-only: deferred dynamic references load from the on-demand chunk endpoint. */
-function devDeferredDynamicHref(dev: boolean | undefined) {
+function devDeferredDynamicHref(dev: boolean | undefined, routeId?: string) {
   if (!dev || !devDynamicSplitEnabled()) return undefined
   return (reference: ClientReference) =>
     reference.dynamic && !ssrClientReference(reference)
-      ? deferredDynamicChunkHref(reference)
+      ? deferredDynamicChunkHref(reference, routeId)
       : undefined
 }
 
@@ -422,7 +457,7 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
   await ensureDir(outDir)
   const suspense = routeSuspenseFree(config, route) === false
   const source = clientEntrySource({
-    deferredDynamicHref: devDeferredDynamicHref(dev),
+    deferredDynamicHref: devDeferredDynamicHref(dev, route.id),
     pageFile: route.client ? route.file : undefined,
     clientReferences: route.clientReferences,
     nextCompat: nextCompatEnabled(config),
@@ -439,7 +474,7 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
   })
   const entryName = clientEntryName(route)
   const outfile = path.join(outDir, `${entryName}.js`)
-  const pipeline = createClientSourcePipeline(config, dev === true)
+  const pipeline = createClientSourcePipeline(config, dev === true, route.id)
   pipeline.warmRoutes([route])
   const runtimeFacts = clientRuntimeFacts(
     [
@@ -467,38 +502,59 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
     ),
   )
 
+  const split = Boolean(devDeferredDynamicHref(dev))
+  const runEntryBuild = (dynEntries: DeferredDynamicEntry[]) =>
+    build({
+      ...baseClientBuildOptions(config, dev),
+      // Every deferred reference is an entry point of THIS build, so esbuild
+      // hoists what it shares with the route entry into a shared chunk. Module
+      // identity — contexts, singletons, the preact instance — then holds by
+      // construction, and esbuild owns the interop it always did.
+      entryPoints: [
+        { in: virtualEntryPath(route.id), out: entryName },
+        ...dynEntries.map(entry => ({ in: entry.file, out: entry.id })),
+      ],
+      // Chunk imports as absolute URLs: an on-demand output is served from a
+      // different directory than the entry, and a relative specifier would make
+      // the browser fetch the same chunk under two URLs — two module instances.
+      ...(split ? { publicPath: devClientPublicPath } : {}),
+      outdir: outDir,
+      metafile: true,
+      plugins: clientBuildPlugins(
+        config,
+        pipeline,
+        [
+          ...(prebuilt ? [prebuilt.plugin] : []),
+          virtualEntryPlugin([{ route, source }]),
+          ...(split ? [deferredDynamicExternalPlugin()] : []),
+          clientRuntimePlugin(runtimeFacts),
+        ],
+        !suspense,
+      ),
+    })
+
   let metafile: Metafile | undefined
+  let dynEntries = split ? deferredDynamicEntries(route) : []
   try {
     const result = await profileClientBuild(route, dev, () =>
-      clientProfile.timeAsync('esbuild', () =>
-        build({
-          ...baseClientBuildOptions(config, dev),
-          stdin: {
-            contents: source,
-            loader: 'ts',
-            resolveDir: process.cwd(),
-            sourcefile: `${route.id}.ts`,
-          },
-          outdir: outDir,
-          entryNames: entryName,
-          metafile: true,
-          plugins: clientBuildPlugins(
-            config,
-            pipeline,
-            [
-              ...(prebuilt ? [prebuilt.plugin] : []),
-              ...(devDeferredDynamicHref(dev) ? [deferredDynamicExternalPlugin()] : []),
-              clientRuntimePlugin(runtimeFacts),
-            ],
-            !suspense,
-          ),
-        }),
-      ),
+      clientProfile.timeAsync('esbuild', () => runEntryBuild(dynEntries)),
     )
     metafile = result.metafile
   } catch (error) {
     throw withClientImportTrace(error, config, route, source)
   }
+  // A dynamic() inside a 'use client' module is only named by the pipeline's
+  // rewrite, which runs mid-build: those references become entry points on the
+  // rebuild here, and stay ones from then on (the registry outlives the build).
+  if (split) {
+    const discovered = deferredDynamicEntries(route)
+    if (discovered.length !== dynEntries.length) {
+      dynEntries = discovered
+      metafile = (
+        await clientProfile.timeAsync('esbuildDynEntries', () => runEntryBuild(dynEntries))
+      ).metafile
+    }
+  }
   await clientProfile.timeAsync('prebuiltSettle', () => prebuilt?.settle() ?? Promise.resolve())
 
   if (metafile) {
@@ -522,88 +578,6 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
   return outfile
 }
 
-/**
- * Dev split: bundle ONE deferred dynamic reference on browser demand. The
- * chunk is its own esbuild build, so single-instance vendors (preact and its
- * facades) resolve to shared shims reading the entry's published namespaces
- * (see dynSharedTableSource) instead of bundling a second copy whose hooks
- * would never see the entry renderer's dispatch.
- */
-export async function buildClientDynamicChunk({
-  config,
-  route,
-  reference,
-  outDir,
-}: {
-  config: ResolvedConfig
-  route?: RouteManifestEntry
-  reference: DeferredDynamicRef & { id: string }
-  outDir: string
-}) {
-  await ensureDir(outDir)
-  const pipeline = createClientSourcePipeline(config, true)
-  const prebuilt = await preparePrebuilt(
-    config,
-    outDir,
-    true,
-    importer => pipeline.sourceOf(importer) ?? readTextSyncSafe(importer),
-    route ? surfaceSignature(config, route, true) : '',
-  )
-  const source = [
-    reference.exportName === 'default'
-      ? `export { default } from ${JSON.stringify(reference.file)};`
-      : '',
-    `export * from ${JSON.stringify(reference.file)};`,
-  ].join('\n')
-  const outfile = path.join(outDir, `${reference.id}.js`)
-  await clientProfile.timeAsync('dynChunk', () =>
-    build({
-      ...baseClientBuildOptions(config, true),
-      stdin: {
-        contents: source,
-        loader: 'ts',
-        resolveDir: process.cwd(),
-        sourcefile: `${reference.id}.dyn.ts`,
-      },
-      outdir: outDir,
-      entryNames: reference.id,
-      plugins: clientBuildPlugins(config, pipeline, [
-        ...(prebuilt ? [prebuilt.plugin] : []),
-        dynSharedVendorPlugin(nextCompatEnabled(config)),
-        deferredDynamicExternalPlugin(),
-      ]),
-    }),
-  )
-  await prebuilt?.settle()
-  clientProfile.report(`client dynamic chunk ${reference.id}`)
-  return outfile
-}
-
-/** Shared-vendor shims: preact resolves to the entry's published namespace. */
-function dynSharedVendorPlugin(nextCompat: boolean): Plugin {
-  const namespace = 'pnext-dyn-shared'
-  const filter = new RegExp(`^(?:${dynSharedSpecifiers(nextCompat).map(escapeRegex).join('|')})$`)
-  return {
-    name: 'pnext-dyn-shared-vendor',
-    setup(build) {
-      build.onResolve({ filter }, args =>
-        args.namespace === namespace ? undefined : { path: args.path, namespace },
-      )
-      build.onLoad({ filter: /.*/, namespace }, async args => {
-        const names = Object.keys((await import(args.path)) as Record<string, unknown>).filter(
-          name => /^[A-Za-z_$][\w$]*$/.test(name) && name !== 'default',
-        )
-        const lines = [
-          `const m = window.${DYN_SHARED_GLOBAL}[${JSON.stringify(args.path)}];`,
-          'export default (m && m.default);',
-          ...names.map(name => `export const ${name} = m.${name};`),
-        ]
-        return { contents: lines.join('\n'), loader: 'js' }
-      })
-    },
-  }
-}
-
 /**
  * Bundle every route's client entry in a single esbuild build. With `splitting`
  * enabled, esbuild emits the shared dependency graph (preact runtime, ui kit,
@@ -1404,7 +1378,7 @@ function coreStaticAssetModule(
  * App-convention .js/.mjs may contain JSX (jsxImportSource is preact), so those parse with the jsx
  * loader; scoped to the source roots, so third-party node_modules .js keeps esbuild's default loader.
  */
-function createClientSourcePipeline(config: ResolvedConfig, dev = false) {
+function createClientSourcePipeline(config: ResolvedConfig, dev = false, routeId?: string) {
   const sourceRewrite = nextCompatEnabled(config)
   const compiler = getCompatModeExtensions().reactCompilerOptions(config)
   const asyncPre = hasClientSourceAsyncPreTransforms()
@@ -1466,9 +1440,10 @@ function createClientSourcePipeline(config: ResolvedConfig, dev = false) {
         specifier => resolveImport(rootFromFile(resolved), resolved, specifier),
         target => {
           const id = clientReferenceId(target.file, target.exportName)
-          registerDeferredDynamicRef(id, target)
-          deferredRefs.set(id, target)
-          return deferredDynamicChunkHref({ id })
+          const ref = { ...target, routeId }
+          registerDeferredDynamicRef(id, ref)
+          deferredRefs.set(id, ref)
+          return deferredDynamicChunkHref({ id }, routeId)
         },
       )
     }

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
 }
@@ -293,7 +294,7 @@ 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
@@ -317,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();
 `
 }
 
@@ -612,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,
@@ -689,6 +702,7 @@ ${revival ? layoutSegmentHelperSource(nextCompat) : ''}
 ${revival ? propsParserSource(nextCompat) : ''}
 ${revival ? islandHelpersSource(facts) : ''}
 ${islandCssHelperSource()}
+${revival ? hostMeasureSource() : ''}
 ${mountLifecycleSource(nextCompat)}
 
 export function bootstrapRoute(config) {
@@ -789,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)}
 
@@ -891,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}
@@ -961,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;
 }
@@ -1491,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/utils/serialize.ts

@@ -19,6 +19,12 @@ const SET_MARKER = '$$pnext_set'
 // restoring identity. Only true cycles are encoded this way - a value that merely appears twice in different
 // branches is still expanded, so every acyclic payload is byte-identical to what it was before.
 const REF_MARKER = '$$pnext_ref'
+// Promise-valued island props ride as `{__pnextPromise: resolved}` so the value keeps its PROMISE
+// IDENTITY across the wire - top level (page params) and nested in plain containers (a react-query
+// dehydrated state carries its pending-query promise inside `state.queries[n].promise`). The render
+// half writes the marker (render/slots promiseMarker); both revive halves live here so the
+// preact-free client entry can import them.
+export const PROMISE_MARKER_KEY = '__pnextPromise'
 
 type TypedArray =
   | Int8Array
@@ -197,6 +203,49 @@ function refTarget(root: unknown, node: Record<string, unknown>): unknown {
   return current
 }
 
+/** Cheap gate: an island whose raw props carry no marker skips the revive walk entirely. */
+export function hasPromiseProps(raw: string) {
+  return raw.includes(PROMISE_MARKER_KEY)
+}
+
+/**
+ * Revive every `promiseMarker` in `props` - top level and nested inside plain objects/arrays - into a
+ * PRE-FULFILLED promise (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.
+ *
+ * Nested containers are rewritten in place (the client just parsed them; the server already
+ * serialized the wire bytes before this runs), the root is not.
+ */
+export function revivePromiseMarkers<T>(props: T): T {
+  return reviveMarkers(props, new Set()) as T
+}
+
+function reviveMarkers(value: unknown, seen: Set<object>): unknown {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return value
+  if (PROMISE_MARKER_KEY in value) {
+    return fulfilledPromise((value as Record<string, unknown>)[PROMISE_MARKER_KEY])
+  }
+  seen.add(value)
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      value[index] = reviveMarkers(value[index], seen)
+    }
+    return value
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) return value
+  const target = value as Record<string, unknown>
+  for (const key of Object.keys(target)) target[key] = reviveMarkers(target[key], seen)
+  return value
+}
+
+function fulfilledPromise(value: unknown) {
+  const promise = Promise.resolve(value) as Promise<unknown> & { status: string; value: unknown }
+  promise.status = 'fulfilled'
+  promise.value = value
+  return promise
+}
+
 /** A preact vnode: `h` sets `constructor` to undefined on every one it makes. */
 export function isElementLike(value: unknown): boolean {
   if (value === null || typeof value !== 'object') return false
@@ -227,6 +276,14 @@ export function assertSerializable(
   if (value instanceof Date || value instanceof URL) {
     throw new Error(`${path} must be a plain JSON value`)
   }
+  // A promise the render half could not await: island props are awaited at the top level and inside
+  // plain objects/arrays/Maps/Sets, so anything left here sits behind a class instance (or is a
+  // server-action argument, where promises are never allowed). Say so instead of "plain object".
+  if (typeof (value as { then?: unknown }).then === 'function') {
+    throw new Error(
+      `${path} is a Promise: a promise prop must be reachable at the top level of the props or nested in plain objects/arrays/Maps/Sets - one held by a class instance cannot be awaited or serialized, and server actions take no promises at all`,
+    )
+  }
   if (typeof value !== 'object') return
   // A value that contains ITSELF is serializable: encodeBinary writes it as a
   // `$$pnext_ref` back-reference (React flight does the same), so stop walking
@@ -241,8 +298,8 @@ export function assertSerializable(
     return
   }
 
-  // The slot walk (render/static-slots) never enters Map/Set, so elements inside them must
-  // still throw rather than ship mangled.
+  // Elements stay illegal inside Map/Set: the slot walk (render/static-slots) does not enter
+  // them, so allowing one would silently ship a JSON-mangled vnode instead of a `$$pnext_slot`.
   if (value instanceof Map) {
     let index = 0
     for (const [key, item] of value.entries()) {