npm - @bractjs/bractjs - Versions diffs - 0.1.27 → 0.1.29 - Mend

@bractjs/bractjs 0.1.27 → 0.1.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (117) hide show

package/bin/cli.ts +18 -1
package/package.json +3 -2
package/src/__tests__/codegen-write.test.ts +67 -0
package/src/__tests__/codegen.test.ts +29 -2
package/src/__tests__/compile-safety.test.ts +4 -0
package/src/__tests__/csp.test.ts +10 -0
package/src/__tests__/define-actions.test.ts +69 -0
package/src/__tests__/env.test.ts +18 -0
package/src/__tests__/fetcher-store.test.ts +67 -0
package/src/__tests__/fixtures/app/root.tsx +7 -2
package/src/__tests__/fixtures/app/routes/boom.tsx +9 -0
package/src/__tests__/fixtures/app/routes/client-only.tsx +16 -0
package/src/__tests__/fixtures/app/routes/counter.tsx +16 -0
package/src/__tests__/fixtures/app/routes/data-only.tsx +16 -0
package/src/__tests__/fixtures/app/routes/features-demo.tsx +28 -0
package/src/__tests__/fixtures/app/routes/intent-demo.tsx +46 -0
package/src/__tests__/fixtures/app/routes/protected-client-only.tsx +15 -0
package/src/__tests__/fixtures/app/routes/search-demo.tsx +39 -0
package/src/__tests__/form-data-helpers.test.ts +43 -0
package/src/__tests__/headers.test.ts +111 -0
package/src/__tests__/integration.test.ts +90 -0
package/src/__tests__/layout-registry.test.ts +7 -3
package/src/__tests__/loader.test.ts +32 -1
package/src/__tests__/matcher.test.ts +29 -0
package/src/__tests__/module-registry.test.ts +2 -3
package/src/__tests__/nav-utils.test.ts +46 -0
package/src/__tests__/prerender.test.ts +102 -0
package/src/__tests__/programmatic-api.test.ts +20 -1
package/src/__tests__/revalidation.test.ts +65 -0
package/src/__tests__/route-lint.test.ts +79 -0
package/src/__tests__/route-middleware.test.ts +84 -0
package/src/__tests__/route-table.test.ts +33 -0
package/src/__tests__/safe-validate.test.ts +96 -0
package/src/__tests__/scanner.test.ts +46 -1
package/src/__tests__/scroll-restoration.test.ts +66 -0
package/src/__tests__/search-serializer.test.ts +42 -0
package/src/__tests__/search-validation.test.ts +125 -0
package/src/__tests__/security-fixes.test.ts +201 -0
package/src/__tests__/security.test.ts +110 -1
package/src/__tests__/selective-ssr.test.ts +85 -0
package/src/__tests__/spa-mode.test.ts +77 -0
package/src/__tests__/typed-routing.test.ts +51 -1
package/src/__tests__/use-matches.test.ts +54 -0
package/src/build/bundler.ts +33 -0
package/src/build/prerender.ts +88 -0
package/src/build/route-lint.ts +49 -0
package/src/client/ClientRouter.tsx +339 -47
package/src/client/cache.ts +8 -0
package/src/client/components/Await.tsx +9 -2
package/src/client/components/Form.tsx +23 -34
package/src/client/components/Link.tsx +80 -9
package/src/client/components/Outlet.tsx +8 -2
package/src/client/components/ScrollRestoration.tsx +125 -0
package/src/client/entry.tsx +39 -2
package/src/client/fetcher-store.ts +61 -0
package/src/client/form-utils.ts +3 -0
package/src/client/hooks/useActionData.ts +7 -3
package/src/client/hooks/useFetcher.ts +116 -33
package/src/client/hooks/useFetchers.ts +23 -0
package/src/client/hooks/useLoaderData.ts +8 -4
package/src/client/hooks/useLocation.ts +27 -0
package/src/client/hooks/useMatches.ts +32 -0
package/src/client/hooks/useNavigate.ts +11 -6
package/src/client/hooks/useRevalidator.ts +26 -0
package/src/client/hooks/useSearch.ts +73 -0
package/src/client/hooks/useSearchParams.ts +7 -2
package/src/client/nav-utils.ts +26 -0
package/src/client/prefetch.ts +110 -15
package/src/client/registry.ts +24 -0
package/src/client/revalidation.ts +25 -0
package/src/client/router.tsx +34 -1
package/src/client/rpc.ts +11 -1
package/src/client/scroll-restoration.ts +48 -0
package/src/client/search-serializer.ts +40 -0
package/src/client/types.ts +6 -0
package/src/codegen/module-registry.ts +13 -21
package/src/codegen/route-codegen.ts +148 -10
package/src/config/load.ts +22 -0
package/src/dev/hmr-client.ts +3 -1
package/src/dev/route-table.ts +27 -0
package/src/dev/server.ts +106 -8
package/src/dev/watcher.ts +25 -3
package/src/index.ts +38 -6
package/src/server/action-handler.ts +3 -13
package/src/server/action-registry.ts +35 -0
package/src/server/adapter.ts +16 -0
package/src/server/api-route.ts +47 -0
package/src/server/csp.ts +19 -4
package/src/server/csrf.ts +36 -3
package/src/server/env.ts +26 -5
package/src/server/headers.ts +49 -0
package/src/server/layout.ts +43 -20
package/src/server/loader.ts +14 -8
package/src/server/matcher.ts +29 -2
package/src/server/matches.ts +50 -0
package/src/server/middleware.ts +66 -0
package/src/server/proto-guard.ts +56 -0
package/src/server/render.ts +51 -18
package/src/server/request-handler.ts +111 -29
package/src/server/scanner.ts +45 -3
package/src/server/search.ts +47 -0
package/src/server/serve.ts +116 -4
package/src/server/session.ts +12 -1
package/src/server/spa.ts +62 -0
package/src/server/stream-handler.ts +10 -1
package/src/server/validate.ts +89 -14
package/src/shared/context.ts +7 -0
package/src/shared/define-actions.ts +39 -0
package/src/shared/form-data.ts +34 -0
package/src/shared/route-types.ts +191 -2
package/templates/new-app/app/root.tsx +2 -1
package/templates/new-app/bractjs.config.ts +7 -12
package/types/config.d.ts +24 -0
package/types/index.d.ts +182 -9
package/types/route.d.ts +138 -3
package/LICENSE +0 -21
package/README.md +0 -1125

