@wular/pnext 0.0.1

package/src/compat/register/static-image.ts

@@ -0,0 +1,21 @@
+// next/image static-import extension registration (COMPAT - may import core).
+//
+// Registers the Next static-image module producer into core's `staticAssetModule` seam so
+// `import img from './pic.png'` in the server module pipeline evaluates to the full
+// `{src,width,height,blurDataURL,blurWidth,blurHeight}` descriptor next/image consumes, with the asset
+// emitted under `/_next/static/media/<name>.<hash>.<ext>`.
+//
+// Safe in a pure-core app: the seam only overrides core's generic asset module for recognized image
+// extensions; everything else falls through.
+
+import { setAssetExtensions } from '../../extensions';
+import { staticImageModule } from '../next/image/static-metadata';
+
+export function registerStaticImageExtensions(): void {
+  setAssetExtensions({
+    staticAssetPublicPrefixes: () => ['/__pnext/static/media/', '/_next/static/media/'],
+    staticAssetRelativePath: ({ base, hash, ext }) =>
+      ['_next', 'static', 'media', `${base}.${hash}${ext}`].join('/'),
+    staticAssetModule: staticImageModule,
+  });
+}

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

@@ -0,0 +1,35 @@
+// Typed-routes codegen registration (COMPAT - may import core freely). Wires a build step into
+// buildExtensions.steps that emits Next-shaped route type definitions under
+// `<root>/.next/types/{routes.d.ts,link.d.ts,validator.ts}`. Runs during a build under compat.next;
+// pure-core apps register nothing.
+
+import type { ResolvedConfig } from '../../config';
+import {
+  registerBuildParallelPhases,
+  registerBuildSteps,
+  type BuildStepContext,
+} from '../../extensions';
+import type { RouteManifestEntry } from '../../types';
+import { nextCompatEnabled } from '../index';
+import { writeTsconfigDefaults } from '../tsconfig-defaults';
+import { typecheckDisabled, validateTypesOffThread } from '../typecheck';
+import { generateTypedRoutes } from '../typed-routes';
+
+export function registerTypedRoutesExtensions(_config: ResolvedConfig): void {
+  registerBuildSteps(runTypedRoutesBuildStep);
+}
+
+async function runTypedRoutesBuildStep(ctx: BuildStepContext): Promise<void> {
+  if (!nextCompatEnabled(ctx.config)) return;
+  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
+  // the summary. A build that disables it reports no line at all.
+  if (typecheckDisabled()) return;
+  const startedAt = performance.now();
+  registerBuildParallelPhases({
+    name: 'Typecheck',
+    run: validateTypesOffThread(ctx.config).then(() => performance.now() - startedAt),
+  });
+}

package/src/compat/register/usecache.ts

