@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/src/dev-tools/stack-classifier.ts

@@ -0,0 +1,75 @@
+/**
+ * Stack trace frame classifier — categorizes stack frames by origin.
+ *
+ * Provides `classifyFrame` (single frame) and `classifyStack` (full stack
+ * string) as the shared primitives used by the error page, terminal
+ * formatter, and overlay.
+ *
+ * Dev-only: this module is only imported by other dev-tools modules.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type FrameType = 'app' | 'framework' | 'internal';
+
+export interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+// ─── Frame Parsing ──────────────────────────────────────────────────────────
+
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
+  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+  if (parenMatch) {
+    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
+  }
+  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+  if (bareMatch) {
+    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
+  }
+  return {};
+}
+
+// ─── Classification ─────────────────────────────────────────────────────────
+
+/**
+ * Classify a single stack frame line by origin.
+ *
+ * - 'app': user application code (in project root, not node_modules)
+ * - 'framework': timber-app internal code
+ * - 'internal': node_modules, Node.js internals
+ */
+export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
+  const trimmed = frameLine.trim();
+
+  if (trimmed.includes('packages/timber-app/')) return 'framework';
+  if (trimmed.includes('node_modules/')) return 'internal';
+  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
+  if (trimmed.includes(projectRoot)) return 'app';
+
+  return 'internal';
+}
+
+/**
+ * Classify all frames in a full stack trace string.
+ *
+ * Parses the stack, skips the first line (error message), filters to
+ * lines starting with "at ", and returns classified frames with optional
+ * file/line/col metadata.
+ */
+export function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1) // skip first line (error message)
+    .filter((line) => line.trim().startsWith('at '))
+    .map((raw) => {
+      const type = classifyFrame(raw, projectRoot);
+      const { file, line, col } = parseFrame(raw);
+      return { raw, type, file, line, col };
+    });
+}

package/src/{plugins/dev-terminal-error.ts → dev-tools/terminal.ts}

@@ -16,13 +16,12 @@
 
 import { pathToFileURL } from 'node:url';
 import {
-  classifyFrame,
   extractComponentStack,
   parseFirstAppFrame,
   PHASE_LABELS,
   type ErrorPhase,
-  type FrameType,
-} from './dev-error-overlay.js';
+} from './overlay.js';
+import { classifyStack } from './stack-classifier.js';
 
 // ─── ANSI Codes ─────────────────────────────────────────────────────────────
 
@@ -93,40 +92,7 @@ function box(lines: string[], borderColor: string, width = 80): string {
   return output.join('\n');
 }
 
-// ─── Frame Extraction ───────────────────────────────────────────────────────
-
-interface ClassifiedFrame {
-  raw: string;
-  type: FrameType;
-  file?: string;
-  line?: number;
-  col?: number;
-}
-
-/** Parse file/line/col from a stack frame line. */
-function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
-  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
-  if (parenMatch) {
-    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
-  }
-  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
-  if (bareMatch) {
-    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
-  }
-  return {};
-}
-
-function classifyFrames(stack: string, projectRoot: string): ClassifiedFrame[] {
-  return stack
-    .split('\n')
-    .slice(1)
-    .filter((l) => l.trim().startsWith('at '))
-    .map((raw) => {
-      const type = classifyFrame(raw, projectRoot);
-      const { file, line, col } = parseFrame(raw);
-      return { raw, type, file, line, col };
-    });
-}
+// Frame classification and parsing provided by stack-classifier.ts
 
 // ─── Public API ─────────────────────────────────────────────────────────────
 
@@ -144,7 +110,7 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
   const sections: string[] = [];
   const componentStack = extractComponentStack(error);
   const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
-  const frames = error.stack ? classifyFrames(error.stack, projectRoot) : [];
+  const frames = error.stack ? classifyStack(error.stack, projectRoot) : [];
   const appFrames = frames.filter((f) => f.type === 'app');
   const internalCount = frames.filter((f) => f.type !== 'app').length;
 

package/src/{server/dev-warnings.ts → dev-tools/warnings.ts}

@@ -15,7 +15,7 @@
  */
 
 import type { ViteDevServer } from 'vite';
-import { isDebug } from './debug.js';
+import { isDebug } from '../server/debug.js';
 
 // ─── Warning IDs ───────────────────────────────────────────────────────────
 

