@timber-js/app 0.2.0-alpha.121 → 0.2.0-alpha.123

package/src/client/router.ts

@@ -215,6 +215,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentElementCache = new SegmentElementCache();
 
   let routerPhase: RouterPhase = { phase: 'idle' };
+  let navigationId = 0;
   const pendingListeners = new Set<(pending: boolean) => void>();
 
   // AbortController for the current in-flight navigation.
@@ -287,24 +288,46 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /**
    * Merge a partial RSC payload with cached segment elements if segments
-   * were skipped, then cache segments from the (merged) payload.
-   * Returns the merged payload ready for rendering.
+   * were skipped. Returns the merged payload ready for rendering.
+   *
+   * Segment element caching is deferred to after paint by the caller
+   * so it doesn't block the render path.
    */
-  function mergeAndCachePayload(
+  async function mergePayload(
     payload: unknown,
     skippedSegments: string[] | null | undefined
-  ): unknown {
-    let merged = payload;
-
-    // If segments were skipped, merge the partial payload with cached segments
+  ): Promise<unknown> {
     if (skippedSegments && skippedSegments.length > 0) {
-      merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+      // Segment merging needs a resolved React element tree for cloneElement.
+      // Await the payload only when merging is actually needed.
+      const resolved =
+        payload != null && typeof payload === 'object' && 'then' in payload
+          ? await (payload as PromiseLike<unknown>)
+          : payload;
+      return mergeSegmentTree(resolved, skippedSegments, segmentElementCache);
     }
+    // No merging needed — return the payload as-is (may be an unresolved
+    // Flight thenable). React handles progressive rendering via Suspense.
+    return payload;
+  }
 
-    // Cache segment elements from the (merged) payload for future merges
-    cacheSegmentElements(merged, segmentElementCache);
-
-    return merged;
+  /**
+   * Schedule segment element caching after paint. Resolves thenable
+   * payloads first since tree walking requires resolved React elements.
+   * Guards against stale writes: if a newer navigation started before
+   * this callback fires, the cache write is skipped.
+   */
+  function deferSegmentCaching(payload: unknown): void {
+    const capturedNavId = navigationId;
+    afterPaint(async () => {
+      if (capturedNavId !== navigationId) return;
+      const resolved =
+        payload != null && typeof payload === 'object' && 'then' in payload
+          ? await (payload as PromiseLike<unknown>)
+          : payload;
+      if (capturedNavId !== navigationId) return;
+      cacheSegmentElements(resolved, segmentElementCache);
+    });
   }
 
   /**
@@ -335,17 +358,27 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * FetchResult plus the NavigationState (so it can be passed explicitly
    * to wrapPayload/renderRoot without temporal coupling).
    */
+  interface TransitionResult {
+    headElements: HeadElement[] | null;
+    decodePromise: Promise<void> | null;
+  }
+
   async function renderViaTransition(
     url: string,
     perform: () => Promise<FetchResult & { navState: NavigationState }>
-  ): Promise<HeadElement[] | null> {
+  ): Promise<TransitionResult> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
+      let decodePromise: Promise<void> | null = null;
       await deps.navigateTransition(url, async (wrapPayload) => {
         const result = await perform();
         headElements = result.headElements;
-        // Merge partial payload with cached segments before wrapping
-        const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+        decodePromise = result.decodePromise;
+        // Merge partial payload with cached segments before wrapping.
+        // When no segments were skipped, mergePayload returns the payload
+        // as-is (possibly still an unresolved Flight thenable — React
+        // handles progressive rendering via Suspense).
+        const merged = await mergePayload(result.payload, result.skippedSegments);
         // Store the MERGED payload in history — not the partial pre-merge tree.
         // This ensures handlePopState replays the complete tree on back/forward.
         historyStack.push(url, {
@@ -353,24 +386,28 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: result.headElements,
           params: result.params,
         });
+        // Defer segment element caching to after paint — it only benefits
+        // future navigations and doesn't need to block the current render.
+        deferSegmentCaching(merged);
         // Pass navState explicitly — wrapPayload wraps element in
         // NavigationProvider with this state, no getNavigationState() needed.
         return wrapPayload(merged, result.navState);
       });
-      return headElements;
+      return { headElements, decodePromise };
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
     // Merge partial payload with cached segments before rendering
-    const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+    const merged = await mergePayload(result.payload, result.skippedSegments);
     // Store merged payload in history
     historyStack.push(url, {
       payload: merged,
       headElements: result.headElements,
       params: result.params,
     });
+    deferSegmentCaching(merged);
     renderPayload(merged, result.navState);
-    return result.headElements;
+    return { headElements: result.headElements, decodePromise: result.decodePromise };
   }
 
   /** Apply head elements (title, meta tags) to the DOM if available. */
