@wular/pnext 0.0.20 → 0.0.21

package/package.json

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

package/src/cli/build/cache.ts

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { lstat, mkdir, readFile, readdir, readlink } from 'node:fs/promises'
+import path from 'node:path'
+import type { ResolvedConfig } from '../../config'
+import { frameworkFingerprint } from '../../runtime/fingerprint'
+import type { BuildManifest } from '../../types'
+import { writeFileAtomic } from '../../utils/fs'
+
+const CACHE_VERSION = 2
+const CACHE_SEGMENTS = ['cache', 'build'] as const
+const SKIP_INPUT_DIRS = new Set([
+  '.claude',
+  '.git',
+  '.husky',
+  '.next',
+  '.pnext',
+  '.tmp',
+  '.turbo',
+  '.vercel',
+  '.vscode',
+  'node_modules',
+])
+const SKIP_INPUT_FILE = /(?:^\.DS_Store$|\.(?:log|pid)$)/i
+const LOCK_FILES = [
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'npm-shrinkwrap.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+]
+
+type InputRecord = [mtimeMs: number, size: number, hash: string]
+
+interface CacheRecord {
+  version: number
+  key: string
+  inputs: Record<string, InputRecord>
+  outputHash: string
+  outputs: Record<string, string>
+}
+
+export interface BuildCacheOptions {
+  adapter?: 'vercel'
+  debugBuildPaths?: string
+  buildMode?: 'compile' | 'generate'
+  debugPrerender?: boolean
+}
+
+export interface BuildCacheSession {
+  enabled: boolean
+  context?: string
+  inputs?: Record<string, InputRecord>
+  manifest?: BuildManifest
+  reason?: string
+}
+
+/** Validate the standard production build before its output directory is touched. */
+export async function lookupBuildCache(
+  config: ResolvedConfig,
+  options: BuildCacheOptions,
+): Promise<BuildCacheSession> {
+  if (!cacheEnabled(options)) return { enabled: false }
+  const record = await readRecord(config.outPath)
+  const inputs = await inputRecords(config, record?.inputs)
+  const context = buildContext()
+  const key = buildKey(context, inputs)
+  if (record?.key !== key) return { enabled: true, context, inputs, reason: 'inputs' }
+  const output = await outputSnapshot(config.outPath)
+  if (output.hash !== record.outputHash) {
+    const changed = changedFiles(record.outputs, output.files).slice(0, 3).join(', ')
+    return { enabled: true, context, inputs, reason: `output (${changed || 'unknown'})` }
+  }
+  try {
+    const manifest = JSON.parse(
+      await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
+    ) as BuildManifest
+    return { enabled: true, context, inputs, manifest, reason: 'hit' }
+  } catch {
+    return { enabled: true, context, inputs, reason: 'manifest' }
+  }
+}
+
+/** Publish a successful build only after every production artifact has landed. */
+export async function writeBuildCache(
+  config: ResolvedConfig,
+  options: BuildCacheOptions,
+  session: BuildCacheSession,
+) {
+  if (!session.enabled || !session.context || !cacheEnabled(options)) return
+  const inputs = await inputRecords(config, session.inputs)
+  const output = await outputSnapshot(config.outPath)
+  const record: CacheRecord = {
+    version: CACHE_VERSION,
+    key: buildKey(session.context, inputs),
+    inputs,
+    outputHash: output.hash,
+    outputs: output.files,
+  }
+  await mkdir(cacheDir(config.outPath), { recursive: true })
+  await writeFileAtomic(recordFile(config.outPath), JSON.stringify(record))
+}
+
+function cacheEnabled(options: BuildCacheOptions) {
+  // Opt-in until the no-change short-circuit is finished: the key currently hashes the whole
+  // environment, so cross-shell hits are rare and the cache adds bookkeeping without payoff.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (process.env.PNEXT_BUILD_CACHE !== '1') return false
+  return (
+    options.adapter === undefined &&
+    options.debugBuildPaths === undefined &&
+    options.buildMode === undefined &&
+    options.debugPrerender !== true
+  )
+}
+
+function cacheDir(outPath: string) {
+  return path.join(outPath, ...CACHE_SEGMENTS)
+}
+
+function recordFile(outPath: string) {
+  return path.join(cacheDir(outPath), 'result.json')
+}
+
+async function readRecord(outPath: string): Promise<CacheRecord | undefined> {
+  try {
+    const parsed = JSON.parse(await readFile(recordFile(outPath), 'utf8')) as CacheRecord
+    if (
+      parsed.version === CACHE_VERSION &&
+      parsed.key &&
+      parsed.inputs &&
+      parsed.outputHash &&
+      parsed.outputs
+    ) {
+      return parsed
+    }
+  } catch {
+    // A partial or older entry is a miss, never a stale hit.
+  }
+  return undefined
+}
+
+function buildContext() {
+  const hash = createHash('sha256')
+  hash.update(`pnext-build-cache:${CACHE_VERSION}\0`)
+  hash.update(frameworkFingerprint())
+  hash.update(`\0bun:${Bun.version}\0`)
+  for (const [name, value] of Object.entries(process.env).sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(`${name}=${value ?? ''}\0`)
+  }
+  return hash.digest('hex')
+}
+
+function buildKey(context: string, inputs: Record<string, InputRecord>) {
+  const hash = createHash('sha256')
+  hash.update(context)
+  for (const [file, record] of Object.entries(inputs).sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(`${file}\0${record[2]}\0`)
+  }
+  return hash.digest('hex')
+}
+
+async function inputRecords(
+  config: ResolvedConfig,
+  previous: Record<string, InputRecord> | undefined,
+) {
+  const files = new Map<string, string>()
+  await collectTree(config.root, 'root', files, config.outPath)
+  await collectModuleGraphInputs(config, files)
+
+  // Dependency trees are represented by package-manager content identities,
+  // while first-party modules above are keyed by their own bytes.
+  for (const [prefix, root] of [
+    ['root-deps', config.root],
+    ['workspace-deps', config.workspaceRoot],
+  ] as const) {
+    for (const name of LOCK_FILES) addFile(files, `${prefix}:${name}`, path.join(root, name))
+    addFile(
+      files,
+      `${prefix}:node_modules/.package-lock.json`,
+      path.join(root, 'node_modules', '.package-lock.json'),
+    )
+  }
+
+  const frameworkRoot = path.resolve(import.meta.dirname, '..', '..')
+  addFile(files, 'framework:package.json', path.join(frameworkRoot, 'package.json'))
+  for (const name of LOCK_FILES) {
+    addFile(files, `framework:${name}`, path.join(frameworkRoot, name))
+    addFile(files, `framework-workspace:${name}`, path.join(frameworkRoot, '..', name))
+  }
+
+  const entries = await Promise.all(
+    [...files].map(async ([key, file]): Promise<[string, InputRecord] | undefined> => {
+      const stats = await lstat(file).catch(() => undefined)
+      if (!stats?.isFile() && !stats?.isSymbolicLink()) return undefined
+      const old = previous?.[key]
+      if (old?.[0] === stats.mtimeMs && old[1] === stats.size) return [key, old]
+      const contents = stats.isSymbolicLink()
+        ? Buffer.from(`link:${await readlink(file)}`)
+        : await readFile(file)
+      return [key, [stats.mtimeMs, stats.size, contentHash(contents)]]
+    }),
+  )
+  return Object.fromEntries(
+    entries.filter((entry): entry is [string, InputRecord] => Boolean(entry)),
+  )
+}
+
+interface ModuleGraphIndex {
+  files?: Record<string, unknown>
+}
+
+async function collectModuleGraphInputs(config: ResolvedConfig, files: Map<string, string>) {
+  let parsed: ModuleGraphIndex
+  try {
+    parsed = JSON.parse(
+      await readFile(path.join(config.outPath, 'cache', 'server', 'graph.json'), 'utf8'),
+    ) as ModuleGraphIndex
+  } catch {
+    return
+  }
+  const frameworkRoot = path.resolve(import.meta.dirname, '..', '..')
+  for (const source of Object.keys(parsed.files ?? {})) {
+    const value = source.slice(2).split('/').join(path.sep)
+    const file = source.startsWith('w:')
+      ? path.resolve(config.workspaceRoot, value)
+      : source.startsWith('f:')
+        ? path.resolve(frameworkRoot, value)
+        : source.startsWith('a:')
+          ? value
+          : undefined
+    if (file) addFile(files, `module:${source}`, file)
+  }
+}
+
+async function collectTree(
+  root: string,
+  prefix: string,
+  files: Map<string, string>,
+  outPath: string,
+  dir = root,
+): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  await Promise.all(
+    entries.map(async entry => {
+      const file = path.join(dir, entry.name)
+      if (file === outPath || file.startsWith(`${outPath}${path.sep}`)) return
+      if (entry.isDirectory()) {
+        if (!SKIP_INPUT_DIRS.has(entry.name)) await collectTree(root, prefix, files, outPath, file)
+        return
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) return
+      const relative = path.relative(root, file)
+      // Local server logs and top-level response captures are not compiler
+      // inputs; watching processes commonly rewrite them during a build.
+      if (
+        SKIP_INPUT_FILE.test(entry.name) ||
+        (!relative.includes(path.sep) && /\.html?$/i.test(entry.name))
+      ) {
+        return
+      }
+      addFile(files, `${prefix}:${toPosix(relative)}`, file)
+    }),
+  )
+}
+
+function addFile(files: Map<string, string>, key: string, file: string) {
+  if (existsSync(file)) files.set(key, file)
+}
+
+async function outputSnapshot(outPath: string) {
+  const files = new Map<string, string>()
+  const entries = await readdir(outPath, { withFileTypes: true }).catch(() => [])
+  await Promise.all(
+    entries.map(async entry => {
+      if (entry.name === 'cache' || entry.name === 'dev') return
+      const file = path.join(outPath, entry.name)
+      if (entry.isDirectory()) await collectOutputTree(outPath, file, files)
+      else if (entry.isFile() || entry.isSymbolicLink()) {
+        files.set(toPosix(entry.name), file)
+      }
+    }),
+  )
+  const hash = createHash('sha256')
+  const hashes: Record<string, string> = {}
+  for (const [name, file] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    const stats = await lstat(file)
+    const contents = stats.isSymbolicLink()
+      ? Buffer.from(`link:${await readlink(file)}`)
+      : await readFile(file)
+    const contentsHash = contentHash(contents)
+    hashes[name] = contentsHash
+    hash.update(`${name}\0${contentsHash}\0`)
+  }
+  return { hash: hash.digest('hex'), files: hashes }
+}
+
+function changedFiles(before: Record<string, string>, after: Record<string, string>) {
+  return [...new Set([...Object.keys(before), ...Object.keys(after)])].filter(
+    file => before[file] !== after[file],
+  )
+}
+
+async function collectOutputTree(root: string, dir: string, files: Map<string, string>) {
+  const entries = await readdir(dir, { withFileTypes: true })
+  await Promise.all(
+    entries.map(async entry => {
+      const file = path.join(dir, entry.name)
+      if (entry.isDirectory()) await collectOutputTree(root, file, files)
+      else if (entry.isFile() || entry.isSymbolicLink()) {
+        files.set(toPosix(path.relative(root, file)), file)
+      }
+    }),
+  )
+}
+
+function contentHash(contents: Uint8Array) {
+  return createHash('sha256').update(contents).digest('hex')
+}
+
+function toPosix(file: string) {
+  return path.sep === '/' ? file : file.split(path.sep).join('/')
+}

