@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/server/metadata-collector.ts

@@ -0,0 +1,115 @@
+/**
+ * Render-time metadata resolution components.
+ *
+ * MetadataCollector runs below AccessGate for each segment, collecting
+ * metadata entries into a request-scoped array. MetadataHead runs at
+ * the page level, merging all collected entries and rendering Float-
+ * hoisted head elements.
+ *
+ * This structural approach replaces the eager pre-render metadata
+ * resolution: a denied segment's AccessGate prevents MetadataCollector
+ * from rendering, so metadata() never executes for denied segments.
+ * No `firstDeniedIndex` bookkeeping needed.
+ *
+ * See TIM-1363, design/16-metadata.md.
+ */
+
+import { createElement, Fragment } from 'react';
+import type { ReactNode } from 'react';
+
+import { requestContextAls } from './als-registry.js';
+import type { Metadata } from './types.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { withSpan } from './tracing.js';
+import { resolveMetadata, renderMetadataToElements, headElementsToReact } from './metadata.js';
+import type { SegmentMetadataEntry } from './metadata.js';
+import { collectMetadataRouteHeadElements } from './metadata-routes.js';
+
+// ─── Request-scoped metadata entry store ────────────────────────────────
+
+function getMetadataEntries(): SegmentMetadataEntry[] {
+  const store = requestContextAls.getStore();
+  if (!store) return [];
+  store._metadataEntries ??= [];
+  return store._metadataEntries;
+}
+
+// ─── MetadataCollector ──────────────────────────────────────────────────
+
+export interface MetadataCollectorProps {
+  metadataExport: Metadata | (() => Promise<Metadata>);
+  segmentName: string;
+  isPage: boolean;
+  onSettled?: () => void;
+  children: ReactNode;
+}
+
+/**
+ * Async server component that collects one segment's metadata during
+ * render. Placed between AccessGate and the layout/page. When
+ * AccessGate denies, this component never renders, so dynamic
+ * metadata() never executes for denied segments (TIM-1027).
+ *
+ * Static metadata objects are pushed synchronously (no side effects).
+ * Dynamic metadata functions are awaited with OTEL tracing.
+ */
+export async function MetadataCollector(props: MetadataCollectorProps): Promise<ReactNode> {
+  const { metadataExport, segmentName, isPage, onSettled, children } = props;
+
+  try {
+    let metadata: Metadata | null = null;
+    if (typeof metadataExport === 'function') {
+      metadata =
+        (await withSpan('timber.metadata', { 'timber.segment': segmentName }, () =>
+          (metadataExport as () => Promise<Metadata>)()
+        )) ?? null;
+    } else {
+      metadata = metadataExport;
+    }
+
+    if (metadata) {
+      getMetadataEntries().push({ metadata, isPage });
+    }
+
+    return children;
+  } finally {
+    onSettled?.();
+  }
+}
+
+// ─── MetadataHead ───────────────────────────────────────────────────────
+
+export interface MetadataHeadProps {
+  segments: ManifestSegmentNode[];
+  requestUrl: string;
+  metadataRouteHashes?: Record<string, string>;
+  children: ReactNode;
+}
+
+/**
+ * Server component at the page level. Reads all metadata entries
+ * collected by MetadataCollector components above it, merges them,
+ * auto-links metadata routes, and renders Float-hoisted head elements.
+ *
+ * Placed as a sibling of the page element inside a Fragment so the
+ * Float elements are always at the page segment level (re-rendered
+ * on every SPA navigation, never skipped by segment tree diffing).
+ */
+export function MetadataHead(props: MetadataHeadProps): ReactNode {
+  const { segments, requestUrl, metadataRouteHashes, children } = props;
+  const entries = getMetadataEntries();
+  const resolved = resolveMetadata(entries);
+  const headElements = renderMetadataToElements(resolved);
+
+  const autoLinked = collectMetadataRouteHeadElements(
+    segments,
+    Infinity,
+    resolved,
+    new URL(requestUrl),
+    metadataRouteHashes
+  );
+  headElements.push(...autoLinked);
+
+  const metadataElement = headElementsToReact(headElements);
+  return createElement(Fragment, null, metadataElement, children);
+}

package/src/server/param-coercion.ts

@@ -1,6 +1,6 @@
 /**
- * Segment param coercion — runs the matched route's `params.ts` codecs
- * over the raw matcher output before middleware and rendering.
+ * Segment param coercion — runs the app/schema.ts codecs over the raw
+ * matcher output before middleware and rendering.
  *
  * Lifted out of `pipeline-phases.ts` (TIM-853) so the coercer can be
  * imported directly by other entry points (the action-dispatch wrapper,
@@ -13,10 +13,11 @@
  */
 
 import type { Codec } from '../codec.js';
