@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/plugins/dev-server.ts

@@ -14,16 +14,47 @@
 
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
-import { setViteServer } from '#/server/dev-warnings.js';
-import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
-import { compressResponse } from '#/server/compress.js';
+import type { TLSSocket } from 'node:tls';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { sendNodeResponse } from 'srvx/node';
+import type { PluginContext } from '../plugin-context.ts';
+import {
+  sendErrorToOverlay,
+  classifyErrorPhase,
+  fixErrorStacktrace,
+  parseFirstAppFrame,
+  type ErrorPhase,
+} from '../dev-tools/overlay.ts';
+import { generateDevErrorPage } from '../dev-tools/error-page.ts';
+import { extractHmrOptions, type DevErrorHmrOptions } from '../dev-tools/dev-page-shell.ts';
+import { addVirtualModuleContext } from '../config-validation.ts';
+import { DebugChannelRegistry, DEBUG_SUBSCRIBE_EVENT } from '../dev-tools/debug-channel.ts';
+import { registerDevDiscovery } from './dev-discovery.ts';
+import {
+  createGraphEndpointMiddleware,
+  makeGraphUpdateChannel,
+  type GraphUpdateChannel,
+} from './graph-endpoint.ts';
+import { compressResponse } from '../server/compress.ts';
+import { isSsrStreamError } from '../server/primitives.ts';
+import { isMetadataRouteServePath } from '../server/metadata-routes.ts';
+import { canonicalize } from '../server/canonicalize.ts';
+import { matchUrlParts } from '../server/tree-match.ts';
+import type { RouteTree } from '../routing/types.ts';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
 const RSC_ENTRY_ID = 'virtual:timber-rsc-entry';
 
