@wular/pnext 0.0.24 → 0.1.0

package/src/client/build.ts

@@ -99,6 +99,13 @@ interface ClientBatchBuildOptions {
   routes: RouteManifestEntry[]
   outDir: string
   verbose?: boolean
+  /**
+   * Dev-server batch build: one esbuild graph over every client route, exactly like prod.
+   * Per-route dev builds gave each route its own module graph, so shared libraries existed
+   * as per-route copies — context identity broke across navigations and every soft nav
+   * remounted the app shell (user-visible splash). Module identity must hold by construction.
+   */
+  dev?: boolean
   /**
    * The app defines at least one server action (the build's action manifest). Unset means "unknown" -
    * dev, where the manifest is discovered per request - and the action runtime is emitted, since only
@@ -597,6 +604,7 @@ export async function buildClientEntries({
   verbose,
   hasServerActions,
   pipeline: warmed,
+  dev,
 }: ClientBatchBuildOptions) {
   if (!warmed) conventionCache.clear()
   const actions = appUsesActions(routes, hasServerActions)
@@ -607,6 +615,7 @@ export async function buildClientEntries({
         route,
         entryName: clientEntryName(route),
         source: clientEntrySource({
+          deferredDynamicHref: devDeferredDynamicHref(dev, route.id),
           pageFile: route.client ? route.file : undefined,
           clientReferences: route.clientReferences,
           nextCompat: nextCompatEnabled(config),
@@ -626,14 +635,14 @@ export async function buildClientEntries({
   // Every route's client sources start their transform and React Compiler pass here, in one batch on
   // oxc's threadpool, while esbuild is still booting and walking the graph. A caller-warmed pipeline
   // has them in flight already; warming twice is a Map hit, so the same call covers both.
-  const pipeline = warmed ?? createClientSourcePipeline(config)
+  const pipeline = warmed ?? createClientSourcePipeline(config, dev === true)
   pipeline.warmRoutes(entries.map(entry => entry.route))
   await ensureDir(outDir)
   const groups = surfaceGroups(config, entries, actions)
   clientProfile.count('group#', groups.length)
   const built: BuiltEntryGroup[] = []
   for (const group of groups) {
-    built.push(await buildEntryGroup({ config, outDir, entries, group, pipeline, verbose }))
+    built.push(await buildEntryGroup({ config, outDir, entries, group, pipeline, verbose, dev }))
   }
 
   // Fold and rename once over the finished output, never per group. Chunk names
@@ -647,19 +656,42 @@ export async function buildClientEntries({
     Object.assign(merged.outputs, item.metafile.outputs)
   }
   merged = await clientProfile.timeAsync('fold', () =>
-    foldInitialChunks({ outDir, metafile: merged, buildOptions: baseClientBuildOptions(config) }),
+    // `dev` is load-bearing, not cosmetic: the fold rides the minify flag and must stay a no-op in
+    // dev. Dev emits absolute publicPath specifiers, which the fold's rewriter cannot express — it
+    // would unlink the merged members and leave every entry importing a deleted chunk.
+    foldInitialChunks({
+      outDir,
+      metafile: merged,
+      buildOptions: baseClientBuildOptions(config, dev),
+    }),
   )
   const renames = await clientProfile.timeAsync('write', () =>
     nameSharedClientChunks(outDir, merged),
   )
-  clientProfile.time('entryImports', () => {
-    for (const item of built) {
-      if (item.metafile) {
-        assignClientEntryImports(item.group.entries, merged, outDir, renames, item.prebuilt)
+  // Entry-import lists become modulepreload links with prod /_next/static URLs; dev serves
+  // chunks under /__pnext/client and re-derives everything per request, so baking prod URLs
+  // onto the routes would emit preloads that 404 in the dev document.
+  if (!dev) {
+    clientProfile.time('entryImports', () => {
+      for (const item of built) {
+        if (item.metafile) {
+          assignClientEntryImports(item.group.entries, merged, outDir, renames, item.prebuilt)
+        }
       }
-    }
-  })
-  await clientProfile.timeAsync('fingerprint', () => fingerprintClientEntries(outDir, entries))
+    })
+  }
+  // Dev serves entries by their stable route-derived names (/__pnext/client/<id>.js) and
+  // re-resolves them per request; the immutable-content rename is prod-deploy machinery and
+  // would also mutate route.clientEntry under the dev renderer's feet.
+  if (!dev) {
+    await clientProfile.timeAsync('fingerprint', () => fingerprintClientEntries(outDir, entries))
+  }
+  if (dev && devDynamicSplitEnabled() && pipeline.deferredRefs().size > 0) {
+    await writeText(
+      path.join(outDir, DEFERRED_DYNAMIC_SIDECAR),
+      JSON.stringify(Object.fromEntries(pipeline.deferredRefs())),
+    )
+  }
   clientProfile.report('client stage')
 }
 
@@ -761,6 +793,7 @@ async function buildEntryGroup({
   group,
   pipeline,
   verbose,
+  dev,
 }: {
   config: ResolvedConfig
   outDir: string
@@ -769,15 +802,17 @@ async function buildEntryGroup({
   group: SurfaceGroup
   pipeline: ClientSourcePipeline
   verbose?: boolean
+  dev?: boolean
 }): Promise<BuiltEntryGroup> {
-  const reactLite = group.facts.suspense === false
+  const facts: ClientRuntimeFacts = dev ? { ...group.facts, dev: true } : group.facts
+  const reactLite = facts.suspense === false
   const prebuilt = await clientProfile.timeAsync('prebuilt', () =>
     preparePrebuilt(
       config,
       outDir,
-      false,
+      dev === true,
       importer => {
-        if (importer === CLIENT_RUNTIME_MODULE) return clientRuntimeSource(group.facts)
+        if (importer === CLIENT_RUNTIME_MODULE) return clientRuntimeSource(facts)
         const entry = entries.find(item => item.route.id === importer)
         return entry?.source ?? pipeline.sourceOf(importer) ?? readTextSyncSafe(importer)
       },
@@ -787,29 +822,51 @@ async function buildEntryGroup({
   )
 
   let metafile: Metafile | undefined
-  try {
-    const result = await clientProfile.timeAsync('esbuild', () =>
-      build({
-        ...baseClientBuildOptions(config),
-        entryPoints: group.entries.map(entry => ({
+  const split = Boolean(dev) && devDynamicSplitEnabled()
+  const groupDynEntries = () => {
+    const byId = new Map<string, DeferredDynamicEntry>()
+    if (!split) return []
+    for (const entry of group.entries) {
+      for (const dynEntry of deferredDynamicEntries(entry.route)) byId.set(dynEntry.id, dynEntry)
+    }
+    return [...byId.values()]
+  }
+  let dynEntries = groupDynEntries()
+  const runGroupBuild = () =>
+    build({
+      ...baseClientBuildOptions(config, dev),
+      entryPoints: [
+        ...group.entries.map(entry => ({
           in: virtualEntryPath(entry.route.id),
           out: entry.entryName,
         })),
-        outdir: outDir,
-        metafile: true,
-        plugins: clientBuildPlugins(
-          config,
-          pipeline,
-          [
-            ...(prebuilt ? [prebuilt.plugin] : []),
-            virtualEntryPlugin(group.entries),
-            clientRuntimePlugin(group.facts),
-          ],
-          reactLite,
-        ),
-      }),
-    )
+        ...dynEntries.map(entry => ({ in: entry.file, out: entry.id })),
+      ],
+      // Absolute chunk URLs: an on-demand dyn output is served from a different path than
+      // the entry, and a relative specifier would fetch one chunk under two URLs — two
+      // module instances (see buildClientEntry).
+      ...(split ? { publicPath: devClientPublicPath } : {}),
+      outdir: outDir,
+      metafile: true,
+      plugins: clientBuildPlugins(
+        config,
+        pipeline,
+        [
+          ...(prebuilt ? [prebuilt.plugin] : []),
+          virtualEntryPlugin(group.entries),
+          ...(split ? [deferredDynamicExternalPlugin()] : []),
+          clientRuntimePlugin(facts),
+        ],
+        reactLite,
+      ),
+    })
+  try {
+    const result = await clientProfile.timeAsync('esbuild', () => runGroupBuild())
     metafile = result.metafile
+    // NOTE deliberately no discovered-refs second pass here (unlike buildClientEntry): a
+    // rebuild re-emits raw chunk-*.js after the prebuilt runtime settled against the first
+    // pass's names, and the merged rename map then orphans them. Mid-build-discovered
+    // dynamic refs fall back to the shared graph until the next generation.
   } catch (error) {
     // A batched build cannot attribute a "Could not resolve" error to a single route, so fall back to
     // per-route builds - the offending route then throws with its precise client import trace. Other
@@ -817,7 +874,7 @@ async function buildEntryGroup({
     // per-route build surface a more confusing downstream error.
     if (!hasUnresolvedImportError(error)) throw error
     for (const { route } of group.entries) {
-      await buildClientEntry({ config, route, outDir })
+      await buildClientEntry({ config, route, outDir, dev })
     }
     throw error
   }
@@ -2099,23 +2156,96 @@ function rootFromFile(file: string) {
   return path.dirname(file)
 }
 
-// esbuild names every shared chunk "chunk-<hash>", which makes bundle reports
-// unreadable. Rename each one after the module that dominates it by size in
-// the metafile: the package name for node_modules code, the file stem for app
-// code. Falls back to "shared" when a build ran without a metafile.
-async function nameSharedClientChunks(outDir: string, metafile?: Metafile) {
+// Give every split output a payload-addressed name after its import specifiers
+// have their final values. Equal final bytes therefore collapse to one URL.
+export async function nameSharedClientChunks(outDir: string, metafile?: Metafile) {
   if (metafile && traceEnabled('client')) {
     await writeText(path.join(outDir, 'metafile.json'), JSON.stringify(metafile))
   }
   const chunksDir = path.join(outDir, 'chunks')
-  const files = (await listFiles(chunksDir)).filter(file => file.endsWith('.js'))
+  const chunkFiles = await listFiles(chunksDir)
+  const files = chunkFiles.filter(file => file.endsWith('.js'))
   const labels = metafile ? chunkLabelsFromMetafile(metafile) : new Map<string, string>()
   const renames = new Map<string, string>()
+  const mapRenames = new Map<string, string>()
+  await Promise.all(
+    chunkFiles
+      .filter(file => file.endsWith('.js.map'))
+      .map(async file => {
+        const basename = path.basename(file)
+        const next = `chunk-map-${assetContentHash(await readFile(file))}.js.map`
+        mapRenames.set(basename, next)
+        if (basename !== next) await rename(file, path.join(chunksDir, next))
+      }),
+  )
+  const sources = new Map(
+    await Promise.all(
+      files.map(async file => [file, replaceChunkNames(await readText(file), mapRenames)] as const),
+    ),
+  )
+  const sourceByName = new Map(
+    [...sources].map(([file, source]) => [path.basename(file), source] as const),
+  )
+  const names = [...sourceByName.keys()].sort()
+  const dependencies = new Map(
+    names.map(name => [
+      name,
+      new Set(names.filter(candidate => sourceByName.get(name)!.includes(candidate))),
+    ]),
+  )
 
-  for (const file of files) {
-    const basename = path.basename(file)
-    if (!basename.startsWith('chunk-')) continue
-    renames.set(basename, `${labels.get(basename) ?? 'shared'}-${hashSuffix(basename)}.js`)
+  // A chunk's final bytes include its dependencies' final names. Collapse
+  // cycles, then process the component DAG dependency-first so the hash put in
+  // every acyclic filename is computed from exactly the bytes we write.
+  const groups = chunkDependencyGroups(names, dependencies)
+  const groupByName = new Map(groups.flatMap((group, index) => group.map(name => [name, index])))
+  const pending = new Set(groups.map((_, index) => index))
+  const finalSources = new Map<string, string>()
+  while (pending.size > 0) {
+    let progressed = false
+    for (const groupIndex of pending) {
+      const group = groups[groupIndex]!
+      const waitsFor = group.some(name =>
+        [...(dependencies.get(name) ?? [])].some(dependency => {
+          const dependencyGroup = groupByName.get(dependency)
+          return dependencyGroup !== groupIndex && pending.has(dependencyGroup!)
+        }),
+      )
+      if (waitsFor) continue
+
+      const rewritten = new Map(
+        group.map(name => [name, replaceChunkNames(sourceByName.get(name)!, renames)]),
+      )
+      const cyclic = group.length > 1 || (dependencies.get(group[0]!)?.has(group[0]!) ?? false)
+      if (cyclic) {
+        // A cryptographic self-reference has no practical fixed point. Hash a
+        // canonical form whose intra-cycle names are stable placeholders, and
+        // put that group hash in every member name. Any member change therefore
+        // renames the whole strongly-connected component together.
+        const placeholders = new Map(
+          group.map((name, index) => [name, `__pnext_cycle_${index}.js`]),
+        )
+        const canonical = group
+          .map(name => replaceChunkNames(rewritten.get(name)!, placeholders))
+          .join('\0')
+        const groupHash = assetContentHash(canonical)
+        for (const [index, name] of group.entries()) {
+          renames.set(name, `${clientChunkLabel(name, labels)}-${groupHash}-${index}.js`)
+        }
+      } else {
+        const name = group[0]!
+        renames.set(
+          name,
+          `${clientChunkLabel(name, labels)}-${assetContentHash(rewritten.get(name)!)}.js`,
+        )
+      }
+      for (const name of group) {
+        finalSources.set(name, replaceChunkNames(rewritten.get(name)!, renames))
+      }
+      pending.delete(groupIndex)
+      progressed = true
+    }
+    if (!progressed) throw new Error('Unable to order client chunk dependency groups')
   }
 
   if (renames.size === 0) return renames
@@ -2132,17 +2262,7 @@ async function nameSharedClientChunks(outDir: string, metafile?: Metafile) {
         // the reference rewrite below still points at the renamed file.
         if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
       }
-      // Move the external sourcemap alongside its chunk. The `sourceMappingURL`
-      // comment in the renamed chunk is rewritten below (replaceChunkNames matches
-      // the `chunk-<hash>.js` prefix inside `chunk-<hash>.js.map`), so the map file
-      // must adopt the new name to keep the link resolvable.
-      const fromMap = `${fromPath}.map`
-      if (!existsSync(fromMap)) return
-      try {
-        await rename(fromMap, `${toPath}.map`)
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-      }
+      await writeText(toPath, finalSources.get(from)!)
     }),
   )
 
@@ -2151,8 +2271,9 @@ async function nameSharedClientChunks(outDir: string, metafile?: Metafile) {
   const outputs = (await listFiles(outDir)).filter(item => item.endsWith('.js'))
   await Promise.all(
     outputs.map(async file => {
-      const source = await readText(file)
-      const next = replaceChunkNames(source, renames)
+      const originalName = path.basename(file)
+      const source = sources.get(file) ?? (await readText(file))
+      const next = finalSources.get(originalName) ?? replaceChunkNames(source, renames)
       if (next !== source) await writeText(file, next)
     }),
   )
@@ -2160,8 +2281,9 @@ async function nameSharedClientChunks(outDir: string, metafile?: Metafile) {
   return renames
 }
 
-function hashSuffix(file: string) {
-  return path.basename(file, '.js').split('-').at(-1) ?? 'chunk'
+function clientChunkLabel(file: string, labels: Map<string, string>) {
+  if (file.startsWith('chunk-')) return labels.get(file) ?? 'shared'
+  return path.basename(file, '.js').replace(/-(?:[A-Z0-9]{8}|[0-9a-f]{16})$/, '')
 }
 
 function chunkLabelsFromMetafile(metafile: Metafile) {
@@ -2206,6 +2328,43 @@ function sanitizeChunkLabel(label: string) {
   return clean || undefined
 }
 
+function chunkDependencyGroups(names: string[], dependencies: Map<string, Set<string>>) {
+  let nextIndex = 0
+  const indices = new Map<string, number>()
+  const lowLinks = new Map<string, number>()
+  const stack: string[] = []
+  const onStack = new Set<string>()
+  const groups: string[][] = []
+
+  const visit = (name: string) => {
+    const index = nextIndex++
+    indices.set(name, index)
+    lowLinks.set(name, index)
+    stack.push(name)
+    onStack.add(name)
+    for (const dependency of dependencies.get(name) ?? []) {
+      if (!indices.has(dependency)) {
+        visit(dependency)
+        lowLinks.set(name, Math.min(lowLinks.get(name)!, lowLinks.get(dependency)!))
+      } else if (onStack.has(dependency)) {
+        lowLinks.set(name, Math.min(lowLinks.get(name)!, indices.get(dependency)!))
+      }
+    }
+    if (lowLinks.get(name) !== indices.get(name)) return
+    const group: string[] = []
+    for (;;) {
+      const member = stack.pop()!
+      onStack.delete(member)
+      group.push(member)
+      if (member === name) break
+    }
+    groups.push(group.sort())
+  }
+
+  for (const name of names) if (!indices.has(name)) visit(name)
+  return groups
+}
+
 function replaceChunkNames(source: string, renames: Map<string, string>) {
   const pattern = new RegExp([...renames.keys()].map(escapeRegex).join('|'), 'g')
   return source.replace(pattern, match => renames.get(match) ?? match)

package/src/client/chunk-fold.ts

@@ -360,6 +360,10 @@ function memberRewriter(
     new RegExp(String.raw`import\s*\*\s*as\s*[\w$]+\s*from\s*${specifier}`),
     new RegExp(String.raw`export\s*\*[^;]*from\s*${specifier}`),
     new RegExp(String.raw`import\(\s*${specifier}`),
+    // The merged chunk's href is computed RELATIVE to each referrer, so a member named through an
+    // absolute specifier (a publicPath URL) cannot be re-pointed. Unlinking it anyway leaves the
+    // referrer importing a file that no longer exists — a 404 for every chunk, and a blank app.
+    new RegExp(String.raw`"[^".][^"]*(?:${memberPattern})"`),
   ]
   const namedImport = new RegExp(
     String.raw`(import|export)\s*${namedClause}\s*from\s*(${specifier})`,
@@ -471,7 +475,9 @@ interface FoldOutput {
 }
 
 function foldOutput(text: string): FoldOutput {
-  return { text, specifiers: [...text.matchAll(/"\.[^"]*"/g)].map(match => match[0]) }
+  // Absolute specifiers are indexed too, though the rewriter cannot express them: a referrer the
+  // index cannot see is a referrer the fold silently strands. Being visible lets the veto fire.
+  return { text, specifiers: [...text.matchAll(/"[./][^"]*"/g)].map(match => match[0]) }
 }
 
 /** Every output's text plus a basename->referrers index, read once. Chunk names

package/src/client/entry.ts

@@ -1155,7 +1155,7 @@ function mountIsland(root, island) {
 async function mountIslandTree(root, island) {
   const [{ h, hydrate, render }${facts.suspense !== false ? ', { Suspense }' : ''}, Component] = await Promise.all([
     import('preact'),${facts.suspense !== false ? "\n    import('preact/compat')," : ''}
-    island.load(),
+    islandComponent(island),
   ]);
 ${facts.suspense !== false ? '  islandBoundary = Suspense;\n' : ''}  const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
@@ -1169,7 +1169,7 @@ ${facts.suspense !== false ? '  islandBoundary = Suspense;\n' : ''}  const rawPr
 }
 
 async function mountIslandTree(root, island) {
-  const [{ h, hydrate, render }, Component] = await Promise.all([import('preact'), island.load()]);
+  const [{ h, hydrate, render }, Component] = await Promise.all([import('preact'), islandComponent(island)]);
   const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const source = preservedSource(root, render);
   const vnode = islandVNode(h, Component, await islandProps(rawProps, source, node => domChildren(h, node), h), await staticChildren(h, source, island.id));
@@ -1178,6 +1178,20 @@ async function mountIslandTree(root, island) {
 }`
 }
 
+// Dev route entries each bundle their own copy of a shared island component, and Preact
+// diffs by component IDENTITY: mounting the destination entry's copy would remount every
+// preserved island on navigation (a splash gate re-splashes, a reel restarts). The first
+// loaded instance of an island id wins for the document's lifetime; a dev recompile
+// full-reloads the page, which resets the registry. Prod ships one entry, so this is a
+// no-op there.
+// NOTE: pinning a single component instance across dev route entries is NOT safe here:
+// each dev entry carries its own module graph, and a pinned provider's context object
+// would not match the consuming entry's copy (breaks e.g. QueryClientProvider). Module
+// graphs must be deduped at the bundler level instead.
+async function islandComponent(island) {
+  return island.Component ?? await island.load();
+}
+
 // A root preserved across a soft navigation carries the incoming placeholder
 // (fresh SSR children) stashed by the router; render children from it when this
 // preact instance owns the live tree. A foreign entry copy (dev bundles) can't
@@ -1256,9 +1270,15 @@ async function domNode(h, node) {
     const id = element.getAttribute('data-pnext-client');
     const island = islands.find(candidate => candidate.id === id);
     if (!island) return h(element.localName, domProps(element), await domChildren(h, element));
-    const Component = island.Component ?? await island.load();
+    const Component = await islandComponent(island);
     const rawProps = element.getAttribute('data-pnext-props') ?? '{}';
-    const vnode = islandVNode(h, Component, await islandProps(rawProps, element, node => domChildren(h, node), h), await staticChildren(h, element, island.id));
+    const props = await islandProps(rawProps, element, node => domChildren(h, node), h);
+    // Adopted DOM is diffed positionally, and SSR-state-only siblings (a splash overlay the
+    // server rendered that the live tree no longer shows) shift positions between renders.
+    // A nested island must match its previous incarnation by IDENTITY, or the shift remounts
+    // it and resets its state - Next never remounts layout components on navigation.
+    if (props.key === undefined) props.key = 'pnext-island:' + id;
+    const vnode = islandVNode(h, Component, props, await staticChildren(h, element, island.id));
     return ${nextCompat ? 'islandBoundary ? h(islandBoundary, { fallback: null }, pnextClientBoundary(h, vnode)) : pnextClientBoundary(h, vnode)' : 'vnode'};
   }
 
@@ -1574,8 +1594,19 @@ function mountIsland(root, island) {
   return mountIslandOnce(root, () => mountIslandTree(root, island));
 }
 
+// Dev route entries each bundle their own copy of a shared island component; Preact diffs
+// by identity, so mounting another entry's copy would remount every preserved island on
+// navigation. First loaded instance per island id wins; a dev recompile full-reloads.
+// NOTE: pinning a single component instance across dev route entries is NOT safe here:
+// each dev entry carries its own module graph, and a pinned provider's context object
+// would not match the consuming entry's copy (breaks e.g. QueryClientProvider). Module
+// graphs must be deduped at the bundler level instead.
+async function islandComponent(island) {
+  return island.Component ?? await island.load();
+}
+
 async function mountIslandTree(root, island) {
-  const Component = island.Component ?? await island.load();${
+  const Component = await islandComponent(island);${
     nextCompat
       ? `
   window.__PNEXT_ACTIONS__?.registerClientReference(island.id, Component);`
@@ -1584,7 +1615,13 @@ async function mountIslandTree(root, island) {
   const rawProps = root.getAttribute('data-pnext-props') ?? '{}';
   const incoming = root.__pnextIncoming;
   root.__pnextIncoming = undefined;
-  if (incoming && root.__pnextLive === render) {
+  // A streamed chunk promoted INSIDE this root's adopted children (the hard-loaded document
+  // finishes streaming long after hydration) replaced DOM this preact tree owns without
+  // telling it. Its vdom still names the fallback, so a diff would build the incoming
+  // children BESIDE the promoted ones. Rebuild from the incoming DOM instead.
+  const streamGrafted = root.__pnextStreamGrafted;
+  root.__pnextStreamGrafted = undefined;
+  if (incoming && root.__pnextLive === render && !streamGrafted) {
     // Preserved across a soft navigation: re-render in place with the incoming
     // document's props/children so component state survives while the routed
     // content under the island updates.
@@ -1675,7 +1712,7 @@ async function domNode(node) {
     }`
         : ''
     }
-    const Component = island.Component ?? await island.load();
+    const Component = await islandComponent(island);
     return ${wrapInBoundary(islandVNodeExpr('Component', 'await islandProps(rawProps, element, domChildren, h)', 'children', 'element', nextCompat), nextCompat)};
   }