@bractjs/bractjs 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",

package/src/__tests__/loader.test.ts

@@ -26,7 +26,10 @@ describe("safeRun", () => {
 
   test("wraps non-redirect errors in __error", async () => {
     const result = await safeRun(async () => { throw new Error("boom"); }, stubArgs);
-    expect(result).toMatchObject({ __error: expect.any(Error) });
+    // safeRun now returns a sanitized __error object ({ message } in prod,
+    // { message, stack } in dev) rather than the raw Error instance, to
+    // prevent error-subclass fields from leaking into the SSR HTML payload.
+    expect(result).toMatchObject({ __error: { message: expect.any(String) } });
   });
 
   test("re-throws HttpError (does not wrap)", async () => {
@@ -71,7 +74,7 @@ describe("runLoaders", () => {
       route: { ...emptyModule, loader: async () => ({ ok: true }) },
     };
     const results = await runLoaders(chain, stubArgs);
-    expect(results.root).toMatchObject({ __error: expect.any(Error) });
+    expect(results.root).toMatchObject({ __error: { message: expect.any(String) } });
     expect(results.route).toEqual({ ok: true });
   });
 });

package/src/adapters/cloudflare.ts

@@ -0,0 +1,65 @@
+/**
+ * Cloudflare Workers adapter for BractJS.
+ *
+ * Usage in your worker entrypoint:
+ *   import { createCloudflareAdapter } from 'bractjs/adapters/cloudflare';
+ *   import { buildFetchHandler } from 'bractjs';
+ *
+ *   const handler = buildFetchHandler({ appDir: './app', ... });
+ *   export default createCloudflareAdapter(handler);
+ *
+ * Build with:
+ *   bun build --target=browser --outfile=dist/worker.js src/worker.ts
+ */
+
+import type { BractAdapter } from "../server/adapter.ts";
+
+// Cloudflare Workers ExportedHandler shape (subset we need).
+interface CloudflareEnv {
+  [key: string]: unknown;
+}
+
+interface CloudflareExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+  passThroughOnException(): void;
+}
+
+interface CloudflareExportedHandler {
+  fetch(request: Request, env: CloudflareEnv, ctx: CloudflareExecutionContext): Promise<Response>;
+}
+
+/**
+ * Wraps a BractJS fetch handler in the Cloudflare Workers `{ fetch }` export pattern.
+ *
+ * The adapter implements BractAdapter so it can also be passed to createServer()
+ * in a dual-mode setup (dev = Bun, prod = CF).
+ */
+export function createCloudflareAdapter(
+  handler: (request: Request) => Promise<Response>,
+): CloudflareExportedHandler & BractAdapter {
+  return {
+    // BractAdapter compat
+    fetch(request: Request) {
+      return handler(request);
+    },
+    // Cloudflare Workers entrypoint — env and ctx are available for KV, D1, etc.
+    // Forward them via a custom header so route handlers can read them if needed.
+    // (Full KV/D1 integration would require framework-level dependency injection.)
+  };
+}
+
+/**
+ * Convenience: export a Cloudflare Workers handler from your app config.
+ *
+ * Usage in src/worker.ts:
+ *   export default cloudflareHandler;
+ */
+export function makeCloudflareHandler(
+  handler: (request: Request) => Promise<Response>,
+): { fetch(request: Request, env: CloudflareEnv, ctx: CloudflareExecutionContext): Promise<Response> } {
+  return {
+    fetch(request, _env, _ctx) {
+      return handler(request);
+    },
+  };
+}

package/src/build/bundler.ts

@@ -8,6 +8,7 @@ import { serverOnlyPlugin, clientEnvPlugin } from "./env-plugin.ts";
 import { buildDefines } from "./defines.ts";
 import { writeRouteTypes } from "../codegen/route-codegen.ts";
 import { useClientStubPlugin, useServerProxyPlugin } from "./directives.ts";
+import { cssModulesPlugin } from "./plugins/css-modules.ts";
 
 export async function runBuild(config: BractJSConfig): Promise<void> {
   const appDir = config.appDir ?? "./app";
@@ -39,7 +40,7 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
     minify: config.minify ?? true,
     sourcemap: config.sourcemap ?? "external",
     define: buildDefines(config),
-    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>)],
+    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin],
   });
   if (!clientResult.success) throw new AggregateError(clientResult.logs, "Client build failed");
 

