@wular/pnext 0.0.19 → 0.0.21

package/src/css/build.ts

@@ -1,11 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { writeFile } from 'node:fs/promises'
+import { readFile, rename, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import type { Plugin } from 'esbuild'
+import { hashedAssetName } from '../utils/asset-hash'
 import { build } from '../utils/esbuild'
 import { ensureDir, readText } from '../utils/fs'
 import { postcssConfigFile, runPostcss } from './postcss'
 import { extraPageExtensions, getCssExtensions } from '../extensions'
+import { nextCompatEnabled } from '../render/hooks'
 import { resolveImport } from '../resolve/imports'
 import { createVerboseLogger } from '../utils/verbose'
 import type { ClientReference } from '../client/reference'
@@ -222,20 +224,116 @@ function rootLayoutFile(appPath: string, missing?: Set<string>) {
 }
 
 export function globalCssHref(config: ResolvedConfig) {
-  return globalCssSources(config).length > 0
-    ? withAssetPrefix(config, '/assets/global.css')
-    : undefined
+  return globalCssSources(config).length > 0 ? assetHref(config, 'global.css') : undefined
+}
+
+export type AssetHrefConfig = Pick<ResolvedConfig, 'assetPrefix' | 'compat' | 'outPath'>
+
+/**
+ * Logical build-asset name -> the content-hashed name the build actually emitted
+ * (`global.css` -> `global-1f4a9c2b3d5e6f70.css`). A production asset name must
+ * carry its content, or the URL cannot honestly be served `immutable`: the same
+ * name would answer different bytes after a deploy.
+ *
+ * Keyed by outPath, never process-global: one process builds several apps (the
+ * test suite does it constantly) and their names must not cross. Empty in dev,
+ * where names stay flat and every asset is served `no-cache` anyway.
+ */
+const emittedAssets = new Map<string, Map<string, string>>()
+
+export function recordEmittedAsset(outPath: string, logical: string, emitted: string): void {
+  const names = emittedAssets.get(outPath) ?? new Map<string, string>()
+  names.set(logical, emitted)
+  emittedAssets.set(outPath, names)
+}
+
+/** Re-publish the build's name map at server boot (see BuildManifest.assetNames). */
+export function publishEmittedAssets(
+  outPath: string,
+  names: Record<string, string> | undefined,
+): void {
+  if (!names) return
+  for (const [logical, emitted] of Object.entries(names))
+    recordEmittedAsset(outPath, logical, emitted)
+}
+
+export function emittedAssetNames(outPath: string): Record<string, string> {
+  return Object.fromEntries(emittedAssets.get(outPath) ?? [])
+}
+
+export function clearEmittedAssets(outPath: string): void {
+  emittedAssets.delete(outPath)
+}
+
+/** The file name a logical asset name resolves to. Identity until a build records one. */
+export function emittedAssetName(
+  config: Pick<ResolvedConfig, 'outPath'> | undefined,
+  name: string,
+): string {
+  if (!config?.outPath) return name
+  return emittedAssets.get(config.outPath)?.get(name) ?? name
+}
+
+// Where a built asset lives in the URL space. next-compat serves the build output under Next's
+// static path, so a compat app's document references its CSS/JS exactly as Next does; core keeps
+// `/assets/`. Every document-emitted build-asset URL goes through here (and the dev/prod servers
+// accept both spellings), so an emitted href can never name a path the server will not serve —
+// including the content hash the production name carries.
+export function assetPathname(
+  config: Pick<ResolvedConfig, 'compat' | 'outPath'> | undefined,
+  name: string,
+) {
+  const emitted = emittedAssetName(config, name)
+  return nextCompatEnabled(config ?? {}) ? `/_next/static/${emitted}` : `/assets/${emitted}`
+}
+
+export function assetHref(config: AssetHrefConfig | undefined, name: string) {
+  return withAssetPrefix(config, assetPathname(config, name))
+}
+
+// A route's built CSS filenames - the one rule behind the document's links, the
+// inline-CSS path and analyze, so no consumer can disagree about whether a
+// route has CSS. compat cssChunking records split names in cssAssets.
+export function routeCssAssetNames(
+  route: Pick<RouteManifestEntry, 'id' | 'cssImports' | 'cssAssets'>,
+): string[] {
+  if (route.cssImports.length === 0) return []
+  return route.cssAssets?.length ? route.cssAssets : [`${route.id}.css`]
 }
 
 export function routeCssHref(
   route: RouteManifestEntry,
-  config?: Pick<ResolvedConfig, 'assetPrefix'>,
+  config?: AssetHrefConfig,
 ): string | string[] | undefined {
-  if (route.cssImports.length === 0) return undefined
-  if (route.cssAssets?.length) {
-    return route.cssAssets.map(asset => withAssetPrefix(config, `/assets/${asset}`))
-  }
-  return withAssetPrefix(config, `/assets/${route.id}.css`)
+  const assets = routeCssAssetNames(route)
+  if (assets.length === 0) return undefined
+  return assets.map(asset => assetHref(config, asset))
+}
+
+/**
+ * Put a render's next/font rules in the first stylesheet chunk, matching Next's
+ * linked CSS delivery without changing the rest of the route's chunk order.
+ */
+export async function emitFontCssStylesheet(
+  config: ResolvedConfig,
+  routeId: string,
+  fontCss: string,
+  baseAsset: string | undefined,
+  options: { dev: boolean },
+) {
+  const outDir = path.join(config.outPath, options.dev ? 'cache' : 'public', 'assets')
+  await ensureDir(outDir)
+  const baseFile = baseAsset ? path.join(outDir, baseAsset) : undefined
+  const baseCss = baseFile && existsSync(baseFile) ? await readFile(baseFile, 'utf8') : ''
+  const contents = [fontCss, baseCss].filter(Boolean).join('\n')
+  const logicalName = baseAsset
+    ? baseAsset.replace(/-[0-9a-f]{16}(?=\.css$)/, '')
+    : `${routeId}.css`
+  const name = hashedAssetName(logicalName, contents)
+  const file = path.join(outDir, name)
+  if (!existsSync(file) || (await readFile(file, 'utf8')) !== contents)
+    await writeFile(file, contents)
+  return name
 }
 
 // Prepend the configured assetPrefix (a CDN origin or path) to an app-absolute
@@ -296,7 +394,11 @@ export async function buildGlobalCss(config: ResolvedConfig, options: CssBuildOp
       minify: !options.dev,
       conditions: ['style', 'browser'],
       assetNames: 'files/[name]-[hash]',
-      plugins: [...getCssExtensions().cssChunkPlugins(), ...cssDirectiveOrderPlugins(postcss)],
+      plugins: [
+        cssPublicUrlPlugin(),
+        ...getCssExtensions().cssChunkPlugins(),
+        ...cssDirectiveOrderPlugins(postcss),
+      ],
       loader: {
         '.css': 'css',
         '.module.css': 'css',
@@ -319,8 +421,30 @@ export async function buildGlobalCss(config: ResolvedConfig, options: CssBuildOp
     )
   }
 
-  log.log(`global css → ${path.relative(config.root, outfile)}`)
-  return outfile
+  const emitted = await fingerprintAsset(config, outDir, 'global.css', options)
+  log.log(`global css → ${path.relative(config.root, emitted)}`)
+  return emitted
+}
+
+/**
+ * Rename a freshly built asset to carry its content hash, and record the
+ * logical -> emitted mapping every href/file consumer resolves through.
+ * Dev keeps flat names: nothing there is served immutable, and the dev server
+ * addresses these files by their logical name.
+ */
+async function fingerprintAsset(
+  config: Pick<ResolvedConfig, 'outPath'>,
+  outDir: string,
+  assetName: string,
+  options: CssBuildOptions,
+) {
+  const outfile = path.join(outDir, assetName)
+  if (options.dev) return outfile
+  const emittedName = hashedAssetName(assetName, await readFile(outfile))
+  const emitted = path.join(outDir, emittedName)
+  if (emitted !== outfile) await rename(outfile, emitted)
+  recordEmittedAsset(config.outPath, assetName, emittedName)
+  return emitted
 }
 
 function moduleSpecifiers(source: string) {
@@ -491,6 +615,7 @@ async function bundleCssChunk(
     assetNames: 'files/[name]-[hash]',
     // Lazy registry read: compat (sass) plugins register at bootstrap.
     plugins: [
+      cssPublicUrlPlugin(),
       ...getCssExtensions().cssChunkPlugins(),
       cssModuleBuildPlugin(),
       ...cssDirectiveOrderPlugins(postcss),
@@ -515,7 +640,21 @@ async function bundleCssChunk(
     await log.step(`${label}: postcss`, () => runPostcssOffThread(config, outfile, options))
   }
 
-  return outfile
+  return fingerprintAsset(config, outDir, assetName, options)
+}
+
+// A leading slash in a CSS url() is a public URL, not an app-root filesystem
+// path. Keep it verbatim so the production bundle matches the dev server and
+// Next's public/ asset contract; relative URLs still use esbuild's file loader.
+function cssPublicUrlPlugin(): Plugin {
+  return {
+    name: 'pnext-css-public-url',
+    setup(plugin) {
+      plugin.onResolve({ filter: /^\// }, args =>
+        args.kind === 'url-token' ? { path: args.path, external: true } : undefined,
+      )
+    },
+  }
 }
 
 export function registerCssRuntime() {

package/src/css/postcss.ts

@@ -75,9 +75,10 @@ export async function runPostcss(
   // `DEBUG=tailwindcss` marker keys off `result.opts.from`). We still write the
   // processed output back to the bundle outfile via `to`.
   const from = fromSource ?? cssFile
+  const css = await readText(cssFile)
   // The scan directives go last so they don't shift the line numbers plugins
   // report against the real source; `@source` is order-independent to Tailwind.
-  const result = await loaded.processor.process((await readText(cssFile)) + loaded.sources, {
+  const result = await loaded.processor.process(css + keptExclusions(loaded.sources, css, from), {
     from,
     to: cssFile,
   })
@@ -112,7 +113,35 @@ async function createPostcssProcessor(root: string, options: PostcssOptions) {
  * Excluding these three by name restores that behaviour without narrowing what a correctly-ignored
  * checkout already scans. Apps that really do keep Tailwind-classed sources in one of them set
  * `PNEXT_TAILWIND_SCAN_ALL`.
+ *
+ * A pure function of (root, outDir) — deliberately NOT of what is on disk. The processor is built
+ * once and cached, and `warmCssPipeline` builds it before the build has written its output, so an
+ * `existsSync` here made the exclusion set depend on which of the two got there first: the same
+ * stylesheet compiled with or without utilities minted out of pnext's own emitted JS.
  */
+/**
+ * An appended `@source not <dir>` silences every explicit `@source` glob the stylesheet points
+ * under that dir - Tailwind gives `not` precedence - so an app opting INTO scanning a package
+ * (`@source '../../node_modules/x/dist/...'`) lost those utilities entirely. Keep only the
+ * exclusions that no explicit `@source` in this stylesheet reaches into.
+ */
+export function keptExclusions(exclusions: string, css: string, fromFile: string): string {
+  if (!exclusions) return exclusions
+  const dir = path.dirname(fromFile)
+  const globs = [...css.matchAll(/@source\s+(?!not\s)['"]([^'"]+)['"]/g)].map(m =>
+    path.resolve(dir, m[1]!.replace(/[*{[].*$/, '')),
+  )
+  if (globs.length === 0) return exclusions
+  const kept = exclusions
+    .split('\n')
+    .filter(line => {
+      const m = /@source not "([^"]+)"/.exec(line)
+      return !m || !globs.some(glob => glob === m[1] || glob.startsWith(m[1] + '/'))
+    })
+    .join('\n')
+  return kept.includes('@source not') ? kept : ''
+}
+
 function scanExclusions(root: string, appRequire: NodeJS.Require, options: PostcssOptions) {
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   if (process.env.PNEXT_TAILWIND_SCAN_ALL) return ''
@@ -120,8 +149,8 @@ function scanExclusions(root: string, appRequire: NodeJS.Require, options: Postc
   const [major, minor] = packageVersion(appRequire, '@tailwindcss/postcss')
   if (major < 4 || (major === 4 && minor < 1)) return ''
   const dirs = ['node_modules', '.next', options.outDir ?? '.pnext']
-  const excluded = [...new Set(dirs.map(dir => path.resolve(root, dir)))].filter(
-    dir => dir.startsWith(root + path.sep) && existsSync(dir),
+  const excluded = [...new Set(dirs.map(dir => path.resolve(root, dir)))].filter(dir =>
+    dir.startsWith(root + path.sep),
   )
   if (excluded.length === 0) return ''
   // Leading and trailing newlines keep the stylesheet's own first and last

package/src/dev/restart/client-key.ts

@@ -83,7 +83,7 @@ export async function devClientCacheKey(
 ): Promise<string> {
   if (!restartCacheEnabled()) return (await clientCacheKeyParts(route, nextCompat, config)).key
   const cache = keyCache(config)
-  const staticHash = await clientCacheStaticHash(route, nextCompat, config)
+  const staticHash = clientCacheStaticHash(route, nextCompat, config)
   const entry = cache.routes.get(route.id)
   if (entry?.static === staticHash) {
     const revalidated = await revalidate(entry.files)

package/src/dev/restart/global-css.ts

@@ -10,19 +10,17 @@
 //   content differs   -> discard, walk again, record the new answer
 // Paths the walk found ABSENT are re-checked too: a stylesheet restored while the server was not
 // running adds an edge that no importer's bytes record.
-import { mkdirSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import type { ResolvedConfig } from '../../config'
 import { setGlobalCssSourceStore, type GlobalCssSourceStore } from '../../css/build'
 import { traceEnabled } from '../../utils/trace-flags'
 import { restartCacheEnabled } from './enabled'
-
-/** `[file, mtimeMs, size, contentHash]` — the shape the other restart caches use. */
-type SourceEntry = [string, number, number, string]
+import { hash, lazyRecordCacheKey, revalidate, sourceEntries, type SourceEntry } from './record'
 
 interface RecordFile {
   version: number
-  /** Everything the answer depends on that is not a walked source (see cacheKey). */
+  /** Everything the answer depends on that is not a walked source (see restart/record.ts). */
   key: string
   files: SourceEntry[]
   missing: string[]
@@ -32,47 +30,15 @@ interface RecordFile {
 /** Bumped whenever a record's shape changes; an older record is simply ignored. */
 const RECORD_VERSION = 1
 
-const hash = (value: string) => Bun.hash(value).toString(36)
-
-/**
- * The walk's answer can change without any app file moving, when the thing that
- * *interprets* the graph does: the resolver's config (aliases, conditions, page
- * extensions) or pnext itself. Both go in the key, so either one moving makes
- * the record read as a miss instead of half-validating it.
- */
-function cacheKey(config: ResolvedConfig): string | undefined {
-  try {
-    const shape = JSON.stringify(config, (_key, value: unknown) =>
-      typeof value === 'function' ? '[fn]' : value,
-    )
-    return hash(`${RECORD_VERSION}\n${pnextBuildStamp()}\n${shape}`)
-  } catch {
-    return undefined // a config that will not serialize simply opts out
-  }
-}
-
-/** mtime+size of the walk this process is running (see restart/route-facts.ts). */
-function pnextBuildStamp() {
-  try {
-    const self = Bun.fileURLToPath(import.meta.url)
-    const walk = path.join(path.dirname(path.dirname(self)), 'css', 'build.ts')
-    const info = statSync(walk, { throwIfNoEntry: false })
-    return info ? `${info.mtimeMs}:${info.size}` : self
-  } catch {
-    return 'unknown'
-  }
-}
-
 export function installGlobalCssCache(config: ResolvedConfig) {
   if (!restartCacheEnabled()) return
   // eslint-disable-next-line turbo/no-undeclared-env-vars
   if (process.env.PNEXT_DEV_GLOBAL_CSS_CACHE === '0') return
-  const key = cacheKey(config)
-  if (!key) return
-  setGlobalCssSourceStore(createStore(path.join(config.outPath, 'cache', 'global-css'), key))
+  const dir = path.join(config.outPath, 'cache', 'global-css')
+  setGlobalCssSourceStore(createStore(dir, lazyRecordCacheKey(config, RECORD_VERSION)))
 }
 
-function createStore(dir: string, key: string): GlobalCssSourceStore {
+function createStore(dir: string, cacheKey: () => string | undefined): GlobalCssSourceStore {
   // Last payload written per walk, so a save that re-runs the walk with an
   // unchanged answer costs no write, and one with a changed answer does.
   const written = new Map<string, string>()
@@ -80,8 +46,10 @@ function createStore(dir: string, key: string): GlobalCssSourceStore {
 
   return {
     load(walkKey) {
-      const record = readRecord(recordFile(walkKey), key)
-      if (!record) {
+      // A config that will not serialize has no key, so it simply always walks.
+      const key = cacheKey()
+      const record = key ? readRecord(recordFile(walkKey), key) : undefined
+      if (!key || !record) {
         stats.misses += 1
         return undefined
       }
@@ -111,6 +79,8 @@ function createStore(dir: string, key: string): GlobalCssSourceStore {
       return record.sources
     },
     save(walkKey, sources, visited, missing) {
+      const key = cacheKey()
+      if (!key) return
       const files = sourceEntries(visited)
       if (!files) return
       write(recordFile(walkKey), key, written, walkKey, files, missing, sources)
@@ -161,58 +131,6 @@ function write(
   }
 }
 
-function sourceEntries(files: string[]): SourceEntry[] | undefined {
-  const entries: SourceEntry[] = []
-  for (const file of files) {
-    const entry = sourceEntry(file)
-    if (!entry) return undefined
-    entries.push(entry)
-  }
-  return entries
-}
-
-function sourceEntry(file: string): SourceEntry | undefined {
-  try {
-    const source = readFileSync(file, 'utf8')
-    // Stat AFTER the read: a file that changes between the two records the
-    // older stat, so the next boot re-hashes rather than trusting a stale one.
-    const info = statSync(file, { throwIfNoEntry: false })
-    if (!info) return undefined
-    return [file, info.mtimeMs, info.size, hash(source)]
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * The recorded sources, re-stated: `files` itself when nothing moved, a fresh list when only stats moved,
- * `undefined` when any content actually differs - or a source is gone, which is the same thing, since the
- * walk has to run again.
- */
-function revalidate(files: SourceEntry[]): SourceEntry[] | undefined {
-  let moved = false
-  const checked: SourceEntry[] = []
-  for (const entry of files) {
-    const [file, mtimeMs, size, contentHash] = entry
-    const info = statSync(file, { throwIfNoEntry: false })
-    if (!info) return undefined
-    if (info.mtimeMs === mtimeMs && info.size === size) {
-      checked.push(entry)
-      continue
-    }
-    let source: string
-    try {
-      source = readFileSync(file, 'utf8')
-    } catch {
-      return undefined
-    }
-    if (hash(source) !== contentHash) return undefined
-    moved = true
-    checked.push([file, info.mtimeMs, info.size, contentHash])
-  }
-  return moved ? checked : files
-}
-
 /** Bisect seam: `PNEXT_TRACE=server` prints the hit/miss split at exit. */
 const stats = { hits: 0, misses: 0 }
 if (traceEnabled('server')) {

package/src/dev/restart/record.ts

@@ -0,0 +1,106 @@
+// Shared spine of the persisted restart records (global-css, route-facts): the key everything a
+// record depends on that is NOT a walked source folds into, and the stat->hash ladder that
+// revalidates the sources themselves. Both halves were duplicated per record; a key rule that lives
+// in two copies is a key rule that gets fixed in one of them.
+import { readFileSync, statSync } from 'node:fs'
+import type { ResolvedConfig } from '../../config'
+import { frameworkFingerprint } from '../../runtime/fingerprint'
+import { cacheRoot } from '../../runtime/module-cache'
+
+/** `[file, mtimeMs, size, contentHash]` — the shape every restart cache records. */
+export type SourceEntry = [string, number, number, string]
+
+export const hash = (value: string) => Bun.hash(value).toString(36)
+
+/**
+ * A record's answer can change without any app file moving, when the thing that *interprets* the
+ * graph does: the resolver's config (aliases, conditions, page extensions) or pnext itself.
+ *
+ * The framework half is the CONTENT of pnext's whole shipped tree, never the mtime+size of one
+ * hand-picked walker file. A record derived by reading many framework files cannot be keyed on one
+ * of them - the stamp is blind to an edit in any of the others - and mtime+size is not content: a
+ * same-length edit landing in the same mtime tick moved nothing the stamp could see. The tree
+ * fingerprint is already computed at boot for the module cache and memoized per process, so this
+ * costs a memo read.
+ */
+export function recordCacheKey(config: ResolvedConfig, version: number): string | undefined {
+  try {
+    const shape = JSON.stringify(config, (_key, value: unknown) =>
+      typeof value === 'function' ? '[fn]' : value,
+    )
+    return hash(`${version}\n${frameworkFingerprint(cacheRoot(config.outPath))}\n${shape}`)
+  } catch {
+    // A config that will not serialize (cycles, exotic values) simply opts out.
+    return undefined
+  }
+}
+
+/**
+ * The same key, on first USE rather than at install. The stores are installed during boot but first
+ * read on the first page, and the fingerprint the key folds in is paid by the module cache on that
+ * same page - so computing it eagerly does not save the work, it just moves it in front of the
+ * server being ready to serve.
+ */
+export function lazyRecordCacheKey(config: ResolvedConfig, version: number) {
+  let key: string | undefined
+  let computed = false
+  return () => {
+    if (!computed) {
+      computed = true
+      key = recordCacheKey(config, version)
+    }
+    return key
+  }
+}
+
+export function sourceEntries(files: string[]): SourceEntry[] | undefined {
+  const entries: SourceEntry[] = []
+  for (const file of files) {
+    const entry = sourceEntry(file)
+    if (!entry) return undefined
+    entries.push(entry)
+  }
+  return entries
+}
+
+export function sourceEntry(file: string): SourceEntry | undefined {
+  try {
+    const source = readFileSync(file, 'utf8')
+    // Stat AFTER the read: a file that changes between the two records the
+    // older stat, so the next boot re-hashes rather than trusting a stale one.
+    const info = statSync(file, { throwIfNoEntry: false })
+    if (!info) return undefined
+    return [file, info.mtimeMs, info.size, hash(source)]
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The recorded sources, re-stated: `files` itself when nothing moved, a fresh list when only stats moved,
+ * `undefined` when any content actually differs - or a source is gone, which is the same thing, since the
+ * walk has to run again.
+ */
+export function revalidate(files: SourceEntry[]): SourceEntry[] | undefined {
+  let moved = false
+  const checked: SourceEntry[] = []
+  for (const entry of files) {
+    const [file, mtimeMs, size, contentHash] = entry
+    const info = statSync(file, { throwIfNoEntry: false })
+    if (!info) return undefined
+    if (info.mtimeMs === mtimeMs && info.size === size) {
+      checked.push(entry)
+      continue
+    }
+    let source: string
+    try {
+      source = readFileSync(file, 'utf8')
+    } catch {
+      return undefined
+    }
+    if (hash(source) !== contentHash) return undefined
+    moved = true
+    checked.push([file, info.mtimeMs, info.size, contentHash])
+  }
+  return moved ? checked : files
+}