@timber-js/app 0.2.0-alpha.209 → 0.2.0-alpha.210

package/src/client/router.ts

@@ -22,7 +22,14 @@ import { createScrollEffects, createSpaExits, createNavigationRecovery } from '.
 import { createNavigationLifecycle } from './router-lifecycle.ts';
 import { createNavigationPipeline, prefetchKeyFor } from './router-pipeline.ts';
 import { recordSkew } from './router-skew.ts';
-import type { NavigationOptions, RouterDeps, RouterInstance } from './router-types.ts';
+import type {
+  NavigationOptions,
+  NavigationTransitionType,
+  RefreshOptions,
+  RouterDeps,
+  RouterInstance,
+  TraverseDirection,
+} from './router-types.ts';
 import { createRenderOwner, type CommitOutcome } from './navigation-transition.ts';
 
 // ─── Router Factory ──────────────────────────────────────────────
@@ -95,7 +102,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     currentOwner,
     leaveSpaIfOwned,
     // Hoisted — `navigate` is a function declaration below.
-    navigate: (url) => navigate(url, { replace: true }),
+    navigate: (url, types) => navigate(url, { replace: true, _renderTypes: types }),
   });
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -103,6 +110,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const replace = options.replace === true;
     const externalSignal = options._signal as AbortSignal | undefined;
     const skipHistory = options._skipHistory === true;
+    // A push, a replace, and a server action redirect all move the user
+    // forward; the caller's own types ride beside it. A redirect this router
+    // follows keeps the types of the render it interrupted instead.
+    const types = options._renderTypes ?? [
+      'navigation-forward' satisfies NavigationTransitionType,
+      ...(options.transitionTypes ?? []),
+    ];
 
     // Split the #fragment off the navigation URL (TIM-1035). The full URL
     // (with hash) is committed to the address bar; the hash-less URL is used
