@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/search-params/index.ts

@@ -1,34 +1,28 @@
 // @timber-js/app/search-params — Typed search params
 
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
+
 // Core types and factory
 export type {
   SearchParamCodec,
+  SearchParamCodecWithUrlKey,
   InferCodec,
+  InferField,
+  CodecMap,
   SearchParamsDefinition,
   SetParams,
   SetParamsOptions,
   QueryStatesOptions,
-  SearchParamsOptions,
-} from './create.js';
-export { createSearchParams } from './create.js';
+  StandardSchemaV1,
+} from './define.js';
+export { defineSearchParams } from './define.js';
 
-// Codec bridges
-export { fromSchema, fromArraySchema } from './codecs.js';
+// Codec bridges moved to @timber-js/app/codec
+// Import fromSchema / fromArraySchema from '@timber-js/app/codec' instead.
 
-// Built-in codecs
-export {
-  parseAsString,
-  parseAsInteger,
-  parseAsFloat,
-  parseAsBoolean,
-  parseAsStringEnum,
-  parseAsStringLiteral,
-  withDefault,
-} from './builtin-codecs.js';
+// Codec wrappers
+export { withDefault, withUrlKey } from './wrappers.js';
 
 // Runtime registry (route-scoped useQueryStates)
-export { registerSearchParams, getSearchParams } from './registry.js';
-
-// Static analysis (build-time only)
-export type { AnalyzeResult, AnalyzeError } from './analyze.js';
-export { analyzeSearchParams, formatAnalyzeError } from './analyze.js';
+export { registerSearchParams, getSearchParamsDefinition } from './registry.js';

package/src/search-params/registry.ts

@@ -7,7 +7,7 @@
  * Design doc: design/23-search-params.md §"Runtime: Registration at Route Load"
  */
 
