@bractjs/bractjs 0.1.25 → 0.1.27

package/src/client/hooks/useFetcher.ts

@@ -1,4 +1,5 @@
 import { useState } from "react";
+import { toSamePath } from "../nav-utils.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -100,7 +101,22 @@ export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | Stre
         submitOpts.body instanceof FormData
           ? submitOpts.body
           : new URLSearchParams(submitOpts.body as Record<string, string>);
-      const res = await fetch(path, { method: submitOpts.method, body });
+      // Send the custom header so the server's CSRF gate accepts this
+      // same-origin mutation (browsers block it cross-origin without a CORS
+      // preflight). Without it every fetcher submit 403s.
+      const res = await fetch(path, {
+        method: submitOpts.method,
+        body,
+        headers: { "X-BractJS-Action": "1" },
+      });
+      // If the action redirected, do a real navigation rather than parsing the
+      // redirect target as JSON. Off-origin targets get a full-page nav so we
+      // never follow an attacker-controlled Location inside the SPA.
+      if (res.redirected) {
+        const to = toSamePath(res.url);
+        window.location.assign(to ?? res.url);
+        return;
+      }
       setData(await res.json());
     } finally {
       setState("idle");

package/src/client/hooks/useNavigate.ts

@@ -0,0 +1,46 @@
+import { useContext, useCallback } from "react";
+import { NavigationContext } from "../router.tsx";
+import { buildPath } from "../build-path.ts";
+import type { RegisteredRoutes, ParamsFor } from "../registry.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> {
+  /** Path params for a dynamic `to` (e.g. `{ params: { id } }` for `/blog/:id`). */
+  params?: ParamsFor<TTo>;
+}
+
+export interface NavigateFn {
+  <TTo extends RegisteredRoutes>(
+    to: TTo | (string & {}),
+    options?: NavigateOptions<TTo>,
+  ): Promise<void>;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a typed `navigate(to, { params })` for programmatic soft navigation —
+ * the imperative counterpart to `<Link>`. Mirrors `<Link>`'s `to`/`params` API:
+ * `to` autocompletes registered routes (after `bractjs codegen`) while still
+ * accepting any string, and `params` is typed per route.
+ *
+ * SSR-safe and safe outside a `ClientRouter`: with no NavigationContext it
+ * resolves to a no-op (same guard as `<Link>`), so it never throws during render.
+ *
+ * Note: navigation always pushes a history entry today; a `replace` option will
+ * follow once the underlying navigate contract supports it.
+ */
+export function useNavigate(): NavigateFn {
+  const navCtx = useContext(NavigationContext);
+  return useCallback<NavigateFn>(
+    (to, options) => {
+      const href = options?.params
+        ? buildPath(to as string, options.params as Record<string, string>)
+        : (to as string);
+      if (!navCtx) return Promise.resolve();
+      return navCtx.navigate(href);
+    },
+    [navCtx],
+  );
+}

package/src/client/hooks/useParams.ts

@@ -1,14 +1,25 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { ParamsFor } from "../registry.ts";
 
 /**
- * Returns the current route's URL params (e.g. { id: "42" }).
- * Pass a RouteParams<T> generic for typed params: useParams<RouteParams<"/blog/:id">>()
+ * Returns the current route's URL params (e.g. `{ id: "42" }`).
+ *
+ * Pass the route pattern as a generic to type the result against your codegen'd
+ * routes: `useParams<"/blog/:id">()` → `{ id: string }`. The pattern is supplied
+ * by the caller because the framework can't infer the active route at the type
+ * level (React Router's `useParams` has the same limitation). An object generic
+ * — `useParams<{ id: string }>()` — also works for hand-typed shapes.
+ *
  * Works in both SSR and client contexts.
  */
-export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+// Overload 1: a route literal → params resolved from the registry.
+export function useParams<TTo extends string>(): ParamsFor<TTo>;
+// Overload 2: an explicit object shape (back-compat with the old generic form).
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+export function useParams(): Record<string, string> {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
-  return (router?.params ?? bract?.params ?? {}) as T;
+  return router?.params ?? bract?.params ?? {};
 }

package/src/client/hooks/useSearchParams.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback, useEffect, useRef, startTransition } from "react";
 import { NavigationContext } from "../router.tsx";
 import { useContext } from "react";
