@wular/pnext 0.0.19 → 0.0.21

package/src/runtime/vendor.ts

@@ -40,7 +40,7 @@ import { fileURLToPath } from 'node:url'
 import { build } from '../utils/esbuild'
 import { isCommonJsModuleSource } from '../resolve/imports'
 import { outputSpecifiers } from './module-transform'
-import { escapeRegex, isIdentifier, uniqueIdentifier } from '../utils/code'
+import { esbuildEntryExportNames, isIdentifier, uniqueIdentifier } from '../utils/code'
 import { cachedExistsSync } from '../utils/fs-cache'
 import { traceEnabled, traceValue } from '../utils/trace-flags'
 import { writeFileAtomic } from '../utils/fs'
@@ -771,23 +771,6 @@ export function commonJsExportNames(code: string) {
     .sort()
 }
 
-// Recover named exports from esbuild's `__export(entry, {...}); module.exports =
-// __toCommonJS(entry)` shape. The entry is emitted last, so the final __toCommonJS.
-function esbuildEntryExportNames(code: string) {
-  const toCommonJs = [
-    ...code.matchAll(/module\.exports\s*=\s*__toCommonJS\w*\(\s*([A-Za-z_$][\w$]*)\s*\)/g),
-  ]
-  const entryVar = toCommonJs.at(-1)?.[1]
-  if (!entryVar) return []
-  const exportCall = new RegExp(
-    `__export\\w*\\(\\s*${escapeRegex(entryVar)}\\s*,\\s*\\{([\\s\\S]*?)\\}\\s*\\)`,
-  ).exec(code)
-  if (!exportCall?.[1]) return []
-  return [...exportCall[1].matchAll(/(?:^|,)\s*([A-Za-z_$][\w$]*)\s*:/g)]
-    .map(match => match[1])
-    .filter((name): name is string => Boolean(name && isIdentifier(name)))
-}
-
 /**
  * The gate every plugin-free artifact has to pass before it is published: esbuild re-bundles the emitted
  * entry, so its own chunk graph has to resolve and its syntax has to be real, and every reference the

package/src/types.ts

@@ -558,6 +558,8 @@ export interface RouteManifestEntry {
   childrenDefault?: string
   /** Intercepting-route metadata, when this route is an interceptor. */
   interception?: RouteInterception
+  /** First `'use server'` module in the route's closure — core refuses these. */
+  serverActionFile?: string
   /**
    * Ship the soft-navigation runtime even without client references. Derived:
    * true exactly when `clientEntryReasons` is non-empty. Kept as its own field
@@ -609,6 +611,8 @@ export interface StaticMetadataFileEntry {
   outputPath: string
   routeSegments: string[]
   contentType: string
+  /** Content-derived URL identity for cache-busted metadata image links. */
+  cacheIdentity?: string
   width?: number
   height?: number
   sizes?: string
@@ -642,6 +646,8 @@ export interface BuildManifest {
   outDir: string
   routes: RouteManifestEntry[]
   staticFiles?: Record<string, StaticFileMetadata>
+  /** Logical build-asset name -> the content-hashed name emitted (`global.css` -> `global-<hash>.css`). */
+  assetNames?: Record<string, string>
   staticMetadataFiles?: StaticMetadataFileEntry[]
   staticModuleMetadata?: Record<string, StaticModuleMetadata>
   staticRouteMetadata?: Record<string, StaticRouteMetadata>

package/src/utils/asset-hash.ts

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * The content fingerprint a build-output asset name carries so its URL can be
+ * served `immutable`. Lowercase hex keeps the emitted name inside the
+ * `<name>-<hash>.<ext>` shape the client chunks and Next's own assets use.
+ */
+export function assetContentHash(bytes: Uint8Array | string): string {
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 16)
+}
+
+/** `global.css` + bytes -> `global-1f4a9c2b3d5e6f70.css`. */
+export function hashedAssetName(name: string, bytes: Uint8Array | string): string {
+  const hash = assetContentHash(bytes)
+  const dot = name.lastIndexOf('.')
+  return dot <= 0 ? `${name}-${hash}` : `${name.slice(0, dot)}-${hash}${name.slice(dot)}`
+}
+
+/** True for a name that already carries an `assetContentHash` fingerprint. */
+export function isHashedAssetName(name: string): boolean {
+  return /-[0-9a-f]{16}(?:\.[^.]+)?$/.test(name)
+}