-import type { SearchParamsDefinition } from './create.js';
+import type { SearchParamsDefinition } from './define.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const registry = new Map<string, SearchParamsDefinition<any>>();
@@ -26,6 +26,6 @@ export function registerSearchParams(route: string, definition: SearchParamsDefi
  * Returns undefined if the route hasn't been loaded yet.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {
+export function getSearchParamsDefinition(route: string): SearchParamsDefinition<any> | undefined {
   return registry.get(route);
 }

package/src/search-params/wrappers.ts

@@ -0,0 +1,92 @@
+/**
+ * Codec wrappers — withDefault and withUrlKey.
+ *
+ * These are timber-specific utilities that work with any SearchParamCodec.
+ * For actual codecs (string, integer, boolean, etc.), use nuqs parsers
+ * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.
+ *
+ * Design doc: design/23-search-params.md
+ */
+
+import type { SearchParamCodec, SearchParamCodecWithUrlKey, SearchParamField } from './define.js';
+import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// withDefault
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a nullable codec with a default value. When the inner codec returns
+ * null, the default is used instead. The output type becomes non-nullable.
+ *
+ * Works with any codec — nuqs parsers, custom codecs, fromSchema results.
+ *
+ * ```ts
+ * import { parseAsInteger } from 'nuqs'
+ * import { withDefault } from '@timber-js/app/search-params'
+ *
+ * const page = withDefault(parseAsInteger, 1)
+ * // page.parse(undefined) → 1 (not null)
+ * // page.parse('5') → 5
+ * ```
+ */
+export function withDefault<T>(
+  codec: SearchParamCodec<T | null>,
+  defaultValue: T
+): SearchParamCodec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      const result = codec.parse(value);
+      return result === null ? defaultValue : result;
+    },
+    serialize(value: T): string | null {
+      return codec.serialize(value);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// withUrlKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a URL key alias to a codec. The alias determines what query
+ * parameter key is used in the URL, while the TypeScript property name
+ * stays descriptive.
+ *
+ * Aliases travel with codecs through object spread composition — when
+ * you spread a bundle containing aliased codecs into defineSearchParams,
+ * the aliases come along automatically.
+ *
+ * ```ts
+ * import { parseAsString } from 'nuqs'
+ * import { withUrlKey } from '@timber-js/app/search-params'
+ *
+ * export const searchable = {
+ *   q: withUrlKey(parseAsString, 'search'),
+ *   // ?search=shoes → { q: 'shoes' }
+ * }
+ * ```
+ *
+ * Composes with withDefault:
+ * ```ts
+ * import { parseAsInteger } from 'nuqs'
+ * withUrlKey(withDefault(parseAsInteger, 1), 'p')
+ * ```
+ */
+export function withUrlKey<T>(
+  codecOrSchema: SearchParamField<T>,
+  urlKey: string
+): SearchParamCodecWithUrlKey<T> {
+  // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap
+  const codec: SearchParamCodec<T> = isCodec(codecOrSchema)
+    ? codecOrSchema
+    : isStandardSchema(codecOrSchema)
+      ? fromSchema(codecOrSchema)
+      : (codecOrSchema as SearchParamCodec<T>);
+  return {
+    parse: codec.parse.bind(codec),
+    serialize: codec.serialize.bind(codec),
+    urlKey,
+  };
+}

package/src/segment-params/define.ts

@@ -0,0 +1,309 @@
+/**
+ * defineSegmentParams — factory for typed route param coercion.
+ *
+ * Creates a ParamsDefinition that coerces raw string params from the
+ * URL into typed values. Used by exporting from params.ts (segment-level)
+ * convention file.
+ *
+ * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,
+ * same pattern as defineSearchParams. Runtime constraints are stricter:
+ * - serialize must return string (not null — path segments can't be omitted)
+ * - parse throwing → 404 (invalid param value)
+ *
+ * Design doc: design/07a-route-params-triage.md
+ */
+
+import type { Codec } from '../codec.js';
+import {
+  type StandardSchemaV1,
+  validateSync,
+  isStandardSchema,
+  isCodec,
+} from '../schema-bridge.js';
+import { useSegmentParams as clientUseSegmentParams } from '../client/use-segment-params.js';
+
+// ---------------------------------------------------------------------------
+// Server-only ALS reference for .get()
+// ---------------------------------------------------------------------------
+
+// Same pattern as search-params: eagerly registered at server startup
+// to avoid dynamic imports that lose ALS context. See TIM-523.
+let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
+
+/**
+ * Register the getSegmentParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {
+  _getSegmentParamsFn = fn;
+}
+
+function getSegmentParamsFromAls(): Record<string, string | string[]> {
+  if (!_getSegmentParamsFn) {
+    throw new Error(
+      '[timber] segmentParams.get() is only available on the server. ' +
+        'Use segmentParams.useSegmentParams() on the client.'
+    );
+  }
+  return _getSegmentParamsFn();
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Infer the output type from a Codec or StandardSchemaV1. */
+export type InferParamField<V> =
+  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+
+/** Acceptable field value for defineParams: a Codec or a Standard Schema. */
+export type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;
+
+export type { StandardSchemaV1 };
+
+/**
+ * A typed route params definition.
+ *
+ * Returned by defineParams(). Provides parse (string → typed) and
+ * serialize (typed → string) for each declared param.
+ */
+export interface ParamsDefinition<T extends Record<string, unknown>> {
+  /** Parse raw string params into typed values. Throws on invalid values. */
+  parse(raw: Record<string, string | string[]>): T;
+
+  /** Serialize typed values back to strings for URL construction. */
+  serialize(values: T): Record<string, string>;
+
+  /**
+   * Get typed segment params from the current request context (ALS).
+   *
+   * Server-only, sync.
+   *
+   * ```ts
+   * // app/products/[id]/params.ts
+   * export const segmentParams = defineSegmentParams({ id: z.coerce.number() })
+   *
+   * // app/products/[id]/page.tsx
+   * import { segmentParams } from './params'
+   * export default function Page() {
+   *   const { id } = segmentParams.get() // id: number
+   * }
+   * ```
+   */
+  get(): T;
+
+  /**
+   * Client hook for accessing typed segment params reactively.
+   *
+   * ```tsx
+   * 'use client'
+   * import { segmentParams } from './params'
+   * export function ProductHeader() {
+   *   const { id } = segmentParams.useSegmentParams()
+   * }
+   * ```
+   */
+  useSegmentParams(): T;
+
+  /** Read-only codec map. */
+  codecs: { [K in keyof T]: Codec<T[K]> };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a Standard Schema into a Codec for route params.
+ *
+ * Unlike fromSchema for search params:
+ * - Parse throws on failure (no fallback to default)
+ * - Serialize returns string (not null)
+ */
+function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      // Route params are always strings (single segment) or string[] (catch-all)
+      const input = Array.isArray(value) ? value : value;
+
+      const result = validateSync(schema, input);
+      if (!result.issues) {
+        return result.value;
+      }
+
+      // For route params, parse failure means the param is invalid → throw
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      // Catch-all segments produce arrays — join with '/' for path reconstruction
+      if (Array.isArray(value)) {
+        return value.join('/');
+      }
+      return String(value);
+    },
+  };
+}
+
+/**
+ * Resolve a field value to a Codec. Auto-detects Standard Schema objects.
+ */
+function resolveField(fieldName: string, value: ParamField): Codec<unknown> {
+  if (isCodec(value)) {
+    return value;
+  }
+
+  if (isStandardSchema(value)) {
+    return fromParamSchema(fieldName, value);
+  }
+
+  throw new Error(
+    `[timber] defineSegmentParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +
+      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +
+      `(Zod, Valibot, ArkType).`
+  );
+}
+
+/**
+ * Validate that no codec's serialize returns null.
+ * Route params are structural — they must produce a valid path segment.
+ */
+function validateSerialize(codecMap: Record<string, Codec<unknown>>): void {
+  for (const [key, codec] of Object.entries(codecMap)) {
+    // Test serialize with a sample parsed value to check for null
+    // We can't exhaustively test, but we can check that serialize(parse("test"))
+    // doesn't return null for a basic input.
+    try {
+      const testValue = codec.parse('test');
+      const serialized = codec.serialize(testValue);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] defineSegmentParams: field '${key}' codec.serialize() returned null.\n` +
+            `  Route params are path segments — they cannot be omitted.\n` +
+            `  Ensure serialize() always returns a string.`
+        );
+      }
+    } catch (e) {
+      // parse('test') may throw for strict codecs (e.g., number-only).
+      // That's fine — it means the codec validates. We only care about
+      // serialize returning null, which we can't test without a valid value.
+      if (e instanceof Error && e.message.includes('returned null')) {
+        throw e;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.
+ *
+ * ```ts
+ * // app/products/[id]/layout.tsx
+ * import { defineSegmentParams } from '@timber-js/app/segment-params'
+ * import { z } from 'zod/v4'
+ *
+ * export const segmentParams = defineSegmentParams({
+ *   id: z.coerce.number().int().positive(),
+ * })
+ * ```
+ */
+export function defineSegmentParams<C extends Record<string, ParamField>>(
+  codecs: C
+): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {
+  type T = { [K in keyof C]: InferParamField<C[K]> };
+
+  const resolvedCodecs: Record<string, Codec<unknown>> = {};
+
+  for (const [key, value] of Object.entries(codecs)) {
+    resolvedCodecs[key] = resolveField(key, value as ParamField);
+  }
+
+  // Validate that serialize doesn't return null
+  validateSerialize(resolvedCodecs);
+
+  // ---- parse ----
+  function parse(raw: Record<string, string | string[]>): T {
+    const result: Record<string, unknown> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const rawValue = raw[key];
+      // Skip params not present in the URL at this route depth.
+      // This supports TIM-834 inheritance: a parent params.ts can declare
+      // codecs for descendant segments. At shallower depths those params
+      // don't exist yet — skip them instead of passing undefined to the codec.
+      if (rawValue === undefined) continue;
+      result[key] = codec.parse(rawValue);
+    }
+
+    return result as T;
+  }
+
+  // ---- serialize ----
+  function serialize(values: T): Record<string, string> {
+    const result: Record<string, string> = {};
+
+    for (const [key, codec] of Object.entries(resolvedCodecs)) {
+      const serialized = codec.serialize(values[key as keyof T] as unknown);
+      if (serialized === null) {
+        throw new Error(
+          `[timber] params.serialize: field '${key}' serialized to null. ` +
+            `Route params must produce a valid path segment.`
+        );
+      }
+      result[key] = serialized;
+    }
+
+    return result;
+  }
+
+  // ---- get ----
+  // ALS-backed: reads segment params from the current request context.
+  // Server-only, sync.
+  //
+  // The pipeline already coerces params via coerceSegmentParams() which
+  // calls parse() and stores typed values in ALS via setSegmentParams().
+  // We return those directly instead of re-parsing, because codecs may
+  // not be idempotent (e.g., a codec that only accepts raw strings would
+  // throw if given an already-parsed value). See TIM-574.
+  function get(): T {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] segmentParams.get() is server-only. ' +
+          'Use segmentParams.useSegmentParams() on the client.'
+      );
+    }
+    const params = getSegmentParamsFromAls();
+    // params are already coerced by the pipeline — return as-is.
+    return params as unknown as T;
+  }
+
+  // ---- useSegmentParams ----
+  // Client hook that reads typed params from the navigation context.
+  // Delegates to the existing useSegmentParams hook from use-segment-params.ts.
+  function useSegmentParams(): T {
+    const raw = clientUseSegmentParams();
+    // Params are already coerced by the server pipeline before being sent
+    // to the client — return as-is. Re-parsing would break non-idempotent
+    // codecs (e.g., z.coerce.number() on an already-parsed number). See TIM-574.
+    return raw as unknown as T;
+  }
+
+  const definition: ParamsDefinition<T> = {
+    parse,
+    serialize,
+    get,
+    useSegmentParams,
+    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },
+  };
+
+  return definition;
+}

