@wular/pnext 0.0.19 → 0.0.21

package/src/extensions.ts

@@ -376,6 +376,17 @@ export interface RenderExtensions {
     context: VaryParamsTrackingContext,
   ) => T
 
+  /**
+   * Give a `params`/`searchParams` promise Next 15's transitional SYNC surface (the resolved keys
+   * readable without `await`), behind compat.next.legacyRequestAPIs. The SAME promise comes back —
+   * callers hand a settled thenable to `use()`. Default: identity.
+   */
+  legacySyncProps: <T extends object>(
+    promise: Promise<T>,
+    kind: 'params' | 'searchParams',
+    value: T,
+  ) => Promise<T>
+
   /** Optional opaque state lifecycle around partial prerenders. */
   prerenderSidecar: PrerenderSidecarExtension
 }
@@ -476,6 +487,7 @@ function createRenderExtensions(): RenderExtensions {
     formatErrorLog: () => undefined,
     globalNotFoundEnabled: () => false,
     trackVaryParams: value => value,
+    legacySyncProps: promise => promise,
     prerenderSidecar: {
       begin: () => undefined,
       collect: () => Promise.resolve(undefined),
@@ -704,8 +716,11 @@ export function registerRevalidateBypassToken(token: () => string | undefined):
  * Run every registered response finalizer against `response` before it is
  * flushed, then return the response to send. Finalizers see request info + the
  * outgoing status/headers and mutate them in place; when a finalizer changes the
- * status (immutable on a Response) the body is re-wrapped with the new status. A
- * no-finalizer app (pure core) returns the response untouched.
+ * status (immutable on a Response) the body is re-wrapped with the new status.
+ *
+ * The document cache-control default is applied LAST, and only when nothing
+ * upstream claimed the header: an ISR/`use cache` route's SWR value, a route
+ * handler's own header and compat's RSC `private, no-store` all win over it.
  */
 export async function finalizeResponse(
   response: Response,
@@ -714,10 +729,10 @@ export async function finalizeResponse(
     routeKind: ResponseRouteKind
     routeMode?: ResponseRouteMode
     hints?: Record<string, unknown>
+    dev?: boolean
   },
 ): Promise<Response> {
   const finalizers = activeHost.request.responseFinalizers
-  if (finalizers.length === 0) return response
   const ctx: ResponseFinalizerContext = {
     request,
     routeKind: info.routeKind,
@@ -727,6 +742,7 @@ export async function finalizeResponse(
     headers: response.headers,
   }
   for (const finalizer of finalizers) await finalizer(ctx)
+  applyDocumentCacheControl(ctx, info.dev === true)
   if (ctx.status === response.status) return response
   return new Response(response.body, {
     status: ctx.status,
@@ -735,6 +751,56 @@ export async function finalizeResponse(
   })
 }
 
+/**
+ * What Next answers a DOCUMENT with, byte for byte (measured against stock
+ * next@16.2.12, `next start` and `next dev`; see tests/compat/conformance):
+ *
+ *   dev, every document          `no-cache, must-revalidate`
+ *   prod, per-request document   `private, no-cache, no-store, max-age=0, must-revalidate`
+ *   prod, pure prerender (200)   `s-maxage=31536000`
+ *   prod, ISR / `use cache`      `s-maxage=<revalidate>, stale-while-revalidate=<expire-revalidate>`
+ *   route handler                nothing, unless it sets `revalidate`
+ *
+ * Without one of these an intermediary is free to apply heuristic freshness to
+ * a personalised document. A non-200 is never a cacheable prerender in Next
+ * (its prerendered 404 still answers with the per-request value), so status
+ * gates the static case rather than the route's build-time disposition alone —
+ * which is also why no 404/500 render spells its own `no-store` any more: the
+ * prod value below already carries it, in Next's words.
+ */
+const DYNAMIC_DOCUMENT_CACHE_CONTROL = 'private, no-cache, no-store, max-age=0, must-revalidate'
+const DEV_DOCUMENT_CACHE_CONTROL = 'no-cache, must-revalidate'
+const DOCUMENT_EXPIRE_SECONDS = 31536000
+
+function applyDocumentCacheControl(ctx: ResponseFinalizerContext, dev: boolean): void {
+  if (ctx.routeKind !== 'html') return
+  if (ctx.headers.has('cache-control')) return
+  if (!(ctx.headers.get('content-type') ?? '').startsWith('text/html')) return
+  if (dev) {
+    ctx.headers.set('cache-control', DEV_DOCUMENT_CACHE_CONTROL)
+    return
+  }
+  if (ctx.status !== 200) {
+    ctx.headers.set('cache-control', DYNAMIC_DOCUMENT_CACHE_CONTROL)
+    return
+  }
+  // Compat sets the SWR value itself (its expireTime is configurable and it also
+  // covers pages-router getStaticProps); this only catches a core ISR document,
+  // which would otherwise be told never to cache a page that is cacheable for N.
+  const revalidate = ctx.routeMode === 'isr' ? ctx.hints?.revalidateSeconds : undefined
+  if (typeof revalidate === 'number' && revalidate > 0) {
+    const swr = Math.max(0, DOCUMENT_EXPIRE_SECONDS - revalidate)
+    ctx.headers.set('cache-control', `s-maxage=${revalidate}, stale-while-revalidate=${swr}`)
+    return
+  }
+  ctx.headers.set(
+    'cache-control',
+    ctx.routeMode === 'static'
+      ? `s-maxage=${DOCUMENT_EXPIRE_SECONDS}`
+      : DYNAMIC_DOCUMENT_CACHE_CONTROL,
+  )
+}
+
 export function setRequestExtensions(
   overrides: Partial<Omit<RequestExtensions, 'interceptors' | 'responseFinalizers'>>,
 ): void {

package/src/render/hooks.ts

@@ -22,7 +22,7 @@ import { restoreWithExtensionHost } from '../extensions'
 // ---------------------------------------------------------------------------
 
 /** Next compat is on (server actions, next/* modules, authInterrupts). */
-export function nextCompatEnabled(config: ResolvedConfig): boolean {
+export function nextCompatEnabled(config: Pick<ResolvedConfig, 'compat'>): boolean {
   return Boolean(config.compat?.next)
 }
 

package/src/render/metadata.ts

@@ -60,12 +60,23 @@ export function metadataContext(page: MetadataRenderPage): MetadataContext {
   }
 }
 
-export function headLinks(page: MetadataRenderPage, context: MetadataContext) {
-  const canonical = coerceCanonical(page.metadata.alternates, context)
-  const links: (MetadataLink | ResourceHint)[] = [
-    ...page.fontPreloads,
-    ...(page.resourceHints ?? []),
-    ...stylesheetLinks(page.stylesheets),
+// Links describing the render's own bytes, not metadata - so they stay in the
+// head even when metadata streams into the body.
+export function assetLinks(page: MetadataRenderPage) {
+  return assetLinkGroups(page).filter(Boolean).join('\n')
+}
+
+export function assetLinkGroups(page: MetadataRenderPage) {
+  const connects: ResourceHint[] = []
+  const preloads: ResourceHint[] = []
+  const lateHints: ResourceHint[] = []
+  for (const hint of page.resourceHints ?? []) {
+    if (hint.rel === 'preconnect' || hint.rel === 'dns-prefetch') connects.push(hint)
+    else if (hint.rel === 'preload' && (hint.as === 'font' || hint.as === 'image'))
+      preloads.push(hint)
+    else lateHints.push(hint)
+  }
+  const bulk: (MetadataLink | ResourceHint)[] = [
     ...(page.modulePreloads ?? []).map(url => ({ rel: 'modulepreload', url })),
     ...(page.dynamicScriptPreloads ?? []).map(url => ({
       rel: 'preload',
@@ -76,6 +87,20 @@ export function headLinks(page: MetadataRenderPage, context: MetadataContext) {
       crossOrigin: 'anonymous' as const,
       fetchPriority: 'low' as const,
     })),
+  ]
+  return [
+    renderLinks(connects),
+    renderLinks([...page.fontPreloads, ...preloads]),
+    renderLinks(stylesheetLinks(page.stylesheets)),
+    renderLinks(bulk),
+    renderLinks(lateHints),
+  ]
+}
+
+// Links derived from `metadata` - these travel with it into the body.
+export function metadataOnlyLinks(page: MetadataRenderPage, context: MetadataContext) {
+  const canonical = coerceCanonical(page.metadata.alternates, context)
+  const links: (MetadataLink | ResourceHint)[] = [
     ...(canonical ? [{ rel: 'canonical', url: canonical }] : []),
     ...staticMetadataLinks(page),
     ...authorLinks(page.metadata.authors, context),
@@ -86,6 +111,14 @@ export function headLinks(page: MetadataRenderPage, context: MetadataContext) {
     ...coerceIcons(page.metadata.icons, context),
     ...(page.metadata.links ?? []),
   ]
+  return renderLinks(links)
+}
+
+export function headLinks(page: MetadataRenderPage, context: MetadataContext) {
+  return [assetLinks(page), metadataOnlyLinks(page, context)].filter(Boolean).join('\n')
+}
+
+function renderLinks(links: (MetadataLink | ResourceHint)[]) {
   return links.map(link => `    <link ${linkAttrs(link)}/>`).join('\n')
 }
 
@@ -122,11 +155,13 @@ function staticMetadataLinks(page: MetadataRenderPage): MetadataLink[] {
     ...(!hasExplicitManifest && metadata.manifest ? [staticMetadataLink(metadata.manifest)] : []),
     ...metadata.icons.map(staticMetadataLink),
     ...(metadata.dynamicIcons ?? []),
-    ...metadata.appleIcons.map(staticMetadataLink),
-    ...(metadata.dynamicAppleIcons ?? []),
+    // Root icons share the icon bucket. Keeping them after apple icons made
+    // the link order differ from Next whenever both conventions were present.
     ...(!hasExplicitIcons && metadata.icons.length === 0
       ? metadata.rootIcons.map(staticMetadataLink)
       : []),
+    ...metadata.appleIcons.map(staticMetadataLink),
+    ...(metadata.dynamicAppleIcons ?? []),
   ])
 }
 
@@ -233,8 +268,9 @@ export function metadataTags(metadata: Metadata, context: MetadataContext): stri
   }
   for (const [property, value] of appLinkTags(meta.appLinks)) pushProperty(property, value)
 
-  tags.push(...openGraphTags(meta.openGraph, context))
-  tags.push(...twitterTags(meta.twitter ?? twitterFromOpenGraph(meta.openGraph), context))
+  const social = resolveSocialMetadata(meta)
+  tags.push(...openGraphTags(social.openGraph, context))
+  tags.push(...twitterTags(social.twitter, context))
 
   return tags.join('\n    ')
 }
@@ -831,17 +867,53 @@ function twitterCard(twitter: MetadataTwitter) {
   return twitter.images === undefined ? 'summary' : 'summary_large_image'
 }
 
-function twitterFromOpenGraph(
-  openGraph: MetadataOpenGraph | undefined,
-): MetadataTwitter | undefined {
-  if (!openGraph) return undefined
+// og/twitter resolve in one final pass over the merged chain: twitter auto-fills
+// from openGraph, then whichever of the two exists inherits the page
+// title/description it still lacks. Emission is that pass - nothing between the
+// merge and here reads these fields, and the parent handed to generateMetadata
+// is pre-merge by design.
+function resolveSocialMetadata(meta: Metadata): {
+  openGraph?: MetadataOpenGraph
+  twitter?: MetadataTwitter
+} {
+  const og = meta.openGraph
+  let twitter = meta.twitter
+  if (og) {
+    const ownImages = twitter && 'images' in twitter && twitter.images
+    twitter = {
+      ...twitter,
+      // card follows twitter's OWN images: an og image inherited below never
+      // upgrades a declared twitter block to summary_large_image.
+      card: twitterCard(twitter ?? { images: og.images }),
+      title: titleText(twitter?.title) === undefined ? og.title : twitter?.title,
+      description: twitter?.description || og.description,
+      images: ownImages ? twitter?.images : og.images,
+    }
+  }
+  return { openGraph: og && inherited(og, meta), twitter: twitter && inherited(twitter, meta) }
+}
+
+// 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 }>(
+  block: T,
+  meta: Metadata,
+): T {
+  const own = titleText(block.title)
+  if (own !== undefined && block.description) return block
   return {
-    title: openGraph.title,
-    description: openGraph.description,
-    images: openGraph.images,
+    ...block,
+    title: own === undefined ? titleText(meta.title) : block.title,
+    description: block.description || meta.description,
   }
 }
 
+// The title a chain entry actually renders, or undefined when it renders none
+// (a bare `template`, an empty string) and so counts as missing for inheritance.
+function titleText(title: Metadata['title']): string | undefined {
+  if (title === undefined) return undefined
+  return resolveTitleChain([{ title }]) || undefined
+}
+
 export function mergeViewport(...items: Viewport[]) {
   return items.reduce<Viewport>(
     (viewport, item) => ({