package/src/client/search-serializer.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { parseTo } from "./nav-utils.ts";
+/**
+ * Serialize a validated-search-shaped object back into a query string
+ * (including the leading `?`, or `""` when empty).
+ *
+ * - `undefined`/`null` values are dropped (the way to delete a param).
+ * - Arrays serialize as repeated keys (`{ tag: ["a","b"] }` → `?tag=a&tag=b`),
+ *   the inverse of the server's `searchParamsToObject`.
+ * - Other objects are JSON-stringified; pair them with a schema field that
+ *   `JSON.parse`s on the way in.
+ * - Everything else goes through `String()` — the server schema re-coerces on
+ *   the next request, so numbers/booleans round-trip.
+ */
+export function serializeSearch(search: Record<string, unknown>): string {
+  const sp = new URLSearchParams();
+  for (const [key, value] of Object.entries(search)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === undefined || item === null) continue;
+        sp.append(key, typeof item === "object" ? JSON.stringify(item) : String(item));
+      }
+    } else {
+      sp.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+    }
+  }
+  const qs = sp.toString();
+  return qs ? "?" + qs : "";
+}
+/**
+ * Replace a path's query string with the serialized `search` object,
+ * preserving any hash. No-op when `search` is undefined.
+ */
+export function withSearch(path: string, search?: Record<string, unknown>): string {
+  if (!search) return path;
+  const { pathname, hash } = parseTo(path);
+  return pathname + serializeSearch(search) + hash;
+}

package/src/client/types.ts CHANGED Viewed

@@ -8,11 +8,15 @@ export interface BractJSClientData {
   actionData: unknown;
   params: Record<string, string>;
   pathname: string;
+  /** Validated search params for the initial request (route `searchSchema` output). */
+  search?: Record<string, unknown>;
   manifest: ServerManifest;
   /** Path of the matched route file, used to pre-import the module before hydration. */
   routeFile?: string;
   /** Merged meta descriptors for the current route — keeps <head> in sync. */
   meta?: MetaDescriptor[];
+  /** Present when the document did not SSR the route component (selective SSR / SPA shell). */
+  ssrMode?: "client-only" | "data-only" | "spa";
 }
 // ── Window augmentation ────────────────────────────────────────────────────
@@ -22,5 +26,7 @@ declare global {
     __BRACTJS_DATA__: BractJSClientData;
     /** Dev-only: registered by ClientRouter for module-level HMR swaps. */
     __BRACTJS_HMR_ACCEPT__?: (pattern: string, mod: Record<string, unknown>) => void;
+    /** Dev-only: HMR WebSocket port published by the server's dev bootstrap. */
+    __BRACTJS_HMR_PORT__?: number;
   }
 }

package/src/codegen/module-registry.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import { join, resolve } from "node:path";
-import { scanRoutes, type RouteFile } from "../server/scanner.ts";
+import { scanRoutes, layoutDirsFromFilePath, type RouteFile } from "../server/scanner.ts";
 // Codegen entry-points: `bun build --compile` can't statically trace
 // `Bun.Glob` scans or `import(absPath)` calls, so we materialise the route /
@@ -9,13 +9,14 @@ import { scanRoutes, type RouteFile } from "../server/scanner.ts";
 // ── Path safety ────────────────────────────────────────────────────────────