@@ -0,0 +1,131 @@
+// `use cache` response-header registration (COMPAT - may import core freely).
+//
+// Wires the SWR cache-control headers Next emits for a `use cache` route into core via a
+// responseFinalizer: `cache-control: s-maxage=<revalidate>, stale-while-revalidate=<expire-revalidate>`
+// and `x-nextjs-stale-time: <stale>`.
+//
+// Mechanism mirrors the font runtime: as each `use cache` entry resolves during a render it stashes its
+// effective cacheLife on the request work unit. This finalizer, running before the first flush inside the
+// same work unit, reads the aggregate and sets the headers. A user-supplied Cache-Control survives - the
+// header is only set when absent, matching the "merge, do not overwrite" finalizer discipline.
+//
+// LIMITATION: statically-served prerendered pages (a cache HIT from prebuilt bytes) do not re-run a
+// render, so no cacheLife is stashed for them - the header is emitted only on dynamic renders and
+// lazy-static MISS responses. Emitting it for pure static HITs needs the route's cacheLife persisted in
+// the build manifest and read by the static-serve path in src/cli/start.ts.
+
+import type { ResolvedConfig } from '../../config';
+import { nextCompatEnabled } from '../../compat';
+import {
+  onExtensionHostReset,
+  registerBuildCompleteHooks,
+  registerBuildSteps,
+  registerResponseFinalizers,
+  type ResponseFinalizer,
+  type ResponseFinalizerContext,
+} from '../../extensions';
+import {
+  setUseCacheFillTimeout,
+  setUseCacheRootParamNames,
+  takeCacheLifeStash,
+} from '../cache/use-cache';
+import { scanRootParams } from '../ppr/root-params-scan';
+import {
+  beginPrerenderErrorCollection,
+  endPrerenderErrorCollection,
+} from '../cache/build-prerender-errors';
+import { getNextConfig } from '../next/config-loader';
+
+// Route kinds a `use cache` page/handler can be served as.
+const CACHEABLE_ROUTE_KINDS = new Set<ResponseFinalizerContext['routeKind']>([
+  'html',
+  'data',
+  'route-handler',
+]);
+
+const useCacheHeaderFinalizer: ResponseFinalizer = ctx => {
+  const life = takeCacheLifeStash();
+  if (!life) return;
+  if (!CACHEABLE_ROUTE_KINDS.has(ctx.routeKind)) return;
+
+  const { revalidateSeconds, expireSeconds, staleSeconds } = life;
+
+  // SWR cache-control: s-maxage = revalidate, stale-while-revalidate =
+  // expire − revalidate. Emitted only when a revalidate window is known and no
+  // explicit Cache-Control was already set by the app/route.
+  if (
+    revalidateSeconds !== undefined &&
+    expireSeconds !== undefined &&
+    !ctx.headers.has('cache-control')
+  ) {
+    const swr = Math.max(0, expireSeconds - revalidateSeconds);
+    ctx.headers.set('cache-control', `s-maxage=${revalidateSeconds}, stale-while-revalidate=${swr}`);
+  }
+
+  // x-nextjs-stale-time drives the client router's cache staleness window.
+  // Set unconditionally: the segment finalizer runs earlier and stamps a
+  // mode-derived default, but the live render's own cacheLife is authoritative
+  // (the header is internal — never user-supplied — so overwriting is safe).
+  if (staleSeconds !== undefined) {
+    ctx.headers.set('x-nextjs-stale-time', String(staleSeconds));
+  }
+};
+
+let registered = false;
+// Host-scoped guard: a fresh host must be registered into again.
+onExtensionHostReset(() => (registered = false));
+
+export function registerUseCacheExtensions(config: ResolvedConfig): void {
+  if (registered) return;
+  if (!nextCompatEnabled(config)) return;
+  registered = true;
+  registerResponseFinalizers(useCacheHeaderFinalizer);
+
+  // Seed the root-param NAME set for cache-key participation (Stage B-3): a
+  // `use cache` entry's conservative first-call key may only discriminate by
+  // root params, so the runtime needs the scanned names at build AND serve.
+  setUseCacheRootParamNames(scanRootParams(config.appPath));
+
+  // Arm `use cache` build-time validation for this build's prerender pass.
+  // Registered as a build STEP so it runs before any page is prerendered; the
+  // registry is process-global, so re-check enablement per build (a later
+  // pure-core buildProject in the same process must stay unarmed).
+  registerBuildSteps(ctx => {
+    if (nextCompatEnabled(ctx.config)) {
+      const config = getNextConfig() as {
+        experimental?: { useCacheTimeout?: number };
+        staticPageGenerationTimeout?: number;
+      };
+      const configured = config.experimental?.useCacheTimeout;
+      const staticTimeout = config.staticPageGenerationTimeout;
+      // Next clamps the build-time `use cache` fill timeout to just under the
+      // page-generation timeout (1s buffer before the build worker kills the
+      // page), so a slow fill fails via the clamp rather than the worker.
+      const baseMs = typeof configured === 'number' ? configured * 1000 : 50_000;
+      const clampMs =
+        typeof staticTimeout === 'number' && staticTimeout > 1
+          ? (staticTimeout - 1) * 1000
+          : undefined;
+      const fillMs = clampMs !== undefined ? Math.min(baseMs, clampMs) : baseMs;
+      setUseCacheFillTimeout(fillMs);
+      beginPrerenderErrorCollection();
+    }
+    return Promise.resolve();
+  });
+
+  // After prerendering, surface any recorded `use cache` violations. Each is
+  // printed with Next's exact error text plus the "Error occurred prerendering
+  // page" line the e2e suites grep for, then the build is aborted (exit 1).
+  registerBuildCompleteHooks(ctx => {
+    const errors = endPrerenderErrorCollection();
+    if (!nextCompatEnabled(ctx.config) || errors.length === 0) return Promise.resolve();
+    // Messages were already printed at detection time (see recordPrerenderError);
+    // the hook only forces the non-zero exit for builds that otherwise completed
+    // (a swallowed hanging timeout or a caught searchParams access).
+    throw new Error(
+      `pnext build: ${errors.length} "use cache" validation error${
+        errors.length === 1 ? '' : 's'
+      } (see above)`,
+    );
+  });
+}

