@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/segment-params/define.ts

@@ -0,0 +1,279 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// 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: (() => Promise<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: () => Promise<Record<string, string | string[]>>): void {
+  _getSegmentParamsFn = fn;
+}
+
+function getSegmentParamsFromAls(): Promise<Record<string, string | string[]>> {
+  if (!_getSegmentParamsFn) {
+    throw new Error(
+      '[timber] segmentParams.get() is only available on the server. ' +
+        'Use 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. Reads getSegmentParams() from ALS and coerces through
+   * this definition's codecs, returning fully typed params.
+   *
+   * ```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 async function Page() {
+   *   const { id } = await segmentParams.get() // id: number
+   * }
+   * ```
+   */
+  get(): Promise<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];
+      // Route params are always present (the route matched)
+      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 — throws on client.
+  //
+  // 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.
+  async function get(): Promise<T> {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] segmentParams.get() is server-only. ' + 'Use useSegmentParams() on the client.'
+      );
+    }
+    const params = await getSegmentParamsFromAls();
+    // params are already coerced by the pipeline — return as-is.
+    return params as unknown as T;
+  }
+
+  const definition: ParamsDefinition<T> = {
+    parse,
+    serialize,
+    get,
+    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

@@ -17,6 +17,8 @@ import { DenySignal, RedirectSignal } from './primitives.js';
 import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
+import type { DenyPageEntry } from './deny-page-resolver.js';
+import { renderMatchingDenyPage, setDenyStatus } from './deny-page-resolver.js';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -35,24 +37,20 @@ import { isDebug } from './debug.js';
  * 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;
+  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 +59,41 @@ export function AccessGate(props: AccessGateProps): ReactElement | Promise<React
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
-  params: AccessGateProps['params'],
-  searchParams: AccessGateProps['searchParams'],
   segmentName: AccessGateProps['segmentName'],
+  denyPages: DenyPageEntry[] | undefined,
   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);
+  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 +107,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;
+  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 +143,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 +165,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']
+): ReactElement | null {
+  if (!DeniedComponent) return null;
+  return createElement(DeniedComponent, {
+    slot: slotName,
+    dangerouslyPassData: data,
+  });
+}

package/src/server/action-client.ts

@@ -138,22 +138,45 @@ export interface ActionBuilder<TCtx> {
   /** Declare the input schema. Validation errors are returned typed. */
   schema<TInput>(schema: ActionSchema<TInput>): ActionBuilderWithSchema<TCtx, TInput>;
   /** Define the action body without input validation. */
-  action<TData>(fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>): ActionFn<TData>;
+  action<TData>(
+    fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>
+  ): ActionFn<undefined, TData>;
 }
 
 /** Builder after .schema() has been called. */
 export interface ActionBuilderWithSchema<TCtx, TInput> {
   /** Define the action body with validated input. */
-  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData>;
+  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TInput, TData>;
 }
 
 /**
- * The final action function. Callable two ways:
+ * The final action function. Callable three ways:
  * - Direct: action(input) → Promise<ActionResult<TData>>
  * - React useActionState: action(prevState, formData) → Promise<ActionResult<TData>>
+ * - React <form action={fn}>: action(formData) → void  (return value ignored by React)
+ *
+ * The third overload exists purely for type compatibility with React's
+ * `<form action>` prop, which expects `(formData: FormData) => void`.
+ * At runtime the function still returns Promise<ActionResult>, but React
+ * discards it. This lets validated actions be passed directly to forms
+ * without casts.
+ */
+/**
+ * Map schema output keys to `string | undefined` for form-facing APIs.
+ * HTML form values are always strings, and fields can be absent.
+ * Gives autocomplete for field names without lying about value types.
  */
-export type ActionFn<TData> = {
-  (input?: unknown): Promise<ActionResult<TData>>;
+export type InputHint<T> =
+  T extends Record<string, unknown> ? { [K in keyof T]: string | undefined } : T;
+
+export type ActionFn<TInput = unknown, TData = unknown> = {
+  /** <form action={fn}> compatibility — React discards the return value. */
+  (formData: FormData): void;
+  /** Direct call: action(input) — optional when TInput is undefined (no-schema actions). */
+  (
+    ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]
+  ): Promise<ActionResult<TData>>;
+  /** React useActionState: action(prevState, formData) */
   (prevState: ActionResult<TData> | null, formData: FormData): Promise<ActionResult<TData>>;
 };
 
@@ -183,8 +206,9 @@ async function runActionMiddleware<TCtx>(
 
 // Re-export parseFormData for use throughout the framework
 import { parseFormData } from './form-data.js';
-import { formatSize } from '#/utils/format.js';
+import { formatSize } from '../utils/format.js';
 import { isDebug, isDevMode } from './debug.js';
+import { RedirectSignal, DenySignal } from './primitives.js';
 
 /**
  * Extract validation errors from a schema error.
@@ -286,7 +310,7 @@ export function createActionClient<TCtx = Record<string, never>>(
   function buildAction<TInput, TData>(
     schema: ActionSchema<TInput> | undefined,
     fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
-  ): ActionFn<TData> {
+  ): ActionFn<TInput, TData> {
     async function actionHandler(...args: unknown[]): Promise<ActionResult<TData>> {
       try {
         // Run middleware
@@ -366,22 +390,33 @@ export function createActionClient<TCtx = Record<string, never>>(
         const data = await fn({ ctx, input });
         return { data };
       } catch (error) {
+        // Re-throw redirect/deny signals — these are control flow, not errors.
+        // They must propagate to executeAction() which converts them to proper
+        // HTTP responses (302 redirect, 4xx deny). Catching them here would
+        // wrap them as INTERNAL_ERROR and break redirect()/redirectExternal()/deny().
+        if (error instanceof RedirectSignal || error instanceof DenySignal) {
+          throw error;
+        }
         return handleActionError(error);
       }
     }
 
-    return actionHandler as ActionFn<TData>;
+    return actionHandler as ActionFn<TInput, TData>;
   }
 
   return {
     schema<TInput>(schema: ActionSchema<TInput>) {
       return {
-        action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData> {
+        action<TData>(
+          fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
+        ): ActionFn<TInput, TData> {
           return buildAction(schema, fn);
         },
       };
     },
-    action<TData>(fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>): ActionFn<TData> {
+    action<TData>(
+      fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>
+    ): ActionFn<undefined, TData> {
       return buildAction(undefined, fn as (ctx: ActionContext<TCtx, unknown>) => Promise<TData>);
     },
   };
@@ -410,7 +445,7 @@ export function createActionClient<TCtx = Record<string, never>>(
 export function validated<TInput, TData>(
   schema: ActionSchema<TInput>,
   handler: (input: TInput) => Promise<TData>
-): ActionFn<TData> {
+): ActionFn<TInput, TData> {
   return createActionClient()
     .schema(schema)
     .action(async ({ input }) => handler(input));