@thomas.f/prnext 0.1.0-alpha.1

package/compat/app-error-boundary.cjs

@@ -0,0 +1,53 @@
+'use client';
+'use strict';
+
+const React = require('react');
+const { AppRouterContext } = require('./app-context.cjs');
+
+function initialError(value) {
+  if (!value) return null;
+  if (value instanceof Error) return value;
+  const error = new Error(value.message || 'An error occurred while rendering this page.');
+  if (value.digest !== undefined) error.digest = value.digest;
+  return error;
+}
+
+function ThrowInitialError({ error }) { throw initialError(error); }
+
+class AppErrorBoundary extends React.Component {
+  static contextType = AppRouterContext;
+  state = { children: this.props.children, resetKey: this.props.resetKey, error: initialError(this.props.initialError), hasError: !!this.props.initialError };
+
+  static getDerivedStateFromError(error) {
+    if (error?.digest === 'NEXT_HTTP_ERROR_FALLBACK;404' || String(error?.digest || '').startsWith('NEXT_REDIRECT;')) throw error;
+    return { error, hasError: true };
+  }
+
+  static getDerivedStateFromProps(props, state) {
+    if ((props.resetOnChildrenChange !== false && props.children !== state.children) || props.resetKey !== state.resetKey) {
+      return { children: props.children, resetKey: props.resetKey, error: initialError(props.initialError), hasError: !!props.initialError };
+    }
+    return null;
+  }
+
+  reset = () => { this.setState({ error: null, hasError: false }); };
+
+  retry = () => {
+    React.startTransition(() => {
+      (this.props.refresh || this.context?.router.refresh)?.();
+      this.reset();
+    });
+  };
+
+  render() {
+    if (this.state.hasError) return React.createElement(React.Fragment, null, this.props.errorStyles,
+      React.createElement(this.props.errorComponent, { error: this.state.error, reset: this.reset, retry: this.retry }));
+    // A server fallback contains no successful subtree to reveal. Reset retries
+    // that same encoded failure; only retry/refresh obtains new server work.
+    if (this.props.initialError) return React.createElement(ThrowInitialError, { error: this.props.initialError });
+    return this.props.children;
+  }
+}
+
+module.exports = AppErrorBoundary;
+module.exports.default = AppErrorBoundary;

package/compat/app-global-error-boundary.cjs

@@ -0,0 +1,34 @@
+'use client';
+'use strict';
+
+const React = require('react');
+const AppErrorBoundary = require('./app-error-boundary.cjs');
+
+function DefaultGlobalError({ error }) {
+  const digest = typeof error?.digest === 'string' ? error.digest : undefined;
+  return React.createElement('html', { id: '__prnext_error__' },
+    React.createElement('head'),
+    React.createElement('body', { style: { margin: 0, fontFamily: 'system-ui, sans-serif' } },
+      React.createElement('main', { style: { minHeight: '100vh', display: 'grid', placeContent: 'center', padding: 24 } },
+        React.createElement('h1', null, 'This page couldn’t load'),
+        React.createElement('p', null, digest ? 'A server error occurred. Reload to try again.' : 'Reload to try again, or go back.'),
+        React.createElement('form', null, React.createElement('button', { type: 'submit' }, 'Reload')),
+        digest ? React.createElement('p', null, 'ERROR ', digest) : null)));
+}
+
+function GlobalErrorTrigger({ error }) {
+  if (error instanceof Error) throw error;
+  const failure = new Error(error.message || 'An error occurred while rendering this page.');
+  if (typeof error.digest === 'string') failure.digest = error.digest;
+  throw failure;
+}
+
+function GlobalErrorBoundary({ component = DefaultGlobalError, css = [], children, ...props }) {
+  const styles = css.map(href => React.createElement('link', { key: href, rel: 'stylesheet', href, precedence: 'prnext-global-error' }));
+  return React.createElement(AppErrorBoundary, { ...props, resetOnChildrenChange: false, errorComponent: component, errorStyles: styles }, children);
+}
+
+module.exports = GlobalErrorBoundary;
+module.exports.default = GlobalErrorBoundary;
+module.exports.DefaultGlobalError = DefaultGlobalError;
+module.exports.GlobalErrorTrigger = GlobalErrorTrigger;