package/src/index.ts

@@ -24,8 +24,8 @@ import { timberFonts } from './plugins/fonts';
 import { timberStaticBuild } from './plugins/static-build';
 import { timberServerActionExports } from './plugins/server-action-exports';
 import { timberBuildManifest } from './plugins/build-manifest';
-import { timberDevLogs } from './plugins/dev-logs';
-import { timberDevBrowserLogs } from './plugins/dev-browser-logs';
+import { timberDevLogs } from './dev-tools/logs';
+import { timberDevBrowserLogs } from './dev-tools/browser-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
 import { clientChunkGroup } from './plugins/client-chunks';
@@ -34,7 +34,8 @@ import { timberAdapterBuild } from './plugins/adapter-build';
 import { timberBuildReport } from './plugins/build-report';
 import { createNoopTimer } from './utils/startup-timer';
 import { resolveEncryptionKeyExpression, shouldEnableEncryption } from './server/action-encryption';
-import { createHoldingServer } from './server/dev-holding-server.js';
+import { createHoldingServer } from './dev-tools/holding-server.js';
+import { resolveStartPort, startDevServerPort } from './server/port-resolution.js';
 import type { TimberUserConfig } from './config-types.js';
 import type { PluginContext } from './plugin-context.js';
 import {
@@ -51,6 +52,14 @@ import {
 
 export type { TimberUserConfig } from './config-types.js';
 
+// Metadata route handler types — re-exported so user-authored metadata
+// route files (sitemap.ts, robots.ts, manifest.ts, icon.tsx, etc.) can
+// import them from the package root without reaching into ./server.
+// The canonical location for these types is '@timber-js/app/server'; this
+// root re-export is a convenience for typed metadata route handlers.
+// See design/16-metadata.md §"Metadata Routes".
+export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './server/types.js';
+
 /**
  * Route map interface — augmented by the generated timber-routes.d.ts.
  *
@@ -232,7 +241,7 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
   // config() hook must NOT return a `plugins` field (Vite ignores it).
   const rootSync: Plugin = {
     name: 'timber-root-sync',
-    config(userConfig, { command }) {
+    async config(userConfig, { command, isPreview }) {
       // ── Load timber.config.ts from the correct root ───────────────
       // Vite's `config` hook fires before `configResolved`. The user's
       // `root` option (if set) tells us where the project lives.
@@ -287,36 +296,60 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // We explicitly set `oxc.jsx.development: false` for builds so
       // the client bundle always uses jsx/jsxs from react/jsx-runtime,
       // regardless of the ambient NODE_ENV value.
-      // ── Start holding server for dev mode ───────────────────────
-      // Bind the port immediately so browsers see a loading page
-      // instead of ERR_CONNECTION_REFUSED during the ~6-8s startup.
-      // The holding server is closed in timber-dev-server's
-      // configureServer hook (the last plugin), right before Vite
-      // calls server.listen().
-      // See design/21-dev-server.md §"Startup Holding Server", TIM-665.
-      if (command === 'serve') {
-        const port = (userConfig.server?.port as number) ?? 5173;
-        try {
-          ctx.holdingServer = createHoldingServer();
-          // listen() is async but we fire-and-forget — the server
-          // starts binding immediately and will be ready well before
-          // any browser request arrives. We can't await here because
-          // config() must return synchronously.
-          ctx.holdingServer.listen(port).then(
-            (boundPort) => {
-              const url = `http://localhost:${boundPort}`;
-              console.log(
-                `\n  \x1b[2m🪵 timber.js dev server starting at\x1b[0m \x1b[36m${url}\x1b[0m\n`
-              );
-            },
-            () => {
-              // Port already in use — skip gracefully.
-              ctx.holdingServer = null;
-            }
-          );
-        } catch {
+      // ── Resolve dev/preview port (TIM-842) ───────────────────────
+      // Default port is 3000 with auto-bump on conflict. Explicit user
+      // overrides (`--port`, `PORT` env, `vite.config.ts` server.port)
+      // are honored as-is and fail loudly via `strictPort: true`.
+      //
+      // For dev (`command === 'serve' && !isPreview`) we start the
+      // holding server and use its `listen()` as the probe, pairing
+      // the probe with the real bind to eliminate TOCTOU races.
+      //
+      // For `vite preview` (`command === 'serve' && isPreview`) we
+      // resolve the config/env port but delegate the actual bind +
+      // auto-bump to Vite's own preview server. Starting the holding
+      // server in preview mode would self-conflict because the dev
+      // plugin's `configureServer` handoff does not run for preview;
+      // the holding server would keep the port occupied while Vite's
+      // preview tried to bind the same port.
+      //
+      // See design/21-dev-server.md §"Default Port and Auto-Bump".
+      let resolvedDevPort: number | null = null;
+      let resolvedDevPortExplicit = false;
+      if (command === 'serve' && !isPreview) {
+        ctx.holdingServer = createHoldingServer();
+        const holdingRef = ctx.holdingServer;
+        const result = await startDevServerPort({
+          configPort:
+            typeof userConfig.server?.port === 'number' ? userConfig.server.port : undefined,
+          envPort: process.env.PORT,
+          listen: (p) => holdingRef.listen(p),
+        });
+        resolvedDevPort = result.port;
+        resolvedDevPortExplicit = result.explicit;
+        if (!result.bound) {
+          // Holding server failed to bind. Drop the reference so the
+          // dev-server plugin doesn't try to close a server that was
+          // never listening, and let Vite surface the conflict.
           ctx.holdingServer = null;
         }
+      } else if (command === 'serve' && isPreview) {
+        // Preview mode: resolve the starting port from config/env/
+        // default but do NOT probe. Vite's preview server handles the
+        // bind itself, with `preview.strictPort` controlling whether
+        // an in-use port auto-bumps (implicit) or errors (explicit).
+        const previewConfigPort =
+          typeof userConfig.preview?.port === 'number'
+            ? userConfig.preview.port
+            : typeof userConfig.server?.port === 'number'
+              ? userConfig.server.port
+              : undefined;
+        const start = resolveStartPort({
+          configPort: previewConfigPort,
+          envPort: process.env.PORT,
+        });
+        resolvedDevPort = start.port;
+        resolvedDevPortExplicit = start.explicit;
       }
 
       // Return the resolved buildDir as Vite's build.outDir so the RSC
@@ -349,8 +382,36 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         };
       }
 
-      // Dev mode: set outDir so dev-time references are consistent
-      return { build: { outDir: buildOutDir }, environments: envOutDirs };
+      // Dev/preview mode: set outDir so dev-time references are
+      // consistent, and surface the resolved port to Vite.
+      //
+      // For dev, we set strictPort: true so Vite uses exactly the port
+      // the holding server probed for — without strictPort, Vite would
+      // run its own auto-bump starting from `port`, which would skip
+      // straight past whatever holding-server-bumped port we picked.
+      //
+      // For `vite preview`, we set `preview.strictPort` based on
+      // whether the user explicitly set the port. Implicit (default)
+      // preview uses strictPort: false so Vite's preview server can
+      // auto-bump from 3000. Explicit preview uses strictPort: true
+      // so conflicts fail loudly, matching the dev behavior and the
+      // TIM-842 spec.
+      const serverConfig: { port?: number; strictPort?: boolean } = {};
+      const previewConfig: { port?: number; strictPort?: boolean } = {};
+      if (resolvedDevPort != null) {
+        if (!isPreview) {
+          serverConfig.port = resolvedDevPort;
+          serverConfig.strictPort = true;
+        }
+        previewConfig.port = resolvedDevPort;
+        previewConfig.strictPort = resolvedDevPortExplicit;
+      }
+      return {
+        build: { outDir: buildOutDir },
+        environments: envOutDirs,
+        server: serverConfig,
+        preview: previewConfig,
+      };
     },
     configResolved(resolved) {
       ctx.root = resolved.root;

package/src/plugin-context.ts

@@ -16,7 +16,7 @@ import type { BuildManifest } from './server/build-manifest';
 import type { StartupTimer } from './utils/startup-timer';
 import { createStartupTimer } from './utils/startup-timer';
 import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
-import type { HoldingServer } from './server/dev-holding-server.js';
+import type { HoldingServer } from './dev-tools/holding-server.js';
 
 // Re-export for sub-plugin convenience — they import from plugin-context.ts
 export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';

package/src/plugins/adapter-build.ts

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
 import type { PluginContext } from '../plugin-context.js';
 import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
+import { swallow } from '../server/logger.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -103,7 +104,8 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
     let manifest: Record<string, unknown>;
     try {
       manifest = JSON.parse(jsonStr);
-    } catch {
+    } catch (err) {
+      swallow(err, `corrupted RSC assets manifest: ${path}`, { level: 'warn' });
       continue;
     }
 

package/src/plugins/build-report.ts

@@ -17,6 +17,7 @@ import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
 import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
@@ -83,33 +84,23 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
-  const routes: RouteInfo[] = [];
-
-  function walk(node: SegmentNode, chain: SegmentNode[]): void {
-    const currentChain = [...chain, node];
-    const path = node.urlPath || '/';
-
-    if (node.page) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.page.filePath });
-    }
-    if (node.route) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
-    }
-
-    // Recurse into child segments only — skip parallel slots (node.slots)
-    for (const child of node.children) walk(child, currentChain);
-  }
-
-  walk(tree.root, []);
+  const leaves = collectLeafRoutes(tree.root);
+  const routes: RouteInfo[] = leaves.map((leaf) => ({
+    path: leaf.urlPath,
+    segments: leaf.segments,
+    entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null,
+  }));
 
   // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
   // Keep the entry with the longest segment chain (most specific match).

package/src/plugins/dev-server.ts

@@ -16,19 +16,19 @@ import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
 import type { PluginContext } from '../plugin-context.js';
-import { setViteServer } from '../server/dev-warnings.js';
+import { setViteServer } from '../dev-tools/warnings.js';
 import {
   sendErrorToOverlay,
   classifyErrorPhase,
   fixErrorStacktrace,
   parseFirstAppFrame,
   type ErrorPhase,
-} from './dev-error-overlay.js';
+} from '../dev-tools/overlay.js';
 import {
   generateDevErrorPage,
   extractHmrOptions,
   type DevErrorHmrOptions,
-} from './dev-error-page.js';
+} from '../dev-tools/error-page.js';
 import { addVirtualModuleContext } from '../config-validation.js';
 import { compressResponse } from '../server/compress.js';
 

package/src/plugins/routing.ts

@@ -116,7 +116,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
           segmentType: 'static',
           urlPath: '/',
           children: [],
-          slots: new Map(),
+          slots: {},
         },
       };
       return;
@@ -326,7 +326,7 @@ function generateSearchParamsRegistryModule(tree: RouteTree): string {
       }
     }
     for (const child of node.children) walk(child);
-    for (const [, slot] of node.slots) walk(slot);
+    for (const slot of Object.values(node.slots)) walk(slot);
   }
   walk(tree.root);
 
@@ -482,9 +482,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     // Runtime registration happens in the route loader using the page module.
 
     // Status-code files
-    if (node.statusFiles && node.statusFiles.size > 0) {
+    if (node.statusFiles && Object.keys(node.statusFiles).length > 0) {
       const statusEntries: string[] = [];
-      for (const [code, file] of node.statusFiles) {
+      for (const [code, file] of Object.entries(node.statusFiles)) {
         const v = addImport(file);
         statusEntries.push(
           `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -494,9 +494,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // JSON status-code files
-    if (node.jsonStatusFiles && node.jsonStatusFiles.size > 0) {
+    if (node.jsonStatusFiles && Object.keys(node.jsonStatusFiles).length > 0) {
       const jsonEntries: string[] = [];
-      for (const [code, file] of node.jsonStatusFiles) {
+      for (const [code, file] of Object.entries(node.jsonStatusFiles)) {
         const v = addImport(file);
         jsonEntries.push(
           `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -506,9 +506,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // Legacy status files
-    if (node.legacyStatusFiles && node.legacyStatusFiles.size > 0) {
+    if (node.legacyStatusFiles && Object.keys(node.legacyStatusFiles).length > 0) {
       const legacyEntries: string[] = [];
-      for (const [name, file] of node.legacyStatusFiles) {
+      for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
         const v = addImport(file);
         legacyEntries.push(
           `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -520,9 +520,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.)
-    if (node.metadataRoutes && node.metadataRoutes.size > 0) {
+    if (node.metadataRoutes && Object.keys(node.metadataRoutes).length > 0) {
       const metaEntries: string[] = [];
-      for (const [name, file] of node.metadataRoutes) {
+      for (const [name, file] of Object.entries(node.metadataRoutes)) {
         const v = addImport(file);
         metaEntries.push(
           `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -540,9 +540,11 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // Parallel slots
-    if (node.slots.size > 0) {
+    const slotKeys = Object.keys(node.slots);
+    if (slotKeys.length > 0) {
       const slotEntries: string[] = [];
-      for (const [slotName, slotNode] of node.slots) {
+      for (const slotName of slotKeys) {
+        const slotNode = node.slots[slotName]!;
         slotEntries.push(
           `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
         );

package/src/plugins/shims.ts

@@ -299,7 +299,7 @@ export const headers = stub;
 export const cookies = stub;
 export const getHeaders = stub;
 export const getHeader = stub;
-export const getCookies = stub;
+export const getCookieJar = stub;
 export const getCookie = stub;
 export const getSearchParams = stub;
 export const getSegmentParams = stub;

package/src/plugins/static-build.ts

@@ -39,7 +39,7 @@ export interface StaticOptions {
  * We detect both import-level and call-level usage.
  */
 const DYNAMIC_API_PATTERNS: Array<{ pattern: RegExp; name: string }> = [
-  { pattern: /\bgetCookies\s*\(/, name: 'getCookies()' },
+  { pattern: /\bgetCookieJar\s*\(/, name: 'getCookieJar()' },
   { pattern: /\bgetHeaders\s*\(/, name: 'getHeaders()' },
   { pattern: /\bcookies\s*\(/, name: 'cookies()' },
   { pattern: /\bheaders\s*\(/, name: 'headers()' },

package/src/routing/codegen.ts

@@ -149,7 +149,7 @@ function collectRoutes(
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     collectRoutes(slot, params, nextAncestorFiles, routes);
   }
 }

package/src/routing/convention-lint.ts

@@ -13,6 +13,7 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import type { RouteTree, SegmentNode } from './types.js';
+import { swallow } from '../server/logger.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -89,7 +90,7 @@ function hasAnyRoutable(node: SegmentNode): boolean {
   for (const child of node.children) {
     if (hasAnyRoutable(child)) return true;
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     if (hasAnyRoutable(slot)) return true;
   }
   return false;
@@ -105,7 +106,7 @@ function hasAnyPage(node: SegmentNode): boolean {
   for (const child of node.children) {
     if (hasAnyPage(child)) return true;
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     if (hasAnyPage(slot)) return true;
   }
   return false;
@@ -164,8 +165,8 @@ function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): vo
           level: 'warn',
         });
       }
-    } catch {
-      // Can't read the file — skip silently
+    } catch (err) {
+      swallow(err, `convention-lint: unreadable route.ts ${filePath}`);
     }
   }
 
@@ -173,7 +174,7 @@ function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): vo
   for (const child of node.children) {
     checkRouteExports(child, warnings);
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     checkRouteExports(slot, warnings);
   }
 }