package/src/cli/build.ts

@@ -84,6 +84,7 @@ import {
 } from '../routing/routes'
 import { interceptionMarkerLevels } from '../routing/slots'
 import { writeTypegen } from './typegen'
+import { lookupBuildCache, writeBuildCache } from './build/cache'
 import { createVerboseLogger, type VerboseLogger } from '../utils/verbose'
 import { bold, cyan, dim, green } from '../utils/ansi'
 import type {
@@ -179,9 +180,7 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
     `${cyan('▲')} ${bold('pnext')} ${dim('— Creating an optimized production build ...\n')}`,
   )
   const config = await loadConfig(root)
-  // Load Tailwind on the CSS worker while the steps below run, so the first
-  // stylesheet doesn't pay its cold boot.
-  warmCssPipeline(config)
+  const buildCache = lookupBuildCache(config, options)
   // Compat plugin loader: the single gated seam that populates the core
   // extension registries when compat is enabled (no-op for pure-core apps).
   // A build compiles immediately, so it takes both tiers up front.
@@ -192,6 +191,21 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // server-boot-only hooks out of the build - Next never runs register() during `next build`, so
   // build prerenders must see a noop tracer.
   runInitHooks(config, { build: true })
+  const cached = await buildCache
+  log.log(`build cache ${cached.reason ?? 'disabled'}`)
+  if (cached.manifest) {
+    printBuildSummary(
+      config,
+      cached.manifest.routes,
+      cached.manifest.staticFiles ?? {},
+      performance.now() - startedAt,
+      Boolean(cached.manifest.proxyModule),
+    )
+    return cached.manifest
+  }
+  // Load Tailwind on the CSS worker while the steps below run, so the first
+  // stylesheet doesn't pay its cold boot.
+  warmCssPipeline(config)
   // The vercel adapter's warm pass runs in its own process; start it here so
   // its boot overlaps the build and only the warming itself lands on the
   // adapter step.
