@timber-js/app 0.2.0-alpha.98 → 0.2.0-alpha.99

package/src/{plugins/dev-terminal-error.ts → dev-tools/terminal.ts}

@@ -16,13 +16,12 @@
 
 import { pathToFileURL } from 'node:url';
 import {
-  classifyFrame,
   extractComponentStack,
   parseFirstAppFrame,
   PHASE_LABELS,
   type ErrorPhase,
-  type FrameType,
-} from './dev-error-overlay.js';
+} from './overlay.js';
+import { classifyStack } from './stack-classifier.js';
 
 // ─── ANSI Codes ─────────────────────────────────────────────────────────────
 
@@ -93,40 +92,7 @@ function box(lines: string[], borderColor: string, width = 80): string {
   return output.join('\n');
 }
 
-// ─── Frame Extraction ───────────────────────────────────────────────────────
-
-interface ClassifiedFrame {
-  raw: string;
-  type: FrameType;
-  file?: string;
-  line?: number;
-  col?: number;
-}
-
-/** Parse file/line/col from a stack frame line. */
-function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
-  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
-  if (parenMatch) {
-    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
-  }
-  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
-  if (bareMatch) {
-    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
-  }
-  return {};
-}
-
-function classifyFrames(stack: string, projectRoot: string): ClassifiedFrame[] {
-  return stack
-    .split('\n')
-    .slice(1)
-    .filter((l) => l.trim().startsWith('at '))
-    .map((raw) => {
-      const type = classifyFrame(raw, projectRoot);
-      const { file, line, col } = parseFrame(raw);
-      return { raw, type, file, line, col };
-    });
-}
+// Frame classification and parsing provided by stack-classifier.ts
 
 // ─── Public API ─────────────────────────────────────────────────────────────
 
@@ -144,7 +110,7 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
   const sections: string[] = [];
   const componentStack = extractComponentStack(error);
   const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
-  const frames = error.stack ? classifyFrames(error.stack, projectRoot) : [];
+  const frames = error.stack ? classifyStack(error.stack, projectRoot) : [];
   const appFrames = frames.filter((f) => f.type === 'app');
   const internalCount = frames.filter((f) => f.type !== 'app').length;
 

package/src/{server/dev-warnings.ts → dev-tools/warnings.ts}

@@ -15,7 +15,7 @@
  */
 
 import type { ViteDevServer } from 'vite';
-import { isDebug } from './debug.js';
+import { isDebug } from '../server/debug.js';
 
 // ─── Warning IDs ───────────────────────────────────────────────────────────
 

package/src/index.ts

@@ -24,8 +24,8 @@ import { timberFonts } from './plugins/fonts';
 import { timberStaticBuild } from './plugins/static-build';
 import { timberServerActionExports } from './plugins/server-action-exports';
 import { timberBuildManifest } from './plugins/build-manifest';
-import { timberDevLogs } from './plugins/dev-logs';
-import { timberDevBrowserLogs } from './plugins/dev-browser-logs';
+import { timberDevLogs } from './dev-tools/logs';
+import { timberDevBrowserLogs } from './dev-tools/browser-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
 import { clientChunkGroup } from './plugins/client-chunks';
@@ -34,7 +34,7 @@ import { timberAdapterBuild } from './plugins/adapter-build';
 import { timberBuildReport } from './plugins/build-report';
 import { createNoopTimer } from './utils/startup-timer';
 import { resolveEncryptionKeyExpression, shouldEnableEncryption } from './server/action-encryption';
-import { createHoldingServer } from './server/dev-holding-server.js';
+import { createHoldingServer } from './dev-tools/holding-server.js';
 import { resolveStartPort, startDevServerPort } from './server/port-resolution.js';
 import type { TimberUserConfig } from './config-types.js';
 import type { PluginContext } from './plugin-context.js';
