@bractjs/bractjs 0.1.5 → 0.1.7

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");

package/src/client/hooks/useLocale.ts

@@ -0,0 +1,12 @@
+import { useParams } from "./useParams.ts";
+
+/**
+ * Returns the current locale from URL params.
+ * Works when the router is configured with i18n prefix routes (`/:locale/...`).
+ *
+ * Falls back to `defaultLocale` when no locale param is present (e.g. SSR without locale prefix).
+ */
+export function useLocale(defaultLocale = "en"): string {
+  const params = useParams<{ locale?: string }>();
+  return params.locale ?? defaultLocale;
+}

package/src/client/hooks/useLocalizedLink.ts

@@ -0,0 +1,18 @@
+import { useLocale } from "./useLocale.ts";
+
+/**
+ * Returns a helper that prepends the current locale to a path.
+ *
+ * Usage:
+ *   const localizedTo = useLocalizedLink();
+ *   <Link to={localizedTo('/about')} />  // → /en/about
+ */
+export function useLocalizedLink(defaultLocale = "en"): (path: string) => string {
+  const locale = useLocale(defaultLocale);
+  return (path: string) => {
+    // Don't double-prefix if the path already starts with /<locale>.
+    const alreadyPrefixed = path.startsWith(`/${locale}/`) || path === `/${locale}`;
+    if (alreadyPrefixed) return path;
+    return `/${locale}${path.startsWith("/") ? path : "/" + path}`;
+  };
+}

package/src/client/hooks/useSearchParams.ts

