@wular/pnext 0.0.20 → 0.0.22

package/src/render/metadata.ts

@@ -7,6 +7,7 @@ import type {
   MetadataLink,
   MetadataOpenGraph,
   MetadataRobots,
+  MetadataValue,
   ResourceHint,
   MetadataTwitter,
   Viewport,
@@ -19,6 +20,13 @@ import {
 import { escapeHtml, stringifyHtmlValue } from '../utils/html'
 import { getTrailingSlashUrls, withBasePath } from '../routing/href'
 
+/** Every metadata field is nullable: null means "not set", exactly like undefined. */
+type MetaContent = MetadataValue | null | undefined
+
+function absent(value: unknown): value is null | undefined {
+  return value === undefined || value === null
+}
+
 export type MetadataExport = Metadata | (() => Metadata | Promise<Metadata>)
 
 export type ViewportExport = Viewport | (() => Viewport | Promise<Viewport>)
@@ -224,12 +232,15 @@ function prefixImageBasePath(image: MetadataImage): MetadataImage {
 export function metadataTags(metadata: Metadata, context: MetadataContext): string {
   const meta = metadata
   const tags: string[] = []
-  const push = (name: string, content: string | undefined) => {
-    if (content) tags.push(`<meta name="${escapeHtml(name)}" content="${escapeHtml(content)}"/>`)
+  const push = (name: string, content: MetaContent) => {
+    if (content)
+      tags.push(`<meta name="${escapeHtml(name)}" content="${escapeHtml(coerceString(content))}"/>`)
   }
-  const pushProperty = (property: string, content: string | undefined) => {
+  const pushProperty = (property: string, content: MetaContent) => {
     if (content)
-      tags.push(`<meta property="${escapeHtml(property)}" content="${escapeHtml(content)}"/>`)
+      tags.push(
+        `<meta property="${escapeHtml(property)}" content="${escapeHtml(coerceString(content))}"/>`,
+      )
   }
 
   push('description', meta.description)
@@ -263,8 +274,8 @@ export function metadataTags(metadata: Metadata, context: MetadataContext): stri
   }
   if (meta.facebook?.appId) pushProperty('fb:app_id', meta.facebook.appId)
   for (const admin of list(meta.facebook?.admins)) pushProperty('fb:admins', admin)
-  if (meta.pinterest?.richPin !== undefined) {
-    pushProperty('pinterest-rich-pin', meta.pinterest.richPin ? 'true' : 'false')
+  if (!absent(meta.pinterest?.richPin)) {
+    pushProperty('pinterest-rich-pin', String(meta.pinterest.richPin))
   }
   for (const [property, value] of appLinkTags(meta.appLinks)) pushProperty(property, value)
 
@@ -278,13 +289,15 @@ export function metadataTags(metadata: Metadata, context: MetadataContext): stri
 function openGraphTags(og: MetadataOpenGraph | undefined, context: MetadataContext): string[] {
   if (!og) return []
   const tags: string[] = []
-  const push = (property: string, content: string | undefined) => {
+  const push = (property: string, content: MetaContent) => {
     if (content)
-      tags.push(`<meta property="${escapeHtml(property)}" content="${escapeHtml(content)}"/>`)
+      tags.push(
+        `<meta property="${escapeHtml(property)}" content="${escapeHtml(coerceString(content))}"/>`,
+      )
   }
   push('og:title', og.title === undefined ? undefined : resolveTitleChain([{ title: og.title }]))
   push('og:description', og.description)
-  push('og:url', og.url === undefined ? undefined : resolveMetadataUrl(og.url, context))
+  push('og:url', resolveMetadataUrl(og.url, context))
   push('og:site_name', og.siteName)
   push('og:locale', og.locale)
   push('og:type', og.type)
@@ -313,8 +326,9 @@ function openGraphTags(og: MetadataOpenGraph | undefined, context: MetadataConte
 function twitterTags(twitter: MetadataTwitter | undefined, context: MetadataContext): string[] {
   if (!twitter) return []
   const tags: string[] = []
-  const push = (name: string, content: string | undefined) => {
-    if (content) tags.push(`<meta name="${escapeHtml(name)}" content="${escapeHtml(content)}"/>`)
+  const push = (name: string, content: MetaContent) => {
+    if (content)
+      tags.push(`<meta name="${escapeHtml(name)}" content="${escapeHtml(coerceString(content))}"/>`)
   }
   push('twitter:card', twitterCard(twitter))
   push('twitter:site', twitter.site)
@@ -334,10 +348,13 @@ function twitterTags(twitter: MetadataTwitter | undefined, context: MetadataCont
     push('twitter:image:alt', image.alt)
     push('twitter:image:type', image.type)
   }
-  push('twitter:player', resolveMetadataUrl(twitter.players?.playerUrl, context))
-  push('twitter:player:stream', resolveMetadataUrl(twitter.players?.streamUrl, context))
-  push('twitter:player:width', coerceString(twitter.players?.width) || undefined)
-  push('twitter:player:height', coerceString(twitter.players?.height) || undefined)
+  const players = twitter.players === undefined ? [] : [twitter.players].flat()
+  for (const player of players) {
+    push('twitter:player', resolveMetadataUrl(player.playerUrl, context))
+    push('twitter:player:stream', resolveMetadataUrl(player.streamUrl, context))
+    push('twitter:player:width', coerceString(player.width) || undefined)
+    push('twitter:player:height', coerceString(player.height) || undefined)
+  }
   for (const [device, id] of Object.entries(twitter.app?.id ?? {})) {
     push(`twitter:app:id:${device}`, id)
   }
@@ -349,7 +366,7 @@ function twitterTags(twitter: MetadataTwitter | undefined, context: MetadataCont
 
 // theme-color: string | { color, media } | array of those.
 export function themeColorTags(value: Viewport['themeColor']): string {
-  if (value === undefined) return ''
+  if (absent(value)) return ''
   const list = Array.isArray(value) ? value : [value]
   return list
     .map(entry => {
@@ -514,13 +531,13 @@ function coerceKeywords(value: Metadata['keywords']): string | undefined {
 }
 
 function normalizeKeywordList(value: Metadata['keywords']): (string | number)[] | undefined {
-  if (value === undefined) return undefined
+  if (absent(value)) return undefined
   return Array.isArray(value) ? value : [value]
 }
 
 // authors -> list of display names for meta[name=author].
 function coerceAuthors(value: Metadata['authors']): string[] {
-  if (value === undefined) return []
+  if (absent(value)) return []
   const list = Array.isArray(value) ? value : [value]
   return list
     .map(author => (typeof author === 'string' ? author : author.name))
@@ -530,7 +547,7 @@ function coerceAuthors(value: Metadata['authors']): string[] {
 
 // robots: string passthrough, or object -> "index, follow, noarchive" style.
 function coerceRobots(value: Metadata['robots']): string | undefined {
-  if (value === undefined) return undefined
+  if (absent(value)) return undefined
   if (typeof value === 'string') return value
   const flags: string[] = []
   const r = value
@@ -601,7 +618,7 @@ function coerceCanonical(
   context: MetadataContext,
 ): string | undefined {
   const canonical = value?.canonical
-  if (canonical === undefined) return undefined
+  if (absent(canonical)) return undefined
   if (typeof canonical === 'string') return resolveMetadataUrl(canonical, context)
   if (canonical instanceof URL) return canonical.href
   if (typeof canonical === 'object' && 'url' in canonical)
@@ -687,7 +704,7 @@ function joinUrlPath(...parts: string[]) {
 
 // Normalizes every icon form (string | URL | object | group) into <link> descriptors.
 function coerceIcons(value: Metadata['icons'], context: MetadataContext): MetadataLink[] {
-  if (value === undefined) return []
+  if (absent(value)) return []
   if (isIconGroups(value)) {
     return [
       ...iconList(value.icon, 'icon', context),
@@ -706,11 +723,11 @@ function isIconGroups(value: NonNullable<Metadata['icons']>): value is MetadataI
 }
 
 function iconList(
-  value: MetadataIcon | MetadataIcon[] | undefined,
+  value: MetadataIcon | MetadataIcon[] | null | undefined,
   rel: string,
   context: MetadataContext,
 ): MetadataLink[] {
-  if (value === undefined) return []
+  if (absent(value)) return []
   const list = Array.isArray(value) ? value : [value]
   return list.map((icon): MetadataLink => {
     if (typeof icon === 'string') return { rel, url: resolveMetadataUrl(icon, context) ?? icon }
@@ -725,7 +742,7 @@ function iconList(
 }
 
 function authorLinks(value: Metadata['authors'], context: MetadataContext): MetadataLink[] {
-  if (value === undefined) return []
+  if (absent(value)) return []
   return (Array.isArray(value) ? value : [value])
     .filter((author): author is MetadataAuthor => typeof author === 'object' && author !== null)
     .flatMap(author => {
@@ -775,7 +792,7 @@ function alternateLinks(value: Metadata['alternates'], context: MetadataContext)
   for (const [type, entries] of Object.entries(value.types ?? {})) {
     const listEntries = Array.isArray(entries) ? entries : [entries]
     for (const entry of listEntries) {
-      const record =
+      const record: { url: unknown; title?: string } =
         typeof entry === 'object' && !(entry instanceof URL) && entry !== null && 'url' in entry
           ? entry
           : { url: entry }
@@ -794,8 +811,8 @@ function appleStartupLinks(
   value: Metadata['appleWebApp'],
   context: MetadataContext,
 ): MetadataLink[] {
-  if (!value || typeof value !== 'object' || value.startupImage === undefined) return []
-  const images = Array.isArray(value.startupImage) ? value.startupImage : [value.startupImage]
+  if (!value || typeof value !== 'object' || absent(value.startupImage)) return []
+  const images = [value.startupImage].flat()
   return images.map(image => {
     if (typeof image === 'string' || image instanceof URL) {
       return {
@@ -853,8 +870,10 @@ function appLinkTags(value: Metadata['appLinks']): [string, string][] {
   if (!value) return []
   const tags: [string, string][] = []
   for (const [platform, entries] of Object.entries(value)) {
-    for (const [name, item] of Object.entries(entries)) {
-      if (item !== undefined) tags.push([`al:${platform}:${name}`, String(item)])
+    for (const target of entries === undefined ? [] : [entries].flat()) {
+      for (const [name, item] of Object.entries(target)) {
+        if (item !== undefined) tags.push([`al:${platform}:${name}`, coerceString(item)])
+      }
     }
   }
   return tags
@@ -890,11 +909,14 @@ function resolveSocialMetadata(meta: Metadata): {
       images: ownImages ? twitter?.images : og.images,
     }
   }
-  return { openGraph: og && inherited(og, meta), twitter: twitter && inherited(twitter, meta) }
+  return {
+    openGraph: og ? inherited(og, meta) : undefined,
+    twitter: twitter ? inherited(twitter, meta) : undefined,
+  }
 }
 
 // A block that renders no title/description of its own falls back to the page's.
-function inherited<T extends { title?: Metadata['title']; description?: string }>(
+function inherited<T extends { title?: Metadata['title']; description?: string | null }>(
   block: T,
   meta: Metadata,
 ): T {

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/resolve/imports.ts

@@ -11,6 +11,12 @@ import {
 } from './engine'
 import { onExtensionHostReset } from '../extensions'
 
+// `Bun` through globalThis: pnext ships TypeScript source, so app compilers without
+// bun-types typecheck this file and a bare `Bun` identifier would fail them.
+const { Bun: bun } = globalThis as unknown as {
+  Bun: { resolveSync(specifier: string, parent: string): string }
+}
+
 // Conditions for "is this a local source file" lookups. Ordered to mirror the
 // preference a bundler applies, though `exports` key order ultimately decides.
 const localConditions = ['source', 'import', 'browser', 'node', 'default', 'require']
@@ -668,7 +674,7 @@ export function resolveRuntimeSpecifier(dir: string, specifier: string): string
   const cached = runtimeResolveCache.get(key)
   if (cached !== undefined) return cached
   try {
-    const resolved = Bun.resolveSync(specifier, dir)
+    const resolved = bun.resolveSync(specifier, dir)
     runtimeResolveCache.set(key, resolved)
     return resolved
   } catch {

package/src/resolve/scan-facts.ts

@@ -17,6 +17,12 @@ const parseSync: typeof import('oxc-parser').parseSync = (...args) =>
 import { loadNative } from '../utils/native-require'
 import { spliceSource } from '../runtime/module-transform'
 
+// `Bun` through globalThis: pnext ships TypeScript source, so app compilers without
+// bun-types typecheck this file and a bare `Bun` identifier would fail them.
+const { Bun: bun } = globalThis as unknown as {
+  Bun: { hash(input: string | ArrayBufferView): { toString(radix?: number): string } }
+}
+
 export interface ScanEdge {
   specifier: string
   /** Bound names: `default`, `*` (namespace object), or the imported names. */
@@ -187,7 +193,7 @@ export function rewriteFacts(file: string, source: string): RewriteFacts {
 }
 
 function parsed(file: string, source: string, lang = langForFile(file)) {
-  const key = `${lang}\0${source.length}\0${Bun.hash(source).toString()}`
+  const key = `${lang}\0${source.length}\0${bun.hash(source).toString()}`
   const cached = memo.get(key)
   if (cached) {
     hits += 1

package/src/runtime/fetch-host.ts

@@ -3,10 +3,18 @@
  * always derives Host from the request URL and drops any supplied one. An app that forwards its
  * inbound request headers to an upstream - every proxy/BFF route handler - would otherwise send
  * the local Host upstream, an RFC 9110 7.2 violation that real upstreams reject. Match undici.
+ *
+ * Bun also ignores response-body cancellation: cancelling a fetch Response's stream leaves the
+ * upstream request in flight and its keep-alive socket checked out for good, so a passthrough proxy
+ * route whose client disconnects mid-stream leaks a connection per abort until later fetches to that
+ * host queue behind them forever. Only the fetch's own AbortSignal tears the request down, so each
+ * response body is tracked against its controller here and the serving layer fires it on disconnect.
  */
 
 let installed = false
 
+const upstreamAborts = new WeakMap<ReadableStream<Uint8Array>, AbortController>()
+
 function isHostKey(key: unknown): boolean {
   return typeof key === 'string' && key.length === 4 && key.toLowerCase() === 'host'
 }
@@ -36,7 +44,43 @@ export function installFetchHostNormalization(): void {
   const original = globalThis.fetch.bind(globalThis)
   globalThis.fetch = function fetch(input: RequestInfo | URL, init?: RequestInit) {
     const source = init?.headers ?? (input instanceof Request ? input.headers : undefined)
-    if (source === undefined || !hasHost(source)) return original(input, init)
-    return original(input, { ...init, headers: withoutHost(source) })
+    const normalized =
+      source !== undefined && hasHost(source) ? { ...init, headers: withoutHost(source) } : init
+    return trackUpstream(original, input, normalized)
   } as typeof globalThis.fetch
 }
+
+/** Give every fetch an abort handle of its own, keyed on the body it streams back. */
+function trackUpstream(
+  original: typeof globalThis.fetch,
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+): Promise<Response> {
+  const controller = new AbortController()
+  const caller = init?.signal ?? (input instanceof Request ? input.signal : undefined)
+  const signal = caller ? AbortSignal.any([caller, controller.signal]) : controller.signal
+  return original(input, { ...init, signal }).then(response => {
+    if (response.body) upstreamAborts.set(response.body, controller)
+    return response
+  })
+}
+
+/**
+ * Tear down the upstream fetch `body` is streaming from once the client goes away. Bun.serve never
+ * cancels the body it is writing, so this disconnect is the only chance to release that socket.
+ * Zero-cost for any response that is not a fetch passthrough.
+ */
+export function abortUpstreamFetchOnDisconnect(
+  body: ReadableStream<Uint8Array> | null,
+  signal: AbortSignal | undefined,
+): void {
+  if (!body || !signal || !upstreamAborts.has(body)) return
+  const abort = () => {
+    const controller = upstreamAborts.get(body)
+    if (!controller) return
+    upstreamAborts.delete(body)
+    controller.abort()
+  }
+  if (signal.aborted) abort()
+  else signal.addEventListener('abort', abort, { once: true })
+}

package/src/types.ts

@@ -95,7 +95,8 @@ export interface ResourceHint extends Omit<MetadataLink, 'url'> {
 export type MetadataTitle =
   string | number | { absolute?: string; default?: string; template?: string | null }
 
-export type MetadataIcon = string | URL | (Partial<MetadataLink> & { url: string | URL })
+export type MetadataIcon =
+  string | URL | (Omit<Partial<MetadataLink>, 'url'> & { url: string | URL })
 
 export interface MetadataIconGroups {
   icon?: MetadataIcon | MetadataIcon[]
@@ -116,7 +117,7 @@ export interface MetadataRobots {
   nosnippet?: boolean
   noimageindex?: boolean
   nocache?: boolean
-  googleBot?: MetadataRobots & Record<string, string | number | boolean | undefined>
+  googleBot?: string | (MetadataRobots & Record<string, string | number | boolean | undefined>)
 }
 
 export type MetadataImage =
@@ -134,7 +135,7 @@ export type MetadataImage =
 export interface MetadataOpenGraph {
   title?: MetadataTitle
   description?: string
-  url?: string | URL
+  url?: string | URL | null
   siteName?: string
   locale?: string
   type?: string
@@ -142,109 +143,125 @@ export interface MetadataOpenGraph {
   videos?: MetadataImage | MetadataImage[]
   audio?: MetadataImage | MetadataImage[]
   publishedTime?: string
-  authors?: string | string[]
+  authors?: string | URL | (string | URL)[] | null
   emails?: string | string[]
   phoneNumbers?: string | string[]
   faxNumbers?: string | string[]
 }
 
+export interface MetadataTwitterPlayer {
+  playerUrl?: string | URL
+  streamUrl?: string | URL
+  width?: string | number
+  height?: string | number
+}
+
 export interface MetadataTwitter {
   card?: string
-  site?: string
-  siteId?: string
-  creator?: string
-  creatorId?: string
+  site?: string | null
+  siteId?: string | null
+  creator?: string | null
+  creatorId?: string | null
   title?: MetadataTitle
-  description?: string
+  description?: string | null
   images?: MetadataImage | MetadataImage[]
-  players?: {
-    playerUrl?: string | URL
-    streamUrl?: string | URL
-    width?: string | number
-    height?: string | number
-  }
+  players?: MetadataTwitterPlayer | MetadataTwitterPlayer[]
   app?: {
     name?: string
-    id?: Record<string, string | undefined>
+    id?: Record<string, MetadataValue | undefined>
     url?: Record<string, string | URL | undefined>
   }
 }
 
+export type MetadataAlternate =
+  | string
+  | URL
+  | { url: string | URL; title?: string }
+  | (string | URL | { url: string | URL; title?: string })[]
+
 export interface MetadataAlternates {
-  canonical?: string | URL | { url: string | URL }
-  languages?: Record<string, string | URL>
-  media?: Record<string, string | URL>
-  types?: Record<
-    string,
-    | string
-    | URL
-    | { url: string | URL; title?: string }
-    | (string | URL | { url: string | URL; title?: string })[]
-  >
+  canonical?: string | URL | { url: string | URL; title?: string } | null
+  languages?: Record<string, MetadataAlternate | null | undefined>
+  media?: Record<string, MetadataAlternate | null | undefined>
+  types?: Record<string, MetadataAlternate | null | undefined>
 }
 
+// Every field is nullable: a metadata object may explicitly null a field out to
+// suppress an inherited value, and null reads the same as absent here.
 export interface Metadata {
-  metadataBase?: string | URL
-  title?: MetadataTitle
-  description?: string
-  lang?: string
-  keywords?: string | number | (string | number)[]
-  authors?: string | MetadataAuthor | (string | MetadataAuthor)[]
-  generator?: string
-  applicationName?: string
-  referrer?: string
-  robots?: string | MetadataRobots
-  openGraph?: MetadataOpenGraph
-  twitter?: MetadataTwitter
-  alternates?: MetadataAlternates
+  metadataBase?: string | URL | null
+  title?: MetadataTitle | null
+  description?: string | null
+  lang?: string | null
+  keywords?: string | number | (string | number)[] | null
+  authors?: string | MetadataAuthor | (string | MetadataAuthor)[] | null
+  generator?: string | null
+  applicationName?: string | null
+  referrer?: string | null
+  robots?: string | MetadataRobots | null
+  openGraph?: MetadataOpenGraph | null
+  twitter?: MetadataTwitter | null
+  alternates?: MetadataAlternates | null
   pagination?: {
-    previous?: string | URL
-    next?: string | URL
-  }
-  icons?: MetadataIcon | MetadataIcon[] | MetadataIconGroups
-  manifest?: string | URL
-  creator?: string
-  publisher?: string
+    previous?: string | URL | null
+    next?: string | URL | null
+  } | null
+  icons?: MetadataIcon | MetadataIcon[] | MetadataIconGroups | null
+  manifest?: string | URL | null
+  creator?: string | null
+  publisher?: string | null
   formatDetection?: {
-    email?: boolean
-    address?: boolean
-    telephone?: boolean
-    url?: boolean
-  }
+    email?: boolean | null
+    address?: boolean | null
+    telephone?: boolean | null
+    url?: boolean | null
+  } | null
   verification?: {
-    google?: string | string[]
-    yahoo?: string | string[]
-    yandex?: string | string[]
-    other?: Record<string, string | string[]>
-  }
+    google?: MetadataValue | MetadataValue[] | null
+    yahoo?: MetadataValue | MetadataValue[] | null
+    yandex?: MetadataValue | MetadataValue[] | null
+    other?: Record<string, MetadataValue | MetadataValue[]>
+  } | null
   itunes?: {
     appId?: string
-    appArgument?: string
-  }
+    appArgument?: string | null
+  } | null
   appleWebApp?:
     | boolean
     | {
         capable?: boolean
-        title?: string
+        title?: string | null
         statusBarStyle?: string
         startupImage?:
           | string
           | URL
           | { url: string | URL; media?: string }
           | (string | URL | { url: string | URL; media?: string })[]
+          | null
       }
+    | null
   facebook?: {
     appId?: string
-    admins?: string | string[]
-  }
+    admins?: MetadataValue | MetadataValue[]
+  } | null
   pinterest?: {
-    richPin?: boolean
-  }
-  appLinks?: Record<string, Record<string, string | boolean | undefined>>
-  other?: Record<string, string | string[]>
+    richPin?: boolean | string | null
+  } | null
+  appLinks?: MetadataAppLinks | null
+  other?: Record<string, MetadataValue | MetadataValue[] | null>
   links?: MetadataLink[]
 }
 
+/** A metadata value that renders to text; numbers are stringified. */
+export type MetadataValue = string | number
+
+export type MetadataAppLinkTarget = Record<string, MetadataValue | boolean | URL | undefined>
+
+export type MetadataAppLinks = Record<
+  string,
+  MetadataAppLinkTarget | MetadataAppLinkTarget[] | undefined
+>
+
 export type ThemeColor = string | { color: string; media?: string }
 
 export interface Viewport {
@@ -255,8 +272,8 @@ export interface Viewport {
   userScalable?: boolean
   viewportFit?: 'auto' | 'contain' | 'cover'
   interactiveWidget?: 'resizes-visual' | 'resizes-content' | 'overlays-content'
-  themeColor?: ThemeColor | ThemeColor[]
-  colorScheme?: string
+  themeColor?: ThemeColor | ThemeColor[] | null
+  colorScheme?: string | null
 }
 
 export interface NextRequestCookie {

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