@bractjs/bractjs 0.1.26 → 0.1.28

package/src/client/prefetch.ts

@@ -1,32 +1,127 @@
 import type { ServerManifest } from "../server/render.ts";
-import { matchPatternForPath } from "./nav-utils.ts";
+import { matchPatternForPath, parseTo } from "./nav-utils.ts";
+import { loaderCache, cacheKey } from "./cache.ts";
 
-// ── Cache ──────────────────────────────────────────────────────────────────
+// ── State ──────────────────────────────────────────────────────────────────
 
-const prefetched = new Set<string>();
+/** In-flight prefetches by path — concurrent callers share one task. */
+const inflight = new Map<string, Promise<void>>();
+
+/** Chunk hrefs already given a <link rel="modulepreload"> tag. */
+const preloadedChunks = new Set<string>();
+
+// Cap concurrent /_data prefetches so viewport-prefetching a long list of
+// links cannot stampede the server. Chunk modulepreload is cheap (served
+// immutable from cache) and stays uncapped.
+const MAX_DATA_PREFETCHES = 6;
+let activeDataPrefetches = 0;
+
+// Prefetched data gets at least this freshness window so a hover→click within
+// it commits straight from cache with zero extra requests (same idea as
+// TanStack Router's preloadStaleTime). Routes with a longer `config.staleTime`
+// keep their own.
+const PREFETCH_STALE_TIME = 30_000;
+const PREFETCH_GC_TIME = 60_000;
 
 // ── Implementation ─────────────────────────────────────────────────────────
 
 /**
- * Prefetches both the route chunk and loader data for the given path.
- * De-duplicates via a module-level Set — safe to call on every hover.
+ * Prefetches the route chunk (via `<link rel="modulepreload">`) and warms the
+ * loader cache for the given path, under the same cache key the router
+ * computes — so the eventual navigation commits instantly. Best-effort and
+ * de-duplicated; safe to call on every hover.
  */
-export function prefetchRoute(path: string, manifest: ServerManifest): void {
-  if (prefetched.has(path)) return;
-  prefetched.add(path);
+export function prefetchRoute(path: string, manifest: ServerManifest): Promise<void> {
+  const existing = inflight.get(path);
+  if (existing) return existing;
+
+  const task = doPrefetch(path, manifest)
+    .catch(() => { /* prefetch is best-effort — never surface errors */ })
+    .finally(() => { inflight.delete(path); });
+  inflight.set(path, task);
+  return task;
+}
 
-  // Prefetch route chunk via <link rel="modulepreload">
-  const pattern = matchPatternForPath(path, manifest);
+async function doPrefetch(path: string, manifest: ServerManifest): Promise<void> {
+  const { pathname, search } = parseTo(path);
+  const pattern = matchPatternForPath(pathname, manifest);
   const chunk = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
-  if (chunk) {
+
+  // 1. Warm the route chunk.
+  if (chunk && !preloadedChunks.has(chunk)) {
+    preloadedChunks.add(chunk);
     const link = document.createElement("link");
     link.rel = "modulepreload";
     link.href = chunk;
     document.head.appendChild(link);
   }
 
-  // Prefetch loader data at low priority
-  void fetch(`/_data?path=${encodeURIComponent(path)}`, {
-    priority: "low",
-  } as RequestInit);
+  // 2. Warm the loader cache. Importing the (already preloaded) chunk yields
+  //    config/loaderDeps, which the router uses to key the cache — without the
+  //    module we fall back to the path-keyed default, matching loadRoute.
+  const mod = chunk
+    ? (await import(/* @vite-ignore */ chunk).catch(() => null)) as Record<string, unknown> | null
+    : null;
+  const routeConfig = mod?.config as { staleTime?: number; gcTime?: number } | undefined;
+  const loaderDepsFn = mod?.loaderDeps as
+    | ((args: { searchParams: URLSearchParams }) => unknown[])
+    | undefined;
+  const dataPath = pathname + search;
+  const deps = loaderDepsFn ? loaderDepsFn({ searchParams: new URLSearchParams(search) }) : [dataPath];
+  const key = cacheKey(pathname, deps);
+
+  if (loaderCache.get(key)?.fresh) return; // already warm
+  if (activeDataPrefetches >= MAX_DATA_PREFETCHES) return;
+
+  activeDataPrefetches++;
+  try {
+    const res = await fetch(`/_data?path=${encodeURIComponent(dataPath)}`, {
+      priority: "low",
+    } as RequestInit);
+    if (!res.ok) return;
+    const data = (await res.json()) as Record<string, unknown>;
+    loaderCache.set(
+      key,
+      data,
+      Math.max(routeConfig?.staleTime ?? 0, PREFETCH_STALE_TIME),
+      Math.max(routeConfig?.gcTime ?? 0, PREFETCH_GC_TIME),
+    );
+  } finally {
+    activeDataPrefetches--;
+  }
+}
+
+// ── Viewport observation (shared) ──────────────────────────────────────────
+
+const observedCallbacks = new WeakMap<Element, () => void>();
+let observer: IntersectionObserver | null = null;
+
+/**
+ * Fire `callback` once when `el` first enters the viewport, via one shared
+ * IntersectionObserver (per-element observers are a perf trap on long lists).
+ * Returns an unsubscribe function. Environments without IntersectionObserver
+ * fire immediately.
+ */
+export function observeOnce(el: Element, callback: () => void): () => void {
+  if (typeof IntersectionObserver === "undefined") {
+    callback();
+    return () => {};
+  }
+  if (!observer) {
+    observer = new IntersectionObserver((entries) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        const fire = observedCallbacks.get(entry.target);
+        observedCallbacks.delete(entry.target);
+        observer!.unobserve(entry.target);
+        if (fire) fire();
+      }
+    });
+  }
+  observedCallbacks.set(el, callback);
+  observer.observe(el);
+  return () => {
+    observedCallbacks.delete(el);
+    observer?.unobserve(el);
+  };
 }

