@timber-js/app 0.2.0-alpha.191 → 0.2.0-alpha.194

package/src/plugins/mdx.ts

@@ -1,10 +1,22 @@
 /**
- * timber-mdx — Vite sub-plugin for MDX page rendering.
+ * timber-mdx — Vite sub-plugin for MDX and Markdown rendering.
  *
- * Wires @mdx-js/rollup into the Vite pipeline when MDX is activated.
+ * Wires vite-plugin-satteri into the Vite pipeline when MDX is activated.
  * MDX is activated when pageExtensions includes 'mdx' or 'md', or
  * when a content/ directory exists at the project root.
  *
+ * Satteri is a Rust-based Markdown/MDX compiler with a native Vite plugin:
+ * - `.mdx` files compile to React components (ES modules with real import
+ *   statements, so @vitejs/plugin-rsc client-boundary detection works).
+ * - `.md` files compile to modules exporting a rendered HTML string.
+ * - Frontmatter (YAML/TOML) parses natively and is emitted as a
+ *   `frontmatter` named export — no remark plugins needed.
+ * - GFM (tables, footnotes, strikethrough, task lists) is on by default.
+ *
+ * Extensibility is satteri's visitor-based plugin API (defineMdastPlugin /
+ * defineHastPlugin), not unified — the AST lives on the Rust side, so
+ * remark/rehype plugins cannot run. See design/20-content-collections.md.
+ *
  * Design doc: 20-content-collections.md §"The timber-mdx Plugin"
  */
 
@@ -13,9 +25,10 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
+import { MDX_EXTENSIONS } from '../server/utils/mdx-file.ts';
 