+import type { SearchFor } from "../registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -17,13 +18,22 @@ export interface SearchParamsResult<T extends Record<string, string>> {
 // ── Hook ───────────────────────────────────────────────────────────────────
 
 /**
- * Reads and writes URL search params, typed per-route via generic T.
- * Triggers a loader re-run (soft-nav fetch) when params change.
+ * Reads and writes URL search params. Triggers a loader re-run (soft-nav fetch)
+ * when params change.
+ *
+ * Pass the route pattern as a generic to type the result against your codegen'd
+ * routes: `useSearchParams<"/posts">()`. Augment `RouteSearchParamsMap` to give a
+ * route a concrete shape (defaults to `Record<string, string>`). The pattern is
+ * supplied by the caller — the framework can't infer the active route at the type
+ * level. An object generic — `useSearchParams<{ page: string }>()` — also works.
  *
- * T is the route's SearchParams shape (e.g. { page: string; sort: string }).
  * This hook is SSR-safe: on the server window is absent, so it returns empty params.
  */
-export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T> {
+// Overload 1: a route literal → search shape resolved from the registry.
+export function useSearchParams<TTo extends string>(): SearchParamsResult<SearchFor<TTo>>;
+// Overload 2: an explicit object shape (back-compat with the old generic form).
+export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T>;
+export function useSearchParams(): SearchParamsResult<Record<string, string>> {
   const navCtx = useContext(NavigationContext);
 
   function readCurrent(): URLSearchParams {
@@ -66,8 +76,8 @@ export function useSearchParams<T extends Record<string, string> = Record<string
     }
   }, [navCtx]);
 