package/src/utils/code.ts

@@ -37,6 +37,47 @@ export function isIdentifier(value: string) {
   return /^[A-Za-z_$][\w$]*$/.test(value)
 }
 
+/**
+ * Named exports of esbuild's `__export(entry, {...}); module.exports = __toCommonJS(entry)` shape.
+ * Both helpers are matched by POSITION, not by name: a dependency published with `--minify` (tsup's
+ * default, e.g. react-web-share) renames them to one letter, and a literal `__export`/`__toCommonJS`
+ * match left every such package default-only - a hard failure, since the importer's named binding is
+ * static. The `() =>` getter value is what pins the object down as an export map, not any other literal.
+ */
+export function esbuildEntryExportNames(code: string): string[] {
+  const scope = entryCommonJsScope(code)
+  const assignments = [
+    ...scope.matchAll(
+      /module\.exports\s*=\s*(?:[A-Za-z_$][\w$]*\s*\(\s*)?([A-Za-z_$][\w$]*)\s*\)?\s*[;\n]/g,
+    ),
+  ]
+  const entryVar = assignments.at(-1)?.[1]
+  if (!entryVar) return []
+  const exportCall = new RegExp(
+    `[A-Za-z_$][\\w$]*\\(\\s*${escapeRegex(entryVar)}\\s*,\\s*\\{([\\s\\S]*?)\\}\\s*\\)`,
+  ).exec(scope)
+  if (!exportCall?.[1]) return []
+  return [
+    ...exportCall[1].matchAll(
+      /(?:^|,)\s*(?:["']([^"']+)["']|([A-Za-z_$][\w$]*))\s*:\s*\(\s*\)\s*=>/g,
+    ),
+  ]
+    .map(match => match[1] ?? match[2])
+    .filter((name): name is string => Boolean(name && isIdentifier(name)))
+}
+
+/**
+ * The entry CommonJS module's own text. esbuild emits a `__commonJS` wrapper per module, dependencies
+ * first and the entry's last, so slicing from that declaration keeps a dependency's `module.exports`
+ * from being read as the entry's - which would publish names the package does not have.
+ */
+function entryCommonJsScope(code: string) {
+  const wrapper = /(^|\n)export default ([A-Za-z_$][\w$]*)\(\)/.exec(code)?.[2]
+  if (!wrapper) return code
+  const start = code.lastIndexOf(`var ${wrapper} = `)
+  return start === -1 ? code : code.slice(start)
+}
+
 /** Source with comments removed; the `[^:]` guard keeps `://` inside string URLs intact. */
 export function stripComments(source: string): string {
   return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')

package/src/utils/html.ts

@@ -10,7 +10,10 @@ export function escapeHtml(value: unknown) {
       case '"':
         return '"'
       case "'":
-        return '''
+        // React/Next use the hexadecimal spelling in both text and attribute
+        // nodes. Keep our hand-written document/metadata serializers on the
+        // same wire format rather than relying on browser-equivalent entities.
+        return '''
       default:
         return char
     }

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

package/src/utils/serialize.ts

@@ -109,6 +109,11 @@ function encodeContainer(value: object, ancestors: Map<object, string[]>, path:
 // Errors reach `error.tsx` as props and ride the same marker convention (the
 // encoder for this one lives on the render side, with the boundary props).
 const ERROR_MARKER = '$$pnextError'
+// error.tsx's `reset`/`unstable_retry` are FUNCTIONS the framework supplies, so
+// they cross as this marker (renderer serializeConventionProps) and come back as
+// a re-run of the route. Compat's action runtime revives it first and identically;
+// core has no action runtime, so the reviver below is the one that runs.
+const ERROR_RESET_MARKER = '$$pnextErrorReset'
 
 /**
  * Revive the wire markers `serializeProps` wrote, IN PLACE:
@@ -132,7 +137,8 @@ export function reviveSerializedRefs<T>(
       const item = node[key]
       if (item === null || typeof item !== 'object' || ArrayBuffer.isView(item)) continue
       const child = item as Record<string, unknown>
-      const revived = refTarget(root, child) ?? extra?.(child) ?? binaryTarget(child)
+      const revived =
+        refTarget(root, child) ?? extra?.(child) ?? binaryTarget(child) ?? errorResetTarget(child)
       if (revived !== undefined) {
         node[key] = revived
         continue
@@ -154,6 +160,14 @@ export function reviveSerializedErrorRefs<T>(root: T): T {
   return reviveSerializedRefs(root, errorTarget)
 }
 
+function errorResetTarget(node: Record<string, unknown>): (() => void) | undefined {
+  return node[ERROR_RESET_MARKER] === true ? reloadRoute : undefined
+}
+
+function reloadRoute(): void {
+  location.reload()
+}
+
 function errorTarget(node: Record<string, unknown>): Error | undefined {
   const marker = node[ERROR_MARKER]
   if (marker === null || typeof marker !== 'object') return undefined
@@ -217,28 +231,73 @@ export function hasPromiseProps(raw: string) {
  * Nested containers are rewritten in place (the client just parsed them; the server already
  * serialized the wire bytes before this runs), the root is not.
  */
-export function revivePromiseMarkers<T>(props: T): T {
-  return reviveMarkers(props, new Set()) as T
+export function revivePromiseMarkers<T>(props: T, sync?: SyncPropsRebuild): T {
+  return reviveMarkers(props, new Set(), sync) as T
 }
 
-function reviveMarkers(value: unknown, seen: Set<object>): unknown {
+/**
+ * Rebuild the legacy sync surface (`withSyncProps`) on a revived promise. The wire carries only the
+ * resolved value, so a marker revives into a bare promise and every unawaited `params.creator` read
+ * a Next-14-era component makes returns undefined - on the island SSR pass as well as on the client.
+ */
+export type SyncPropsRebuild = <T extends object>(
+  promise: Promise<T>,
+  kind: 'params' | 'searchParams',
+  value: T,
+) => Promise<T>
+
+/** Exactly the props Next gives the transitional sync surface - the same scope as the server's. */
+const SYNC_PROP_KEYS = new Set(['params', 'searchParams'])
+
+function reviveMarkers(
+  value: unknown,
+  seen: Set<object>,
+  sync?: SyncPropsRebuild,
+  key?: string,
+): unknown {
   if (value === null || typeof value !== 'object' || seen.has(value)) return value
   if (PROMISE_MARKER_KEY in value) {
-    return fulfilledPromise((value as Record<string, unknown>)[PROMISE_MARKER_KEY])
+    const resolved = (value as Record<string, unknown>)[PROMISE_MARKER_KEY]
+    const promise = fulfilledPromise(resolved)
+    if (!sync || !key || !SYNC_PROP_KEYS.has(key)) return promise
+    if (resolved === null || typeof resolved !== 'object') return promise
+    return sync(promise as Promise<object>, key as 'params' | 'searchParams', resolved)
   }
   seen.add(value)
   if (Array.isArray(value)) {
     for (let index = 0; index < value.length; index++) {
-      value[index] = reviveMarkers(value[index], seen)
+      value[index] = reviveMarkers(value[index], seen, sync)
     }
     return value
   }
   if (Object.getPrototypeOf(value) !== Object.prototype) return value
   const target = value as Record<string, unknown>
-  for (const key of Object.keys(target)) target[key] = reviveMarkers(target[key], seen)
+  for (const name of Object.keys(target)) {
+    target[name] = reviveMarkers(target[name], seen, sync, name)
+  }
   return value
 }
 
+/**
+ * Client half of `withSyncProps`: give the revived promise the resolved object's own keys, skipping
+ * the ones the promise already answers for (then/status/value/...), exactly as the server does.
+ */
+export function rebuildSyncProps<T extends object>(
+  promise: Promise<T>,
+  _kind: 'params' | 'searchParams',
+  value: T,
+): Promise<T> {
+  for (const key of Object.keys(value)) {
+    if (key in promise) continue
+    void Object.defineProperty(promise, key, {
+      get: () => (value as Record<string, unknown>)[key],
+      enumerable: true,
+      configurable: true,
+    })
+  }
+  return promise
+}
+
 function fulfilledPromise(value: unknown) {
   const promise = Promise.resolve(value) as Promise<unknown> & { status: string; value: unknown }
   promise.status = 'fulfilled'