@wular/pnext 0.0.1

package/src/compat/next/offline.ts

@@ -0,0 +1,51 @@
+// `next/offline` - the useOffline() hook. Reports whether the app is currently offline: false on the
+// server and during hydration; in the browser it tracks the native online/offline events. The router's
+// own offline handling (soft-nav retry on reconnect) lives in api/router.ts; this hook is only the
+// UI-facing subscription.
+
+import { useEffect, useState } from 'preact/hooks';
+
+type Listener = () => void;
+
+const listeners = new Set<Listener>();
+let installed = false;
+let offline = false;
+
+function currentOffline(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  return navigator.onLine === false;
+}
+
+function install() {
+  if (installed || (!process.browser && typeof window === 'undefined')) return;
+  installed = true;
+  offline = currentOffline();
+  const update = () => {
+    const next = currentOffline();
+    if (next === offline) return;
+    offline = next;
+    for (const listener of [...listeners]) listener();
+  };
+  window.addEventListener('offline', update);
+  window.addEventListener('online', update);
+}
+
+/**
+ * True while the browser reports no connectivity. Server-rendered and
+ * hydrating trees always see `false` (matching Next: the offline state is a
+ * client-side signal only).
+ */
+export function useOffline(): boolean {
+  const [value, setValue] = useState(false);
+  useEffect(() => {
+    install();
+    const listener = () => setValue(offline);
+    listeners.add(listener);
+    // The state may have flipped between render and subscription.
+    listener();
+    return () => {
+      listeners.delete(listener);
+    };
+  }, []);
+  return value;
+}

package/src/compat/next/og.ts