-// Allow ASCII filename characters, `/` for nested directories, and `[`/`]`
-// for file-based dynamic route syntax (`[id]`, `[...slug]`). All emit sites
-// wrap the path in JSON.stringify, but we still allowlist the charset as
-// defense-in-depth against a hostile filename containing a backtick, $, quote,
-// backslash, or whitespace breaking out of the generated literal. `..` as a
-// whole segment is rejected separately below (path-traversal guard).
-const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]]+$/;
+// Allow ASCII filename characters, `/` for nested directories, `[`/`]` for
+// file-based dynamic route syntax (`[id]`, `[...slug]`, `[[id]]`), and `(`/`)`
+// for route-group folders (`(marketing)`). All emit sites wrap the path in
+// JSON.stringify, but we still allowlist the charset as defense-in-depth
+// against a hostile filename containing a backtick, $, quote, backslash, or
+// whitespace breaking out of the generated literal. `..` as a whole segment is
+// rejected separately below (path-traversal guard).
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]()]+$/;
 function assertSafeFilePath(filePath: string): void {
   if (!SAFE_FILEPATH_RE.test(filePath)) {
@@ -37,26 +38,17 @@ function pathToIdent(prefix: string, relPath: string): string {
 // ── Layout discovery ───────────────────────────────────────────────────────
-function layoutDirsForPattern(urlPattern: string): string[] {
-  if (urlPattern === "") return [];
-  const segments = urlPattern.split("/");
-  segments.pop();
-  const dirs: string[] = [];
-  for (let i = 1; i <= segments.length; i++) {
-    dirs.push(segments.slice(0, i).join("/"));
-  }
-  return dirs;
-}
 /**
  * Find every `routes/<dir>/layout.tsx` (or `.ts`) that exists on disk for the
  * given set of routes. Mirrors the runtime probe in `resolveLayoutChain` but
- * runs once at codegen time so the generated registry is exhaustive.
+ * runs once at codegen time so the generated registry is exhaustive. Layout
+ * dirs are derived from each route's FILE path (via `layoutDirsFromFilePath`)
+ * so route-group folders are covered identically to the runtime.
  */
 async function collectLayouts(appDir: string, routes: RouteFile[]): Promise<string[]> {
   const layoutPaths = new Set<string>();
   for (const route of routes) {
-    for (const dir of layoutDirsForPattern(route.urlPattern)) {
+    for (const dir of layoutDirsFromFilePath(route.filePath)) {
       for (const ext of ["tsx", "ts"]) {
         const rel = `routes/${dir}/layout.${ext}`;
         const abs = resolve(join(appDir, rel));

package/src/codegen/route-codegen.ts CHANGED Viewed

@@ -1,12 +1,14 @@
 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.
+// Convert [param] / [[optional]] / [...catchAll] notation to :param colon-style.
 function patternToColon(urlPattern: string): string {
   if (urlPattern === "") return "/";
   return "/" + urlPattern.split("/").map((seg) => {
     if (seg.startsWith("[...") && seg.endsWith("]")) return ":" + seg.slice(4, -1);
+    if (seg.startsWith("[[") && seg.endsWith("]]")) return ":" + seg.slice(2, -2);
     if (seg.startsWith("[") && seg.endsWith("]")) return ":" + seg.slice(1, -1);
     return seg;
   }).join("/");
@@ -15,7 +17,9 @@ function patternToColon(urlPattern: string): string {
 function paramsFromSegments(segments: Segment[]): string[] {
   return segments.flatMap((seg) =>
     typeof seg === "string" ? [] :
-    "param" in seg ? [seg.param] : [seg.catchAll],
+    "param" in seg ? [seg.param] :
+    "optional" in seg ? [seg.optional] :
+    [seg.catchAll],
   );
 }
@@ -34,6 +38,10 @@ 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.
+// Parens are permitted for route-group folders like `(marketing)`; they are
+// inert inside the double-quoted import string the codegen emits.
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]()]+$/;
 function assertSafePattern(pattern: string): void {
   if (!SAFE_PATTERN_RE.test(pattern)) {
@@ -45,6 +53,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);
@@ -110,6 +123,38 @@ function searchParamsTypeLines(routes: Array<{ pattern: 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>;";
@@ -156,18 +201,87 @@ function registerAugmentationLines(routes: Array<{ pattern: string; params: stri
     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) => {
@@ -180,11 +294,18 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
   // `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"`.
-  const IMPORTS = 'import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs";';
+  // 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 =",
@@ -194,16 +315,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}`;",
     "",
@@ -217,8 +346,17 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
   ].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 CHANGED Viewed

@@ -25,6 +25,8 @@ 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("maxRequestBodySize", typeof c.maxRequestBodySize === "number" && Number.isFinite(c.maxRequestBodySize) && c.maxRequestBodySize > 0, "a positive 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 +47,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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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);
   });
 }