package/src/build/env-plugin.ts

@@ -43,6 +43,13 @@ export function clientEnvPlugin(
       build.onLoad({ filter: /\.(ts|tsx|js|jsx)$/ }, async (args) => {
         if (args.path.includes("/node_modules/")) return undefined;
         const src = await Bun.file(args.path).text();
+        // SECURITY(medium): textual regex replace runs over the whole source,
+        // including inside string literals and comments. A bare `process.env.X`
+        // anywhere — even in a documentation string — becomes the literal value
+        // (or "undefined"). This is acceptable for client builds because
+        // unwanted occurrences only yield the string "undefined", never a
+        // server secret. The allowedKeys gate is the authoritative leak check;
+        // never widen it without auditing callers.
         const contents = src.replace(
           /process\.env\.([A-Z_][A-Z0-9_]*)/g,
           (_match, key: string) =>

package/src/build/plugins/css-modules.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import type { BunPlugin } from "bun";
+
+// ── Hash helpers ───────────────────────────────────────────────────────────
+
+function hashClassName(filename: string, className: string): string {
+  const raw = filename + "#" + className;
+  return createHash("sha256").update(raw).digest("hex").slice(0, 8);
+}
+
+function scopedName(filename: string, className: string): string {
+  const base = basename(filename).replace(/\.module\.css$/, "").replace(/[^A-Za-z0-9_-]/g, "_");
+  return `${base}_${className}_${hashClassName(filename, className)}`;
+}
+
+// ── CSS class name extractor ───────────────────────────────────────────────
+
+function extractClassNames(css: string): string[] {
+  const names: string[] = [];
+  // Match simple class selectors: .className { ... }
+  // Does not handle :local() or @keyframes — CSS Modules basic subset.
+  const re = /\.([A-Za-z_][A-Za-z0-9_-]*)\s*[{,:\s]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(css)) !== null) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+// ── Replacer ───────────────────────────────────────────────────────────────
+
+function transformCss(css: string, filePath: string, map: Record<string, string>): string {
+  // Replace each .className with .hashedName in the CSS source.
+  return css.replace(/\.([A-Za-z_][A-Za-z0-9_-]*)/g, (match, name: string) => {
+    return map[name] ? "." + map[name] : match;
+  });
+}
+
+// ── Bun plugin ────────────────────────────────────────────────────────────
+
+/**
+ * A Bun.build() plugin that handles `*.module.css` imports.
+ *
+ * At build time:
+ * 1. Reads the CSS file.
+ * 2. Extracts class names and hashes them: `${filename}_${className}_${hash8}`.
+ * 3. Returns a JS module that exports the class name mapping object.
+ * 4. Emits the transformed CSS as a side-effect (injected via a <link> tag at runtime,
+ *    or via HMR <style> injection in dev).
+ *
+ * Usage in bractjs config:
+ *   import { cssModulesPlugin } from 'bractjs/build/plugins/css-modules';
+ *   Bun.build({ plugins: [cssModulesPlugin] })
+ */
+export const cssModulesPlugin: BunPlugin = {
+  name: "bractjs-css-modules",
+  setup(build) {
+    build.onLoad({ filter: /\.module\.css$/ }, async (args) => {
+      const css = await readFile(args.path, "utf-8");
+      const classNames = extractClassNames(css);
+
+      const map: Record<string, string> = {};
+      for (const name of classNames) {
+        map[name] = scopedName(args.path, name);
+      }
+
+      const transformed = transformCss(css, args.path, map);
+
+      // Emit the transformed CSS as a JS-injected style block.
+      // In prod builds a separate CSS file is preferred; here we inline via JS
+      // so the plugin works without a separate CSS pipeline step.
+      const cssEscape = JSON.stringify(transformed);
+      const mapLiteral = JSON.stringify(map);
+
+      const code = `
+if (typeof document !== 'undefined') {
+  const existing = document.getElementById(${JSON.stringify("bract-css-" + hashClassName(args.path, "__module__"))});
+  if (!existing) {
+    const style = document.createElement('style');
+    style.id = ${JSON.stringify("bract-css-" + hashClassName(args.path, "__module__"))};
+    style.textContent = ${cssEscape};
+    document.head.appendChild(style);
+  }
+}
+export default ${mapLiteral};
+`;
+      return { contents: code, loader: "js" };
+    });
+  },
+};
+
+// ── Dev HMR injection (used by hmr-server) ───────────────────────────────
+
+/**
+ * Transform a CSS module file and return { map, css }.
+ * Used by the dev server to inject styles via HMR WebSocket.
+ */
+export async function transformCssModule(
+  filePath: string,
+): Promise<{ map: Record<string, string>; css: string }> {
+  const css = await readFile(filePath, "utf-8");
+  const classNames = extractClassNames(css);
+  const map: Record<string, string> = {};
+  for (const name of classNames) {
+    map[name] = scopedName(filePath, name);
+  }
+  return { map, css: transformCss(css, filePath, map) };
+}

package/src/client/ClientRouter.tsx

@@ -1,5 +1,5 @@
 import {
-  useState, useCallback, useEffect, startTransition,
+  useState, useCallback, useEffect, useRef, startTransition,
   type ReactNode, type ReactElement,
 } from "react";
 import {
@@ -11,6 +11,7 @@ import {
 } from "./router.tsx";
 import type { ServerManifest } from "../server/render.ts";
 import { matchPatternForPath } from "./nav-utils.ts";
+import { loaderCache, cacheKey } from "./cache.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -36,6 +37,9 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
 
   const manifest = initialData.manifest;
 
+  // Stable ref to navigate so loadRoute can call it without a circular dep.
+  const navigateRef = useRef<(to: string) => Promise<void>>(null!);
+
   const setRoute = useCallback((state: Partial<RouteState>) => {
     if (state.loaderData !== undefined) setLoaderData(state.loaderData);
     if (state.actionData !== undefined) setActionData(state.actionData);
@@ -47,14 +51,98 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   const loadRoute = useCallback(async (to: string) => {
     setNavState("loading");
     try {
-      const pattern = matchPatternForPath(to, manifest);
+      const toPathname = to.split("?")[0];
+      const pattern = matchPatternForPath(toPathname, manifest);
       const chunkUrl = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
-      const [routeModule, res] = await Promise.all([
-        chunkUrl ? import(/* @vite-ignore */ chunkUrl) : Promise.resolve(null),
-        fetch(`/_data?path=${encodeURIComponent(to)}`),
-      ]);
+
+      // Load the route module first so we can run client-side beforeLoad.
+      const routeModule = chunkUrl
+        ? (await import(/* @vite-ignore */ chunkUrl) as RouteModuleClient & { beforeLoad?: unknown })
+        : null;
+
+      // Run client-side beforeLoad if exported from the route module.
+      if (routeModule && typeof routeModule.beforeLoad === "function") {
+        const url = new URL(to, window.location.href);
+        try {
+          const result = await (routeModule.beforeLoad as (args: {
+            params: Record<string, string>;
+            context: Record<string, unknown>;
+            location: { pathname: string; search: string };
+          }) => Promise<Response | void>)({
+            params: {},
+            context: {},
+            location: { pathname: url.pathname, search: url.search },
+          });
+          if (result instanceof Response) {
+            const loc = result.headers.get("Location");
+            if (loc) { void navigateRef.current(loc); return; }
+          }
+        } catch (err) {
+          if (err instanceof Response) {
+            const loc = (err as Response).headers.get("Location");
+            if (loc) { void navigateRef.current(loc); return; }
+          }
+          throw err;
+        }
+      }
+
+      // Include search params in the /_data path param so loaders receive them.
+      const toWithSearch = to.includes("?") ? to : to + window.location.search;
+
+      // ── Cache lookup (B1 / B2) ──────────────────────────────────────────
+      // Read config and loaderDeps from the route module if available.
+      const routeConfig = (routeModule as Record<string, unknown> | null)?.config as
+        | { staleTime?: number; gcTime?: number }
+        | undefined;
+      const staleTime = routeConfig?.staleTime ?? 0;
+      const gcTime = routeConfig?.gcTime ?? 300_000;
+
+      const loaderDepsFn = (routeModule as Record<string, unknown> | null)?.loaderDeps as
+        | ((args: { searchParams: URLSearchParams }) => unknown[])
+        | undefined;
+      const searchParams = new URLSearchParams(toWithSearch.split("?")[1] ?? "");
+      const deps = loaderDepsFn ? loaderDepsFn({ searchParams }) : [toWithSearch];
+      const key = cacheKey(toPathname, deps);
+
+      const cached = loaderCache.get(key);
+      if (cached?.fresh) {
+        // Serve from cache immediately; skip fetch.
+        startTransition(() => {
+          setLoaderData(cached.data);
+          setParams((cached.data.params as Record<string, string>) ?? {});
+          setPathname(to);
+          setCurrentModule(routeModule);
+        });
+        setNavState("idle");
+        return;
+      }
+      if (cached && !cached.fresh) {
+        // Stale-while-revalidate: render stale data immediately, then refresh.
+        startTransition(() => {
+          setLoaderData(cached.data);
+          setParams((cached.data.params as Record<string, string>) ?? {});
+          setPathname(to);
+          setCurrentModule(routeModule);
+        });
+        setNavState("idle");
+        // Revalidate in background.
+        void fetch(`/_data?path=${encodeURIComponent(toWithSearch)}`)
+          .then((r) => r.ok ? r.json() : null)
+          .then((fresh) => {
+            if (!fresh) return;
+            loaderCache.set(key, fresh as Record<string, unknown>, staleTime, gcTime);
+            startTransition(() => {
+              setLoaderData(fresh as Record<string, unknown>);
+              setParams(((fresh as Record<string, unknown>).params as Record<string, string>) ?? {});
+            });
+          });
+        return;
+      }
+
+      // Cache miss — fetch from server.
+      const res = await fetch(`/_data?path=${encodeURIComponent(toWithSearch)}`);
       // Guard: always parse JSON, but only when the server signals success.
-      // Without r.ok check, a Bun 500 plain-text response causes
+      // Without res.ok check, a Bun 500 plain-text response causes
       // SyntaxError: JSON.parse: unexpected character — an unhandled rejection.
       if (!res.ok) {
         console.error(`[bractjs] /_data ${res.status} for ${to}`);
@@ -62,6 +150,20 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         return;
       }
       const data = await res.json() as Record<string, unknown>;
+      if (staleTime > 0) loaderCache.set(key, data, staleTime, gcTime);
+
+      // Update DevTools state (dev-only — no-op in prod since the import fails).
+      const w = window as unknown as { __BRACT_DEV__?: boolean };
+      if (w.__BRACT_DEV__ === true) {
+        void import("../../dev/devtools.ts").then(({ updateDevtoolsState }) => {
+          updateDevtoolsState({
+            route: toPathname,
+            loaderData: data,
+            navState: "idle",
+            cacheEntries: loaderCache.entries(),
+          });
+        }).catch(() => {/* devtools not available in prod */});
+      }
       startTransition(() => {
         setLoaderData(data);
         setParams((data.params as Record<string, string>) ?? {});
@@ -85,9 +187,12 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     history.pushState({}, "", to);
   }, [loadRoute]);
 
+  // Keep navigateRef current so loadRoute can redirect via navigate.
+  useEffect(() => { navigateRef.current = navigate; }, [navigate]);
+
   // Handle browser back / forward
   useEffect(() => {
-    const onPopState = () => { void loadRoute(location.pathname); };
+    const onPopState = () => { void loadRoute(location.pathname + location.search); };
     window.addEventListener("popstate", onPopState);
     return () => window.removeEventListener("popstate", onPopState);
   }, [loadRoute]);
@@ -107,7 +212,6 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     return () => { delete w.__BRACTJS_HMR_ACCEPT__; };
   }, [pathname, manifest]);
 
-  // Stub — real implementation in Prompt 2.6
   const submit = useCallback(async (
     _to: string,
     _opts: { method: string; body: FormData | Record<string, string> },

package/src/client/cache.ts

@@ -0,0 +1,69 @@
+// ── LoaderCache ────────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  data: Record<string, unknown>;
+  timestamp: number;
+  staleTime: number;
+  gcTime: number;
+}
+
+class LoaderCache {
+  private store = new Map<string, CacheEntry>();
+  private gcTimer: ReturnType<typeof setInterval> | null = null;
+
+  set(key: string, data: Record<string, unknown>, staleTime: number, gcTime: number): void {
+    this.store.set(key, { data, timestamp: Date.now(), staleTime, gcTime });
+    this.ensureGc();
+  }
+
+  get(key: string): { data: Record<string, unknown>; fresh: boolean } | null {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    const age = Date.now() - entry.timestamp;
+    if (age > entry.gcTime) {
+      this.store.delete(key);
+      return null;
+    }
+    return { data: entry.data, fresh: age < entry.staleTime };
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  entries(): Array<{ key: string; age: number; staleTime: number; gcTime: number }> {
+    const now = Date.now();
+    return Array.from(this.store.entries()).map(([key, entry]) => ({
+      key,
+      age: now - entry.timestamp,
+      staleTime: entry.staleTime,
+      gcTime: entry.gcTime,
+    }));
+  }
+
+  private ensureGc(): void {
+    if (this.gcTimer !== null) return;
+    this.gcTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.store) {
+        if (now - entry.timestamp > entry.gcTime) this.store.delete(key);
+      }
+      if (this.store.size === 0) {
+        clearInterval(this.gcTimer!);
+        this.gcTimer = null;
+      }
+    }, 60_000);
+  }
+}
+
+export const loaderCache = new LoaderCache();
+
+// ── Cache key helpers ──────────────────────────────────────────────────────
+
+/**
+ * Build a cache key from a route pattern and a (sorted) deps array.
+ * Using sorted search ensures `?a=1&b=2` and `?b=2&a=1` hit the same entry.
+ */
+export function cacheKey(pattern: string, deps: unknown[]): string {
+  return pattern + "\0" + JSON.stringify(deps);
+}

package/src/client/components/Link.tsx

@@ -7,12 +7,19 @@ import { prefetchRoute } from "../prefetch.ts";
 interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
   to: string;
   prefetch?: "hover" | "none";
+  /** Opt in to View Transitions API for this navigation (E1). */
+  viewTransition?: boolean;
   children: ReactNode;
 }
 
 // ── Component ──────────────────────────────────────────────────────────────
 
-export function Link({ to, prefetch = "none", children, ...rest }: LinkProps) {
+// Feature-detection at module evaluation so every click doesn't repeat it.
+const supportsViewTransitions =
+  typeof document !== "undefined" &&
+  typeof (document as Document & { startViewTransition?: unknown }).startViewTransition === "function";
+
+export function Link({ to, prefetch = "none", viewTransition = false, children, ...rest }: LinkProps) {
   const navCtx = useContext(NavigationContext);
   const routerCtx = useContext(RouterContext);
   const isLoading = navCtx?.state === "loading";
@@ -21,7 +28,14 @@ export function Link({ to, prefetch = "none", children, ...rest }: LinkProps) {
     if (!navCtx) return; // SSR: let browser handle naturally
     if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
     e.preventDefault();
-    void navCtx.navigate(to);
+
+    if (viewTransition && supportsViewTransitions) {
+      (document as Document & { startViewTransition(cb: () => void): void }).startViewTransition(
+        () => { void navCtx.navigate(to); },
+      );
+    } else {
+      void navCtx.navigate(to);
+    }
   }
 
   function handleMouseEnter() {

package/src/client/components/LiveReload.tsx

@@ -8,6 +8,10 @@ import { hmrClientScript } from "../../dev/hmr-client.ts";
 export function LiveReload(): ReactElement | null {
   if (process.env.NODE_ENV === "production") return null;
 
+  // SECURITY(low): dangerouslySetInnerHTML is safe here — hmrClientScript is a
+  // build-time constant string with no user input. The NODE_ENV gate above
+  // ensures this is never rendered in production. If hmrClientScript ever
+  // accepts dynamic content, audit for XSS.
   return (
     <script
       dangerouslySetInnerHTML={{ __html: hmrClientScript }}

package/src/client/hooks/useBlocker.ts

@@ -0,0 +1,44 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Intercepts browser back/forward and <Link> clicks when `shouldBlock()` returns true.
+ * Shows a native confirm() dialog; the user must confirm to continue navigating.
+ *
+ * Note: The Link component calls NavigationContext.navigate(), which bypasses this
+ * hook's popstate listener.  The hook also patches window.history.pushState so
+ * programmatic navigation (including <Link>) is also intercepted.
+ */
+export function useBlocker(shouldBlock: () => boolean): void {
+  // Keep a stable ref so listeners always call the latest version.
+  const shouldBlockRef = useRef(shouldBlock);
+  useEffect(() => { shouldBlockRef.current = shouldBlock; });
+
+  // Intercept popstate (browser back/forward).
+  useEffect(() => {
+    function onPopState(e: PopStateEvent) {
+      if (!shouldBlockRef.current()) return;
+      // The browser already moved back — push the user back to the current
+      // page before asking, then confirm.
+      e.preventDefault();
+      if (!window.confirm("Leave page? Changes you made may not be saved.")) {
+        // Re-push the current URL so the address bar doesn't change.
+        history.pushState(null, "", window.location.href);
+      }
+    }
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, []);
+
+  // Patch history.pushState so <Link> navigations (which call pushState) are
+  // intercepted. Restore on cleanup.
+  useEffect(() => {
+    const original = history.pushState.bind(history);
+    history.pushState = (state: unknown, title: string, url?: string | URL | null) => {
+      if (shouldBlockRef.current()) {
+        if (!window.confirm("Leave page? Changes you made may not be saved.")) return;
+      }
+      original(state, title, url);
+    };
+    return () => { history.pushState = original; };
+  }, []);
+}

package/src/client/hooks/useFetcher.ts

@@ -16,10 +16,70 @@ interface FetcherResult {
   submit(path: string, opts: SubmitOptions): Promise<void>;
 }
 
+interface StreamFetcherResult<T = unknown> {
+  events: AsyncGenerator<T>;
+  connect(actionId: string): AsyncGenerator<T>;
+}
+
+// ── SSE async generator ────────────────────────────────────────────────────
+
+async function* sseStream<T>(actionId: string): AsyncGenerator<T> {
+  // Send X-BractJS-Action so the server's CSRF gate accepts this same-origin
+  // GET. Cross-origin <script>/<img>/<link rel=prefetch> tags cannot set this
+  // header, so the gate blocks CSRF invocations of server actions.
+  const res = await fetch(`/_stream?id=${encodeURIComponent(actionId)}`, {
+    headers: { "X-BractJS-Action": "1" },
+  });
+  if (!res.ok || !res.body) {
+    throw new Error(`[bractjs] /_stream ${res.status}`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const parts = buf.split("\n\n");
+      buf = parts.pop() ?? "";
+      for (const part of parts) {
+        const lines = part.trim().split("\n");
+        let event = "data";
+        let data = "";
+        for (const line of lines) {
+          if (line.startsWith("event: ")) event = line.slice(7).trim();
+          else if (line.startsWith("data: ")) data = line.slice(6);
+        }
+        if (event === "done") return;
+        if (event === "error") throw new Error((JSON.parse(data) as { message: string }).message);
+        if (event === "data" && data) yield JSON.parse(data) as T;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // ── Hook ───────────────────────────────────────────────────────────────────
 
-export function useFetcher(): FetcherResult {
+export function useFetcher(): FetcherResult;
+export function useFetcher<T>(opts: { stream: true }): StreamFetcherResult<T>;
+export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | StreamFetcherResult<T> {
+  if (opts?.stream) {
+    return {
+      events: (null as unknown) as AsyncGenerator<T>,
+      connect(actionId: string): AsyncGenerator<T> {
+        return sseStream<T>(actionId);
+      },
+    } satisfies StreamFetcherResult<T>;
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   const [data, setData] = useState<unknown>(undefined);
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   const [state, setState] = useState<FetcherState>("idle");
 
   async function load(path: string): Promise<void> {
@@ -33,14 +93,14 @@ export function useFetcher(): FetcherResult {
     }
   }
 
-  async function submit(path: string, opts: SubmitOptions): Promise<void> {
+  async function submit(path: string, submitOpts: SubmitOptions): Promise<void> {
     setState("submitting");
     try {
       const body =
-        opts.body instanceof FormData
-          ? opts.body
-          : new URLSearchParams(opts.body as Record<string, string>);
-      const res = await fetch(path, { method: opts.method, body });
+        submitOpts.body instanceof FormData
+          ? submitOpts.body
+          : new URLSearchParams(submitOpts.body as Record<string, string>);
+      const res = await fetch(path, { method: submitOpts.method, body });
       setData(await res.json());
     } finally {
       setState("idle");