@wular/pnext 0.0.19 → 0.0.21

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,
@@ -477,16 +479,19 @@ export async function buildClientEntry({ config, route, outDir, dev }: ClientBui
   const outfile = path.join(outDir, `${entryName}.js`)
   const pipeline = createClientSourcePipeline(config, dev === true, route.id)
   pipeline.warmRoutes([route])
-  const runtimeFacts = clientRuntimeFacts(
-    [
-      {
-        route,
-        shell: hasClientRootLayout(config, route),
-      },
-    ],
-    nextCompatEnabled(config),
-    suspense,
-  )
+  const runtimeFacts: ClientRuntimeFacts = {
+    ...clientRuntimeFacts(
+      [
+        {
+          route,
+          shell: hasClientRootLayout(config, route),
+        },
+      ],
+      nextCompatEnabled(config),
+      suspense,
+    ),
+    dev: dev === true,
+  }
   const prebuilt = await clientProfile.timeAsync('prebuilt', () =>
     preparePrebuilt(
       config,
@@ -654,9 +659,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 +1942,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 +1959,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 +1980,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 +2030,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 +2045,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

@@ -139,6 +139,142 @@ function islandVNodeExpr(
     : `h(${componentExpr}, ${propsExpr}, ${childrenExpr})`
 }
 
+/**
+ * A streamed Suspense hole is the one region a live island stops owning: `$RC` replaces the hole's
+ * children wholesale before the graft's materialize pass turns the arriving island markers into
+ * hosts. Rendering the hole through this component leaves a seam that pass can re-adopt through -
+ * INSIDE the parent island's tree, so the new islands keep the parent's whole context chain. Mounting
+ * such a host as its own preact root instead severs it from every provider the parent renders.
+ */
+function holeSeamSource() {
+  return `
+class PnextHole extends Component {
+  componentDidMount() {
+    if (this.base) this.base.__pnextHole = this;
+  }
+  componentWillUnmount() {
+    if (this.base && this.base.__pnextHole === this) this.base.__pnextHole = undefined;
+  }
+  componentWillReceiveProps(next) {
+    // A soft navigation re-adopts the parent from the incoming document's DOM;
+    // the previous document's grafted content must not outlive its children.
+    if (next.children !== this.props.children) this.setState({ adopted: undefined });
+  }
+  render(props, state) {
+    return h('pnext-hole', props.attrs, state.adopted !== undefined ? state.adopted : props.children);
+  }
+}
+`
+}
+
+/**
+ * The late-host half of the seam. `adoptHoleSeam` re-renders one hole through its live parent;
+ * `claimNestedIslandRoot` is what the island scan calls instead of mounting a nested host.
+ */
+function lateIslandClaimSource() {
+  return `
+// The graft ($RC) swapped this hole's DOM wholesale, so re-adopting ALL of it is total: nothing in
+// the hole is still preact-owned. The re-render lands inside the parent island's tree, which is what
+// makes the new islands inherit its context.
+// Detaching an element costs it every piece of state the browser keeps outside the DOM - a lazy
+// image's deferred load observation, an iframe's document, playing media, focus - and re-inserting
+// it does not bring any of that back. moveBefore is the state-preserving move (Chrome 133+); it
+// needs both ends connected and refuses some moves outright, so a plain insert stays the fallback.
+function movePnextNode(parent, node) {
+  if (parent.moveBefore && parent.isConnected && node.isConnected) {
+    try {
+      parent.moveBefore(node, null);
+      return;
+    } catch (error) {}
+  }
+  parent.append(node);
+}
+
+// A subtree rebuilt from adopted vnodes is made of freshly created elements, and a graft can bring
+// in ones the browser had already deferred. Either way a lazy image can end up in the document with
+// no live intersection observation - no request ever fires, and it stays blank forever. Re-running
+// its source selection re-arms it WITHOUT giving up laziness; one already loading (currentSrc set)
+// or already loaded is left alone, so this never forces a fetch or duplicates one.
+// Drop the capture holder, moving its nodes into \`into\` first when the adoption cannot use them.
+function releaseHoleCapture(hole, into) {
+  const captured = hole.__pnextCaptured;
+  if (!captured) return;
+  hole.__pnextCaptured = undefined;
+  if (into) for (const node of [...captured.childNodes]) movePnextNode(into, node);
+  captured.remove();
+}
+
+function rekickLazyLoadables(root) {
+  for (const img of root.querySelectorAll('img[loading=lazy]')) {
+    if (img.complete || img.currentSrc) continue;
+    for (const name of ['src', 'srcset']) {
+      const value = img.getAttribute(name);
+      if (value === null) continue;
+      img.removeAttribute(name);
+      img.setAttribute(name, value);
+    }
+  }
+}
+
+async function adoptHoleSeam(hole) {
+  const pending = hole.__pnextAdopting;
+  if (pending) return pending;
+  const seam = hole.__pnextHole;
+  // No seam ever appeared: put the captured nodes back rather than losing them.
+  if (!seam) return releaseHoleCapture(hole, hole);
+  const adopting = (async () => {
+    const captured = hole.__pnextCaptured;
+    const children = await domChildren(captured ?? hole);
+    // Preact rebuilds the subtree from the adopted vnodes, so the server nodes they were read from
+    // would survive as unowned duplicates. Clearing and re-rendering within one task keeps the swap
+    // inside a single frame - preact's rerender is a microtask, so no paint sees the empty hole.
+    releaseHoleCapture(hole);
+    hole.replaceChildren();
+    seam.setState({ adopted: children ?? null }, () => rekickLazyLoadables(hole));
+  })();
+  hole.__pnextAdopting = adopting;
+  try {
+    await adopting;
+  } finally {
+    if (hole.__pnextAdopting === adopting) hole.__pnextAdopting = undefined;
+  }
+}
+
+// A nested host belongs to its parent island's DOM adoption pass, never to a mount of its own. Wait
+// out an adoption already in flight (its walk may still reach this host), and claim only what the
+// parent can no longer see - a host the graft materialized after the parent went live - through the
+// hole seam that owns the grafted DOM. A host under a parent that has not mounted yet stays put.
+async function claimNestedIslandRoot(root, parent) {
+  // The innermost hole whose seam is live owns this host. A nearer hole with no seam is raw grafted
+  // DOM inside an outer seam's region, so that outer one is the tree to re-adopt through.
+  let hole;
+  for (let node = root.parentElement; node && node !== parent; node = node.parentElement) {
+    if (node.localName !== 'pnext-hole') continue;
+    if (node.__pnextHole) { hole = node; break; }
+    hole ??= node;
+  }
+  // The parent is mid-adoption and has no seam here yet: its walk may already have snapshotted this
+  // hole's fallback, and its hydration then drops the DOM the graft just landed. Park the grafted
+  // nodes synchronously - ahead of that render - and adopt them from the holder once the tree is
+  // live. A walk that had NOT reached the hole yet simply adopts an empty one and gets the same
+  // content back through the seam. The holder is a hidden ELEMENT rather than a fragment: a
+  // disconnected parent is exactly what strips browser state, and moveBefore refuses one.
+  if (hole && !hole.__pnextHole && !hole.__pnextCaptured && parent.__pnextMounting) {
+    const holder = document.createElement('pnext-hole-capture');
+    holder.hidden = true;
+    document.body.append(holder);
+    hole.__pnextCaptured = holder;
+    for (const node of [...hole.childNodes]) movePnextNode(holder, node);
+  }
+  // A parent whose module failed still settles: the claim has to release its capture rather than
+  // leave the grafted nodes parked in a holder nobody will ever adopt from.
+  await parent.__pnextMounting?.catch(() => {});
+  if (!hole || (!hole.__pnextCaptured && !root.isConnected)) return;
+  return adoptHoleSeam(hole);
+}
+`
+}
+
 // Two mount passes can reach the same island root concurrently - mountRoute and the streamed-Suspense
 // re-scan both walk the document, and their "already live" guard runs BEFORE mountIsland awaits the
 // component module. Without a synchronous claim both passes mount: the first tree is orphaned over the
@@ -291,6 +427,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 +474,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;
 }
 `
 }
@@ -501,15 +653,21 @@ function keepsMountedRoot(root, keep) {
 // The per-route half of the lifecycle, closing over the route's own mount
 // state. mountRoute runs the steps the route actually has: an island scan, the
 // client-shell hydration, the client page.
-function routeLifecycleSource({ nextCompat, islands, page, shell }: ClientRuntimeFacts) {
+function routeLifecycleSource({ nextCompat, islands, page, shell, dev }: ClientRuntimeFacts) {
   const gate = nextCompat
     ? '  pnextGate(markRouteHydrated, pnextIslandMounts, pnextVisibleMount);\n'
     : ''
+  const islandMounts = dev
+    ? `pnextIslandScan.done.then(() => {
+      diagnoseSkippedIslands();
+      return pnextIslandScan.mounted;
+    })`
+    : 'pnextIslandScan.done.then(() => pnextIslandScan.mounted)'
   const mountBody = [
     islands
       ? `  if (islands.length > 0) {
     pnextIslandScan = scanIslands();
-    pnextIslandMounts = pnextIslandScan.done.then(() => pnextIslandScan.mounted);
+    pnextIslandMounts = ${islandMounts};
   }`
       : '',
     shell ? '  if (shell) pnextVisibleMount = hydrateClientShell();' : '',
@@ -639,6 +797,8 @@ ${overlay}installClientErrors({ errorComponent: ${
  * ships only when some route in the app can actually use it.
  */
 export interface ClientRuntimeFacts {
+  /** Development-only diagnostics; omitted entirely from production bundles. */
+  dev?: boolean
   nextCompat?: boolean
   /** Any route mounts islands (island scan, revival, static children). */
   islands?: boolean
@@ -694,11 +854,12 @@ export function clientRuntimeSource(facts: ClientRuntimeFacts) {
   // it revives island DOM exactly like an island mount does.
   const revival = Boolean(facts.islands || shell)
   return `
-import { h, hydrate, render } from 'preact';
+import { ${revival ? 'Component, ' : ''}h, hydrate, render } from 'preact';
 ${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 +1079,7 @@ const pnextMountedRoots = new Set();
 let pnextIslandMounts;
 let pnextRender;
 
+${nextCompat ? syncPropsHelperSource() : ''}
 ${propsParserSource(nextCompat)}
 ${compatBoundary}
 export function mountRoute() {
@@ -1119,6 +1281,10 @@ function domProps(element) {
   return props;
 }
 
+// A nested root belongs to its parent island's DOM adoption pass, never to a
+// mount of its own. This entry carries no streamed-hole seam (see the shared
+// runtime): its whole point is a preact-free first paint, and a host grafted in
+// after a visible island mounted would be dead weight in every bundle.
 function isNestedIslandRoot(root) {
   return root.parentElement?.closest('pnext-client') != null;
 }
@@ -1195,16 +1361,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)),
   ),
 };
