@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/plugins/shims.ts

@@ -5,10 +5,11 @@
  * shim implementations. This enables Next.js-compatible libraries
  * (nuqs, next-intl, etc.) to work unmodified.
  *
- * NOTE: This plugin does NOT resolve @timber-js/app/* subpath imports.
- * Those are handled by Vite's native package.json `exports` resolution,
- * which maps them to dist/ files. This ensures a single module instance
- * for shared modules like request-context (ALS singleton).
+ * This plugin also remaps ALL @timber-js/app/* subpath imports to src/ in
+ * server environments (RSC + SSR). This is required because dist/ chunks
+ * are pre-built and miss Vite's RSC transforms (e.g. createContext from
+ * 'react' doesn't exist in RSC's React build). It also ensures a single
+ * module instance for shared mutable state. See SUBPATH_SRC_MAP and TIM-568.
  *
  * Design doc: 18-build-system.md §"Shim Map"
  */
@@ -16,7 +17,7 @@
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Detect whether we're running from source (src/plugins/) or dist (dist/).
@@ -38,6 +39,24 @@ const SHIMS_DIR = resolve(PKG_ROOT, 'src', 'shims');
 const SERVER_ONLY_VIRTUAL = '\0timber:server-only';
 const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
 
+/**
+ * Map from @timber-js/app/<subpath> to relative src/ file paths.
+ *
+ * Used by the catch-all resolveId rule to remap subpath imports to src/
+ * in server environments. When adding a new subpath export to package.json,
+ * add it here too. See TIM-568.
+ */
+const SUBPATH_SRC_MAP: Record<string, string> = {
+  'cache': 'cache/index.ts',
+  'cookies': 'cookies/index.ts',
+  'search-params': 'search-params/index.ts',
+  'segment-params': 'segment-params/index.ts',
+
+  'adapters/cloudflare': 'adapters/cloudflare.ts',
+  'adapters/cloudflare/dev': 'adapters/cloudflare-dev.ts',
+  'adapters/nitro': 'adapters/nitro.ts',
+};
+
 /**
  * Map from next/* import specifiers to shim file paths.
  *
@@ -49,10 +68,14 @@ const SHIM_MAP: Record<string, string> = {
   'next/image': resolve(SHIMS_DIR, 'image.ts'),
   'next/navigation': resolve(SHIMS_DIR, 'navigation.ts'),
   'next/headers': resolve(SHIMS_DIR, 'headers.ts'),
-  // next/font/* redirects to the timber-fonts virtual modules.
-  // The fonts plugin's load hook serves the actual module code.
+  // next/font/* and @timber-js/app/fonts/* redirect to the timber-fonts
+  // virtual modules. The fonts plugin's load hook serves the actual module
+  // code. The package.json exports point to shim stubs for non-Vite contexts
+  // (tsc, tests), but in Vite the virtual module takes priority via this map.
   'next/font/google': '\0@timber/fonts/google',
   'next/font/local': '\0@timber/fonts/local',
+  '@timber-js/app/fonts/google': '\0@timber/fonts/google',
+  '@timber-js/app/fonts/local': '\0@timber/fonts/local',
 };
 
 /**
@@ -88,14 +111,14 @@ export function timberShims(_ctx: PluginContext): Plugin {
      * 3. Check next/* shim map
      * 4. Return null (pass through) for everything else
      *
-     * @timber-js/app/server is resolved to src/ so it shares the same module
-     * instance as framework internals (which import via #/). This ensures
-     * a single requestContextAls and _getRscFallback variable.
+     * All @timber-js/app/* subpath imports resolve to dist/ via package.json
+     * exports in all environments. This ensures a single module instance
+     * for each module — the dist/ chunks share code via rollup's code
+     * splitting. No src/ remapping is needed (see TIM-568).
      *
-     * @timber-js/app/client is resolved to src/ in the SSR environment so
-     * client hooks share the same module instance as ssr-entry.ts internals.
-     * In RSC it resolves to dist/ (via package.json exports) where 'use client'
-     * is preserved on the entry for client boundary detection.
+     * The only exception is @timber-js/app/server in the client (browser)
+     * environment, which returns a virtual stub — server code must never
+     * be bundled into the browser.
      */
     resolveId(id: string) {
       // Poison pill packages — resolve to virtual modules handled by load()
@@ -117,38 +140,110 @@ export function timberShims(_ctx: PluginContext): Plugin {
         return SHIM_MAP[cleanId];
       }
 
-      // @timber-js/app/server → src/ in server environments so user code
-      // shares the same module instance as framework internals (single ALS).
-      // In the client environment, return a virtual empty module — server
-      // code must never be bundled into the browser.
+      // ── @timber-js/app/* → src/ resolution in server environments ──
+      //
+      // All @timber-js/app/* subpath imports are remapped to src/ in server
+      // environments (RSC + SSR). This is required for two reasons:
+      //
+      // 1. RSC correctness: dist/ chunks eagerly import from 'react' (e.g.
+      //    createContext in segment-context) which doesn't exist in RSC's
+      //    React build. Vite's RSC plugin only transforms src/ files —
+      //    dist/ chunks are pre-built and served as-is.
+      //
+      // 2. Module singleton correctness: framework internals use relative
+      //    imports that resolve within src/. If user code resolved to dist/
+      //    while framework code resolved to src/, mutable module-level state
+      //    (ALS refs, registered callbacks) would be duplicated. By remapping
+      //    all @timber-js/app/* to src/, everything shares one module graph.
+      //
+      // Exception: @timber-js/app/client in RSC resolves to dist/ where
+      // 'use client' is preserved for client boundary detection.
+      //
+      // In the client (browser) environment, all imports resolve to dist/
+      // via package.json exports (no remapping needed).
+
+      // ── #imports resolution for package-internal modules ─────────────
+      //
+      // #server-internal and #client-internal are Node package imports
+      // (package.json "imports" field). They are only resolvable from
+      // within this package — external consumers get module-not-found.
+      //
+      // In Vite, we intercept them here to resolve to src/ for dev/build
+      // correctness (same rationale as the @timber-js/app/* remap above).
+      if (cleanId === '#server-internal') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '#client-internal') {
+        // Always resolve to src/ — all environments (RSC, SSR, client)
+        // use src/ for framework internals. In the client env, this
+        // ensures browser-entry and @timber-js/app/client share the
+        // same module graph (both resolve to src/).
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
+      if (cleanId === '#routing') {
+        return resolve(PKG_ROOT, 'src', 'routing', 'index.ts');
+      }
+
+      // Legacy aliases — vitest and monorepo configs may still reference
+      // the old @timber-js/app/server/internal and @timber-js/app/client/internal
+      // specifiers via resolve.alias. When those aliases resolve to the
+      // absolute src/ path, they bypass this plugin entirely. But if the
+      // specifier reaches us unresolved (e.g., in a Vite build without
+      // aliases), handle it the same way as the #imports above.
+      if (cleanId === '@timber-js/app/server/internal') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName === 'client') {
+          return '\0timber:server-empty';
+        }
+        return resolve(PKG_ROOT, 'src', 'server', 'internal.ts');
+      }
+
+      if (cleanId === '@timber-js/app/client/internal') {
+        // Same as #client-internal above — always resolve to src/.
+        return resolve(PKG_ROOT, 'src', 'client', 'internal.ts');
+      }
+
       if (cleanId === '@timber-js/app/server') {
         const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
         if (envName === 'client') {
           return '\0timber:server-empty';
         }
+        // RSC + SSR: remap to src/
         return resolve(PKG_ROOT, 'src', 'server', 'index.ts');
       }
 