package/src/compat/register/validation.ts

@@ -0,0 +1,56 @@
+// Build-time validation registration (COMPAT - may import core freely).
+//
+// Registers a single build step that runs the Next-compatible validation pass over the scanned route
+// table. A validation failure throws PnextBuildValidationError, aborting the build with Next's exact
+// error string on stderr, which the Next e2e suites substring-match.
+//
+// The step is ordered FIRST among build steps (registered before action discovery) so validation fails
+// fast, before any bundling or prerender work. Registration is idempotent and no-op for pure-core apps.
+
+import type { ResolvedConfig } from '../../config';
+import { nextCompatEnabled } from '../../compat';
+import {
+  onExtensionHostReset,
+  registerBuildSteps,
+  setBuildCompatExtensions,
+  type BuildStep,
+} from '../../extensions';
+import type { RouteManifestEntry } from '../../types';
+import { writeBuildFlags } from '../cache/build-flags';
+import { validateBuild } from '../validation';
+import {
+  diagnoseCacheComponentsPrerender,
+  diagnosticLeadsWithErrorLine,
+  prerenderFailureFooter,
+} from '../validation/prerender-diagnostics';
+
+let registered = false;
+// Host-scoped guard: a fresh host must be registered into again.
+onExtensionHostReset(() => (registered = false));
+
+export function registerValidationExtensions(config: ResolvedConfig): void {
+  if (registered) return;
+  if (!nextCompatEnabled(config)) return;
+  registered = true;
+
+  const step: BuildStep = async ctx => {
+    // Runtime compat gate: the extension registry is process-global, so once any compat.next build
+    // registers this step it stays registered for every later buildProject() in the same process -
+    // including pure-core fixtures that legitimately have no root layout. Re-check enablement per build so
+    // validation only runs for the app that actually enabled compat.next.
+    if (!nextCompatEnabled(ctx.config)) return;
+    await ctx.log.step('validate build', () =>
+      Promise.resolve(validateBuild(ctx.config, ctx.routes as RouteManifestEntry[])),
+    );
+  };
+  // Gate step: validation diagnostics must beat any error the invalid app would
+  // otherwise raise first from bundling or the not-found prerender.
+  step.gate = true;
+  registerBuildSteps(step);
+  setBuildCompatExtensions({
+    diagnoseCacheComponentsPrerender,
+    diagnosticLeadsWithErrorLine,
+    prerenderFailureFooter,
+    recordBuildFlags: writeBuildFlags,
+  });
+}

package/src/compat/segment/loading-boundary.ts