@@ -1320,9 +1491,39 @@ function clientBoundaryHelperSource(nextCompat?: boolean, suspense?: boolean) {
 `
 }
 
-function hydrateIslandsSource({ nextCompat, visibleIslands, deferredIslands }: ClientRuntimeFacts) {
+function hydrateIslandsSource({
+  nextCompat,
+  visibleIslands,
+  deferredIslands,
+  dev,
+}: ClientRuntimeFacts) {
+  const diagnostic = dev
+    ? `
+function diagnoseSkippedIslands() {
+  for (const root of document.querySelectorAll('pnext-client[data-pnext-client]')) {
+    if (root.__pnextLive) continue;
+    const id = root.getAttribute('data-pnext-client');
+    const island = id ? islandById.get(id) : undefined;
+    const parent = nestedIslandParent(root);
+    // A visible island is deliberately inert until intersection. A nested
+    // island whose parent is still pending is likewise owned by that parent's
+    // adoption pass, one parked in a capture holder is mid-adoption, and one the
+    // claim pass adopted is no longer in the document. Everything else is a host
+    // this route can never hydrate.
+    if (island?.options?.load === 'visible') continue;
+    if (root.closest('pnext-hole-capture')) continue;
+    if (parent && !parent.__pnextLive) continue;
+    const reason = island
+      ? 'was materialized after its parent island mounted, outside any streamed hole this route can re-adopt'
+      : 'has no entry in the client island manifest';
+    console.warn('pnext: client island ' + (id ?? '<missing id>') + ' ' + reason);
+  }
+}
+`
+    : ''
   return `
 const islandById = new Map(islands.map(island => [island.id, island]));
+${lateIslandClaimSource()}${diagnostic}
 
 // The mounted count is known as soon as the scan loop finishes, before any
 // island module resolves — so the client shell can decide whether it owns the
@@ -1341,7 +1542,11 @@ for (const island of islands) {
   }
 for (const island of islands) {
   for (const root of document.querySelectorAll(\`[data-pnext-client="\${island.id}"]\`)) {
-    if (isNestedIslandRoot(root)) continue;
+    const parent = nestedIslandParent(root);
+    if (parent) {
+      pending.push(claimNestedIslandRoot(root, parent));
+      continue;
+    }
     // Already mounted (e.g. a re-scan after a streamed Suspense hole materialized new islands):
     // mount() stamps __pnextLive, so skipping these leaves the shell's live islands untouched. A root
     // preserved across a soft navigation is ALSO live, but carries the incoming placeholder (fresh SSR
@@ -1453,6 +1658,10 @@ async function domNode(node) {
 
   const element = node;
   if (element.localName === ${JSON.stringify(ISLAND_BOUNDARY_ERROR_ELEMENT)}) return pnextBoundaryErrorVNode(element);
+  // The seam a late streamed graft re-adopts through (see holeSeamSource).
+  if (element.localName === 'pnext-hole') {
+    return h(PnextHole, { attrs: domProps(element) }, await domChildren(element));
+  }
   if (element.localName === 'pnext-client') {
     const id = element.getAttribute('data-pnext-client');
     const island = id ? islandById.get(id) : undefined;
@@ -1499,12 +1708,15 @@ function domProps(element) {
   return props;
 }
 
-function isNestedIslandRoot(root) {
-  return root.parentElement?.closest('pnext-client') != null;
+// The island host that owns this root's DOM, if any. A nested root is never
+// mounted here: the parent adopts it, or claimNestedIslandRoot routes it through
+// the parent's hole seam.
+function nestedIslandParent(root) {
+  return root.parentElement?.closest('pnext-client');
 }
-${
-  visibleIslands
-    ? `
+${holeSeamSource()}${
+    visibleIslands
+      ? `
 function visibleTarget(root) {
   // The host's OWN box: hostMeasureSource delegates the patched one to the
   // parent, and IntersectionObserver never fires for a display:contents target.
@@ -1513,8 +1725,8 @@ function visibleTarget(root) {
   return root.parentElement ?? root;
 }
 `
-    : ''
-}${mountOnceSource()}${
+      : ''
+  }${mountOnceSource()}${
     deferredIslands
       ? `
 function DeferredIsland({ load, props, children }) {

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 }
+}