package/compat/app-layout-context.cjs

@@ -0,0 +1,27 @@
+'use client';
+'use strict';
+const React = require('react');
+const LayoutContext = React.createContext({ children: [] });
+const LayoutCacheContext = React.createContext(null);
+
+function LayoutProvider({ id, segments, children }) {
+  const cache = React.useContext(LayoutCacheContext);
+  const previous = React.useRef({});
+  const current = {};
+  for (const [slot, value] of Object.entries(segments || {})) current[slot] = value === null ? cache?.segments[id]?.[slot] || previous.current[slot] || [] : value;
+  React.useLayoutEffect(() => { previous.current = current; if (cache && id) cache.segments[id] = current; });
+  return React.createElement(LayoutContext.Provider, { value: current }, children);
+}
+
+function LayoutSlot({ id, preserve, children }) {
+  const cache = React.useContext(LayoutCacheContext);
+  const previous = React.useRef(children);
+  const current = preserve && cache && Object.hasOwn(cache.slots, id) ? cache.slots[id] : preserve ? previous.current : children;
+  React.useLayoutEffect(() => { previous.current = current; if (cache && id) cache.slots[id] = current; }, [cache, id, current]);
+  return current ?? null;
+}
+
+module.exports.LayoutContext = LayoutContext;
+module.exports.LayoutCacheContext = LayoutCacheContext;
+module.exports.LayoutProvider = LayoutProvider;
+module.exports.LayoutSlot = LayoutSlot;

package/compat/app-navigation-boundary.cjs

@@ -0,0 +1,47 @@
+'use client';
+'use strict';
+
+const React = require('react');
+const { AppRouterContext } = require('./app-context.cjs');
+
+function navigation(error) {
+  const digest = error?.digest;
+  if (digest === 'NEXT_HTTP_ERROR_FALLBACK;404') return { notFound: true };
+  if (typeof digest !== 'string' || !digest.startsWith('NEXT_REDIRECT;')) return null;
+  const parts = digest.split(';');
+  if (parts.at(-1) === '') parts.pop();
+  const status = Number(parts.pop());
+  const href = parts.slice(2).join(';');
+  if (![307, 308].includes(status) || !href || /[\r\n]/.test(href)) return null;
+  let url;
+  try { url = new URL(href, 'http://prnext.invalid'); } catch { return null; }
+  if (!['http:', 'https:'].includes(url.protocol)) return null;
+  return { href, replace: parts[1] === 'replace' };
+}
+
+class AppNavigationBoundary extends React.Component {
+  static contextType = AppRouterContext;
+  state = { control: null, resetKey: this.props.resetKey };
+  static getDerivedStateFromError(error) {
+    const control = navigation(error);
+    if (!control) throw error;
+    return { control };
+  }
+  static getDerivedStateFromProps(props, state) {
+    return props.resetKey !== state.resetKey ? { control: null, resetKey: props.resetKey } : null;
+  }
+  componentDidCatch(error) {
+    const control = navigation(error);
+    if (control?.href) this.context.router[control.replace ? 'replace' : 'push'](control.href);
+  }
+  render() {
+    if (this.state.control?.notFound) return React.createElement(React.Fragment, null,
+      React.createElement('meta', { name: 'robots', content: 'noindex' }), this.props.notFound);
+    if (this.state.control) return null;
+    return this.props.children;
+  }
+}
+
+module.exports = AppNavigationBoundary;
+module.exports.default = AppNavigationBoundary;
+module.exports.getNavigationControl = navigation;

package/compat/app.cjs