-      // @timber-js/app/client → src/ in the SSR environment so client hooks
-      // (useParams, usePathname, etc.) share the same module instance as
-      // ssr-entry.ts's internal imports (via #/client/...).
-      //
-      // Without this remap, @timber-js/app/client resolves to dist/ (via
-      // package.json exports), creating a module instance split: ssr-entry.ts
-      // registers the ALS-backed SSR data provider on the src/ instance of
-      // ssr-data.ts, but client component hooks read getSsrData() from the
-      // dist/ instance — which has no provider. Result: hooks like useParams()
-      // return empty defaults during SSR.
-      //
-      // This remap is SSR-only. The RSC environment still resolves to dist/
-      // where 'use client' is preserved on the entry (needed for client
-      // boundary detection). The client (browser) environment uses dist/
-      // for bundling.
       if (cleanId === '@timber-js/app/client') {
         const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
-        if (envName === 'ssr') {
+        // RSC: return null — needs dist/ for 'use client' boundary detection.
+        // SSR + Client: resolve to src/ so that browser-entry (which uses
+        // relative imports from src/) and user code (which uses the bare
+        // specifier @timber-js/app/client) share the same module instances.
+        // Without this, state.ts is loaded twice (src/ and dist/) and
+        // setGlobalRouter() writes to one copy while getRouterOrNull()
+        // reads from the other (always null).
+        if (envName === 'ssr' || envName === 'client') {
           return resolve(PKG_ROOT, 'src', 'client', 'index.ts');
         }
+        return null;
+      }
+
+      // Catch-all: remap any other @timber-js/app/<subpath> to src/
+      // in non-client environments (RSC + SSR).
+      if (cleanId.startsWith('@timber-js/app/') && cleanId !== '@timber-js/app/package.json') {
+        const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
+        if (envName !== 'client') {
+          const subpath = cleanId.slice('@timber-js/app/'.length);
+          const srcPath = SUBPATH_SRC_MAP[subpath];
+          if (srcPath) {
+            return resolve(PKG_ROOT, 'src', srcPath);
+          }
+        }
       }
 
       return null;
@@ -202,6 +297,12 @@ const msg = "[timber] @timber-js/app/server was imported from client code. " +
 function stub() { throw new Error(msg); }
 export const headers = stub;
 export const cookies = stub;
+export const getHeaders = stub;
+export const getHeader = stub;
+export const getCookieJar = stub;
+export const getCookie = stub;
+export const getSearchParams = stub;
+export const getSegmentParams = stub;
 export const searchParams = stub;
 export const deny = stub;
 export const notFound = stub;
@@ -209,7 +310,7 @@ export const redirect = stub;
 export const permanentRedirect = stub;
 export const redirectExternal = stub;
 export const waitUntil = stub;
-export const RenderError = stub;
+export const DenyOptions = {};
 export const RedirectType = {};
 export const DenySignal = stub;
 export const RedirectSignal = stub;

package/src/plugins/static-build.ts

@@ -2,34 +2,28 @@
  * timber-static-build — Vite sub-plugin for static output mode.
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (cookies(), headers()) are used
- * 2. When client JavaScript is disabled, rejects 'use client' and 'use server' directives
- * 3. Coordinates build-time rendering of all pages
+ * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
+ * 2. Coordinates build-time rendering of all pages
  *
  * Design doc: design/15-future-prerendering.md
  */
 
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { detectFileDirective } from '#/utils/directive-parser.js';
+import type { PluginContext } from '../plugin-context.js';
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export interface StaticValidationError {
-  type: 'dynamic-api' | 'nojs-directive';
+  type: 'dynamic-api';
   file: string;
   message: string;
   line?: number;
 }
 
-export interface StaticOptions {
-  clientJavascriptDisabled: boolean;
-}
-
 // ---------------------------------------------------------------------------
-// Detection: dynamic APIs (cookies, headers)
+// Detection: dynamic APIs (getCookies, getHeaders, and legacy cookies/headers)
 // ---------------------------------------------------------------------------
 
 /**
@@ -39,12 +33,14 @@ export interface StaticOptions {
  * We detect both import-level and call-level usage.
  */
 const DYNAMIC_API_PATTERNS: Array<{ pattern: RegExp; name: string }> = [
+  { pattern: /\bgetCookieJar\s*\(/, name: 'getCookieJar()' },
+  { pattern: /\bgetHeaders\s*\(/, name: 'getHeaders()' },
   { pattern: /\bcookies\s*\(/, name: 'cookies()' },
   { pattern: /\bheaders\s*\(/, name: 'headers()' },
 ];
 
 /**
- * Detect usage of dynamic per-request APIs (cookies(), headers())
+ * Detect usage of dynamic per-request APIs (getCookies(), getHeaders())
  * that cannot work at build time in static mode.
  *
  * Returns an array of validation errors.
@@ -78,78 +74,6 @@ export function detectDynamicApis(code: string, fileId: string): StaticValidatio
   return errors;
 }
 
-// ---------------------------------------------------------------------------
-// Detection: 'use client' / 'use server' directives (clientJavascript disabled)
-// ---------------------------------------------------------------------------
-
-/**
- * Detect 'use client' and 'use server' directives using AST-based parsing.
- * When client JavaScript is disabled, both are hard build errors — no React
- * runtime or server actions are allowed in the output.
- *
- * When client JavaScript is enabled, these are allowed (client components
- * hydrate, server actions get extracted to API endpoints).
- */
-export function detectDirectives(
-  code: string,
-  fileId: string,
-  options: StaticOptions
-): StaticValidationError[] {
-  if (!options.clientJavascriptDisabled) return [];
-
-  const errors: StaticValidationError[] = [];
-
-  const clientDirective = detectFileDirective(code, ['use client']);
-  if (clientDirective) {
-    errors.push({
-      type: 'nojs-directive',
-      file: fileId,
-      message:
-        `'use client' is not allowed when client JavaScript is disabled (clientJavascript: false). ` +
-        `This mode produces zero JavaScript — client components cannot exist.`,
-      line: clientDirective.line,
-    });
-  }
-
-  const serverDirective = detectFileDirective(code, ['use server']);
-  if (serverDirective) {
-    errors.push({
-      type: 'nojs-directive',
-      file: fileId,
-      message:
-        `'use server' is not allowed when client JavaScript is disabled (clientJavascript: false). ` +
-        `This mode produces zero JavaScript — server actions cannot exist.`,
-      line: serverDirective.line,
-    });
-  }
-
-  return errors;
-}
-
-// ---------------------------------------------------------------------------
-// Combined validation
-// ---------------------------------------------------------------------------
-
-/**
- * Run all static mode validations on a source file.
- *
- * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
- * - Directive detection ('use client', 'use server') — only when client JS is disabled
- */
-export function validateStaticMode(
-  code: string,
-  fileId: string,
-  options: StaticOptions
-): StaticValidationError[] {
-  const errors: StaticValidationError[] = [];
-
-  errors.push(...detectDynamicApis(code, fileId));
-  errors.push(...detectDirectives(code, fileId, options));
-
-  return errors;
-}
-
 // ---------------------------------------------------------------------------
 // Vite Plugin
 // ---------------------------------------------------------------------------
@@ -163,9 +87,6 @@ export function validateStaticMode(
  * - transform: Validates source files for static mode violations
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-  const clientJavascriptDisabled = ctx.clientJavascript.disabled;
-
   return {
     name: 'timber-static-build',
 
@@ -173,10 +94,15 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
      * Validate source files during transform.
      *
      * In static mode, we check every app/ file for:
-     * - Dynamic API usage (cookies(), headers()) → build error
+     * - Dynamic API usage (getCookies(), getHeaders()) → build error
      * - When client JS disabled: 'use client' / 'use server' directives → build error
      */
     transform(code: string, id: string) {
+      // Read ctx.config lazily inside the hook — not at plugin construction
+      // time — so file-based config from timber.config.ts is respected.
+      // See TIM-451.
+      const isStatic = ctx.config.output === 'static';
+
       // Only active in static mode
       if (!isStatic) return null;
 
@@ -189,7 +115,7 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
       // Only check JS/TS files
       if (!/\.[jt]sx?$/.test(id)) return null;
 
-      const errors = validateStaticMode(code, id, { clientJavascriptDisabled });
+      const errors = detectDynamicApis(code, id);
 
       if (errors.length > 0) {
         // Format all errors into a single build error message

package/src/routing/codegen-shared.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared codegen helpers — import-path computation, codec chain type
+ * builder, and searchParams type formatter.
+ *
+ * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+ * helpers without a cyclic import.
+ */
+
+import { relative, posix } from 'node:path';
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+
+/**
+ * Compute a relative import specifier for a codec/page file, stripping
+ * the .ts/.tsx extension and resolving against the codegen output dir.
+ */
+export function codecImportPath(codecFilePath: string, importBase: string | undefined): string {
+  const absPath = codecFilePath.replace(/\.(ts|tsx)$/, '');
+  if (importBase) {
+    return './' + relative(importBase, absPath).replace(/\\/g, '/');
+  }
+  return './' + posix.basename(absPath);
+}
+
+/** Name of the shared helper type emitted at the top of the .d.ts. */
+export const RESOLVE_SEGMENT_FIELD_TYPE_NAME = '_TimberResolveSegmentField';
+
+/**
+ * Helper type emitted once at the top of the generated `.d.ts` and
+ * referenced by every codec-chain conditional. Without this shared
+ * helper, the inline expansion would duplicate the fallback branch on
+ * every step and grow O(2^N) in chain depth (a single deep nested route
+ * could blow up the file size and TS performance). With the helper,
+ * each step reuses the named type and growth is O(N).
+ *
+ * The helper is a 2-arg conditional: given a typeof import expression
+ * (`Def`), a key (`K`), and a fallback (`F`), it returns `T[K]` if
+ * `Def extends ParamsDefinition<T>` and `K extends keyof T`, otherwise
+ * `F`. The codec chain composes calls to this helper.
+ */
+export function emitResolveSegmentFieldHelper(): string {
+  return [
+    `type ${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<Def, K extends string, F> =`,
+    `  Def extends import('@timber-js/app/segment-params').ParamsDefinition<infer T>`,
+    `    ? K extends keyof T ? T[K] : F`,
+    `    : F;`,
+  ].join('\n');
+}
+
+/**
+ * Build a TypeScript type expression that resolves a single param's
+ * codec by walking a chain of params.ts files in priority order.
+ *
+ * Each entry in the chain emits one application of the shared
+ * `_TimberResolveSegmentField` helper type. Composing N applications
+ * grows linearly with chain depth (O(N) characters), unlike an inline
+ * conditional that would duplicate the fallback in each branch and
+ * grow O(2^N).
+ *
+ * The closest match (position 0 in the chain) is checked first; if its
+ * `segmentParams` definition declares the key, its inferred type wins.
+ * Otherwise we fall through to the next entry, and finally to the
+ * provided fallback. See TIM-834.
+ */
+export function buildCodecChainType(
+  p: ParamEntry,
+  importBase: string | undefined,
+  fallback: string
+): string {
+  const files = p.codecFilePaths;
+  if (!files || files.length === 0) return fallback;
+  const key = JSON.stringify(p.name);
+  // Compose helper applications inside-out so the closest entry
+  // (files[0]) ends up as the OUTERMOST application. Each application
+  // adds a constant-size wrapper around the running fallback.
+  let inner = fallback;
+  for (let i = files.length - 1; i >= 0; i--) {
+    const importPath = codecImportPath(files[i], importBase);
+    inner = `${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<(typeof import('${importPath}'))['segmentParams'], ${key}, ${inner}>`;
+  }
+  return inner;
+}
+
+/**
+ * Build a TypeScript type expression for a single param using the global
+ * schema's InferCodecType. Falls back to the param's base type when
+ * schema doesn't declare this param (schemas are opt-in per key).
+ *
+ * Uses `infer` to extract the codec value rather than direct indexing
+ * because TypeScript doesn't narrow index validity inside a conditional
+ * type's true branch — `typeof schema.segmentParams[K]` produces TS2538
+ * even when the condition proves K is a valid key. In .d.ts files that
+ * error is suppressed and the type silently becomes `any`.
+ */
+export function buildSchemaParamType(p: ParamEntry, fallback?: string): string {
+  const key = JSON.stringify(p.bracketName);
+  const fb = fallback ?? p.type;
+  return `typeof schema['segmentParams'] extends Record<${key}, infer V> ? InferCodecType<V> : ${fb}`;
+}
+
+/**
+ * Format the searchParams type for a route entry.
+ *
+ * When a page.tsx (or params.ts) exports searchParams, we reference its
+ * inferred type via an import type. The import path is relative to
+ * `importBase` (the directory where the .d.ts will be written). When
+ * importBase is undefined, falls back to a bare relative path.
+ */
+export function formatSearchParamsType(route: RouteEntry, importBase?: string): string {
+  if (route.hasSearchParams && route.searchParamsPagePath) {
+    const importPath = codecImportPath(route.searchParamsPagePath, importBase);
+    // Extract the type from the named 'searchParams' export of the page module.
+    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
+  }
+  return '{}';
+}

package/src/routing/codegen-types.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared types for route codegen modules.
+ *
+ * Lives in its own file so `link-codegen.ts` and `codegen.ts` can import
+ * the same `RouteEntry` / `ParamEntry` shapes without a cyclic
+ * dependency between the two.
+ */
+
+/** A single route entry extracted from the segment tree. */
+export interface RouteEntry {
+  /** URL path pattern (e.g. "/products/[id]") */
+  urlPath: string;
+  /** Full tree path including groups and slots (e.g. "/(browse)/[artistSlug]/@shows/[year]").
+   *  Uniquely identifies a segment — unlike urlPath which strips groups/slots. */
+  segmentPath: string;
+  /** Accumulated params from all ancestor dynamic segments */
+  params: ParamEntry[];
+  /** Whether the page.tsx exports searchParams */
+  hasSearchParams: boolean;
+  /** Absolute path to the page file that exports searchParams (for import paths) */
+  searchParamsPagePath?: string;
+  /** Whether this is an API route (route.ts) vs page route */
+  isApiRoute: boolean;
+  /** Whether a global schema (app/schema.ts) exists for this app */
+  hasSchema?: boolean;
+}
+
+export interface ParamEntry {
+  name: string;
+  /** Bracket-wrapped segment name as it appears in the filesystem and schema.
+   *  e.g. '[id]', '[...slug]', '[[...slug]]' */
+  bracketName: string;
+  type: 'string' | 'string[]' | 'string[] | undefined';
+  /**
+   * Ordered list of params.ts files in the route chain that may declare
+   * a codec for this param, in priority order — **closest-to-leaf
+   * first**. The generated type emits a chain that picks the first
+   * entry whose `segmentParams` definition declares this param key.
+   *
+   * This array is the SAME for every param in a given route entry
+   * (it is the route's full ancestry of params.ts files in leaf-first
+   * order); the type-level conditional in `buildCodecChainType`
+   * narrows per-key. Sharing the array matches the runtime semantics
+   * of `coerceSegmentParams`, which walks segments top-down and lets
+   * later (deeper) coercions overwrite earlier ones — closest-to-leaf
+   * wins for both types and runtime.
+   *
+   * See TIM-834.
+   */
+  codecFilePaths?: string[];
+  /**
+   * Per-segment legacy fallback: a layout.tsx or page.tsx that exports
+   * `segmentParams` directly (pre-TIM-508 convention). Used only when
+   * the chain has no params.ts files at all. Does NOT participate in
+   * inheritance — a layout/page export is per-segment only.
+   *
+   * @internal Set during `collectRoutes`; consumed at leaf time when
+   *   building the final `codecFilePaths`.
+   */
+  legacyCodecFilePath?: string;
+}