@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

package/src/react-canary.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="react/canary" />
+/// <reference types="react-dom/canary" />

package/src/routing/codegen-write.ts

@@ -60,6 +60,8 @@ const TIMBER_ENV_DTS = [
   '/* eslint-disable @typescript-eslint/triple-slash-reference */',
   '/// <reference path=".timber/timber-routes.d.ts" />',
   '/// <reference types="vite/client" />',
+  '/// <reference types="react/canary" />',
+  '/// <reference types="react-dom/canary" />',
   '',
 ].join('\n');
 

package/src/routing/interception-overlap.ts

@@ -0,0 +1,141 @@
+/**
+ * Pattern intersection for intercepted URL patterns.
+ *
+ * Checks whether two intercepted URL patterns can both match the same concrete
+ * URL. Used by the cross-mode claim check (TIM-1319) to detect when a
+ * children-path interceptor and a slot interceptor from the same owner overlap.
+ *
+ * This is not the order-dependence oracle (`findOrderDependentCollision`) the
+ * within-mode collision checks use. `findInterceptionMatch` picks the mode by
+ * first-match on `pathnameMatchesPattern`, which has no priority tiers, so a
+ * static `/feed/foo` and a dynamic `/feed/[id]` both match `/feed/foo` even
+ * though `matchUrlParts` would resolve the static deterministically. The
+ * intersection test catches that: it walks both patterns segment by segment and
+ * asks whether any value satisfies both.
+ *
+ * This is not a model of `matchNode` precedence — that decides *which*
+ * candidate wins when several match one URL. This decides the prior question:
+ * *do* they both match one URL at all? The two questions are independent, and
+ * conflating them is what caused TIM-1308's five-round drift.
+ */
+
+import { classifyUrlSegment } from './segment-classify.ts';
+
+/**
+ * Check whether two intercepted URL patterns can both match the same concrete
+ * URL. Returns a display string for the overlapping URL, or null.
+ *
+ * Walks both patterns segment by segment:
+ * - Two statics: must be identical.
+ * - Static + dynamic: static must satisfy the dynamic's affix constraints.
+ * - Two dynamics: affix constraints must be compatible.
+ * - A catch-all at either side: compatible with everything remaining.
+ *
+ * If the patterns differ in length, they can only overlap if the longer one's
+ * extra part is an optional catch-all (which also matches zero segments).
+ */
+export function interceptedPatternsOverlap(p1: string, p2: string): string | null {
+  if (p1 === p2) return p1;
+
+  const parts1 = p1 === '/' ? [] : p1.slice(1).split('/');
+  const parts2 = p2 === '/' ? [] : p2.slice(1).split('/');
+  const display: string[] = [];
+  let i = 0;
+
+  while (i < parts1.length && i < parts2.length) {
+    const seg1 = classifyUrlSegment(parts1[i]);
+    const seg2 = classifyUrlSegment(parts2[i]);
+
+    if (
+      seg1.kind === 'catch-all' ||
+      seg1.kind === 'optional-catch-all' ||
+      seg2.kind === 'catch-all' ||
+      seg2.kind === 'optional-catch-all'
+    ) {
+      display.push('<any>');
+      return '/' + display.join('/');
+    }
+
+    const part = segmentsOverlap(seg1, seg2);
+    if (part === null) return null;
+    display.push(part);
+    i++;
+  }
+
+  const remaining = i < parts1.length ? parts1 : i < parts2.length ? parts2 : null;
+  if (remaining) {
+    const next = classifyUrlSegment(remaining[i]);
+    if (next.kind !== 'optional-catch-all') return null;
+  }
+
+  return display.length === 0 ? '/' : '/' + display.join('/');
+}
+
+/**
+ * Can some concrete value satisfy both classified URL segments?
+ *
+ * An affixed dynamic (`a-[id].png`) constrains both the prefix and suffix of
+ * the value, so a static segment must satisfy those constraints and two
+ * dynamics must have compatible affixes — prefixes where one extends the other,
+ * and likewise for suffixes. Without this check, `/feed/photo.jpg` beside
+ * `/feed/asset-[id].png` would be falsely rejected.
+ */
+function segmentsOverlap(
+  seg1: ReturnType<typeof classifyUrlSegment>,
+  seg2: ReturnType<typeof classifyUrlSegment>
+): string | null {
+  if (seg1.kind === 'static' && seg2.kind === 'static') {
+    return seg1.value === seg2.value ? seg1.value : null;
+  }
+
+  if (seg1.kind === 'static' && seg2.kind === 'dynamic') {
+    return staticMatchesAffix(seg1.value, seg2) ? seg1.value : null;
+  }
+  if (seg2.kind === 'static' && seg1.kind === 'dynamic') {
+    return staticMatchesAffix(seg2.value, seg1) ? seg2.value : null;
+  }
+
+  if (seg1.kind === 'dynamic' && seg2.kind === 'dynamic') {
+    return dynamicAffixesCompatible(seg1, seg2) ? '<any>' : null;
+  }
+
+  return '<any>';
+}
+
+/**
+ * Does a static value satisfy an affixed dynamic's prefix, suffix, and
+ * non-empty capture constraints?
+ *
+ * Mirrors the check `pathnameMatchesPattern` applies: the value must start with
+ * the prefix, end with the suffix, and be strictly longer than their combined
+ * length (a capture of zero characters is not a match).
+ */
+function staticMatchesAffix(value: string, dynamic: { prefix?: string; suffix?: string }): boolean {
+  const prefix = dynamic.prefix ?? '';
+  const suffix = dynamic.suffix ?? '';
+  if (!prefix && !suffix) return true;
+  if (prefix && !value.startsWith(prefix)) return false;
+  if (suffix && !value.endsWith(suffix)) return false;
+  return value.length > prefix.length + suffix.length;
+}
+
+/**
+ * Can some value simultaneously satisfy two affixed dynamics?
+ *
+ * Two prefix constraints are compatible when one extends the other (a value
+ * starting with the longer one also starts with the shorter). Suffixes are
+ * analogous. Without affixes on either side, every value works.
+ */
+function dynamicAffixesCompatible(
+  d1: { prefix?: string; suffix?: string },
+  d2: { prefix?: string; suffix?: string }
+): boolean {
+  const p1 = d1.prefix ?? '',
+    s1 = d1.suffix ?? '';
+  const p2 = d2.prefix ?? '',
+    s2 = d2.suffix ?? '';
+
+  if (p1 && p2 && !p1.startsWith(p2) && !p2.startsWith(p1)) return false;
+  if (s1 && s2 && !s1.endsWith(s2) && !s2.endsWith(s1)) return false;
+  return true;
+}