@@ -0,0 +1,33 @@
+'use strict';
+const React = require('react');
+
+// Shared by the server and browser: an App without a hook still delegates to
+// its Page, while a custom App hook owns that delegation itself.
+async function loadGetInitialProps(Component, context) {
+  if (process.env.NODE_ENV !== 'production' && Component.prototype?.getInitialProps) {
+    throw new Error(`${Component.displayName || Component.name || 'Component'}.getInitialProps must be a static method`);
+  }
+  const response = context.res || context.ctx?.res;
+  if (!Component.getInitialProps) {
+    if (context.ctx && context.Component) return { pageProps: await loadGetInitialProps(context.Component, context.ctx) };
+    return {};
+  }
+  const props = await Component.getInitialProps(context);
+  if (response?.finished || response?.headersSent || response?.writableEnded) return props;
+  if (!props) throw new Error(`${Component.displayName || Component.name || 'Component'}.getInitialProps must return an object; received ${props}`);
+  return props;
+}
+
+async function appGetInitialProps({ Component, ctx }) {
+  return { pageProps: await loadGetInitialProps(Component, ctx) };
+}
+
+class App extends React.Component {
+  static origGetInitialProps = appGetInitialProps;
+  static getInitialProps = appGetInitialProps;
+  render() { return React.createElement(this.props.Component, this.props.pageProps); }
+}
+
+module.exports = App;
+module.exports.default = App;
+module.exports.loadGetInitialProps = loadGetInitialProps;

package/compat/app.d.cts

@@ -0,0 +1,9 @@
+import { Component } from 'react';
+import type { AppContext, AppInitialProps, AppProps } from './index.d.ts';
+export type { AppContext, AppInitialProps, AppProps } from './index.d.ts';
+
+export default class App<P = {}, CP = {}, S = {}> extends Component<P & AppProps<CP>, S> {
+  static origGetInitialProps(context: AppContext): Promise<AppInitialProps>;
+  static getInitialProps(context: AppContext): Promise<AppInitialProps>;
+  render(): import('react').ReactElement;
+}

package/compat/cache-handlers.cjs

