@timber-js/app 0.2.0-alpha.190 → 0.2.0-alpha.191

package/dist/shared/slot-params.d.ts

@@ -17,8 +17,9 @@
  *
  * See design/41-global-params.md §"Params in a parallel slot".
  */
+import type { CoercedParams } from './param-value.js';
 /** Slot tree path → that slot's own coerced params. */
-export type SlotParamsRecord = Record<string, Record<string, string | string[]>>;
+export type SlotParamsRecord = Record<string, CoercedParams>;
 /**
  * The params a slot sees: the main route's as a base, the slot's own on top.
  *
@@ -34,7 +35,7 @@ export type SlotParamsRecord = Record<string, Record<string, string | string[]>>
  * a function instead of `undefined` — in the one param record that was built
  * by merging. See design/13-security.md #36c.
  */
-export declare function mergeSlotParams(mainParams: Record<string, string | string[]>, slotParams: Record<string, string | string[]>): Record<string, string | string[]>;
+export declare function mergeSlotParams(mainParams: CoercedParams, slotParams: CoercedParams): CoercedParams;
 /**
  * Resolve the params for a segment path against a published slot map.
  *
@@ -47,5 +48,5 @@ export declare function mergeSlotParams(mainParams: Record<string, string | stri
  * JSON, so a segment path of `constructor` or `toString` would otherwise
  * resolve to an inherited member of `Object.prototype`.
  */
-export declare function resolveSegmentParams(mainParams: Record<string, string | string[]>, slotParams: SlotParamsRecord | null | undefined, segmentPath: string | undefined): Record<string, string | string[]>;
+export declare function resolveSegmentParams(mainParams: CoercedParams, slotParams: SlotParamsRecord | null | undefined, segmentPath: string | undefined): CoercedParams;
 //# sourceMappingURL=slot-params.d.ts.map

