@wular/pnext 0.0.21 → 0.0.22

package/package.json

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

package/src/cli/serve/entry.ts

@@ -7,6 +7,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { Plugin as EsbuildPlugin } from 'esbuild'
+import { frameworkFingerprint } from '../../runtime/fingerprint'
 
 const frameworkRoot = path.resolve(import.meta.dirname, '..', '..', '..')
 
@@ -20,8 +21,17 @@ function frameworkVersion(): string {
   }
 }
 
-function serverEntryDir(outPath: string): string {
-  return path.join(outPath, 'server', `bundle-${frameworkVersion()}`)
+/**
+ * Version AND framework fingerprint: the version alone let an edited `src` keep serving the bundle
+ * built from the previous source, so a fix appeared to have no effect until the app was rebuilt.
+ * The fingerprint is the same one every other compiled artifact is keyed on, taken through the
+ * cache-root record so a restart pays one stat per file rather than re-reading the tree.
+ */
+export function serverEntryDir(outPath: string): string {
+  // Cache root spelled inline, not imported: this module is parsed before anything else on the
+  // start path, and pulling in the module cache for one path.join would drag its whole graph along.
+  const generation = frameworkFingerprint(path.join(outPath, 'cache', 'server'))
+  return path.join(outPath, 'server', `bundle-${frameworkVersion()}-${generation}`)
 }
 
 function serverEntryFile(outPath: string): string {
@@ -30,7 +40,7 @@ function serverEntryFile(outPath: string): string {
 
 /**
  * The prebuilt entry for a project root, or undefined when there is none to
- * use (no build, a custom `outDir`, a version mismatch, or the opt-out). The
+ * use (no build, a custom `outDir`, a version or source-generation mismatch, or the opt-out). The
  * caller then falls back to importing src/cli/start.ts directly, so a miss only
  * costs speed. Deliberately cheap: one existsSync and one package.json read,
  * because it runs before anything else on the start path.
@@ -43,7 +53,7 @@ export function prebuiltServerEntry(root = process.cwd()): string | undefined {
 }
 
 /**
- * Bundle src/cli/start.ts under `<outPath>/server/bundle-<version>/`. Bare
+ * Bundle src/cli/start.ts under `<outPath>/server/bundle-<version>-<fingerprint>/`. Bare
  * specifiers stay external (the framework's deps are already plain JS), so only
  * the framework's own source is inlined. Splitting is on so the graph behind a
  * dynamic import (compat, dev, build) stays in its own chunk — folding it into

package/src/cli/serve/pipeline.ts

@@ -15,6 +15,7 @@ import type { ResolvedConfig } from '../../config'
 import { bootstrapCompat } from '../../compat-bootstrap'
 import { registerServerRuntime, serverBundleTargetForRuntime } from '../../runtime/loader'
 import { importModuleOnce } from '../../runtime/modules'
+import { abortUpstreamFetchOnDisconnect } from '../../runtime/fetch-host'
 import { applyProxyResponse, createProxyRunner } from '../../routing/proxy'
 import {
   isPprShellUpgradeEligible,
@@ -287,6 +288,9 @@ export async function createRequestHandler(
           },
         )
         const response = maybeCloseNodeFetchConnection(finalized, request)
+        // Wired before the close-observer wraps the body: the stream a handler
+        // passed through from fetch is still the one the abort map knows.
+        abortUpstreamFetchOnDisconnect(response.body, request.signal)
         return flushWorkUnitOnClose(response, unit, request.signal)
       } catch (error) {
         // A dropped promise here would close the socket without a response

package/src/cli/start.ts

@@ -130,6 +130,15 @@ async function guardUnservableOutputMode(root?: string): Promise<ResolvedConfig>
     )
     process.exit(1)
   }
+  // Next warns on `next start` with standalone output; its standalone launcher re-execs this path
+  // with __NEXT_PRIVATE_STANDALONE_CONFIG set to suppress the warning. Mirror both.
+  // 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/cli/typegen.ts

@@ -57,7 +57,10 @@ function routeEntry(route: RouteManifestEntry) {
 }
 
 async function writeChecks(config: ResolvedConfig, routes: RouteManifestEntry[]) {
-  const checksDir = path.join(config.typesPath, 'checks')
+  const checksDir = config.checksPath
+  // Checks used to live under typesPath, which the app's own tsconfig includes; a stale
+  // copy there fails the app's compiler on pnext internals, so heal that on every generate.
+  await rm(path.join(config.typesPath, 'checks'), { recursive: true, force: true })
   await rm(checksDir, { recursive: true, force: true })
   await ensureDir(checksDir)
 

package/src/client/router/runtime.ts

@@ -4810,9 +4810,11 @@ export async function softNavigate(href: string, options: SoftNavigateOptions =
   // Same-entry-identity navigation (a search-param nav on the same pathname, a refresh):
   // `key={bfcacheId}` subtrees do NOT remount, so typed values must survive. The commit can
   // still rebuild the page DOM under them (a PPR route streams its page slot in AFTER the
-  // swap), so re-apply the departure snapshot as the controls appear.
+  // swap), so re-apply the departure snapshot as the controls appear - but only to the DOM
+  // this swap replaced, never to a control a live island's own render owns (see
+  // islandOwnedControl).
   else if (departingBfcacheId && departingBfcacheId === historyBfcacheId()) {
-    restoreFormStateWhenMounted(departingBfcacheId, sequence)
+    restoreFormStateWhenMounted(departingBfcacheId, sequence, true)
   }
 
   // A navigation that only changed parallel slots (same children path AND unchanged search
@@ -4907,13 +4909,25 @@ function restoreControl(
   if (control.value !== saved.value) control.value = saved.value
 }
 
-function restoreFormState(bfcacheId: string | undefined, onlyEmpty = false) {
+/**
+ * A control inside a mounted island is owned by that island's preact diff, which reproduces
+ * React's reconciliation - including an app key (`key={searchParams.get('q')}`) that
+ * deliberately remounts the subtree with an EMPTY control. Re-applying the departure snapshot
+ * there fights the app; only DOM the raw swap replaced is pnext's own loss to compensate.
+ */
+function islandOwnedControl(control: Element): boolean {
+  const root: LiveIslandRoot | null = control.closest('pnext-client[data-pnext-client]')
+  return Boolean(root?.__pnextLive)
+}
+
+function restoreFormState(bfcacheId: string | undefined, onlyEmpty = false, skipIslands = false) {
   if (!bfcacheId) return
   const state = entryFormStateCache.get(bfcacheId)
   if (!state) return
   const controls = formControls()
   if (controls.length !== state.length) return
   for (const [index, control] of controls.entries()) {
+    if (skipIslands && islandOwnedControl(control)) continue
     // `onlyEmpty`: a freshly mounted control is empty, so filling it restores
     // what the remount lost — while anything already carrying a value (the app
     // set it, or the user typed after the commit) is left alone.
@@ -4951,10 +4965,10 @@ function restoreSharedLayoutFormState(
  * describes can appear after the swap. Keep trying while the DOM changes until the control
  * set matches the snapshot.
  */
-function restoreFormStateWhenMounted(bfcacheId: string, sequence: number): void {
+function restoreFormStateWhenMounted(bfcacheId: string, sequence: number, skipIslands = false) {
   const state = entryFormStateCache.get(bfcacheId)
   if (!state) return
-  restoreFormState(bfcacheId, true)
+  restoreFormState(bfcacheId, true, skipIslands)
   // The controls can be rebuilt more than once while the commit settles, so the restore stays
   // armed for a short window instead of firing once. It only ever fills EMPTY controls, so a
   // value the app or the user set after the commit is never clobbered.
@@ -4963,7 +4977,7 @@ function restoreFormStateWhenMounted(bfcacheId: string, sequence: number): void
       observer.disconnect()
       return
     }
-    restoreFormState(bfcacheId, true)
+    restoreFormState(bfcacheId, true, skipIslands)
   })
   observer.observe(document.body, { childList: true, subtree: true })
   window.setTimeout(() => observer.disconnect(), FORM_STATE_RESTORE_WINDOW_MS)

package/src/compat/metadata.ts

@@ -1,6 +1,7 @@
 import type { Metadata, MetadataOpenGraph, PageProps, RouteManifestEntry, Viewport } from '../types'
 import { staticMetadataForPathFromFiles, type StaticMetadataFile } from '../routing/metadata-files'
 import { coerceString } from '../render/metadata'
+import { legacyRequestAPIs } from '../request/context'
 import { readSourceText } from '../resolve/source-text'
 import { SPAN_TYPE, withChildSpan } from './otel/tracer'
 import { settledPromise } from '../render/renderer'
@@ -146,7 +147,9 @@ function resolvedParentMetadata(parent: Metadata): Metadata {
   }
 }
 
-function resolvedParentOpenGraph(openGraph: MetadataOpenGraph | undefined): MetadataOpenGraph {
+function resolvedParentOpenGraph(
+  openGraph: MetadataOpenGraph | null | undefined,
+): MetadataOpenGraph {
   if (!openGraph) return {}
   return {
     ...openGraph,
@@ -165,7 +168,7 @@ function resolvedParentOpenGraph(openGraph: MetadataOpenGraph | undefined): Meta
 }
 
 function normalizeKeywordList(value: Metadata['keywords']): (string | number)[] | undefined {
-  if (value === undefined) return undefined
+  if (value === undefined || value === null) return undefined
   return Array.isArray(value) ? value : [value]
 }
 
@@ -192,6 +195,14 @@ 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)
+    // themeColor-in-metadata deprecation is Next 15+; legacy (Next-14 era) apps never saw it.
+    if (!legacyRequestAPIs() && 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,
@@ -239,6 +250,7 @@ async function readSourceTextOrEmpty(file: string) {
  * nearly every file has none of these keys.
  */
 interface MetadataSourceFacts {
+  themeColor: boolean
   appleTouchFullscreen: boolean
   appleTouchIconPrecomposed: boolean
   metadataBase: boolean
@@ -247,6 +259,7 @@ interface MetadataSourceFacts {
 
 function metadataSourceFacts(source: string): MetadataSourceFacts {
   return {
+    themeColor: themeColorInMetadataExport(source),
     appleTouchFullscreen:
       source.includes('apple-touch-fullscreen') && /['"]apple-touch-fullscreen['"]/.test(source),
     appleTouchIconPrecomposed:
@@ -257,6 +270,35 @@ function metadataSourceFacts(source: string): MetadataSourceFacts {
   }
 }
 
+// A themeColor inside a viewport export is where the notice says to put it, so
+// only occurrences outside viewport/generateViewport blocks count.
+function themeColorInMetadataExport(source: string): boolean {
+  if (!source.includes('themeColor') || !/\bthemeColor\s*:/.test(source)) return false
+  return /\bthemeColor\s*:/.test(stripViewportExports(source))
+}
+
+function stripViewportExports(source: string): string {
+  const starts =
+    /export\s+(?:const|let|var)\s+viewport\b|export\s+(?:async\s+)?function\s+generateViewport\b/g
+  let out = ''
+  let last = 0
+  for (let match = starts.exec(source); match; match = starts.exec(source)) {
+    const open = source.indexOf('{', match.index)
+    if (open === -1) break
+    let depth = 0
+    let end = open
+    for (; end < source.length; end++) {
+      const char = source[end]
+      if (char === '{') depth++
+      else if (char === '}' && --depth === 0) break
+    }
+    out += source.slice(last, match.index)
+    last = end + 1
+    starts.lastIndex = last
+  }
+  return out + source.slice(last)
+}
+
 function routeUsesRelativeSocialImage(
   route: RouteManifestEntry,
   facts: MetadataSourceFacts[],

package/src/compat/next/config-loader.ts

@@ -112,10 +112,16 @@ function findConfigPath(root: string): string | undefined {
   return undefined
 }
 
+// `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 } }
+}
+
 /** Stable per config content, so the emitted bundle keeps one name per boot. */
 function configSourceKey(configPath: string): string {
   try {
-    return Bun.hash(readFileSync(configPath)).toString(36)
+    return bun.hash(readFileSync(configPath)).toString(36)
   } catch {
     return 'config'
   }

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

@@ -9,8 +9,10 @@ import {
   registerBuildSteps,
   type BuildStepContext,
 } from '../../extensions'
+import { legacyRequestAPIs } from '../../request/context'
 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'
 
@@ -20,6 +22,8 @@ export function registerTypedRoutesExtensions(_config: ResolvedConfig): void {
 
 async function runTypedRoutesBuildStep(ctx: BuildStepContext): Promise<void> {
   if (!nextCompatEnabled(ctx.config)) return
+  // Legacy (Next-14 era) apps keep their tsconfig untouched; current apps get Next's defaults.
+  if (!legacyRequestAPIs()) 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/typecheck/check.ts

@@ -372,6 +372,10 @@ async function writeTypecheckProject(
         },
         include: [
           path.join(dir, 'next-shims.d.ts'),
+          // Generated per-route assignability checks (typegen writes them next to this
+          // project, not under the app-included `types/` dir, so only pnext's own compiler
+          // reads them). Included by hand to keep that coverage.
+          path.join(dir, 'checks', '**/*.ts'),
           ...(nodeTypes ? [path.join(nodeTypes, 'index.d.ts')] : []),
           path.join(config.root, 'next-env.d.ts'),
           // The build emits `.next/types/validator.ts` (page/layout/route-handler export validation) just
@@ -661,7 +665,7 @@ declare module 'react/jsx-runtime' {
 `
   const requestType = (type: string) =>
     legacyRequestTypes ? `Promise<${type}> & ${type}` : `Promise<${type}>`
-  const requestShims = `declare module 'next/headers'{interface CookieSetOptions{name?:string;value?:string;path?:string;maxAge?:number;expires?:Date|number;httpOnly?:boolean;secure?:boolean;sameSite?:'strict'|'lax'|'none'|boolean;domain?:string}interface CookieStore{get(name:string):{name:string;value:string}|undefined;get(options:{name:string;value?:string}):{name:string;value:string}|undefined;getAll(name?:string):{name:string;value:string}[];getAll(options:{name:string;value?:string}):{name:string;value:string}[];has(name:string):boolean;readonly size:number;set(name:string,value:string,options?:CookieSetOptions):CookieStore;set(options:CookieSetOptions):CookieStore;delete(name:string):boolean;clear():CookieStore;[Symbol.iterator]():IterableIterator<readonly[string,{name?:string;value:string}]>}export function cookies():${requestType('CookieStore')};export function headers():${requestType('Headers')};export function draftMode():${requestType(`{isEnabled:boolean;enable():void;disable():void}`)}}
+  const requestShims = `declare module 'next/headers'{interface CookieSetOptions{name?:string;value?:string;path?:string;maxAge?:number;expires?:Date|number;httpOnly?:boolean;secure?:boolean;sameSite?:'strict'|'lax'|'none'|boolean;domain?:string}interface CookieStore{get(name:string):{name:string;value:string}|undefined;get(options:{name:string;value?:string}):{name:string;value:string}|undefined;getAll(name?:string):{name:string;value:string}[];getAll(options:{name:string;value?:string}):{name:string;value:string}[];has(name:string):boolean;readonly size:number;set(options:CookieSetOptions):CookieStore;set(name:string,value:string,options?:CookieSetOptions):CookieStore;delete(name:string):boolean;clear():CookieStore;[Symbol.iterator]():IterableIterator<readonly[string,{name?:string;value:string}]>}export function cookies():${requestType('CookieStore')};export function headers():${requestType('Headers')};export function draftMode():${requestType(`{isEnabled:boolean;enable():void;disable():void}`)}}
 `
   const fontShims = hasRealNext
     ? ''

package/src/config.ts

@@ -21,6 +21,12 @@ export type ResolvedConfig = Required<Pick<PNextConfig, 'outDir' | 'basePath'>>
     outRootPath: string
     /** Generated types — always under the out root, because tsconfig points at it. */
     typesPath: string
+    /**
+     * Generated per-route assignability checks. Deliberately OUTSIDE typesPath: an app's
+     * tsconfig includes `<outRoot>/types/**` and a foreign compiler must never see pnext's
+     * own internals. pnext's private typecheck project includes this directory instead.
+     */
+    checksPath: string
   }
 
 /**
@@ -146,6 +152,7 @@ export async function loadConfig(
     outPath: options.dev ? path.join(outRootPath, devOutSegment) : outRootPath,
     outRootPath,
     typesPath: path.join(outRootPath, 'types'),
+    checksPath: path.join(outRootPath, 'typecheck', 'checks'),
   }
 }
 

package/src/dev/server.ts

@@ -100,6 +100,7 @@ import {
 } from '../runtime/modules'
 import { ssrClientReference } from '../client/reference'
 import { cacheRoot, setDevWatcherFreshness } from '../runtime/module-cache'
+import { abortUpstreamFetchOnDisconnect } from '../runtime/fetch-host'
 import { markBoot } from '../cli/boot/trace'
 import { formatDuration } from '../utils/verbose'
 
@@ -454,6 +455,7 @@ export async function startDevServer(options: DevServerOptions) {
         syncWatchRoots()
       }, 0)
       if (profile) flushDevProfileLines()
+      abortUpstreamFetchOnDisconnect(logged.body, request.signal)
       return flushWorkUnitOnClose(logged, unit, request.signal)
     }
 

package/src/extensions.ts

@@ -15,6 +15,12 @@ import type { BuildManifest, ClientEntryReason, RouteManifestEntry, RouteParamVa
 import type { VerboseLogger } from './utils/verbose'
 import { escapeRegex } from './utils/code'
 
+// `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 } }
+}
+
 /** Per-build wiring for the server plugin chain. */
 export interface ServerEsbuildPluginOptions {
   /**
@@ -1416,7 +1422,7 @@ export function classifyRouteDependencies(
 
 /** Every reason a registered detector requires a client entry for this source. */
 export function sourceClientEntryReasons(source: string): ClientEntryReason[] {
-  const key = `${source.length}\0${Bun.hash(source).toString(36)}`
+  const key = `${source.length}\0${bun.hash(source).toString(36)}`
   const cached = clientEntryReasonCache.get(key)
   if (cached) return cached
   const reasons: ClientEntryReason[] = []

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/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 {