@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/dist/search-params/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/search-params/create.ts","../../src/search-params/codecs.ts","../../src/search-params/builtin-codecs.ts","../../src/search-params/analyze.ts"],"sourcesContent":["/**\n * createSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Supports codec protocol, URL key aliasing, default-omission serialization,\n * and composition via .extend() / .pick().\n *\n * Design doc: design/09-typescript.md §\"Typed searchParams — search-params.ts\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '#/client/use-query-states.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * nuqs parsers (parseAsInteger, parseAsString, etc.) implement this\n * interface natively — no adapter needed.\n */\nexport interface SearchParamCodec<T> {\n  /** URL string → typed value. Receives undefined when the param is absent. */\n  parse(value: string | string[] | undefined): T;\n  /** Typed value → URL string. Return null to omit from URL. */\n  serialize(value: T): string | null;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/** Options for useQueryStates setter. */\nexport interface SetParamsOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/** Options for useQueryStates hook. */\nexport interface QueryStatesOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/** Options for createSearchParams and .extend(). */\nexport interface SearchParamsOptions<Keys extends string = string> {\n  /** Map property names to different URL query parameter keys. */\n  urlKeys?: Partial<Record<Keys, string>>;\n}\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by createSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw URL search params into typed values. */\n  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n\n  /** Client hook — reads current URL params and returns typed values + setter. */\n  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n  /** Extend with additional codecs. Key collisions are a type error. */\n  extend<U extends Record<string, SearchParamCodec<unknown>>>(\n    codecs: U,\n    options?: SearchParamsOptions<string>\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferCodec<U[K]> }>;\n\n  /** Pick a subset of keys. Preserves codecs and aliases. */\n  pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n  /** Serialize values to a query string (no leading '?'), omitting defaults. */\n  serialize(values: Partial<T>): string;\n\n  /** Build a full path with query string, omitting defaults. */\n  href(pathname: string, values: Partial<T>): string;\n\n  /** Build a URLSearchParams instance, omitting defaults. */\n  toSearchParams(values: Partial<T>): URLSearchParams;\n\n  /** Read-only codec map for spreading into .extend(). Aliases NOT carried. */\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n  readonly urlKeys: Readonly<Record<string, string>>;\n\n  /**\n   * Phantom property for build-time type extraction.\n   * Never set at runtime — exists only in the type system.\n   */\n  readonly _type?: T;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n  raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n  if (raw instanceof URLSearchParams) {\n    const result: Record<string, string | string[] | undefined> = {};\n    for (const key of new Set(raw.keys())) {\n      const values = raw.getAll(key);\n      result[key] = values.length === 1 ? values[0] : values;\n    }\n    return result;\n  }\n  return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n */\nfunction getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {\n  return codec.serialize(codec.parse(undefined));\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a codec map and optional URL key aliases.\n *\n * ```ts\n * import { createSearchParams, fromSchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * export default createSearchParams({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n *   q: { parse: (v) => v ?? null, serialize: (v) => v },\n * }, {\n *   urlKeys: { q: 'search' },\n * })\n * ```\n */\nexport function createSearchParams<C extends Record<string, SearchParamCodec<unknown>>>(\n  codecs: C,\n  options?: SearchParamsOptions<Extract<keyof C, string>>\n): SearchParamsDefinition<{ [K in keyof C]: InferCodec<C[K]> }> {\n  type T = { [K in keyof C]: InferCodec<C[K]> };\n  const urlKeys: Record<string, string> = {};\n  if (options?.urlKeys) {\n    for (const [k, v] of Object.entries(options.urlKeys)) {\n      if (v !== undefined) urlKeys[k] = v;\n    }\n  }\n\n  return buildDefinition<T>(codecs as unknown as CodecMap<T>, urlKeys);\n}\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n  codecMap: CodecMap<T>,\n  urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n  // Pre-compute default serialized values for omission check\n  const defaultSerialized: Record<string, string | null> = {};\n  for (const key of Object.keys(codecMap)) {\n    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n  }\n\n  function getUrlKey(prop: string): string {\n    return urlKeys[prop] ?? prop;\n  }\n\n  // ---- parse ----\n  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n    const normalized = normalizeRaw(raw);\n    const result: Record<string, unknown> = {};\n\n    for (const prop of Object.keys(codecMap)) {\n      const urlKey = getUrlKey(prop);\n      const rawValue = normalized[urlKey];\n      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // ---- serialize ----\n  function serialize(values: Partial<T>): string {\n    const parts: string[] = [];\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      // Omit if serialized value matches the default\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = serialize(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- toSearchParams ----\n  function toSearchParams(values: Partial<T>): URLSearchParams {\n    const usp = new URLSearchParams();\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      usp.set(getUrlKey(prop), serialized);\n    }\n\n    return usp;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamCodec<unknown>>>(\n    newCodecs: U,\n    extendOptions?: SearchParamsOptions<string>\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferCodec<U[K]> }> {\n    type Combined = T & { [K in keyof U]: InferCodec<U[K]> };\n\n    const combinedCodecs = {\n      ...codecMap,\n      ...newCodecs,\n    } as unknown as CodecMap<Combined>;\n\n    // Merge URL keys: extend options override, but do NOT inherit from base\n    // (aliases are route-level, not carried through .codecs)\n    const combinedUrlKeys: Record<string, string> = { ...urlKeys };\n    if (extendOptions?.urlKeys) {\n      for (const [k, v] of Object.entries(extendOptions.urlKeys)) {\n        if (v !== undefined) combinedUrlKeys[k] = v;\n      }\n    }\n\n    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n  }\n\n  // ---- pick ----\n  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const pickedUrlKeys: Record<string, string> = {};\n\n    for (const key of keys) {\n      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n      if (key in urlKeys) {\n        pickedUrlKeys[key] = urlKeys[key];\n      }\n    }\n\n    return buildDefinition<Pick<T, K>>(\n      pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n      pickedUrlKeys\n    );\n  }\n\n  // ---- useQueryStates ----\n  // Delegates to the 'use client' implementation from use-query-states.ts.\n  //\n  // In the RSC environment: use-query-states.ts is transformed by the RSC\n  //   plugin into a client reference proxy. Calling it throws — correct,\n  //   because hooks can't run during server component rendering.\n  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n  //   work during SSR's renderToReadableStream, so this works correctly.\n  // On the client: same as SSR — the real function is available.\n  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n      T,\n      SetParams<T>,\n    ];\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    useQueryStates,\n    extend,\n    pick,\n    serialize,\n    href,\n    toSearchParams,\n    codecs: codecMap,\n    urlKeys: Object.freeze({ ...urlKeys }),\n  };\n\n  return definition;\n}\n","/**\n * Built-in codecs and the fromSchema bridge for Standard Schema-compatible\n * validation libraries (Zod, Valibot, ArkType).\n *\n * Design doc: design/09-typescript.md §\"The SearchParamCodec Protocol\"\n */\n\nimport type { SearchParamCodec } from './create.js';\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We depend only on `~standard.validate` to avoid coupling to any specific lib.\n// ---------------------------------------------------------------------------\n\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\ntype StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };\n\n// ---------------------------------------------------------------------------\n// Sync validate helper\n// ---------------------------------------------------------------------------\n\n/**\n * Zod v4's ~standard.validate() signature includes Promise in the return union\n * to satisfy the Standard Schema spec, but in practice Zod always validates\n * synchronously for the schema types we use. We assert the result is sync and\n * throw if it isn't — search params parsing must be synchronous.\n */\nfunction validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n): StandardSchemaResult<Output> {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'\n    );\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// fromSchema — bridge from Standard Schema to SearchParamCodec\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a\n * SearchParamCodec.\n *\n * Parse: coerces the raw URL string through the schema. On validation failure,\n * parses `undefined` to get the schema's default value (the schema should have\n * a `.default()` call). If that also fails, returns `undefined`.\n *\n * Serialize: uses `String()` for primitives, `null` for null/undefined.\n *\n * ```ts\n * import { fromSchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))\n * ```\n */\nexport function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // For array inputs, take the last value (consistent with URLSearchParams.get())\n      const input = Array.isArray(value) ? value[value.length - 1] : value;\n\n      // Try parsing the raw value\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try parsing undefined to get the default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      // No default available — return undefined (codec design choice)\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// fromArraySchema — bridge for array-valued search params\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema for array values. Handles both single strings\n * and repeated query keys (`?tag=a&tag=b`).\n *\n * ```ts\n * import { fromArraySchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))\n * ```\n */\nexport function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Coerce single string to array for array schemas\n      let input: unknown = value;\n      if (typeof value === 'string') {\n        input = [value];\n      } else if (value === undefined) {\n        input = undefined;\n      }\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try undefined for default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      if (Array.isArray(value)) {\n        return value.length === 0 ? null : value.join(',');\n      }\n      return String(value);\n    },\n  };\n}\n","/**\n * Built-in search param codecs for common types.\n *\n * These provide zero-dependency alternatives to nuqs parsers for the most\n * common cases: strings, integers, floats, booleans, and string enums.\n *\n * All codecs implement SearchParamCodec<T | null> — returning null when the\n * param is absent or unparseable. Use withDefault() to replace null with a\n * concrete fallback value.\n *\n * Design doc: design/23-search-params.md §\"Identified Gaps\" #1\n * Task: TIM-362\n */\n\nimport type { SearchParamCodec } from './create.js';\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Normalize array inputs to a single string (last value wins, matching\n * URLSearchParams.get() semantics). Returns undefined if absent or empty.\n */\nfunction normalizeInput(value: string | string[] | undefined): string | undefined {\n  if (Array.isArray(value)) {\n    return value.length > 0 ? value[value.length - 1] : undefined;\n  }\n  return value;\n}\n\n// ---------------------------------------------------------------------------\n// parseAsString\n// ---------------------------------------------------------------------------\n\n/**\n * String codec. Returns the raw string value, or null if absent.\n *\n * ```ts\n * import { parseAsString } from '@timber-js/app/search-params'\n *\n * const def = createSearchParams({ q: parseAsString })\n * // ?q=shoes → { q: 'shoes' }\n * // (absent) → { q: null }\n * ```\n */\nexport const parseAsString: SearchParamCodec<string | null> = {\n  parse(value: string | string[] | undefined): string | null {\n    const v = normalizeInput(value);\n    return v !== undefined ? v : null;\n  },\n  serialize(value: string | null): string | null {\n    return value;\n  },\n};\n\n// ---------------------------------------------------------------------------\n// parseAsInteger\n// ---------------------------------------------------------------------------\n\n/**\n * Integer codec. Parses a base-10 integer, or returns null if absent or\n * not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.\n *\n * ```ts\n * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'\n *\n * const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })\n * // ?page=2 → { page: 2 }\n * // ?page=abc → { page: 1 }\n * // (absent) → { page: 1 }\n * ```\n */\nexport const parseAsInteger: SearchParamCodec<number | null> = {\n  parse(value: string | string[] | undefined): number | null {\n    const v = normalizeInput(value);\n    if (v === undefined || v === '') return null;\n    const n = Number(v);\n    if (!Number.isFinite(n) || !Number.isInteger(n)) return null;\n    return n;\n  },\n  serialize(value: number | null): string | null {\n    return value === null ? null : String(value);\n  },\n};\n\n// ---------------------------------------------------------------------------\n// parseAsFloat\n// ---------------------------------------------------------------------------\n\n/**\n * Float codec. Parses a finite number, or returns null if absent or invalid.\n * Rejects NaN and Infinity.\n *\n * ```ts\n * import { parseAsFloat, withDefault } from '@timber-js/app/search-params'\n *\n * const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })\n * ```\n */\nexport const parseAsFloat: SearchParamCodec<number | null> = {\n  parse(value: string | string[] | undefined): number | null {\n    const v = normalizeInput(value);\n    if (v === undefined || v === '') return null;\n    const n = Number(v);\n    if (!Number.isFinite(n)) return null;\n    return n;\n  },\n  serialize(value: number | null): string | null {\n    return value === null ? null : String(value);\n  },\n};\n\n// ---------------------------------------------------------------------------\n// parseAsBoolean\n// ---------------------------------------------------------------------------\n\n/**\n * Boolean codec. Accepts \"true\"/\"1\" as true, \"false\"/\"0\" as false.\n * Returns null for absent or unrecognized values.\n *\n * ```ts\n * import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'\n *\n * const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })\n * // ?debug=true → { debug: true }\n * // ?debug=0 → { debug: false }\n * ```\n */\nexport const parseAsBoolean: SearchParamCodec<boolean | null> = {\n  parse(value: string | string[] | undefined): boolean | null {\n    const v = normalizeInput(value);\n    if (v === undefined) return null;\n    if (v === 'true' || v === '1') return true;\n    if (v === 'false' || v === '0') return false;\n    return null;\n  },\n  serialize(value: boolean | null): string | null {\n    return value === null ? null : String(value);\n  },\n};\n\n// ---------------------------------------------------------------------------\n// parseAsStringEnum\n// ---------------------------------------------------------------------------\n\n/**\n * String enum codec. Accepts only values in the provided list.\n * Returns null for absent or invalid values.\n *\n * ```ts\n * import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'\n *\n * const sortCodec = withDefault(\n *   parseAsStringEnum(['price', 'name', 'date']),\n *   'date'\n * )\n * ```\n */\nexport function parseAsStringEnum<T extends string>(\n  values: readonly T[]\n): SearchParamCodec<T | null> {\n  const allowed = new Set<string>(values);\n  return {\n    parse(value: string | string[] | undefined): T | null {\n      const v = normalizeInput(value);\n      if (v === undefined) return null;\n      return allowed.has(v) ? (v as T) : null;\n    },\n    serialize(value: T | null): string | null {\n      return value;\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// parseAsStringLiteral\n// ---------------------------------------------------------------------------\n\n/**\n * String literal codec. Functionally identical to parseAsStringEnum but\n * accepts `as const` tuples for narrower type inference.\n *\n * ```ts\n * import { parseAsStringLiteral } from '@timber-js/app/search-params'\n *\n * const sizes = ['sm', 'md', 'lg', 'xl'] as const\n * const codec = parseAsStringLiteral(sizes)\n * // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>\n * ```\n */\nexport function parseAsStringLiteral<const T extends readonly string[]>(\n  values: T\n): SearchParamCodec<T[number] | null> {\n  // Delegates to parseAsStringEnum — same runtime behavior, different type\n  return parseAsStringEnum<T[number]>(values);\n}\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * ```ts\n * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n","/**\n * Static analyzability checker for search-params.ts files.\n *\n * Validates that a search-params.ts file's default export is statically\n * analyzable — a createSearchParams() call or a chain of .extend()/.pick()\n * calls on a SearchParamsDefinition.\n *\n * Non-analyzable files produce a hard build error with a diagnostic.\n *\n * Design doc: design/09-typescript.md §\"Static Analyzability\"\n */\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Result of analyzing a search-params.ts file. */\nexport interface AnalyzeResult {\n  /** Whether the file is statically analyzable. */\n  valid: boolean;\n  /** Error details when valid is false. */\n  error?: AnalyzeError;\n}\n\n/** Diagnostic error for non-analyzable search-params.ts. */\nexport interface AnalyzeError {\n  /** Absolute file path. */\n  filePath: string;\n  /** Description of the non-analyzable expression. */\n  expression: string;\n  /** Suggested fix. */\n  suggestion: string;\n}\n\n// ---------------------------------------------------------------------------\n// AST-free source analysis\n//\n// We use a lightweight regex-based approach to validate the structure of the\n// default export. This avoids requiring a TypeScript compiler instance at\n// build time for the initial validation pass. The full type extraction\n// (reading T from SearchParamsDefinition<T>) still happens via the TypeScript\n// compiler in the codegen step — this module just validates the *shape*.\n// ---------------------------------------------------------------------------\n\n/**\n * Patterns that indicate a valid default export:\n *\n * 1. `export default createSearchParams(...)`\n * 2. `export default someVar.extend(...)`\n * 3. `export default someVar.pick(...)`\n * 4. `export default someVar.extend(...).extend(...)`  (chained)\n * 5. `export default someVar.extend(...).pick(...)`    (chained)\n * 6. `export default createSearchParams(...).extend(...)`\n *\n * Invalid patterns:\n * - `export default someFunction(...)` (arbitrary factory)\n * - `export default condition ? a : b` (runtime conditional)\n * - `export default variable` (opaque reference without call)\n */\n\n/**\n * Analyze a search-params.ts file source for static analyzability.\n *\n * @param source - The file content as a string\n * @param filePath - Absolute path to the file (for diagnostics)\n */\nexport function analyzeSearchParams(source: string, filePath: string): AnalyzeResult {\n  // Strip comments to avoid false matches\n  const stripped = stripComments(source);\n\n  // Find the default export\n  const defaultExport = extractDefaultExport(stripped);\n\n  if (!defaultExport) {\n    return {\n      valid: false,\n      error: {\n        filePath,\n        expression: '(no default export found)',\n        suggestion:\n          'search-params.ts must have a default export. Use: export default createSearchParams({ ... })',\n      },\n    };\n  }\n\n  // Validate the expression\n  if (isValidExpression(defaultExport.trim())) {\n    return { valid: true };\n  }\n\n  return {\n    valid: false,\n    error: {\n      filePath,\n      expression: defaultExport.trim(),\n      suggestion:\n        'The default export must be a createSearchParams() call, or a chain of ' +\n        '.extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory ' +\n        'functions and runtime conditionals are not supported.',\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/** Strip single-line and multi-line comments from source. */\nfunction stripComments(source: string): string {\n  // Remove multi-line comments\n  let result = source.replace(/\\/\\*[\\s\\S]*?\\*\\//g, '');\n  // Remove single-line comments\n  result = result.replace(/\\/\\/.*$/gm, '');\n  return result;\n}\n\n/**\n * Extract the expression from `export default <expr>`.\n *\n * Handles both:\n *   export default createSearchParams(...)\n *   export default expr\\n (terminated by newline or semicolon before next statement)\n */\nfunction extractDefaultExport(source: string): string | undefined {\n  // Match `export default` followed by the expression\n  const match = source.match(\n    /export\\s+default\\s+([\\s\\S]+?)(?:;|\\n(?=export|import|const|let|var|function|class|type|interface|declare))/\n  );\n  if (match) {\n    return match[1];\n  }\n\n  // Fallback: match everything after `export default` to end of file\n  const fallback = source.match(/export\\s+default\\s+([\\s\\S]+)$/);\n  if (fallback) {\n    return fallback[1].replace(/;\\s*$/, '');\n  }\n\n  return undefined;\n}\n\n/**\n * Check if an expression is a valid statically-analyzable pattern.\n *\n * Valid patterns:\n * - Starts with `createSearchParams(`\n * - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)\n * - A variable identifier followed by chaining\n */\nfunction isValidExpression(expr: string): boolean {\n  // Normalize whitespace\n  const normalized = expr.replace(/\\s+/g, ' ').trim();\n\n  // Pattern 1: starts with createSearchParams(\n  if (normalized.startsWith('createSearchParams(')) {\n    return true;\n  }\n\n  // Pattern 2: chain ending with .extend(...) or .pick(...)\n  // This covers: someVar.extend(...), createSearchParams(...).extend(...).pick(...), etc.\n  if (/\\.(extend|pick)\\s*\\(/.test(normalized)) {\n    // Reject ternaries and other conditional patterns\n    if (/\\?/.test(normalized) && /:/.test(normalized)) {\n      return false;\n    }\n    // Reject function declarations/expressions\n    if (/^\\s*(function|=>|\\()/.test(normalized)) {\n      return false;\n    }\n    return true;\n  }\n\n  return false;\n}\n\n/**\n * Format an AnalyzeError into a human-readable build error message.\n */\nexport function formatAnalyzeError(error: AnalyzeError): string {\n  return [\n    `[timber] Non-analyzable search-params.ts`,\n    ``,\n    `  File: ${error.filePath}`,\n    `  Expression: ${error.expression}`,\n    ``,\n    `  ${error.suggestion}`,\n    ``,\n    `  The framework must be able to statically extract the type from your`,\n    `  search-params.ts at build time. Dynamic values, conditionals, and`,\n    `  arbitrary factory functions prevent this analysis.`,\n  ].join('\\n');\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n *   q: withUrlKey(parseAsString, 'search'),\n *   // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<T>(\n  codec: SearchParamCodec<T>,\n  urlKey: string\n): SearchParamCodecWithUrlKey<T> {\n  return {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA+BA,SAAgB,YACd,OACA,cACqB;AACrB,QAAO;EACL,MAAM,OAAyC;GAC7C,MAAM,SAAS,MAAM,MAAM,MAAM;AACjC,UAAO,WAAW,OAAO,eAAe;;EAE1C,UAAU,OAAyB;AACjC,UAAO,MAAM,UAAU,MAAM;;EAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCH,SAAgB,WACd,OACA,QAC+B;AAC/B,QAAO;EACL,OAAO,MAAM,MAAM,KAAK,MAAM;EAC9B,WAAW,MAAM,UAAU,KAAK,MAAM;EACtC;EACD"}

package/dist/search-params/registry.d.ts

@@ -6,7 +6,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';
 /**
  * Register a route's search params definition.
  * Called by the generated route manifest loader when a route's modules load.
@@ -16,5 +16,5 @@ export declare function registerSearchParams(route: string, definition: SearchPa
  * Look up a route's search params definition.
  * Returns undefined if the route hasn't been loaded yet.
  */
-export declare function getSearchParams(route: string): SearchParamsDefinition<any> | undefined;
+export declare function getSearchParamsDefinition(route: string): SearchParamsDefinition<any> | undefined;
 //# sourceMappingURL=registry.d.ts.map

package/dist/search-params/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/search-params/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAK1D;;;GAGG;AAEH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,CAAC,GAAG,CAAC,GAAG,IAAI,CAEjG;AAED;;;GAGG;AAEH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAAC,GAAG,CAAC,GAAG,SAAS,CAEtF"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/search-params/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAK1D;;;GAGG;AAEH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,CAAC,GAAG,CAAC,GAAG,IAAI,CAEjG;AAED;;;GAGG;AAEH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAAC,GAAG,CAAC,GAAG,SAAS,CAEhG"}

package/dist/search-params/wrappers.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 } from './define.js';
+/**
+ * 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 declare function withDefault<T>(codec: SearchParamCodec<T | null>, defaultValue: T): SearchParamCodec<T>;
+/**
+ * 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 declare function withUrlKey<T>(codec: SearchParamCodec<T>, urlKey: string): SearchParamCodecWithUrlKey<T>;
+//# sourceMappingURL=wrappers.d.ts.map

package/dist/search-params/wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers.d.ts","sourceRoot":"","sources":["../../src/search-params/wrappers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAMhF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,gBAAgB,CAAC,CAAC,GAAG,IAAI,CAAC,EACjC,YAAY,EAAE,CAAC,GACd,gBAAgB,CAAC,CAAC,CAAC,CAUrB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,0BAA0B,CAAC,CAAC,CAAC,CAM/B"}

package/dist/segment-params/define.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 } from '../schema-bridge.js';
+/**
+ * Register the getSegmentParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export declare function _setGetSegmentParamsFn(fn: () => Promise<Record<string, string | string[]>>): void;
+/** 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]>;
+    };
+}
+/**
+ * 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 declare function defineSegmentParams<C extends Record<string, ParamField>>(codecs: C): ParamsDefinition<{
+    [K in keyof C]: InferParamField<C[K]>;
+}>;
+//# sourceMappingURL=define.d.ts.map

package/dist/segment-params/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/segment-params/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,KAAK,gBAAgB,EAItB,MAAM,qBAAqB,CAAC;AAU7B;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,CAEjG;AAgBD,8DAA8D;AAC9D,MAAM,MAAM,eAAe,CAAC,CAAC,IAC3B,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,gBAAgB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEjF,6EAA6E;AAC7E,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAErE,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,2EAA2E;IAC3E,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IAEjD,mEAAmE;IACnE,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAElB,2BAA2B;IAC3B,MAAM,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAAE,CAAC;CACzC;AA+FD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACtE,MAAM,EAAE,CAAC,GACR,gBAAgB,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,CAuE7D"}

package/dist/segment-params/index.d.ts

@@ -0,0 +1,3 @@
+export type { ParamsDefinition, InferParamField, ParamField } from './define.js';
+export { defineSegmentParams } from './define.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/segment-params/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/segment-params/index.ts"],"names":[],"mappings":"AAOA,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/segment-params/index.js

@@ -0,0 +1,2 @@
+import { n as defineSegmentParams } from "../_chunks/define-C77ScO0m.js";
+export { defineSegmentParams };

package/dist/server/access-gate.d.ts

@@ -35,6 +35,10 @@ export declare function AccessGate(props: AccessGateProps): ReactElement | Promi
  * 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.
  */