+/**
+ * Exit code used to signal the CLI supervisor that the dev server needs
+ * a full process restart (e.g. timber.config.ts changed). The supervisor
+ * in cli.ts respawns the worker on this code. 75 = EX_TEMPFAIL (sysexits).
+ * See TIM-1444.
+ */
+export const RESTART_EXIT_CODE = 75;
+
 /**
  * Config file names that trigger a full dev server restart when changed.
  * See 21-dev-server.md §HMR Wiring — config is loaded once at startup.
@@ -55,6 +86,10 @@ const ASSET_EXTENSIONS =
  * Hook: configureServer (returns post-hook to register after Vite's middleware)
  */
 export function timberDevServer(ctx: PluginContext): Plugin {
+  // Set in configureServer, consumed by hotUpdate/transform — the
+  // graph push channel emits through the server's HMR transport.
+  let graphChannel: GraphUpdateChannel | null = null;
+
   return {
     name: 'timber-dev-server',
 
@@ -62,6 +97,28 @@ export function timberDevServer(ctx: PluginContext): Plugin {
     // See 21-dev-server.md §Plugin Registration.
     apply: 'serve',
 
+    /**
+     * Push channel for the graph endpoint, phase 1: `invalidated`, one
+     * per (file, environment). Emitted from hotUpdate — which runs
+     * AFTER Vite invalidates the environment module graphs — never
+     * from a raw watcher listener, which would race consumers into
+     * querying pre-invalidation memberships (design/47 §"Dev-server
+     * endpoint").
+     */
+    hotUpdate({ file, type }) {
+      graphChannel?.onHotUpdate({ file, type, environment: this.environment.name });
+    },
+
+    /**
+     * Push channel phase 2: `transformed`, when a pending-invalidated
+     * module's import edges are actually rebuilt. A Set lookup for
+     * everything without a pending invalidation — free on the hot
+     * path. Returning nothing leaves the code untouched.
+     */
+    transform(_code, id) {
+      graphChannel?.onTransform(id, this.environment.name);
+    },
+
     /**
      * Register the dev server middleware and config file watcher.
      *
@@ -71,21 +128,33 @@ export function timberDevServer(ctx: PluginContext): Plugin {
      * rewritten /index.html. Vite-internal and asset requests are
      * filtered out explicitly and passed through to Vite.
      */
-    configureServer(server: ViteDevServer) {
-      // Watch config files for full restart.
-      // timber.config.ts is loaded once at startup — any change requires
-      // a full dev server restart. See 21-dev-server.md §HMR Wiring.
+    async configureServer(server: ViteDevServer) {
+      // Watch config files for changes. When running under the CLI
+      // supervisor (__TIMBER_DEV_WORKER), exit the process so the
+      // supervisor respawns with a fresh require cache. When running
+      // via `vite dev` directly (no supervisor), fall back to Vite's
+      // in-process server.restart() — it serves stale config, but at
+      // least the server stays alive. See TIM-1444.
       const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
-
-      server.watcher.on('change', (filePath: string) => {
-        if (configPaths.includes(filePath)) {
+      server.watcher.add(configPaths);
+      const configPathSet = new Set(configPaths);
+      const hasSupervisor = Boolean(process.env.__TIMBER_DEV_WORKER);
+      const onConfigChange = (filePath: string) => {
+        if (!configPathSet.has(filePath)) return;
+        if (hasSupervisor) {
+          console.log(`\n[timber] ${basename(filePath)} changed — restarting dev server...\n`);
+          process.exit(RESTART_EXIT_CODE);
+        } else {
+          console.log(
+            `\n[timber] ${basename(filePath)} changed — restarting dev server...` +
+              `\n[timber] Run \`timber dev\` instead of \`vite dev\` for guaranteed fresh config on restart.\n`
+          );
           server.restart();
         }
-      });
-
-      // Register Vite server for browser console warning forwarding.
-      // See 21-dev-server.md §Dev-Mode Warnings.
-      setViteServer(server);
+      };
+      server.watcher.on('change', onConfigChange);
+      server.watcher.on('add', onConfigChange);
+      server.watcher.on('unlink', onConfigChange);
 
       // Listen for client-side errors forwarded from the browser.
       // The browser entry sends 'timber:client-error' events via HMR
@@ -93,8 +162,73 @@ export function timberDevServer(ctx: PluginContext): Plugin {
       // as Vite's '{ type: "error" }' payload to trigger the overlay.
       listenForClientErrors(server, ctx.root);
 
+      // GET /__timber/graph — module-environment classification from the
+      // live env graphs, plus the timber:graph-update HMR push channel.
+      // Registered before the timber middleware so /__timber/* requests
+      // never reach the app pipeline. Dev-only by construction (this
+      // plugin is apply: 'serve'). See design/47 §"Dev-server endpoint".
+      server.middlewares.use(createGraphEndpointMiddleware(server, ctx));
+      graphChannel = makeGraphUpdateChannel(
+        ctx,
+        (payload) => server.hot.send(payload),
+        // "Edges rebuilt" signal: Vite sets a node's transformResult at
+        // the END of the transform request, after vite:import-analysis
+        // has updated the importer edges. Virtual ids (the route
+        // manifest's structural updates) have no file index — resolve
+        // them by id.
+        (file, environment) => {
+          const graph = server.environments[environment]?.moduleGraph;
+          if (!graph) return false;
+          const nodes = graph.getModulesByFile(file);
+          if (nodes) {
+            for (const node of nodes) {
+              if (node.transformResult != null) return true;
+            }
+            return false;
+          }
+          return graph.getModuleById(file)?.transformResult != null;
+        },
+        // Canonicalize watcher/hook paths into the module graphs' path
+        // space: under the default preserveSymlinks:false the graphs
+        // carry realpaths while watcher events can carry symlink paths
+        // — unkeyed by one canonical form, a pending entry would never
+        // match its own transform. Deleted files realpath their parent
+        // directory instead; virtual ids pass through untouched.
+        (file) => {
+          // Optional-chained: mock servers in unit tests carry a bare
+          // config object without resolve options.
+          if (server.config?.resolve?.preserveSymlinks || file.includes('virtual:')) return file;
+          try {
+            return realpathSync(file);
+          } catch {
+            try {
+              return join(realpathSync(dirname(file)), basename(file));
+            } catch {
+              return file;
+            }
+          }
+        }
+      );
+
       // Pre-hook — registers middleware before Vite's internals
-      server.middlewares.use(createTimberMiddleware(server, ctx.root));
+      server.middlewares.use(createTimberMiddleware(server, ctx));
+
+      // Write this server's .timber/dev/<pid>-<port>-<token>.json record once
+      // the server is listening so the graph CLI / VS Code extension can
+      // discover it. See design/47-module-environment-tooling.md §5.
+      registerDevDiscovery(server.httpServer, ctx.root, server.config);
+
+      // Close the holding server and await the port release so Vite's
+      // port probe and bind see a free port. configureServer is awaited
+      // by Vite during createServer(), before startServer() runs
+      // isPortAvailable() and httpServer.listen().
+      // closeAllConnections() (in HoldingServer.close) kills keep-alive
+      // sockets from the meta-refresh page so close() resolves promptly.
+      // See design/21-dev-server.md §"Startup Holding Server", TIM-1419.
+      if (ctx.holdingServer) {
+        await ctx.holdingServer.close().catch(() => {});
+        ctx.holdingServer = null;
+      }
 
       // Log startup timing summary. configureServer runs on all plugins
       // before the server listens, so this captures the full cold start.
@@ -121,7 +255,33 @@ export function timberDevServer(ctx: PluginContext): Plugin {
  * For non-route requests (assets, Vite internals, HMR), the middleware
  * calls next() to let Vite handle them.
  */
-function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
+function createTimberMiddleware(server: ViteDevServer, ctx: PluginContext) {
+  const projectRoot = ctx.root;
+  // Extract HMR connection options once so the error page can construct
+  // a correct WebSocket URL (TIM-789).
+  const hmrOptions = extractHmrOptions(server.config);
+
+  // Debug channel registry: buffers RSC debug rows per request and replays
+  // them when the browser subscribes via HMR. Created ONCE per server, not
+  // per request — the middleware below re-imports the RSC entry on every
+  // request, and a per-request registry + listener would leak a stale
+  // listener per request. Each stale listener answers a subscribe with
+  // `done: true` (unknown ID), closing the browser's debug readable before
+  // the real replay arrives, which blocks Flight's root on unresolved owner
+  // refs and prevents hydration entirely. See TIM-1507.
+  const debugRegistry = new DebugChannelRegistry();
+  server.hot.on(
+    DEBUG_SUBSCRIBE_EVENT,
+    (data: unknown, client: { send: (event: string, payload: unknown) => void }) => {
+      const msg = data as { id?: string };
+      if (msg?.id) {
+        debugRegistry.subscribe(msg.id, (event, payload) => {
+          client.send(event, payload);
+        });
+      }
+    }
+  );
+
   return async (req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void> => {
     const url = req.url;
     if (!url) {
@@ -135,8 +295,27 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       return;
     }
 
-    // Pass through static asset requests
-    if (isAssetRequest(url)) {
+    // Files that exist in public/ are always served by Vite's static
+    // middleware, regardless of extension. Without this, extensions like
+    // .ico, .txt, .xml, .html either get caught by the metadata route
+    // check or aren't in ASSET_EXTENSIONS, so they fall through to the
+    // app router where a dynamic segment like [artistSlug] 404s them.
+    if (isPublicFile(server, url)) {
+      next();
+      return;
+    }
+
+    // Pass through static asset requests — but not metadata routes like
+    // /favicon.ico that match asset extensions but are handled by timber,
+    // and not registered routes like app/feed.json/route.ts whose URL ends
+    // in an asset extension. Production serves these through the RSC
+    // handler, so letting them fall through to Vite would 404 in dev only
+    // (TIM-1038).
+    if (
+      isAssetRequest(url) &&
+      !isMetadataRouteServePath(url) &&
+      !isRouteOwnedAsset(ctx.routeTree, server, url)
+    ) {
       next();
       return;
     }
@@ -160,13 +339,54 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       handler = rscModule.default as (req: Request) => Promise<Response>;
 
       // Wire pipeline errors into the browser error overlay.
-      // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
-      const setHandler = rscModule.setDevPipelineErrorHandler as
-        | ((fn: (error: Error, phase: string) => void) => void)
+      // Set devPipelineErrorHandler directly on the pipeline config —
+      // no module-level singleton. The handler receives optional RSC debug
+      // component data (component names, environments, stack frames) from
+      // the Flight debug channel for render errors.
+      const config = rscModule.pipelineConfig as
+        | {
+            devPipelineErrorHandler?: (
+              error: Error,
+              phase: string,
+              debugComponents?: Array<{
+                name: string;
+                env: string | null;
+                stack: unknown[] | null;
+              }>
+            ) => void;
+            devHmrOptions?: DevErrorHmrOptions;
+            devDebugRegistry?: DebugChannelRegistry;
+          }
         | undefined;
-      if (typeof setHandler === 'function') {
-        setHandler((error) => {
-          sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+      if (config) {
+        config.devPipelineErrorHandler = (error, _phase, debugComponents) => {
+          sendErrorToOverlay(
+            server,
+            error,
+            classifyErrorPhase(error, projectRoot),
+            projectRoot,
+            debugComponents
+          );
+        };
+        // Plumb the resolved HMR options into the RSC environment. The RSC
+        // entry can't read the Vite server config (separate module graph),
+        // but its dev 404 page and fallback error page need the HMR endpoint
+        // (including Vite 8's required WS token) for auto-reload (TIM-1067).
+        config.devHmrOptions = hmrOptions;
+        // Server-lifetime debug channel registry (created above). Re-assigned
+        // per request because the RSC module may be re-evaluated on HMR.
+        config.devDebugRegistry = debugRegistry;
+      }
+
+      // Wire source-map handler so error pages show original positions.
+      // fixErrorStacktrace rewrites the error's stack trace in-place using
+      // the Vite dev server's module graph. See TIM-811.
+      const setSourceMap = rscModule.setDevSourceMapHandler as
+        | ((fn: (error: Error) => void) => void)
+        | undefined;
+      if (typeof setSourceMap === 'function') {
+        setSourceMap((error: Error) => {
+          fixErrorStacktrace(server, error);
         });
       }
     } catch (error) {
@@ -174,9 +394,11 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Vite may already show its own overlay for these, but we still
       // log to stderr with frame dimming for the terminal.
       if (error instanceof Error) {
+        // Add context for virtual:timber-* module errors
+        addTimberContext(error);
         sendErrorToOverlay(server, error, 'module-transform', projectRoot);
       }
-      respond500(res, error);
+      respond500(res, error, 'module-transform', projectRoot, hmrOptions);
       return;
     }
 
@@ -191,40 +413,106 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Convert Node IncomingMessage → Web Request
       const webRequest = toWebRequest(req);
 
-      // Run the full pipeline
-      const webResponse = await handler(webRequest);
+      // Check for a platform-specific request wrapper (e.g., Cloudflare
+      // dev bindings). The cloudflareDevBindings() plugin stores a wrapper
+      // function on the server instance using a well-known Symbol. The
+      // wrapper runs the handler inside an ALS context so platform APIs
+      // like getCloudflareBindings() work during dev.
+      // See design/35-cloudflare-primitives.md §"Dev Experience".
+      const wrapper = (server as any)[Symbol.for('timber:dev-request-wrapper')] as
+        | (<T>(fn: () => T) => T)
+        | undefined;
+
+      // Run the full pipeline (wrapped if a platform dev plugin is active)
+      const webResponse = wrapper
+        ? await wrapper(() => handler(webRequest))
+        : await handler(webRequest);
 
       // Compress the response if the client supports it.
       // In dev mode, compression is always enabled for parity with production.
       // See design/25-production-deployments.md.
       const finalResponse = compressResponse(webRequest, webResponse);
 
-      // Convert Web Response → Node ServerResponse
-      await sendWebResponse(res, finalResponse);
+      // Flush headers eagerly so streaming responses (SSE, long-polling)
+      // reach the client before the first body chunk. Node.js buffers
+      // headers until write()/end() otherwise, which stalls EventSource
+      // clients that wait for the response to open. srvx's writeHead
+      // skips if headersSent is already true, so pre-flushing is safe.
+      res.writeHead(finalResponse.status, [...finalResponse.headers].flat());
+      res.flushHeaders();
+
+      // Stream the body with backpressure and disconnect handling.
+      // srvx skips its own writeHead since headers are already sent.
+      await sendNodeResponse(res, finalResponse);
     } catch (error) {
       // Pipeline error — classify the phase, send to overlay, respond 500.
       // The dev server remains running for recovery on file fix + HMR.
       if (error instanceof Error) {
-        const phase = classifyErrorPhase(error, projectRoot);
-        sendErrorToOverlay(server, error, phase, projectRoot);
+        // Unwrap SsrStreamError to show the real cause in the error overlay.
+        // SsrStreamError wraps the original RSC render error with a generic
+        // message; the developer needs to see the actual error (e.g.,
+        // "useSegmentParams is not a function"), not the wrapper.
+        const displayError =
+          isSsrStreamError(error) && error.cause instanceof Error ? error.cause : error;
+        const phase = classifyErrorPhase(displayError, projectRoot);
+        sendErrorToOverlay(server, displayError, phase, projectRoot);
+        respond500(res, displayError, phase, projectRoot, hmrOptions);
       } else {
         process.stderr.write(`\x1b[31m[timber] Dev server error:\x1b[0m ${String(error)}\n`);
+        respond500(res, error, 'render', projectRoot, hmrOptions);
       }
-      respond500(res, error);
     }
   };
 }
 
 /**
  * Send a 500 response without crashing the dev server.
+ *
+ * In dev mode, renders a styled HTML error page with source context,
+ * classified stack trace, and auto-reload on HMR. Falls back to
+ * text/plain if the HTML generator fails (must never crash).
  */
-function respond500(res: ServerResponse, error: unknown): void {
-  if (!res.headersSent) {
-    res.statusCode = 500;
-    res.setHeader('content-type', 'text/plain');
-    res.end(
-      `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
-    );
+function respond500(
+  res: ServerResponse,
+  error: unknown,
+  phase: ErrorPhase,
+  projectRoot: string,
+  hmrOptions?: DevErrorHmrOptions
+): void {
+  if (res.headersSent) return;
+
+  // Try to render the rich HTML error page
+  if (error instanceof Error) {
+    try {
+      const html = generateDevErrorPage(error, phase, projectRoot, hmrOptions);
+      res.statusCode = 500;
+      res.setHeader('content-type', 'text/html; charset=utf-8');
+      res.end(html);
+      return;
+    } catch (e) {
+      console.debug(
+        '[timber] dev error page generation failed, falling back to text/plain:',
+        e instanceof Error ? e.message : e
+      );
+    }
+  }
+
+  // Fallback: plain text (same as before)
+  res.statusCode = 500;
+  res.setHeader('content-type', 'text/plain');
+  res.end(
+    `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
+  );
+}
+
+/**
+ * Add timber-specific context to an error's message if it references
+ * internal virtual modules (virtual:timber-*). Mutates the error in place.
+ */
+function addTimberContext(error: Error): void {
+  const enriched = addVirtualModuleContext(error.message);
+  if (enriched !== error.message) {
+    error.message = enriched;
   }
 }
 
@@ -235,15 +523,30 @@ function respond500(res: ServerResponse, error: unknown): void {
  *
  * Constructs the full URL from the Host header and request URL,
  * and forwards the method, headers, and body.
+ *
+ * The scheme comes from the socket's TLS state — with `server.https` the
+ * browser sends `Origin: https://host`, and a hardcoded `http://` would
+ * fail CSRF origin comparison on every POST. X-Forwarded-Proto is NOT
+ * consulted: dev connections are direct, so the header would be
+ * attacker-controlled. (TIM-1067, B32)
+ *
+ * Exported for tests.
  */
-function toWebRequest(nodeReq: IncomingMessage): Request {
-  const protocol = 'http';
-  const host = nodeReq.headers.host ?? 'localhost';
+export function toWebRequest(nodeReq: IncomingMessage): Request {
+  const protocol = (nodeReq.socket as TLSSocket | undefined)?.encrypted ? 'https' : 'http';
+  // Under HTTP/2 there is no Host header — the authority lives in the
+  // `:authority` pseudo-header.
+  const host =
+    nodeReq.headers.host ?? (nodeReq.headers[':authority'] as string | undefined) ?? 'localhost';
   const url = `${protocol}://${host}${nodeReq.url}`;
 
   const headers = new Headers();
   for (const [key, value] of Object.entries(nodeReq.headers)) {
     if (value === undefined) continue;
+    // HTTP/2 pseudo-headers (:method, :path, :authority, :scheme) are not
+    // valid Headers names — Headers.set() throws on them. They're already
+    // reflected in the request URL/method above.
+    if (key.startsWith(':')) continue;
     if (Array.isArray(value)) {
       for (const v of value) {
         headers.append(key, v);
@@ -252,6 +555,11 @@ function toWebRequest(nodeReq: IncomingMessage): Request {
       headers.set(key, value);
     }
   }
+  // HTTP/2 requests carry the authority in `:authority`, not Host — but
+  // downstream consumers (CSRF origin validation) read the Host header.
+  if (!headers.has('host')) {
+    headers.set('host', host);
+  }
 
   const method = nodeReq.method ?? 'GET';
   const hasBody = method !== 'GET' && method !== 'HEAD';
@@ -284,53 +592,6 @@ function nodeReadableToWebStream(nodeStream: IncomingMessage): ReadableStream<Ui
   });
 }
 
-/**
- * Write a Web Response to a Node ServerResponse.
- *
- * Copies status code, headers, and streams the body.
- */
-async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response): Promise<void> {
-  nodeRes.statusCode = webResponse.status;
-
-  // Copy headers. Set-Cookie needs special handling: Headers.forEach()
-  // joins multiple Set-Cookie values with ", " into one entry, but each
-  // cookie must be its own header per RFC 6265 §4.1. Use getSetCookie()
-  // to preserve individual Set-Cookie headers.
-  webResponse.headers.forEach((value, key) => {
-    if (key.toLowerCase() !== 'set-cookie') {
-      nodeRes.setHeader(key, value);
-    }
-  });
-  const setCookies = webResponse.headers.getSetCookie();
-  if (setCookies.length > 0) {
-    nodeRes.setHeader('Set-Cookie', setCookies);
-  }
-
-  // Stream the body
-  if (!webResponse.body) {
-    nodeRes.end();
-    return;
-  }
-
-  // Flush headers immediately so the client can start processing
-  // the response (critical for SSE and other streaming responses).
-  nodeRes.flushHeaders();
-
-  const reader = webResponse.body.getReader();
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      // write() returns false when the kernel buffer is full, but we
-      // don't need back-pressure here — just keep pushing chunks.
-      nodeRes.write(value);
-    }
-  } finally {
-    reader.releaseLock();
-    nodeRes.end();
-  }
-}
-
 // ─── URL Classification ──────────────────────────────────────────────────
 
 /**
@@ -347,6 +608,69 @@ function isAssetRequest(url: string): boolean {
   return ASSET_EXTENSIONS.test(url);
 }
 
+/**
+ * Check if a URL maps to a real file in the project's public/ directory.
+ * Vite serves public/ files as static assets — if a file exists there it
+ * must be passed through to Vite regardless of extension.
+ */
+function isPublicFile(server: ViteDevServer, url: string): boolean {
+  const { publicDir } = server.config;
+  if (!publicDir) return false;
+  const pathname = url.split('?')[0];
+  const relativePath = pathname.startsWith('/') ? pathname.slice(1) : pathname;
+  if (!relativePath) return false;
+  const fullPath = join(publicDir, relativePath);
+  try {
+    return statSync(fullPath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check whether an asset-extension URL belongs to a scanned route rather
+ * than a static file.
+ *
+ * Route handlers may live at paths ending in asset-like extensions
+ * (app/feed.json/route.ts → /feed.json), which the asset bypass would
+ * otherwise hand to Vite — 404ing in dev while working in production.
+ * Uses the same canonicalization and tree walker as the runtime matcher
+ * so dev classification agrees with what the pipeline would match.
+ *
+ * A file that actually exists on disk wins over the route match: the
+ * production server serves public/ statics before the RSC handler (see
+ * adapters/nitro.ts), and Vite serves root-relative source files (e.g.
+ * /app/global.css) in dev. Without this, a broad catch-all route like
+ * app/[...slug] would shadow every static asset. Joining the canonical
+ * pathname is traversal-safe — canonicalize() resolves `..` segments and
+ * rejects root escapes and encoded separators.
+ *
+ * Reads ctx.routeTree per request — the routing plugin rescans it on
+ * file add/unlink/change, so newly created routes are picked up live.
+ */
+function isRouteOwnedAsset(
+  routeTree: RouteTree | null,
+  server: ViteDevServer,
+  url: string
+): boolean {
+  if (!routeTree) return false;
+  const rawPathname = url.split('?')[0];
+  const result = canonicalize(rawPathname);
+  // Malformed URLs can't match a route — let Vite handle them as before.
+  if (!result.ok) return false;
+  const parts = result.pathname === '/' ? [] : result.pathname.slice(1).split('/');
+  if (matchUrlParts(routeTree.root, parts) === null) return false;
+
+  // Real static files win over the route match (dev/prod parity: the
+  // production server tries public/ before the RSC handler).
+  const relativePath = result.pathname.slice(1);
+  const { publicDir, root } = server.config;
+  if (publicDir && existsSync(join(publicDir, relativePath))) return false;
+  if (existsSync(join(root, relativePath))) return false;
+
+  return true;
+}
+
 // ─── Client Error Listener ─────────────────────────────────────────────
 
 interface ClientErrorPayload {
@@ -392,8 +716,8 @@ function listenForClientErrors(server: ViteDevServer, projectRoot: string): void
           loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
         },
       });
-    } catch {
-      // Overlay send must never crash the dev server
+    } catch (e) {
+      console.debug('[timber] overlay send failed:', e instanceof Error ? e.message : e);
     }
   });
 }