-const MDX_EXTENSIONS = ['mdx', 'md'];
+const MDX_EXTENSIONS_UNDOTTED = [...MDX_EXTENSIONS].map((ext) => ext.slice(1));
 
 /**
  * Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
@@ -43,8 +56,14 @@ export function findMdxComponents(root: string): string | undefined {
  * Determine if MDX should be activated based on config and project structure.
  */
 function shouldActivate(ctx: PluginContext): boolean {
+  // Explicit opt-out — the escape hatch for apps that register their own
+  // MDX compiler (e.g. @mdx-js/rollup for the unified pipeline) in
+  // vite.config.ts. Without this, a content/ directory would force
+  // activation no matter what pageExtensions says.
+  if (ctx.config.mdx === false) return false;
+
   const exts = ctx.config.pageExtensions;
-  if (exts && exts.some((ext) => MDX_EXTENSIONS.includes(ext))) {
+  if (exts && exts.some((ext) => MDX_EXTENSIONS_UNDOTTED.includes(ext))) {
     return true;
   }
 
@@ -61,13 +80,11 @@ function shouldActivate(ctx: PluginContext): boolean {
  *
  * Why this matters: pnpm only hoists declared (peer) dependencies into a
  * package's resolution scope. The MDX integration's optional companions
- * — `remark-frontmatter`, `remark-mdx-frontmatter`, `@mdx-js/rollup` — are
- * installed as direct deps of the consumer (e.g. `packages/website`), not
- * `@timber-js/app`. A bare `import('remark-frontmatter')` from inside this
- * file resolves against `packages/timber-app/node_modules` and silently
- * fails with `ERR_MODULE_NOT_FOUND`, which made `tryImport` return
- * `undefined` and skipped frontmatter parsing entirely — leaving MDX to
- * choke on YAML as JS expressions (TIM-840).
+ * — `vite-plugin-satteri` and `satteri` — are installed as direct deps of
+ * the consumer (e.g. `packages/website`), not `@timber-js/app`. A bare
+ * `import('vite-plugin-satteri')` from inside this file resolves against
+ * `packages/timber-app/node_modules` and silently fails with
+ * `ERR_MODULE_NOT_FOUND` (TIM-840).
  *
  * Resolving relative to `projectRoot` (via `createRequire`) makes the
  * lookup walk the consumer's `node_modules` tree first, which is where
@@ -106,9 +123,10 @@ async function tryImport(name: string, projectRoot: string): Promise<unknown | u
  * Create the timber-mdx Vite plugin.
  *
  * Uses the transform and resolveId hooks to delegate MDX compilation
- * to @mdx-js/rollup. The inner plugin is loaded lazily on first activation.
+ * to vite-plugin-satteri. The inner plugin is loaded lazily on first
+ * activation.
  *
- * Hooks: buildStart (loads @mdx-js/rollup), resolveId, load, transform
+ * Hooks: buildStart (loads vite-plugin-satteri), resolveId, load, transform
  */
 export function timberMdx(ctx: PluginContext): Plugin {
   let innerPlugin: Plugin | null = null;
@@ -116,50 +134,60 @@ export function timberMdx(ctx: PluginContext): Plugin {
   async function activate(): Promise<void> {
     if (innerPlugin !== null || !shouldActivate(ctx)) return;
 
-    const createMdxPlugin = (await tryImport('@mdx-js/rollup', ctx.root)) as
+    // Satteri compiles .md to an HTML string, not a component — a page.md
+    // route would make the renderer invoke a string as a component and
+    // TypeError at request time. Fail at startup instead. Imported .md
+    // files work without listing 'md' in pageExtensions.
+    if (ctx.config.pageExtensions?.includes('md')) {
+      throw new Error(
+        [
+          "[timber] pageExtensions includes 'md', but .md route pages are not supported:",
+          'Markdown files compile to HTML strings, not components.',
+          '',
+          "Use .mdx for pages (pageExtensions: ['tsx', 'ts', 'mdx']).",
+          '.md files can still be imported as HTML strings — no pageExtensions entry needed.',
+        ].join('\n')
+      );
+    }
+
+    const createSatteriPlugin = (await tryImport('vite-plugin-satteri', ctx.root)) as
       | ((options?: Record<string, unknown>) => Plugin)
       | undefined;
 
-    if (!createMdxPlugin) {
+    if (!createSatteriPlugin) {
       throw new Error(
         [
-          '[timber] MDX is enabled but @mdx-js/rollup is not installed.',
+          '[timber] MDX is enabled but vite-plugin-satteri is not installed.',
           '',
           'Install it:',
-          '  pnpm add -D @mdx-js/rollup remark-frontmatter remark-mdx-frontmatter',
+          '  pnpm add -D vite-plugin-satteri satteri',
           '',
           'MDX is activated because pageExtensions includes "mdx"/"md" or a content/ directory exists.',
         ].join('\n')
       );
     }
 
-    const mdxConfig = ctx.config.mdx ?? {};
-
-    // Auto-register frontmatter plugins. Resolve from the consumer's root
-    // so pnpm finds packages declared in the user's package.json (TIM-840).
-    const remarkPlugins: unknown[] = [];
-    const remarkFrontmatter = await tryImport('remark-frontmatter', ctx.root);
-    const remarkMdxFrontmatter = await tryImport('remark-mdx-frontmatter', ctx.root);
-    if (remarkFrontmatter) remarkPlugins.push(remarkFrontmatter);
-    if (remarkMdxFrontmatter) remarkPlugins.push(remarkMdxFrontmatter);
-
-    if (mdxConfig.remarkPlugins) {
-      remarkPlugins.push(...mdxConfig.remarkPlugins);
-    }
+    // `|| {}` (not `??`): mdx can be `false`, though shouldActivate() has
+    // already bailed in that case.
+    const mdxConfig = ctx.config.mdx || {};
 
-    const mdxOptions: Record<string, unknown> = {
-      remarkPlugins,
-      rehypePlugins: mdxConfig.rehypePlugins ?? [],
-      recmaPlugins: mdxConfig.recmaPlugins ?? [],
-      remarkRehypeOptions: mdxConfig.remarkRehypeOptions,
-    };
+    // We pass `development` explicitly (satteri otherwise infers it from
+    // Vite's command via its own configResolved hook, which we don't
+    // delegate) and control providerImportSource — the mdx-components.tsx
+    // convention belongs to the framework, not the user config.
+    const mdxOptions: Record<string, unknown> = { development: ctx.dev };
 
     const mdxComponentsPath = findMdxComponents(ctx.root);
     if (mdxComponentsPath) {
       mdxOptions.providerImportSource = mdxComponentsPath;
     }
 
-    innerPlugin = createMdxPlugin(mdxOptions);
+    innerPlugin = createSatteriPlugin({
+      mdx: mdxOptions,
+      ...(mdxConfig.mdastPlugins ? { mdastPlugins: mdxConfig.mdastPlugins } : {}),
+      ...(mdxConfig.hastPlugins ? { hastPlugins: mdxConfig.hastPlugins } : {}),
+      ...(mdxConfig.features ? { features: mdxConfig.features } : {}),
+    });
   }
 
   return {
@@ -208,6 +236,13 @@ export function timberMdx(ctx: PluginContext): Plugin {
 
     async transform(code, id) {
       if (!innerPlugin) return null;
+      // Ids with a Vite query (?raw, ?url, ?import) are asset requests, not
+      // modules to compile. vite-plugin-satteri's id regexes match them, but
+      // by the time this transform runs the code is already the asset module
+      // (e.g. `export default "<file text>"` for ?raw) — compiling that as
+      // markdown corrupts it. @mdx-js/rollup matched by extname and skipped
+      // queried ids; preserve that behavior.
+      if (id.includes('?')) return null;
       const envName = (this as unknown as { environment?: { name?: string } }).environment?.name;
       if (envName && envName !== 'rsc') return null;
       if (typeof innerPlugin.transform === 'function') {

package/src/plugins/prebuilt-capture.ts

@@ -30,9 +30,9 @@ import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
-import type { PluginContext } from '../plugin-context.js';
-import type { CaptureOptions, CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.js';
-import type { PrebuiltManifest } from '../server/prebuilt/payload-source.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { CaptureOptions, CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.ts';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.ts';
 
 // ─── Artifact writer ──────────────────────────────────────────────────────
 

package/src/plugins/prebuilt-options-analysis.ts

@@ -12,7 +12,7 @@
  * would silently skip prerendering.
  */
 
-import type { CallExpressionNode, PositionedNode } from './callsite-ast.js';
+import type { CallExpressionNode, PositionedNode } from './callsite-ast.ts';
 
 const EXPRESSION_WRAPPER_TYPES = new Set([
   'TSAsExpression',

package/src/plugins/prebuilt.ts

@@ -61,16 +61,16 @@ import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import MagicString from 'magic-string';
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
-import type { SegmentNode } from '../routing/types.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode } from '../routing/types.ts';
 import {
   CACHE_MODULE_SOURCES,
   findImportBindings,
   generateStableCallsiteId,
-} from './callsite-ast.js';
-import { collectJsxUsages, recordCallSiteProps } from './callsite-jsx.js';
-import { mayPrerender, unwrapExpression } from './prebuilt-options-analysis.js';
-import { cleanPrebuiltDir, runPrebuiltCapture } from './prebuilt-capture.js';
+} from './callsite-ast.ts';
+import { collectJsxUsages, recordCallSiteProps } from './callsite-jsx.ts';
+import { mayPrerender, unwrapExpression } from './prebuilt-options-analysis.ts';
+import { cleanPrebuiltDir, runPrebuiltCapture } from './prebuilt-capture.ts';
 import type {
   CallExpressionNode,
   IdentifierNode,
@@ -78,7 +78,7 @@ import type {
   MemberExpressionNode,
   PositionedNode,
   ProgramNode,
-} from './callsite-ast.js';
+} from './callsite-ast.ts';
 
 /**
  * Is this callee `cache.component` (named import, aliases included) or

package/src/plugins/prerender-sugar.ts

@@ -11,11 +11,10 @@
  * `export const prerender` to descendant pages via most-specific-wins:
  * walk the segment tree from leaf to root, first explicit value wins.
  *
- * A layout that declares `export const prerender` is ALSO wrapped — the
- * layout's flight payload is its own static shell (`children` is a
- * separate component boundary), so caching it is natural (nav, sidebar,
- * footer benefit from build-time rendering). See design/45 §Layout
- * Propagation.
+ * Layout declarations are propagation policy only. Layouts receive the real
+ * descendant React element as `children` to preserve the server-layout
+ * containment boundary, so their props are not cache-keyable and the layout
+ * itself must not be registered for capture.
  *
  * This transform runs BEFORE timber-prebuilt so the generated
  * `cache.component(...)` call is picked up by the callsite rewrite.
@@ -23,9 +22,9 @@
 
 import MagicString from 'magic-string';
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
-import type { SegmentNode, RouteFile } from '../routing/types.js';
-import { getPrerenderExport, type PrerenderExportValue } from '../routing/export-detect.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode, RouteFile } from '../routing/types.ts';
+import { getPrerenderExport, type PrerenderExportValue } from '../routing/export-detect.ts';
 
 interface AstNode {
   type: string;
@@ -39,16 +38,14 @@ interface AstNode {
 
 /**
  * Walk the segment tree and resolve the effective prerender value for
- * every page and layout. Returns a map from file path to resolved value.
+ * every page. Returns a map from page file path to resolved value.
  *
  * **Pages:** walk from leaf toward root; first explicit `export const prerender`
  * wins (page > nearest layout > ... > root layout). If none, dynamic.
  *
- * **Layouts:** a layout that declares `export const prerender` is wrapped
- * directly (its own shell is a separate component boundary from `children`).
- * Layouts without their own declaration are NOT wrapped — they don't
- * inherit from ancestors, because wrapping a layout's shell without the
- * author's explicit opt-in would cache content they may expect to be dynamic.
+ * **Layouts:** declarations propagate to descendant pages but layouts are not
+ * included in the result. Their real React-element `children` preserve secure
+ * containment and deliberately make child-independent layout caching invalid.
  */
 export function resolvePagePrerender(root: SegmentNode): Map<string, PrerenderExportValue> {
   const result = new Map<string, PrerenderExportValue>();
@@ -60,11 +57,6 @@ export function resolvePagePrerender(root: SegmentNode): Map<string, PrerenderEx
     const layoutValue = node.layout ? getPrerenderExport(node.layout.filePath) : undefined;
     const stack = layoutValue !== undefined ? [layoutValue, ...ancestorStack] : ancestorStack;
 
-    // Wrap the layout itself if it declares prerender (truthy)
-    if (node.layout && layoutValue !== undefined && layoutValue !== false) {
-      result.set(node.layout.filePath, layoutValue);
-    }
-
     if (node.page) {
       const pageValue = getPrerenderExport(node.page.filePath);
       // Page's own value takes priority; otherwise use nearest ancestor

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).
@@ -43,7 +50,8 @@ const BUILD_ONLY_EXTERNALS: string[] = [
   'vite',
   'nitro',
   'rollup',
-  '@mdx-js/rollup',
+  'vite-plugin-satteri',
+  'satteri',
   'fsevents',
   'chokidar',
 ];
@@ -79,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.