@timber-js/app 0.2.0-alpha.192 → 0.2.0-alpha.195

package/src/plugins/request-dep/analysis.ts

@@ -23,7 +23,7 @@ import type {
   IdentifierNode,
   CallExpressionNode,
   MemberExpressionNode,
-} from '../callsite-ast.js';
+} from '../callsite-ast.ts';
 
 /**
  * One module-graph edge introduced by an `import` or `export … from`.

package/src/plugins/request-dep/index.ts

@@ -24,14 +24,14 @@
  */
 
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../../plugin-context.js';
-import type { ProgramNode } from '../callsite-ast.js';
-import { analyzeModule, usedSources, contributesNothing, type ModuleFacts } from './analysis.js';
-import { createOriginResolver, FRAMEWORK_SOURCES } from './origin.js';
-
-export type { ModuleFacts } from './analysis.js';
-export { analyzeModule, usedSources } from './analysis.js';
-export { createOriginResolver } from './origin.js';
+import type { PluginContext } from '../../plugin-context.ts';
+import type { ProgramNode } from '../callsite-ast.ts';
+import { analyzeModule, usedSources, contributesNothing, type ModuleFacts } from './analysis.ts';
+import { createOriginResolver, FRAMEWORK_SOURCES } from './origin.ts';
+
+export type { ModuleFacts } from './analysis.ts';
+export { analyzeModule, usedSources } from './analysis.ts';
+export { createOriginResolver } from './origin.ts';
 
 // ─── Framework module detection ─────────────────────────────────────────
 

package/src/plugins/request-dep/origin.ts

@@ -16,7 +16,7 @@
  * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
  */
 
-import type { CalleeRef, ImportEdge, ModuleFacts } from './analysis.js';
+import type { CalleeRef, ImportEdge, ModuleFacts } from './analysis.ts';
 
 // ─── What counts as a request accessor ───────────────────────────────────
 

package/src/plugins/routing.ts

@@ -10,17 +10,17 @@
 
 import type { Plugin, ViteDevServer } from 'vite';
 import { join } from 'node:path';