package/dist/server/access-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access-gate.d.ts","sourceRoot":"","sources":["../../src/server/access-gate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAM5F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBvF;AAoCD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAyCtF"}
+{"version":3,"file":"access-gate.d.ts","sourceRoot":"","sources":["../../src/server/access-gate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAQ5F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAevF;AAiDD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkDtF"}

package/dist/server/action-client.d.ts

@@ -116,28 +116,63 @@ interface ActionClientConfig<TCtx> {
     middleware?: ActionMiddleware<TCtx> | ActionMiddleware<Record<string, unknown>>[];
     /** Max file size in bytes. Files exceeding this are rejected with validation errors. */
     fileSizeLimit?: number;
+    /**
+     * Override the sensitive-field deny-list for this action client.
+     * See `SensitiveFieldsOption` in `./sensitive-fields.ts`. Per-action config
+     * takes precedence over the global `forms.stripSensitiveFields` option in
+     * `timber.config.ts`. See design/08-forms-and-actions.md and TIM-816.
+     */
+    stripSensitiveFields?: SensitiveFieldsOption;
 }
 /** Intermediate builder returned by createActionClient(). */
 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<TData, undefined>;
 }
 /** 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<TData, TInput>;
 }
 /**
- * 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 InputHint<T> = T extends Record<string, unknown> ? {
+    [K in keyof T]: string | undefined;
+} : T;
+/**
+ * ActionFn — the callable returned by `createActionClient().action()`.
+ *
+ * Generic order: `<TData, TInput>` — TData first for backward compatibility.
+ * Previously ActionFn had a single `<TData>` generic, so existing code like
+ * `ActionFn<MyResult>` must still work with TData in the first position.
+ * See TIM-797.
  */