package/src/client/registry.ts

@@ -0,0 +1,131 @@
+// 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>>;
+
+/**
+ * Pattern → VALIDATED search shape (the output of each route's `searchSchema`),
+ * registered by codegen under `Register.routes.searchOutput`. Distinct from
+ * `RegisteredSearchMap`, which stays string-valued for the legacy
+ * `useSearchParams` surface.
+ */
+export type RegisteredSearchOutputMap =
+  Register extends { routes: { searchOutput: infer S } } ? S : Record<string, Record<string, unknown>>;
+
+/** 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>;
+
+/** Validated (schema-output) search object for a specific route literal. */
+export type SearchOutputFor<TTo> =
+  TTo extends keyof RegisteredSearchOutputMap ? RegisteredSearchOutputMap[TTo] : Record<string, unknown>;
+
+/**
+ * Infer the output type of a Zod/Valibot-compatible schema — the duck-typed
+ * counterpart of `z.infer`. Used by the generated route types to derive each
+ * route's search shape from its `searchSchema` export.
+ */
+export type InferSchemaOutput<S> =
+  S extends { parse(input: unknown): infer T } ? T :
+  S extends { safeParse(input: unknown): infer R }
+    ? (Awaited<R> extends { data?: infer T } ? NonNullable<T> : Record<string, unknown>)
+    : Record<string, unknown>;
+
+/** 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/revalidation.ts

@@ -0,0 +1,25 @@
+// Bridge between the router and fetchers. `useFetcher().submit` must trigger a
+// loader revalidation after its mutation, but the hook module cannot import
+// ClientRouter (circular); instead the router registers its revalidate
+// function here on mount.
+
+export interface RevalidationInfo {
+  /** The mutation's HTTP method, when revalidation follows an action. */
+  formMethod?: string;
+  /** The action response status, when mutation-triggered. */
+  actionStatus?: number;
+}
+
+type RevalidateFn = (info?: RevalidationInfo) => Promise<void>;
+
+let currentRevalidator: RevalidateFn | null = null;
+
+/** Called by ClientRouter on mount/unmount. Not part of the public API. */
+export function registerRevalidator(fn: RevalidateFn | null): void {
+  currentRevalidator = fn;
+}
+
+/** Revalidate the active route's loaders, if a router is mounted. */
+export function triggerRevalidation(info?: RevalidationInfo): Promise<void> {
+  return currentRevalidator ? currentRevalidator(info) : Promise.resolve();
+}

package/src/client/router.tsx