@@ -414,6 +451,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     let result: FetchResult | undefined = prefetched
       ? {
           payload: prefetched.payload,
+          decodePromise: null,
           headElements: prefetched.headElements,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
@@ -466,6 +504,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const externalSignal = options._signal as AbortSignal | undefined;
     const skipHistory = options._skipHistory === true;
 
+    navigationId++;
+
     // Create an abort controller for this navigation. Links to the external
     // signal (Navigation API's event.signal) when provided.
     const navAbort = createNavAbort(externalSignal);
@@ -499,7 +539,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, url);
 
     try {
-      const headElements = await renderViaTransition(url, () =>
+      const { headElements, decodePromise } = await renderViaTransition(url, () =>
         performNavigationFetch(url, {
           replace,
           signal: navAbort.signal,
@@ -507,6 +547,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         })
       );
 
+      // Await async RSC decode errors (truncated streams, Flight parse failures)
+      // so they surface through this try/catch rather than becoming unhandled.
+      if (decodePromise) await decodePromise;
+
       // Update document.title and <meta> tags with the new page's metadata
       applyHead(headElements);
 
@@ -575,12 +619,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
+    navigationId++;
     const navAbort = createNavAbort();
 
     setPending(true, currentUrl);
 
     try {
-      const headElements = await renderViaTransition(currentUrl, async () => {
+      const { headElements, decodePromise } = await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(
           currentUrl,
@@ -595,6 +640,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         return { ...result, navState };
       });
 
+      if (decodePromise) await decodePromise;
       applyHead(headElements);
     } catch (error) {
       // Stale transition (superseded by a newer navigation) or aborted
@@ -615,6 +661,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     scrollY: number = 0,
     externalSignal?: AbortSignal
   ): Promise<void> {
+    navigationId++;
     // Scroll position is read from history.state by the caller (browser-entry.ts)
     // and passed in. This is more reliable than tracking scroll per-URL in memory
     // because the browser maintains per-entry state even with duplicate URLs.
@@ -634,7 +681,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const navAbort = createNavAbort(externalSignal);
       setPending(true, url);
       try {
-        const headElements = await renderViaTransition(url, async () => {
+        const { headElements, decodePromise } = await renderViaTransition(url, async () => {
           const stateTree = segmentCache.serializeStateTree(
             segmentElementCache.getMergeablePaths()
           );
@@ -645,6 +692,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           return { ...result, navState };
         });
 
+        if (decodePromise) await decodePromise;
         applyHead(headElements);
         restoreScrollAfterPaint(scrollY);
       } catch (error) {
@@ -697,18 +745,19 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload and applies
       // head elements — same as refresh() but without a server fetch.
-      // Cache segment elements for future partial merges.
+      // Revalidation payloads are already resolved (no Flight thenable),
+      // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
-      const merged = mergeAndCachePayload(element, null);
       historyStack.push(currentUrl, {
-        payload: merged,
+        payload: element,
         headElements,
       });
+      deferSegmentCaching(element);
       // Revalidation doesn't change params/pathname — preserve current state.
       // DO NOT call updateNavigationState(null, ...) here: that normalizes
       // params to {}, clearing dynamic route params on every action response.
       const navState = getNavigationState();
-      renderPayload(merged, navState);
+      renderPayload(element, navState);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),

package/src/client/rsc-fetch.ts

@@ -20,6 +20,14 @@ import type { RouterDeps } from './router';
 /** Result of fetching an RSC payload — includes head elements and segment metadata. */
 export interface FetchResult {
   payload: unknown;
+  /**
+   * Promise that settles when the RSC decode completes or fails.
+   * The payload thenable is NOT awaited before returning (for streaming),
+   * so callers must monitor this to catch async decode errors
+   * (truncated streams, Flight parse failures) that would otherwise
+   * become unhandled rejections.
+   */
+  decodePromise: Promise<void> | null;
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
@@ -313,11 +321,17 @@ export async function fetchRscPayload(
     });
     // Await headers so headElements/segmentInfo/params are populated.
     await wrappedPromise;
-    // Await the decoded payload — createFromFetch returns a thenable
-    // that resolves to the React element tree once the Flight stream
-    // has enough data to produce the shell.
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params, skippedSegments };
+    // Start decoding but do NOT await — return the in-progress thenable.
+    // React can render a Flight thenable directly: it suspends on unresolved
+    // parts and progressively renders as chunks arrive, spreading work across
+    // frames instead of blocking the main thread in one burst.
+    const payload = deps.decodeRsc(wrappedPromise);
+    // Track decode completion so callers can catch async errors (truncated
+    // streams, Flight parse failures) that fire after fetchRscPayload returns.
+    const decodePromise = Promise.resolve(payload).then(() => undefined);
+    // Prevent unhandled rejection — the router monitors decodePromise separately.
+    decodePromise.catch(() => {});
+    return { payload, decodePromise, headElements, segmentInfo, params, skippedSegments };
   }
   // Test/fallback path: return raw text
   const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
@@ -330,6 +344,7 @@ export async function fetchRscPayload(
   }
   return {
     payload: await response.text(),
+    decodePromise: null,
     headElements: extractHeadElements(response),
     segmentInfo: extractSegmentInfo(response),
     params: extractParams(response),

package/src/client/shallow-url.ts

@@ -0,0 +1,22 @@
+/**
+ * Shallow URL replacement — update the browser URL bar without triggering
+ * RSC navigation, TopLoader, or any server round-trip.
+ *
+ * Uses the Navigation API's `info: { shallow: true }` when available (Chrome),
+ * which the navigate event handler intercepts with a no-op handler. Falls back
+ * to raw `history.replaceState` (Safari/Firefox — no navigate event fired).
+ */
+
+import { getNavigationApi } from './navigation-api.js';
+
+export function replaceUrl(url: string): void {
+  const nav = getNavigationApi();
+  if (nav) {
+    nav.navigate(url, {
+      history: 'replace',
+      info: { shallow: true },
+    });
+  } else {
+    history.replaceState(history.state, '', url);
+  }
+}

package/src/index.ts

@@ -29,6 +29,7 @@ import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
 import { clientChunkGroup } from './plugins/client-chunks';
 import { timberServerBundle } from './plugins/server-bundle';
+import { timberCloudflareWasm } from './plugins/cloudflare-wasm';
 import { timberAdapterBuild } from './plugins/adapter-build';
 import { timberBuildReport } from './plugins/build-report';
 import { createNoopTimer } from './utils/startup-timer';
@@ -531,6 +532,7 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     timberMdx(ctx),
     timberContent(ctx),
     timberServerBundle(), // Bundle all deps in server environments for prod
+    timberCloudflareWasm(ctx), // Externalize WASM for Cloudflare Workers
     timberChunks(),
     timberBuildReport(ctx), // Post-build: route table with bundle sizes
     timberAdapterBuild(ctx), // Post-build: invoke adapter.buildOutput()

package/src/params/resolve-schema.ts

@@ -70,6 +70,10 @@ function isCatchAllKey(key: string): boolean {
   return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);
 }
 
+function isOptionalCatchAllKey(key: string): boolean {
+  return OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
 /**
  * Resolve the global schema's segmentParams into a map of bracket-keyed
  * param name → resolved Codec.
@@ -94,6 +98,17 @@ export function resolveSchemaCodecs(
           `(e.g. codec.catchAll(codec.string)). Got a scalar codec.`
       );
     }
+    if (
+      isOptionalCatchAllKey(bracketName) &&
+      isCodec(value) &&
+      '__catchAll' in value &&
+      !('__optional' in value)
+    ) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() ` +
+          `(e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`
+      );
+    }
     resolved[bracketName] = resolveCodec(bracketName, value);
   }
 

package/src/plugins/build-manifest.ts

@@ -16,10 +16,13 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
-import { randomUUID } from 'node:crypto';
+import { randomUUID, createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import type { Plugin, ResolvedConfig } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import type { BuildManifest } from '../server/build-manifest.js';
+import type { SegmentNode, RouteFile } from '../routing/types.js';
+import { isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.
 // We define minimal interfaces here to avoid a direct 'rollup' dependency.
@@ -84,7 +87,7 @@ export function parseViteManifest(
     modulepreload[inputPath] = collectTransitiveDeps(inputPath, viteManifest, base);
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -197,7 +200,7 @@ export function buildManifestFromBundle(
     css['_global'] = allCss;
   }
 
-  return { css, js, modulepreload, fonts: {} };
+  return { css, js, modulepreload, fonts: {}, metadataRouteHashes: {} };
 }
 
 /**
@@ -228,6 +231,50 @@ function collectTransitiveBundleDeps(
   return result;
 }
 
+/**
+ * Walk the route tree and compute short content hashes for metadata route files
+ * (opengraph-image, icon, apple-icon) used for cache-busting
+ * the auto-linked URLs in <head>.
+ */
+function computeMetadataRouteHashes(node: SegmentNode<RouteFile>): Record<string, string> {
+  const hashes: Record<string, string> = {};
+
+  if (node.metadataRoutes) {
+    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
+      if (!isDynamicMetadataExtension(baseName, file.extension)) {
+        // For static files, hash the file content
+        try {
+          const content = readFileSync(file.filePath);
+          const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
+          hashes[file.filePath] = hash;
+        } catch {
+          // File unreadable — skip hash, DEV_NONCE fallback applies
+        }
+      } else {
+        // For dynamic files (.ts/.tsx), hash the source file as a reasonable
+        // approximation — the output depends on runtime data too, but the
+        // source change is the best build-time signal we have.
+        try {
+          const content = readFileSync(file.filePath);
+          const hash = createHash('sha256').update(content).digest('hex').slice(0, 8);
+          hashes[file.filePath] = hash;
+        } catch {
+          // File unreadable — skip
+        }
+      }
+    }
+  }
+
+  for (const child of node.children) {
+    Object.assign(hashes, computeMetadataRouteHashes(child));
+  }
+  for (const slot of Object.values(node.slots)) {
+    Object.assign(hashes, computeMetadataRouteHashes(slot));
+  }
+
+  return hashes;
+}
+
 /**
  * Create the timber-build-manifest Vite plugin.
  *
@@ -278,7 +325,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
           '// Auto-generated build manifest — do not edit.',
           '// Dev mode: empty manifest (Vite HMR handles CSS/JS).',
           '',
-          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
           '',
           'export default manifest;',
         ].join('\n');
@@ -292,7 +339,7 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
         '// Auto-generated build manifest — do not edit.',
         '// Production: reads manifest from globalThis (set by _timber-manifest-init.js).',
         '',
-        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {}, metadataRouteHashes: {} };',
         '',
         'export default manifest;',
       ].join('\n');
@@ -309,6 +356,11 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
       if (envName === 'client') {
         ctx.buildManifest = buildManifestFromBundle(bundle, resolvedBase, ctx.root);
 
+        // Compute cache-busting hashes for metadata route files
+        if (ctx.routeTree) {
+          ctx.buildManifest.metadataRouteHashes = computeMetadataRouteHashes(ctx.routeTree.root);
+        }
+
         // When client JavaScript is disabled, strip JS chunks from the bundle
         // so Rollup never writes them to disk. CSS assets are preserved —
         // they're still needed for server-rendered HTML.

package/src/plugins/cloudflare-wasm.ts

@@ -0,0 +1,103 @@
+/**
+ * timber-cloudflare-wasm — Handle WASM modules for Cloudflare Workers builds.
+ *
+ * Cloudflare Workers can natively import `.wasm` files as compiled
+ * WebAssembly.Module. But Rolldown can't load `.wasm` files at build time.
+ *
+ * This plugin bridges the gap:
+ * 1. Adds the `workerd` resolve condition so libraries like @takumi-rs/wasm
+ *    resolve to their Cloudflare-native entry (bare `.wasm` import)
+ * 2. Externalizes `.wasm` imports so Rolldown skips them
+ * 3. Copies the WASM files to the build output so wrangler can find them
+ *
+ * Only active for Cloudflare adapter production builds.
+ */
+
+import { basename, resolve, dirname } from 'node:path';
+import { copyFile, mkdir } from 'node:fs/promises';
+import type { Plugin, ResolvedConfig } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+
+function isCloudflareAdapter(ctx: PluginContext): boolean {
+  const adapter = ctx.config.adapter as { name?: string } | undefined;
+  return adapter?.name === 'cloudflare';
+}
+
+export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
+  // Track resolved WASM file paths so we can copy them to the output
+  const wasmFiles = new Map<string, string>();
+
+  const plugin: Plugin = {
+    name: 'timber-cloudflare-wasm',
+
+    configResolved(resolved: ResolvedConfig) {
+      if (resolved.command !== 'build') return;
+      if (!isCloudflareAdapter(ctx)) return;
+
+      // Prepend `workerd` to resolve conditions for server environments
+      // so @takumi-rs/wasm/auto resolves to the Cloudflare-native entry
+      // (bare WASM import) instead of the Vite entry (?url + fetch).
+      // Must happen in configResolved because the RSC plugin sets its own
+      // conditions during config — merging via config() would lose them.
+      for (const envName of ['rsc', 'ssr']) {
+        const env = resolved.environments[envName];
+        if (!env) continue;
+        const conditions = env.resolve.conditions;
+        if (!conditions.includes('workerd')) {
+          conditions.unshift('workerd');
+        }
+      }
+    },
+
+    resolveId: {
+      order: 'pre',
+      async handler(source, importer) {
+        if (!source.endsWith('.wasm')) return;
+
+        let absolutePath: string;
+        if (source.startsWith('.') && importer) {
+          absolutePath = resolve(dirname(importer), source);
+        } else {
+          return;
+        }
+
+        const filename = basename(absolutePath);
+        wasmFiles.set(filename, absolutePath);
+
+        return { id: './' + filename, external: true };
+      },
+    },
+
+    async writeBundle(options, bundle) {
+      if (wasmFiles.size === 0) return;
+
+      const outDir = options.dir;
+      if (!outDir) return;
+
+      // Find which output chunks reference WASM files and copy the WASM
+      // to the same directory so the relative imports resolve correctly.
+      const targetDirs = new Set<string>();
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== 'chunk') continue;
+        for (const filename of wasmFiles.keys()) {
+          if (chunk.code.includes(filename)) {
+            targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
+          }
+        }
+      }
+
+      if (targetDirs.size === 0) return;
+
+      const copies: Promise<void>[] = [];
+      for (const dir of targetDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [filename, absolutePath] of wasmFiles) {
+          copies.push(copyFile(absolutePath, resolve(dir, filename)));
+        }
+      }
+      await Promise.all(copies);
+    },
+  };
+
+  return [plugin];
+}