@@ -0,0 +1,74 @@
+import { useState, useCallback, useEffect, useRef, startTransition } from "react";
+import { NavigationContext } from "../router.tsx";
+import { useContext } from "react";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+type SetSearchParams = (
+  updater: Record<string, string> | ((prev: URLSearchParams) => URLSearchParams),
+) => void;
+
+export interface SearchParamsResult<T extends Record<string, string>> {
+  searchParams: URLSearchParams;
+  getParam<K extends keyof T & string>(key: K): T[K] | null;
+  setSearchParams: SetSearchParams;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Reads and writes URL search params, typed per-route via generic T.
+ * Triggers a loader re-run (soft-nav fetch) when params change.
+ *
+ * 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> {
+  const navCtx = useContext(NavigationContext);
+
+  function readCurrent(): URLSearchParams {
+    if (typeof window === "undefined") return new URLSearchParams();
+    return new URLSearchParams(window.location.search);
+  }
+
+  const [searchParams, setSearchParamsState] = useState<URLSearchParams>(readCurrent);
+
+  // Track whether we triggered the change ourselves to avoid double re-run.
+  const selfTriggerRef = useRef(false);
+
+  // Sync when the browser's history changes (back/forward, external pushState).
+  useEffect(() => {
+    function onPopState() {
+      setSearchParamsState(new URLSearchParams(window.location.search));
+    }
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, []);
+
+  const setSearchParams: SetSearchParams = useCallback((updater) => {
+    const next =
+      typeof updater === "function"
+        ? updater(new URLSearchParams(window.location.search))
+        : new URLSearchParams(updater);
+
+    const newSearch = next.toString();
+    const newUrl = window.location.pathname + (newSearch ? "?" + newSearch : "") + window.location.hash;
+
+    // Update browser URL without pushing a new history entry if only params changed.
+    history.pushState({}, "", newUrl);
+    selfTriggerRef.current = true;
+    startTransition(() => setSearchParamsState(next));
+
+    // Trigger a loader re-run via the NavigationContext navigate so the full
+    // soft-nav fetch path is exercised (meta update, module swap, etc.).
+    if (navCtx) {
+      void navCtx.navigate(window.location.pathname + (newSearch ? "?" + newSearch : ""));
+    }
+  }, [navCtx]);
+
+  const getParam = useCallback(<K extends keyof T & string>(key: K): T[K] | null => {
+    return (searchParams.get(key) as T[K] | null);
+  }, [searchParams]);
+
+  return { searchParams, getParam, setSearchParams };
+}

package/src/client/rpc.ts

@@ -0,0 +1,70 @@
+// ── createClient ───────────────────────────────────────────────────────────
+
+/**
+ * Creates a fully-typed fetch client for BractJS API routes.
+ *
+ * Usage:
+ *   import type { AppApiRoutes } from 'bractjs';
+ *   const client = createClient<AppApiRoutes>();
+ *   const users = await client['/api/users'].GET();
+ *
+ * The proxy builds the fetch URL from the property access chain and HTTP method,
+ * so `client['/api/users'].GET()` calls `GET /api/users`.
+ *
+ * This is intentionally minimal (no batching, no retries) — add wrapping as needed.
+ */
+
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+
+// Given a union of route definitions (method/path/input/output), extract
+// the output type for a specific method + path pair.
+type RouteOutput<
+  TRoutes extends { method: string; path: string; input: unknown; output: unknown },
+  TMethod extends string,
+  TPath extends string,
+> = Extract<TRoutes, { method: TMethod; path: TPath }>["output"];
+
+type RouteInput<
+  TRoutes extends { method: string; path: string; input: unknown; output: unknown },
+  TMethod extends string,
+  TPath extends string,
+> = Extract<TRoutes, { method: TMethod; path: TPath }>["input"];
+
+type ApiClient<TRoutes extends { method: string; path: string; input: unknown; output: unknown }> = {
+  [TPath in TRoutes["path"]]: {
+    [TMethod in Extract<TRoutes, { path: TPath }>["method"]]: (
+      input?: RouteInput<TRoutes, TMethod, TPath>,
+    ) => Promise<UnwrapPromise<RouteOutput<TRoutes, TMethod, TPath>>>;
+  };
+};
+
+export function createClient<
+  TRoutes extends { method: string; path: string; input: unknown; output: unknown },
+>(baseUrl = ""): ApiClient<TRoutes> {
+  return new Proxy({} as ApiClient<TRoutes>, {
+    get(_target, path: string) {
+      return new Proxy({} as Record<string, unknown>, {
+        get(_t, method: string) {
+          return async (input?: unknown) => {
+            const httpMethod = method.toUpperCase();
+            const url = baseUrl + path;
+            const hasBody = httpMethod !== "GET" && httpMethod !== "DELETE" && input !== undefined;
+            const res = await fetch(url, {
+              method: httpMethod,
+              headers: hasBody ? { "Content-Type": "application/json" } : undefined,
+              body: hasBody ? JSON.stringify(input) : undefined,
+            });
+            if (!res.ok) {
+              const err = await res.json().catch(() => ({ error: res.statusText }));
+              throw Object.assign(new Error((err as { error?: string }).error ?? res.statusText), {
+                status: res.status,
+                response: res,
+              });
+            }
+            return res.json();
+          };
+        },
+      });
+    },
+  });
+}

package/src/codegen/route-codegen.ts

@@ -29,23 +29,44 @@ function substituteParams(pattern: string, params: string[]): string {
   ).join("/");
 }
 
+// Allowed pattern: "/" + (segment | ":ident") (segments are filename-derived).
+// Restricting upfront removes any chance that a hostile filename injects a
+// 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_]*$/;
+
+function assertSafePattern(pattern: string): void {
+  if (!SAFE_PATTERN_RE.test(pattern)) {
+    throw new Error(`[bractjs] codegen: refusing to emit unsafe route pattern: ${JSON.stringify(pattern)}`);
+  }
+}
+function assertSafeParam(name: string): void {
+  if (!SAFE_IDENT_RE.test(name)) {
+    throw new Error(`[bractjs] codegen: refusing to emit unsafe param name: ${JSON.stringify(name)}`);
+  }
+}
+
 function builderEntry(pattern: string, params: string[]): string {
-  if (params.length === 0)
-    return "  \"" + pattern + "\": () => \"" + pattern + "\" as const,";
+  assertSafePattern(pattern);
+  params.forEach(assertSafeParam);
+  const key = JSON.stringify(pattern);
+  if (params.length === 0) return "  " + key + ": () => " + key + " as const,";
   const paramType = params.map((p) => p + ": string").join("; ");
   const body = substituteParams(pattern, params);
-  return "  \"" + pattern + "\": (params: { " + paramType + " }) => `" + body + "` as const,";
+  return "  " + key + ": (params: { " + paramType + " }) => `" + body + "` as const,";
 }
 
 function paramsTypeLines(routes: Array<{ pattern: string; params: string[] }>): string {
   const dynamic = routes.filter((r) => r.params.length > 0);
   if (dynamic.length === 0) return "export type RouteParams<_T extends AppRoutes> = Record<never, never>;";
   const branches = dynamic
-    .map((r) =>
-      "  T extends \"" + r.pattern + "\" ? { "
-      + r.params.map((p) => p + ": string").join("; ")
-      + " } :",
-    )
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      r.params.forEach(assertSafeParam);
+      return "  T extends " + JSON.stringify(r.pattern) + " ? { "
+        + r.params.map((p) => p + ": string").join("; ")
+        + " } :";
+    })
     .join("\n");
   return "export type RouteParams<T extends AppRoutes> =\n" + branches + "\n  Record<never, never>;";
 }