@@ -161,6 +175,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           await renderViaTransition(
             fetchUrl,
             owner,
+            types,
             () =>
               performNavigationFetch(fetchUrl, {
                 replace,
@@ -185,7 +200,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // load of the destination, fragment included (TIM-1234). Reloading
           // instead would rebuild the page they were *leaving* and discard
           // the click (TIM-1275).
-          if (await recoverFromNavigationError(error, owner, url, departingUrl)) return;
+          if (await recoverFromNavigationError(error, owner, url, departingUrl, types)) return;
           throw error;
         }
       },
@@ -204,6 +219,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    */
   async function fetchCommitAndRender(
     url: string,
+    /** The view transition type the render adds. */
+    type: NavigationTransitionType,
     opts: {
       /** Omitted by refresh(): the server renders the complete payload. */
       stateTree?: { segments: string[] };
@@ -221,6 +238,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           await renderViaTransition(
             url,
             owner,
+            [type],
             async () => {
               const result = await fetchRscPayload(
                 url,
@@ -252,7 +270,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // browser has already traversed, and `refresh()` is by definition
           // where it already is. So `hardNavigate()` takes its same-document
           // branch and reloads rather than pushing an entry.
-          if (await recoverFromNavigationError(error, owner, url, url)) return;
+          if (await recoverFromNavigationError(error, owner, url, url, [type])) return;
           throw error;
         }
 
@@ -262,7 +280,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     );
   }
 
-  async function refresh(options?: { onCommit?: (outcome: CommitOutcome) => void }): Promise<void> {
+  async function refresh(options: RefreshOptions = {}): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
 
     // A refresh on a stale client is a full document load of the current URL.
@@ -273,13 +291,16 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await leaveSpaSuperseding(currentUrl, currentUrl);
     }
 
-    await fetchCommitAndRender(currentUrl, { onCommit: options?.onCommit });
+    await fetchCommitAndRender(currentUrl, options.transitionType ?? 'refresh', {
+      onCommit: options.onCommit,
+    });
   }
 
   async function handlePopState(
     url: string,
     scrollY: number = 0,
-    externalSignal?: AbortSignal
+    externalSignal?: AbortSignal,
+    direction: TraverseDirection = 'navigation-traverse'
   ): Promise<void> {
     // A stale client hard-navigates on back/forward too — this path never
     // reaches navigate(), so it needs the same check. `url` is where the
@@ -326,7 +347,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           // that misses one of them (TIM-1478). The perform resolves
           // immediately: there is no fetch, and the cached payload is
           // already decoded.
-          await renderViaTransition(url, owner, async () => {
+          await renderViaTransition(url, owner, [direction], async () => {
             const { navState, commit } = prepareNavigation(url, {
               payload: entry.payload,
               params: entry.params,
@@ -352,7 +373,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // This happens when navigating back to the initial SSR'd page
       // (its payload is null since it was rendered via SSR, not RSC fetch)
       // or when the entry doesn't exist at all.
-      await fetchCommitAndRender(url, {
+      await fetchCommitAndRender(url, direction, {
         stateTree: currentStateTree(),
         scrollY,
         externalSignal,
@@ -447,7 +468,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         let outcomeResolve!: (o: CommitOutcome) => void;
         const outcomePromise = new Promise<CommitOutcome>((r) => (outcomeResolve = r));
         const [, outcome] = await Promise.all([
-          refresh({ onCommit: outcomeResolve }).catch(() => {}),
+          refresh({ transitionType: 'revalidate', onCommit: outcomeResolve }).catch(() => {}),
           outcomePromise,
         ]);
         return outcome === 'committed';
@@ -478,6 +499,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         renderViaTransition(
           currentUrl,
           owner,
+          ['revalidate' satisfies NavigationTransitionType],
           async () => {
             const { navState, commit } = prepareNavigation(currentUrl, {
               payload: payloadTree,
@@ -502,20 +524,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     },
     runWhenIdle: (task: () => void) => lifecycle.runWhenIdle(task),
     settleHandoffs: () => lifecycle.settleHandoffs(),
-    invalidatePath(path: string): void {
-      const hasSearch = path.includes('?');
-      if (hasSearch) {
-        historyStack.delete(path);
-      } else {
-        // TIM-1465: evict all query variants sharing this pathname
-        historyStack.deleteByPathname(path);
-      }
-      prefetchCache.invalidateUrl(path);
-      // TIM-1466: suppress segment/slot reuse so the next navigation
-      // gets a full render instead of reusing stale shared layouts.
-      // Uses invalidateReuse() instead of clear() to preserve treePaths
-      // for interception scoping — a modal mounted on the current tree
-      // must still be navigable (codex on #1167).
+    suppressSegmentReuse(): void {
+      // TIM-1466: uses invalidateReuse() instead of clear() to preserve
+      // treePaths for interception scoping — a modal mounted on the current
+      // tree must still be navigable (codex on #1167).
       segmentCache.invalidateReuse();
     },
     evictStaleCaches(): void {

package/src/client/segment-cache.ts

@@ -364,27 +364,6 @@ function prefetchMapKey(key: PrefetchKey): string {
   return `${key.from.length}:${key.from}:${key.scope.length}:${key.scope}:${key.url}`;
 }
 
-/**
- * Extract the destination URL from a length-prefixed map key.
- * Key format: `${from.length}:${from}:${scope.length}:${scope}:${url}`
- */
-function extractUrlFromMapKey(mapKey: string): string | null {
-  // Parse from-length prefix
-  const firstColon = mapKey.indexOf(':');
-  if (firstColon === -1) return null;
-  const fromLen = parseInt(mapKey.slice(0, firstColon), 10);
-  if (Number.isNaN(fromLen)) return null;
-  // Skip past `from.length:from:`
-  const scopeStart = firstColon + 1 + fromLen + 1;
-  // Parse scope-length prefix
-  const secondColon = mapKey.indexOf(':', scopeStart);
-  if (secondColon === -1) return null;
-  const scopeLen = parseInt(mapKey.slice(scopeStart, secondColon), 10);
-  if (Number.isNaN(scopeLen)) return null;
-  // Skip past `scope.length:scope:` — remainder is the URL
-  return mapKey.slice(secondColon + 1 + scopeLen + 1);
-}
-
 /**
  * The `scope` half of a `PrefetchKey`, derived from the state tree that will
  * actually be sent. Taking it from the header value rather than re-walking the
@@ -522,50 +501,6 @@ export class PrefetchCache {
     return this.get(key) === NEGATIVE_ENTRY;
   }
 
-  /**
-   * Invalidate entries whose destination URL matches (TIM-1454).
-   *
-   * When `url` has no search string, evicts all entries sharing that
-   * pathname — `/products` evicts `/products?page=1` too, because
-   * `revalidatePath('/products')` invalidates the route regardless of
-   * query (TIM-1465).
-   *
-   * When `url` has a search string, only the exact URL is evicted.
-   *
-   * Also bumps the eviction generation so in-flight singleflight
-   * flights for the invalidated URL(s) discard their results on
-   * completion (TIM-1464).
-   */
-  invalidateUrl(url: string): void {
-    const hasSearch = url.includes('?');
-    const pathname = hasSearch ? null : url;
-
-    for (const [mapKey] of this.entries) {
-      // The map key is `${from.length}:${from}:${scope.length}:${scope}:${url}`.
-      // The destination URL is the suffix after the last unescaped colon pair.
-      if (hasSearch) {
-        if (mapKey.endsWith(':' + url)) {
-          this.entries.delete(mapKey);
-        }
-      } else {
-        // Extract the URL suffix — everything after the scope block.
-        // Match any entry whose URL pathname matches.
-        const entryUrl = extractUrlFromMapKey(mapKey);
-        if (entryUrl !== null) {
-          const qIndex = entryUrl.indexOf('?');
-          const entryPathname = qIndex === -1 ? entryUrl : entryUrl.slice(0, qIndex);
-          if (entryPathname === pathname) {
-            this.entries.delete(mapKey);
-          }
-        }
-      }
-    }
-
-    // Fence in-flight flights so a prefetch that started before
-    // invalidation cannot store its stale result (TIM-1464).
-    this.evictionGen++;
-  }
-
   /**
    * Evict all ready entries and fence in-flight singleflights (TIM-1476).
    * Called after a server action that revalidated data — the mutation may

package/src/client/use-router.ts

@@ -26,11 +26,23 @@
 import { getRouterOrNull } from './router-ref.ts';
 import { validateNavigationHref } from '../shared/href-validation.ts';
 
+/** Options for `push` and `replace`. */
+export interface NavigateOptions {
+  /** Set to false to keep the scroll position instead of scrolling to top. */
+  scroll?: boolean;
+  /**
+   * View transition types to add to this navigation, beside the router's own
+   * `navigation-forward`. See `NavigationOptions.transitionTypes` — they must
+   * go here rather than in a `startTransition` around the call.
+   */
+  transitionTypes?: readonly string[];
+}
+
 export interface AppRouterInstance {
   /** Navigate to a URL, pushing a new history entry */
-  push(href: string, options?: { scroll?: boolean }): void;
+  push(href: string, options?: NavigateOptions): void;
   /** Navigate to a URL, replacing the current history entry */
-  replace(href: string, options?: { scroll?: boolean }): void;
+  replace(href: string, options?: NavigateOptions): void;
   /** Refresh the current page (re-fetch RSC payload) */
   refresh(): void;
   /** Navigate back in history */
@@ -60,7 +72,7 @@ export interface AppRouterInstance {
  */
 export function useRouter(): AppRouterInstance {
   return {
-    push(href: string, options?: { scroll?: boolean }) {
+    push(href: string, options?: NavigateOptions) {
       validateNavigationHref(href);
       const router = getRouterOrNull();
       if (!router) {
@@ -71,9 +83,12 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      void router.navigate(href, { scroll: options?.scroll });
+      void router.navigate(href, {
+        scroll: options?.scroll,
+        transitionTypes: options?.transitionTypes,
+      });
     },
-    replace(href: string, options?: { scroll?: boolean }) {
+    replace(href: string, options?: NavigateOptions) {
       validateNavigationHref(href);
       const router = getRouterOrNull();
       if (!router) {
@@ -82,7 +97,11 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      void router.navigate(href, { scroll: options?.scroll, replace: true });
+      void router.navigate(href, {
+        scroll: options?.scroll,
+        replace: true,
+        transitionTypes: options?.transitionTypes,
+      });
     },
     refresh() {
       const router = getRouterOrNull();

package/src/config-validation.ts

@@ -19,6 +19,12 @@ export interface ConfigError {
   message: string;
   value?: unknown;
   suggestion?: string;
+  /**
+   * Refuse to start rather than log. Most config errors only warn — Vite may
+   * still work partially — but a fatal one would leave a security check
+   * running on a value the developer did not mean (`allowedOrigins`).
+   */
+  fatal?: true;
 }
 
 // ─── Known config keys ──────────────────────────────────────────────────────
@@ -108,6 +114,24 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
     }
   }
 
+  // allowedOrigins
+  if (config.allowedOrigins !== undefined) {
+    if (!Array.isArray(config.allowedOrigins)) {
+      errors.push({
+        field: 'allowedOrigins',
+        message: 'allowedOrigins must be an array of origin strings.',
+        value: config.allowedOrigins,
+        fatal: true,
+        suggestion: 'Example: allowedOrigins: ["https://app.example.com"]',
+      });
+    } else {
+      for (const entry of config.allowedOrigins) {
+        const error = allowedOriginError(entry);
+        if (error) errors.push(error);
+      }
+    }
+  }
+
   // slowRequestMs
   if (config.slowRequestMs !== undefined) {
     if (typeof config.slowRequestMs !== 'number' || config.slowRequestMs < 0) {
@@ -230,6 +254,76 @@ export function validateConfig(config: TimberUserConfig): ConfigError[] {
   return errors;
 }
 
+/**
+ * Why one `allowedOrigins` entry can never match, or null when it can.
+ *
+ * The CSRF check compares entries to the request's `Origin` header by
+ * exact string, and browsers send only the canonical form — scheme, host,
+ * and non-default port, lowercased, no path. So an entry that is not its
+ * own `new URL(x).origin` (`https://example.com/`, `https://Example.com`,
+ * `example.com`) silently matches nothing. `"null"` is refused outright:
+ * it is the `Origin` of every opaque context at once.
+ */
+function allowedOriginError(entry: unknown): ConfigError | null {
+  const field = 'allowedOrigins';
+  const fatal = true;
+  if (typeof entry !== 'string') {
+    return {
+      field,
+      message: `allowedOrigins contains a non-string value: ${JSON.stringify(entry)}.`,
+      value: entry,
+      fatal,
+    };
+  }
+  if (entry === 'null') {
+    return {
+      field,
+      message:
+        'allowedOrigins cannot contain "null". Browsers send Origin: null from every opaque ' +
+        "context — sandboxed iframes (an attacker's <iframe sandbox> included), POSTs " +
+        'redirected across origins, and file: pages — so allowing it allows all of them.',
+      value: entry,
+      suggestion:
+        'To accept a cross-site POST on one endpoint, handle it in a route.ts that exports ' +
+        '`const csrf = false` instead.',
+      fatal,
+    };
+  }
+  // `new URL('https://*.example.com').origin` round-trips, so the canonical
+  // check alone would accept a wildcard that matches no real Origin.
+  if (entry.includes('*')) {
+    return {
+      field,
+      message: `allowedOrigins entry ${JSON.stringify(entry)} uses a wildcard. Matching is exact; wildcards are not supported.`,
+      value: entry,
+      suggestion:
+        'List each origin, e.g. ["https://app.example.com", "https://admin.example.com"].',
+      fatal,
+    };
+  }
+  const canonical = canonicalOrigin(entry) ?? canonicalOrigin(`https://${entry}`);
+  if (canonical === entry) return null;
+  return {
+    field,
+    message: `allowedOrigins entry ${JSON.stringify(entry)} is not a canonical origin, so it can never match a request's Origin header.`,
+    value: entry,
+    suggestion: canonical
+      ? `Did you mean "${canonical}"? An origin is scheme://host[:port] — lowercase, no path or trailing slash.`
+      : 'An origin is scheme://host[:port], e.g. "https://app.example.com".',
+    fatal,
+  };
+}
+
+/** `new URL(x).origin` for an http(s) URL, or null. Opaque origins are not origins here. */
+function canonicalOrigin(value: string): string | null {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:' ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
 // ─── Formatting ─────────────────────────────────────────────────────────────
 
 const RED = '\x1b[31m';
@@ -238,27 +332,49 @@ const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 
 /**
- * Format config errors for terminal output.
+ * Format config errors for terminal output. Pass `color: false` for text
+ * that goes into a thrown `Error` — escapes there reach CI logs and the
+ * Vite overlay as raw bytes.
  */
-export function formatConfigErrors(errors: ConfigError[]): string {
+export function formatConfigErrors(
+  errors: ConfigError[],
+  { color = true }: { color?: boolean } = {}
+): string {
   if (errors.length === 0) return '';
+  const [red, bold, dim, reset] = color ? [RED, BOLD, DIM, RESET] : ['', '', '', ''];
 
   const lines: string[] = [];
   lines.push(
-    `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} config error${errors.length !== 1 ? 's' : ''} in timber.config.ts:${RESET}`
+    `${red}${bold}[timber]${reset} ${red}${errors.length} config error${errors.length !== 1 ? 's' : ''} in timber.config.ts:${reset}`
   );
 
   for (const err of errors) {
     lines.push('');
-    lines.push(`  ${RED}✗${RESET} ${BOLD}${err.field}${RESET}: ${err.message}`);
+    lines.push(`  ${red}✗${reset} ${bold}${err.field}${reset}: ${err.message}`);
     if (err.suggestion) {
-      lines.push(`    ${DIM}${err.suggestion}${RESET}`);
+      lines.push(`    ${dim}${err.suggestion}${reset}`);
     }
   }
 
   return lines.join('\n');
 }
 
+/**
+ * Surface config errors at startup: non-fatal ones are written to stderr
+ * (Vite may still work partially, and the message guides the fix); fatal
+ * ones then stop startup with a thrown error. Non-fatal errors are written
+ * first so a fatal one does not hide them.
+ */
+export function reportConfigErrors(
+  errors: ConfigError[],
+  write: (text: string) => void = (text) => process.stderr.write(text)
+): void {
+  const warnings = errors.filter((e) => !e.fatal);
+  if (warnings.length > 0) write(`${formatConfigErrors(warnings)}\n\n`);
+  const fatal = errors.filter((e) => e.fatal);
+  if (fatal.length > 0) throw new Error(formatConfigErrors(fatal, { color: false }));
+}
+
 // ─── Virtual Module Name Mapping ────────────────────────────────────────────
 
 const VIRTUAL_MODULE_NAMES: Record<string, string> = {

package/src/index.ts

@@ -42,7 +42,7 @@ import { timberBuildReport } from './plugins/build-report.ts';
 import { createNoopTimer } from './utils/startup-timer.ts';
 import {
   validateConfig,
-  formatConfigErrors,
+  reportConfigErrors,
   checkPeerDependencies,
   formatMissingPeers,
 } from './config-validation.ts';
@@ -513,13 +513,10 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         ctx.timer.start('dev-server-setup');
       }
 
-      // Validate config and check peer dependencies at startup.
-      // Errors are logged to stderr but don't block startup — Vite may
-      // still work partially, and the errors guide the user to fix things.
-      const configErrors = validateConfig(ctx.config);
-      if (configErrors.length > 0) {
-        process.stderr.write(`${formatConfigErrors(configErrors)}\n\n`);
-      }
+      // Validate config and check peer dependencies at startup. Most errors
+      // are logged and don't block startup; fatal ones (a security setting
+      // that would not mean what it says) stop it. See reportConfigErrors.
+      reportConfigErrors(validateConfig(ctx.config));
 
       const peerResults = checkPeerDependencies(ctx.root);
       const peerWarning = formatMissingPeers(peerResults);

package/src/routing/convention-lint.ts

@@ -26,6 +26,7 @@ import {
   fileHasDefaultExport,
   fileHasDirective,
   fileHasStarExport,
+  getCsrfExport,
 } from './export-detect.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
@@ -82,6 +83,12 @@ export function lintConventions(tree: RouteTree, appDir: string): ConventionWarn
   // Check 8: middleware.ts inside a parallel slot subtree (silently dead)
   checkSlotMiddleware(tree.root, warnings);
 
+  // Check 9: `export const csrf` anywhere but route.ts, or in a form the
+  // scanner cannot read (TIM-1543)
+  checkCsrfExports(tree.root, warnings);
+  if (tree.proxy) checkCsrfExport(tree.proxy, 'proxy.ts', warnings);
+  if (tree.globalError) checkCsrfExport(tree.globalError, 'global-error', warnings);
+
   return warnings;
 }
 
@@ -116,6 +123,74 @@ function checkClientLayouts(node: SegmentNode, warnings: ConventionWarning[]): v
   for (const slot of Object.values(node.slots)) checkClientLayouts(slot, warnings);
 }
 
+// ─── Check: CSRF Exemption Export ──────────────────────────────────────────
+
+/** Single-file segment conventions other than route.ts. */
+const NON_ROUTE_FILE_KEYS = [
+  'page',
+  'layout',
+  'middleware',
+  'access',
+  'error',
+  'default',
+  'denied',
+] as const satisfies readonly (keyof SegmentNode)[];
+
+/**
+ * Fail the build on a `csrf` export the CSRF gate would not honor.
+ *
+ * Both findings are proven from source, and both are fatal in the sense
+ * the error level requires: the developer wrote an exemption that silently
+ * does nothing, so a legitimate cross-site POST they meant to accept gets
+ * a 403 in production, or they believe a page or action is exempt when
+ * the gate still protects it. The exemption exists only on route.ts —
+ * server actions always get the check (design/08 §"Per-route exemption").
+ * A `'use server'` module cannot export it at all: plugin-rsc rejects every
+ * non-async-function export there.
+ */
+function checkCsrfExports(node: SegmentNode, warnings: ConventionWarning[]): void {
+  if (node.route) checkCsrfExport(node.route, 'route.ts', warnings);
+  for (const key of NON_ROUTE_FILE_KEYS) {
+    const file = node[key];
+    if (file) checkCsrfExport(file, key, warnings);
+  }
+  // Status files and metadata routes (sitemap.ts, opengraph-image.tsx, …).
+  // JSON status files are skipped by the script-extension check.
+  for (const [name, file] of Object.entries(node.statusFiles ?? {})) {
+    checkCsrfExport(file, name, warnings);
+  }
+  for (const [name, file] of Object.entries(node.metadataRoutes ?? {})) {
+    checkCsrfExport(file, name, warnings);
+  }
+  for (const child of node.children) checkCsrfExports(child, warnings);
+  for (const slot of Object.values(node.slots)) checkCsrfExports(slot, warnings);
+}
+
+function checkCsrfExport(file: RouteFile, convention: string, warnings: ConventionWarning[]): void {
+  if (!isScriptExtension(file.extension)) return;
+  const found = getCsrfExport(file.filePath);
+  if (found === 'absent') return;
+  const isRoute = convention === 'route.ts';
+  if (isRoute && found === 'exempt') return;
+  warnings.push({
+    id: `CSRF_EXPORT_INVALID:${file.filePath}`,
+    summary: isRoute
+      ? `route.ts csrf export must be exactly \`export const csrf = false\`: ${file.filePath}`
+      : `\`csrf\` can only be exported from route.ts, not ${convention}: ${file.filePath}`,
+    details:
+      `  File: ${file.filePath}\n\n` +
+      (isRoute
+        ? '  The CSRF gate reads this export from source before any module loads, so only\n' +
+          '  the literal form counts. Other values, `let`, and re-exports are not read.\n\n' +
+          '  To fix: write `export const csrf = false;` in this file, or remove the export.\n'
+        : '  The per-route CSRF exemption applies only to route.ts handlers. Pages, layouts\n' +
+          '  and server actions always get the CSRF check.\n\n' +
+          '  To fix: remove the export. To accept a cross-site POST, handle it in a route.ts\n' +
+          '  that exports `const csrf = false`.\n'),
+    level: 'error',
+  });
+}
+
 // ─── Check: Empty App ───────────────────────────────────────────────────────
 
 /**