@@ -0,0 +1,113 @@
+// In-page loading-boundary detection (COMPAT).
+//
+// A route serves a truncated loading shell on a default (partial) prefetch when its render is GUARANTEED
+// to stop at a boundary. The `loading` convention file is one such marker; an in-page `<Suspense>` around
+// the params-dependent subtree is the other - Next's vary-params suites prefetch exactly that shape and
+// expect the shared fallback shell rather than a segment miss.
+//
+// Detection is a static source scan (no bundling, no evaluation), deliberately narrow: the identifier
+// must be imported from `react` AND used as JSX in the scanned source. Missing a boundary only leaves the
+// route on today's segment-miss path, so false negatives are the safe direction.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * True when the route's PAGE file wraps content in a React `<Suspense>`.
+ *
+ * The manifest's page file is not always the author's source: the hybrid
+ * pages+app materializer shims every app convention as `export * from
+ * '<relative source>'`, so a text scan of the shim sees no JSX at all. Follow
+ * relative re-exports (one shim hop is all the materializer emits; the depth
+ * bound keeps a cyclic re-export from looping) before scanning.
+ */
+export function pageHasInPageSuspense(file: string): boolean {
+  return scanSourceOf(file, 2).some(sourceHasInPageSuspense);
+}
+
+/** `file`'s source plus the sources of its relative re-export targets. */
+function scanSourceOf(file: string, depth: number, seen = new Set<string>()): string[] {
+  const resolved = resolveSourceFile(file);
+  if (resolved === null || seen.has(resolved)) return [];
+  seen.add(resolved);
+  let source: string;
+  try {
+    source = readFileSync(resolved, 'utf8');
+  } catch {
+    return [];
+  }
+  const sources = [source];
+  if (depth <= 0) return sources;
+  const pattern = /(?:export|import)\s+(?:\*(?:\s+as\s+[\w$]+)?|\{[^}]*\})\s+from\s*['"](\.[^'"]+)['"]/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(source)) !== null) {
+    const specifier = match[1];
+    if (!specifier) continue;
+    sources.push(...scanSourceOf(path.resolve(path.dirname(resolved), specifier), depth - 1, seen));
+  }
+  return sources;
+}
+
+/** `file` itself, or the first existing extension/index candidate for it. */
+function resolveSourceFile(file: string): string | null {
+  if (existsSync(file) && statSync(file).isFile()) return file;
+  for (const extension of SOURCE_EXTENSIONS) {
+    for (const candidate of [`${file}${extension}`, path.join(file, `index${extension}`)]) {
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+const SOURCE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+
+/**
+ * True when `source` imports `Suspense` from React and uses it as a JSX element. Comments are stripped
+ * first (fixtures routinely describe the shape they do NOT have in prose above the component). Both the
+ * named import and the namespace/default form are recognized.
+ */
+export function sourceHasInPageSuspense(source: string): boolean {
+  const stripped = stripComments(source);
+  const clauses = reactImportClauses(stripped);
+  if (clauses.length === 0) return false;
+  const named = clauses.some(clause => /\bSuspense\b/.test(clause));
+  if (named && /<\s*Suspense[\s/>]/.test(stripped)) return true;
+  // `<React.Suspense>` / `<Foo.Suspense>` needs a default or namespace binding
+  // of the react module under that name.
+  return namespaceBindings(clauses).some(name =>
+    new RegExp(`<\\s*${escapeRegExp(name)}\\.Suspense[\\s/>]`).test(stripped),
+  );
+}
+
+/** The import clauses of every `... from 'react'` statement in `source`. */
+function reactImportClauses(source: string): string[] {
+  const clauses: string[] = [];
+  const pattern = /import\s+([^'"]*?)\s+from\s*['"]react['"]/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(source)) !== null) clauses.push(match[1] ?? '');
+  // `const React = require('react')` — the CJS form app code still uses.
+  const cjs = /(?:const|let|var)\s+([\w$]+)\s*=\s*require\(\s*['"]react['"]\s*\)/g;
+  while ((match = cjs.exec(source)) !== null) clauses.push(`* as ${match[1] ?? ''}`);
+  return clauses;
+}
+
+/** Names bound to the whole react module by an import clause (default/namespace). */
+function namespaceBindings(clauses: readonly string[]): string[] {
+  const names: string[] = [];
+  for (const clause of clauses) {
+    const namespace = /\*\s+as\s+([\w$]+)/.exec(clause);
+    if (namespace?.[1]) names.push(namespace[1]);
+    // A default binding precedes any `{ ... }` named list.
+    const fallback = /^\s*([\w$]+)\s*(?:,|$)/.exec(clause.split('{')[0] ?? '');
+    if (fallback?.[1] && fallback[1] !== '*') names.push(fallback[1]);
+  }
+  return names;
+}
+
+function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/compat/segment/page-slot.ts

@@ -0,0 +1,200 @@
+// Page-slot framing for the layout/page segment split (COMPAT - browser-safe).
+//
+// pnext answers a segment prefetch with ONE document that carries the layout chain AND the page. Next
+// answers with per-segment frames, each keyed on the params THAT segment read - which is what lets a
+// navigation re-fetch a layout (vary `[category, item]`) while reusing the cached page (vary `[category]`).
+//
+// pnext keeps the one-document wire form and derives the two frames from it: the page's markup always
+// lives inside the renderer's page slot, emitted as either a `<div id="pnext-page">` wrapper or the
+// neutralized comment pair a client-island bootstrap dissolves it into. So the LAYOUT frame is the
+// document with the slot's CHILDREN removed, the PAGE frame is the document as rendered, and composing
+// them splices the page frame's slot children into the layout frame's slot.
+//
+// Deliberately string-level, not DOM-level: the server has no DOM and the client runs this before it
+// parses anything. The div scan is BALANCED - a greedy `</div>` match swallows ancestor closing tags and
+// leaves the layout unclosed.
+
+/** The byte range of a document's page slot and of the page markup inside it. */
+export interface PageSlotRange {
+  /** Index of the opening `<div …>` / `<!--pnext-page:…-->` marker. */
+  start: number;
+  /** Index just past the opening marker (where the page's markup begins). */
+  childrenStart: number;
+  /** Index of the closing `</div>` / `<!--/pnext-page-->` marker. */
+  childrenEnd: number;
+  /** Index just past the closing marker. */
+  end: number;
+}
+
+const SLOT_DIV_OPEN = /<div\b[^>]*\bid="pnext-page"[^>]*>/;
+const SLOT_COMMENT_OPEN = /<!--pnext-page:[^>]*-->/;
+const SLOT_COMMENT_CLOSE = '<!--/pnext-page-->';
+
+/**
+ * Locate the page slot in a rendered document, or null when it has none (a
+ * global-error document, a page that ships no client runtime and therefore had
+ * its slot markers dropped, a non-pnext body).
+ */
+export function pageSlotRange(html: string): PageSlotRange | null {
+  const comment = SLOT_COMMENT_OPEN.exec(html);
+  if (comment) {
+    const childrenStart = comment.index + comment[0].length;
+    const childrenEnd = html.indexOf(SLOT_COMMENT_CLOSE, childrenStart);
+    if (childrenEnd === -1) return null;
+    return {
+      start: comment.index,
+      childrenStart,
+      childrenEnd,
+      end: childrenEnd + SLOT_COMMENT_CLOSE.length,
+    };
+  }
+  const open = SLOT_DIV_OPEN.exec(html);
+  if (!open) return null;
+  const childrenStart = open.index + open[0].length;
+  const tag = /<div\b|<\/div>/g;
+  tag.lastIndex = childrenStart;
+  let depth = 1;
+  for (let match = tag.exec(html); match; match = tag.exec(html)) {
+    depth += match[0] === '</div>' ? -1 : 1;
+    if (depth !== 0) continue;
+    return {
+      start: open.index,
+      childrenStart,
+      childrenEnd: match.index,
+      end: match.index + match[0].length,
+    };
+  }
+  return null;
+}
+
+/** The page's own markup (the slot's children), or null without a slot. */
+export function pageSlotContent(html: string): string | null {
+  const range = pageSlotRange(html);
+  return range ? html.slice(range.childrenStart, range.childrenEnd) : null;
+}
+
+/**
+ * The LAYOUT frame of a rendered document: the same document with the page's markup removed and the slot
+ * left empty. Returned unchanged when the document has no page slot - an empty layout frame would be
+ * worse than a whole one.
+ */
+export function stripPageSlotContent(html: string): string {
+  const range = pageSlotRange(html);
+  if (!range) return html;
+  return html.slice(0, range.childrenStart) + html.slice(range.childrenEnd);
+}
+
+// A streamed Suspense continuation: the hidden chunk divs the renderer appends
+// near the end of the document (renderer.ts STREAM_CHUNK_MARKER), plus the
+// inline-suspense variant. A page's dynamic content resolves INTO one of these,
+// not into the slot, so a page frame that stopped at the slot would carry only
+// the page's `loading` fallback.
+const STREAM_CHUNK_MARKERS = ['<div hidden data-pnext-stream', '<div hidden><preact-island'];
+
+/** Index of the first streamed continuation chunk at/after `from`, or -1. */
+function streamedContinuationStart(html: string, from: number): number {
+  const cuts = STREAM_CHUNK_MARKERS.map(marker => html.indexOf(marker, from)).filter(
+    index => index !== -1,
+  );
+  return cuts.length > 0 ? Math.min(...cuts) : -1;
+}
+
+/**
+ * The PAGE frame of a rendered document: the page slot - its markers plus the page's own markup -
+ * followed by the document's streamed continuation chunks, with the whole layout chain and the document
+ * shell cut away. Null when the document has no page slot.
+ *
+ * The inverse of `stripPageSlotContent`, and what the `/_page` segment request serves: the response must
+ * not carry the layout's markup (a navigation that already renders that layout rejects it), while
+ * carrying everything needed to resolve the page's own boundaries. The frame is self-identifying: its
+ * page slot starts at offset 0, which is what `composeSegmentFrames` keys on.
+ */
+export function pageSlotFrame(html: string): string | null {
+  const range = pageSlotRange(html);
+  if (!range) return null;
+  const slot = html.slice(range.start, range.end);
+  const chunks = streamedContinuationStart(html, range.end);
+  if (chunks === -1) return slot;
+  const bodyEnd = html.lastIndexOf('</body>');
+  return slot + html.slice(chunks, bodyEnd > chunks ? bodyEnd : html.length);
+}
+
+/**
+ * A LAYOUT frame with the streamed continuation chunks of the render it came from cut away.
+ *
+ * Every layout frame is derived from a document that also rendered a PAGE, and that page's dynamic content
+ * resolves into the chunks near the end of the document, not into the slot. Splicing a FRESH page frame
+ * into a frame that still carries the old page's chunks would graft the stale content over the new page's
+ * boundaries. Scanned on the frame, whose slot is already empty, so the first marker found is always a
+ * continuation chunk.
+ */
+export function stripStreamedContinuation(html: string): string {
+  // Each chunk is removed SURGICALLY (its balanced div plus the promotion
+  // script that follows it), never "from the first marker to </body>": a layout
+  // whose own content streams emits chunks BEFORE the page slot, and cutting to
+  // the end of the body would take the slot with them, leaving a frame nothing
+  // can be composed into.
+  let result = html;
+  let from = 0;
+  for (;;) {
+    const start = streamedContinuationStart(result, from);
+    if (start === -1) return result;
+    const end = chunkEnd(result, start);
+    if (end === -1) return result;
+    // A chunk that CONTAINS the page slot is the frame's own slot carrier (the
+    // page's markup streams in below the layout), not stale continuation —
+    // dropping it would leave nothing to compose a fresh page into.
+    const slot = pageSlotRange(result);
+    if (slot && slot.start > start && slot.end <= end) {
+      from = end;
+      continue;
+    }
+    result = result.slice(0, start) + result.slice(end);
+  }
+}
+
+/** Index just past a continuation chunk (its balanced div + promotion script). */
+function chunkEnd(html: string, start: number): number {
+  const tag = /<div\b|<\/div>/g;
+  tag.lastIndex = start + '<div'.length;
+  let depth = 1;
+  let divEnd = -1;
+  for (let match = tag.exec(html); match; match = tag.exec(html)) {
+    depth += match[0] === '</div>' ? -1 : 1;
+    if (depth > 0) continue;
+    divEnd = match.index + match[0].length;
+    break;
+  }
+  if (divEnd === -1) return -1;
+  const rest = html.slice(divEnd);
+  const script = /^\s*<script\b[^>]*>[\s\S]*?<\/script>/.exec(rest);
+  return script ? divEnd + script[0].length : divEnd;
+}
+
+/**
+ * Compose a cached LAYOUT frame with a PAGE frame: the layout document with the page frame's slot children
+ * spliced into its (empty) slot.
+ *
+ * When `pageHtml` is a `/_page` FRAME - its slot starts at offset 0 - rather than a whole document,
+ * whatever follows the slot is the page's streamed continuation and is appended before the layout's
+ * `</body>`, so the composed document resolves the page's boundaries exactly as the whole-document
+ * response would have. Null when either side has no page slot: the frames cannot be proven to line up,
+ * and painting a half-composed document is worse than fetching.
+ */
+export function composeSegmentFrames(layoutHtml: string, pageHtml: string): string | null {
+  const range = pageSlotRange(layoutHtml);
+  if (!range) return null;
+  const pageRange = pageSlotRange(pageHtml);
+  if (!pageRange) return null;
+  const page = pageHtml.slice(pageRange.childrenStart, pageRange.childrenEnd);
+  const composed =
+    layoutHtml.slice(0, range.childrenStart) + page + layoutHtml.slice(range.childrenEnd);
+  // A whole document's tail is its own layout/scripts, already present in the
+  // layout frame; only a frame's tail is continuation markup to carry over.
+  const tail = pageRange.start === 0 ? pageHtml.slice(pageRange.end) : '';
+  if (!tail) return composed;
+  const insertAt = composed.lastIndexOf('</body>');
+  return insertAt === -1
+    ? composed + tail
+    : composed.slice(0, insertAt) + tail + composed.slice(insertAt);
+}