@@ -917,6 +931,8 @@ async function runBuild(root: string | undefined, options: BuildOptions) {
   // (typecheck) are awaited next and reported on their own lines.
   const buildDurationMs = performance.now() - startedAt
   const phases = await settleBuildParallelPhases()
+  flushDevModuleCaches()
+  await writeBuildCache(config, options, cached)
 
   printBuildSummary(
     config,

package/src/cli/create.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs'
 import { mkdir, readdir } from 'node:fs/promises'
 import path from 'node:path'
 import { bold, cyan, dim, green } from '../utils/ansi'
-import { pnextVersionRange } from '../utils/fs'
+import { latestPnextVersionRange } from '../utils/registry'
 import { formatDuration } from '../utils/verbose'
 
 export interface CreateAppOptions {
@@ -27,7 +27,7 @@ export async function createApp(dir: string | undefined, options: CreateAppOptio
   const name = sanitizePackageName(path.basename(target))
   console.log(`${cyan('▲')} ${bold('pnext create')} ${dim(`— scaffolding ${name}`)}\n`)
 
-  const files = scaffoldFiles(name)
+  const files = scaffoldFiles(name, await latestPnextVersionRange('create'))
   await Promise.all(
     Object.entries(files).map(([file, source]) => Bun.write(path.join(target, file), source)),
   )
@@ -112,7 +112,7 @@ function printNextSteps(dir: string, installed: boolean) {
   console.log(dim(`└${'─'.repeat(width + 2)}┘`))
 }
 
-function scaffoldFiles(name: string): Record<string, string> {
+function scaffoldFiles(name: string, pnextRange: string): Record<string, string> {
   return {
     'package.json': `${JSON.stringify(
       {
@@ -126,7 +126,7 @@ function scaffoldFiles(name: string): Record<string, string> {
         },
         dependencies: { preact: '^10' },
         devDependencies: {
-          '@wular/pnext': pnextVersionRange(),
+          '@wular/pnext': pnextRange,
           typescript: '^5',
           '@types/bun': '^1',
         },

package/src/cli/migrate/package-json.ts

@@ -3,7 +3,8 @@
 
 import { readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { pnextOptionalDependencyRange, pnextVersionRange } from '../../utils/fs'
+import { pnextOptionalDependencyRange } from '../../utils/fs'
+import { latestPnextVersionRange } from '../../utils/registry'
 import type { MigrationResult } from './report'
 
 const SEPARATORS = new Set(['&&', '||', ';', '|', '&'])
@@ -124,7 +125,7 @@ export async function migratePackageJson(
     }
   }
   if (!('@wular/pnext' in devDependencies) && !('@wular/pnext' in dependencies)) {
-    const versionRange = pnextVersionRange()
+    const versionRange = await latestPnextVersionRange('migrate')
     devDependencies['@wular/pnext'] = versionRange
     result.edits.push({
       file: 'package.json',

package/src/cli/start.ts

@@ -48,14 +48,9 @@ export async function start(options: StartOptions = {}) {
   const startedAt = Date.now()
   const port = options.port ?? 3000
   const hostname = options.hostname ?? 'localhost'
-  // Export builds are not served by a production start (Next throws). Standalone builds still serve -
-  // Next only WARNS, pointing at the standalone launcher, and the launcher re-execs this path with
-  // `__NEXT_PRIVATE_STANDALONE_CONFIG` set to suppress that warning. Handle both before binding a
-  // port, matching Next's messages.
+  // Export builds are not served; pnext serves its standalone output directly.
   const config = await guardUnservableOutputMode(options.root)
-  const manifest = JSON.parse(
-    await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
-  ) as BuildManifest
+  const manifest = await readProductionManifest(config)
   await ensurePortFree(port, hostname)
 
   // The pipeline import starts right after listen; a request that beats it
@@ -110,10 +105,20 @@ function installProcessErrorHandlers(): void {
   process.on('uncaughtException', report)
 }
 
-// Next's output-mode handling on start: an export build throws (fatal - it is unservable), while a
-// standalone build only warns and serves on, unless the standalone launcher re-execs with
-// `__NEXT_PRIVATE_STANDALONE_CONFIG` set. pnext mirrors that: load the compat config, read the output
-// mode from the build-compat registry, and reproduce Next's exact messages.
+export async function readProductionManifest(config: ResolvedConfig): Promise<BuildManifest> {
+  try {
+    return JSON.parse(
+      await readFile(path.join(config.outPath, 'manifest.json'), 'utf8'),
+    ) as BuildManifest
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error("No production build found. Run 'pnext build' first.")
+    }
+    throw error
+  }
+}
+
+// Export output is unservable; pnext production output remains serveable for standalone apps.
 async function guardUnservableOutputMode(root?: string): Promise<ResolvedConfig> {
   const config = await loadConfig(root, { serve: true })
   await bootstrapCompat(config)
@@ -125,13 +130,6 @@ async function guardUnservableOutputMode(root?: string): Promise<ResolvedConfig>
     )
     process.exit(1)
   }
-  // eslint-disable-next-line turbo/no-undeclared-env-vars
-  if (mode === 'standalone' && !process.env.__NEXT_PRIVATE_STANDALONE_CONFIG) {
-    console.warn(
-      '"next start" does not work with "output: standalone" configuration. ' +
-        'Use "node .next/standalone/server.js" instead.',
-    )
-  }
   return config
 }
 

package/src/client/build.ts

@@ -479,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,

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
@@ -517,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();' : '',
@@ -655,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
@@ -710,7 +854,7 @@ 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';" : ''}
@@ -1137,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;
 }
@@ -1343,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
@@ -1364,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
@@ -1476,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;
@@ -1522,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.
@@ -1536,8 +1725,8 @@ function visibleTarget(root) {
   return root.parentElement ?? root;
 }
 `
-    : ''
-}${mountOnceSource()}${
+      : ''
+  }${mountOnceSource()}${
     deferredIslands
       ? `
 function DeferredIsland({ load, props, children }) {

package/src/compat/metadata.ts

@@ -192,13 +192,6 @@ export async function warnNextMetadataBuildIssues(
     if (route.kind !== 'page') continue
     const routeFacts = await Promise.all(routeSourceFiles(appPath, route).map(factsFor))
     const some = (pick: (fact: MetadataSourceFacts) => boolean) => routeFacts.some(pick)
-    if (some(fact => fact.themeColor)) {
-      warnOnce(
-        warned,
-        `themeColor:${route.route}`,
-        `Unsupported metadata themeColor is configured in metadata export in ${route.route || '/'}. Please move it to viewport\nRead more: https://nextjs.org/docs/app/api-reference/functions/generate-viewport`,
-      )
-    }
     if (some(fact => fact.appleTouchFullscreen)) {
       warnOnce(
         warned,
@@ -246,7 +239,6 @@ async function readSourceTextOrEmpty(file: string) {
  * nearly every file has none of these keys.
  */
 interface MetadataSourceFacts {
-  themeColor: boolean
   appleTouchFullscreen: boolean
   appleTouchIconPrecomposed: boolean
   metadataBase: boolean
@@ -255,7 +247,6 @@ interface MetadataSourceFacts {
 
 function metadataSourceFacts(source: string): MetadataSourceFacts {
   return {
-    themeColor: source.includes('themeColor') && /\bthemeColor\s*:/.test(source),
     appleTouchFullscreen:
       source.includes('apple-touch-fullscreen') && /['"]apple-touch-fullscreen['"]/.test(source),
     appleTouchIconPrecomposed:

package/src/compat/register/proxy.ts

@@ -8,6 +8,7 @@ import { recordRewrite } from '../protocol'
 import { recordCanonicalUrl } from '../next/canonical-url'
 import { getNextConfig } from '../next/config-loader'
 import { activateTestProxy } from '../lifecycle/testmode'
+import { legacyRequestAPIs } from '../../request/context'
 
 export function registerProxyExtensions(_config: ResolvedConfig): void {
   setProxyResponseProtocol({
@@ -72,7 +73,8 @@ async function validateNextProxyFiles(config: ResolvedConfig) {
       `Both middleware file "${relativeProxyPath(config, middleware)}" and proxy file "${relativeProxyPath(config, proxy)}" are detected. Please use "${relativeProxyPath(config, proxy)}" only.`,
     )
   }
-  if (middleware && !proxy) {
+  // Proxy is a Next 16 migration; legacy request APIs explicitly target the middleware era.
+  if (middleware && !proxy && !legacyRequestAPIs()) {
     console.warn('The "middleware" file convention is deprecated. Please use "proxy" instead.')
   }
   await Promise.all(files.map(file => validateNextProxyFile(config, file)))

package/src/compat/register/typed-routes.ts

@@ -11,7 +11,6 @@ import {
 } from '../../extensions'
 import type { RouteManifestEntry } from '../../types'
 import { nextCompatEnabled } from '../aliases'
-import { writeTsconfigDefaults } from '../tsconfig-defaults'
 import { typecheckDisabled, validateTypesOffThread } from '../typecheck/check'
 import { generateTypedRoutes } from '../typed-routes/generate'
 
@@ -21,7 +20,6 @@ export function registerTypedRoutesExtensions(_config: ResolvedConfig): void {
 
 async function runTypedRoutesBuildStep(ctx: BuildStepContext): Promise<void> {
   if (!nextCompatEnabled(ctx.config)) return
-  await writeTsconfigDefaults(ctx.config)
   await generateTypedRoutes(ctx.config, ctx.routes as RouteManifestEntry[])
   // The typecheck reads only files that already exist on disk, so it runs on a worker thread
   // alongside client bundling and prerendering rather than ahead of them; the CLI awaits it before

package/src/compat/validation/validate.ts

@@ -15,6 +15,7 @@ import path from 'node:path'
 import type { ResolvedConfig } from '../../config'
 import { extraPageExtensions } from '../../extensions'
 import type { RouteManifestEntry } from '../../types'
+import { legacyRequestAPIs } from '../../request/context'
 import { getNextConfig } from '../next/config-loader'
 import { stripComments } from '../../utils/code'
 import {
@@ -271,6 +272,7 @@ function warnBuildDiagnostics(config: ResolvedConfig, routes: RouteManifestEntry
     console.warn('Disabled SWC as replacement for Babel because of custom Babel configuration')
   }
   if (
+    !legacyRequestAPIs() &&
     typeof nextConfig.outputFileTracingRoot !== 'string' &&
     !(
       nextConfig.turbopack &&

package/src/render/renderer.ts

@@ -4470,6 +4470,7 @@ export function errorLogTrace(error: Error): string {
 }
 
 function logDevError(options: RenderOptions, error: Error, clientSsrError = false) {
+  if (error.name === 'DynamicServerError') return
   const seen = isBuildError(error) ? loggedBuildErrors : loggedRuntimeErrors
   if (seen.has(error)) return
   seen.add(error)
@@ -6733,7 +6734,7 @@ function anchorInlineSuspenseHoles(html: string): string {
     .replace(/<!--\/\$s:[^>]+?-->/g, '</pnext-hole>')
 }
 
-function clientSuspenseRefreshScript(nonce: string | undefined) {
+export function clientSuspenseRefreshScript(nonce: string | undefined) {
   const nonceAttribute = nonce ? ` nonce="${escapeHtml(nonce)}"` : ''
   // Graft each streamed island's content over its hole. The hole is a `<pnext-hole>` element rather
   // than preact's `$s:ID` comment markers: hydration of an ancestor client layout removes comment
@@ -6873,7 +6874,7 @@ function streamPageSlotMode(options: RenderOptions): PageSlotMarkerMode {
   return pageSlotIsMountTarget(options) ? 'materialize' : 'keep'
 }
 
-function clientIslandMarkerBootstrapSource(mode: PageSlotMarkerMode = 'materialize') {
+export function clientIslandMarkerBootstrapSource(mode: PageSlotMarkerMode = 'materialize') {
   // Pages that mount nothing on #pnext-page never need the wrapper div: the
   // page's children stay direct children of <body>, matching Next's document
   // structure (tests assert structural selectors like `body > p`). `keep`

package/src/utils/registry.ts

@@ -0,0 +1,70 @@
+// Which @wular/pnext a generated project depends on. `bunx @wular/pnext` reuses a cached copy of the
+// package instead of re-resolving the dist-tag, so a stale laptop runs an old CLI — and an old CLI
+// stamping its own version pins the new project to it. The range comes from the registry instead,
+// with the running version as the offline fallback.
+
+import { bold, cyan, dim } from './ansi'
+import { pnextVersionRange } from './fs'
+
+const REGISTRY_URL = 'https://registry.npmjs.org/@wular%2Fpnext'
+// Short: create/migrate must not hang behind a slow or captive network.
+const TIMEOUT_MS = 2000
+
+async function fetchLatestPublishedVersion() {
+  const response = await fetch(REGISTRY_URL, {
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    // The abbreviated document — dist-tags plus versions, without the full metadata.
+    headers: { accept: 'application/vnd.npm.install-v1+json' },
+  })
+  if (!response.ok) return undefined
+  const body = (await response.json()) as { 'dist-tags'?: { latest?: string } }
+  return body['dist-tags']?.latest
+}
+
+// Test seam: the create/migrate suites assert the stamped range and must never hit the network.
+let fetchLatestVersion: () => Promise<string | undefined> = fetchLatestPublishedVersion
+
+/** @internal Test-only. Returns a restore function. */
+export function setLatestVersionFetcher(fetcher: () => Promise<string | undefined>) {
+  const previous = fetchLatestVersion
+  fetchLatestVersion = fetcher
+  return () => {
+    fetchLatestVersion = previous
+  }
+}
+
+/**
+ * '^' + the latest published @wular/pnext, for a project this CLI generates. Never throws and never
+ * blocks for long — any failure falls back to the running version. Warns when the CLI itself is
+ * stale, which is the symptom the user actually has to fix.
+ */
+export async function latestPnextVersionRange(command: 'create' | 'migrate') {
+  const running = pnextVersionRange().slice(1)
+  const latest = await fetchLatestVersion().catch(() => undefined)
+  if (!latest) return `^${running}`
+  if (isNewer(latest, running)) warnStaleCli(command, running, latest)
+  return `^${latest}`
+}
+
+function warnStaleCli(command: string, running: string, latest: string) {
+  console.error(
+    `\n${bold('⚠ Your pnext CLI is out of date')} — running ${running}, latest is ${latest}.\n` +
+      dim(
+        `  bunx reused a cached copy. This project depends on ^${latest}, but ${command} ran with ${running}.\n`,
+      ) +
+      `  Re-run with: ${cyan(`bunx @wular/pnext@latest ${command}`)}\n`,
+  )
+}
+
+/** Numeric major.minor.patch only; anything unparseable counts as "not newer". */
+function isNewer(candidate: string, current: string) {
+  const parts = (value: string) => value.split('-')[0]!.split('.').map(Number)
+  const [a, b] = [parts(candidate), parts(current)]
+  for (let index = 0; index < 3; index += 1) {
+    const left = a[index] ?? 0
+    const right = b[index] ?? 0
+    if (!Number.isFinite(left) || !Number.isFinite(right)) return false
+    if (left !== right) return left > right
+  }
+  return false
+}