package/src/plugins/dev-server.ts

@@ -31,6 +31,7 @@ import {
 } from '../dev-tools/error-page.js';
 import { addVirtualModuleContext } from '../config-validation.js';
 import { compressResponse } from '../server/compress.js';
+import { isMetadataRouteServePath } from '../server/metadata-routes.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -165,8 +166,9 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       return;
     }
 
-    // Pass through static asset requests
-    if (isAssetRequest(url)) {
+    // Pass through static asset requests — but not metadata routes like
+    // /favicon.ico that match asset extensions but are handled by timber.
+    if (isAssetRequest(url) && !isMetadataRouteServePath(url)) {
       next();
       return;
     }

package/src/plugins/routing.ts

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

package/src/routing/codegen-shared.ts

@@ -82,13 +82,16 @@ export function buildCodecChainType(
 
 /**
  * Build a TypeScript type expression for a single param using the global
- * schema's InferCodecType. Falls back to `fallback` when schema doesn't
- * declare this param.
+ * schema's InferCodecType. Falls back to the param's base type when
+ * schema doesn't declare this param (schemas are opt-in per key).
  *
- * Generates: `InferCodecType<typeof schema.segmentParams['[paramName]']>`
+ * Generates a conditional that checks key existence:
+ * `[bracketName] extends keyof typeof schema.segmentParams ? InferCodecType<...> : fallback`
  */
-export function buildSchemaParamType(p: ParamEntry): string {
-  return `InferCodecType<typeof schema.segmentParams[${JSON.stringify(p.bracketName)}]>`;
+export function buildSchemaParamType(p: ParamEntry, fallback?: string): string {
+  const key = JSON.stringify(p.bracketName);
+  const fb = fallback ?? p.type;
+  return `${key} extends keyof typeof schema['segmentParams'] ? InferCodecType<typeof schema.segmentParams[${key}]> : ${fb}`;
 }
 
 /**

package/src/routing/codegen.ts

@@ -350,6 +350,11 @@ function formatDeclarationFile(
       "  [K in keyof typeof schema['segmentParams']]: typeof schema['segmentParams'][K] extends SegmentParamCodec ? true : ['Error: value for', K, 'is not a valid Codec or Standard Schema'];"
     );
     lines.push('};');
+    // Generic constraint enforces that all values are `true` — if any value is
+    // an error tuple, TS reports a real diagnostic instead of silently computing it.
+    lines.push(
+      'type _EnforceSchemaValues<_T extends Record<string, true> = _AssertSchemaValues> = true;'
+    );
     lines.push('');
   }
 

package/src/routing/link-codegen.ts

@@ -83,7 +83,7 @@ export function formatLinkParamsType(
   const fields = params.map((p) => {
     const fallback = p.type === 'string' ? 'string | number' : p.type;
     const codecType = hasSchema
-      ? buildSchemaParamType(p)
+      ? buildSchemaParamType(p, fallback)
       : buildCodecChainType(p, importBase, fallback);
     return `${p.name}: ${codecType}`;
   });