@@ -52,6 +52,14 @@ import {
 
 export type { TimberUserConfig } from './config-types.js';
 
+// Metadata route handler types — re-exported so user-authored metadata
+// route files (sitemap.ts, robots.ts, manifest.ts, icon.tsx, etc.) can
+// import them from the package root without reaching into ./server.
+// The canonical location for these types is '@timber-js/app/server'; this
+// root re-export is a convenience for typed metadata route handlers.
+// See design/16-metadata.md §"Metadata Routes".
+export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './server/types.js';
+
 /**
  * Route map interface — augmented by the generated timber-routes.d.ts.
  *

package/src/plugin-context.ts

@@ -16,7 +16,7 @@ import type { BuildManifest } from './server/build-manifest';
 import type { StartupTimer } from './utils/startup-timer';
 import { createStartupTimer } from './utils/startup-timer';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
-import type { HoldingServer } from './server/dev-holding-server.js';
+import type { HoldingServer } from './dev-tools/holding-server.js';
 
 // Re-export for sub-plugin convenience — they import from plugin-context.ts
 export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';

package/src/plugins/adapter-build.ts

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
 import type { PluginContext } from '../plugin-context.js';
 import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
+import { swallow } from '../server/logger.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -103,7 +104,8 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
     let manifest: Record<string, unknown>;
     try {
       manifest = JSON.parse(jsonStr);
-    } catch {
+    } catch (err) {
+      swallow(err, `corrupted RSC assets manifest: ${path}`, { level: 'warn' });
       continue;
     }
 

package/src/plugins/dev-server.ts

@@ -16,19 +16,19 @@ import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
 import type { PluginContext } from '../plugin-context.js';
-import { setViteServer } from '../server/dev-warnings.js';
+import { setViteServer } from '../dev-tools/warnings.js';
 import {
   sendErrorToOverlay,
   classifyErrorPhase,
   fixErrorStacktrace,
   parseFirstAppFrame,
   type ErrorPhase,
-} from './dev-error-overlay.js';
+} from '../dev-tools/overlay.js';
 import {
   generateDevErrorPage,
   extractHmrOptions,
   type DevErrorHmrOptions,
-} from './dev-error-page.js';
+} from '../dev-tools/error-page.js';
 import { addVirtualModuleContext } from '../config-validation.js';
 import { compressResponse } from '../server/compress.js';
 

package/src/plugins/shims.ts

@@ -299,7 +299,7 @@ export const headers = stub;
 export const cookies = stub;
 export const getHeaders = stub;
 export const getHeader = stub;
-export const getCookies = stub;
+export const getCookieJar = stub;
 export const getCookie = stub;
 export const getSearchParams = stub;
 export const getSegmentParams = stub;

package/src/plugins/static-build.ts

@@ -39,7 +39,7 @@ export interface StaticOptions {
  * We detect both import-level and call-level usage.
  */
 const DYNAMIC_API_PATTERNS: Array<{ pattern: RegExp; name: string }> = [
-  { pattern: /\bgetCookies\s*\(/, name: 'getCookies()' },
+  { pattern: /\bgetCookieJar\s*\(/, name: 'getCookieJar()' },
   { pattern: /\bgetHeaders\s*\(/, name: 'getHeaders()' },
   { pattern: /\bcookies\s*\(/, name: 'cookies()' },
   { pattern: /\bheaders\s*\(/, name: 'headers()' },

package/src/routing/convention-lint.ts

@@ -13,6 +13,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import type { RouteTree, SegmentNode } from './types.js';
+import { swallow } from '../server/logger.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -164,8 +165,8 @@ function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): vo
           level: 'warn',
         });
       }
-    } catch {
-      // Can't read the file — skip silently
+    } catch (err) {
+      swallow(err, `convention-lint: unreadable route.ts ${filePath}`);
     }
   }
 
@@ -280,8 +281,8 @@ function checkFileDefaultExport(
         level: 'warn',
       });
     }
-  } catch {
-    // Can't read file — skip silently
+  } catch (err) {
+    swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
   }
 }
 

package/src/routing/scanner.ts

