@timber-js/app 0.2.0-alpha.60 → 0.2.0-alpha.62

package/src/client/transition-root.tsx

@@ -176,3 +176,30 @@ export function navigateTransition(
 export function isTransitionRootReady(): boolean {
   return _transitionRender !== null;
 }
+
+/**
+ * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
+ *
+ * When there's no RSC payload, we can't create a React root immediately —
+ * `createRoot(document).render(...)` would blank the SSR HTML. Instead,
+ * this sets up `_transitionRender` and `_navigateTransition` so that the
+ * first client navigation triggers root creation via `createAndMount`.
+ *
+ * After `createAndMount` runs, TransitionRoot renders and overwrites these
+ * callbacks with its real `startTransition`-based implementations.
+ */
+export function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {
+  let mounted = false;
+  const mountOnce = (element: ReactNode) => {
+    if (mounted) return;
+    mounted = true;
+    createAndMount(element);
+  };
+  _transitionRender = (element: ReactNode) => {
+    mountOnce(element);
+  };
+  _navigateTransition = async (_pendingUrl: string, perform: () => Promise<ReactNode>) => {
+    const element = await perform();
+    mountOnce(element);
+  };
+}

package/src/params/define.ts

@@ -297,16 +297,23 @@ export function defineSegmentParams<C extends Record<string, ParamField>>(
   }
 
   // ---- load ----
-  // ALS-backed: reads rawSegmentParams() from the current request context
-  // and parses through codecs. Server-only — throws on client.
+  // ALS-backed: reads segment params from the current request context.
+  // Server-only — throws on client.
+  //
+  // The pipeline already coerces params via coerceSegmentParams() which
+  // calls parse() and stores typed values in ALS via setSegmentParams().
+  // We return those directly instead of re-parsing, because codecs may
+  // not be idempotent (e.g., a codec that only accepts raw strings would
+  // throw if given an already-parsed value). See TIM-574.
   async function load(): Promise<T> {
     if (typeof window !== 'undefined') {
       throw new Error(
         '[timber] segmentParams.load() is server-only. ' + 'Use useSegmentParams() on the client.'
       );
     }
-    const raw = await getRawSegmentParams();
-    return parse(raw);
+    const params = await getRawSegmentParams();
+    // params are already coerced by the pipeline — return as-is.
+    return params as unknown as T;
   }
 
   const definition: ParamsDefinition<T> = {

package/src/plugins/dev-browser-logs.ts

@@ -233,6 +233,16 @@ export function timberDevBrowserLogs(ctx: PluginContext): Plugin {
       const threshold = ctx.config.devBrowserLogs ?? 'warn';
       if (threshold === 'none') return;
 
+      // Register the client injection script on globalThis so the RSC entry
+      // can include it in headHtml for all Timber route responses.
+      // transformIndexHtml only runs for Vite's index.html fallback, not
+      // for responses served by createTimberMiddleware (TIM-575).
+      const script = generateClientScript(threshold);
+      if (script) {
+        (globalThis as Record<string, unknown>).__timber_dev_browser_log_script =
+          `<script type="module">${script}</script>`;
+      }
+
       // Listen for browser log messages via HMR WebSocket
       server.hot.on(HMR_EVENT, (payload: BrowserLogPayload) => {
         try {

package/src/plugins/entries.ts

@@ -34,6 +34,7 @@ const VIRTUAL_IDS = {
   browserEntry: 'virtual:timber-browser-entry',
   config: 'virtual:timber-config',
   instrumentation: 'virtual:timber-instrumentation',
+  cacheHandler: 'virtual:timber-cache-handler',
 } as const;
 
 /**
@@ -57,6 +58,9 @@ const RESOLVED_CONFIG_ID = `\0${VIRTUAL_IDS.config}`;
 /** The \0-prefixed resolved ID for virtual:timber-instrumentation */
 const RESOLVED_INSTRUMENTATION_ID = `\0${VIRTUAL_IDS.instrumentation}`;
 
+/** The \0-prefixed resolved ID for virtual:timber-cache-handler */
+const RESOLVED_CACHE_HANDLER_ID = `\0${VIRTUAL_IDS.cacheHandler}`;
+
 /**
  * Strip the \0 prefix from a module ID.
  *
@@ -175,6 +179,53 @@ export function generateInstrumentationModule(instrumentationPath: string | null
   ].join('\n');
 }
 
+/**
+ * Detect the user's timber.config file at the project root.
+ * Returns the absolute path or null if not found.
+ */
+function detectConfigFile(root: string): string | null {
+  const names = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  for (const name of names) {
+    const candidate = resolve(root, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Generate the virtual:timber-cache-handler module source.
+ *
+ * When the user's config has a cacheHandler, generates a module that
+ * dynamically imports the config file and extracts the cacheHandler.
+ * The cacheHandler is a class instance (e.g. RedisCacheHandler) that
+ * cannot be JSON-serialized into virtual:timber-config, so it must
+ * be loaded at runtime via dynamic import. See TIM-599.
+ */
+function generateCacheHandlerModule(configPath: string | null, hasCacheHandler: boolean): string {
+  if (configPath && hasCacheHandler) {
+    return [
+      '// Auto-generated cache handler loader — do not edit.',
+      '// Generated by timber-entries plugin.',
+      '',
+      `export default async function loadCacheHandler() {`,
+      `  const mod = await import(${JSON.stringify(configPath)});`,
+      `  const config = mod.default ?? mod;`,
+      `  return config.cacheHandler ?? null;`,
+      `}`,
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated cache handler loader — do not edit.',
+    '// Generated by timber-entries plugin.',
+    '// No cacheHandler configured in timber.config.',
+    '',
+    `export default async function loadCacheHandler() {`,
+    `  return null;`,
+    `}`,
+  ].join('\n');
+}
+
 /**
  * Create the timber-entries Vite plugin.
  *
@@ -217,6 +268,11 @@ export function timberEntries(ctx: PluginContext): Plugin {
         return RESOLVED_INSTRUMENTATION_ID;
       }
 
+      // Check cache handler virtual module
+      if (cleanId === VIRTUAL_IDS.cacheHandler) {
+        return RESOLVED_CACHE_HANDLER_ID;
+      }
+
       return null;
     },
 
@@ -234,6 +290,11 @@ export function timberEntries(ctx: PluginContext): Plugin {
         const instrumentationPath = detectInstrumentationFile(ctx.root);
         return generateInstrumentationModule(instrumentationPath);
       }
+      if (id === RESOLVED_CACHE_HANDLER_ID) {
+        const configPath = detectConfigFile(ctx.root);
+        const hasCacheHandler = ctx.config.cacheHandler != null;
+        return generateCacheHandlerModule(configPath, hasCacheHandler);
+      }
       return null;
     },
 

package/src/plugins/routing.ts

@@ -28,7 +28,7 @@ const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|default|denied|params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.

package/src/routing/index.ts

@@ -12,3 +12,5 @@ export type {
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
 export { collectInterceptionRewrites } from './interception.js';
 export type { InterceptionRewrite } from './interception.js';
+export { classifyUrlSegment } from './segment-classify.js';
+export type { UrlSegment } from './segment-classify.js';

package/src/routing/scanner.ts

@@ -18,6 +18,7 @@ import type {
   ScannerConfig,
   InterceptionMarker,
 } from './types.js';
+import { classifyUrlSegment } from './segment-classify.js';
 import { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
 import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
@@ -165,22 +166,12 @@ export function classifySegment(dirName: string): {
     return { type: 'group' };
   }
 
-  // Optional catch-all: [[...name]]
-  if (dirName.startsWith('[[...') && dirName.endsWith(']]')) {
-    const paramName = dirName.slice(5, -2);
-    return { type: 'optional-catch-all', paramName };
-  }
-
-  // Catch-all: [...name]
-  if (dirName.startsWith('[...') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(4, -1);
-    return { type: 'catch-all', paramName };
-  }
-
-  // Dynamic: [name]
-  if (dirName.startsWith('[') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(1, -1);
-    return { type: 'dynamic', paramName };
+  // Bracket-syntax segments: [param], [...param], [[...param]]
+  // Delegated to the shared character-based classifier. If you change
+  // bracket syntax, update segment-classify.ts — not here.
+  const urlSeg = classifyUrlSegment(dirName);
+  if (urlSeg.kind !== 'static') {
+    return { type: urlSeg.kind, paramName: urlSeg.name };
   }
 
   return { type: 'static' };

package/src/routing/segment-classify.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared URL segment classifier.
+ *
+ * Single-pass character parser that classifies a route segment token
+ * (e.g. "dashboard", "[id]", "[...slug]", "[[...path]]") into a typed
+ * discriminated union. Used by both server-side routing and client-side
+ * Link interpolation.
+ *
+ * NO regex. NO Node.js-only APIs. Safe to import from browser code.
+ *
+ * Malformed input (unclosed brackets, empty names, etc.) falls through
+ * to { kind: 'static' } — the safe default.
+ *
+ * If you change the bracket syntax, update ONLY this file. Every
+ * consumer imports from here.
+ *
+ * See design/07-routing.md §"Route Segments"
+ */
+
+export type UrlSegment =
+  | { kind: 'static'; value: string }
+  | { kind: 'dynamic'; name: string }
+  | { kind: 'catch-all'; name: string }
+  | { kind: 'optional-catch-all'; name: string };
+
+/**
+ * Classify a URL path segment token.
+ *
+ * Walks the string left-to-right in one pass:
+ *   1. If it doesn't start with '[', it's static.
+ *   2. Count opening brackets (1 or 2) to detect optional.
+ *   3. Check for '...' to detect catch-all.
+ *   4. Read the param name up to the closing bracket.
+ *   5. Validate the expected closing sequence (']' or ']]').
+ *   6. Reject if there are leftover characters after the close.
+ *
+ * Any structural violation → static (safe default).
+ */
+export function classifyUrlSegment(token: string): UrlSegment {
+  const len = token.length;
+
+  // Must start with '[' to be dynamic
+  if (len === 0 || token[0] !== '[') {
+    return { kind: 'static', value: token };
+  }
+
+  let i = 1;
+
+  // Check for optional: '[[...'
+  const optional = token[i] === '[';
+  if (optional) i++;
+
+  // Check for catch-all: '...'
+  const catchAll = i + 2 < len && token[i] === '.' && token[i + 1] === '.' && token[i + 2] === '.';
+  if (catchAll) i += 3;
+
+  // Read param name — everything up to ']'
+  const nameStart = i;
+  while (i < len && token[i] !== ']') i++;
+
+  // Must have found a ']' and name must be non-empty
+  if (i >= len || i === nameStart) {
+    return { kind: 'static', value: token };
+  }
+
+  const name = token.slice(nameStart, i);
+  i++; // skip first ']'
+
+  // Optional requires a second ']'
+  if (optional) {
+    if (i >= len || token[i] !== ']') {
+      return { kind: 'static', value: token };
+    }
+    i++;
+  }
+
+  // Must be at end of string — no trailing characters
+  if (i !== len) {
+    return { kind: 'static', value: token };
+  }
+
+  if (optional && catchAll) return { kind: 'optional-catch-all', name };
+  if (catchAll) return { kind: 'catch-all', name };
+  if (optional) {
+    // '[[name]]' without '...' is malformed — not a valid segment syntax
+    return { kind: 'static', value: token };
+  }
+  return { kind: 'dynamic', name };
+}

package/src/server/actions.ts

@@ -14,7 +14,7 @@
  * See design/08-forms-and-actions.md
  */
 
-import type { CacheHandler } from '../cache/index';
+import { getCacheHandler } from '../cache/handler-store';
 import { RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
@@ -37,8 +37,6 @@ 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;
 }
@@ -172,9 +170,12 @@ export async function executeAction(
     }
   });
 
-  // Process tag invalidation
-  if (state.tags.length > 0 && config.cacheHandler) {
-    await Promise.all(state.tags.map((tag) => config.cacheHandler!.invalidate({ tag })));
+  // Process tag invalidation via the module-level cache handler singleton.
+  // setCacheHandler() is called at boot from rsc-entry when timber.config.ts
+  // provides a cacheHandler; otherwise falls back to in-memory LRU (TIM-599).
+  if (state.tags.length > 0) {
+    const handler = getCacheHandler();
+    await Promise.all(state.tags.map((tag) => handler.invalidate({ tag })));
   }
 
   // Process path revalidation — build element tree (not yet serialized)

package/src/server/deny-renderer.ts

@@ -20,6 +20,7 @@ import { renderToReadableStream } from '../rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 import { logRenderError } from './logger.js';
+import { loadModule } from './safe-load.js';
 import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
 import { resolveManifestStatusFile } from './manifest-status-resolver.js';
@@ -110,7 +111,7 @@ export async function renderDenyPage(
   }
 
   // Load the status-code page component
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   if (!mod.default) {
     return new Response(null, { status: deny.status, headers: responseHeaders });
   }
@@ -208,7 +209,7 @@ export async function renderDenyPageAsRsc(
     return new Response(null, { status: deny.status, headers: responseHeaders });
   }
 
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   if (!mod.default) {
     responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
     return new Response(null, { status: deny.status, headers: responseHeaders });
@@ -274,7 +275,7 @@ async function renderDenyPageJson(
   // JSON status files are loaded as modules that export the JSON content.
   // The manifest's load() imports the .json file, which Vite handles as a
   // default export of the parsed JSON object.
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   const jsonContent = mod.default ?? mod;
 
   responseHeaders.set('content-type', 'application/json; charset=utf-8');

package/src/server/error-boundary-wrapper.ts

@@ -7,6 +7,7 @@
 
 import { TimberErrorBoundary } from '../client/error-boundary.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
+import { loadModule } from './safe-load.js';
 
 /** MDX/markdown extensions — server components that cannot be passed as function props. */
 const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
@@ -45,8 +46,10 @@ export async function wrapSegmentWithErrorBoundaries(
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
-          const mod = (await file.load()) as Record<string, unknown>;
-          if (mod.default) {
+          // .catch: error boundary construction must not fail if the
+          // error page module has a syntax error — skip this boundary.
+          const mod = await loadModule(file).catch(() => null);
+          if (mod?.default) {
             if (isMdxFilePath(file.filePath)) {
               // MDX: pre-render as element (server component can't be a function prop)
               element = h(TimberErrorBoundary, {
@@ -69,8 +72,8 @@ export async function wrapSegmentWithErrorBoundaries(
     // Category catch-alls (4xx.tsx, 5xx.tsx)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
       if (key === '4xx' || key === '5xx') {
-        const mod = (await file.load()) as Record<string, unknown>;
-        if (mod.default) {
+        const mod = await loadModule(file).catch(() => null);
+        if (mod?.default) {
           const categoryStatus = key === '4xx' ? 400 : 500;
           if (isMdxFilePath(file.filePath)) {
             element = h(TimberErrorBoundary, {
@@ -92,8 +95,8 @@ export async function wrapSegmentWithErrorBoundaries(
 
   // error.tsx (outermost — catches anything not matched by status files)
   if (segment.error) {
-    const mod = (await segment.error.load()) as Record<string, unknown>;
-    if (mod.default) {
+    const mod = await loadModule(segment.error).catch(() => null);
+    if (mod?.default) {
       if (isMdxFilePath(segment.error.filePath)) {
         element = h(TimberErrorBoundary, {
           fallbackElement: h(mod.default as never, {}),

package/src/server/fallback-error.ts

@@ -15,6 +15,8 @@ import type { ManifestSegmentNode } from './route-matcher.js';
 import type { ClientBootstrapConfig } from './html-injectors.js';
 import type { LayoutEntry } from './deny-renderer.js';
 import type { GlobalErrorFile } from './rsc-entry/error-renderer.js';
+import { logRenderError } from './logger.js';
+import { loadModule } from './safe-load.js';
 
 /**
  * Render a fallback error page when the render pipeline throws.
@@ -38,14 +40,25 @@ export async function renderFallbackError(
   const { renderErrorPage } = await import('./rsc-entry/error-renderer.js');
   const segments = [rootSegment];
   const layoutComponents: LayoutEntry[] = [];
-  if (rootSegment.layout) {
-    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
-    if (mod.default) {
-      layoutComponents.push({
-        component: mod.default as (...args: unknown[]) => unknown,
-        segment: rootSegment,
-      });
+  // Wrap layout loading in try/catch — if the root layout module itself
+  // crashes (evaluation failure, syntax error, etc.), we still want to
+  // reach renderErrorPage so it can fall through to global-error.tsx
+  // (Tier 2), which renders without any layout wrapping.
+  try {
+    if (rootSegment.layout) {
+      const mod = await loadModule(rootSegment.layout);
+      if (mod.default) {
+        layoutComponents.push({
+          component: mod.default as (...args: unknown[]) => unknown,
+          segment: rootSegment,
+        });
+      }
     }
+  } catch (layoutError) {
+    // Layout failed to load — proceed without it. renderErrorPage will
+    // attempt segment-level error pages (without layout wrapping) and
+    // then fall through to global-error.tsx if those also fail.
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
   }
   const match: RouteMatch = { segments: segments as never, params: {} };
   return renderErrorPage(

package/src/server/pipeline-interception.ts

@@ -9,6 +9,8 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
+import { classifyUrlSegment } from '../routing/segment-classify.js';
+
 /** Result of a successful interception match. */
 export interface InterceptionMatchResult {
   /** The pathname to re-match (the source/intercepting route's parent). */
@@ -53,23 +55,22 @@ export function pathnameMatchesPattern(pathname: string, pattern: string): boole
 
   let pi = 0;
   for (let i = 0; i < patternParts.length; i++) {
-    const segment = patternParts[i];
-
-    // Catch-all: [...param] or [[...param]] — matches rest of URL
-    if (segment.startsWith('[...') || segment.startsWith('[[...')) {
-      return pi < pathParts.length || segment.startsWith('[[...');
-    }
+    const seg = classifyUrlSegment(patternParts[i]);
 
-    // Dynamic: [param] — matches any single segment
-    if (segment.startsWith('[') && segment.endsWith(']')) {
-      if (pi >= pathParts.length) return false;
-      pi++;
-      continue;
+    switch (seg.kind) {
+      case 'catch-all':
+        return pi < pathParts.length;
+      case 'optional-catch-all':
+        return true;
+      case 'dynamic':
+        if (pi >= pathParts.length) return false;
+        pi++;
+        continue;
+      case 'static':
+        if (pi >= pathParts.length || pathParts[pi] !== seg.value) return false;
+        pi++;
+        continue;
     }
-
-    // Static — must match exactly
-    if (pi >= pathParts.length || pathParts[pi] !== segment) return false;
-    pi++;
   }
 
   return pi === pathParts.length;

package/src/server/pipeline.ts

@@ -46,6 +46,7 @@ import { RedirectSignal, DenySignal } from './primitives.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
 import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
+import { loadModule } from './safe-load.js';
 import { findInterceptionMatch } from './pipeline-interception.js';
 import type { MiddlewareContext } from './types.js';
 import type { SegmentNode } from '../routing/types.js';
@@ -174,7 +175,15 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
     // Only process segments that have a params.ts convention file
     if (!segment.params) continue;
 
-    const mod = (await segment.params.load()) as Record<string, unknown>;
+    let mod: Record<string, unknown>;
+    try {
+      mod = await loadModule(segment.params);
+    } catch (err) {
+      throw new ParamCoercionError(
+        `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+
     const segmentParamsDef = mod.segmentParams as
       | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
       | undefined;
@@ -366,7 +375,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
             return await serveStaticMetadataFile(metaMatch);
           }
 
-          const mod = (await metaMatch.file.load()) as { default?: Function };
+          const mod = await loadModule<{ default?: Function }>(metaMatch.file);
           if (typeof mod.default !== 'function') {
             return new Response('Metadata route must export a default function', { status: 500 });
           }
@@ -480,6 +489,15 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       await coerceSegmentParams(match);
     } catch (error) {
       if (error instanceof ParamCoercionError) {
+        // For API routes (route.ts), return a bare 404 — not an HTML page.
+        // API consumers expect JSON/empty responses, not rendered HTML.
+        const leafSegment = match.segments[match.segments.length - 1];
+        if (
+          (leafSegment as { route?: unknown }).route &&
+          !(leafSegment as { page?: unknown }).page
+        ) {
+          return new Response(null, { status: 404 });
+        }
         // Route through the app's 404 page (404.tsx in root layout) instead of
         // returning a bare empty 404 Response. Falls back to bare 404 only if
         // no renderNoMatch renderer is configured.

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

@@ -32,6 +32,7 @@ import { SegmentProvider } from '../client/segment-context.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
 import { shouldSkipSegment } from './state-tree-diff.js';
+import { loadModule } from './safe-load.js';
 
 // ─── Param Coercion Error ─────────────────────────────────────────────────
 
@@ -186,7 +187,7 @@ export async function buildRouteElement(
 
     // Load layout
     if (segment.layout) {
-      const mod = (await segment.layout.load()) as Record<string, unknown>;
+      const mod = await loadModule(segment.layout);
       if (mod.default) {
         layoutComponents.push({
           component: mod.default as (...args: unknown[]) => unknown,
@@ -207,7 +208,7 @@ export async function buildRouteElement(
 
     // Load page (leaf segment only)
     if (isLeaf && segment.page) {
-      const mod = (await segment.page.load()) as Record<string, unknown>;
+      const mod = await loadModule(segment.page);
 
       // Param coercion is handled in the pipeline (Stage 2c) before
       // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
@@ -239,7 +240,7 @@ export async function buildRouteElement(
   for (let si = 0; si < segments.length; si++) {
     const segment = segments[si];
     if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
+      const accessMod = await loadModule(segment.access);
       const accessFn = accessMod.default as
         | ((ctx: { params: Record<string, string | string[]> }) => unknown)
         | undefined;
@@ -389,7 +390,7 @@ export async function buildRouteElement(
     // Pass the pre-computed verdict so AccessGate replays it synchronously
     // instead of re-calling accessFn (dedup + Suspense immunity).
     if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
+      const accessMod = await loadModule(segment.access);
       const accessFn = accessMod.default as
         | ((ctx: { params: Record<string, string | string[]> }) => unknown)
         | undefined;

package/src/server/rsc-entry/api-handler.ts

@@ -8,6 +8,7 @@
 
 import { withSpan, setSpanAttribute } from '../tracing.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
+import { loadModule } from '../safe-load.js';
 import type { RouteMatch } from '../pipeline.js';
 import { DenySignal, RedirectSignal } from '../primitives.js';
 import { handleRouteRequest } from '../route-handler.js';
@@ -26,7 +27,7 @@ export async function handleApiRoute(
   // Each access.ts is independent — deny()/redirect() throws a signal.
   for (const segment of segments) {
     if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
+      const accessMod = await loadModule(segment.access);
       const accessFn = accessMod.default as
         | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
         | undefined;
@@ -68,7 +69,7 @@ export async function handleApiRoute(
   }
 
   // Load route.ts module and dispatch
-  const routeMod = (await leaf.route!.load()) as RouteModule;
+  const routeMod = await loadModule<RouteModule>(leaf.route!);
   const ctx: RouteContext = {
     req,
     params: match.params,
@@ -94,7 +95,7 @@ async function renderApiDeny(
 
   const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
   if (resolution) {
-    const mod = (await resolution.file.load()) as Record<string, unknown>;
+    const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;
     responseHeaders.set('content-type', 'application/json; charset=utf-8');
     return new Response(JSON.stringify(jsonContent), {