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

package/src/server/pipeline.ts

@@ -15,6 +15,7 @@
  * and design/17-logging.md §"Production Logging"
  */
 
+import type { CoercedParams } from '../shared/param-value.js';
 import type { ProxyExport } from './proxy.js';
 import type { MiddlewareFn } from './middleware-runner.js';
 import { runWithTimingCollector, getServerTimingHeader } from './server-timing.js';
@@ -54,8 +55,8 @@ import { isDebug } from './debug.js';
 export interface RouteMatch {
   /** The matched segment chain from root to leaf. */
   segments: ManifestSegmentNode[];
-  /** Extracted segment params (catch-all segments produce string[]). */
-  segmentParams: Record<string, string | string[]>;
+  /** Extracted segment params (catch-all segments produce string[]). Post-coercion, values may be non-string (TIM-1347). */
+  segmentParams: CoercedParams;
   /**
    * Raw segment params before codec coercion. Always string or string[].
    * Used by slot resolution to reconstruct URL parts — coerced params may

package/src/server/prebuilt/cache-key.ts

@@ -41,6 +41,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { CoercedParams } from '../../shared/param-value.js';
 
 class UnkeyableValueError extends Error {}
 
@@ -260,7 +261,7 @@ export function splitSlotProps(
  */
 export function computeComponentCacheKey(
   props: Record<string, unknown>,
-  params: Record<string, string | string[]>
+  params: CoercedParams
 ): string | null {
   let canonical: string;
   try {

package/src/server/prebuilt/payload-source.ts

@@ -17,10 +17,11 @@
  */
 
 import { initTagIndex, resetTagIndex } from './overlay.js';
+import type { CoercedParams } from '../../shared/param-value.js';
 
 export interface PrebuiltManifestEntry {
   /** Segment params this entry was captured under. */
-  params: Record<string, string | string[]>;
+  params: CoercedParams;
   /** Payload path relative to the prebuilt/ directory. */
   file: string;
   /** Payload size in bytes (build report / diagnostics). */

package/src/server/prebuilt/synthetic-store.ts

@@ -35,6 +35,7 @@
  */
 
 import type { RequestContextStore } from '../als-registry.js';
+import type { CoercedParams } from '../../shared/param-value.js';
 
 /**
  * Thrown when a prerendered component touches per-request context at
@@ -79,7 +80,7 @@ export interface BuildTimeStoreHandle {
  */
 export function createBuildTimeStore(
   componentId: string,
-  segmentParams: Record<string, string | string[]>
+  segmentParams: CoercedParams
 ): BuildTimeStoreHandle {
   const violations: BuildTimeContextError[] = [];
   const handle: BuildTimeStoreHandle = {

package/src/server/prebuilt-builder.ts

@@ -45,6 +45,7 @@
 import { createElement } from 'react';
 
 import { requestContextAls } from './als-registry.js';
+import type { CoercedParams } from '../shared/param-value.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { SlotOutlet } from '../client/slot-outlet.js';
 import { coerceSegmentParams } from './param-coercion.js';
@@ -76,8 +77,8 @@ export interface CapturedEntry {
   componentId: string;
   /** `computeComponentCacheKey(callSiteProps, coercedParams)` — names the .flight file. */
   cacheKey: string;
-  /** The raw param combo (JSON-safe) — manifest metadata, not the hash input. */
-  params: Record<string, string | string[]>;
+  /** The param combo — manifest metadata, not the hash input. */
+  params: CoercedParams;
   /** Call-site props used for this entry (empty object for zero-prop usages). */
   props?: Record<string, unknown>;
   bytes: Uint8Array;
@@ -91,7 +92,7 @@ export interface CapturedEntry {
 export interface CaptureIssue {
   componentId: string;
   routeUrlPath: string;
-  params: Record<string, string | string[]>;
+  params: CoercedParams;
   message: string;
 }
 
@@ -219,7 +220,7 @@ async function loadLazyChunk(chunkFile: string): Promise<void> {
 
 // ─── Param enumeration ────────────────────────────────────────────────────
 
-type ParamCombo = Record<string, string | string[]>;
+type ParamCombo = CoercedParams;
 
 /**
  * Resolve the param combos to capture for a route. Static routes have
@@ -333,7 +334,7 @@ interface EntryOutcome {
 async function renderEntry(
   registration: PrebuiltRegistration,
   props: Record<string, unknown>,
-  coercedParams: Record<string, string | string[]>,
+  coercedParams: CoercedParams,
   timeoutMs: number,
   isLayout: boolean
 ): Promise<EntryOutcome> {

package/src/server/prebuilt-runtime.ts

@@ -36,6 +36,8 @@
 import { createElement } from 'react';
 
 import { requestContextAls, type RequestContextStore } from './als-registry.js';
+import type { CoercedParams } from '../shared/param-value.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 import { computeComponentCacheKey, splitSlotProps, tryCanonicalize } from './prebuilt/cache-key.js';
 import {
   isChildrenSlotOutletElement,
@@ -172,9 +174,9 @@ const registry = new Map<string, PrebuiltRegistration>();
  * aliases, …) is unkeyable here too, and this guard can never throw.
  */
 function resolveKeyParams(store: {
-  segmentParams?: Record<string, string | string[]>;
-  slotParams?: Record<string, Record<string, string | string[]>>;
-}): Record<string, string | string[]> | null {
+  segmentParams?: CoercedParams;
+  slotParams?: SlotParamsRecord;
+}): CoercedParams | null {
   const main = store.segmentParams ?? {};
   const slots = store.slotParams;
   if (!slots || Object.keys(slots).length === 0) return main;

package/src/server/request-context.ts

@@ -14,6 +14,7 @@
  * and design/11-platform.md §"AsyncLocalStorage".
  */
 
+import type { CoercedParams } from '../shared/param-value.js';
 import { requestContextAls, type RequestContextStore } from './als-registry.js';
 import { _setGetSearchParamsFn, _setGetSegmentParamsFn } from '../shared/als-slots.js';
 import { consumeSeededCookies } from './cookie-context.js';
@@ -101,7 +102,7 @@ _setGetSegmentParamsFn(getSegmentParams);
  *
  * See design/41-global-params.md §Function Signatures
  */
-export function getSegmentParams(segmentPath?: string): Record<string, string | string[]> {
+export function getSegmentParams(segmentPath?: string): CoercedParams {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
@@ -152,7 +153,7 @@ export function getSegmentParams(segmentPath?: string): Record<string, string |
  *
  * @internal — framework use only
  */
-export function setSegmentParams(params: Record<string, string | string[]>): void {
+export function setSegmentParams(params: CoercedParams): void {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error('[timber] setSegmentParams() called outside of a request context.');
@@ -168,10 +169,7 @@ export function setSegmentParams(params: Record<string, string | string[]>): voi
  * @param params — The slot's coerced segment params
  * @internal — framework use only
  */
-export function setSlotParams(
-  segmentPath: string,
-  params: Record<string, string | string[]>
-): void {
+export function setSlotParams(segmentPath: string, params: CoercedParams): void {
   const store = requestContextAls.getStore();
   if (!store) return; // non-throwing — optional diagnostic
   if (!store.slotParams) store.slotParams = Object.create(null) as SlotParamsRecord;
@@ -203,7 +201,7 @@ export function setSlotParams(
  */
 export function runWithSlotSegmentParams<T>(
   slotSegmentPath: string | undefined,
-  slotParams: Record<string, string | string[]>,
+  slotParams: CoercedParams,
   fn: () => T
 ): T {
   const store = requestContextAls.getStore();
@@ -230,7 +228,7 @@ export function runWithSlotSegmentParams<T>(
  *
  * @internal — framework use only. See TIM-1285.
  */
-export function getSegmentParamsForClient(): Record<string, string | string[]> {
+export function getSegmentParamsForClient(): CoercedParams {
   return requestContextAls.getStore()?.segmentParams ?? {};
 }
 

package/src/server/route-element-builder.ts

@@ -220,34 +220,6 @@ function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: st
   }
 }
 
-/**
- * Extract and resolve metadata from a module (layout or page).
- * Handles both static metadata objects and async metadata functions.
- * Returns the resolved Metadata, or null if none exported.
- *
- * Metadata functions no longer receive { params } — they access params
- * via getSegmentParams() from ALS, same as page/layout components.
- */
-async function extractMetadata(
-  mod: Record<string, unknown>,
-  segment: ManifestSegmentNode
-): Promise<Metadata | null> {
-  if (typeof mod.metadata === 'function') {
-    type MetadataFn = () => Promise<Metadata>;
-    return (
-      (await withSpan(
-        'timber.metadata',
-        { 'timber.segment': segment.segmentName ?? segment.urlPath },
-        () => (mod.metadata as MetadataFn)()
-      )) ?? null
-    );
-  }
-  if (mod.metadata) {
-    return mod.metadata as Metadata;
-  }
-  return null;
-}
-
 /**
  * Extract `deferSuspenseFor` from a module and return the maximum
  * of the current value and the module's value.
@@ -446,18 +418,24 @@ export async function buildRouteElement(
     element = h(TracedPage, {});
   }
 
-  // Wrap page in MetadataHead — a server component that reads all
-  // metadata entries collected by MetadataCollector components above it,
-  // merges them, and renders Float-hoisted head elements as siblings of
-  // the page. Placed at the page level so metadata is always re-rendered
-  // on SPA navigation (never skipped by segment tree diffing).
-  // See TIM-1363, design/16-metadata.md.
-  element = h(MetadataHead, {
-    segments,
-    requestUrl: req.url,
-    metadataRouteHashes,
-    children: element,
-  });
+  // Place MetadataHead as a SIBLING of the page, not a wrapper. React
+  // renders siblings concurrently — the page starts immediately while
+  // MetadataHead awaits metadata promises. Float hoists the head
+  // elements to <head> regardless of tree position. Both resolve before
+  // onShellReady (outside Suspense), but they overlap.
+  // Placed at the page level so metadata is always re-rendered on SPA
+  // navigation (never skipped by segment tree diffing).
+  // See TIM-1363, TIM-1367, design/16-metadata.md.
+  element = h(
+    Fragment,
+    null,
+    h(MetadataHead, {
+      segments,
+      requestUrl: req.url,
+      metadataRouteHashes,
+    }),
+    element
+  );
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(

package/src/server/sitemap-generator.ts

@@ -16,6 +16,7 @@
 
 import { serializeSitemap, serializeSitemapIndex } from './pipeline-metadata.js';
 import type { SegmentNode } from '../routing/types.js';
+import type { CoercedParams } from '../shared/param-value.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -229,26 +230,23 @@ export async function resolveSitemapUrls(
  *
  * @returns The resolved path, or null if params are missing
  */
-export function resolvePathWithParams(
-  urlPath: string,
-  params: Record<string, string | string[]>
-): string | null {
+export function resolvePathWithParams(urlPath: string, params: CoercedParams): string | null {
   let resolved = urlPath;
 
   // Optional catch-all: [[...param]]
   resolved = resolved.replace(/\[\[\.\.\.([^\]]+)\]\]/g, (_, name) => {
     const value = params[name];
     if (value === undefined || value === '') return '';
-    if (Array.isArray(value)) return value.join('/');
-    return value;
+    if (Array.isArray(value)) return value.map(String).join('/');
+    return String(value);
   });
 
   // Catch-all: [...param]
   resolved = resolved.replace(/\[\.\.\.([^\]]+)\]/g, (_, name) => {
     const value = params[name];
     if (value === undefined) return '';
-    if (Array.isArray(value)) return value.join('/');
-    return value;
+    if (Array.isArray(value)) return value.map(String).join('/');
+    return String(value);
   });
 
   // Single dynamic: [param] (possibly with affixes like img-[id].png)
@@ -260,7 +258,7 @@ export function resolvePathWithParams(
       missingRequired = true;
       return match; // keep original to avoid malformed URL
     }
-    const v = Array.isArray(value) ? (value[0] ?? '') : value;
+    const v = Array.isArray(value) ? String(value[0] ?? '') : String(value);
     return prefix + v + suffix;
   });
 

package/src/server/slot-resolver.ts

@@ -28,6 +28,7 @@ import { logRenderError } from './logger.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import { setSlotParams, runWithSlotSegmentParams } from './request-context.js';
 import { coerceSlotParams } from './param-coercion.js';
+import type { CoercedParams } from '../shared/param-value.js';
 import { matchUrlParts } from './tree-match.js';
 import { extractUrlParts, consumedPartsThroughSegment } from './chain-url-parts.js';
 import { findInterceptingMatch } from './slot-interception.js';
@@ -391,7 +392,7 @@ export interface SlotMatchResult {
   page: NonNullable<ManifestSegmentNode['page']>;
   /** The full chain of slot nodes traversed (slot root → … → leaf with page). */
   chain: ManifestSegmentNode[];
-  /** Params collected from the slot's segment chain (may differ from main route params). */
+  /** Params collected from the slot's segment chain (pre-coercion, may differ from main route params). */
   slotParams: Record<string, string | string[]>;
 }
 

package/src/server/ssr-bridge-types.ts

@@ -29,6 +29,9 @@
  * and `CLAUDE.md` §"RSC and SSR Are Separate Vite Environments".
  */
 
+import type { CoercedParams } from '../shared/param-value.js';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
+
 /**
  * Navigation context passed from the RSC environment to SSR.
  *
@@ -38,8 +41,8 @@
 export interface NavContext {
   /** The requested pathname */
   pathname: string;
-  /** Extracted route segment params (catch-all segments produce string[]) */
-  segmentParams: Record<string, string | string[]>;
+  /** Extracted route segment params. Post-coercion, values may be non-string (TIM-1347). */
+  segmentParams: CoercedParams;
   /** Search params from the URL */
   searchParams: Record<string, string>;
   /**
@@ -47,7 +50,7 @@ export interface NavContext {
    * rendered no slot with params of its own. Feeds `useSegmentParams(path)`
    * during SSR and, via `__timber_slot_params`, after hydration (TIM-1285).
    */
-  slotParams?: Record<string, Record<string, string | string[]>>;
+  slotParams?: SlotParamsRecord;
   /** The committed HTTP status code */
   statusCode: number;
   /** Response headers from middleware/proxy */

package/src/server/types.ts

@@ -1,5 +1,6 @@
 // Server-side type definitions
 
+import type { CoercedParams } from '../shared/param-value.js';
 import type { EarlyHint } from './early-hints.js';
 
 /**
@@ -22,7 +23,7 @@ export interface MiddlewareContext {
   req: Request;
   requestHeaders: Headers;
   headers: Headers;
-  segmentParams: Record<string, string | string[]>;
+  segmentParams: CoercedParams;
   /** Declare early hints for critical resources. Appends Link headers. */
   earlyHints: (hints: EarlyHint[]) => void;
 }

package/src/shared/als-slots.ts

@@ -31,6 +31,8 @@
  * design/41-global-params.md.
  */
 
+import type { CoercedParams } from './param-value.js';
+
 interface AlsSlot<T> {
   /** Register the server-side getter. Called once at module-init time. */
   set(fn: () => T): void;
@@ -56,7 +58,7 @@ const searchParamsSlot = createAlsSlot<URLSearchParams>(
     'Use searchParams.useQueryStates() on the client.'
 );
 
-const segmentParamsSlot = createAlsSlot<Record<string, string | string[]>>(
+const segmentParamsSlot = createAlsSlot<CoercedParams>(
   '[timber] segmentParams.get() is only available on the server. ' +
     'Use segmentParams.useSegmentParams() on the client.'
 );

package/src/shared/param-value.ts

@@ -62,6 +62,43 @@
  * See design/41-global-params.md §"Transport".
  */
 
+// ─── Post-coercion param types ──────────────────────────────────────────
+
+/**
+ * A single segment param value after codec coercion and normalization.
+ *
+ * Before coercion, every param is `string | string[]` (the raw URL part).
+ * After `app/schema.ts` codecs run, a param can be any value in the
+ * `normalizeParamValue` domain below. This type replaces the previous
+ * `string | string[]` declaration, which was a lie whenever a codec
+ * produced a non-string value (TIM-1347).
+ *
+ * The typed accessor `getSegmentParams(SEGMENT_PATH)` resolves through
+ * the schema and returns the exact type the codec declares. This type
+ * covers the untyped/no-argument form and internal plumbing.
+ */
+export type CoercedParamValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | null
+  | undefined
+  | Date
+  | Map<CoercedParamValue, CoercedParamValue>
+  | Set<CoercedParamValue>
+  | CoercedParamValue[]
+  | { [key: string]: CoercedParamValue };
+
+/**
+ * A record of coerced segment params, keyed by param name.
+ *
+ * This is the post-coercion type for `segmentParams` throughout the
+ * framework. Before coercion (route matcher output, `rawSegmentParams`),
+ * the type is `Record<string, string | string[]>`.
+ */
+export type CoercedParams = Record<string, CoercedParamValue>;
+
 /** Types the canonical form rebuilds rather than rejects. */
 const REBUILT = ['Date', 'Map', 'Set'] as const;
 
@@ -88,16 +125,16 @@ function describe(value: object): string {
  * is rejected. That is one rule for two things — a shared reference and a cycle
  * are both "this object again" — and it is what keeps the result a tree.
  */
-export function normalizeParamValue(value: unknown, path = ''): unknown {
+export function normalizeParamValue(value: unknown, path = ''): CoercedParamValue {
   return normalize(value, path, new Set());
 }
 
-function normalize(value: unknown, path: string, seen: Set<object>): unknown {
+function normalize(value: unknown, path: string, seen: Set<object>): CoercedParamValue {
   if (value === null) return null;
 
   const kind = typeof value;
   if (kind === 'string' || kind === 'number' || kind === 'boolean' || kind === 'bigint') {
-    return value;
+    return value as string | number | boolean | bigint;
   }
   if (kind === 'undefined') return undefined;
   if (kind === 'function') {
@@ -124,7 +161,7 @@ function normalize(value: unknown, path: string, seen: Set<object>): unknown {
     // Read by index, so holes become `undefined` — on both sides, which is
     // the point. A subclass and any own properties are left behind for the
     // same reason: the clone is a plain, dense array either way.
-    const out: unknown[] = [];
+    const out: CoercedParamValue[] = [];
     for (let index = 0; index < object.length; index++) {
       out.push(normalize((object as unknown[])[index], `${path}[${index}]`, seen));
     }
@@ -138,7 +175,7 @@ function normalize(value: unknown, path: string, seen: Set<object>): unknown {
   }
 
   if (object instanceof Map) {
-    const out = new Map<unknown, unknown>();
+    const out = new Map<CoercedParamValue, CoercedParamValue>();
     for (const [key, entry] of object) {
       out.set(
         normalize(key, `${path}<key>`, seen),
@@ -149,7 +186,7 @@ function normalize(value: unknown, path: string, seen: Set<object>): unknown {
   }
 
   if (object instanceof Set) {
-    const out = new Set<unknown>();
+    const out = new Set<CoercedParamValue>();
     let index = 0;
     for (const entry of object) out.add(normalize(entry, `${path}[${index++}]`, seen));
     return out;
@@ -171,7 +208,7 @@ function normalize(value: unknown, path: string, seen: Set<object>): unknown {
   // so dropping it here keeps the two sides identical. `__proto__` is skipped
   // rather than copied: it has a language-level setter that would change the
   // prototype chain of the copy (TIM-655, TIM-855, TIM-873).
-  const out: Record<string, unknown> = Object.create(null);
+  const out: Record<string, CoercedParamValue> = Object.create(null);
   for (const key of Object.keys(object)) {
     if (key === '__proto__') continue;
     out[key] = normalize(

package/src/shared/payload-root.ts

@@ -32,12 +32,13 @@
  * helpers here — producer and consumer do not each describe the payload.
  */
 
+import type { CoercedParams } from './param-value.js';
 import type { SlotParamsRecord } from './slot-params.js';
 
 /** The params published beside a tree. */
 export interface PublishedParams {
   /** The main route's coerced params. */
-  params: Record<string, string | string[]>;
+  params: CoercedParams;
   /** Per-slot params, or null when the route rendered no slots with params. */
   slotParams: SlotParamsRecord | null;
 }

package/src/shared/slot-params.ts

@@ -18,8 +18,10 @@
  * 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.
@@ -37,9 +39,9 @@ export type SlotParamsRecord = Record<string, Record<string, string | string[]>>
  * by merging. See design/13-security.md #36c.
  */
 export function mergeSlotParams(
-  mainParams: Record<string, string | string[]>,
-  slotParams: Record<string, string | string[]>
-): Record<string, string | string[]> {
+  mainParams: CoercedParams,
+  slotParams: CoercedParams
+): CoercedParams {
   return Object.assign(Object.create(null), mainParams, slotParams);
 }
 
@@ -56,10 +58,10 @@ export function mergeSlotParams(
  * resolve to an inherited member of `Object.prototype`.
  */
 export function resolveSegmentParams(
-  mainParams: Record<string, string | string[]>,
+  mainParams: CoercedParams,
   slotParams: SlotParamsRecord | null | undefined,
   segmentPath: string | undefined
-): Record<string, string | string[]> {
+): CoercedParams {
   if (!segmentPath || !slotParams || !Object.hasOwn(slotParams, segmentPath)) return mainParams;
   return cachedMerge(mainParams, slotParams, segmentPath);
 }
@@ -83,16 +85,13 @@ export function resolveSegmentParams(
  * A `WeakMap` chain rather than a `Map`, so a superseded navigation's records
  * and their merges become collectable as soon as nothing else holds them.
  */
-const mergeCache = new WeakMap<
-  object,
-  WeakMap<object, Map<string, Record<string, string | string[]>>>
->();
+const mergeCache = new WeakMap<object, WeakMap<object, Map<string, CoercedParams>>>();
 
 function cachedMerge(
-  mainParams: Record<string, string | string[]>,
+  mainParams: CoercedParams,
   slotParams: SlotParamsRecord,
   segmentPath: string
-): Record<string, string | string[]> {
+): CoercedParams {
   let bySlotMap = mergeCache.get(mainParams);
   if (!bySlotMap) {
     bySlotMap = new WeakMap();