@@ -0,0 +1,223 @@
+'use strict';
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { validateTags, cacheState, getCachePaths } = require('./data-cache.cjs');
+const MAX_BYTES = 2 * 1024 * 1024;
+const modules = new Map();
+const requests = new WeakMap();
+const revisions = new WeakMap();
+const owners = new WeakMap();
+let pendingCount = 0;
+
+function configured(context) { return context?.cacheHandlers || context?.manifest?.config?.cacheHandlers || {}; }
+function outsideRequest(callback) { return require('./headers.cjs').runWithoutRequestContext(callback); }
+function wait(promise, signal, timeoutMs = 5000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => finish(reject, new Error('Cache handler operation timed out')), Math.max(1, timeoutMs));
+    timer.unref();
+    function finish(callback, value) { clearTimeout(timer); signal?.removeEventListener('abort', abort); callback(value); }
+    function abort() { finish(reject, signal.reason); }
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) abort();
+    Promise.resolve(promise).then(value => finish(resolve, value), error => finish(reject, error));
+  });
+}
+async function call(handler, method, args, context) {
+  return wait(outsideRequest(() => Promise.resolve().then(() => handler[method](...args))), context?.signal);
+}
+function softTags(context) {
+  // Next's implicit tags use /layout and /page suffixes and the _N_T_ prefix.
+  return [...new Set(getCachePaths(context).map(value => {
+    const separator = value.indexOf(':');
+    return '_N_T_' + value.slice(separator + 1).replace(/\/$/, '') + '/' + value.slice(0, separator);
+  }).concat(context?.url ? ['_N_T_' + (new URL(context.url).pathname.replace(/\/$/, '') || '/')] : []))];
+}
+async function load(context, kind) {
+  const source = configured(context)[kind];
+  if (!source) return undefined;
+  if (!context.distDir) throw new Error('Custom cache handlers require a build directory');
+  const root = path.resolve(context.distDir);
+  const file = path.resolve(root, source);
+  if (!source.startsWith('server/') || !file.startsWith(root + path.sep)) throw new Error('Invalid cache handler module path');
+  let pending = modules.get(file);
+  if (!pending) {
+    pending = outsideRequest(() => import(pathToFileURL(file).href)).then(module => {
+      const handler = module.default;
+      if (!handler || ['get', 'set', 'refreshTags', 'getExpiration', 'updateTags'].some(name => typeof handler[name] !== 'function')) throw new TypeError(`cacheHandlers.${kind} must export get, set, refreshTags, getExpiration and updateTags methods`);
+      return handler;
+    });
+    // Production workers have a single build. Bound this lookup for direct runtime callers.
+    if (modules.size >= 32) modules.delete(modules.keys().next().value);
+    modules.set(file, pending);
+  }
+  return wait(pending, context.signal);
+}
+async function refresh(handler, context) {
+  let refreshed = requests.get(context);
+  if (!refreshed) requests.set(context, refreshed = new Map());
+  if (!refreshed.has(handler)) refreshed.set(handler, call(handler, 'refreshTags', [], context));
+  return refreshed.get(handler);
+}
+function metadata(entry) {
+  if (!entry || !entry.value || typeof entry.value.getReader !== 'function' || typeof entry.value.cancel !== 'function') throw new TypeError('Invalid CacheEntry stream');
+  const tags = validateTags(entry.tags);
+  for (const field of ['timestamp', 'stale', 'revalidate', 'expire']) if (typeof entry[field] !== 'number' || !Number.isFinite(entry[field]) || entry[field] < 0) throw new TypeError(`Invalid CacheEntry ${field}`);
+  return { tags, timestamp: entry.timestamp, stale: entry.stale, revalidate: entry.revalidate, expire: entry.expire };
+}
+async function read(entry, context) {
+  const reader = entry.value.getReader();
+  const chunks = [];
+  let size = 0, complete = false;
+  const deadline = Date.now() + 5000;
+  let chunksRead = 0;
+  try {
+    while (true) {
+      if (Date.now() >= deadline || ++chunksRead > 10_000) throw new Error('CacheEntry stream exceeded its read budget');
+      const { value, done } = await wait(reader.read(), context.signal, deadline - Date.now());
+      if (done) { complete = true; break; }
+      if (!(value instanceof Uint8Array)) throw new TypeError('CacheEntry streams must contain bytes');
+      size += value.byteLength;
+      if (size > MAX_BYTES) throw new Error('CacheEntry exceeds 2 MiB');
+      chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks, size);
+  } finally {
+    if (!complete) void reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+function stream(bytes) {
+  let offset = 0;
+  return new ReadableStream({ pull(controller) {
+    if (offset === bytes.length) { controller.close(); return; }
+    const end = Math.min(bytes.length, offset + 64 * 1024);
+    controller.enqueue(new Uint8Array(bytes.subarray(offset, end))); offset = end;
+  } });
+}
+async function expiration(handler, tags, context) {
+  const value = await call(handler, 'getExpiration', [tags], context);
+  if (typeof value !== 'number' || value < 0 || Number.isNaN(value)) throw new TypeError('Cache handler getExpiration must return a nonnegative timestamp');
+  return value;
+}
+async function customCachedValue(key, kind, producer, options) {
+  const { context, resolveMetadata } = options;
+  const handler = await load(context, kind);
+  if (!handler) return undefined;
+  const state = cacheState(context);
+  await state.invalidations;
+  context.signal?.throwIfAborted();
+  const tags = softTags(context);
+  let entry, info, bytes;
+  try {
+    await refresh(handler, context);
+    const tagTime = await expiration(handler, tags, context);
+    entry = await call(handler, 'get', [key, tags], context);
+    if (entry) {
+      info = metadata(entry);
+      const age = Date.now() - info.timestamp;
+      if ((tagTime === Infinity || tagTime < info.timestamp) && age < info.expire * 1000 && (!context.staticState || age < info.revalidate * 1000)) bytes = await read(entry, context);
+      else void entry.value.cancel().catch(() => {});
+    }
+  } catch {
+    context.signal?.throwIfAborted();
+    if (typeof entry?.value?.cancel === 'function' && !entry.value.locked) void entry.value.cancel().catch(() => {});
+  }
+  const stale = bytes && Date.now() - info.timestamp >= info.revalidate * 1000;
+  if (bytes) options.onReadMetadata?.(info);
+  if (bytes && !stale) return bytes;
+  let pending = owners.get(handler);
+  if (!pending) owners.set(handler, pending = new Map());
+  const existing = pending.get(key);
+  // A post-mutation reader must not join a producer started before invalidation.
+  // Preventing that producer's write alone would still return its old value.
+  const joined = options.allowJoin !== false && existing?.revision === (revisions.get(handler) || 0) ? existing : undefined;
+  let work = joined?.work;
+  if (!work) {
+    const revision = revisions.get(handler) || 0;
+    const timestamp = performance.timeOrigin + performance.now();
+    const record = { revision, timestamp, work: undefined, metadata: undefined };
+    work = (async () => {
+      const result = await producer();
+      const info = resolveMetadata();
+      record.metadata = info;
+      if (result.byteLength <= MAX_BYTES && revision === (revisions.get(handler) || 0)) {
+        try {
+          const changed = await expiration(handler, [...new Set([...tags, ...info.tags])], context);
+          // Many backends record Date.now() millisecond timestamps. Treat the
+          // same millisecond conservatively so fractional producer times cannot
+          // hide an invalidation which actually happened after the read started.
+          if ((changed === Infinity || changed < Math.floor(timestamp)) && revision === (revisions.get(handler) || 0)) {
+            const value = stream(result);
+            try { await call(handler, 'set', [key, Promise.resolve({ value, tags: info.tags, stale: info.stale, revalidate: info.revalidate, expire: info.expire, timestamp })], context); }
+            catch { if (!value.locked) void value.cancel().catch(() => {}); }
+          }
+        } catch { context.signal?.throwIfAborted(); }
+      }
+      return result;
+    })();
+    record.work = work;
+    if (pendingCount < 64) {
+      pendingCount++; pending.set(key, record);
+      const cleanup = () => { if (pending.get(key) === record) pending.delete(key); pendingCount--; };
+      void work.then(cleanup, cleanup);
+    }
+  }
+  if (stale) {
+    const background = work.catch(() => {});
+    state.pending.add(background);
+    void background.finally(() => state.pending.delete(background));
+    return bytes;
+  }
+  const result = await work;
+  if (joined) {
+    let invalidated = joined.revision !== (revisions.get(handler) || 0);
+    let confirmed;
+    try {
+      const changed = await expiration(handler, [...new Set([...tags, ...(joined.metadata?.tags || [])])], context);
+      // Infinity delegates expiration to handler.get; it is not an invalidation
+      // timestamp. A finite timestamp can expose a different instance's update.
+      invalidated ||= changed !== Infinity && changed >= Math.floor(joined.timestamp);
+      if (changed === Infinity && !invalidated) {
+        // The backend may know about an invalidation that this worker cannot
+        // observe through getExpiration. Re-read its published value instead of
+        // trusting the result returned directly by the older producer.
+        confirmed = await call(handler, 'get', [key, tags], context);
+        if (confirmed) {
+          const confirmedInfo = metadata(confirmed);
+          const age = Date.now() - confirmedInfo.timestamp;
+          if (age < Math.min(confirmedInfo.expire, confirmedInfo.revalidate) * 1000) {
+            const confirmedBytes = await read(confirmed, context);
+            options.onReadMetadata?.(confirmedInfo);
+            return confirmedBytes;
+          }
+          void confirmed.value.cancel().catch(() => {});
+        }
+        invalidated = true;
+      }
+    } catch {
+      context.signal?.throwIfAborted(); invalidated = true;
+      if (typeof confirmed?.value?.cancel === 'function' && !confirmed.value.locked) void confirmed.value.cancel().catch(() => {});
+    }
+    // Only a joined reader retries, at most once, and cannot join another old
+    // producer on that attempt. The original caller's producer is never replayed.
+    if (invalidated) return customCachedValue(key, kind, producer, { ...options, allowJoin: false });
+  }
+  return result;
+}
+async function invalidateHandlers(context, operation) {
+  const tags = [...(operation.tags || []), ...(operation.paths || []).map(value => {
+    const separator = value.indexOf(':');
+    return '_N_T_' + value.slice(separator + 1).replace(/\/$/, '') + '/' + value.slice(0, separator);
+  })];
+  const durations = operation.mode === 'expire' ? { expire: 0 } : operation.expire === undefined ? undefined : { expire: operation.expire };
+  const seen = new Set();
+  for (const kind of Object.keys(configured(context))) {
+    const handler = await load(context, kind);
+    if (seen.has(handler)) continue;
+    seen.add(handler);
+    revisions.set(handler, (revisions.get(handler) || 0) + 1);
+    await call(handler, 'updateTags', [tags, durations], context);
+    requests.get(context)?.delete(handler);
+  }
+}
+module.exports = { configured, customCachedValue, invalidateHandlers, softTags };

package/compat/cache-life.cjs

@@ -0,0 +1,34 @@
+'use strict';
+const defaults = Object.freeze({
+  default: { stale: 300, revalidate: 900, expire: 4294967294 },
+  seconds: { stale: 30, revalidate: 1, expire: 60 },
+  minutes: { stale: 300, revalidate: 60, expire: 3600 },
+  hours: { stale: 300, revalidate: 3600, expire: 86400 },
+  days: { stale: 300, revalidate: 86400, expire: 604800 },
+  weeks: { stale: 300, revalidate: 604800, expire: 2592000 },
+  max: { stale: 300, revalidate: 2592000, expire: 31536000 },
+});
+function validateLife(input, { partial = true } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('cacheLife requires a profile name or { stale, revalidate, expire }');
+  const result = {};
+  for (const key of Object.keys(input)) {
+    if (!['stale', 'revalidate', 'expire'].includes(key)) throw new TypeError(`Unknown cacheLife option: ${key}`);
+    const value = input[key];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 4294967294) throw new TypeError(`cacheLife ${key} must be a nonnegative finite number of seconds`);
+    result[key] = value;
+  }
+  if (!Object.keys(result).length || !partial && Object.keys(result).length !== 3) throw new TypeError('cacheLife profiles must specify their lifetime');
+  if (result.expire !== undefined && result.revalidate !== undefined && result.expire < result.revalidate) throw new TypeError('cacheLife expire must be at least revalidate');
+  return result;
+}
+function profiles(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('cacheLife configuration must be an object of profiles');
+  const result = Object.fromEntries(Object.entries(defaults).map(([key, value]) => [key, { ...value }]));
+  for (const [key, value] of Object.entries(input)) {
+    if (!key || ['__proto__', 'constructor', 'prototype'].includes(key)) throw new TypeError('Invalid cacheLife profile name');
+    result[key] = { ...(result[key] || defaults.default), ...validateLife(value) };
+    validateLife(result[key], { partial: false });
+  }
+  return result;
+}
+module.exports = { defaults, validateLife, profiles };

package/compat/cache.cjs

@@ -0,0 +1,99 @@
+'use strict';
+const { createHash } = require('node:crypto');
+const { dynamicUsage, staticBailout, trackStaticDependency } = require('./static-generation.cjs');
+const { cacheTag, cacheLife, recordCacheDependency } = require('./use-cache.cjs');
+const {
+  cachedValue, cacheState, runCacheScope, inCacheScope, optionalRequestContext,
+  getCachePaths, normalizeCachePath, validateTags, validateRevalidate, queueInvalidation,
+} = require('./data-cache.cjs');
+
+function unstable_cache(callback, keyParts = [], options = {}) {
+  if (typeof callback !== 'function') throw new TypeError('unstable_cache requires a function');
+  if (!Array.isArray(keyParts) || keyParts.some(part => typeof part !== 'string')) throw new TypeError('unstable_cache keyParts must be an array of strings');
+  const tags = validateTags(options.tags);
+  const revalidate = validateRevalidate(options.revalidate === Infinity ? false : options.revalidate);
+  const fixedKey = JSON.stringify([callback.toString(), keyParts]);
+  return async function (...args) {
+    const context = optionalRequestContext();
+    const paths = getCachePaths(context);
+    if (context?.staticState) trackStaticDependency({ tags, revalidate, paths }, context);
+    recordCacheDependency({ tags, revalidate });
+    // Nested calls must not wait on a lease already owned by their outer call.
+    // A route's explicit force-no-store setting also prevents cached reads.
+    if (inCacheScope() || context?.cacheConfig?.forceNoStore || context?.draftMode) {
+      return runCacheScope(() => callback.apply(this, args));
+    }
+    const key = createHash('sha256').update(JSON.stringify(['unstable_cache', fixedKey, args])).digest('hex');
+    let produced = false;
+    let result;
+    const bytes = await cachedValue(key, async ({ background }) => runCacheScope(async () => {
+      const value = await callback.apply(this, args);
+      const serialized = Buffer.from(JSON.stringify({ value }));
+      if (!background) { produced = true; result = value; }
+      return serialized;
+    }), { tags, paths, revalidate, context,
+      incremental: {
+        encode: bytes => { const { value } = JSON.parse(bytes.toString('utf8')); return { headers: {}, status: 200, url: '', body: JSON.stringify(value) ?? 'null', ...(value === undefined ? { _prnextUndefined: true } : {}) }; },
+        decode: entry => {
+          if (typeof entry.data?.body !== 'string' || Buffer.byteLength(entry.data.body) > 2 * 1024 * 1024) throw new Error('Invalid incremental cached function data');
+          return Buffer.from(JSON.stringify(entry.data._prnextUndefined ? {} : { value: JSON.parse(entry.data.body) }));
+        },
+      },
+      forceFresh: !context || context.phase === 'pages' || Boolean(context.staticState) });
+    return produced ? result : JSON.parse(bytes.toString('utf8')).value;
+  };
+}
+
+function mutationContext(name, actionOnly = false) {
+  if (inCacheScope()) throw new Error(`${name} cannot be called inside unstable_cache`);
+  const context = optionalRequestContext();
+  if (!context || (actionOnly ? context.phase !== 'action' : !['action', 'route'].includes(context.phase))) {
+    throw new Error(`${name} can only be called in ${actionOnly ? 'a Server Action' : 'a Server Action or Route Handler'}, outside rendering`);
+  }
+  if (context.cacheState?.closed) throw new Error(`${name} cannot be called after the response headers have been sent`);
+  if (context.staticState) staticBailout(`${name}()`, context);
+  return context;
+}
+
+// Only the expiration window is relevant to tag invalidation. Values match
+// Next's built-in cacheLife profiles; custom next.config profiles are not yet read.
+const expirations = Object.freeze({ default: null, seconds: 60, minutes: 3600, hours: 86400, days: 604800, weeks: 2592000, max: 31536000 });
+function revalidateTag(tag, profile) {
+  const context = mutationContext('revalidateTag');
+  validateTags([tag]);
+  let expire;
+  if (profile === undefined) expire = 0;
+  else if (typeof profile === 'string') {
+    const configured = context.cacheLife || context.manifest?.config?.cacheLife;
+    if (configured && Object.hasOwn(configured, profile)) expire = configured[profile].expire;
+    else {
+      if (!Object.hasOwn(expirations, profile)) throw new TypeError(`Unknown cache lifetime profile: ${profile}`);
+      expire = expirations[profile];
+    }
+  } else if (profile && typeof profile === 'object' && !Array.isArray(profile)) {
+    expire = profile.expire ?? null;
+    if (expire !== null && (typeof expire !== 'number' || !Number.isFinite(expire) || expire < 0)) throw new TypeError('revalidateTag expire must be a nonnegative number of seconds');
+  } else throw new TypeError('revalidateTag requires a cache profile name or an expire option');
+  queueInvalidation(context, { tags: [tag], mode: expire === 0 ? 'expire' : 'stale', ...(expire === null ? {} : { expire }) });
+}
+function updateTag(tag) {
+  const context = mutationContext('updateTag', true);
+  validateTags([tag]);
+  queueInvalidation(context, { tags: [tag], mode: 'expire' });
+}
+function revalidatePath(path, type) {
+  const context = mutationContext('revalidatePath');
+  if (type !== undefined && type !== 'page' && type !== 'layout') throw new TypeError('revalidatePath type must be page or layout');
+  if (typeof path === 'string' && /\[[^/]+\]/.test(path) && !type) throw new TypeError('revalidatePath requires a page or layout type for dynamic paths');
+  const normalized = normalizeCachePath(path, { groups: true });
+  queueInvalidation(context, { paths: [`${type || 'page'}:${normalized}`], mode: 'expire' });
+}
+function unstable_noStore() {
+  if (inCacheScope()) return;
+  if (!dynamicUsage('unstable_noStore()')) return;
+  const state = cacheState();
+  if (state) state.noStore = true;
+}
+function refresh() { cacheState(mutationContext('refresh', true)).refresh = true; }
+
+module.exports = { unstable_cache, revalidateTag, updateTag, revalidatePath, unstable_noStore, refresh, cacheTag, cacheLife };

package/compat/cache.d.cts

@@ -0,0 +1,36 @@
+/// <reference path="./fetch.d.cts" />
+export interface CacheLife { stale?: number; revalidate?: number; expire?: number }
+export function cacheLife(profile: string | CacheLife): void;
+
+/** Storage interface accepted by the cacheHandlers project option. */
+export interface CacheEntry {
+  value: ReadableStream<Uint8Array>;
+  tags: string[];
+  stale: number;
+  timestamp: number;
+  expire: number;
+  revalidate: number;
+}
+export interface CacheHandler {
+  get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>;
+  set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>;
+  refreshTags(): Promise<void>;
+  getExpiration(tags: string[]): Promise<number>;
+  updateTags(tags: string[], durations?: { expire?: number }): Promise<void>;
+}
+export function cacheTag(...tags: string[]): void;
+
+export interface UnstableCacheOptions {
+  tags?: string[];
+  revalidate?: number | false;
+}
+export function unstable_cache<T extends (...args: any[]) => Promise<any>>(
+  callback: T,
+  keyParts?: string[],
+  options?: UnstableCacheOptions,
+): T;
+export function revalidateTag(tag: string, profile?: string | { expire?: number }): void;
+export function updateTag(tag: string): void;
+export function revalidatePath(path: string, type?: 'page' | 'layout'): void;
+export function unstable_noStore(): void;
+export function refresh(): void;

package/compat/compat/router.d.cts

@@ -0,0 +1,2 @@
+import type {NextRouter} from '../router.cjs';
+export function useRouter(): NextRouter | null;

package/compat/compat-router.cjs

@@ -0,0 +1,7 @@
+'use strict';
+const React = require('react');
+const {RouterContext} = require('./router.cjs');
+
+// Shared migration components may render outside the Pages Router provider.
+function useRouter() { return React.useContext(RouterContext); }
+module.exports = {useRouter};

package/compat/constants.cjs

@@ -0,0 +1,8 @@
+'use strict';
+exports.PHASE_EXPORT = 'phase-export';
+exports.PHASE_ANALYZE = 'phase-analyze';
+exports.PHASE_PRODUCTION_BUILD = 'phase-production-build';
+exports.PHASE_PRODUCTION_SERVER = 'phase-production-server';
+exports.PHASE_DEVELOPMENT_SERVER = 'phase-development-server';
+exports.PHASE_TEST = 'phase-test';
+exports.PHASE_INFO = 'phase-info';

package/compat/constants.d.cts

@@ -0,0 +1,7 @@
+export const PHASE_EXPORT: 'phase-export';
+export const PHASE_ANALYZE: 'phase-analyze';
+export const PHASE_PRODUCTION_BUILD: 'phase-production-build';
+export const PHASE_PRODUCTION_SERVER: 'phase-production-server';
+export const PHASE_DEVELOPMENT_SERVER: 'phase-development-server';
+export const PHASE_TEST: 'phase-test';
+export const PHASE_INFO: 'phase-info';