@@ -0,0 +1,324 @@
+// next/og - ImageResponse (COMPAT).
+//
+// Renders a JSX element to a PNG the way Next's `next/og` / `@vercel/og` does: satori compiles the
+// element tree to an SVG, then @resvg/resvg-js rasterizes it to PNG bytes. Both are optionalDependencies
+// - when either is absent (or no usable font is available for satori's text layout) the endpoint falls
+// back to a self-contained minimal-but-valid PNG, so it still answers `content-type: image/png` with a
+// non-empty body in every runtime.
+//
+// The Response is constructed synchronously (Response bodies may be a stream), so the async
+// satori/resvg pipeline is driven through a ReadableStream that resolves the bytes lazily; the fallback
+// path also flows through the stream.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export interface ImageResponseFont {
+  name: string;
+  data: ArrayBuffer | Uint8Array;
+  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style?: 'normal' | 'italic';
+}
+
+export type ImageResponseOptions = ResponseInit & {
+  width?: number;
+  height?: number;
+  debug?: boolean;
+  fonts?: ImageResponseFont[];
+  emoji?: string;
+};
+
+const DEFAULT_WIDTH = 1200;
+const DEFAULT_HEIGHT = 630;
+const MAX_DIMENSION = 4096;
+const MAX_RAW_IMAGE_BYTES = 3 * 1024 * 1024;
+const PNG_SIGNATURE = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+
+let crcTable: Uint32Array | undefined;
+
+export class ImageResponse extends Response {
+  static displayName = 'ImageResponse';
+
+  constructor(element: unknown, options: ImageResponseOptions = {}) {
+    // Validate dimensions eagerly so an invalid width/height throws from the
+    // constructor (matching Next), not later inside the async PNG stream — a
+    // stream-time RangeError would otherwise surface as a degraded fallback PNG
+    // instead of the synchronous error callers assert on.
+    dimension(options.width, DEFAULT_WIDTH, 'width');
+    dimension(options.height, DEFAULT_HEIGHT, 'height');
+    const headers = new Headers(options.headers);
+    headers.set('content-type', 'image/png');
+    // Match Next's default caching behavior for on-the-fly OG images.
+    if (!headers.has('cache-control')) {
+      headers.set(
+        'cache-control',
+        'public, immutable, no-transform, max-age=31536000',
+      );
+    }
+    super(pngStream(element, options), {
+      status: options.status,
+      statusText: options.statusText,
+      headers,
+    });
+  }
+}
+
+/**
+ * A one-shot ReadableStream that renders the element to PNG bytes. Rendering is
+ * async (satori/resvg), so we enqueue inside `start`. Any failure degrades to
+ * the deterministic minimal PNG rather than erroring the response.
+ */
+function pngStream(element: unknown, options: ImageResponseOptions): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      let bytes: Uint8Array;
+      try {
+        bytes =
+          (await renderWithVercelOg(element, options)) ??
+          (await renderWithSatori(element, options)) ??
+          createFallbackPng(options);
+      } catch {
+        bytes = createFallbackPng(options);
+      }
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+interface VercelOgModule {
+  ImageResponse: new (element: unknown, options?: Record<string, unknown>) => Response;
+}
+
+/**
+ * Preferred path: delegate to the app's own `@vercel/og` (which `next/og` wraps in real Next). It
+ * bundles satori, a wasm resvg and a default font, so it produces a real JSX-to-PNG rasterization even
+ * when the fixture provides no `fonts` option - satori alone cannot lay out text without one.
+ *
+ * Resolved from the APP ROOT, not from pnext's own node_modules: the bundled server output lives outside
+ * the app tree, so a bare `import('@vercel/og')` would resolve against the wrong node_modules, or not at
+ * all. Resolving to an absolute path first keeps the optional dep bound to the user's install.
+ */
+async function renderWithVercelOg(
+  element: unknown,
+  options: ImageResponseOptions,
+): Promise<Uint8Array | undefined> {
+  const og = await loadFromAppRoot<VercelOgModule>('@vercel/og');
+  if (!og?.ImageResponse) return undefined;
+
+  const width = dimension(options.width, DEFAULT_WIDTH, 'width');
+  const height = dimension(options.height, DEFAULT_HEIGHT, 'height');
+  const response = new og.ImageResponse(element, {
+    width,
+    height,
+    ...(options.fonts === undefined ? {} : { fonts: options.fonts }),
+    ...(options.debug === undefined ? {} : { debug: options.debug }),
+    ...(options.emoji === undefined ? {} : { emoji: options.emoji }),
+  });
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  return bytes.length > 0 ? bytes : undefined;
+}
+
+interface SatoriModule {
+  default: (element: unknown, opts: Record<string, unknown>) => Promise<string>;
+}
+interface ResvgModule {
+  Resvg: new (
+    svg: string | Uint8Array,
+    opts?: Record<string, unknown>,
+  ) => { render: () => { asPng: () => Uint8Array } };
+}
+
+/**
+ * Full JSX-to-PNG pipeline via the optional deps. Returns undefined - triggering the fallback - when
+ * either dependency or a usable font is missing, since satori cannot lay out text without one.
+ */
+async function renderWithSatori(
+  element: unknown,
+  options: ImageResponseOptions,
+): Promise<Uint8Array | undefined> {
+  const satori = await loadOptional<SatoriModule>('satori');
+  const resvg = await loadOptional<ResvgModule>('@resvg/resvg-js');
+  if (!satori || !resvg) return undefined;
+
+  const fonts = normalizeFonts(options.fonts);
+  if (fonts.length === 0) return undefined;
+
+  const width = dimension(options.width, DEFAULT_WIDTH, 'width');
+  const height = dimension(options.height, DEFAULT_HEIGHT, 'height');
+
+  const svg = await satori.default(element, {
+    width,
+    height,
+    fonts,
+    ...(options.debug === undefined ? {} : { debug: options.debug }),
+    ...(options.emoji === undefined ? {} : { emoji: options.emoji }),
+  });
+
+  const renderer = new resvg.Resvg(svg, {
+    fitTo: { mode: 'width', value: width },
+  });
+  return renderer.render().asPng();
+}
+
+interface SatoriFont {
+  name: string;
+  data: ArrayBuffer | Uint8Array;
+  weight?: number;
+  style?: 'normal' | 'italic';
+}
+
+function normalizeFonts(fonts: ImageResponseFont[] | undefined): SatoriFont[] {
+  if (!fonts) return [];
+  return fonts.map(font => ({
+    name: font.name,
+    data: font.data,
+    ...(font.weight === undefined ? {} : { weight: font.weight }),
+    ...(font.style === undefined ? {} : { style: font.style }),
+  }));
+}
+
+/**
+ * Resolve an optional dependency without letting a missing module become a hard
+ * build/runtime error. The dynamic specifier is opaque to the bundler so the
+ * optional dep is never eagerly required.
+ */
+async function loadOptional<T>(name: string): Promise<T | undefined> {
+  try {
+    const specifier = name;
+    return (await import(/* @vite-ignore */ specifier)) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve + import an optional dependency from the APP ROOT (process.cwd(), the
+ * pnext server's working dir at runtime), not from the bundled output's
+ * location. Mirrors the MDX plugin resolution: createRequire anchored at the
+ * project root turns the bare name into an absolute path, which the opaque
+ * dynamic import then loads. Returns undefined when the package is not
+ * installed in the user's app.
+ */
+async function loadFromAppRoot<T>(name: string): Promise<T | undefined> {
+  try {
+    const resolveFrom = createRequire(path.join(process.cwd(), 'pnext-og-resolve.cjs'));
+    const resolved = resolveFrom.resolve(name);
+    return (await import(/* @vite-ignore */ resolved)) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fallback: a deterministic, valid 1-bit PNG of the requested dimensions. Not a
+// rendering of the element, but a non-empty `image/png` body honoring the
+// endpoint contract when satori/resvg (or a font) are unavailable.
+// ---------------------------------------------------------------------------
+
+function createFallbackPng(options: ImageResponseOptions) {
+  const width = dimension(options.width, DEFAULT_WIDTH, 'width');
+  const height = dimension(options.height, DEFAULT_HEIGHT, 'height');
+  const rowBytes = Math.ceil(width / 8) + 1;
+  const rawBytes = rowBytes * height;
+  if (rawBytes > MAX_RAW_IMAGE_BYTES) {
+    throw new RangeError(
+      `ImageResponse dimensions ${width}x${height} exceed the lightweight PNG limit.`,
+    );
+  }
+
+  const ihdr = new Uint8Array(13);
+  const ihdrView = new DataView(ihdr.buffer);
+  ihdrView.setUint32(0, width);
+  ihdrView.setUint32(4, height);
+  ihdr[8] = 1;
+
+  return concat(
+    PNG_SIGNATURE,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlibStoreZeros(rawBytes)),
+    chunk('IEND', new Uint8Array()),
+  );
+}
+
+function dimension(value: number | undefined, fallback: number, name: string) {
+  if (value === undefined) return fallback;
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`ImageResponse ${name} must be a positive finite number.`);
+  }
+  const rounded = Math.floor(value);
+  if (rounded > MAX_DIMENSION) {
+    throw new RangeError(`ImageResponse ${name} must be ${MAX_DIMENSION} pixels or less.`);
+  }
+  return rounded;
+}
+
+function zlibStoreZeros(length: number) {
+  const blockCount = Math.max(1, Math.ceil(length / 0xffff));
+  const output = new Uint8Array(2 + blockCount * 5 + length + 4);
+  output[0] = 0x78;
+  output[1] = 0x01;
+
+  let offset = 2;
+  let remaining = length;
+  while (remaining > 0 || offset === 2) {
+    const blockLength = Math.min(remaining, 0xffff);
+    remaining -= blockLength;
+    output[offset++] = remaining === 0 ? 0x01 : 0x00;
+    output[offset++] = blockLength & 0xff;
+    output[offset++] = (blockLength >> 8) & 0xff;
+    const inverse = 0xffff - blockLength;
+    output[offset++] = inverse & 0xff;
+    output[offset++] = (inverse >> 8) & 0xff;
+    offset += blockLength;
+  }
+
+  const adler = ((length % 65521) << 16) | 1;
+  new DataView(output.buffer).setUint32(output.length - 4, adler);
+  return output;
+}
+
+function chunk(type: string, data: Uint8Array) {
+  const output = new Uint8Array(12 + data.length);
+  const view = new DataView(output.buffer);
+  view.setUint32(0, data.length);
+  for (let index = 0; index < 4; index += 1) {
+    output[4 + index] = type.charCodeAt(index);
+  }
+  output.set(data, 8);
+  view.setUint32(output.length - 4, crc32(output.subarray(4, output.length - 4)));
+  return output;
+}
+
+function crc32(bytes: Uint8Array) {
+  const table = crcTable ?? createCrcTable();
+  crcTable = table;
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc = table[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function createCrcTable() {
+  const table = new Uint32Array(256);
+  for (let index = 0; index < table.length; index += 1) {
+    let value = index;
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+    table[index] = value >>> 0;
+  }
+  return table;
+}
+
+function concat(...parts: Uint8Array[]) {
+  const length = parts.reduce((total, part) => total + part.length, 0);
+  const output = new Uint8Array(length);
+  let offset = 0;
+  for (const part of parts) {
+    output.set(part, offset);
+    offset += part.length;
+  }
+  return output;
+}

package/src/compat/next/optimistic-route-state.ts

@@ -0,0 +1,188 @@
+// Optimistic-routing route state (COMPAT - may import core freely).
+//
+// Next's client router builds a route-prediction trie from visited routes; a dynamic segment's trie node
+// records its STATIC SIBLINGS (literal segments at the same URL level) so a prediction never shadows a
+// static route. pnext ships the same information inline: the `__PNEXT_ROUTE__` state of a rendered
+// document carries `staticChildren` - the literal sibling names at the route's deepest dynamic level.
+//
+// Siblings are computed from the ROUTE MANIFEST in URL space, which is what makes the Next-parity cases
+// fall out for free: route groups collapse, parallel-route slot pages appear via their synthetic slot
+// URLs, and page-less intermediate directories still surface as static children without leaking their
+// nested names.
+
+import type { RouteManifestEntry, RouteParamValue } from '../../types';
+import { getRequestRuntime } from '../../routing/request-runtime';
+import { getNextConfig } from './config-loader';
+
+interface RouteState {
+  route: string;
+  params: Record<string, RouteParamValue>;
+  catchAllOptional?: boolean;
+  staticChildren?: string[];
+  staticChildrenBySegment?: Record<string, string[]>;
+  prefetchKind?: 'shell' | 'eager';
+  /**
+   * `prefetch = 'allow-runtime'`: the route's shell is RUNTIME-prefetched (request-sampled,
+   * param-derived), so unlike a static `partial` shell it is NOT shared across params - every URL of the
+   * route needs its own prefetch.
+   */
+  runtimePrefetch?: boolean;
+  /**
+   * The vary set of the BAKED SHELL these bytes came from (renderer's
+   * `bakedShellPageVary`). Passed straight through by the spread below: the
+   * client segment cache reads it off a hard-loaded document to key that
+   * document's static stage across the route's params.
+   */
+  pageVary?: string[];
+}
+
+/**
+ * `route.route` pattern segments in the client's bracket-free colon form (`:id`, `:slug*`). Both the
+ * manifest routes and the embedded `__PNEXT_ROUTE__` state use this encoding, so siblings computed here
+ * align with the pattern the client trie matches against - and no `[x]` placeholder ever reaches a body.
+ */
+function publicSegments(route: string): string[] {
+  if (route === 'index' || route === '/') return [];
+  return route.split('/').filter(Boolean);
+}
+
+function isDynamicSegment(segment: string): boolean {
+  return segment.startsWith(':');
+}
+
+/**
+ * Literal sibling names at the deepest level of `pattern` (the level its dynamic/catch-all tail owns).
+ * A manifest route contributes the literal it places at that level when its leading segments are
+ * compatible with the pattern's prefix - literal-vs-literal must match, and a dynamic segment on either
+ * side matches anything. Over-collecting is safe: it only suppresses a prediction that then falls back
+ * to the server.
+ */
+export function staticSiblingNames(
+  routes: readonly Pick<RouteManifestEntry, 'route' | 'kind' | 'interception'>[],
+  pattern: readonly string[],
+): string[] {
+  for (let index = pattern.length - 1; index >= 0; index--) {
+    if (isDynamicSegment(pattern[index]!)) return staticSiblingNamesAt(routes, pattern, index);
+  }
+  return [];
+}
+
+/** Literal static siblings for every dynamic level in a route prediction. */
+export function staticSiblingNamesBySegment(
+  routes: readonly Pick<RouteManifestEntry, 'route' | 'kind' | 'interception'>[],
+  pattern: readonly string[],
+): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+  for (let index = 0; index < pattern.length; index++) {
+    if (!isDynamicSegment(pattern[index]!)) continue;
+    const siblings = staticSiblingNamesAt(routes, pattern, index);
+    // An empty array is meaningful: unlike an absent entry, it says this
+    // production route table knows there are no literal siblings here.
+    result[String(index)] = siblings;
+  }
+  return result;
+}
+
+function staticSiblingNamesAt(
+  routes: readonly Pick<RouteManifestEntry, 'route' | 'kind' | 'interception'>[],
+  pattern: readonly string[],
+  level: number,
+): string[] {
+  if (!isDynamicSegment(pattern[level]!)) return [];
+  const names = new Set<string>();
+  for (const route of routes) {
+    if (route.kind !== 'page' || route.interception) continue;
+    const segments = publicSegments(route.route);
+    if (segments.length <= level) continue;
+    let compatible = true;
+    for (let index = 0; index < level; index++) {
+      const own = pattern[index]!;
+      const other = segments[index]!;
+      if (isDynamicSegment(own) || isDynamicSegment(other)) continue;
+      if (own !== other) {
+        compatible = false;
+        break;
+      }
+    }
+    if (!compatible) continue;
+    const name = segments[level]!;
+    if (!isDynamicSegment(name)) names.add(name);
+  }
+  return [...names].sort();
+}
+
+/** True when the build enumerated exactly this param set for the route. */
+function paramsPrerendered(
+  route: Pick<RouteManifestEntry, 'prerenderedParams' | 'params'>,
+  params: Record<string, RouteParamValue>,
+): boolean {
+  const sets = route.prerenderedParams;
+  if (!sets?.length) return false;
+  // A PPR SUB-shell carries only the params the build made concrete (the rest
+  // are still holes), so its state is not the full URL's — never "prerendered".
+  if (Object.keys(params).length !== (route.params ?? []).length) return false;
+  return sets.some(set => {
+    const names = Object.keys(set);
+    return (
+      names.length === Object.keys(params).length &&
+      names.every(name => String(set[name]) === String(params[name]))
+    );
+  });
+}
+
+/**
+ * Enrich the client route state of a rendered document with the static
+ * siblings of every dynamic segment. Reads the route table from the
+ * request runtime (published by start/dev handlers and by the build's
+ * prerender pass); without one the state passes through unchanged and the
+ * client simply never predicts (safe fallback).
+ */
+export function nextClientRouteState(
+  route: Pick<
+    RouteManifestEntry,
+    | 'route'
+    | 'file'
+    | 'hasStaticParams'
+    | 'usesRequest'
+    | 'segmentConfig'
+    | 'prerenderedParams'
+    | 'params'
+    | 'stream'
+  >,
+  state: RouteState,
+): RouteState {
+  const pattern = state.route.split('/').filter(Boolean);
+  const routes = getRequestRuntime()?.routes;
+  if (!routes) return state;
+  const staticChildrenBySegment = staticSiblingNamesBySegment(routes, pattern);
+  const staticChildren = staticSiblingNames(routes, pattern);
+  // Global `partialPrefetching: 'unstable_eager'` makes every route without a
+  // per-segment `prefetch` export eager (the App Shells Speculative-skip does
+  // not apply anywhere); a per-segment export still wins.
+  const globalEager =
+    (getNextConfig() as { partialPrefetching?: unknown }).partialPrefetching === 'unstable_eager';
+  const declared = route.segmentConfig?.prefetch;
+  // `generateStaticParams` only makes a route eager for the param sets it actually enumerated. When
+  // THIS URL's params were not among them and the route has a `loading` boundary, its page is dynamic
+  // here - the server answers the default prefetch with the loading shell, and calling it eager would
+  // escalate the reveal to a FULL prefetch that fetches the dynamic body and erases the loading state.
+  const partiallyEnumerated =
+    route.stream?.hasLoadingBoundary === true && !paramsPrerendered(route, state.params);
+  const prefetchKind =
+    declared === 'unstable_eager' ||
+    (declared === undefined &&
+      (globalEager || (route.hasStaticParams && !route.usesRequest && !partiallyEnumerated)))
+      ? 'eager'
+      : declared === 'allow-runtime' || declared === 'partial'
+        ? 'shell'
+        : undefined;
+  return {
+    ...state,
+    ...(staticChildren.length > 0 ? { staticChildren } : {}),
+    ...(Object.keys(staticChildrenBySegment).length > 0 ? { staticChildrenBySegment } : {}),
+    ...(prefetchKind ? { prefetchKind } : {}),
+    // Only `allow-runtime` shells are request-sampled per URL; a `partial` shell
+    // is a static prerender the whole route shares.
+    ...(declared === 'allow-runtime' ? { runtimePrefetch: true } : {}),
+  };
+}

package/src/compat/next/preferred-region.ts

@@ -0,0 +1,39 @@
+// `export const preferredRegion` extraction (COMPAT). Next records a route segment's preferredRegion in
+// its build manifests as a normalized string[]. It is read straight off the route's source files via
+// regex - the value is a static export, so a scan matches how `maxDuration` is already collected in core.
+
+import { readFileSync } from 'node:fs';
+import type { RouteManifestEntry } from '../../types';
+
+const PREFERRED_REGION_RE =
+  /\bexport\s+const\s+preferredRegion\s*=\s*(\[[^\]]*\]|['"][^'"]*['"])/;
+
+/**
+ * Resolve the route's `preferredRegion`, normalized to a string[] (Next accepts
+ * a single string or an array). Returns undefined when no segment declares it.
+ */
+export function preferredRegionForRoute(route: RouteManifestEntry): string[] | undefined {
+  for (const file of routeSources(route)) {
+    let source: string;
+    try {
+      source = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const match = PREFERRED_REGION_RE.exec(source);
+    if (!match?.[1]) continue;
+    return parsePreferredRegion(match[1]);
+  }
+  return undefined;
+}
+
+function routeSources(route: RouteManifestEntry): string[] {
+  return [...new Set([route.file, ...route.sourceFiles])].filter(Boolean);
+}
+
+function parsePreferredRegion(literal: string): string[] {
+  if (literal.startsWith('[')) {
+    return Array.from(literal.matchAll(/['"]([^'"]*)['"]/g), m => m[1] ?? '');
+  }
+  return [literal.slice(1, -1)];
+}