package/src/routing/interception.ts

@@ -24,6 +24,7 @@ import { classifyUrlSegment, effectiveUrlSegment } from './segment-classify.ts';
 // — decides order-dependence with the same oracle, so the spaces cannot drift
 // on what counts as two pages answering one URL. See TIM-1308.
 import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.ts';
+import { interceptedPatternsOverlap } from './interception-overlap.ts';
 
 /** Fields shared by both interception shapes. */
 interface InterceptionRewriteBase {
@@ -256,11 +257,12 @@ export function collectInterceptionRewrites(root: SegmentNode): InterceptionRewr
  * nothing per request.
  *
  * Sorting is stable, so rewrites sharing one scope keep tree-walk order. Equal
- * scopes mean one owner, and of the three pairings that produces only one is an
- * ambiguity — a children-path interceptor beside a slot one, tracked as
- * TIM-1319. The enumeration is in design/07-routing.md §"Selection Between
- * Owners" rather than repeated here, so there is one place to correct if a
- * rewrite ever grows a field that makes two of them distinguishable.
+ * scopes mean one owner, and of the three pairings that produces only one was
+ * ambiguous — a children-path interceptor beside a slot one — and that is now
+ * rejected at build time by `assertNoCrossModeClaims` (TIM-1319). The
+ * enumeration is in design/07-routing.md §"Selection Between Owners" rather
+ * than repeated here, so there is one place to correct if a rewrite ever grows
+ * a field that makes two of them distinguishable.
  */
 function sortByScopeDepth(rewrites: InterceptionRewrite[]): InterceptionRewrite[] {
   return rewrites.sort(
@@ -595,6 +597,108 @@ function assertNoInterceptedPatternCollisions(owner: SegmentNode, ownerPath: str
   }
 }
 
+/**
+ * Reject a children-path interceptor and a slot interceptor from the same owner
+ * that claim URLs in common.
+ *
+ * Within one mode the ambiguity is either non-existent (two children-path
+ * rewrites are interchangeable, §"Selection Between Owners") or harmless (two
+ * slots on one owner both render). Across modes one is a layout swap and the
+ * other is a modal overlay, and the walk order picks the children-path shape —
+ * making the modal dead, silently and deterministically (TIM-1319).
+ *
+ * Overlap is a **pattern intersection** test: do two intercepted URL patterns
+ * share any concrete URL? This is not the same question the within-mode
+ * collision oracle answers. `findOrderDependentCollision` checks whether two
+ * candidates in one `matchUrlParts` walk produce different winners when
+ * `children` order is reversed — that is, order-dependence. A static segment
+ * always beats a dynamic one deterministically (no order-dependence), so
+ * `/feed/foo` and `/feed/[id]` pass the oracle even though
+ * `pathnameMatchesPattern` — the actual rewrite matcher — accepts both. The
+ * pattern intersection test catches that: it walks both patterns segment by
+ * segment and asks whether any value satisfies both.
+ *
+ * The check collects intercepted patterns from children-path interceptors and
+ * from each slot's interceptors independently. Slots are checked one at a time
+ * so two slot interceptors from *different* slots claiming one URL — the legal
+ * "two slots on one owner" case — are never compared.
+ */
+function assertNoCrossModeClaims(node: SegmentNode, ownerPath: string): void {
+  // Collect children-path interceptor patterns
+  const childrenLeaves: Array<{ pattern: string; filePath: string }> = [];
+  for (const child of node.children) {
+    if (
+      child.segmentType !== 'intercepting' ||
+      !child.interceptionMarker ||
+      !child.interceptedSegmentName
+    )
+      continue;
+    const urlBase = computeInterceptedUrlBase(
+      node.urlPath,
+      child.interceptionMarker,
+      child.interceptedSegmentName
+    );
+    walkInterceptedLeaves(child, urlBase, [child], (page, leaf) => {
+      childrenLeaves.push({ pattern: leaf.interceptedPattern, filePath: page.filePath });
+    });
+  }
+
+  if (childrenLeaves.length === 0) return;
+
+  const owner = ownerPath || '(app root)';
+
+  for (const slot of Object.values(node.slots)) {
+    const slotLeaves: Array<{ pattern: string; filePath: string }> = [];
+    for (const child of slot.children) {
+      if (
+        child.segmentType !== 'intercepting' ||
+        !child.interceptionMarker ||
+        !child.interceptedSegmentName
+      )
+        continue;
+      const urlBase = computeInterceptedUrlBase(
+        node.urlPath,
+        child.interceptionMarker,
+        child.interceptedSegmentName
+      );
+      walkInterceptedLeaves(child, urlBase, [child], (page, leaf) => {
+        slotLeaves.push({ pattern: leaf.interceptedPattern, filePath: page.filePath });
+      });
+    }
+
+    for (const cl of childrenLeaves) {
+      for (const sl of slotLeaves) {
+        const overlap = interceptedPatternsOverlap(cl.pattern, sl.pattern);
+        if (overlap !== null) {
+          throwCrossModeClaim(owner, overlap, cl.filePath, sl.filePath);
+        }
+      }
+    }
+  }
+}
+
+function throwCrossModeClaim(
+  owner: string,
+  url: string,
+  childFile: string,
+  slotFile: string
+): never {
+  throw new Error(
+    `Build error: a children-path interception and a slot interception both ` +
+      `claim the same URL.\n` +
+      `  Owner:    app/${owner}\n` +
+      `  URL:      ${url}\n` +
+      `  Children: ${childFile}\n` +
+      `  Slot:     ${slotFile}\n` +
+      `The children-path interceptor replaces the owner's children (layout swap) ` +
+      `while the slot interceptor renders inside a parallel slot (modal overlay). ` +
+      `Both apply from the same scope at the same URL, and which one wins would ` +
+      `depend on internal walk order rather than an explicit rule.\n` +
+      `Remove one of the two, or move them to different scopes.\n` +
+      `See design/07-routing.md §"Selection Between Owners".`
+  );
+}
+
 /**
  * The URL-matching identity of an intercepting node, as a node.
  *
@@ -792,6 +896,15 @@ function walkForPlacement(node: SegmentNode, path: string, ctx: PlacementContext
       ancestorsBindParams: false,
     });
   }
+
+  // After both children and slots have been validated independently, check for
+  // the cross-mode ambiguity that neither space covers: a children-path
+  // interceptor and a slot interceptor from the same owner claiming one URL.
+  // Within each mode the collision is either ordered (two children-path) or
+  // harmless (two slots) — see §"Selection Between Owners" — but across modes
+  // one is an overlay and the other a layout swap, and the walk order picks the
+  // children-path shape silently (TIM-1319).
+  assertNoCrossModeClaims(node, path);
 }
 
 /**

package/src/rsc-runtime/ssr.ts

@@ -53,10 +53,11 @@ try {
  * signaling the caller to use createFromReadableStream instead.
  */
 export function createFromNodeStream(
-  stream: import('node:stream').Readable
+  stream: import('node:stream').Readable,
+  options?: { nonce?: string }
 ): React.ReactNode | null {
   if (!_createFromNodeStream) return null;
-  return _createFromNodeStream(stream, createServerConsumerManifest());
+  return _createFromNodeStream(stream, createServerConsumerManifest(), options);
 }
 
 /** Whether the Node.js stream RSC decode path is available. */

package/src/server/als-registry.ts

@@ -76,6 +76,12 @@ export interface RequestContextStore {
   parsedCookies?: Map<string, string>;
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
+  /**
+   * CSP nonce, created the first time middleware reads `ctx.nonce`. Read by
+   * the renderers via `getCspNonce()` and stamped on every inline script.
+   * Absent when no middleware asked for one. See server/csp-nonce.ts.
+   */
+  cspNonce?: string;
   /**
    * Raw URLSearchParams for the current request.
    * To get typed parsed params, import a search params definition and

package/src/server/csp-nonce.ts

@@ -0,0 +1,70 @@
+/**
+ * CSP nonce — per-request, generated on demand.
+ *
+ * timber emits several inline `<script>` tags per HTML response — React's
+ * bootstrap script and Fizz runtime, the Flight init/chunk scripts, the
+ * segment-tree script, and the post-flush noindex script. Under a strict
+ * `Content-Security-Policy` (`script-src 'nonce-…' 'strict-dynamic'`) every
+ * one of them needs the request's nonce or the browser refuses to run it.
+ *
+ * The app opts in by reading `ctx.nonce` in `middleware.ts` and putting it
+ * in the CSP header it sets through `ctx.headers`. The first read generates
+ * the value and stores it on the request context; the render pipeline reads
+ * it back with `getCspNonce()` and stamps it on every inline script. A
+ * request whose middleware never reads `ctx.nonce` has no nonce, and its
+ * markup is byte-identical to a render without this feature. timber does
+ * not parse the CSP header — the app owns the policy, timber owns the
+ * markup, and `ctx.nonce` is the one value both are built from.
+ *
+ * `proxy.ts` cannot participate: it only sees the finished response from
+ * `next()`, after the markup exists.
+ *
+ * See design/13-security.md §"Content Security Policy" (TIM-1414).
+ */
+
+import { requestContextAls } from './als-registry.ts';
+
+/**
+ * Generate a CSP nonce: 128 random bits, base64. Matches CSP's
+ * `base64-value` grammar, so it is valid in the header verbatim and safe
+ * inside a double-quoted HTML attribute without escaping.
+ */
+function generateNonce(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+/**
+ * The request's CSP nonce, creating it on first call. Backs the
+ * `ctx.nonce` getter on `MiddlewareContext`. Outside a request context
+ * (tests, build-time rendering) a fresh value is returned but not
+ * retained, since there is no request for it to belong to.
+ */
+export function requestCspNonce(): string {
+  const store = requestContextAls.getStore();
+  if (!store) return generateNonce();
+  store.cspNonce ??= generateNonce();
+  return store.cspNonce;
+}
+
+/**
+ * The request's CSP nonce if middleware asked for one, else `undefined` —
+ * in which case the pipeline emits bare `<script>` tags.
+ */
+export function getCspNonce(): string | undefined {
+  return requestContextAls.getStore()?.cspNonce;
+}
+
+/**
+ * The ` nonce="…"` attribute fragment for a timber-generated `<script>` tag,
+ * or `''` when the request has no nonce. Callers interpolate it directly
+ * after the tag name: `` `<script${nonceAttr(nonce)}>` ``.
+ *
+ * The value comes from `generateNonce` and is base64, so no attribute
+ * escaping is required.
+ */
+export function nonceAttr(nonce: string | undefined): string {
+  return nonce ? ` nonce="${nonce}"` : '';
+}

package/src/server/default-status-page.ts

@@ -94,6 +94,7 @@ body {
   background: var(--bg); color: var(--fg);
   font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
   text-align: center; padding: 2rem;
+  box-sizing: border-box;
 }
 h1 { font-size: 3rem; font-weight: 600; margin: 0; letter-spacing: -0.02em; }
 p { margin: 0.5rem 0 0; color: var(--muted); font-size: 1rem; }

package/src/server/deny-renderer.ts

@@ -37,6 +37,7 @@ import type { ManifestSegmentNode } from './route-matcher.ts';
 import type { RouteMatch } from './pipeline.ts';
 import type { NavContext } from './ssr-bridge-types.ts';
 import { flightInitScript } from './flight-scripts.ts';
+import { getCspNonce } from './csp-nonce.ts';
 import type { ClientBootstrapConfig } from './html-injectors.ts';
 import type { Metadata } from './types.ts';
 import { teeWithErrorPropagation } from './stream-utils.ts';
@@ -226,15 +227,18 @@ export async function renderDenyPage(
 
   const slotParams = getSlotParamsForClient();
 
+  const denyUrl = new URL(req.url);
+  const nonce = getCspNonce();
   const navContext: NavContext = {
-    pathname: new URL(req.url).pathname,
+    pathname: denyUrl.pathname,
+    search: appVisibleSearch(denyUrl).search,
     segmentParams: match.segmentParams,
-    searchParams: Object.fromEntries(appVisibleSearch(new URL(req.url)).params),
     slotParams,
     statusCode: deny.status,
     responseHeaders,
-    headHtml: flightInitScript(),
+    headHtml: flightInitScript(nonce),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+    nonce,
     rscStream: inlineStream,
     signal: req.signal,
     cookies: getCookiesForSsr(),

package/src/server/flight-scripts.ts

@@ -9,9 +9,14 @@
  * 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 ────────────────────────────────────────────────────────
 
 /**
@@ -43,8 +48,8 @@ const FLIGHT_VAR = 'self.__timber_f';
  * Also emits the bootstrap signal [0] which tells the client that
  * Flight data is active for this page.
  */
-export function flightInitScript(): string {
-  return `<script>${FLIGHT_VAR}=[${htmlEscapeJsonString(JSON.stringify([0]))}]</script>`;
+export function flightInitScript(nonce?: string): string {
+  return `<script${nonceAttr(nonce)}>${FLIGHT_VAR}=[${htmlEscapeJsonString(JSON.stringify([0]))}]</script>`;
 }
 
 /**
@@ -56,7 +61,7 @@ export function flightInitScript(): string {
  * 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): string {
+export function flightChunkScript(data: string, nonce?: string): string {
   const escaped = htmlEscapeJsonString(JSON.stringify([1, data]));
-  return `<script>(${FLIGHT_VAR}=${FLIGHT_VAR}||[]).push(${escaped})</script>`;
+  return `<script${nonceAttr(nonce)}>(${FLIGHT_VAR}=${FLIGHT_VAR}||[]).push(${escaped})</script>`;
 }

package/src/server/html-injector-core.ts

@@ -68,7 +68,11 @@ export class BufferAggregator {
   private chunks: Uint8Array[] = [];
   private byteLength = 0;
 
-  constructor(private readonly maxBufferByteLength: number = Infinity) {}
+  private readonly maxBufferByteLength: number;
+
+  constructor(maxBufferByteLength: number = Infinity) {
+    this.maxBufferByteLength = maxBufferByteLength;
+  }
 
   /**
    * Append a chunk. Returns `true` if the caller should flush synchronously
@@ -350,6 +354,21 @@ export function injectorFlush(state: InjectorState): Uint8Array | null {
  * **No polling.** See design/02-rendering-pipeline.md §"No Polling".
  * **Always timeout-guarded reads.** Per design/02 §"Streaming Constraints".
  */
+export interface FlightInjectorOptions {
+  /**
+   * Timeout in milliseconds for individual RSC stream reads. If a single
+   * `rscReader.read()` call does not resolve within this duration, the
+   * read is aborted and the stream errors with a `RenderTimeoutError`.
+   * Default: 30000 (30s). `0` ("disabled") still enforces a 120s ceiling
+   * so a stalled RSC stream can never hang the connection forever.
+   */
+  renderTimeoutMs?: number;
+  /** Signal that fires when an unhandled RSC error is detected. */
+  errorSignal?: AbortSignal;
+  /** Request CSP nonce, stamped on every emitted `<script>` (TIM-1414). */
+  nonce?: string;
+}
+
 export class FlightInjectorCore {
   readonly machine: Machine<FlightInjectionState, FlightInjectionEvent>;
   /** Script chunks waiting to be drained between HTML chunks. */
@@ -358,18 +377,16 @@ export class FlightInjectorCore {
   private readonly rscReader: ReadableStreamDefaultReader<Uint8Array>;
   private readonly timeoutMs: number;
   private readonly errorSignal?: AbortSignal;
+  private readonly nonce?: string;
   private readonly decoder = new TextDecoder('utf-8', { fatal: true });
   private pullPromise: Promise<void> | null = null;
   private _aborted = false;
 
-  constructor(
-    rscStream: ReadableStream<Uint8Array>,
-    renderTimeoutMs?: number,
-    errorSignal?: AbortSignal
-  ) {
+  constructor(rscStream: ReadableStream<Uint8Array>, options: FlightInjectorOptions = {}) {
     this.rscReader = rscStream.getReader();
-    this.timeoutMs = (renderTimeoutMs ?? 30_000) || 120_000;
-    this.errorSignal = errorSignal;
+    this.timeoutMs = (options.renderTimeoutMs ?? 30_000) || 120_000;
+    this.errorSignal = options.errorSignal;
+    this.nonce = options.nonce;
     this.machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
       initial: { phase: 'init' },
       transitions: flightInjectionTransitions,
@@ -470,7 +487,7 @@ export class FlightInjectorCore {
         }
 
         const decoded = this.decoder.decode(value, { stream: true });
-        this.pending.push(encoder.encode(flightChunkScript(decoded)));
+        this.pending.push(encoder.encode(flightChunkScript(decoded, this.nonce)));
 
         // Yield between reads so HTML chunks get priority — but only while
         // HTML is still streaming. Once flush() fires (HTML_DONE), drain

package/src/server/html-injectors.ts

@@ -21,6 +21,7 @@
 import {
   BufferAggregator,
   FlightInjectorCore,
+  type FlightInjectorOptions,
   createInjectorState,
   createSuffixState,
   encodeUtf8,
@@ -201,7 +202,8 @@ export function injectScripts(
  */
 export function createInlinedRscStream(
   rscStream: ReadableStream<Uint8Array>,
-  renderTimeoutMs?: number
+  renderTimeoutMs?: number,
+  nonce?: string
 ): ReadableStream<Uint8Array> {
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
@@ -224,7 +226,7 @@ export function createInlinedRscStream(
         }
         if (value) {
           const decoded = decoder.decode(value, { stream: true });
-          controller.enqueue(encodeUtf8(flightChunkScript(decoded)));
+          controller.enqueue(encodeUtf8(flightChunkScript(decoded, nonce)));
         }
       } catch (error) {
         if (error instanceof RenderTimeoutError) {
@@ -257,10 +259,9 @@ export function createInlinedRscStream(
  */
 function createFlightInjectionTransform(
   rscStream: ReadableStream<Uint8Array>,
-  renderTimeoutMs?: number,
-  errorSignal?: AbortSignal
+  options?: FlightInjectorOptions
 ): TransformStream<Uint8Array, Uint8Array> {
-  const core = new FlightInjectorCore(rscStream, renderTimeoutMs, errorSignal);
+  const core = new FlightInjectorCore(rscStream, options);
   // Controller reference — set on first transform() call so the pull
   // loop can drain pending scripts between HTML chunks (after yielding).
   let _controller: TransformStreamDefaultController<Uint8Array> | null = null;
@@ -340,8 +341,7 @@ function createFlightInjectionTransform(
 export function injectRscPayload(
   htmlStream: ReadableStream<Uint8Array>,
   rscStream: ReadableStream<Uint8Array> | undefined,
-  renderTimeoutMs?: number,
-  errorSignal?: AbortSignal
+  options?: FlightInjectorOptions
 ): ReadableStream<Uint8Array> {
   if (!rscStream) return htmlStream;
   // Pass the raw RSC stream directly to the flight injection transform.
@@ -349,7 +349,7 @@ export function injectRscPayload(
   // <script> via flightChunkScript itself — do NOT pre-wrap with
   // createInlinedRscStream here, that would double-wrap.
   return htmlStream
-    .pipeThrough(createFlightInjectionTransform(rscStream, renderTimeoutMs, errorSignal))
+    .pipeThrough(createFlightInjectionTransform(rscStream, options))
     .pipeThrough(createMoveSuffixStream());
 }
 

package/src/server/metadata-render.ts

@@ -78,14 +78,36 @@ export function renderMetadataToElements(metadata: Metadata): HeadElement[] {
     }
   }
 
-  // Open Graph
+  // Open Graph — inherit title/description from top-level when not set explicitly
   if (metadata.openGraph) {
-    renderOpenGraph(metadata.openGraph, elements);
+    const og = { ...metadata.openGraph };
+    if (og.title === undefined && typeof metadata.title === 'string') {
+      og.title = metadata.title;
+    }
+    if (og.description === undefined && metadata.description) {
+      og.description = metadata.description;
+    }
+    renderOpenGraph(og, elements);
   }
 
-  // Twitter
+  // Twitter — inherit title/description from openGraph or top-level when not set
   if (metadata.twitter) {
-    renderTwitter(metadata.twitter, elements);
+    const tw = { ...metadata.twitter };
+    if (tw.title === undefined) {
+      tw.title =
+        metadata.openGraph?.title !== undefined
+          ? metadata.openGraph.title
+          : typeof metadata.title === 'string'
+            ? metadata.title
+            : undefined;
+    }
+    if (tw.description === undefined) {
+      tw.description =
+        metadata.openGraph?.description !== undefined
+          ? metadata.openGraph.description
+          : metadata.description;
+    }
+    renderTwitter(tw, elements);
   }
 
   // Icons