-  const getParam = useCallback(<K extends keyof T & string>(key: K): T[K] | null => {
-    return (searchParams.get(key) as T[K] | null);
+  const getParam = useCallback((key: string): string | null => {
+    return searchParams.get(key);
   }, [searchParams]);
 
   return { searchParams, getParam, setSearchParams };

package/src/client/nav-utils.ts

@@ -1,5 +1,27 @@
 import type { ServerManifest } from "../server/render.ts";
 
+// ── Redirect normalization ─────────────────────────────────────────────────
+
+/**
+ * Normalize a Location/redirect target to a same-origin path the client router
+ * can match. Returns an internal "/path?query#hash" for same-origin targets, or
+ * `null` for off-origin, protocol-relative, or malformed values — the caller
+ * MUST NOT feed a null result to the SPA router (an off-origin Location should
+ * trigger a full-page navigation instead, so the browser applies its own
+ * cross-origin protections). This is the client-side complement to the server's
+ * `sanitizeRedirect()`: it stops a soft-nav from silently following an
+ * attacker-controlled `Location` header.
+ */
+export function toSamePath(loc: string): string | null {
+  try {
+    const u = new URL(loc, window.location.href);
+    if (u.origin !== window.location.origin) return null;
+    return u.pathname + u.search + u.hash;
+  } catch {
+    return null;
+  }
+}
+
 // ── Pattern Matching ───────────────────────────────────────────────────────
 
 /**
@@ -21,15 +43,44 @@ function patternMatches(pathname: string, pattern: string): boolean {
   return p === pathSegs.length;
 }
 
+/**
+ * Specificity score for a matching pattern, used to pick the best match the
+ * same way the server's trie does: static > dynamic > catch-all. Higher wins.
+ * Object key order is not reliable for priority, so we must score, not
+ * first-match (otherwise `[...slug]` can shadow `_index` / static routes).
+ */
+function patternScore(pattern: string): number {
+  if (pattern === "") return 1_000_000; // index route — most specific for "/"
+  let score = 0;
+  for (const seg of pattern.split("/")) {
+    score *= 10;
+    if (seg.startsWith("[...") && seg.endsWith("]")) score += 1; // catch-all
+    else if (seg.startsWith("[") && seg.endsWith("]")) score += 2; // dynamic
+    else score += 3; // static
+  }
+  return score;
+}
+
 // ── Export ─────────────────────────────────────────────────────────────────
 
-/** Returns the manifest pattern key that matches pathname, or null. */
+/** Returns the highest-priority manifest pattern that matches pathname, or null. */
 export function matchPatternForPath(
   pathname: string,
   manifest: ServerManifest,
 ): string | null {
+  // Exact static match wins outright (most specific) — also a fast path.
+  const normalized = pathname.replace(/^\//, "");
+  if (normalized in manifest.routes) return normalized;
+
+  let best: string | null = null;
+  let bestScore = -1;
   for (const pattern of Object.keys(manifest.routes)) {
-    if (patternMatches(pathname, pattern)) return pattern;
+    if (!patternMatches(pathname, pattern)) continue;
+    const score = patternScore(pattern);
+    if (score > bestScore) {
+      best = pattern;
+      bestScore = score;
+    }
   }
-  return null;
+  return best;
 }

package/src/client/registry.ts

@@ -0,0 +1,107 @@
+// Type-registration seam for end-to-end typed routing (TanStack-Router style).
+//
+// This file is RUNTIME-FREE — it contributes only types. The runtime helpers
+// (`<Link>`, `useNavigate`, `useParams`, `useSearchParams`) resolve their route
+// types from `Register` declared here.
+//
+// HOW IT WORKS
+// ------------
+// `Register` is an empty, augmentable interface. Running `bractjs codegen`
+// writes `app/route-types.gen.ts`, which augments it:
+//
+//   declare module "@bractjs/bractjs" {
+//     interface Register {
+//       routes: {
+//         routes: "/" | "/blog/:id";
+//         params: { "/blog/:id": { id: string } };
+//         search: RouteSearchParamsMap;
+//       };
+//     }
+//   }
+//
+// Once augmented, `<Link to="...">` autocompletes the app's routes and type-
+// checks `params`; `useNavigate`, `useParams`, `useSearchParams` follow suit.
+//
+// GRACEFUL FALLBACK
+// -----------------
+// Un-augmented (no codegen, or codegen not yet run), `Register` is `{}`, so the
+// `Register extends { routes: ... } ? ... : <loose>` conditionals below resolve
+// to the loose `string` / `Record<string, string>` types BractJS used before.
+// Existing apps therefore keep compiling unchanged — the typed surface only
+// activates after the generated augmentation lands.
+//
+// NOTE: this seam is mirrored verbatim in `types/index.d.ts` (the published
+// declaration surface). Keep the two in sync — a divergence silently disables
+// typed routing for either monorepo or published consumers.
+
+// ── The augmentable seam ─────────────────────────────────────────────────────
+
+/**
+ * Augmentable registration interface. Empty by default; `route-types.gen.ts`
+ * augments it with this app's `RouteRegistry`. See file header.
+ */
+export interface Register {}
+
+/** The shape the generated file plugs into `Register["routes"]`. */
+export interface RouteRegistry {
+  /** Union of all route patterns, colon-style — e.g. `"/" | "/blog/:id"`. */
+  routes: string;
+  /** Map of pattern → params object — e.g. `{ "/blog/:id": { id: string } }`. */
+  params: Record<string, Record<string, string>>;
+  /** Map of pattern → search-params object. */
+  search: Record<string, Record<string, string>>;
+}
+
+// ── Package-level customization maps (stable augmentation targets) ───────────
+//
+// Users type search params / context per route by augmenting THESE interfaces
+// on the package, e.g.:
+//
+//   declare module "@bractjs/bractjs" {
+//     interface RouteSearchParamsMap { "/posts": { page: string } }
+//   }
+//
+// The generated file seeds every route with a permissive default; user
+// augmentations merge on top.
+
+/** Per-route search-params shapes. Augment to type a route's search params. */
+export interface RouteSearchParamsMap {}
+
+/** Per-route context shapes. Augment to type a route's `context`. */
+export interface RouteContextMap {}
+
+// ── Resolution helpers (drive the runtime hooks/components) ──────────────────
+
+// NOTE: these conditionals deliberately do NOT use `infer R extends RouteRegistry`.
+// A constrained `infer` here silently fails to match the generated registry (its
+// `search` member is an empty interface, which trips the constraint check) and
+// falls back to the loose branch — defeating the whole feature. We instead infer
+// each member's shape directly. `RouteRegistry` remains the documented contract
+// the generated file targets.
+
+/**
+ * The app's route union when registered, else `string`. The fallback is what
+ * keeps un-codegen'd apps compiling: every `to` still accepts any string.
+ */
+export type RegisteredRoutes =
+  Register extends { routes: { routes: infer R } } ? R : string;
+
+/** Pattern → params map when registered, else a permissive map. */
+export type RegisteredParamsMap =
+  Register extends { routes: { params: infer P } } ? P : Record<string, Record<string, string>>;
+
+/** Pattern → search map when registered, else a permissive map. */
+export type RegisteredSearchMap =
+  Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
+
+/** Params object for a specific route literal (`{}` for static routes). */
+export type ParamsFor<TTo> =
+  TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
+
+/** Search-params object for a specific route literal. */
+export type SearchFor<TTo> =
+  TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
+
+/** Whether a route literal carries any path params. Reserved for a future strict `<Link>` mode. */
+export type HasParams<TTo> =
+  keyof ParamsFor<TTo> extends never ? false : true;

package/src/client/types.ts

@@ -1,4 +1,5 @@
 import type { ServerManifest } from "../server/render.ts";
+import type { MetaDescriptor } from "../shared/route-types.ts";
 
 // ── BractJSClientData ────────────────────────────────────────────────────
 
@@ -10,6 +11,8 @@ export interface BractJSClientData {
   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[];
 }
 
 // ── Window augmentation ────────────────────────────────────────────────────

package/src/codegen/route-codegen.ts

@@ -78,29 +78,32 @@ 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>;",
@@ -114,25 +117,51 @@ 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;",
+    "    };",
+    "  }",
+    "}",
+  ].join("\n");
+}
+
 export async function generateRouteTypes(appDir: string): Promise<string> {
   const routeFiles = await scanRoutes(appDir);
   const routes = routeFiles.map((r) => ({
@@ -149,8 +178,15 @@ 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"`.
+  const IMPORTS = 'import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs";';
+
   return [
     HEADER,
+    IMPORTS,
+    "",
     "export type AppRoutes =",
     union + ";",
     "",
@@ -175,6 +211,9 @@ 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");
 }
 

package/src/config/load.ts

@@ -1,6 +1,54 @@
 import { resolve } from "node:path";
 import type { BractJSConfig } from "../server/serve.ts";
 
+/**
+ * Shallow shape check for a user-supplied config object. We don't validate
+ * exhaustively (plugins/adapters/hooks are opaque), but we catch the common
+ * mistakes early — a string `port`, a non-array `clientEnv`, etc. — so the
+ * failure surfaces here with a clear message instead of deep inside the build
+ * or the request path.
+ */
+export function validateUserConfig(cfg: unknown): Partial<BractJSConfig> {
+  if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg)) {
+    throw new Error(
+      `bractjs.config: default export must be a config object, got ${
+        Array.isArray(cfg) ? "array" : typeof cfg
+      }`,
+    );
+  }
+  const c = cfg as Record<string, unknown>;
+
+  const check = (key: string, ok: boolean, expected: string): void => {
+    if (key in c && c[key] !== undefined && !ok) {
+      throw new Error(`bractjs.config: "${key}" must be ${expected}`);
+    }
+  };
+
+  check("port", typeof c.port === "number" && Number.isFinite(c.port), "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");
+  check("imageCacheDir", typeof c.imageCacheDir === "string", "a string");
+  check("minify", typeof c.minify === "boolean", "a boolean");
+  check(
+    "sourcemap",
+    typeof c.sourcemap === "string" &&
+      ["none", "linked", "inline", "external"].includes(c.sourcemap as string),
+    'one of "none" | "linked" | "inline" | "external"',
+  );
+  check(
+    "clientEnv",
+    Array.isArray(c.clientEnv) && c.clientEnv.every((k) => typeof k === "string"),
+    "an array of strings",
+  );
+  check("plugins", Array.isArray(c.plugins), "an array of Bun plugins");
+  check("onStart", typeof c.onStart === "function", "a function");
+  check("onShutdown", typeof c.onShutdown === "function", "a function");
+  check("onError", typeof c.onError === "function", "a function");
+
+  return c as Partial<BractJSConfig>;
+}
+
 /**
  * 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.
@@ -10,8 +58,8 @@ export async function loadUserConfig(): Promise<Partial<BractJSConfig>> {
     const path = resolve(process.cwd(), name);
     if (!(await Bun.file(path).exists())) continue;
     const mod = await import(path);
-    const cfg = (mod.default ?? mod) as Partial<BractJSConfig>;
-    return cfg ?? {};
+    const cfg = mod.default ?? mod;
+    return validateUserConfig(cfg ?? {});
   }
   return {};
 }