@@ -21,6 +21,7 @@ import type {
 import { classifySegment } from './segment-classify.js';
 import { DEFAULT_PAGE_EXTENSIONS } from './types.js';
 import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
+import { swallow } from '../server/logger.js';
 
 /**
  * Pattern matching encoded path delimiters that must be rejected during route discovery.
@@ -152,7 +153,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
   let entries: string[];
   try {
     entries = readdirSync(dirPath);
-  } catch {
+  } catch (err) {
+    swallow(err, `scanSegmentFiles: unreadable directory ${dirPath}`, { level: 'warn' });
     return;
   }
 
@@ -282,7 +284,8 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
   let entries: string[];
   try {
     entries = readdirSync(dirPath);
-  } catch {
+  } catch (err) {
+    swallow(err, `scanChildren: unreadable directory ${dirPath}`, { level: 'warn' });
     return;
   }
 

package/src/routing/status-file-lint.ts

@@ -16,6 +16,7 @@
 import { readFileSync } from 'node:fs';
 import type { RouteTree, SegmentNode } from './types.js';
 import { detectFileDirective } from '../utils/directive-parser.js';
+import { swallow } from '../server/logger.js';
 
 /** Extensions that require 'use client' (component files, not MDX/JSON). */
 const CLIENT_REQUIRED_EXTENSIONS = new Set(['tsx', 'jsx', 'ts', 'js']);
@@ -80,8 +81,9 @@ function checkFile(
   let code: string;
   try {
     code = readFileSync(filePath, 'utf-8');
-  } catch {
-    return; // File unreadable — skip silently
+  } catch (err) {
+    swallow(err, `status-file-lint: unreadable file ${filePath}`);
+    return;
   }
 
   const directive = detectFileDirective(code, ['use client']);

package/src/search-params/define.ts

@@ -23,18 +23,18 @@ import type { Codec } from '../codec.js';
 // dynamic `await import()` at call time because the async microtask from the
 // dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
 // breaking getSearchParams() in parallel slot pages. See TIM-523.
-let _getSearchParamsFn: (() => Promise<URLSearchParams>) | undefined;
+let _getSearchParamsFn: (() => URLSearchParams) | undefined;
 
 /**
  * Register the getSearchParams function. Called once at module load time
  * from request-context.ts to avoid dynamic import at call time.
  * @internal
  */
-export function _setGetSearchParamsFn(fn: () => Promise<URLSearchParams>): void {
+export function _setGetSearchParamsFn(fn: () => URLSearchParams): void {
   _getSearchParamsFn = fn;
 }
 
-function getSearchParamsFromAls(): Promise<URLSearchParams> {
+function getSearchParamsFromAls(): URLSearchParams {
   if (!_getSearchParamsFn) {
     throw new Error(
       '[timber] searchParams.get() is only available on the server. ' +
@@ -111,19 +111,18 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
   /**
    * Get typed search params from the current request context (ALS-backed).
    *
-   * Server-only — reads getSearchParams() from ALS and parses through codecs.
-   * Throws on client. Eliminates the naming conflict between the definition
-   * export and the server helper.
+   * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.
+   * Throws on client.
    *
    * ```tsx
    * // app/products/page.tsx
    * import { searchParams } from './params'
-   * export default async function Page() {
-   *   const { page, category } = await searchParams.get()
+   * export default function Page() {
+   *   const { page, category } = searchParams.get()
    * }
    * ```
    */
-  get(): Promise<T>;
+  get(): T;
 
   /** Client hook — reads current URL params and returns typed values + setter. */
   useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
@@ -271,11 +270,68 @@ function validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>):
  * })
  * ```
  */
+/**
+ * Overload: accept a Standard Schema object schema (e.g., z.object({...})).
+ *
+ * The schema must have a `.shape` property whose values are themselves
+ * Standard Schema objects. Each shape property becomes a field codec
+ * via fromSchema().
+ *
+ * ```ts
+ * const searchParams = defineSearchParams(
+ *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })
+ * )
+ * ```
+ */
+export function defineSearchParams<T extends Record<string, unknown>>(
+  schema: StandardSchemaV1<T> & { shape: Record<string, StandardSchemaV1<unknown>> }
+): SearchParamsDefinition<T>;
+
+/**
+ * Overload: accept a map of codecs and/or Standard Schema objects.
+ */
 export function defineSearchParams<C extends Record<string, SearchParamField>>(
   codecs: C
-): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }> {
-  type T = { [K in keyof C]: InferField<C[K]> };
+): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;
+
+export function defineSearchParams(
+  codecsOrSchema:
+    | Record<string, SearchParamField>
+    | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })
+): SearchParamsDefinition<Record<string, unknown>> {
+  // Detect Standard Schema object with .shape (e.g., z.object(...))
+  if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {
+    const fieldCodecs: Record<string, SearchParamField> = {};
+    for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {
+      if (isStandardSchema(fieldSchema)) {
+        fieldCodecs[key] = fieldSchema;
+      } else {
+        throw new Error(
+          `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +
+            `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`
+        );
+      }
+    }
+    return defineSearchParamsFromMap(fieldCodecs);
+  }
+
+  return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);
+}
+
+/** Check if a schema has a .shape property with object-type values. */
+function hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    'shape' in schema &&
+    typeof (schema as { shape: unknown }).shape === 'object' &&
+    (schema as { shape: unknown }).shape !== null
+  );
+}
 