package/dist/shared/slot-params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slot-params.d.ts","sourceRoot":"","sources":["../../src/shared/slot-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC7C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAC5C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAEnC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EAC7C,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC/C,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAGnC"}
+{"version":3,"file":"slot-params.d.ts","sourceRoot":"","sources":["../../src/shared/slot-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,GACxB,aAAa,CAEf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC/C,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,aAAa,CAGf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.190",
+  "version": "0.2.0-alpha.191",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/params-context.ts

@@ -32,7 +32,7 @@
 
 import React, { createElement, useMemo, use } from 'react';
 import { _setCurrentParams, _setCurrentSlotParams } from './state.js';
-import { toNullProtoRecord } from '../shared/param-value.js';
+import { toNullProtoRecord, type CoercedParams } from '../shared/param-value.js';
 import { readPublishedParams, type PublishedParams } from '../shared/payload-root.js';
 import type { SlotParamsRecord } from '../shared/slot-params.js';
 
@@ -103,7 +103,7 @@ export function useParamsContext(): ParamsContextValue | null {
 // ─── Provider ────────────────────────────────────────────────────
 
 interface ParamsProviderProps {
-  params: Record<string, string | string[]>;
+  params: CoercedParams;
   slotParams: SlotParamsRecord | null;
   children?: React.ReactNode;
 }

package/src/client/ssr-data.ts

@@ -28,6 +28,7 @@ import {
   _setSsrDataProvider,
   _setCurrentSsrData,
 } from './state.js';
+import type { CoercedParams } from '../shared/param-value.js';
 import type { SlotParamsRecord } from '../shared/slot-params.js';
 
 // ─── Types ────────────────────────────────────────────────────────
@@ -40,7 +41,7 @@ export interface SsrData {
   /** The request's cookies as name→value pairs */
   cookies: Map<string, string>;
   /** The request's route params (e.g. { id: '123' }) */
-  params: Record<string, string | string[]>;
+  params: CoercedParams;
   /**
    * Per-slot params keyed by slot tree path, absent when the request rendered
    * no slot with params of its own (TIM-1285).

package/src/client/state.ts

@@ -19,6 +19,7 @@
  * §"Singleton State Registry".
  */
 
+import type { CoercedParams } from '../shared/param-value.js';
 import type { SlotParamsRecord } from '../shared/slot-params.js';
 import type { RouterInstance } from './router-types.js';
 import type { SsrData } from './ssr-data.js';
@@ -54,9 +55,9 @@ export function _setCurrentSsrData(data: SsrData | undefined): void {
 // ─── Route Params (from use-segment-params.ts) ──────────────────────────────────────
 
 /** Current route params snapshot — replaced (not mutated) on each navigation. */
-export let currentParams: Record<string, string | string[]> = {};
+export let currentParams: CoercedParams = {};
 
-export function _setCurrentParams(params: Record<string, string | string[]>): void {
+export function _setCurrentParams(params: CoercedParams): void {
   currentParams = params;
 }
 

package/src/client/use-segment-params.ts

@@ -30,6 +30,7 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
+import type { CoercedParams } from '../shared/param-value.js';
 import type { Routes } from '../index.js';
 import { getSsrData } from './ssr-data.js';
 import {
@@ -61,7 +62,7 @@ export function subscribe(callback: () => void): () => void {
  * Get the current params snapshot (module-level fallback).
  * Used by tests and by the hook when called outside a React component.
  */
-export function getSnapshot(): Record<string, string | string[]> {
+export function getSnapshot(): CoercedParams {
   return currentParams;
 }
 
@@ -84,7 +85,7 @@ export function getSnapshot(): Record<string, string | string[]> {
  * During SSR, params are also available via getSsrData().params
  * (ALS-backed).
  */
-export function setCurrentParams(params: Record<string, string | string[]>): void {
+export function setCurrentParams(params: CoercedParams): void {
   _setCurrentParams(params);
 }
 
@@ -140,9 +141,9 @@ export function notifyParamsListeners(): void {
  */
 export function useSegmentParams<R extends keyof Routes>(
   segmentPath: R
-): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;
-export function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;
-export function useSegmentParams(segmentPath?: string): Record<string, string | string[]> {
+): Routes[R] extends { segmentParams: infer P } ? P : CoercedParams;
+export function useSegmentParams(segmentPath?: string): CoercedParams;
+export function useSegmentParams(segmentPath?: string): CoercedParams {
   // Try the client-owned provider first. It sits above everything a navigation
   // renders, so any component on the page — initial document, full navigation,
   // or a layout the server skipped — has one above it. Absent during SSR,

package/src/routing/segment-keys.ts

@@ -22,6 +22,9 @@
  * `ManifestSegmentNode` (request time) — keys depend only on the
  * URL path and the segment classification, never on file payloads.
  */
+
+import type { CoercedParams } from '../shared/param-value.js';
+
 export interface SegmentKeyInput {
   urlPath: string;
   segmentName?: string;
@@ -170,14 +173,14 @@ export function computeSlotContentKey(
   slotKey: string,
   ownerParts: string[],
   entryFile: string | null,
-  slotParams: Record<string, string | string[]>
+  slotParams: CoercedParams
 ): string {
   const owner = ownerParts.join('/');
   const entry = entryFile ?? '\x01';
   const paramKeys = Object.keys(slotParams).sort();
   const paramParts = paramKeys.map((k) => {
     const v = slotParams[k];
-    return Array.isArray(v) ? `${k}=${v.join('\x02')}` : `${k}=${v}`;
+    return Array.isArray(v) ? `${k}=${v.map(String).join('\x02')}` : `${k}=${String(v)}`;
   });
   return [slotKey, owner, entry, ...paramParts].join('\0');
 }

package/src/server/action-handler.ts

@@ -21,6 +21,7 @@ import {
 } from '../rsc-runtime/rsc.js';
 
 import { validateCsrf, type CsrfConfig } from './csrf.js';
+import { DenySignal, RedirectSignal } from './primitives.js';
 import { executeAction, type RevalidateRenderer } from './actions.js';
 import { runWithRequestContext, setMutableCookieContext } from './request-context.js';
 import { getSetCookieHeaders, getCookiesForSsr } from './cookie-context.js';
@@ -36,6 +37,7 @@ import {
 import type { FormFlashData } from './form-flash.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { logActionError } from './logger.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
 import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
@@ -287,25 +289,107 @@ async function handleRscAction(
     'Content-Type': RSC_CONTENT_TYPE,
   };
 
-  let payload: unknown;
   if (result.revalidation) {
     // Wrapper object — Next.js-style pattern: action result + element tree
     // serialized together so React Flight handles both in one stream.
-    payload = {
+    const revalidationPayload = {
       _action: result.actionResult,
       // The payload root, not a bare tree: it carries the revalidated
       // route's params too, and the client publishes them (TIM-1297).
       _tree: result.revalidation.payload,
     };
+
+    // TIM-1366: access.ts deny signals fire during serialization (inside
+    // AccessGate during renderToReadableStream), not during buildRouteElement.
+    // Buffer the stream and track errors so we can drop the revalidation
+    // cleanly instead of shipping a broken flight stream. Access runs
+    // exactly once — during the real render — preserving TIM-1363.
+    let serializationSignal:
+      | { kind: 'deny'; status: number }
+      | { kind: 'redirect'; location: string; status: number }
+      | { kind: 'error' }
+      | undefined;
+    const rscStream = renderToReadableStream(revalidationPayload, {
+      signal: req.signal,
+      onError(error: unknown) {
+        // ??= keeps the first signal (shallowest AccessGate in top-down render).
+        if (error instanceof DenySignal) {
+          serializationSignal ??= { kind: 'deny', status: error.status };
+        } else if (error instanceof RedirectSignal) {
+          serializationSignal ??= {
+            kind: 'redirect',
+            location: error.location,
+            status: error.status,
+          };
+        } else {
+          console.error('[timber] revalidation serialization error:', error);
+          serializationSignal ??= { kind: 'error' };
+        }
+      },
+    });
+
+    // Drain the stream to detect any signals before committing the response.
+    // Timeout-guarded: the element tree may contain async server components
+    // with stalled fetches. 30s matches the default renderTimeoutMs.
+    const reader = rscStream.getReader();
+    const chunks: Uint8Array[] = [];
+    const drainTimeoutMs = 30_000;
+    try {
+      for (;;) {
+        const { done, value } = await withTimeout(
+          reader.read(),
+          drainTimeoutMs,
+          'revalidation stream drain timed out'
+        );
+        if (done) break;
+        chunks.push(value);
+        if (serializationSignal) {
+          reader.cancel().catch(() => {});
+          break;
+        }
+      }
+    } catch (drainError) {
+      reader.cancel().catch(() => {});
+      if (drainError instanceof RenderTimeoutError) {
+        console.error('[timber] revalidatePath dropped — stream drain timed out');
+        const fallbackStream = renderToReadableStream(result.actionResult);
+        return new Response(fallbackStream, { status: 200, headers });
+      }
+      throw drainError;
+    }
+
+    if (serializationSignal) {
+      if (serializationSignal.kind === 'redirect') {
+        const redirectPayload = {
+          _redirect: serializationSignal.location,
+          _status: serializationSignal.status,
+        };
+        const redirectStream = renderToReadableStream(redirectPayload);
+        return new Response(redirectStream, {
+          status: 200,
+          headers: {
+            'Content-Type': RSC_CONTENT_TYPE,
+            'X-Timber-Redirect': serializationSignal.location,
+          },
+        });
+      }
+      // Deny or render error: drop the revalidation tree, ship the action result alone.
+      if (serializationSignal.kind === 'deny') {
+        console.error(
+          `[timber] revalidatePath dropped — access denied during render (status ${serializationSignal.status})`
+        );
+      }
+      const fallbackStream = renderToReadableStream(result.actionResult);
+      return new Response(fallbackStream, { status: 200, headers });
+    }
+
+    // Clean serialization — return the buffered bytes with revalidation header.
     headers['X-Timber-Revalidation'] = '1';
-    // Metadata (<title>/<meta>/<link>) now rides the revalidation element
-    // tree as React elements — React 19 Float manages them in document.head
-    // during client rendering. No X-Timber-Head header needed. See TIM-1151.
-  } else {
-    payload = result.actionResult;
+    const buffered = concatUint8Arrays(chunks);
+    return new Response(buffered.buffer as ArrayBuffer, { status: 200, headers });
   }
 
-  const rscStream = renderToReadableStream(payload);
+  const rscStream = renderToReadableStream(result.actionResult);
 
   return new Response(rscStream, {
     status: 200,
@@ -313,6 +397,20 @@ async function handleRscAction(
   });
 }
 
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function concatUint8Arrays(chunks: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const c of chunks) total += c.byteLength;
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
 // ─── No-JS Form Action ───────────────────────────────────────────────────
 
 /**

package/src/server/als-registry.ts

@@ -32,6 +32,7 @@
  */
 
 import '#server-only-guard';
+import type { CoercedParams } from '../shared/param-value.js';
 import type { SlotParamsRecord } from '../shared/slot-params.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import type { DebugComponentEntry } from './rsc-entry/helpers.js';
@@ -94,7 +95,7 @@ export interface RequestContextStore {
    *
    * See design/07-routing.md §"params.ts — Convention File for Typed Params"
    */
-  segmentParams?: Record<string, string | string[]>;
+  segmentParams?: CoercedParams;
   /**
    * The matched segment path (e.g. '/(browse)/[artistSlug]/[year]').
    * Includes route groups and parallel slots — uniquely identifies the
@@ -152,11 +153,15 @@ export interface RequestContextStore {
   /**
    * Metadata entries collected during render by MetadataCollector.
    * Populated per-segment in tree order (root→page) during
-   * renderToReadableStream. MetadataHead reads all entries,
-   * merges them, and renders Float-hoisted head elements.
-   * See TIM-1363, design/16-metadata.md.
+   * renderToReadableStream. Entries may contain promises for dynamic
+   * metadata (resolved concurrently with page rendering, TIM-1367).
+   * MetadataHead awaits all entries before merging.
+   * See TIM-1363, TIM-1367, design/16-metadata.md.
    */
-  _metadataEntries?: import('./metadata.js').SegmentMetadataEntry[];
+  _metadataEntries?: Array<{
+    metadata: import('./types.js').Metadata | Promise<import('./types.js').Metadata | null>;
+    isPage: boolean;
+  }>;
 }
 
 /** A single outgoing cookie entry in the cookie jar. */

package/src/server/chain-url-parts.ts

@@ -22,6 +22,7 @@
 
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
+import type { CoercedParams } from '../shared/param-value.js';
 import { effectiveUrlSegment } from '../routing/segment-classify.js';
 import { computeInterceptedBase } from '../routing/interception.js';
 
@@ -51,7 +52,7 @@ import { computeInterceptedBase } from '../routing/interception.js';
  */
 export function extractUrlParts(
   segments: ManifestSegmentNode[],
-  mainParams: Record<string, string | string[]>
+  mainParams: CoercedParams
 ): string[] {
   const parts: string[] = [];
   for (const node of segments) {

package/src/server/index.ts

@@ -64,4 +64,8 @@ export { revalidatePath, revalidateTag } from './actions';
 // Design doc: design/17-logging.md §"trace_id is Always Set"
 export { getTraceId, getSpanId, withSpan, addSpanEvent } from './tracing';
 
+// Coerced param types — the post-coercion domain for segment params.
+// TIM-1347: these replaced the previous `Record<string, string | string[]>` lie.
+export type { CoercedParamValue, CoercedParams } from '../shared/param-value';
+
 // Segment params types — re-exported for convenience.

package/src/server/metadata-collector.ts

@@ -6,12 +6,21 @@
  * 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.
+ * MetadataCollector is synchronous: it starts dynamic metadata() calls
+ * without awaiting and pushes the promise into the entries array, then
+ * returns children immediately. This lets React descend into the page
+ * subtree while metadata I/O runs concurrently (TIM-1367). A sibling
+ * MetadataSettle component awaits the promise so errors surface at the
+ * collector's tree position (caught by that segment's error boundary).
  *
- * See TIM-1363, design/16-metadata.md.
+ * MetadataHead is async: it awaits all entry promises before merging.
+ * Ordering is guaranteed by tree position — ancestor collectors push
+ * before MetadataHead renders.
+ *
+ * AccessGate denial prevents MetadataCollector from rendering, so
+ * metadata() never starts for denied segments (TIM-1027).
+ *
+ * See TIM-1363, TIM-1367, design/16-metadata.md.
  */
 
 import { createElement, Fragment } from 'react';
@@ -27,11 +36,41 @@ import { collectMetadataRouteHeadElements } from './metadata-routes.js';
 
 // ─── Request-scoped metadata entry store ────────────────────────────────
 
-function getMetadataEntries(): SegmentMetadataEntry[] {
+/**
+ * Internal entry type that supports deferred (promise) metadata for
+ * concurrent resolution (TIM-1367). Dynamic metadata pushes a promise;
+ * static metadata pushes the resolved object directly.
+ */
+interface DeferredMetadataEntry {
+  metadata: Metadata | Promise<Metadata | null>;
+  isPage: boolean;
+}
+
+function getDeferredMetadataEntries(): DeferredMetadataEntry[] {
   const store = requestContextAls.getStore();
   if (!store) return [];
   store._metadataEntries ??= [];
-  return store._metadataEntries;
+  return store._metadataEntries as DeferredMetadataEntry[];
+}
+
+// ─── MetadataSettle ─────────────────────────────────────────────────────
+
+interface MetadataSettleProps {
+  promise: Promise<Metadata | null>;
+}
+
+/**
+ * Tiny async server component rendered as a sibling of the collector's
+ * children. Its sole job is error ownership: awaiting the metadata
+ * promise so that rejections surface at THIS tree position (caught by
+ * the owning segment's error boundary, not MetadataHead's).
+ *
+ * Shell settlement (onSettled) is handled by the collector attaching
+ * directly to the promise — unconditional on render progress.
+ */
+async function MetadataSettle(props: MetadataSettleProps): Promise<ReactNode> {
+  await props.promise;
+  return null;
 }
 
 // ─── MetadataCollector ──────────────────────────────────────────────────
@@ -45,36 +84,47 @@ export interface MetadataCollectorProps {
 }
 
 /**
- * Async server component that collects one segment's metadata during
- * render. Placed between AccessGate and the layout/page. When
+ * Synchronous 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).
+ * metadata() never starts for denied segments (TIM-1027).
  *
  * Static metadata objects are pushed synchronously (no side effects).
- * Dynamic metadata functions are awaited with OTEL tracing.
+ * Dynamic metadata functions are started (not awaited) and pushed as
+ * promises — React descends into children immediately while the I/O
+ * runs concurrently (TIM-1367). Shell settlement (onSettled) is
+ * attached directly to the promise so it fires unconditionally. A
+ * sibling MetadataSettle component awaits the promise for error
+ * ownership only.
  */
-export async function MetadataCollector(props: MetadataCollectorProps): Promise<ReactNode> {
+export function MetadataCollector(props: MetadataCollectorProps): 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 (typeof metadataExport === 'function') {
+    const promise = withSpan('timber.metadata', { 'timber.segment': segmentName }, () =>
+      (metadataExport as () => Promise<Metadata>)()
+    ).then((v) => v ?? null);
+    // Suppress unhandled rejection — MetadataSettle and MetadataHead
+    // both attach handlers, but a fast-rejecting promise can fire
+    // Node's unhandledRejection before they do.
+    promise.catch(() => {});
+    // Shell settlement: unconditional on render progress. If React
+    // never reaches MetadataSettle (e.g., parent error boundary fires
+    // first), the HTTP status still commits on time.
+    if (onSettled)
+      promise.then(
+        () => onSettled(),
+        () => onSettled()
+      );
 
-    if (metadata) {
-      getMetadataEntries().push({ metadata, isPage });
-    }
+    getDeferredMetadataEntries().push({ metadata: promise, isPage });
 
-    return children;
-  } finally {
-    onSettled?.();
+    return createElement(Fragment, null, children, createElement(MetadataSettle, { promise }));
   }
+
+  getDeferredMetadataEntries().push({ metadata: metadataExport, isPage });
+  onSettled?.();
+  return children;
 }
 
 // ─── MetadataHead ───────────────────────────────────────────────────────
@@ -83,21 +133,46 @@ 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.
+ * Async server component that awaits all deferred metadata promises,
+ * merges entries, auto-links metadata routes, and renders Float-
+ * hoisted head elements.
+ *
+ * Rendered as a SIBLING of the page element (not a wrapper) so React
+ * processes both concurrently — the page starts rendering immediately
+ * while MetadataHead awaits metadata promises. Both resolve before
+ * onShellReady (they're outside Suspense), but they overlap. Float
+ * hoists the head elements to <head> regardless of tree position.
  *
- * 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).
+ * Ordering is guaranteed by tree position: every MetadataCollector
+ * is an ancestor of the Fragment containing MetadataHead, so its
+ * synchronous push into the entries array happens-before MetadataHead
+ * executes.
+ *
+ * See TIM-1367 for the concurrent resolution design.
  */
-export function MetadataHead(props: MetadataHeadProps): ReactNode {
-  const { segments, requestUrl, metadataRouteHashes, children } = props;
-  const entries = getMetadataEntries();
+export async function MetadataHead(props: MetadataHeadProps): Promise<ReactNode> {
+  const { segments, requestUrl, metadataRouteHashes } = props;
+  const deferredEntries = getDeferredMetadataEntries();
+
+  // Resolve all deferred metadata concurrently. Rejected entries are
+  // dropped — their errors are surfaced by MetadataSettle at the
+  // owning segment's error boundary, not here.
+  const settled = await Promise.allSettled(
+    deferredEntries.map((e) =>
+      e.metadata instanceof Promise ? e.metadata : Promise.resolve(e.metadata)
+    )
+  );
+  const entries: SegmentMetadataEntry[] = [];
+  for (let i = 0; i < settled.length; i++) {
+    const s = settled[i];
+    if (s.status === 'fulfilled' && s.value) {
+      entries.push({ metadata: s.value, isPage: deferredEntries[i].isPage });
+    }
+  }
+
   const resolved = resolveMetadata(entries);
   const headElements = renderMetadataToElements(resolved);
 
@@ -110,6 +185,5 @@ export function MetadataHead(props: MetadataHeadProps): ReactNode {
   );
   headElements.push(...autoLinked);
 
-  const metadataElement = headElementsToReact(headElements);
-  return createElement(Fragment, null, metadataElement, children);
+  return headElementsToReact(headElements);
 }

package/src/server/param-coercion.ts

@@ -17,7 +17,7 @@ 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 { normalizeParamValue } from '../shared/param-value.js';
+import { normalizeParamValue, type CoercedParams } from '../shared/param-value.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { isDebug } from './debug.js';
 
@@ -65,11 +65,11 @@ export function coerceSlotParams(
     interceptedSegmentName?: string;
   }>,
   rawParams: Record<string, string | string[]>
-): Record<string, string | string[]> {
+): CoercedParams {
   const globalCodecs = _globalCodecs;
   if (!globalCodecs) return rawParams;
 
-  const result: Record<string, string | string[]> = Object.create(null);
+  const result: CoercedParams = Object.create(null);
   for (const key of Object.keys(rawParams)) {
     result[key] = rawParams[key];
   }
@@ -102,10 +102,10 @@ export function coerceSlotParams(
       }
       continue;
     }
-    result[key] = normalizeParamValue(parsed, key) as string | string[];
+    result[key] = normalizeParamValue(parsed, key);
   }
 
-  return result as Record<string, string | string[]>;
+  return result;
 }
 
 /**
@@ -134,13 +134,13 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
   // Unconditionally install a null-prototype target so the invariant
   // "match.segmentParams is null-prototype" holds from the first line,
   // regardless of whether any segment has a codec.
-  const mergeTarget: Record<string, unknown> = Object.create(null);
+  const mergeTarget: CoercedParams = Object.create(null);
   for (const key of Object.keys(match.segmentParams)) {
     if (key !== '__proto__') {
       mergeTarget[key] = match.segmentParams[key as keyof typeof match.segmentParams];
     }
   }
-  match.segmentParams = mergeTarget as RouteMatch['segmentParams'];
+  match.segmentParams = mergeTarget;
 
   // TIM-931/TIM-936: When a global schema is available, use it for coercion
   // instead of per-segment params.ts files. The global codec map is keyed

package/src/server/pipeline-phases.ts

@@ -528,7 +528,9 @@ export async function handleRequest(
   // Snapshot raw params before coercion — slot resolution needs the
   // original string values to reconstruct URL parts for tree matching.
   // Coerced params may have been transformed by codecs.
-  match.rawSegmentParams = { ...match.segmentParams };
+  // segmentParams is typed CoercedParams but is still raw strings here
+  // (coercion runs below). The snapshot preserves the pre-coercion shape.
+  match.rawSegmentParams = { ...match.segmentParams } as Record<string, string | string[]>;
   try {
     await coerceSegmentParams(match);
   } catch (error) {