-export type ActionFn<TData> = {
-    (input?: unknown): Promise<ActionResult<TData>>;
+export type ActionFn<TData = unknown, TInput = unknown> = {
+    /** <form action={fn}> compatibility — React discards the return value. */
+    (formData: FormData): void;
+    /** Direct call: action(input) — optional when TInput is undefined/unknown (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>>;
 };
+import { type SensitiveFieldsOption } from './sensitive-fields.js';
 /**
  * Wrap unexpected errors into a safe server error result.
  * ActionError → typed result. Other errors → INTERNAL_ERROR (no leak).
@@ -185,6 +220,6 @@ export declare function createActionClient<TCtx = Record<string, never>>(config?
  * )
  * ```
  */
-export declare function validated<TInput, TData>(schema: ActionSchema<TInput>, handler: (input: TInput) => Promise<TData>): ActionFn<TData>;
+export declare function validated<TInput, TData>(schema: ActionSchema<TInput>, handler: (input: TInput) => Promise<TData>): ActionFn<TData, TInput>;
 export {};
 //# sourceMappingURL=action-client.d.ts.map

package/dist/server/action-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-client.d.ts","sourceRoot":"","sources":["../../src/server/action-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"action-client.d.ts","sourceRoot":"","sources":["../../src/server/action-client.ts"],"names":[],"mappings":"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"}

package/dist/server/action-encryption.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Server action bound args encryption utilities.
+ *
+ * Provides key management for the RSC plugin's built-in bound args encryption.
+ * The RSC plugin (@vitejs/plugin-rsc) handles the actual encrypt/decrypt via
+ * AES-256-GCM — this module handles:
+ *
+ * 1. Key sourcing: auto-generated at build time (embedded in bundle), overridable
+ *    via env var for cross-build key sharing (rolling/blue-green deployments)
+ * 2. Build-time key expression generation for the RSC plugin's `defineEncryptionKey`
+ *
+ * Encryption is always on in production. In dev mode, it's on by default
+ * (matching the RSC plugin's behavior) but can be disabled for debugging.
+ *
+ * ## Known Security Considerations
+ *
+ * 1. **defineEncryptionKey is a raw JS expression.** The RSC plugin inlines it
+ *    verbatim into generated code. We only emit the hardcoded string
+ *    `process.env.TIMBER_ACTIONS_ENCRYPTION_KEY` — never user-controlled input.
+ *    If this function is ever extended to accept configurable env var names,
+ *    the expression MUST be validated against a safe pattern.
+ *
+ * 2. **Key material lives in GC-visible JS strings.** `atob()` decodes the key
+ *    into a regular JavaScript string on the V8 heap. JavaScript has no
+ *    `SecureString` or memory-zeroing primitive — this is an inherent platform
+ *    limitation. Acceptable for web server use; would need review for FIPS.
+ *
+ * 3. **TIMBER_ACTIONS_ENCRYPTION_KEY must be set at both build time and runtime.**
+ *    At build time, we validate the key format and emit a runtime expression.
+ *    If the env var is present at build time but missing at runtime, the server
+ *    will crash on first action invocation with an opaque `atob(undefined)` error.
+ *    If the env var is present at runtime but was absent at build time, the RSC
+ *    plugin will have generated its own key and the env var is silently ignored.
+ *
+ * See design/08-forms-and-actions.md §"Security"
+ * See design/13-security.md
+ */
+/** User-facing configuration for action bound args encryption. */
+export interface ActionEncryptionConfig {
+    /**
+     * Disable encryption in dev mode for easier debugging.
+     * Has no effect in production — encryption is always enabled.
+     * Default: false (encryption is on in dev too).
+     */
+    disableInDev?: boolean;
+}
+/**
+ * Build the `defineEncryptionKey` expression for the RSC plugin.
+ *
+ * The RSC plugin accepts a JavaScript expression string that will be
+ * inlined into the encryption runtime module. At runtime, this expression
+ * must evaluate to the base64-encoded encryption key.
+ *
+ * Priority:
+ * 1. `TIMBER_ACTIONS_ENCRYPTION_KEY` env var (for cross-build key sharing
+ *    in rolling/blue-green deployments)
+ * 2. Auto-generated at build time (RSC plugin default — embedded in bundle,
+ *    consistent across all instances of the same build)
+ *
+ * For env var keys, we generate a runtime expression that reads the env var.
+ * For auto-generated keys, we return undefined and let the RSC plugin handle it.
+ */
+export declare function resolveEncryptionKeyExpression(): string | undefined;
+/**
+ * Determine whether action encryption should be enabled.
+ *
+ * Encryption is always enabled in production. In dev mode, it's enabled
+ * by default but can be disabled via config for debugging.
+ */
+export declare function shouldEnableEncryption(isDev: boolean, config?: ActionEncryptionConfig): boolean;
+/**
+ * Validate that a key string is a valid base64-encoded 256-bit key.
+ * Throws a descriptive error if the key is malformed.
+ */
+export declare function validateKeyFormat(key: string): void;
+//# sourceMappingURL=action-encryption.d.ts.map

package/dist/server/action-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-encryption.d.ts","sourceRoot":"","sources":["../../src/server/action-encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAwBnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAI/F;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBnD"}

package/dist/server/action-handler.d.ts

@@ -15,6 +15,7 @@
 import { type CsrfConfig } from './csrf.js';
 import { type RevalidateRenderer } from './actions.js';
 import { type BodyLimitsConfig } from './body-limits.js';
+import { type SensitiveFieldsOption } from './sensitive-fields.js';
 import type { FormFlashData } from './form-flash.js';
 /** Configuration for the action handler. */
 export interface ActionDispatchConfig {
@@ -24,6 +25,12 @@ export interface ActionDispatchConfig {
     revalidateRenderer?: RevalidateRenderer;
     /** Body size limits (from timber.config.ts). */
     bodyLimits?: BodyLimitsConfig;
+    /**
+     * Override the sensitive-field deny-list for the no-JS form POST path.
+     * Defaults to the global `forms.stripSensitiveFields` from `timber.config.ts`.
+     * See `SensitiveFieldsOption` in `./sensitive-fields.ts` and TIM-816.
+     */
+    sensitiveFields?: SensitiveFieldsOption;
 }
 /**
  * Check if a request is a server action invocation.

package/dist/server/action-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-handler.d.ts","sourceRoot":"","sources":["../../src/server/action-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,gDAAgD;IAChD,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAQD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAarD;AAID,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC,CAwCzC"}
+{"version":3,"file":"action-handler.d.ts","sourceRoot":"","sources":["../../src/server/action-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOtE,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EAIL,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAMrD,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,gDAAgD;IAChD,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAC;CACzC;AAQD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAarD;AAID,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,GAAG,YAAY,GAAG,IAAI,CAAC,CAuDzC"}

package/dist/server/actions.d.ts

@@ -3,7 +3,7 @@
  *
  * - revalidatePath(path) re-renders the route at that path and returns the RSC
  *   flight payload for inline reconciliation.
- * - revalidateTag(tag) invalidates cached shells and 'use cache' entries by tag.
+ * - revalidateTag(tag) invalidates timber.cache entries by tag.
  *
  * Both are callable from anywhere on the server — actions, API routes, handlers.
  *
@@ -13,7 +13,6 @@
  *
  * See design/08-forms-and-actions.md
  */
-import type { CacheHandler } from '#/cache/index';
 import { type RevalidationState } from './als-registry.js';
 /** Result of rendering a revalidation — element tree before RSC serialization. */
 export interface RevalidationResult {
@@ -27,8 +26,6 @@ export type RevalidateRenderer = (path: string) => Promise<RevalidationResult>;
 export type { RevalidationState } from './als-registry.js';
 /** Options for creating the action handler. */
 export interface ActionHandlerConfig {
-    /** Cache handler for tag invalidation. */
-    cacheHandler?: CacheHandler;
     /** Renderer for producing RSC payloads during revalidation. */
     renderer?: RevalidateRenderer;
 }
@@ -63,8 +60,8 @@ export declare function _clearRevalidationState(): void;
  */
 export declare function revalidatePath(path: string): void;
 /**
- * Invalidate all pre-rendered shells and 'use cache' entries tagged with `tag`.
- * Does not return a payload — the next request for an invalidated route re-renders fresh.
+ * Invalidate all timber.cache entries tagged with `tag`.
+ * Does not return a payload — the next request for an invalidated entry re-executes.
  *
  * @param tag - The cache tag to invalidate (e.g. 'products', 'user:123').
  */

package/dist/server/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/server/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI5E,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAG/E,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;IACtB,2FAA2F;IAC3F,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAIpE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAmBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK/C;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAClD,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,GAAE,mBAAwB,EAChC,QAAQ,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC,mBAAmB,CAAC,CA0D9B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY,GAAG,QAAQ,CAKtF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIxD"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../src/server/actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI5E,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAG/E,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;IACtB,2FAA2F;IAC3F,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAIpE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAmBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKjD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK/C;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAClD,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,GAAE,mBAAwB,EAChC,QAAQ,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC,mBAAmB,CAAC,CA6D9B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,MAAY,GAAG,QAAQ,CAKtF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIxD"}

package/dist/server/als-registry.d.ts

@@ -20,6 +20,7 @@
  * §"Singleton State Registry".
  */
 import { AsyncLocalStorage } from 'node:async_hooks';
+import type { DebugComponentEntry } from './rsc-entry/helpers.js';
 /** @internal — import via request-context.ts public API */
 export declare const requestContextAls: AsyncLocalStorage<RequestContextStore>;
 export interface RequestContextStore {
@@ -32,17 +33,44 @@ export interface RequestContextStore {
     /** Original (pre-overlay) frozen headers, kept for overlay merging. */
     originalHeaders: Headers;
     /**
-     * Promise resolving to the route's typed search params (when search-params.ts
-     * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-     * can later support partial pre-rendering where param resolution is deferred.
+     * Promise resolving to the raw URLSearchParams for the current request.
+     * To get typed parsed params, import a search params definition and
+     * call `.parse(searchParams())`.
      */
-    searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+    searchParamsPromise: Promise<URLSearchParams>;
+    /**
+     * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+     * Available synchronously for use in `redirect()` with `preserveSearchParams`.
+     */
+    searchString: string;
+    /**
+     * Promise resolving to the coerced segment params for the current request.
+     * Set by the pipeline after route matching and param coercion, before
+     * middleware and rendering. Pages and layouts read params via
+     * `getSegmentParams()` instead of receiving them as a prop.
+     *
+     * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+     */
+    segmentParamsPromise?: Promise<Record<string, string | string[]>>;
     /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
     cookieJar: Map<string, CookieEntry>;
     /** Whether the response has flushed (headers committed). */
     flushed: boolean;
     /** Whether the current context allows cookie mutation. */
     mutableContext: boolean;
+    /**
+     * Set by AccessGate or PageDenyBoundary when a DenySignal is caught
+     * server-side (inside the React tree, before React Flight sees it).
+     * The pipeline reads this after render to set the HTTP status code.
+     * See TIM-666.
+     */
+    denyStatus?: number;
+    /**
+     * Dev-only: getter for the current request's RSC debug components.
+     * Set by renderRoute() so onPipelineError can include component tree
+     * context for render-phase errors without module-level shared state.
+     */
+    debugComponentsGetter?: () => DebugComponentEntry[];
 }
 /** A single outgoing cookie entry in the cookie jar. */
 export interface CookieEntry {

package/dist/server/als-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"als-registry.d.ts","sourceRoot":"","sources":["../../src/server/als-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAMrD,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,wCAA+C,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAC,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxE,wFAAwF;IACxF,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAC;CACvD;AAMD,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,+BAAsC,CAAC;AAM5D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,oBAAoB,EAAE,WAAW,EAAE,CAAC;CACrD;AAED,yDAAyD;AACzD,eAAO,MAAM,SAAS,gCAAuC,CAAC;AAM9D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,mDAAmD;AACnD,eAAO,MAAM,eAAe,sCAA6C,CAAC;AAM1E,sDAAsD;AACtD,eAAO,MAAM,YAAY,4DAAmE,CAAC;AAM7F,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAE3D,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,uCAA8C,CAAC;AAM/E,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,YAAY,gCAAuC,CAAC"}
+{"version":3,"file":"als-registry.d.ts","sourceRoot":"","sources":["../../src/server/als-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAMlE,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,wCAA+C,CAAC;AAE9E,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uEAAuE;IACvE,eAAe,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAC9C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;IAClE,wFAAwF;IACxF,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACpC,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,mBAAmB,EAAE,CAAC;CACrD;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAC;CACvD;AAMD,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,+BAAsC,CAAC;AAM5D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,oBAAoB,EAAE,WAAW,EAAE,CAAC;CACrD;AAED,yDAAyD;AACzD,eAAO,MAAM,SAAS,gCAAuC,CAAC;AAM9D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,mDAAmD;AACnD,eAAO,MAAM,eAAe,sCAA6C,CAAC;AAM1E,sDAAsD;AACtD,eAAO,MAAM,YAAY,4DAAmE,CAAC;AAM7F,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;AAE3D,8DAA8D;AAC9D,eAAO,MAAM,mBAAmB,uCAA8C,CAAC;AAM/E,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAE9D,4DAA4D;AAC5D,eAAO,MAAM,YAAY,gCAAuC,CAAC"}