@@ -249,7 +250,7 @@ function checkDefaultExports(node: SegmentNode, warnings: ConventionWarning[]):
   for (const child of node.children) {
     checkDefaultExports(child, warnings);
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     checkDefaultExports(slot, warnings);
   }
 }
@@ -280,8 +281,8 @@ function checkFileDefaultExport(
         level: 'warn',
       });
     }
-  } catch {
-    // Can't read file — skip silently
+  } catch (err) {
+    swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
   }
 }
 

package/src/routing/index.ts

@@ -1,4 +1,4 @@
-export { scanRoutes, classifySegment } from './scanner.js';
+export { scanRoutes } from './scanner.js';
 export { generateRouteMap } from './codegen.js';
 export type { CodegenOptions } from './codegen.js';
 export type {
@@ -12,5 +12,7 @@ export type {
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
 export { collectInterceptionRewrites } from './interception.js';
 export type { InterceptionRewrite } from './interception.js';
-export { classifyUrlSegment } from './segment-classify.js';
-export type { UrlSegment } from './segment-classify.js';
+export { classifyUrlSegment, classifySegment } from './segment-classify.js';
+export type { UrlSegment, SegmentClassification } from './segment-classify.js';
+export { collectLeafRoutes } from './walkers.js';
+export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.js';

package/src/routing/interception.ts

@@ -70,7 +70,7 @@ function walkForInterceptions(
   }
 
   // Check slots (intercepting routes are typically inside slots like @modal)
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     walkForInterceptions(slot, ancestors, rewrites);
   }
 }