@bractjs/bractjs 0.1.26 → 0.1.28

package/src/codegen/route-codegen.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { scanRoutes } from "../server/scanner.ts";
 import type { Segment } from "../server/scanner.ts";
+import { hashString } from "../build/hash.ts";
 
 // Convert [param] / [...catchAll] notation to :param colon-style for URLs.
 function patternToColon(urlPattern: string): string {
@@ -34,6 +35,8 @@ function substituteParams(pattern: string, params: string[]): string {
 // backtick, ${ }, or quote into the generated TS source.
 const SAFE_PATTERN_RE = /^\/(?:[A-Za-z0-9_\-]+|:[A-Za-z_][A-Za-z0-9_]*)(?:\/(?:[A-Za-z0-9_\-]+|:[A-Za-z_][A-Za-z0-9_]*))*$|^\/$/;
 const SAFE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// Same guard the module-registry codegen applies before emitting import paths.
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]]+$/;
 
 function assertSafePattern(pattern: string): void {
   if (!SAFE_PATTERN_RE.test(pattern)) {
@@ -45,6 +48,11 @@ function assertSafeParam(name: string): void {
     throw new Error(`[bractjs] codegen: refusing to emit unsafe param name: ${JSON.stringify(name)}`);
   }
 }
+function assertSafeFilePath(filePath: string): void {
+  if (!SAFE_FILEPATH_RE.test(filePath) || filePath.split("/").includes("..")) {
+    throw new Error(`[bractjs] codegen: refusing to emit unsafe file path: ${JSON.stringify(filePath)}`);
+  }
+}
 
 function builderEntry(pattern: string, params: string[]): string {
   assertSafePattern(pattern);
@@ -78,35 +86,70 @@ const HEADER =
   "\n" +
   "/* eslint-disable */\n";
 
+// `RouteSearchParamsMap` / `RouteContextMap` are owned by the package
+// (`@bractjs/bractjs`) so users have a single stable module to augment. We do
+// NOT seed per-route keys here: seeding `"/posts": Record<string,string>` would
+// conflict with a user augmentation declaring `"/posts": { page: string }`
+// (duplicate-property error). Instead `SearchParams<T>` / `Context<T>` fall back
+// to the permissive default for any route the user hasn't augmented.
 function searchParamsTypeLines(routes: Array<{ pattern: string }>): string {
-  // Route files may declare `export type SearchParams = { page: string }`.
-  // We emit a mapped type that falls back to Record<string,string> per route.
-  // Users augment via module augmentation or via their route file's export.
   if (routes.length === 0) {
     return "export type SearchParams<_T extends AppRoutes> = Record<string, string>;";
   }
   const branches = routes
     .map((r) => {
       assertSafePattern(r.pattern);
-      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteSearchParamsMap[" + JSON.stringify(r.pattern) + "] :";
+      const key = JSON.stringify(r.pattern);
+      // Use `extends Record<K, infer V>` rather than `keyof` + index access:
+      // RouteSearchParamsMap may be `{}` (no user augmentation), and indexing an
+      // empty interface — even inside a `K extends keyof M` guard — trips
+      // TS2538 "cannot be used as an index type". The Record-infer form resolves
+      // V only when the route is augmented, and falls back otherwise.
+      return "  T extends " + key +
+        " ? (RouteSearchParamsMap extends Record<" + key + ", infer V> ? V : Record<string, string>) :";
     })
     .join("\n");
-  const mapEntries = routes
-    .map((r) => "  " + JSON.stringify(r.pattern) + ": Record<string, string>;")
-    .join("\n");
   return [
-    "// Augment RouteSearchParamsMap to type search params per route:",
-    "// declare module 'bractjs' { interface RouteSearchParamsMap { '/blog': { page: string } } }",
-    "export interface RouteSearchParamsMap {",
-    mapEntries,
-    "}",
-    "",
+    "// Augment RouteSearchParamsMap (on the package) to type a route's search params:",
+    "//   declare module \"@bractjs/bractjs\" { interface RouteSearchParamsMap { \"/blog\": { page: string } } }",
     "export type SearchParams<T extends AppRoutes> =",
     branches,
     "  Record<string, string>;",
   ].join("\n");
 }
 
+// Per-route VALIDATED search shapes, inferred from each route's `searchSchema`
+// export via type-only `typeof import(...)`. Routes without a schema fall back
+// to the user's RouteSearchParamsMap augmentation, then a permissive record.
+// This map feeds `Register.routes.searchOutput` → `useSearch`/`useSetSearch`/
+// `<Link search>`; the legacy string-valued `search` member is untouched.
+function searchOutputTypeLines(routes: Array<{ pattern: string; filePath: string }>): string {
+  if (routes.length === 0) {
+    return "export type GeneratedSearchOutput = Record<never, never>;";
+  }
+  const entries = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      assertSafeFilePath(r.filePath);
+      const key = JSON.stringify(r.pattern);
+      const spec = JSON.stringify("./" + r.filePath.split("\\").join("/"));
+      return "  " + key + ": typeof import(" + spec + ") extends { searchSchema: infer S }\n" +
+        "    ? InferSchemaOutput<S>\n" +
+        "    : (RouteSearchParamsMap extends Record<" + key + ", infer V> ? V : Record<string, unknown>);";
+    })
+    .join("\n");
+  return [
+    "// Validated search shape per route, inferred from `searchSchema` exports.",
+    "export type GeneratedSearchOutput = {",
+    entries,
+    "};",
+    "",
+    "/** Validated search object for a route — what `useSearch<T>()` returns. */",
+    "export type SearchOutput<T extends AppRoutes> =",
+    "  T extends keyof GeneratedSearchOutput ? GeneratedSearchOutput[T] : Record<string, unknown>;",
+  ].join("\n");
+}
+
 function contextTypeLines(routes: Array<{ pattern: string }>): string {
   if (routes.length === 0) {
     return "export type Context<_T extends AppRoutes> = Record<string, unknown>;";
@@ -114,31 +157,126 @@ function contextTypeLines(routes: Array<{ pattern: string }>): string {
   const branches = routes
     .map((r) => {
       assertSafePattern(r.pattern);
-      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteContextMap[" + JSON.stringify(r.pattern) + "] :";
+      const key = JSON.stringify(r.pattern);
+      // See SearchParams above for why this uses `extends Record<K, infer V>`.
+      return "  T extends " + key +
+        " ? (RouteContextMap extends Record<" + key + ", infer V> ? V : Record<string, unknown>) :";
     })
     .join("\n");
-  const mapEntries = routes
-    .map((r) => "  " + JSON.stringify(r.pattern) + ": Record<string, unknown>;")
-    .join("\n");
   return [
-    "// Augment RouteContextMap to type context per route:",
-    "// declare module 'bractjs' { interface RouteContextMap { '/blog': { user: User } } }",
-    "export interface RouteContextMap {",
-    mapEntries,
-    "}",
-    "",
+    "// Augment RouteContextMap (on the package) to type a route's context:",
+    "//   declare module \"@bractjs/bractjs\" { interface RouteContextMap { \"/blog\": { user: User } } }",
     "export type Context<T extends AppRoutes> =",
     branches,
     "  Record<string, unknown>;",
   ].join("\n");
 }
 
+// The `Register` augmentation: this is what wires the app's routes into the
+// package's runtime helpers (<Link>, useNavigate, useParams, useSearchParams).
+function registerAugmentationLines(routes: Array<{ pattern: string; params: string[] }>): string {
+  const paramEntries = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      r.params.forEach(assertSafeParam);
+      const shape = r.params.length === 0
+        ? "{}"
+        : "{ " + r.params.map((p) => p + ": string").join("; ") + " }";
+      return "      " + JSON.stringify(r.pattern) + ": " + shape + ";";
+    })
+    .join("\n");
+  return [
+    "// Registers this app's routes with BractJS. After this augmentation, <Link>,",
+    "// useNavigate, useParams, and useSearchParams are type-safe against AppRoutes.",
+    "declare module \"@bractjs/bractjs\" {",
+    "  interface Register {",
+    "    routes: {",
+    "      routes: AppRoutes;",
+    "      params: {",
+    paramEntries,
+    "      };",
+    "      search: RouteSearchParamsMap;",
+    "      searchOutput: GeneratedSearchOutput;",
+    "    };",
+    "  }",
+    "}",
+  ].join("\n");
+}
+
+// ── Freshness fingerprint ────────────────────────────────────────────────
+// The generated file embeds a hash of its route patterns so the dev server can
+// detect drift precisely (and skip rewrites when nothing changed, which would
+// otherwise trigger an editor reload loop). Patterns are sorted everywhere so
+// the output is identical across machines regardless of filesystem scan order.
+
+const FINGERPRINT_RE = /^\/\/ bractjs:routes ([0-9a-f]+) \((\d+) routes?\)$/m;
+
+/** Stable 8-hex fingerprint of a route-pattern set (order-independent). */
+export function routesFingerprint(patterns: string[]): Promise<string> {
+  return hashString([...patterns].sort().join("\n"));
+}
+
+/** Extract the fingerprint hash previously written into a generated file, or null. */
+export function readFingerprint(src: string | null): string | null {
+  if (!src) return null;
+  const m = src.match(FINGERPRINT_RE);
+  return m ? m[1] : null;
+}
+
+/**
+ * A precise human-readable reason the generated types are stale, or null when
+ * fresh. `patterns` must be colon-style (the form the generated file embeds);
+ * prefer {@link explainStalenessForApp} which derives them for you.
+ */
+export async function explainStaleness(
+  oldSrc: string | null,
+  patterns: string[],
+): Promise<string | null> {
+  if (!oldSrc) return "route-types.gen.ts is missing — generating it";
+  const current = await routesFingerprint(patterns);
+  if (readFingerprint(oldSrc) === current) return null;
+  // Recover the old pattern set from the union members to report add/remove
+  // counts. The last member ends with `;`, so allow an optional trailing `;`.
+  const old = new Set(
+    [...oldSrc.matchAll(/^ {2}\| "([^"]+)";?$/gm)].map((m) => m[1]),
+  );
+  const now = new Set(patterns);
+  const added = patterns.filter((p) => !old.has(p)).length;
+  const removed = [...old].filter((p) => !now.has(p)).length;
+  const parts: string[] = [];
+  if (added) parts.push(`+${added} added`);
+  if (removed) parts.push(`-${removed} removed`);
+  const detail = parts.length ? ` (${parts.join(", ")})` : "";
+  return `routes changed since last codegen${detail} — regenerating`;
+}
+
+/** Colon-style route patterns for an app dir (the form the generated file uses). */
+export async function routePatternsForApp(appDir: string): Promise<string[]> {
+  const routeFiles = await scanRoutes(appDir);
+  return routeFiles.map((r) => patternToColon(r.urlPattern));
+}
+
+/** {@link explainStaleness} against the current generated file + route set on disk. */
+export async function explainStalenessForApp(
+  appDir: string,
+  outPath?: string,
+): Promise<string | null> {
+  const dest = outPath ?? join(appDir, "route-types.gen.ts");
+  const existing = await Bun.file(dest).text().catch(() => null);
+  return explainStaleness(existing, await routePatternsForApp(appDir));
+}
+
 export async function generateRouteTypes(appDir: string): Promise<string> {
   const routeFiles = await scanRoutes(appDir);
-  const routes = routeFiles.map((r) => ({
-    pattern: patternToColon(r.urlPattern),
-    params: paramsFromSegments(r.segments),
-  }));
+  const routes = routeFiles
+    .map((r) => ({
+      pattern: patternToColon(r.urlPattern),
+      params: paramsFromSegments(r.segments),
+      filePath: r.filePath,
+    }))
+    // Deterministic order independent of filesystem scan order, so the output
+    // is byte-identical across machines (and the idempotent write works).
+    .sort((a, b) => a.pattern.localeCompare(b.pattern));
 
   const union = routes.length > 0
     ? routes.map((r) => {
@@ -149,8 +287,22 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
 
   const builderEntries = routes.map((r) => builderEntry(r.pattern, r.params)).join("\n");
 
+  // `RouteSearchParamsMap` / `RouteContextMap` are imported from the package so
+  // the local `SearchParams<T>` / `Context<T>` reference the same interfaces the
+  // user augments via `declare module "@bractjs/bractjs"`. `InferSchemaOutput`
+  // derives each route's validated search shape from its `searchSchema` export.
+  const IMPORTS = 'import type { RouteSearchParamsMap, RouteContextMap, InferSchemaOutput } from "@bractjs/bractjs";';
+
+  // Freshness breadcrumb: lets the dev server detect drift without re-deriving
+  // the whole file, and lets writeRouteTypes skip identical writes.
+  const fingerprint = await routesFingerprint(routes.map((r) => r.pattern));
+  const FINGERPRINT = `// bractjs:routes ${fingerprint} (${routes.length} route${routes.length === 1 ? "" : "s"})`;
+
   return [
     HEADER,
+    FINGERPRINT,
+    IMPORTS,
+    "",
     "export type AppRoutes =",
     union + ";",
     "",
@@ -158,16 +310,24 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
     "",
     searchParamsTypeLines(routes),
     "",
+    searchOutputTypeLines(routes),
+    "",
     contextTypeLines(routes),
     "",
     "export type TypedLoaderArgs<T extends AppRoutes> = {",
     "  request: Request;",
     "  params: RouteParams<T>;",
     "  context: Context<T>;",
+    "  search: T extends keyof GeneratedSearchOutput ? GeneratedSearchOutput[T] : Record<string, unknown>;",
     "};",
     "export type TypedActionArgs<T extends AppRoutes> =",
     "  TypedLoaderArgs<T> & { formData: FormData };",
     "",
+    "/** Loader args fully typed for a route literal: `loader(args: LoaderArgsFor<\"/posts\">)`. */",
+    "export type LoaderArgsFor<T extends AppRoutes> = TypedLoaderArgs<T>;",
+    "/** Action args fully typed for a route literal: `action(args: ActionArgsFor<\"/posts\">)`. */",
+    "export type ActionArgsFor<T extends AppRoutes> = TypedActionArgs<T>;",
+    "",
     "/** A locale-prefixed variant of a route (E2 i18n routing). */",
     "export type LocalizedRoute<T extends AppRoutes> = `/${string}${T}`;",
     "",
@@ -175,11 +335,23 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
     builderEntries,
     "} as const;",
     "",
+    // No routes → AppRoutes is `never`; nothing to register.
+    routes.length > 0 ? registerAugmentationLines(routes) : "",
+    "",
   ].join("\n");
 }
 
-export async function writeRouteTypes(appDir: string, outPath?: string): Promise<void> {
+export async function writeRouteTypes(
+  appDir: string,
+  outPath?: string,
+): Promise<{ dest: string; written: boolean }> {
   const dest = outPath ?? join(appDir, "route-types.gen.ts");
-  await Bun.write(dest, await generateRouteTypes(appDir));
+  const next = await generateRouteTypes(appDir);
+  // Skip the write (and the log, and the resulting file-watcher event) when the
+  // content is unchanged — otherwise auto-codegen in dev would loop the editor.
+  const existing = await Bun.file(dest).text().catch(() => null);
+  if (existing === next) return { dest, written: false };
+  await Bun.write(dest, next);
   console.log("[bract] codegen →", dest);
+  return { dest, written: true };
 }

package/src/config/load.ts

@@ -25,6 +25,7 @@ export function validateUserConfig(cfg: unknown): Partial<BractJSConfig> {
   };
 
   check("port", typeof c.port === "number" && Number.isFinite(c.port), "a finite number");
+  check("hmrPort", typeof c.hmrPort === "number" && Number.isFinite(c.hmrPort), "a finite number");
   check("appDir", typeof c.appDir === "string", "a string");
   check("publicDir", typeof c.publicDir === "string", "a string");
   check("buildDir", typeof c.buildDir === "string", "a string");
@@ -45,10 +46,30 @@ export function validateUserConfig(cfg: unknown): Partial<BractJSConfig> {
   check("onStart", typeof c.onStart === "function", "a function");
   check("onShutdown", typeof c.onShutdown === "function", "a function");
   check("onError", typeof c.onError === "function", "a function");
+  check("ssr", typeof c.ssr === "boolean", "a boolean");
+  check(
+    "prerender",
+    typeof c.prerender === "function" ||
+      (Array.isArray(c.prerender) && c.prerender.every((p) => typeof p === "string")),
+    "an array of paths or a function returning one",
+  );
 
   return c as Partial<BractJSConfig>;
 }
 
+/**
+ * Identity helper for `bractjs.config.ts` — wrap your default export to get
+ * autocomplete and type-checking on the config fields (no runtime effect):
+ *
+ * ```ts
+ * import { defineConfig } from "@bractjs/bractjs";
+ * export default defineConfig({ port: 3000, clientEnv: ["PUBLIC_API_URL"] });
+ * ```
+ */
+export function defineConfig(config: Partial<BractJSConfig>): Partial<BractJSConfig> {
+  return config;
+}
+
 /**
  * Load `bractjs.config.ts` (or `.js`) from the user's cwd if present.
  * Returns an empty object when no file exists — callers fall back to defaults.

package/src/dev/hmr-client.ts

@@ -23,7 +23,9 @@ export const hmrClientScript: string = `
   }
 
   function connect() {
-    var ws = new WebSocket("ws://localhost:3001");
+    // Port published by the server's dev bootstrap (config hmrPort), else 3001.
+    var port = window.__BRACTJS_HMR_PORT__ || 3001;
+    var ws = new WebSocket("ws://localhost:" + port);
     ws.onmessage = function (event) {
       try {
         var msg = JSON.parse(event.data);

package/src/dev/route-table.ts

@@ -0,0 +1,27 @@
+export interface RouteTableRow {
+  pattern: string;
+  file: string;
+  hasLoader: boolean;
+  hasAction: boolean;
+}
+
+/**
+ * Render a compact route inventory for the dev server boot log, so a developer
+ * can see at a glance what routes the app matched (and which have data/mutation
+ * handlers). Pure string formatting — no I/O.
+ */
+export function formatRouteTable(rows: RouteTableRow[]): string {
+  if (rows.length === 0) return "[bractjs] no routes found under routes/";
+  const sorted = [...rows].sort((a, b) => a.pattern.localeCompare(b.pattern));
+  const patternWidth = Math.max(7, ...sorted.map((r) => r.pattern.length));
+  const lines = sorted.map((r) => {
+    const markers = [r.hasLoader ? "loader" : "", r.hasAction ? "action" : ""]
+      .filter(Boolean)
+      .join(" ");
+    return `  ${r.pattern.padEnd(patternWidth)}  ${markers.padEnd(13)} ${r.file}`;
+  });
+  return [
+    `[bractjs] ${rows.length} route${rows.length === 1 ? "" : "s"}:`,
+    ...lines,
+  ].join("\n");
+}

package/src/dev/server.ts

@@ -1,13 +1,66 @@
 import { createServer } from "../server/serve.ts";
-import { setRuntimeMode } from "../server/env.ts";
+import { setRuntimeMode, setDevHmrPort } from "../server/env.ts";
 import { createHmrServer } from "./hmr-server.ts";
 import { watchApp } from "./watcher.ts";
 import { rebuildClient } from "./rebuilder.ts";
-import { filePathToPattern } from "../server/scanner.ts";
-import { basename, extname } from "node:path";
+import { filePathToPattern, scanRoutes } from "../server/scanner.ts";
+import { basename, extname, join, resolve } from "node:path";
 import type { LifecycleHooks } from "../server/lifecycle.ts";
 import { loadUserConfig } from "../config/load.ts";
 import type { BractJSConfig } from "../server/serve.ts";
+import { writeRouteTypes, explainStalenessForApp } from "../codegen/route-codegen.ts";
+import { lintRouteModuleSource } from "../build/route-lint.ts";
+import { formatRouteTable, type RouteTableRow } from "./route-table.ts";
+
+// Warn-once across HMR rebuilds so the same lint message doesn't spam the log.
+const warnedRouteIssues = new Set<string>();
+
+/**
+ * Statically lint route modules and print the route table. Reads each route
+ * file's source once (no module execution, no per-request cost). Returns the
+ * table rows so the boot path can print them alongside the HMR port.
+ */
+async function inspectRoutes(appDir: string): Promise<RouteTableRow[]> {
+  const routes = await scanRoutes(appDir);
+  const rows: RouteTableRow[] = [];
+  for (const r of routes) {
+    let src = "";
+    try {
+      src = await Bun.file(resolve(process.cwd(), appDir, r.filePath)).text();
+    } catch {
+      continue;
+    }
+    for (const warning of lintRouteModuleSource(src, r.filePath)) {
+      const key = r.filePath + "\0" + warning;
+      if (warnedRouteIssues.has(key)) continue;
+      warnedRouteIssues.add(key);
+      console.warn(`[bractjs] ${warning}`);
+    }
+    rows.push({
+      pattern: r.urlPattern === "" ? "/" : "/" + r.urlPattern,
+      file: r.filePath,
+      hasLoader: /^export\s+(?:async\s+)?function\s+loader\b|^export\s+const\s+loader\b/m.test(src),
+      hasAction: /^export\s+(?:async\s+)?function\s+action\b|^export\s+const\s+action\b/m.test(src),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Regenerate typed routes if the route set drifted from the last codegen.
+ * Idempotent: writeRouteTypes skips the write when content is unchanged, so it
+ * never triggers an editor reload loop. Runs at boot and on add/remove/rename.
+ */
+async function syncRouteTypes(appDir: string): Promise<void> {
+  try {
+    const reason = await explainStalenessForApp(appDir);
+    if (reason) console.log(`[bractjs] ${reason}`);
+    await writeRouteTypes(appDir);
+  } catch (err) {
+    // Codegen is a DX aid, never fatal to the dev loop.
+    console.warn("[bractjs] route codegen skipped:", err instanceof Error ? err.message : err);
+  }
+}
 
 export interface DevServerOptions {
   /** HTTP port for the app server. Default: config.port ?? 3000. */
@@ -38,15 +91,42 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
   // for any source-import path, dev or `bractjs start`), so no separate dev hook
   // is needed here.
 
-  const hmrPort = options?.hmrPort ?? 3001;
+  const hmrPort = options?.hmrPort ?? merged.hmrPort ?? 3001;
   const appPort = options?.port ?? merged.port ?? 3000;
+  // Publish the port so the SSR dev bootstrap tells the HMR client where to connect.
+  setDevHmrPort(hmrPort);
+
+  const appDir = merged.appDir ?? "./app";
 
-  const hmr = createHmrServer(hmrPort);
+  // Keep typed routes fresh on boot (covers "added a route while the server was
+  // down"). Idempotent — no-op write when nothing changed.
+  await syncRouteTypes(appDir);
+
+  // Friendly port-conflict message instead of a raw Bun EADDRINUSE stack.
+  const onPortInUse = (which: "app server" | "HMR socket", port: number): never => {
+    console.error(
+      `[bractjs] Port ${port} is already in use (${which}). ` +
+        `Set \`port\` (and \`hmrPort\` for the HMR socket) in bractjs.config.ts, ` +
+        `or stop the process using it.`,
+    );
+    return process.exit(1);
+  };
+
+  let hmr: ReturnType<typeof createHmrServer>;
+  try {
+    hmr = createHmrServer(hmrPort);
+  } catch (err) {
+    if ((err as { code?: string }).code === "EADDRINUSE") onPortInUse("HMR socket", hmrPort);
+    throw err;
+  }
 
   // Build client bundle before the HTTP server starts accepting requests
   const { duration: initialMs } = await rebuildClient(merged);
   console.log(`[bractjs] initial client build in ${initialMs}ms`);
 
+  // Lint route modules + collect the route table (read sources once, no exec).
+  const routeRows = await inspectRoutes(appDir);
+
   // Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
   let lifecycle: LifecycleHooks = {};
   try {
@@ -57,9 +137,26 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
     // No lifecycle file — that's fine
   }
 
-  const srv = createServer({ port: appPort, ...merged, ...lifecycle });
+  let srv: ReturnType<typeof createServer>;
+  try {
+    srv = createServer({ port: appPort, ...merged, ...lifecycle });
+  } catch (err) {
+    hmr.stop();
+    if ((err as { code?: string }).code === "EADDRINUSE") onPortInUse("app server", appPort);
+    throw err;
+  }
+
+  watchApp(appDir, async (file, info) => {
+    // Add/remove/rename of a route file changes the route set → regenerate
+    // typed routes. Saves (content changes) never alter the generated output
+    // (it uses type-only `typeof import(...)`), so skip codegen on those.
+    if (info.renameSeen && file.startsWith("routes/")) {
+      await syncRouteTypes(appDir);
+    }
+
+    // Re-lint changed route modules (warn-once dedupes repeats).
+    if (file.startsWith("routes/")) await inspectRoutes(appDir);
 
-  watchApp(merged.appDir ?? "./app", async (file) => {
     const { duration } = await rebuildClient(merged);
 
     // Route files (not layout): do a fine-grained module swap without full reload.
@@ -81,7 +178,8 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
     }
   });
 
-  console.log(`BractJS dev server on http://localhost:${appPort}`);
+  console.log(formatRouteTable(routeRows));
+  console.log(`BractJS dev server on http://localhost:${appPort} (HMR ws://localhost:${hmrPort})`);
 
   return {
     stop() {

package/src/dev/watcher.ts

@@ -3,21 +3,42 @@ import { watch } from "node:fs";
 
 const WATCHED_EXTENSIONS = new Set([".tsx", ".ts", ".css"]);
 
+/** Extra info about a debounced change burst. */
+export interface WatchChangeInfo {
+  /** The last file event type seen in the burst. */
+  event: "rename" | "change";
+  /**
+   * True when ANY event in the burst was a "rename" (add/remove/rename) — not
+   * just the last one. `fs.watch` collapses bursts, so this is OR-accumulated
+   * across the debounce window; the codegen trigger keys on it.
+   */
+  renameSeen: boolean;
+}
+
 /**
  * Watches appDir for file changes and calls onChange with the changed file path.
  * Debounces rapid changes within 50ms to avoid duplicate rebuilds.
  */
-export function watchApp(appDir: string, onChange: (file: string) => void): void {
+export function watchApp(
+  appDir: string,
+  onChange: (file: string, info: WatchChangeInfo) => void,
+): void {
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let pendingFile = "";
+  let lastEvent: "rename" | "change" = "change";
+  let renameSeen = false;
 
-  watch(appDir, { recursive: true }, (_eventType, filename) => {
+  watch(appDir, { recursive: true }, (eventType, filename) => {
     if (!filename) return;
 
     const ext = path.extname(filename);
     if (!WATCHED_EXTENSIONS.has(ext)) return;
 
     pendingFile = filename;
+    lastEvent = eventType === "rename" ? "rename" : "change";
+    // OR-accumulate across the debounce window: a save (change) immediately
+    // followed by a create (rename) must not lose the rename signal.
+    if (lastEvent === "rename") renameSeen = true;
 
     if (debounceTimer !== null) {
       clearTimeout(debounceTimer);
@@ -26,7 +47,8 @@ export function watchApp(appDir: string, onChange: (file: string) => void): void
     debounceTimer = setTimeout(() => {
       debounceTimer = null;
       console.log(`✓ ${path.basename(pendingFile)} changed`);
-      onChange(pendingFile);
+      onChange(pendingFile, { event: lastEvent, renameSeen });
+      renameSeen = false;
     }, 50);
   });
 }