-import { scanRoutes } from '../routing/scanner.js';
-import { buildDirToRouteMap, type SegmentInfo } from '../routing/segment-codegen.js';
-import { writeRouteCodegen, flushCodegenWrites } from '../routing/codegen-write.js';
-import { validateSchemaAgainstRoutes } from '../routing/schema-validation.js';
-import { generateManifestModule, generateSchemaModule } from '../routing/manifest-codegen.js';
+import { scanRoutes } from '../routing/scanner.ts';
+import { buildDirToRouteMap, type SegmentInfo } from '../routing/segment-codegen.ts';
+import { writeRouteCodegen, flushCodegenWrites } from '../routing/codegen-write.ts';
+import { validateSchemaAgainstRoutes } from '../routing/schema-validation.ts';
+import { generateManifestModule, generateSchemaModule } from '../routing/manifest-codegen.ts';
 import {
   lintConventions,
   checkAppDirExists,
   formatConventionWarnings,
-} from '../routing/convention-lint.js';
-import type { PluginContext } from '../plugin-context.js';
+} from '../routing/convention-lint.ts';
+import type { PluginContext } from '../plugin-context.ts';
 
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
@@ -62,6 +62,11 @@ const ROUTE_FILE_PATTERNS =
  */
 function writeCodegen(ctx: PluginContext): void {
   if (!ctx.routeTree) return;
+  // The analyze crawl child only needs the route tree for
+  // classification — codegen writes are fire-and-forget and can be
+  // truncated by the child's process.exit, leaving partial .d.ts
+  // files on disk.
+  if (process.env.TIMBER_ANALYZE === '1') return;
   void writeRouteCodegen(ctx.routeTree, ctx.appDir, ctx.root).catch((err) => {
     console.warn('[timber] Failed to write codegen output:', err);
   });

package/src/plugins/server-bundle.ts

@@ -13,6 +13,13 @@
 
 import { builtinModules } from 'node:module';
 import type { Plugin } from 'vite';
+import { EXPLICIT_MARKERS } from '../analyze/poison-rules.ts';
+
+// The poison-pill marker packages (server-only, client-only) must never be
+// externalized — they have to reach the timber-shims resolveId hook so it
+// can substitute the poison virtual modules. Derived from poison-rules.ts
+// so the list cannot drift from what shims.ts intercepts.
+const POISON_MARKER_SPECIFIERS = EXPLICIT_MARKERS.map((m) => m.specifier);
 
 // Every Node built-in as both bare (`stream`) and prefixed (`node:stream`).
 // Available at runtime on all targets (Node natively, Workers via nodejs_compat).
@@ -80,12 +87,12 @@ export function timberServerBundle(): Plugin[] {
           environments: {
             rsc: {
               resolve: {
-                noExternal: ['server-only', 'client-only'],
+                noExternal: [...POISON_MARKER_SPECIFIERS],
               },
             },
             ssr: {
               resolve: {
-                noExternal: ['server-only', 'client-only', 'nuqs'],
+                noExternal: [...POISON_MARKER_SPECIFIERS, 'nuqs'],
               },
             },
           },

package/src/plugins/shims.ts

@@ -17,7 +17,8 @@
 import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
+import { EXPLICIT_MARKERS, markerFor, poisonPillSource } from '../analyze/poison-rules.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Detect whether we're running from source (src/plugins/) or dist (dist/).
@@ -30,14 +31,13 @@ const PKG_ROOT = __dirname.endsWith('plugins')
 const SHIMS_DIR = resolve(PKG_ROOT, 'src', 'shims');
 
 /**
- * Virtual module IDs for server-only and client-only poison pills.
- *
- * These packages cause build errors when imported in the wrong environment:
- * - `server-only` errors when imported in a client component
- * - `client-only` errors when imported in a server component
+ * The server-only marker's virtual ID, needed directly by the
+ * `#server-only-guard` resolution branch below. All poison-pill rules
+ * (specifiers, virtual IDs, error messages, environment policy) live in
+ * analyze/poison-rules.ts — the single source of truth shared with the
+ * `timber graph` reporter (design/47 §3).
  */
-const SERVER_ONLY_VIRTUAL = '\0timber:server-only';
-const CLIENT_ONLY_VIRTUAL = '\0timber:client-only';
+const SERVER_ONLY_VIRTUAL = markerFor('server-only').virtualId;
 
 /**
  * Map from @timber-js/app/<subpath> to relative src/ file paths.
@@ -191,8 +191,9 @@ export function timberShims(_ctx: PluginContext): Plugin {
      */
     resolveId(id: string) {
       // Poison pill packages — resolve to virtual modules handled by load()
-      if (id === 'server-only') return SERVER_ONLY_VIRTUAL;
-      if (id === 'client-only') return CLIENT_ONLY_VIRTUAL;
+      for (const marker of EXPLICIT_MARKERS) {
+        if (id === marker.specifier) return marker.virtualId;
+      }
 
       const cleanId = stripJsExtension(id);
 
@@ -351,28 +352,12 @@ export function timberShims(_ctx: PluginContext): Plugin {
      */
     load(id: string) {
       const env = envName(this);
-      const isClient = env === 'client';
-
-      if (id === SERVER_ONLY_VIRTUAL) {
-        if (isClient) {
-          return `throw new Error(
-  "This module cannot be imported from a Client Component module. " +
-  "It should only be used from a Server Component."
-);`;
-        }
-        // No-op in server environments (rsc, ssr)
-        return 'export {};';
-      }
 
-      if (id === CLIENT_ONLY_VIRTUAL) {
-        if (!isClient) {
-          return `throw new Error(
-  "This module cannot be imported from a Server Component module. " +
-  "It should only be used from a Client Component."
-);`;
-        }
-        // No-op in client environment
-        return 'export {};';
+      // Poison pill bodies — a top-level throw in the wrong environment,
+      // a no-op in the right one. Behavior (which environments throw, and
+      // the exact message) is defined entirely by poison-rules.ts.
+      for (const marker of EXPLICIT_MARKERS) {
+        if (id === marker.virtualId) return poisonPillSource(marker, env);
       }
 
       // Error module for @timber-js/app/server in client environment.

package/src/plugins/static-build.ts

@@ -14,25 +14,25 @@ import { mkdir, readdir, readFile, writeFile, rename, rm, stat } from 'node:fs/p
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, extname, isAbsolute, join, resolve, relative } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
 import type {
   StaticGenerationOptions,
   StaticGenerationSummary,
   StaticPageEntry,
   StaticRedirectEntry,
-} from '../server/static-generator.js';
-import { mergeRscAssetsManifest } from './adapter-build.js';
-import { isRelativeBase, normalizeBasePath, withBasePath } from '../shared/base-path.js';
-import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.js';
-import { htmlEscapeJsonString } from '../server/flight-scripts.js';
-import { rscPayloadPath } from '../shared/rsc-payload-path.js';
-import { REDIRECTS_FILE, RESERVED_OUTPUT_PATHS } from '../shared/static-platform-files.js';
+} from '../server/static-generator.ts';
+import { mergeRscAssetsManifest } from './adapter-build.ts';
+import { isRelativeBase, normalizeBasePath, withBasePath } from '../shared/base-path.ts';
+import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.ts';
+import { htmlEscapeJsonString } from '../server/flight-scripts.ts';
+import { rscPayloadPath } from '../shared/rsc-payload-path.ts';
+import { REDIRECTS_FILE, RESERVED_OUTPUT_PATHS } from '../shared/static-platform-files.ts';
 import {
   detectFsIdentity,
   fsKey,
   EXACT_FS_IDENTITY,
   type FsIdentity,
-} from '../adapters/fs-identity.js';
+} from '../adapters/fs-identity.ts';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -45,7 +45,7 @@ import {
  */
 // Declared in shared/rsc-manifest.ts so the client that reads this manifest and
 // the build that writes it cannot drift. Re-exported for existing importers.
-export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.js';
+export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.ts';
 
 export interface StaticValidationError {
   type: 'dynamic-api';

package/src/routing/codegen-shared.ts

@@ -7,7 +7,7 @@
  */
 
 import { relative, posix } from 'node:path';
-import type { ParamEntry } from './codegen-types.js';
+import type { ParamEntry } from './codegen-types.ts';
 
 /**
  * Compute a relative import specifier for a codec/page file, stripping

package/src/routing/codegen-write.ts

@@ -17,9 +17,9 @@
 
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { generateRouteMap } from './codegen.js';
-import { writeSegmentTypes } from './segment-codegen.js';
-import type { RouteTree } from './types.js';
+import { generateRouteMap } from './codegen.ts';
+import { writeSegmentTypes } from './segment-codegen.ts';
+import type { RouteTree } from './types.ts';
 
 /**
  * Path (relative to the project root) of the generated route map declaration

package/src/routing/codegen.ts

@@ -10,11 +10,11 @@
 
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import type { RouteTree, SegmentNode } from './types.js';
-import type { ParamEntry, RouteEntry } from './codegen-types.js';
-import { buildSchemaParamType } from './codegen-shared.js';
-import { effectiveUrlSegment, type UrlSegmentIdentity } from './segment-classify.js';
-import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';
+import type { RouteTree, SegmentNode } from './types.ts';
+import type { ParamEntry, RouteEntry } from './codegen-types.ts';
+import { buildSchemaParamType } from './codegen-shared.ts';
+import { effectiveUrlSegment, type UrlSegmentIdentity } from './segment-classify.ts';
+import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.ts';
 
 /** Options for route map generation. */
 export interface CodegenOptions {
@@ -325,6 +325,15 @@ function formatDeclarationFile(
       lines.push('}');
       lines.push('');
     }
+    // Guard: detect when the schema or params imports silently degraded to
+    // `any` because TypeScript could not resolve the import specifier.
+    // In a .d.ts an unresolved import does NOT error — every downstream
+    // type silently becomes `any`, which satisfies every assertion. Only
+    // an explicit IsAny check catches it.
+    lines.push('type _IsAny<T> = 0 extends 1 & T ? true : false;');
+    lines.push('type _AssertSchemaNotAny<_T extends false = _IsAny<typeof schema>> = true;');
+    lines.push('type _AssertCodecTypeNotAny<_T extends false = _IsAny<SegmentParamCodec>> = true;');
+    lines.push('');
     // Type-level validation: each schema value must be a Codec or Standard Schema.
     // Running `pnpm run typecheck` will surface errors for invalid values.
     lines.push('type _AssertSchemaValues = {');

package/src/routing/collision-probe.ts

@@ -41,13 +41,13 @@
  * See design/07-routing.md §"Comparing Routes by the URLs They Match".
  */
 
-import type { SegmentNode } from './types.js';
-import { effectiveUrlSegment } from './segment-classify.js';
+import type { SegmentNode } from './types.ts';
+import { effectiveUrlSegment } from './segment-classify.ts';
 // The validators ask the real matcher which page answers a URL rather than
 // modelling its precedence rules a second time. `tree-match.ts` is a pure
 // walker over `SegmentNode` with no request-time state, and
 // `server/chain-url-parts.ts` already imports the other direction.
-import { matchUrlParts } from '../server/tree-match.js';
+import { matchUrlParts } from '../server/tree-match.ts';
 
 /** One page-or-route-bearing node in a collision space. */
 export interface ProbeLeaf {

package/src/routing/collision-spaces.ts

@@ -11,9 +11,9 @@
  * See design/07-routing.md §"Route Collisions".
  */
 
-import type { SegmentNode } from './types.js';
-import { computeInterceptedUrlBase } from './interception.js';
-import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.js';
+import type { SegmentNode } from './types.ts';
+import { computeInterceptedUrlBase } from './interception.ts';
+import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.ts';
 
 /**
  * Validate that no two pages/routes in one collision space answer the same URL.

package/src/routing/convention-lint.ts

@@ -17,17 +17,17 @@
  * Design doc: 07-routing.md, 10-error-handling.md
  */
 
-import { existsSync } from 'node:fs';
-import type { RouteFile, RouteTree, SegmentNode } from './types.js';
-import { swallow } from '../server/logger.js';
-import { isMdxFilePath } from '../server/utils/mdx-file.js';
+import { existsSync, readFileSync } from 'node:fs';
+import type { RouteFile, RouteTree, SegmentNode } from './types.ts';
+import { swallow } from '../server/logger.ts';
+import { isMdxFilePath } from '../server/utils/mdx-file.ts';
 import {
   fileDefaultExportIsLocalValue,
   fileHasAnyExport,
   fileHasDefaultExport,
   fileHasDirective,
   fileHasStarExport,
-} from './export-detect.js';
+} from './export-detect.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -69,15 +69,56 @@ export function lintConventions(tree: RouteTree, appDir: string): ConventionWarn
   // Check 5: page.tsx / layout.tsx without default export
   checkDefaultExports(tree.root, warnings);
 
-  // Check 6: error.tsx / 404.tsx / 4xx.tsx / … without 'use client' directive
+  // Check 6: Client layouts cannot suppress server children before Flight
+  // serializes them. They remain valid UI boundaries, but not authorization
+  // or data-hiding boundaries.
+  checkClientLayouts(tree.root, warnings);
+
+  // Check 7: error.tsx / 404.tsx / 4xx.tsx / … without 'use client' directive
   checkClientBoundaryFiles(tree.root, warnings);
   if (tree.globalError) {
     checkFileUseClientDirective(tree.globalError, 'global-error', warnings);
   }
 
+  // Check 8: Wildcard MDX status files (4xx.mdx, 5xx.mdx, error.mdx) that
+  // reference `props` — props resolve on deny and throw paths but are empty
+  // on the boundary path. See design/10-error-handling.md §"MDX Props by Path".
+  checkWildcardMdxProps(tree.root, warnings);
+
   return warnings;
 }
 
+function checkClientLayouts(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.layout && isScriptExtension(node.layout.extension)) {
+    try {
+      const isClient = fileHasDirective(node.layout.filePath, 'use client');
+      const isProvablyServer = fileDefaultExportIsLocalValue(node.layout.filePath);
+      if (isClient || !isProvablyServer) {
+        const certainty = isClient
+          ? `This layout is a client component.`
+          : `Timber cannot prove this layout is a server component because its default export comes from another module or an opaque expression.`;
+        warnings.push({
+          id: `CLIENT_LAYOUT_NOT_AUTH_BOUNDARY:${node.layout.filePath}`,
+          summary: isClient
+            ? `Client layout cannot securely suppress server children: ${node.layout.filePath}`
+            : `Layout may resolve to a client component and cannot be trusted as an auth boundary: ${node.layout.filePath}`,
+          details:
+            `  File: ${node.layout.filePath}\n\n` +
+            `  ${certainty}\n` +
+            `  React Flight resolves server content passed to a client layout before the layout runs in the browser.\n` +
+            `  Conditionally omitting children here does not prevent descendant server components from executing or being serialized.\n\n` +
+            `  To fix: Put authorization in access.ts or a provably server layout with a locally defined default component, and keep client components inside that boundary.\n`,
+          level: 'warn',
+        });
+      }
+    } catch (err) {
+      swallow(err, `convention-lint: unreadable layout file ${node.layout.filePath}`);
+    }
+  }
+  for (const child of node.children) checkClientLayouts(child, warnings);
+  for (const slot of Object.values(node.slots)) checkClientLayouts(slot, warnings);
+}
+
 // ─── Check: Empty App ───────────────────────────────────────────────────────
 
 /**
@@ -408,6 +449,95 @@ function checkFileUseClientDirective(
   });
 }
 
+// ─── Check: Wildcard MDX Props ──────────────────────────────────────────────
+
+/**
+ * Wildcard status file keys in `statusFiles` whose props differ by path.
+ * `error` is not here — the scanner stores it in `node.error`, not
+ * `node.statusFiles`, and the check handles it separately below.
+ */
+const WILDCARD_MDX_STATUS_KEYS = new Set(['4xx', '5xx']);
+
+/**
+ * Warn when a wildcard MDX status file (`4xx.mdx`, `5xx.mdx`, `error.mdx`)
+ * appears to reference `props` in its source.
+ *
+ * These files are pre-rendered into `fallbackElement` on the error-boundary
+ * path, before the error happens, so they receive empty or partial props.
+ * On the deny and error-renderer paths they receive the real props. An author
+ * writing `{props.status}` gets the number on some paths and `undefined` on
+ * others — same source, different output.
+ *
+ * A text scan for `props` is acceptable here because the check is `level:
+ * 'warn'` — a false positive costs a printed line, not a refused build. A
+ * sound check would need the MDX compiler, which is optional, async, and
+ * scoped to the RSC environment. See TIM-1333.
+ *
+ * Exact-code MDX files (e.g. `503.mdx`) are unaffected — all four paths
+ * agree on their status.
+ */
+function checkWildcardMdxProps(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.statusFiles) {
+    for (const [key, file] of Object.entries(node.statusFiles)) {
+      if (WILDCARD_MDX_STATUS_KEYS.has(key) && isMdxFilePath(file.filePath)) {
+        checkMdxFileForProps(file.filePath, key, warnings);
+      }
+    }
+  }
+  if (node.error && isMdxFilePath(node.error.filePath)) {
+    checkMdxFileForProps(node.error.filePath, 'error', warnings);
+  }
+
+  for (const child of node.children) {
+    checkWildcardMdxProps(child, warnings);
+  }
+  for (const slot of Object.values(node.slots)) {
+    checkWildcardMdxProps(slot, warnings);
+  }
+}
+
+/**
+ * Check if an MDX file's source appears to reference `props`.
+ *
+ * MDX passes a `props` object to the default export function. A reference to
+ * `props.status` or `props.dangerouslyPassData` in a wildcard file works on
+ * the deny/throw paths but renders `undefined` on the boundary path.
+ */
+function checkMdxFileForProps(
+  filePath: string,
+  convention: string,
+  warnings: ConventionWarning[]
+): void {
+  let source: string;
+  try {
+    source = readFileSync(filePath, 'utf-8');
+  } catch {
+    return;
+  }
+
+  // MDX exposes props via the default export: export default function(props) { ... }
+  // and via JSX expressions: {props.status}. A text scan is intentionally
+  // broad — false positives are cheap at warn level.
+  if (!/\bprops\b/.test(source)) return;
+
+  const label = `${convention}.${filePath.endsWith('.md') ? 'md' : 'mdx'}`;
+  warnings.push({
+    id: `MDX_WILDCARD_PROPS:${filePath}`,
+    summary: `${label} references props, which are empty on the error boundary path: ${filePath}`,
+    details:
+      `  File: ${filePath}\n\n` +
+      `  Wildcard MDX status files (${convention}.mdx) are pre-rendered into\n` +
+      '  fallbackElement before the error occurs. On that path, props are\n' +
+      `  empty${convention === 'error' ? '' : ' (no status, no dangerouslyPassData)'}. On the deny() and error-renderer\n` +
+      '  paths, props.status resolves correctly.\n\n' +
+      '  If this file uses only static content and "props" appears in prose,\n' +
+      '  this warning is a false positive — ignore it.\n\n' +
+      '  To fix: Use only static content in wildcard MDX status files, or\n' +
+      '  use an exact-code file (e.g. 404.mdx) where all paths agree.\n',
+    level: 'warn',
+  });
+}
+
 // ─── Check: App Directory Exists ────────────────────────────────────────────
 
 /**

package/src/routing/export-detect.ts

@@ -8,7 +8,7 @@
 
 import { existsSync } from 'node:fs';
 import { parseAst } from 'vite';
-import { readFileCached } from './file-cache.js';
+import { readFileCached } from './file-cache.ts';
 
 interface AstNode {
   type: string;

package/src/routing/index.ts

@@ -1,6 +1,6 @@
-export { scanRoutes } from './scanner.js';
-export { generateRouteMap } from './codegen.js';
-export type { CodegenOptions } from './codegen.js';
+export { scanRoutes } from './scanner.ts';
+export { generateRouteMap } from './codegen.ts';
+export type { CodegenOptions } from './codegen.ts';
 export type {
   RouteTree,
   SegmentNode,
@@ -8,16 +8,16 @@ export type {
   RouteFile,
   ScannerConfig,
   InterceptionMarker,
-} from './types.js';
-export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-export { collectInterceptionRewrites } from './interception.js';
-export type { InterceptionRewrite } from './interception.js';
-export { classifyUrlSegment, classifySegment } from './segment-classify.js';
-export type { UrlSegment, SegmentClassification } from './segment-classify.js';
-export { collectLeafRoutes } from './walkers.js';
-export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.js';
+} from './types.ts';
+export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.ts';
+export { collectInterceptionRewrites } from './interception.ts';
+export type { InterceptionRewrite } from './interception.ts';
+export { classifyUrlSegment, classifySegment } from './segment-classify.ts';
+export type { UrlSegment, SegmentClassification } from './segment-classify.ts';
+export { collectLeafRoutes } from './walkers.ts';
+export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.ts';
 export {
   validateSchemaAgainstRoutes,
   collectDynamicSegmentsFromTree,
-} from './schema-validation.js';
-export type { SchemaWarning } from './schema-validation.js';
+} from './schema-validation.ts';
+export type { SchemaWarning } from './schema-validation.ts';

package/src/routing/interception.ts

@@ -17,13 +17,13 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
-import type { SegmentNode, InterceptionMarker, RouteFile } from './types.js';
-import { computeSegmentTreePaths, treePathDepth } from './segment-keys.js';
-import { classifyUrlSegment, effectiveUrlSegment } from './segment-classify.js';
+import type { SegmentNode, InterceptionMarker, RouteFile } from './types.ts';
+import { computeSegmentTreePaths, treePathDepth } from './segment-keys.ts';
+import { classifyUrlSegment, effectiveUrlSegment } from './segment-classify.ts';
 // Every collision space — the main tree, each slot, each intercepting subtree
 // — decides order-dependence with the same oracle, so the spaces cannot drift
 // on what counts as two pages answering one URL. See TIM-1308.
-import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.js';
+import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.ts';
 
 /** Fields shared by both interception shapes. */
 interface InterceptionRewriteBase {
@@ -505,6 +505,42 @@ function assertInterceptedCatchAllsAreTerminal(node: SegmentNode, nodePath: stri
   }
 }
 
+/**
+ * Reject a `route.ts` anywhere inside an intercepting subtree.
+ *
+ * An interception is a soft-navigation variant of a page — it swaps which
+ * page component renders. A route handler returns a `Response` and cannot
+ * be an interception target: `walkInterceptedLeaves` visits `node.page`
+ * only, so no rewrite is emitted for it, but `isTerminal` in
+ * `tree-match.ts` counts both `page` and `route`, so `matchUrlParts` can
+ * resolve to the route handler. `slot-interception.ts` then drops the
+ * match (`if (!leaf.page) continue`), silently disabling the page's
+ * interception. Fail-safe (the canonical route renders) but silent.
+ *
+ * The walk mirrors `assertInterceptedCatchAllsAreTerminal`: it descends
+ * `children` (not `slots`), matching `collectLeavesWithRewrites` exactly.
+ */
+function assertNoRouteHandlersInSubtree(node: SegmentNode, nodePath: string): void {
+  if (node.route) {
+    throw new Error(
+      `Build error: route handler inside an intercepting route.\n` +
+        `  File: ${node.route.filePath}\n` +
+        `  Directory: app/${nodePath}\n` +
+        `An intercepting subtree renders a page component on soft navigation — a ` +
+        `route handler returns a Response and cannot be an interception target. ` +
+        `The route handler would silently shadow the interception: the resolver ` +
+        `would match it and then discard it because it has no page, so the modal ` +
+        `would stop opening with no diagnostic.\n` +
+        `Remove the route.ts, or move it outside the intercepting subtree.\n` +
+        `See design/07-routing.md §"Intercepting Routes".`
+    );
+  }
+
+  for (const child of node.children) {
+    assertNoRouteHandlersInSubtree(child, `${nodePath}/${child.segmentName}`);
+  }
+}
+
 /**
  * Reject two pages that answer one URL among the interceptors an owner
  * resolves in a single walk.
@@ -723,6 +759,7 @@ function walkForPlacement(node: SegmentNode, path: string, ctx: PlacementContext
       // interception. The same input rewrite generation bases from.
       assertInterceptedBaseIsCountable(child, node.urlPath, childPath);
       assertInterceptedCatchAllsAreTerminal(child, childPath);
+      assertNoRouteHandlersInSubtree(child, childPath);
     }
 
     walkForPlacement(child, childPath, {

package/src/routing/link-codegen.ts

@@ -23,9 +23,9 @@
  * overload TS reports against on failure.
  */
 
-import type { ParamEntry, RouteEntry } from './codegen-types.js';
-import { buildSchemaParamType } from './codegen-shared.js';
-import { classifyUrlSegment } from './segment-classify.js';
+import type { ParamEntry, RouteEntry } from './codegen-types.ts';
+import { buildSchemaParamType } from './codegen-shared.ts';
+import { classifyUrlSegment } from './segment-classify.ts';
 
 /**
  * The `searchParams` prop type, emitted identically on every Link variant

package/src/routing/manifest-codegen.ts

@@ -10,8 +10,8 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { collectInterceptionRewrites } from './interception.js';
-import type { RouteTree, SegmentNode, RouteFile } from './types.js';
+import { collectInterceptionRewrites } from './interception.ts';
+import type { RouteTree, SegmentNode, RouteFile } from './types.ts';
 
 // ── Single-file conventions ─────────────────────────────────────────────
 // Each entry maps to a node property that holds a single RouteFile.