@@ -1,26 +1,46 @@
 import { createContext, useContext, type ComponentType } from "react";
 import type { ServerManifest } from "../server/render.ts";
+import type { RouterLocation } from "../shared/route-types.ts";
 
 // ── Route module shape visible on the client ───────────────────────────────
 
 export interface RouteModuleClient {
   default?: ComponentType;
   ErrorBoundary?: ComponentType<{ error: Error }>;
+  /** SSR'd placeholder for selective-SSR routes (`ssr: false` / `"data-only"`). */
+  Fallback?: ComponentType;
 }
 
+/**
+ * Truthy while the initial client render must keep showing what the server
+ * sent instead of the real route component: the Fallback for selective-SSR
+ * documents, nothing for the SPA shell. Cleared (→ `false`) once loader data
+ * is in place.
+ */
+export type HydrationPending = false | "client-only" | "data-only" | "spa";
+
 // ── Router Context ─────────────────────────────────────────────────────────
 
 export interface RouteState {
   loaderData: Record<string, unknown>;
   actionData: unknown;
   params: Record<string, string>;
+  /** Query-free pathname of the current route (kept alongside `location` for back-compat). */
   pathname: string;
+  location: RouterLocation;
+  /** Validated search params (route `searchSchema` output; raw string record otherwise). */
+  search: Record<string, unknown>;
 }
 
 export interface RouterContextValue extends RouteState {
   manifest: ServerManifest;
   currentModule: RouteModuleClient | null;
   setRoute(state: Partial<RouteState>): void;
+  /** Re-run the active route's loaders (gated by `shouldRevalidate`). */
+  revalidate(): Promise<void>;
+  /** "loading" while a revalidation is in flight. Distinct from the navigation state. */
+  revalidationState: "idle" | "loading";
+  hydrationPending: HydrationPending;
 }
 
 export const RouterContext = createContext<RouterContextValue>(null!);
@@ -37,9 +57,16 @@ export function useRouterContext(): RouterContextValue {
 
 export type NavigationState = "idle" | "loading" | "submitting";
 
+export interface NavigateOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Arbitrary history state, readable via `useLocation().state` after the navigation. */
+  state?: unknown;
+}
+
 export interface NavigationContextValue {
   state: NavigationState;
-  navigate(to: string): Promise<void>;
+  navigate(to: string, options?: NavigateOptions): Promise<void>;
   submit(to: string, options: { method: string; body: FormData | Record<string, string> }): Promise<void>;
 }
 

package/src/client/scroll-restoration.ts

@@ -0,0 +1,48 @@
+// Pure helpers for <ScrollRestoration /> — kept DOM-free so they are
+// unit-testable under bun:test without a browser.
+
+export const SCROLL_STORAGE_KEY = "bractjs:scroll";
+
+/** Cap stored entries so sessionStorage doesn't grow unbounded in long sessions. */
+export const MAX_SCROLL_ENTRIES = 50;
+
+/**
+ * Record a scroll position for a history-entry key. Re-inserts the key so the
+ * map keeps insertion order as LRU order, then evicts the oldest entries past
+ * the cap.
+ */
+export function savePosition(
+  positions: Map<string, number>,
+  key: string,
+  y: number,
+  max: number = MAX_SCROLL_ENTRIES,
+): void {
+  positions.delete(key);
+  positions.set(key, y);
+  while (positions.size > max) {
+    const oldest = positions.keys().next().value;
+    if (oldest === undefined) break;
+    positions.delete(oldest);
+  }
+}
+
+export function serializePositions(positions: Map<string, number>): string {
+  return JSON.stringify(Object.fromEntries(positions));
+}
+
+/** Tolerant parse: malformed/foreign payloads yield an empty map, never throw. */
+export function deserializePositions(raw: string | null): Map<string, number> {
+  if (!raw) return new Map();
+  try {
+    const obj = JSON.parse(raw) as Record<string, unknown>;
+    const positions = new Map<string, number>();
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+      for (const [key, value] of Object.entries(obj)) {
+        if (typeof value === "number" && Number.isFinite(value)) positions.set(key, value);
+      }
+    }
+    return positions;
+  } catch {
+    return new Map();
+  }
+}

package/src/client/search-serializer.ts

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

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