@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/src/server/error-boundary-wrapper.ts

@@ -1,67 +1,204 @@
 /**
- * Error boundary wrapper — wraps a React element in error boundaries from a route segment.
+ * Error boundary wrapper — wraps a React element in the error boundaries
+ * declared by a route segment (`{status}.tsx`, `4xx.tsx`/`5xx.tsx`, `error.tsx`).
  *
- * Extracted to allow reuse by both rsc-entry.ts and route-element-builder.ts.
- * See design/10-error-handling.md.
+ * This is the single implementation of that walk. It is driven by both
+ * construction sites:
+ *
+ *   - `route-element-builder.ts` / `slot-resolver.ts` — the request-time
+ *     renderer, walking the runtime manifest (`SegmentNode<ManifestFile>`).
+ *
+ * `errorBoundaryComponent` is injected rather than imported: `TimberErrorBoundary`
+ * is a `'use client'` module, and importing it here would pull client code into
+ * every consumer. `tests/use-client-pipeline.test.ts` walks the import graph
+ * from this file to enforce that no `client/` module is reachable at any depth.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
  */
 
-import { TimberErrorBoundary } from '#/client/error-boundary.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
+import type { ReactNode } from 'react';
+import type { SegmentNode } from '../routing/types.ts';
+import { isValidElementType, type LoadedComponent } from './utils/element-type.ts';
+import { isMdxFilePath } from './utils/mdx-file.ts';
+
+/** The minimum a route file must carry for the walk: a path to classify as MDX. */
+interface BoundaryFile {
+  filePath: string;
+}
 
 /**
- * Wrap an element in error boundaries defined by a route segment.
+ * Framework-injected error boundary wrapper.
+ * Wraps content with status-code error boundary handling.
  *
- * Processing order (innermost to outermost):
- * 1. Specific status files (e.g., 404.tsx, 500.tsx) — highest priority at runtime
- * 2. Category catch-alls (4xx.tsx, 5xx.tsx)
- * 3. error.tsx — catches anything not matched by status files
+ * Field types must agree with `TimberErrorBoundaryProps` in
+ * `client/error-boundary.tsx`. The two are kept structurally compatible by
+ * convention rather than by direct type import — this is the server-side
+ * construction site and may not import types from a 'use client' module.
  */