@@ -57,6 +78,61 @@ const HEADER =
   "\n" +
   "/* eslint-disable */\n";
 
+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) + "] :";
+    })
+    .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,
+    "}",
+    "",
+    "export type SearchParams<T extends AppRoutes> =",
+    branches,
+    "  Record<string, string>;",
+  ].join("\n");
+}
+
+function contextTypeLines(routes: Array<{ pattern: string }>): string {
+  if (routes.length === 0) {
+    return "export type Context<_T extends AppRoutes> = Record<string, unknown>;";
+  }
+  const branches = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteContextMap[" + JSON.stringify(r.pattern) + "] :";
+    })
+    .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,
+    "}",
+    "",
+    "export type Context<T extends AppRoutes> =",
+    branches,
+    "  Record<string, unknown>;",
+  ].join("\n");
+}
+
 export async function generateRouteTypes(appDir: string): Promise<string> {
   const routeFiles = await scanRoutes(appDir);
   const routes = routeFiles.map((r) => ({
@@ -65,7 +141,10 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
   }));
 
   const union = routes.length > 0
-    ? routes.map((r) => "  | \"" + r.pattern + "\"").join("\n")
+    ? routes.map((r) => {
+        assertSafePattern(r.pattern);
+        return "  | " + JSON.stringify(r.pattern);
+      }).join("\n")
     : "  never";
 
   const builderEntries = routes.map((r) => builderEntry(r.pattern, r.params)).join("\n");
@@ -77,14 +156,21 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
     "",
     paramsTypeLines(routes),
     "",
+    searchParamsTypeLines(routes),
+    "",
+    contextTypeLines(routes),
+    "",
     "export type TypedLoaderArgs<T extends AppRoutes> = {",
     "  request: Request;",
     "  params: RouteParams<T>;",
-    "  context: Record<string, unknown>;",
+    "  context: Context<T>;",
     "};",
     "export type TypedActionArgs<T extends AppRoutes> =",
     "  TypedLoaderArgs<T> & { formData: FormData };",
     "",
+    "/** A locale-prefixed variant of a route (E2 i18n routing). */",
+    "export type LocalizedRoute<T extends AppRoutes> = `/${string}${T}`;",
+    "",
     "export const routes = {",
     builderEntries,
     "} as const;",

package/src/dev/devtools.ts

@@ -0,0 +1,144 @@
+/**
+ * BractJS DevTools Panel (E3).
+ *
+ * In dev mode this module is imported by the HMR client and registers a
+ * `<bractjs-devtools>` custom element.  The element reads shared state from
+ * `window.__BRACTJS_DEVTOOLS__` which is populated by ClientRouter.
+ *
+ * Ctrl+Shift+B toggles the panel.
+ * Zero production overhead — this file is never imported in production because
+ * it is only loaded via `if (__BRACT_DEV__)` in the HMR client.
+ */
+
+export interface DevtoolsState {
+  route: string | null;
+  loaderData: Record<string, unknown>;
+  navState: string;
+  cacheEntries: Array<{ key: string; age: number; staleTime: number; gcTime: number }>;
+  beforeLoadTrace: string[];
+}
+
+declare global {
+  interface Window {
+    __BRACTJS_DEVTOOLS__?: DevtoolsState;
+  }
+}
+
+const PANEL_ID = "bractjs-devtools-panel";
+
+class BractJSDevtools extends HTMLElement {
+  private open = false;
+  private panel: HTMLDivElement | null = null;
+
+  connectedCallback() {
+    this.style.cssText = "position:fixed;bottom:0;right:0;z-index:2147483647;font-family:monospace;";
+
+    const toggle = document.createElement("button");
+    toggle.textContent = "⚡ BractJS";
+    toggle.style.cssText =
+      "background:#1e1e1e;color:#61dafb;border:none;padding:4px 10px;cursor:pointer;font-size:12px;";
+    toggle.onclick = () => this.togglePanel();
+    this.appendChild(toggle);
+
+    // Keyboard shortcut
+    document.addEventListener("keydown", (e) => {
+      if (e.ctrlKey && e.shiftKey && e.key === "B") {
+        e.preventDefault();
+        this.togglePanel();
+      }
+    });
+  }
+
+  private togglePanel() {
+    if (this.panel) {
+      this.panel.remove();
+      this.panel = null;
+      this.open = false;
+    } else {
+      this.open = true;
+      this.renderPanel();
+    }
+  }
+
+  private renderPanel() {
+    const state = window.__BRACTJS_DEVTOOLS__ ?? {
+      route: null,
+      loaderData: {},
+      navState: "idle",
+      cacheEntries: [],
+      beforeLoadTrace: [],
+    };
+
+    const panel = document.createElement("div");
+    panel.id = PANEL_ID;
+    panel.style.cssText =
+      "background:#1e1e1e;color:#ccc;width:480px;max-height:60vh;overflow:auto;" +
+      "border-top:2px solid #61dafb;border-left:2px solid #61dafb;padding:12px;font-size:11px;";
+
+    const header = document.createElement("div");
+    header.style.cssText = "color:#61dafb;font-weight:bold;margin-bottom:8px;font-size:13px;";
+    header.textContent = "BractJS DevTools";
+    panel.appendChild(header);
+
+    this.section(panel, "Route", state.route ?? "(none)");
+    this.section(panel, "Navigation state", state.navState);
+    this.section(panel, "Loader data", JSON.stringify(state.loaderData, null, 2));
+
+    if (state.cacheEntries.length > 0) {
+      const cacheText = state.cacheEntries
+        .map((e) => `${e.key}\n  age=${e.age}ms stale=${e.staleTime}ms gc=${e.gcTime}ms`)
+        .join("\n");
+      this.section(panel, `Cache (${state.cacheEntries.length})`, cacheText);
+    }
+
+    if (state.beforeLoadTrace.length > 0) {
+      this.section(panel, "beforeLoad trace", state.beforeLoadTrace.join("\n"));
+    }
+
+    this.panel = panel;
+    this.appendChild(panel);
+
+    // Auto-refresh every second while open.
+    const timer = setInterval(() => {
+      if (!this.open) { clearInterval(timer); return; }
+      panel.remove();
+      this.panel = null;
+      this.renderPanel();
+    }, 1000);
+  }
+
+  private section(parent: HTMLElement, title: string, content: string) {
+    const h = document.createElement("div");
+    h.style.cssText = "color:#61dafb;margin-top:8px;margin-bottom:2px;";
+    h.textContent = title;
+    parent.appendChild(h);
+
+    const pre = document.createElement("pre");
+    pre.style.cssText = "margin:0;white-space:pre-wrap;word-break:break-all;color:#ccc;";
+    pre.textContent = content;
+    parent.appendChild(pre);
+  }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("bractjs-devtools")) {
+  customElements.define("bractjs-devtools", BractJSDevtools);
+}
+
+/**
+ * Inject the `<bractjs-devtools>` element into the document body.
+ * Called by the HMR client in dev mode.
+ */
+export function injectDevtools(): void {
+  if (typeof document === "undefined") return;
+  if (document.querySelector("bractjs-devtools")) return;
+  const el = document.createElement("bractjs-devtools");
+  document.body.appendChild(el);
+}
+
+/**
+ * Update the shared devtools state object.
+ * Called by ClientRouter on every navigation.
+ */
+export function updateDevtoolsState(state: Partial<DevtoolsState>): void {
+  window.__BRACTJS_DEVTOOLS__ = { ...window.__BRACTJS_DEVTOOLS__, ...state } as DevtoolsState;
+}

package/src/dev/hmr-client.ts

@@ -13,6 +13,15 @@
  */
 export const hmrClientScript: string = `
 (function () {
+  // Inject DevTools panel in dev mode (E3).
+  if (typeof customElements !== 'undefined') {
+    import('/_bractjs/devtools.js').then(function(m) {
+      if (typeof m.injectDevtools === 'function') m.injectDevtools();
+    }).catch(function() {
+      // DevTools module not available — skip silently.
+    });
+  }
+
   function connect() {
     var ws = new WebSocket("ws://localhost:3001");
     ws.onmessage = function (event) {
@@ -21,6 +30,11 @@ export const hmrClientScript: string = `
         if (msg.type === "hmr:reload") {
           location.reload();
         } else if (msg.type === "hmr:route" && msg.pattern != null && msg.chunkUrl) {
+          // Validate chunk URL is a same-origin relative path before importing.
+          // Prevents a compromised/MITM'd dev WS from executing arbitrary URLs.
+          if (typeof msg.chunkUrl !== 'string' || !/^\/build\//.test(msg.chunkUrl)) {
+            return;
+          }
           // Cache-bust so the browser re-fetches the rebuilt chunk.
           // The chunk was built with splitting, so it shares the same React
           // instance as client.js — no dual-React issue.