+function defineSearchParamsFromMap(
+  codecs: Record<string, SearchParamField>
+): SearchParamsDefinition<Record<string, unknown>> {
   const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};
   const urlKeys: Record<string, string> = {};
 
@@ -290,7 +346,7 @@ export function defineSearchParams<C extends Record<string, SearchParamField>>(
   // Validate that all codecs handle absent params
   validateDefaults(resolvedCodecs);
 
-  return buildDefinition<T>(resolvedCodecs as unknown as CodecMap<T>, urlKeys);
+  return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);
 }
 
 // ---------------------------------------------------------------------------
@@ -453,15 +509,15 @@ function buildDefinition<T extends Record<string, unknown>>(
 
   // ---- get ----
   // ALS-backed: reads getSearchParams() from the current request context
-  // and parses through codecs. Server-only — throws on client.
-  async function get(): Promise<T> {
+  // and parses through codecs. Server-only, sync.
+  function get(): T {
     if (typeof window !== 'undefined') {
       throw new Error(
         '[timber] searchParams.get() is server-only. ' +
           'Use searchParams.useQueryStates() on the client.'
       );
     }
-    const raw = await getSearchParamsFromAls();
+    const raw = getSearchParamsFromAls();
     return parseSync(raw);
   }
 

package/src/search-params/wrappers.ts

@@ -8,7 +8,8 @@
  * Design doc: design/23-search-params.md
  */
 
-import type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';
+import type { SearchParamCodec, SearchParamCodecWithUrlKey, SearchParamField } from './define.js';
+import { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';
 
 // ---------------------------------------------------------------------------
 // withDefault
@@ -74,9 +75,15 @@ export function withDefault<T>(
  * ```
  */
 export function withUrlKey<T>(
-  codec: SearchParamCodec<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),

package/src/segment-params/define.ts

@@ -27,22 +27,44 @@ import {
 
 // 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;
+let _getSegmentParamsFn: (() => Record<string, string | string[]>) | undefined;
+let _useSegmentParamsHook: (() => Record<string, string | string[]>) | undefined;
+
+/**
+ * Register the client useSegmentParams hook.
+ * Called by client entry at module load time to avoid require() at call time.
+ * @internal
+ */
+export function _registerUseSegmentParams(hook: () => Record<string, string | string[]>): void {
+  _useSegmentParamsHook = hook;
+}
+
+// Self-register on the client when the barrel hasn't been imported yet.
+// Handles the edge case where a client component imports only from params.ts
+// without importing anything from @timber-js/app/client (which runs the
+// registration). The dynamic import resolves before React hydration in Vite.
+if (typeof window !== 'undefined' && !_useSegmentParamsHook) {
+  import('../client/use-segment-params.js').then((mod) => {
+    if (!_useSegmentParamsHook) {
+      _useSegmentParamsHook = mod.useSegmentParams;
+    }
+  });
+}
 
 /**
  * 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 {
+export function _setGetSegmentParamsFn(fn: () => Record<string, string | string[]>): void {
   _getSegmentParamsFn = fn;
 }
 
-function getSegmentParamsFromAls(): Promise<Record<string, string | string[]>> {
+function getSegmentParamsFromAls(): Record<string, string | string[]> {
   if (!_getSegmentParamsFn) {
     throw new Error(
       '[timber] segmentParams.get() is only available on the server. ' +
-        'Use useSegmentParams() on the client.'
+        'Use segmentParams.useSegmentParams() on the client.'
     );
   }
   return _getSegmentParamsFn();
@@ -77,8 +99,7 @@ export interface ParamsDefinition<T extends Record<string, unknown>> {
   /**
    * 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.
+   * Server-only, sync.
    *
    * ```ts
    * // app/products/[id]/params.ts
@@ -86,12 +107,25 @@ export interface ParamsDefinition<T extends Record<string, unknown>> {
    *
    * // app/products/[id]/page.tsx
    * import { segmentParams } from './params'
-   * export default async function Page() {
-   *   const { id } = await segmentParams.get() // id: number
+   * 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()
    * }
    * ```
    */
-  get(): Promise<T>;
+  useSegmentParams(): T;
 
   /** Read-only codec map. */
   codecs: { [K in keyof T]: Codec<T[K]> };
@@ -250,28 +284,47 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
 
   // ---- get ----
   // ALS-backed: reads segment params from the current request context.
-  // Server-only — throws on client.
+  // 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.
-  async function get(): Promise<T> {
+  function get(): T {
     if (typeof window !== 'undefined') {
       throw new Error(
-        '[timber] segmentParams.get() is server-only. ' + 'Use useSegmentParams() on the client.'
+        '[timber] segmentParams.get() is server-only. ' +
+          'Use segmentParams.useSegmentParams() on the client.'
       );
     }
-    const params = await getSegmentParamsFromAls();
+    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 {
+    if (!_useSegmentParamsHook) {
+      throw new Error(
+        '[timber] segmentParams.useSegmentParams() requires @timber-js/app/client to be loaded. ' +
+          'This hook can only be used in client components.'
+      );
+    }
+    const raw = _useSegmentParamsHook();
+    // 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]> },
   };
 

package/src/server/access-gate.tsx

@@ -14,11 +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-page-resolver.js';
-import { renderMatchingDenyPage, setDenyStatus } from './deny-page-resolver.js';
+import type { DenyPageEntry } from './deny-boundary.js';
+import { renderMatchingDenyPage, setDenyStatus } from './deny-boundary.js';
+import type { ReactNode } from 'react';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -36,7 +37,7 @@ import { renderMatchingDenyPage, setDenyStatus } from './deny-page-resolver.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> {
+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.
@@ -61,8 +62,8 @@ async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
   segmentName: AccessGateProps['segmentName'],
   denyPages: DenyPageEntry[] | undefined,
-  children: ReactElement
-): Promise<ReactElement> {
+  children: ReactNode
+): Promise<ReactNode> {
   try {
     await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
       try {
@@ -114,7 +115,7 @@ async function accessGateFallback(
  * 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> {
+export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactNode> {
   const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
   try {
@@ -175,7 +176,7 @@ function buildDeniedFallback(
   slotName: string,
   data: unknown,
   createElement: SlotAccessGateProps['createElement']
-): ReactElement | null {
+): ReactNode | null {
   if (!DeniedComponent) return null;
   return createElement(DeniedComponent, {
     slot: slotName,