-export async function wrapSegmentWithErrorBoundaries(
-  segment: ManifestSegmentNode,
-  element: React.ReactElement,
-  h: (...args: unknown[]) => React.ReactElement
-): Promise<React.ReactElement> {
-  // Specific status files (innermost — highest priority at runtime)
+export interface ErrorBoundaryProps {
+  /** The component to render when an error is caught (TSX status files). */
+  fallbackComponent?: LoadedComponent;
+  /** Pre-rendered fallback element (MDX status files — see TIM-503). */
+  fallbackElement?: ReactNode;
+  /** Status code filter: 400 = any 4xx, 500 = any 5xx, specific number = exact match. */
+  status?: number;
+  /**
+   * Segment key of the segment that declared this boundary. An in-tree deny
+   * catch site that matched a file it may not render in place re-throws with
+   * that file's owning key on the signal; boundaries whose key differs
+   * decline, so the deny page lands at its owner rather than at the first
+   * boundary the throw happens to pass. Unset for slot boundaries and for
+   * construction sites with no deny chains — an unkeyed boundary declines
+   * every owner-addressed deny. See TIM-1356.
+   */
+  segmentKey?: string;
+  /**
+   * Catch denies only; re-throw every other error. Set on the copy of a
+   * segment's boundaries that sits outside its layout, which exists to give a
+   * deny thrown from the layout's own chrome a catcher at the right position
+   * without changing where a 5xx from that chrome goes. See TIM-1450.
+   */
+  denyOnly?: boolean;
+  /**
+   * The boundary belongs to a parallel slot. A slot degrading is the page
+   * staying: its status pages never set the document status and never tell
+   * the segment cache the main route's chain is gone. Set on every boundary
+   * a slot's files declare, not only the catch-all outside them — the
+   * identity is the slot's, not the file's (codex on #1138).
+   */
+  isSlotBoundary?: boolean;
+  children: ReactNode;
+}
+
+/** How to load a route file's module. Only `default` is read. */
+type BoundaryModuleLoader<TFile> = (
+  file: TFile
+) => { default?: unknown } | Promise<{ default?: unknown }>;
+
+/** Everything the walk needs from its host environment. */
+export interface ErrorBoundaryWrapConfig<TFile, TElement> {
+  /** `React.createElement` or an equivalent element factory. */
+  createElement: (type: unknown, props: object) => TElement;
+  /** Loads a route file's module. Failures skip the boundary — see below. */
+  loadModule: BoundaryModuleLoader<TFile>;
+  /**
+   * The error boundary component to instantiate (`TimberErrorBoundary`, or a
+   * host-specific stand-in). Injected — see the module docstring.
+   */
+  errorBoundaryComponent: unknown;
+  /** Segment key stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+  segmentKey?: string;
+  /** Stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+  denyOnly?: boolean;
+  /** Stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+  isSlotBoundary?: boolean;
+}
+
+/**
+ * Load a status/error file's component, or `null` if the boundary should be skipped.
+ *
+ * Two ways to get `null`, both deliberate:
+ *   - the module fails to load (syntax error in the error page) — building an
+ *     error boundary must not itself throw, so the boundary is skipped (TIM-584);
+ *   - the default export is not a valid React component type, which would
+ *     otherwise crash inside `createElement`.
+ */
+async function loadBoundaryComponent<TFile>(
+  file: TFile,
+  loadModule: BoundaryModuleLoader<TFile>
+): Promise<LoadedComponent | null> {
+  let mod: { default?: unknown };
+  try {
+    mod = await loadModule(file);
+  } catch {
+    return null;
+  }
+  return isValidElementType(mod?.default) ? mod.default : null;
+}
+
+/**
+ * Wrap `element` in one error boundary rendering `Component` on failure.
+ *
+ * MDX status files are server components and cannot be passed as function
+ * props to `TimberErrorBoundary` (a 'use client' component). They are
+ * pre-rendered as elements and passed as `fallbackElement` instead. See TIM-503.
+ *
+ * @param status      boundary status filter — omitted entirely for `error.tsx`
+ * @param fallbackProps props handed to an MDX fallback when it is pre-rendered
+ */
+function wrapInBoundary<TFile extends BoundaryFile, TElement extends ReactNode>(
+  element: TElement,
+  Component: LoadedComponent,
+  file: TFile,
+  status: number | undefined,
+  fallbackProps: object,
+  config: ErrorBoundaryWrapConfig<TFile, TElement>
+): TElement {
+  const props: ErrorBoundaryProps = isMdxFilePath(file.filePath)
+    ? { fallbackElement: config.createElement(Component, fallbackProps), children: element }
+    : { fallbackComponent: Component, children: element };
+  if (status !== undefined) props.status = status;
+  if (config.segmentKey !== undefined) props.segmentKey = config.segmentKey;
+  if (config.denyOnly) props.denyOnly = true;
+  if (config.isSlotBoundary) props.isSlotBoundary = true;
+  return config.createElement(config.errorBoundaryComponent, props);
+}
+
+/**
+ * Wrap an element in the error boundaries declared by a route segment.
+ *
+ * Wrapping is applied inside-out — the last wrap produces the outermost
+ * boundary — so the processing order below is innermost to outermost:
+ *
+ * 1. Specific status files (e.g. `404.tsx`, `503.tsx`) — highest priority at runtime
+ * 2. Category catch-alls (`4xx.tsx`, `5xx.tsx`)
+ * 3. `error.tsx` — catches anything not matched by a status file
+ *
+ * The order is load-bearing: it decides which boundary catches a given throw.
+ *
+ * See design/10-error-handling.md §"Format-Aware Fallback Chains".
+ */
+export async function wrapSegmentWithErrorBoundaries<
+  TFile extends BoundaryFile,
+  TElement extends ReactNode,
+>(
+  segment: SegmentNode<TFile>,
+  element: TElement,
+  config: ErrorBoundaryWrapConfig<TFile, TElement>
+): Promise<TElement> {
+  const { loadModule } = config;
+
   if (segment.statusFiles) {
+    // Specific status files (innermost — highest priority at runtime)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
-      if (key !== '4xx' && key !== '5xx') {
-        const status = parseInt(key, 10);
-        if (!isNaN(status)) {
-          const mod = (await file.load()) as Record<string, unknown>;
-          if (mod.default) {
-            element = h(TimberErrorBoundary, {
-              fallbackComponent: mod.default,
-              status,
-              children: element,
-            });
-          }
-        }
+      if (key === '4xx' || key === '5xx') continue;
+      const status = parseInt(key, 10);
+      if (isNaN(status)) continue;
+      const Component = await loadBoundaryComponent(file, loadModule);
+      if (Component) {
+        element = wrapInBoundary(element, Component, file, status, { status }, config);
       }
     }
 
     // Category catch-alls (4xx.tsx, 5xx.tsx)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
-      if (key === '4xx' || key === '5xx') {
-        const mod = (await file.load()) as Record<string, unknown>;
-        if (mod.default) {
-          element = h(TimberErrorBoundary, {
-            fallbackComponent: mod.default,
-            status: key === '4xx' ? 400 : 500,
-            children: element,
-          });
-        }
+      if (key !== '4xx' && key !== '5xx') continue;
+      const Component = await loadBoundaryComponent(file, loadModule);
+      if (Component) {
+        const categoryStatus = key === '4xx' ? 400 : 500;
+        element = wrapInBoundary(element, Component, file, categoryStatus, {}, config);
       }
     }
   }
 
-  // error.tsx (outermost — catches anything not matched by status files)
+  // error.tsx (outermost — catches anything not matched by status files).
+  // error.tsx/error.mdx receives { error, digest, reset } props from the
+  // boundary at catch time; MDX error files are pre-rendered without them
+  // (they're static content).
   if (segment.error) {
-    const mod = (await segment.error.load()) as Record<string, unknown>;
-    if (mod.default) {
-      element = h(TimberErrorBoundary, {
-        fallbackComponent: mod.default,
-        children: element,
-      });
+    const Component = await loadBoundaryComponent(segment.error, loadModule);
+    if (Component) {
+      element = wrapInBoundary(element, Component, segment.error, undefined, {}, config);
     }
   }
 

package/src/server/error-response-headers.ts

@@ -0,0 +1,18 @@
+import { preventResponseCaching } from './response-cache-policy.ts';
+
+/** Preserve request-wide metadata when replacing a failed response body. */
+export function errorResponseHeaders(responseHeaders?: Headers): Headers {
+  const headers = new Headers(responseHeaders);
+  // These describe the abandoned body, not the replacement empty/JSON body.
+  headers.delete('Content-Length');
+  headers.delete('Content-Encoding');
+  headers.delete('Transfer-Encoding');
+  // A transient failure must not inherit the success page's cache lifetime
+  // or validators, including CDN overrides of Cache-Control.
+  preventResponseCaching(headers);
+  headers.delete('ETag');
+  headers.delete('Last-Modified');
+  headers.delete('Expires');
+  headers.delete('Age');
+  return headers;
+}

package/src/server/fallback-error.ts

@@ -10,10 +10,15 @@
  * exposed to the client (design/13-security.md principle 4).
  */
 
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
+import type { RouteMatch } from './pipeline.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { ClientBootstrapConfig } from './html-injectors.ts';
+import type { LayoutEntry } from './deny-renderer.ts';
+import type { GlobalErrorFile } from './rsc-entry/error-renderer.ts';
+import { swallow } from './logger.ts';
+import { logRenderError } from './logger.ts';
+import { loadModule } from './safe-load.ts';
+import { sourceMapError } from './dev-source-map.ts';
 
 /**
  * Render a fallback error page when the render pipeline throws.
@@ -27,25 +32,43 @@ export async function renderFallbackError(
   responseHeaders: Headers,
   isDev: boolean,
   rootSegment: ManifestSegmentNode,
-  clientBootstrap: ClientBootstrapConfig
+  clientBootstrap: ClientBootstrapConfig,
+  globalError?: GlobalErrorFile,
+  projectRoot?: string,
+  hmrOptions?: import('../dev-tools/dev-page-shell.ts').DevErrorHmrOptions
 ): Promise<Response> {
+  // Source-map the error's stack trace in dev mode so the error page
+  // shows original source positions. See TIM-811.
+  sourceMapError(error);
+
   if (isDev) {
-    return renderDevErrorPage(error);
+    return renderDevErrorPage(error, projectRoot, hmrOptions);
   }
   // Lazy import to avoid loading error-renderer in the pipeline module
-  const { renderErrorPage } = await import('#/server/rsc-entry/error-renderer.js');
+  const { renderErrorPage } = await import('./rsc-entry/error-renderer.ts');
   const segments = [rootSegment];
   const layoutComponents: LayoutEntry[] = [];
-  if (rootSegment.layout) {
-    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
-    if (mod.default) {
-      layoutComponents.push({
-        component: mod.default as (...args: unknown[]) => unknown,
-        segment: rootSegment,
-      });
+  // Wrap layout loading in try/catch — if the root layout module itself
+  // crashes (evaluation failure, syntax error, etc.), we still want to
+  // reach renderErrorPage so it can fall through to global-error.tsx
+  // (Tier 2), which renders without any layout wrapping.
+  try {
+    if (rootSegment.layout) {
+      const mod = await loadModule(rootSegment.layout);
+      if (mod.default) {
+        layoutComponents.push({
+          component: mod.default as (...args: unknown[]) => unknown,
+          segment: rootSegment,
+        });
+      }
     }
+  } catch (layoutError) {
+    // Layout failed to load — proceed without it. renderErrorPage will
+    // attempt segment-level error pages (without layout wrapping) and
+    // then fall through to global-error.tsx if those also fail.
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
   }
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
   return renderErrorPage(
     error,
     500,
@@ -54,94 +77,44 @@ export async function renderFallbackError(
     req,
     match,
     responseHeaders,
-    clientBootstrap
+    clientBootstrap,
+    globalError
   );
 }
 
 /**
- * Render a dev-mode 500 error page with error message and stack trace.
+ * Render a dev-mode 500 error page with error details, source context,
+ * classified stack trace, and copy button.
+ *
+ * Dynamically imports the shared template from `plugins/dev-error-page.ts`
+ * so it is NOT pulled into production server bundles. The Vite client script
+ * is injected so the error overlay fires when the HMR WebSocket connects.
  *
- * Returns an HTML Response that displays the error in a styled page.
- * The Vite HMR client script is included so the error overlay still fires.
+ * Dev-only — the dynamic import has zero production cost.
  */
-export function renderDevErrorPage(error: unknown): Response {
+export async function renderDevErrorPage(
+  error: unknown,
+  projectRoot?: string,
+  hmrOptions?: import('../dev-tools/dev-page-shell.ts').DevErrorHmrOptions
+): Promise<Response> {
   const err = error instanceof Error ? error : new Error(String(error));
-  const title = err.name || 'Error';
-  const message = escapeHtml(err.message);
-  const stack = err.stack ? escapeHtml(err.stack) : '';
+  const root = projectRoot ?? process.cwd();
 
-  const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>500 — ${escapeHtml(title)}</title>
-  <script type="module" src="/@vite/client"></script>
-  <style>
-    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-      background: #1a1a2e;
-      color: #e0e0e0;
-      padding: 2rem;
-      line-height: 1.6;
-    }
-    .container { max-width: 800px; margin: 0 auto; }
-    .badge {
-      display: inline-block;
-      background: #e74c3c;
-      color: white;
-      font-size: 0.75rem;
-      font-weight: 700;
-      padding: 0.2rem 0.6rem;
-      border-radius: 4px;
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
-      margin-bottom: 1rem;
-    }
-    h1 {
-      font-size: 1.5rem;
-      color: #ff6b6b;
-      margin-bottom: 0.5rem;
-      word-break: break-word;
-    }
-    .message {
-      font-size: 1.1rem;
-      color: #ccc;
-      margin-bottom: 1.5rem;
-      word-break: break-word;
-    }
-    .stack-container {
-      background: #16213e;
-      border: 1px solid #2a2a4a;
-      border-radius: 8px;
-      padding: 1rem;
-      overflow-x: auto;
-    }
-    .stack {
-      font-family: 'SF Mono', 'Fira Code', 'Fira Mono', Menlo, Consolas, monospace;
-      font-size: 0.8rem;
-      color: #a0a0c0;
-      white-space: pre-wrap;
-      word-break: break-all;
-    }
-    .hint {
-      margin-top: 1.5rem;
-      font-size: 0.85rem;
-      color: #666;
-    }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <span class="badge">500 Internal Server Error</span>
-    <h1>${escapeHtml(title)}</h1>
-    <p class="message">${message}</p>
-    ${stack ? `<div class="stack-container"><pre class="stack">${stack}</pre></div>` : ''}
-    <p class="hint">This error page is only shown in development.</p>
-  </div>
-</body>
-</html>`;
+  let html: string;
+  try {
+    // Dynamic import — keeps dev-error-page.ts and its transitive deps
+    // (dev-error-overlay.ts, @jridgewell/trace-mapping) out of production bundles.
+    const { generateDevErrorPage } = await import('../dev-tools/error-page.ts');
+    html = generateDevErrorPage(err, 'render', root, hmrOptions);
+    // Inject Vite client script so the error overlay fires when HMR connects.
+    html = html.replace(
+      '</head>',
+      '  <script type="module" src="/@vite/client"></script>\n</head>'
+    );
+  } catch (e) {
+    swallow(e, 'dev error page template failed, using minimal fallback');
+    html = minimalErrorPage(err);
+  }
 
   return new Response(html, {
     status: 500,
@@ -149,11 +122,15 @@ export function renderDevErrorPage(error: unknown): Response {
   });
 }
 
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#x27;');
+/**
+ * Minimal fallback error page — used only if the shared template fails to load.
+ */
+function minimalErrorPage(err: Error): string {
+  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>500</title>
+<script type="module" src="/@vite/client"></script></head>
+<body style="font-family:system-ui;padding:2rem;background:#1a1a2e;color:#e0e0e0">
+<h1 style="color:#ff6b6b">500 Internal Server Error</h1>
+<pre style="color:#a0a0c0;white-space:pre-wrap">${esc(err.stack ?? err.message)}</pre>
+</body></html>`;
 }

package/src/server/flight-injection-state.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared state machine types and transitions for RSC Flight injection.
+ *
+ * Both html-injectors.ts (Web Streams) and node-stream-transforms.ts
+ * (Node.js streams) implement identical state transitions — only the
+ * I/O primitives differ. This module defines the discriminated union
+ * states and the transition map once.
+ *
+ * Valid state flow:
+ *   init → streaming → flushing → done
+ *   (any) → error
+ *
+ * Suffix stripping (</body></html>) is handled by a separate
+ * createMoveSuffixStream / createNodeMoveSuffixTransform upstream
+ * in the pipeline (TIM-530). The flight injector only interleaves
+ * RSC scripts between HTML chunks — no suffix tracking needed.
+ *
+ * Design doc: 02-rendering-pipeline.md
+ */
+
+import type { TransitionMap } from '../utils/state-machine.ts';
+
+// ─── States ──────────────────────────────────────────────────────────────────
+
+/** Waiting for first HTML chunk. Pull loop not started. */
+export interface InitState {
+  phase: 'init';
+}
+
+/** HTML chunks flowing, pull loop running. */
+export interface StreamingState {
+  phase: 'streaming';
+}
+
+/** HTML stream done (flush fired). Draining remaining RSC chunks. */
+export interface FlushingState {
+  phase: 'flushing';
+}
+
+/** All streams consumed. Terminal state. */
+export interface DoneState {
+  phase: 'done';
+}
+
+/** Pull loop failed. Terminal state with captured error. */
+export interface ErrorState {
+  phase: 'error';
+  error: unknown;
+}
+
+export type FlightInjectionState =
+  | InitState
+  | StreamingState
+  | FlushingState
+  | DoneState
+  | ErrorState;
+
+// ─── Events ──────────────────────────────────────────────────────────────────
+
+/** First HTML chunk arrived — start the pull loop. */
+export interface FirstChunkEvent {
+  type: 'FIRST_CHUNK';
+}
+
+/** HTML stream finished (flush/end). */
+export interface HtmlDoneEvent {
+  type: 'HTML_DONE';
+}
+
+/** RSC pull loop completed (all chunks read or stream closed). */
+export interface PullDoneEvent {
+  type: 'PULL_DONE';
+}
+
+/** RSC pull loop encountered an error. */
+export interface PullErrorEvent {
+  type: 'PULL_ERROR';
+  error: unknown;
+}
+
+export type FlightInjectionEvent = FirstChunkEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
+
+// ─── Transitions ─────────────────────────────────────────────────────────────
+
+export const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent> =
+  {
+    init: {
+      FIRST_CHUNK: (): StreamingState => ({ phase: 'streaming' }),
+      // Edge case: HTML stream ends immediately (empty body)
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
+    },
+    streaming: {
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
+      PULL_DONE: (): StreamingState => ({ phase: 'streaming' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+    flushing: {
+      PULL_DONE: (): DoneState => ({ phase: 'done' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+  };
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Whether the HTML stream has finished (flush/end fired). */
+export function isHtmlDone(state: FlightInjectionState): boolean {
+  return state.phase === 'flushing' || state.phase === 'done';
+}
+
+/** Whether the RSC pull loop has completed. */
+export function isPullDone(state: FlightInjectionState): boolean {
+  return state.phase === 'done' || state.phase === 'error';
+}

package/src/server/flight-scripts.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared Flight data script generation.
+ *
+ * Both html-injectors.ts (Web Streams / dev) and node-stream-transforms.ts
+ * (Node streams / production) use this module to generate inline `<script>`
+ * tags for RSC Flight data injection.
+ *
+ * The init script goes in `<head>` as part of the HTML shell (guaranteed
+ * to execute before any streaming chunk scripts). Push scripts are emitted
+ * as RSC chunks arrive during streaming.
+ *
+ * Every generator takes the request's CSP nonce (from `getCspNonce()`)
+ * so the tags run under a nonce-based `script-src` (TIM-1414).
+ *
+ * See design/02-rendering-pipeline.md, LOCAL-415
+ */
+
+import { nonceAttr } from './csp-nonce.ts';
+
+// ─── JSON Escaping ────────────────────────────────────────────────────────
+
+/**
+ * Escape a JSON string for safe embedding inside an HTML `<script>` tag.
+ *
+ * Prevents XSS via `</script>` injection and handles Unicode line/paragraph
+ * separators that are valid JSON but invalid in JS string literals (pre-ES2019).
+ */
+export function htmlEscapeJsonString(str: string): string {
+  return str
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+// ─── Script Generation ────────────────────────────────────────────────────
+
+/** The global variable name used for Flight data on the client. */
+const FLIGHT_VAR = 'self.__timber_f';
+
+/**
+ * Generate the init script that creates the Flight data array.
+ *
+ * This MUST be included in `<head>` (via headHtml) so it executes before
+ * any streaming chunk scripts arrive in `<body>`. The array is created
+ * unconditionally — no `||[]` guard needed in push scripts.
+ *
+ * Also emits the bootstrap signal [0] which tells the client that
+ * Flight data is active for this page.
+ */
+export function flightInitScript(nonce?: string): string {
+  return `<script${nonceAttr(nonce)}>${FLIGHT_VAR}=[${htmlEscapeJsonString(JSON.stringify([0]))}]</script>`;
+}
+
+/**
+ * Generate a push script for a Flight data chunk.
+ *
+ * Normally the init script runs first (it's in `<head>`), so
+ * `self.__timber_f` already exists. However, shell-less status pages
+ * (e.g. standalone error pages) may have no `<head>` tag, so the init script
+ * never runs. The `||[]` guard ensures the array is created on first
+ * push if needed, preventing a TypeError. See TIM-559.
+ */
+export function flightChunkScript(data: string, nonce?: string): string {
+  const escaped = htmlEscapeJsonString(JSON.stringify([1, data]));
+  return `<script${nonceAttr(nonce)}>(${FLIGHT_VAR}=${FLIGHT_VAR}||[]).push(${escaped})</script>`;
+}