package/src/segment-params/index.ts

@@ -0,0 +1,9 @@
+// @timber-js/app/segment-params — Typed route param coercion
+//
+// This is the import path for defineSegmentParams and related types.
+// For search params, import from @timber-js/app/search-params instead.
+//
+// See design/07-routing.md §"params.ts Convention File"
+
+export type { ParamsDefinition, InferParamField, ParamField } from './define.js';
+export { defineSegmentParams } from './define.js';

package/src/server/access-gate.tsx

@@ -14,9 +14,12 @@
  */
 
 import { DenySignal, RedirectSignal } from './primitives.js';
-import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
+import type { AccessGateProps, SlotAccessGateProps } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
+import type { DenyPageEntry } from './deny-boundary.js';
+import { renderMatchingDenyPage, setDenyStatus } from './deny-boundary.js';
+import type { ReactNode } from 'react';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -34,25 +37,21 @@ import { isDebug } from './debug.js';
  * access.ts is a pure gate — return values are discarded. The layout below
  * gets the same data by calling the same cached functions (React.cache dedup).
  */
-export function AccessGate(props: AccessGateProps): ReactElement | Promise<ReactElement> {
-  const { accessFn, params, searchParams, segmentName, verdict, children } = props;
+export function AccessGate(props: AccessGateProps): ReactNode | Promise<ReactNode> {
+  const { accessFn, segmentName, verdict, denyPages, children } = props;
 
   // Fast path: replay pre-computed verdict from the pre-render pass.
-  // This is synchronous — Suspense boundaries cannot interfere with the
-  // status code because the signal throws before any async work.
   if (verdict !== undefined) {
     if (verdict === 'pass') {
       return children;
     }
-    // Throw the stored DenySignal or RedirectSignal synchronously.
-    // React catches this as a render-phase throw — the flush controller
-    // produces the correct HTTP status code.
     throw verdict;
   }
 
-  // Fallback: call accessFn directly (used by tree-builder.ts which
-  // doesn't run a pre-render pass, and for backward compat).
-  return accessGateFallback(accessFn, params, searchParams, segmentName, children);
+  // Primary path: call accessFn directly during render.
+  // If denyPages is provided, catch DenySignal and render the deny page
+  // in-tree — no throw reaches React Flight, no second render pass.
+  return accessGateFallback(accessFn, segmentName, denyPages, children);
 }
 
 /**
@@ -61,28 +60,41 @@ export function AccessGate(props: AccessGateProps): ReactElement | Promise<React
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
-  params: AccessGateProps['params'],
-  searchParams: AccessGateProps['searchParams'],
   segmentName: AccessGateProps['segmentName'],
-  children: ReactElement
-): Promise<ReactElement> {
-  await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
-    try {
-      await accessFn({ params, searchParams });
-      await setSpanAttribute('timber.result', 'pass');
-    } catch (error: unknown) {
-      if (error instanceof DenySignal) {
-        await setSpanAttribute('timber.result', 'deny');
-        await setSpanAttribute('timber.deny_status', error.status);
-        if (error.sourceFile) {
-          await setSpanAttribute('timber.deny_file', error.sourceFile);
+  denyPages: DenyPageEntry[] | undefined,
+  children: ReactNode
+): Promise<ReactNode> {
+  try {
+    await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
+      try {
+        await accessFn();
+        await setSpanAttribute('timber.result', 'pass');
+      } catch (error: unknown) {
+        if (error instanceof DenySignal) {
+          await setSpanAttribute('timber.result', 'deny');
+          await setSpanAttribute('timber.deny_status', error.status);
+          if (error.sourceFile) {
+            await setSpanAttribute('timber.deny_file', error.sourceFile);
+          }
+        } else if (error instanceof RedirectSignal) {
+          await setSpanAttribute('timber.result', 'redirect');
         }
-      } else if (error instanceof RedirectSignal) {
-        await setSpanAttribute('timber.result', 'redirect');
+        throw error;
+      }
+    });
+  } catch (error: unknown) {
+    // Catch DenySignal and render the deny page in-tree.
+    // No throw reaches React Flight — clean stream, single render pass.
+    // RedirectSignal and other errors propagate normally.
+    if (error instanceof DenySignal && denyPages) {
+      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
+      if (denyElement) {
+        setDenyStatus(error.status);
+        return denyElement;
       }
-      throw error;
     }
-  });
+    throw error;
+  }
 
   return children;
 }
@@ -96,18 +108,27 @@ async function accessGateFallback(
  * The HTTP status code is unaffected — slot denial is a UI concern, not
  * a protocol concern. The parent layout and sibling slots still render.
  *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * DenySignal.data can be forwarded as the dangerouslyPassData prop
+ * and the slot name can be passed as the slot prop. See TIM-488.
+ *
  * redirect() in slot access.ts is a dev-mode error — redirecting from a
  * slot doesn't make architectural sense.
  */
-export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactElement> {
-  const { accessFn, params, searchParams, deniedFallback, defaultFallback, children } = props;
+export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactNode> {
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
   try {
-    await accessFn({ params, searchParams });
+    await accessFn();
   } catch (error: unknown) {
     // DenySignal → graceful degradation (denied.tsx → default.tsx → null)
+    // Build the denied element dynamically so DenySignal.data is forwarded.
     if (error instanceof DenySignal) {
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, error.data, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // RedirectSignal in slot access → dev-mode error.
@@ -123,7 +144,11 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
         );
       }
       // In production, treat as a deny — render fallback rather than crash.
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // Unhandled error — re-throw so error boundaries can catch it.
@@ -141,3 +166,20 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
   // Access passed — render slot content.
   return children;
 }
+
+/**
+ * Build the denied fallback element dynamically with DenySignal data.
+ * Returns null if no DeniedComponent is available.
+ */
+function buildDeniedFallback(
+  DeniedComponent: SlotAccessGateProps['DeniedComponent'],
+  slotName: string,
+  data: unknown,
+  createElement: SlotAccessGateProps['createElement']
+): ReactNode | null {
+  if (!DeniedComponent) return null;
+  return createElement(DeniedComponent, {
+    slot: slotName,
+    dangerouslyPassData: data,
+  });
+}