+import type { SegmentType } from '../routing/types.js';
+import { effectiveUrlSegment } from '../routing/segment-classify.js';
 import { toBracketKey } from '../params/resolve-schema.js';
 import type { RouteMatch } from './pipeline.js';
-import { sanitizeParamValue } from './pipeline-helpers.js';
-import { loadModule } from './safe-load.js';
+import { normalizeParamValue } from '../shared/param-value.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { isDebug } from './debug.js';
 
@@ -44,6 +45,12 @@ export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | n
  * exists, the raw value is parsed through it. If no codec exists or no
  * global codecs are registered, the raw value passes through unchanged.
  *
+ * Segments are read through `effectiveUrlSegment` because an intercepting
+ * node's own `segmentType` is `'intercepting'` and its `paramName` is unset
+ * — the param it binds lives in the intercepted name (`(.)[id]` → `[id]`).
+ * The slot resolver matches through the same helper, so the key a param is
+ * coerced under is always the key it was matched under (TIM-1281).
+ *
  * Unlike main route coercion, this does NOT throw ParamCoercionError on
  * failure — slots degrade gracefully. A failed coercion logs a warning
  * in dev mode and keeps the raw value.
@@ -51,7 +58,12 @@ export function setGlobalSchemaCodecs(codecs: Record<string, Codec<unknown>> | n
  * @internal — framework use only
  */
 export function coerceSlotParams(
-  slotChain: Array<{ segmentType: string; paramName?: string }>,
+  slotChain: Array<{
+    segmentName: string;
+    segmentType: SegmentType;
+    paramName?: string;
+    interceptedSegmentName?: string;
+  }>,
   rawParams: Record<string, string | string[]>
 ): Record<string, string | string[]> {
   const globalCodecs = _globalCodecs;
@@ -62,7 +74,8 @@ export function coerceSlotParams(
     result[key] = rawParams[key];
   }
 
-  for (const segment of slotChain) {
+  for (const node of slotChain) {
+    const segment = effectiveUrlSegment(node);
     if (!segment.paramName) continue;
     const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
     const codec = globalCodecs[bracketKey];
@@ -71,10 +84,9 @@ export function coerceSlotParams(
     const key = segment.paramName;
     if (!(key in result)) continue;
 
+    let parsed: unknown;
     try {
-      result[key] = sanitizeParamValue(codec.parse(result[key] as string | string[])) as
-        | string
-        | string[];
+      parsed = codec.parse(result[key] as string | string[]);
     } catch (err) {
       // Slot param coercion failures are non-fatal — keep the raw value.
       // The main route already validated the URL; the slot just interprets
@@ -88,7 +100,9 @@ export function coerceSlotParams(
             `  Keeping raw value.`
         );
       }
+      continue;
     }
+    result[key] = normalizeParamValue(parsed, key) as string | string[];
   }
 
   return result as Record<string, string | string[]>;
@@ -97,16 +111,24 @@ export function coerceSlotParams(
 /**
  * Run segment param coercion on the matched route's segments.
  *
- * When `globalCodecs` is provided (from app/schema.ts), uses the global
- * codec map keyed by bare param name. Otherwise falls back to loading
- * per-segment params.ts modules.
+ * Codecs come from `app/schema.ts` and nowhere else (TIM-1342 completed
+ * design/41-global-params.md migration step 9). A route with no schema, or
+ * a param the schema does not declare, keeps its raw string — which is the
+ * honest type for an uninterpreted URL segment.
  *
  * Throws ParamCoercionError if any codec fails (→ 404).
  *
  * This runs BEFORE middleware, so ctx.segmentParams is already typed.
  * See design/07-routing.md §"Where Coercion Runs"
  * See design/41-global-params.md §"Pipeline Integration"
+ *
+ * Stays `async` with nothing to await: it is injected as a
+ * `CoerceSegmentParamsFn` into the revalidation renderer and the action
+ * middleware runner, both of which await it. Narrowing the return type to
+ * `void` would break those contracts and remove a microtask boundary the
+ * pipeline's ordering has always had, for no gain.
  */
+// eslint-disable-next-line @typescript-eslint/require-await -- see above
 export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
   const globalCodecs = _globalCodecs;
   // Unconditionally install a null-prototype target so the invariant
@@ -125,7 +147,17 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
   // by bracket name (e.g. '[id]', '[...slug]') to avoid collisions between
   // distinct segment types that share a param name.
   if (globalCodecs) {
-    for (const segment of match.segments) {
+    for (const node of match.segments) {
+      // Read through `effectiveUrlSegment` for the same reason
+      // `coerceSlotParams` does: an intercepting node's own `segmentType` is
+      // 'intercepting' and its `paramName` is unset — the param it binds lives
+      // in the intercepted name (`(.)[id]` → `[id]`). Until TIM-1280 an
+      // intercepting node could only appear in a *slot* chain, so only that
+      // path needed it; a children-path interception puts one in the main
+      // chain, and reading the node directly would silently skip coercion for
+      // exactly the param the intercepting directory declares — so the swapped
+      // route and the canonical one would disagree about the param's type.
+      const segment = effectiveUrlSegment(node);
       if (!segment.paramName) continue;
       const bracketKey = toBracketKey(segment.segmentType, segment.paramName);
       const codec = globalCodecs[bracketKey];
@@ -133,8 +165,9 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
 
       const key = segment.paramName;
       if (!(key in mergeTarget)) continue;
+      let parsed: unknown;
       try {
-        mergeTarget[key] = sanitizeParamValue(codec.parse(mergeTarget[key] as string | string[]));
+        parsed = codec.parse(mergeTarget[key] as string | string[]);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (isDebug()) {
@@ -147,61 +180,10 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
         }
         throw new ParamCoercionError(message);
       }
-    }
-    return;
-  }
-
-  // Legacy path: per-segment params.ts coercion
-  for (const segment of match.segments) {
-    // Only process segments that have a params.ts convention file
-    if (!segment.params) continue;
-
-    let mod: Record<string, unknown>;
-    try {
-      mod = await loadModule(segment.params);
-    } catch (err) {
-      const message = `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`;
-      if (isDebug()) {
-        console.warn(
-          `[timber] Param coercion error: ${message}\n` +
-            `  Segment: ${segment.segmentName}\n` +
-            `  Params file: ${segment.params}`
-        );
-      }
-      throw new ParamCoercionError(message);
-    }
-
-    const segmentParamsDef = mod.segmentParams as
-      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
-      | undefined;
-
-    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
-
-    try {
-      const coerced = segmentParamsDef.parse(match.segmentParams);
-
-      // Deep-sanitize codec output: every nested plain object becomes
-      // null-prototype with dangerous keys stripped at every depth.
-      // See TIM-873, design/13-security.md
-      for (const key of Object.keys(coerced as Record<string, unknown>)) {
-        if (key !== '__proto__') {
-          mergeTarget[key] = sanitizeParamValue((coerced as Record<string, unknown>)[key]);
-        }
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (isDebug()) {
-        const rawKeys = Object.keys(match.segmentParams).join(', ');
-        console.warn(
-          `[timber] Param codec rejected values for segment "${segment.segmentName}"\n` +
-            `  Error: ${message}\n` +
-            `  Available raw params: { ${rawKeys} }\n` +
-            `  Params file: ${segment.params}\n` +
-            `  Hint: this usually means a codec threw for the raw URL value.\n` +
-            `  Check that the regex/schema accepts the actual path segment string.`
-        );
-      }
-      throw new ParamCoercionError(message);
+      // Outside the catch: a codec that rejects a URL value is a 404, a codec
+      // that returns an unrepresentable one is a bug in the app. Normalizing
+      // inside would report the second as the first.
+      mergeTarget[key] = normalizeParamValue(parsed, key);
     }
   }
 }

package/src/server/pipeline-helpers.ts

@@ -15,54 +15,10 @@ import { callOnRequestError } from './instrumentation.js';
 import { getTraceId } from './tracing.js';
 import { RedirectSignal } from './primitives.js';
 import type { ProxyConfig } from './pipeline.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
 
 // ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
 
-/**
- * Only __proto__ needs stripping — it has a language-level setter that
- * changes the prototype chain of spread copies. constructor and prototype
- * are harmless own properties on null-prototype objects.
- */
-const DANGEROUS_KEYS = new Set(['__proto__']);
-
-/**
- * Deep-walk a value returned by a segment param codec, producing a
- * sanitized copy where every plain object is null-prototype and
- * dangerous keys (__proto__, constructor, prototype) are stripped at
- * every depth.
- *
- * Non-plain objects (Date, Map, class instances, etc.) are returned
- * as-is — they cannot be poisoned by `{...x}` spread and may carry
- * author-intended prototype methods.
- *
- * Arrays are walked element-wise.
- *
- * Performance: URL params are bounded by URL length (~8 KB). Realistic
- * trees are <1 KB. The recursive walk is sub-microsecond.
- *
- * See TIM-655, TIM-855, TIM-873, design/13-security.md
- */
-export function sanitizeParamValue(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value;
-
-  if (Array.isArray(value)) {
-    return value.map(sanitizeParamValue);
-  }
-
-  // Only walk plain objects — anything with a custom prototype (Date, Map,
-  // class instances) is left untouched.
-  const proto = Object.getPrototypeOf(value);
-  if (proto !== Object.prototype && proto !== null) return value;
-
-  const out: Record<string, unknown> = Object.create(null);
-  for (const key of Object.keys(value as Record<string, unknown>)) {
-    if (!DANGEROUS_KEYS.has(key)) {
-      out[key] = sanitizeParamValue((value as Record<string, unknown>)[key]);
-    }
-  }
-  return out;
-}
-
 // ─── Proxy Resolver ────────────────────────────────────────────────────────
 
 /**
@@ -170,8 +126,7 @@ export function buildRedirectResponse(
   req: Request,
   headers: Headers
 ): Response {
-  const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-  if (isRsc) {
+  if (isRscRequest(req)) {
     headers.set('X-Timber-Redirect', signal.location);
     return new Response(null, { status: 204, headers });
   }

package/src/server/pipeline-interception.ts

@@ -10,47 +10,96 @@
  */
 
 import { classifyUrlSegment } from '../routing/segment-classify.js';
-
-/** Result of a successful interception match. */
-export interface InterceptionMatchResult {
-  /** The pathname to re-match (the source/intercepting route's parent). */
-  sourcePathname: string;
-}
-
-/**
- * Check if a pathname starts with a prefix on a segment boundary.
- *
- * Prevents /feed from matching /feed-private — the prefix must be
- * followed by '/' or be an exact match.
- */
-function hasSegmentPrefix(pathname: string, prefix: string): boolean {
-  if (prefix === '/') return true;
-  if (!pathname.startsWith(prefix)) return false;
-  return pathname.length === prefix.length || pathname[prefix.length] === '/';
-}
+import type { InterceptionRewrite } from '../routing/interception.js';
 
 /**
  * Check if an intercepting route applies for this soft navigation.
  *
- * Matches the target pathname against interception rewrites, constrained
- * by the source URL (X-Timber-URL header — where the user navigates FROM).
+ * Two conditions must hold:
+ *
+ * 1. The **target** pathname matches the rewrite's intercepted pattern.
+ * 2. The **source** route — the page the user is navigating FROM, per the
+ *    validated X-Timber-URL header — renders the segment that owns the slot
+ *    holding the intercepting page (`interceptingScope`). Only then does that
+ *    slot exist in the rendered tree, so only then can the intercepting page
+ *    render.
  *
- * Returns the source pathname to re-match if interception applies, or null.
+ * Condition 2 replaced a URL-prefix check (TIM-1279). A prefix cannot
+ * distinguish a route-group-scoped interception from a genuinely root-level
+ * one — route groups are invisible in `urlPath`, so both collapse to "/" and
+ * the guard degenerates to always-true. Tree paths carry group identity.
+ * The scope check also subsumes the old segment-boundary rule: a source route
+ * under /feed-private has no "/feed" in its chain.
+ *
+ * A third condition lives with the caller, which owns route matching, and it
+ * applies to the `'slot'` shape only: the route produced by re-matching
+ * `interceptingPrefix` must pass through the scope too. Conditions 1–2 are
+ * about the route the user is leaving; the slot has to exist in the tree that
+ * actually renders. The `'children'` shape resolves its owner from the scope
+ * directly rather than from a pathname, so it satisfies that by construction.
+ *
+ * `resolveSourceScopes` is a thunk so its inputs are only resolved when some
+ * rewrite's pattern actually matches the target — the common case is no match
+ * at all. It returns the two client-supplied answers to "what is on screen?"
+ * as **separate sets, most authoritative first**: the tree paths the client
+ * says it has mounted, then those of the route the departing URL matches. It
+ * returns null only when neither yields anything, which is not a soft
+ * navigation this can reason about.
+ *
+ * They are two sets rather than one union because ranking needs a chain
+ * (TIM-1318). Each channel describes a single rendered chain, so within one the
+ * scopes are strictly nested and the deepest is the innermost owner. Unioned
+ * they are not: once a modal is open the address bar holds the *intercepted*
+ * URL, so the second channel describes the canonical branch — possibly an
+ * exclusive route group the client never mounted — and a deeper scope from
+ * there would outrank the owner actually on screen. Trying the mounted channel
+ * to exhaustion first keeps the fallback the union was there to provide while
+ * ranking only within one chain.
+ *
+ * Returns the winning build-time rewrite, or null. Only build-time values ever
+ * reach the renderer: the client-supplied header selects a rewrite but never
+ * becomes a rendered route or pathname.
+ *
+ * The **first** matching rewrite wins, and the caller does not fall back to the
+ * next one when the winner fails to resolve. That is deliberate and pre-dates
+ * the two shapes: a rewrite that matched the target and the scope described the
+ * author's intent, and quietly rendering some other author's interception
+ * instead would be harder to explain than rendering the canonical route.
+ *
+ * "First" is meaningful because the list arrives **deepest scope first** —
+ * `collectInterceptionRewrites` sorts it at build time, so the deepest owner a
+ * single chain passes through wins and nothing here has to score (TIM-1318).
+ * Tree-walk order used to decide it, which meant renaming a route group flipped
+ * which modal opened. The precondition is a property of the manifest this reads
+ * rather than something it can re-derive, so it is asserted at its source:
+ * `tests/interception.test.ts` §"rewrite order is decided by scope depth".
  */
 export function findInterceptionMatch(
   targetPathname: string,
-  sourceUrl: string,
-  rewrites: import('../routing/interception.js').InterceptionRewrite[]
-): InterceptionMatchResult | null {
-  for (const rewrite of rewrites) {
-    // Check if the source URL starts with the intercepting prefix,
-    // enforcing segment boundary to prevent /feed matching /feed-private.
-    if (!hasSegmentPrefix(sourceUrl, rewrite.interceptingPrefix)) continue;
+  resolveSourceScopes: () => ReadonlySet<string>[] | null,
+  rewrites: InterceptionRewrite[]
+): InterceptionRewrite | null {
+  // Dynamic segments in the pattern match any single URL segment. Collected up
+  // front rather than inside the channel loop so a pattern is matched once
+  // however many channels are tried — and the common case, no rewrite matching
+  // at all, costs exactly the same scan it always did and resolves no scope.
+  const candidates = rewrites.filter((rewrite) =>
+    pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)
+  );
+  if (candidates.length === 0) return null;
+
+  // Nothing at all is known about the source tree — no scope can contain
+  // anything, so no rewrite can apply.
+  const scopes = resolveSourceScopes();
+  if (!scopes) return null;
 
-    // Check if the target URL matches the intercepted pattern.
-    // Dynamic segments in the pattern match any single URL segment.
-    if (pathnameMatchesPattern(targetPathname, rewrite.interceptedPattern)) {
-      return { sourcePathname: rewrite.interceptingPrefix };
+  // `candidates` is deepest scope first (`collectInterceptionRewrites`), so
+  // within one channel the first hit is the innermost owner that channel
+  // reports. Channels are tried in order, so a scope the client says it has
+  // mounted always beats one only the address bar implies.
+  for (const scope of scopes) {
+    for (const rewrite of candidates) {
+      if (scope.has(rewrite.interceptingScope)) return rewrite;
     }
   }
   return null;

package/src/server/pipeline-outcome.ts

@@ -26,16 +26,15 @@ import {
 import { markResponseFlushed } from './request-context.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
 import { isDebug } from './debug.js';
+import { rscErrorEnvelope } from '../shared/rsc-error-envelope.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
 import type { PipelineConfig, RouteMatch } from './pipeline.js';
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
 
 function rscErrorResponse(isRsc: boolean, status: number, headers?: Headers): Response {
   if (!isRsc) return new Response(null, { status });
-  const h = headers ?? new Headers();
-  h.set('X-Timber-Error', '1');
-  h.set('content-type', 'application/json; charset=utf-8');
-  return new Response(JSON.stringify({ error: true, status }), { status, headers: h });
+  return rscErrorEnvelope(status, headers);
 }
 
 // ─── Phase Outcome ─────────────────────────────────────────────────────────
@@ -143,7 +142,7 @@ export async function outcomeToResponse(
       // Signal the error via X-Timber-Error so the client hard-navigates
       // to the server-rendered error page instead of feeding HTML to the
       // Flight decoder (which crashes with "enqueueModel is not a function").
-      const isRsc = (ctx.req.headers.get('Accept') ?? '').includes('text/x-component');
+      const isRsc = isRscRequest(ctx.req);
 
       if (outcome.phase === 'proxy') {
         logProxyError({ error: outcome.error });