@wular/pnext 0.0.19 → 0.0.20

package/src/cli/start.ts

@@ -15,6 +15,7 @@ import { markErrorLogged } from '../utils/error-log'
 import { isPostpone } from '../render/postpone'
 import { browserHost, ensurePortFree, openBrowser, printServerReady } from './serve/ui'
 import type { BuildManifest } from '../types'
+import type { PeerAddressSource } from '../routing/forwarded'
 
 interface StartOptions {
   root?: string
@@ -22,7 +23,7 @@ interface StartOptions {
   hostname?: string
 }
 
-type RequestHandler = (request: Request) => Promise<Response>
+type RequestHandler = (request: Request, server?: PeerAddressSource) => Promise<Response>
 
 /**
  * The production request handler `pnext start` serves with. Exposed on its own
@@ -70,7 +71,8 @@ export async function start(options: StartOptions = {}) {
   const server = Bun.serve({
     hostname,
     port,
-    fetch: request => (handler ? handler(request) : ensureHandler().then(ready => ready(request))),
+    fetch: (request, server) =>
+      handler ? handler(request, server) : ensureHandler().then(ready => ready(request, server)),
   })
 
   printServerReady({

package/src/client/build.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
-import { copyFile, mkdir, readFile, rename, stat } from 'node:fs/promises'
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import {
   build,
@@ -15,6 +15,7 @@ import {
 } from 'esbuild'
 import { foldInitialChunks } from './chunk-fold'
 import { clientEntryName } from './chunk-name'
+import { assetContentHash } from '../utils/asset-hash'
 import { clientProfile } from './profile'
 import { frameworkRuntimeAliasEntries, publicEnvDefines, type ResolvedConfig } from '../config'
 import { cssModuleClientPlugin } from '../css/build'
@@ -57,6 +58,7 @@ import { shouldReactCompile, transformReactCompiler } from './react-compiler'
 import { createVerboseLogger, formatDuration } from '../utils/verbose'
 import { dim as dimText } from '../utils/ansi'
 import { traceEnabled } from '../utils/trace-flags'
+import { frameworkFingerprint } from '../runtime/fingerprint'
 import type { RouteManifestEntry } from '../types'
 import {
   applyClientSourceAsyncPreTransforms,
@@ -654,9 +656,41 @@ export async function buildClientEntries({
       }
     }
   })
+  await clientProfile.timeAsync('fingerprint', () => fingerprintClientEntries(outDir, entries))
   clientProfile.report('client stage')
 }
 
+/**
+ * Give every route entry a CONTENT-hashed name, replacing the route-identity hash
+ * clientEntryName picks for the build. These are served from /_next/static, which
+ * is immutable: a name that outlives its bytes pins a stale runtime in every
+ * browser that saw the previous deploy. Two routes whose entries are byte
+ * identical collapse onto one file — a URL they can honestly share.
+ */
+async function fingerprintClientEntries(outDir: string, entries: ClientEntry[]) {
+  await Promise.all(
+    entries.map(async entry => {
+      const from = path.join(outDir, `${entry.entryName}.js`)
+      const bytes = await readFile(from).catch(() => undefined)
+      if (!bytes) return
+      const name = `pnext-client-${assetContentHash(bytes)}.js`
+      entry.route.clientEntry = `assets/${name}`
+      const to = path.join(outDir, name)
+      if (to === from) return
+      const sourceMap = `${from}.map`
+      if (existsSync(sourceMap)) {
+        // The linked map moves with the entry, so the comment has to move too.
+        const source = bytes.toString('utf8').replaceAll(`${entry.entryName}.js.map`, `${name}.map`)
+        await writeFile(to, source)
+        await rm(from, { force: true })
+        await rename(sourceMap, `${to}.map`)
+        return
+      }
+      await rename(from, to)
+    }),
+  )
+}
+
 interface ClientEntry {
   route: RouteManifestEntry
   entryName: string
@@ -1905,12 +1939,15 @@ export interface ClientCacheKeyParts {
 }
 
 /**
- * The half of the key that is not a walked source: the client build pipeline's own sources, the
- * generated entry, and the route's reference list. A handful of small reads, so it is cheap to
- * recompute on every lookup - which is what lets the expensive source walk be validated from a
- * persisted index instead (see dev/restart/client-key.ts).
+ * The half of the key that is not a walked source: pnext's own generation, the generated entry, and
+ * the route's reference list. Cheap to recompute on every lookup - which is what lets the expensive
+ * source walk be validated from a persisted index instead (see dev/restart/client-key.ts).
+ *
+ * The generation, not a list of the pipeline's own files: that list named seven of them and missed
+ * the router runtime the entry pulls in, so editing it left every route's out-dir named for the
+ * bundle it no longer builds.
  */
-export async function clientCacheStaticHash(
+export function clientCacheStaticHash(
   route: RouteManifestEntry,
   nextCompat?: boolean,
   config?: ResolvedConfig,
@@ -1919,12 +1956,8 @@ export async function clientCacheStaticHash(
   // never reads a memo an earlier call left behind.
   conventionCache.clear()
   const hash = createHash('sha256')
-  for (const file of clientBuildPipelineFiles()) {
-    hash.update(file)
-    hash.update('\0')
-    hash.update(await readText(file))
-    hash.update('\0')
-  }
+  hash.update(frameworkFingerprint())
+  hash.update('\0')
 
   hash.update(
     clientEntrySource({
@@ -1944,6 +1977,11 @@ export async function clientCacheStaticHash(
     }),
   )
   hash.update('\0')
+  // The build is scoped to the route id (virtual entry, source pipeline, surface signature, deferred
+  // dynamic href), so it belongs in the key: without it two routes with the same client closure share
+  // an out-dir, and their entries either overwrite each other or serve one another's bytes.
+  hash.update(route.id)
+  hash.update('\0')
   hash.update(route.client ? route.file : '')
   hash.update(JSON.stringify(route.clientReferences))
   return hash.digest('hex')
@@ -1989,7 +2027,7 @@ export async function clientCacheKeyParts(
   config?: ResolvedConfig,
   staticHash?: string,
 ): Promise<ClientCacheKeyParts> {
-  const staticDigest = staticHash ?? (await clientCacheStaticHash(route, nextCompat, config))
+  const staticDigest = staticHash ?? clientCacheStaticHash(route, nextCompat, config)
   const sources = await Promise.all(
     (await clientSourceFiles(route)).map(file => readClientCacheSource(file)),
   )
@@ -2004,18 +2042,6 @@ export async function clientCacheKey(
   return (await clientCacheKeyParts(route, nextCompat, config)).key
 }
 
-function clientBuildPipelineFiles() {
-  return [
-    path.join(import.meta.dirname, 'entry.ts'),
-    path.resolve(import.meta.dirname, '..', 'api', 'router.ts'),
-    path.resolve(import.meta.dirname, '..', 'api', 'client-navigation.ts'),
-    path.join(import.meta.dirname, 'react-compiler.ts'),
-    path.join(import.meta.dirname, 'build.ts'),
-    path.resolve(import.meta.dirname, '..', 'compat', 'react', 'client.ts'),
-    path.resolve(import.meta.dirname, '..', 'compat', 'react', 'preact.ts'),
-  ].filter(file => existsSync(file))
-}
-
 async function clientSourceFiles(route: RouteManifestEntry) {
   const entryFiles = [
     ...(route.client ? [route.file] : []),

package/src/client/entry.ts

@@ -291,6 +291,22 @@ import { isActionError } from ${JSON.stringify(actionClientModulePath())};`,
 // The `$$pnextError` marker is written by the renderer's action-prop serializer, which returns props
 // untouched when next compat is off - so core and react entries import the ref+binary reviver and the
 // error branch never ships.
+/**
+ * Both wire carriers - an island's `data-pnext-props` markers and the client page's
+ * `__PNEXT_PROPS__` - must rebuild the same legacy sync surface, so they share one rebuilder. The
+ * server stamps the flag only under compat.next.legacyRequestAPIs; a strict app reads params the
+ * async way and must not grow a surface its server render never had.
+ *
+ * Emitted under next compat only - the flag rides compat's document scripts, so a core/react entry
+ * could never see it and ships neither the import nor the call.
+ */
+function syncPropsHelperSource() {
+  return `
+import { rebuildSyncProps as __pnextRebuildSyncProps } from ${JSON.stringify(serializeModulePath())};
+const __pnextSyncProps = () => (typeof window !== 'undefined' && window.__PNEXT_SYNC_PROPS__ ? __pnextRebuildSyncProps : undefined);
+`
+}
+
 function propsParserSource(nextCompat?: boolean) {
   const revive = nextCompat ? 'reviveSerializedErrorRefs' : 'reviveSerializedRefs'
   return `
@@ -322,7 +338,7 @@ function parseIslandProps(raw) {
   // 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;
+  return __pnextHasPromiseProps(raw || '') ? __pnextRevivePromiseMarkers(revived${nextCompat ? ', __pnextSyncProps()' : ''}) : revived;
 }
 `
 }
@@ -699,6 +715,7 @@ ${nextCompat ? "import { options as __pnextPreactOptions } from 'preact';" : ''}
 ${deferredIslands ? "import { useEffect, useState } from 'preact/hooks';" : ''}
 ${suspense ? "import { Suspense } from 'preact/compat';" : ''}
 ${revival ? layoutSegmentHelperSource(nextCompat) : ''}
+${nextCompat && (revival || page) ? syncPropsHelperSource() : ''}
 ${revival ? propsParserSource(nextCompat) : ''}
 ${revival ? islandHelpersSource(facts) : ''}
 ${islandCssHelperSource()}
@@ -918,6 +935,7 @@ const pnextMountedRoots = new Set();
 let pnextIslandMounts;
 let pnextRender;
 
+${nextCompat ? syncPropsHelperSource() : ''}
 ${propsParserSource(nextCompat)}
 ${compatBoundary}
 export function mountRoute() {
@@ -1195,16 +1213,21 @@ const rawProps = window.__PNEXT_PROPS__ ?? {};
 // Pre-fulfilled promises (status/value readable synchronously): use() must
 // not suspend during page hydration or preact appends fragment siblings
 // instead of reusing the server DOM.
-const fulfilled = value => {
+// Under compat.next.legacyRequestAPIs the server also gave these promises the resolved object's
+// own keys (withSyncProps), so Next-14 code reads \`params.creator\` without await; rebuild that
+// same surface here or the hydrated page loses every param the SSR render had.
+${nextCompat ? 'const legacy = __pnextSyncProps();' : ''}
+const fulfilled = (kind, value) => {
   const promise = Promise.resolve(value);
   promise.status = 'fulfilled';
   promise.value = value;
-  return promise;
+  return ${nextCompat ? 'legacy ? legacy(promise, kind, value) : promise' : 'promise'};
 };
 return {
   ...rawProps,
-  params: fulfilled(rawProps.params ?? {}),
+  params: fulfilled('params', rawProps.params ?? {}),
   searchParams: fulfilled(
+    'searchParams',
     rawProps.searchParams ?? Object.fromEntries(new URLSearchParams(location.search)),
   ),
 };

package/src/client/router/page-slot.ts

@@ -0,0 +1,81 @@
+type PageSlotRange = [start: Element | Comment, end: Comment | undefined, nodes: ChildNode[]]
+
+/** Resolve either wire form of a page slot inside a preserved server segment. */
+export function pageSlotRange(segment: Element): PageSlotRange | null {
+  const element = segment.querySelector('#pnext-page')
+  if (element) return [element, undefined, [...element.childNodes]]
+  const walker = document.createTreeWalker(segment, 128 /* NodeFilter.SHOW_COMMENT */)
+  while (walker.nextNode()) {
+    const start = walker.currentNode as Comment
+    if (!start.data.startsWith('pnext-page:')) continue
+    const nodes: ChildNode[] = []
+    let end = start.nextSibling
+    while (end && !(end.nodeType === 8 && end.nodeValue === '/pnext-page')) {
+      nodes.push(end)
+      end = end.nextSibling
+    }
+    return end ? [start, end as Comment, nodes] : null
+  }
+  return null
+}
+
+/** Whether an element belongs to the page slot in either DOM form. */
+export function elementInPageSlot(element: Element): boolean {
+  return !!(
+    element.closest('#pnext-page') ||
+    pageSlotRange(document.body)?.[2].some(node => node.contains(element))
+  )
+}
+
+/**
+ * Graft a destination page into a preserved layout without changing the destination's mount shape.
+ * Client pages need the real `#pnext-page` element; server/island-only pages need the marker range.
+ */
+export function graftPageSlot(liveSegment: Element, incomingSegment: Element): boolean {
+  const live = pageSlotRange(liveSegment)
+  const incoming = pageSlotRange(incomingSegment)
+  if (!live || !incoming) return false
+  const nodes = reusePageNodes(live[2], incoming[2])
+  for (const stale of live[2]) stale.remove()
+  const end = incoming[1]
+  if (!end) (incoming[0] as Element).replaceChildren(...nodes)
+  else {
+    for (const stale of incoming[2]) stale.remove()
+  }
+  live[0].replaceWith(incoming[0])
+  if (end) incoming[0].after(...nodes, end)
+  live[1]?.remove()
+  return true
+}
+
+// Next re-renders a page in place, so unchanged DOM keeps its node identity.
+function reusePageNodes(live: readonly ChildNode[], incoming: readonly Node[]): Node[] {
+  const candidates = live.filter(
+    (node): node is Element =>
+      node instanceof Element &&
+      !node.matches('script, pnext-client, #pnext-page') &&
+      !node.querySelector('pnext-client, #pnext-page, [data-pnext-preserve]'),
+  )
+  return incoming.map(node => {
+    if (!(node instanceof Element)) return node
+    const index = candidates.findIndex(candidate => candidate.outerHTML === node.outerHTML)
+    return index === -1 ? node : candidates.splice(index, 1)[0]!
+  })
+}
+
+export interface LoadingShellTarget {
+  container: HTMLElement
+  markerRange?: PageSlotRange
+}
+
+/** Resolve a safe loading-shell target without falling through a dissolved page to the body. */
+export function loadingShellTarget(): LoadingShellTarget {
+  const page = document.getElementById('pnext-page')
+  if (page) return { container: page }
+  const markerRange = pageSlotRange(document.body)
+  if (markerRange?.[1]) {
+    return { container: markerRange[0].parentElement!, markerRange }
+  }
+  const root = document.querySelector<HTMLElement>('[data-pnext-root]')
+  return { container: root ?? document.body }
+}