npm - @bractjs/bractjs - Versions diffs - 0.2.0 → 0.2.1 - Mend

@bractjs/bractjs 0.2.0 → 0.2.1

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

Files changed (15) hide show

package/README.md +41 -4
package/package.json +8 -8
package/src/__tests__/fixtures/app/routes/redirect-loader.tsx +13 -0
package/src/__tests__/integration.test.ts +18 -0
package/src/client/components/Form.tsx +5 -1
package/src/client/components/Image.tsx +4 -2
package/src/client/components/Toaster.tsx +117 -0
package/src/client/hooks/useToast.ts +12 -0
package/src/client/toast-store.ts +132 -0
package/src/index.ts +5 -0
package/src/server/adapter.ts +7 -1
package/src/server/request-handler.ts +6 -1
package/src/server/serve.ts +17 -1
package/types/index.d.ts +62 -2
package/LICENSE +0 -21

package/README.md CHANGED Viewed

@@ -26,7 +26,7 @@ This README is a **step-by-step guide to every function and feature** BractJS ex
 7. [Per-route context: `defineContext`](#7-per-route-context-definecontext)
 8. [Streaming data: `defer`, `Deferred`, `isDeferred`, `<Await>`](#8-streaming-data)
 9. [Client hooks](#9-client-hooks)
-10. [Client components: `<Outlet>`, `<Link>`, `<Form>`, `<Scripts>`, `<LiveReload>`, `<Image>`](#10-client-components)
+10. [Client components: `<Outlet>`, `<Link>`, `<Form>`, `<Scripts>`, `<LiveReload>`, `<Image>`, `<Toaster>`](#10-client-components)
 11. [Server Actions (`"use server"`) & client-only (`"use client"`)](#11-server-actions--client-components)
 12. [Typed API routes: `route` + `createClient`](#12-typed-api-routes)
 13. [Input validation: `validate`](#13-input-validation-validate)
@@ -564,6 +564,30 @@ Prompt before leaving when there are unsaved changes (intercepts back/forward an
 useBlocker(() => formIsDirty);
 ```
+### `useToast()` → `toast` and `useToasts()` → `ToastEntry[]`
+Flash status feedback ("Saved", "Delete completed", …) from anywhere. `useToast()` returns the stable `toast` API; you can also import `toast` directly to fire from non-React code (event handlers, fetcher callbacks). Render a single [`<Toaster />`](#10-client-components) in `root.tsx`. `useToasts()` exposes the live queue if you want to build a custom renderer.
+```ts
+import { toast, useToast } from "@bractjs/bractjs";
+toast.success("Saved successfully");
+toast.error("Delete failed", { description: "Try again." });
+toast.info("Heads up");           // also: .warning, .loading
+toast.dismiss(id);                // or toast.dismiss() to clear all
+// Wrap an async action: loading → success / error
+await toast.promise(savePost(data), {
+  loading: "Saving…",
+  success: "Saved successfully",
+  error: (e) => `Save failed: ${e}`,
+});
+// Optional action button (e.g. undo) + custom auto-dismiss
+toast.success("Delete completed", {
+  duration: 6000,                 // ms; Infinity/0 = sticky
+  action: { label: "Undo", onClick: () => restore(id) },
+});
+```
 ### `useLocale(defaultLocale?)` → `string` and `useLocalizedLink(defaultLocale?)` → `(path) => string`
 For i18n prefix routing (§19).
 ```ts
@@ -632,6 +656,17 @@ Markers used inside `root.tsx` (§3). `<Scripts />` is where the client bundle +
 ### `<Image />`
 Responsive, format-converted images via the built-in `/_image` endpoint — see §20.
+### `<Toaster position? gap? renderToast?>`
+Renders the toast queue fired by [`toast` / `useToast()`](#9-client-hooks). Mount it **once** in `app/root.tsx`, next to `<Scripts />`. Self-contained inline styles (no CSS import, CSP-safe — no injected `<style>`/nonce).
+```tsx
+<body>
+  <Outlet />
+  <Toaster position="top-right" />   {/* top|bottom + left|center|right */}
+  <Scripts />
+</body>
+```
+Style hooks: target `[data-bract-toaster]` / `[data-bract-toast="success|error|…"]` with your own CSS, or pass `renderToast={(t, dismiss) => <YourCard …/>}` to fully replace the card.
 ---
 ## 11. Server Actions & Client Components
@@ -1353,9 +1388,11 @@ Everything importable from `@bractjs/bractjs` ([packages/core/src/index.ts](pack
 **Sessions:** `createCookieSession`
-**Components:** `Outlet`, `Link`, `Form`, `Scripts`, `LiveReload`, `Await`, `Image`, `ScrollRestoration`
+**Components:** `Outlet`, `Link`, `Form`, `Scripts`, `LiveReload`, `Await`, `Image`, `ScrollRestoration`, `Toaster`
+**Hooks:** `useLoaderData`, `useActionData`, `useLocation`, `useParams`, `useMatches`, `useNavigation`, `useNavigate`, `useFetcher`, `useFetchers`, `useRevalidator`, `useSearch`, `useSetSearch`, `useSearchParams`, `useBlocker`, `useToast`, `useToasts`, `useLocale`, `useLocalizedLink`
-**Hooks:** `useLoaderData`, `useActionData`, `useLocation`, `useParams`, `useMatches`, `useNavigation`, `useNavigate`, `useFetcher`, `useFetchers`, `useRevalidator`, `useSearch`, `useSetSearch`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
+**Toasts:** `toast`, `toastStore`
 **Search serialization:** `serializeSearch`
@@ -1371,7 +1408,7 @@ Everything importable from `@bractjs/bractjs` ([packages/core/src/index.ts](pack
 **Adapters:** `createCloudflareAdapter`, `makeCloudflareHandler`
-**Types:** `LoaderArgs`, `ActionArgs`, `MetaArgs`, `MetaDescriptor`, `LoaderFunction`, `ActionFunction`, `MetaFunction`, `RouteModule`, `RouteDefinition`, `RouteFile`, `Segment`, `RouterLocation`, `ShouldRevalidateArgs`, `ShouldRevalidateFunction`, `BractJSConfig`, `RenderOptions`, `ServerManifest`, `ContextFactory`, `ApiRouteDefinition`, `ApiRouteOptions`, `AppApiRoutes`, `FieldErrors`, `ValidationError`, `BractAdapter`, `LifecycleHooks`, `MiddlewareFn`, `MiddlewareContext`, `CorsOptions`, `AuthGuardOptions`, `CspOptions`, `SessionStorageLike`, `SessionLike`, `Session`, `SessionStorage`, `SessionData`, `CookieSessionOptions`, `CommitOptions`, `ImageProps`, `ImageFormat`, `ImageFit`, `SearchParamsResult`, `SetSearchFn`, `SetSearchOptions`, `SearchOutputFor`, `InferSchemaOutput`, `LoaderData`, `ActionData`, `SafeValidateResult`, `FetcherResult`, `FetcherEntry`, `FetcherState`, `FetcherFormProps`, `UseFetcherOptions`, `Revalidator`, `ScrollRestorationProps`, `PrerenderOptions`, `PrerenderResult`, `I18nConfig`, `DevServerOptions`, `DevServer`, `BuildConfig`, `CodegenResult`, `ModuleRegistry`, `BractJSContextValue`, `RouteManifest`
+**Types:** `LoaderArgs`, `ActionArgs`, `MetaArgs`, `MetaDescriptor`, `LoaderFunction`, `ActionFunction`, `MetaFunction`, `RouteModule`, `RouteDefinition`, `RouteFile`, `Segment`, `RouterLocation`, `ShouldRevalidateArgs`, `ShouldRevalidateFunction`, `BractJSConfig`, `RenderOptions`, `ServerManifest`, `ContextFactory`, `ApiRouteDefinition`, `ApiRouteOptions`, `AppApiRoutes`, `FieldErrors`, `ValidationError`, `BractAdapter`, `LifecycleHooks`, `MiddlewareFn`, `MiddlewareContext`, `CorsOptions`, `AuthGuardOptions`, `CspOptions`, `SessionStorageLike`, `SessionLike`, `Session`, `SessionStorage`, `SessionData`, `CookieSessionOptions`, `CommitOptions`, `ImageProps`, `ImageFormat`, `ImageFit`, `SearchParamsResult`, `SetSearchFn`, `SetSearchOptions`, `SearchOutputFor`, `InferSchemaOutput`, `LoaderData`, `ActionData`, `SafeValidateResult`, `FetcherResult`, `FetcherEntry`, `FetcherState`, `FetcherFormProps`, `UseFetcherOptions`, `Revalidator`, `ScrollRestorationProps`, `ToasterProps`, `ToastPosition`, `Toast`, `ToastEntry`, `ToastOptions`, `ToastType`, `ToastAction`, `PrerenderOptions`, `PrerenderResult`, `I18nConfig`, `DevServerOptions`, `DevServer`, `BuildConfig`, `CodegenResult`, `ModuleRegistry`, `BractJSContextValue`, `RouteManifest`
 ---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",
@@ -42,6 +42,12 @@
       "default": "./src/index.ts"
     }
   },
+  "scripts": {
+    "dev": "bun run src/dev/server.ts",
+    "build": "bun run src/build/bundler.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
   "peerDependencies": {
     "react": "^19",
     "react-dom": "^19"
@@ -52,11 +58,5 @@
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
-  },
-  "scripts": {
-    "dev": "bun run src/dev/server.ts",
-    "build": "bun run src/build/bundler.ts",
-    "test": "bun test",
-    "typecheck": "bunx tsc --noEmit"
   }
-}
+}

package/src/__tests__/fixtures/app/routes/redirect-loader.tsx ADDED Viewed

@@ -0,0 +1,13 @@
+// Fixture for the "/_data must surface a redirect THROWN from a loader" test.
+// Auth gates like requireAdmin() do `throw redirect("/login")` inside a loader.
+// On the /_data soft-nav path that thrown redirect must come back as a real 3xx
+// (so the client follows it), not escape to the top-level handler as a 500.
+import { redirect } from "../../../../server/response.ts";
+export function loader(): never {
+  throw redirect("/login");
+}
+export default function RedirectLoaderPage() {
+  return <p>redirect loader page</p>;
+}

package/src/__tests__/integration.test.ts CHANGED Viewed

@@ -183,6 +183,24 @@ test("/_data of a beforeLoad-gated route is blocked and never leaks loader data"
   expect(body).not.toContain("TOP-SECRET-LOADER-DATA");
 });
+// Regression: a redirect THROWN from a loader (the requireAdmin/auth-gate
+// pattern) must come back from /_data as a real 3xx, not a 500. The /_data
+// handler wraps loaders in `return await runRouteMiddleware(...)`; a bare
+// `return` would let the rejection escape its try/catch (which handles
+// isRedirect) to the top-level handler, which logs "unhandled request error"
+// and returns 500 — breaking soft-nav redirects for gated routes.
+test("full-page GET of a loader that throws redirect returns the 3xx", async () => {
+  const res = await fetch(`${BASE}/redirect-loader`, { redirect: "manual" });
+  expect(res.status).toBe(302);
+  expect(res.headers.get("location")).toBe("/login");
+});
+test("/_data of a loader that throws redirect returns the 3xx (not 500)", async () => {
+  const res = await fetch(`${BASE}/_data?path=/redirect-loader`, { redirect: "manual" });
+  expect(res.status).toBe(302);
+  expect(res.headers.get("location")).toBe("/login");
+});
 // ── Route headers / useMatches / nested middleware (Phases 1, 2, 4) ──────────
 test("route `headers` export sets Cache-Control on the document response", async () => {

package/src/client/components/Form.tsx CHANGED Viewed

@@ -56,8 +56,12 @@ export function Form({ method = "post", action, intent, children, ...rest }: For
     await submit(url, { method, body: new FormData(target) });
   }
+  // Render `action` here too (SSR sets it on line 34): handleSubmit preventDefaults
+  // so it's never used for a native submit, but keeping it on the element makes
+  // the client markup match the server's and avoids a hydration mismatch for any
+  // <Form action="…"> (e.g. a logout form posting to a different route).
   return (
-    <form method={method} onSubmit={(e) => { void handleSubmit(e); }} {...rest}>
+    <form method={method} action={action} onSubmit={(e) => { void handleSubmit(e); }} {...rest}>
       {intentInput}
       {children}
     </form>

package/src/client/components/Image.tsx CHANGED Viewed

@@ -69,8 +69,10 @@ export function Image({
       height={height}
       loading={priority ? "eager" : "lazy"}
       decoding={priority ? "sync" : "async"}
-      // @ts-expect-error — fetchpriority is a valid HTML attribute in React 19
-      fetchpriority={priority ? "high" : "auto"}
+      // React 19 prop is camelCase `fetchPriority`; React emits the lowercase
+      // `fetchpriority` HTML attribute. Using the lowercase prop here triggers
+      // "Invalid DOM property `fetchpriority`" at hydration.
+      fetchPriority={priority ? "high" : "auto"}
       sizes={sizes}
       className={className}
       style={style}

package/src/client/components/Toaster.tsx ADDED Viewed

@@ -0,0 +1,117 @@
+import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import { useToasts } from "../hooks/useToast.ts";
+import { toast } from "../toast-store.ts";
+import type { ToastEntry, ToastType } from "../toast-store.ts";
+export type ToastPosition =
+  | "top-left" | "top-center" | "top-right"
+  | "bottom-left" | "bottom-center" | "bottom-right";
+export interface ToasterProps {
+  position?: ToastPosition;
+  /** Gap between stacked toasts, px. */
+  gap?: number;
+  /** Custom renderer — receives the entry and a dismiss callback. Falls back to the default card. */
+  renderToast?: (toast: ToastEntry, dismiss: () => void) => ReactNode;
+}
+const ACCENT: Record<ToastType, string> = {
+  success: "#16a34a", error: "#dc2626", warning: "#d97706", info: "#2563eb", loading: "#6b7280",
+};
+const ICON: Record<ToastType, string> = {
+  success: "✓", error: "✕", warning: "!", info: "i", loading: "↻",
+};
+function isTop(p: ToastPosition) { return p.startsWith("top"); }
+function containerStyle(position: ToastPosition, gap: number): CSSProperties {
+  const [, x] = position.split("-");
+  return {
+    position: "fixed", zIndex: 9999, display: "flex", flexDirection: "column", gap,
+    pointerEvents: "none", maxWidth: "calc(100vw - 32px)", width: 380,
+    top: isTop(position) ? 16 : undefined, bottom: isTop(position) ? undefined : 16,
+    left: x === "left" ? 16 : x === "center" ? "50%" : undefined,
+    right: x === "right" ? 16 : undefined,
+    transform: x === "center" ? "translateX(-50%)" : undefined,
+  };
+}
+function ToastCard({ entry, top }: { entry: ToastEntry; top: boolean }) {
+  const [shown, setShown] = useState(false);
+  useEffect(() => { const r = requestAnimationFrame(() => setShown(true)); return () => cancelAnimationFrame(r); }, []);
+  const dismiss = () => toast.dismiss(entry.id);
+  return (
+    <div
+      role={entry.type === "error" ? "alert" : "status"}
+      aria-live={entry.type === "error" ? "assertive" : "polite"}
+      data-bract-toast={entry.type}
+      style={{
+        pointerEvents: "auto", display: "flex", alignItems: "flex-start", gap: 12,
+        padding: "12px 14px", borderRadius: 10, background: "#fff", color: "#111",
+        border: "1px solid rgba(0,0,0,0.08)", borderLeft: `4px solid ${ACCENT[entry.type]}`,
+        boxShadow: "0 6px 24px rgba(0,0,0,0.12)", fontSize: 14, lineHeight: 1.4,
+        transition: "opacity .22s ease, transform .22s ease",
+        opacity: shown ? 1 : 0,
+        transform: shown ? "translateY(0)" : `translateY(${top ? -8 : 8}px)`,
+      }}
+    >
+      <span
+        aria-hidden
+        style={{
+          flex: "0 0 auto", width: 20, height: 20, borderRadius: "50%", color: "#fff",
+          background: ACCENT[entry.type], display: "grid", placeItems: "center",
+          fontSize: 12, fontWeight: 700, marginTop: 1,
+        }}
+      >
+        {ICON[entry.type]}
+      </span>
+      <div style={{ flex: 1, minWidth: 0 }}>
+        <div style={{ fontWeight: 600, wordBreak: "break-word" }}>{entry.message}</div>
+        {entry.description ? (
+          <div style={{ marginTop: 2, color: "#555", fontWeight: 400 }}>{entry.description}</div>
+        ) : null}
+        {entry.action ? (
+          <button
+            type="button"
+            onClick={() => { entry.action!.onClick(); dismiss(); }}
+            style={{
+              marginTop: 8, padding: "4px 10px", fontSize: 13, fontWeight: 600, cursor: "pointer",
+              color: ACCENT[entry.type], background: "transparent",
+              border: `1px solid ${ACCENT[entry.type]}`, borderRadius: 6,
+            }}
+          >
+            {entry.action.label}
+          </button>
+        ) : null}
+      </div>
+      <button
+        type="button" aria-label="Dismiss" onClick={dismiss}
+        style={{
+          flex: "0 0 auto", border: "none", background: "transparent", cursor: "pointer",
+          color: "#888", fontSize: 16, lineHeight: 1, padding: 0,
+        }}
+      >
+        ×
+      </button>
+    </div>
+  );
+}
+/**
+ * Renders the active toast queue. Mount once in root.tsx, then call `toast.*`
+ * (or `useToast()`) anywhere — e.g. after a save/delete action resolves.
+ */
+export function Toaster({ position = "top-right", gap = 10, renderToast }: ToasterProps): ReactNode {
+  const toasts = useToasts();
+  if (toasts.length === 0) return null;
+  const ordered = isTop(position) ? toasts : [...toasts].reverse();
+  return (
+    <div data-bract-toaster={position} style={containerStyle(position, gap)}>
+      {ordered.map((entry) =>
+        renderToast
+          ? <div key={entry.id} style={{ pointerEvents: "auto" }}>{renderToast(entry, () => toast.dismiss(entry.id))}</div>
+          : <ToastCard key={entry.id} entry={entry} top={isTop(position)} />,
+      )}
+    </div>
+  );
+}

package/src/client/hooks/useToast.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { useSyncExternalStore } from "react";
+import { toast, toastStore, EMPTY_TOASTS, type Toast, type ToastEntry } from "../toast-store.ts";
+/** The stable `toast` API — `toast.success(...)`, `toast.error(...)`, `toast.promise(...)`. */
+export function useToast(): Toast {
+  return toast;
+}
+/** Reactive list of active toasts. <Toaster> uses this; expose it to build a custom renderer. */
+export function useToasts(): ToastEntry[] {
+  return useSyncExternalStore(toastStore.subscribe, toastStore.getSnapshot, () => EMPTY_TOASTS);
+}

package/src/client/toast-store.ts ADDED Viewed

@@ -0,0 +1,132 @@
+// Module-level toast state, shaped for React's useSyncExternalStore (mirrors
+// fetcher-store.ts). Living outside component state means `toast()` is callable
+// from anywhere — event handlers, fetcher callbacks, non-React code — and every
+// <Toaster> in the tree observes the same queue.
+export type ToastType = "success" | "error" | "info" | "warning" | "loading";
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+export interface ToastEntry {
+  id: string;
+  type: ToastType;
+  message: string;
+  description?: string;
+  /** ms before auto-dismiss; `Infinity`/`0` keeps it until dismissed. */
+  duration: number;
+  action?: ToastAction;
+  createdAt: number;
+}
+export interface ToastOptions {
+  /** Reuse an id to update an existing toast in place (e.g. loading → success). */
+  id?: string;
+  type?: ToastType;
+  description?: string;
+  duration?: number;
+  action?: ToastAction;
+}
+type Listener = () => void;
+const DEFAULT_DURATION = 4000;
+class ToastStore {
+  private entries = new Map<string, ToastEntry>();
+  private timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private listeners = new Set<Listener>();
+  // Stable reference between emits or useSyncExternalStore loops.
+  private snapshot: ToastEntry[] = [];
+  private seq = 0;
+  add(message: string, opts: ToastOptions = {}): string {
+    const id = opts.id ?? `bract-toast-${++this.seq}`;
+    const type = opts.type ?? "info";
+    const duration = opts.duration ?? (type === "loading" ? Infinity : DEFAULT_DURATION);
+    this.clearTimer(id);
+    const prev = this.entries.get(id);
+    this.entries.set(id, {
+      id, type, message, description: opts.description, duration,
+      action: opts.action, createdAt: prev?.createdAt ?? Date.now(),
+    });
+    this.schedule(id, duration);
+    this.emit();
+    return id;
+  }
+  dismiss(id: string): void {
+    this.clearTimer(id);
+    if (this.entries.delete(id)) this.emit();
+  }
+  clear(): void {
+    for (const id of [...this.timers.keys()]) this.clearTimer(id);
+    if (this.entries.size) { this.entries.clear(); this.emit(); }
+  }
+  private schedule(id: string, duration: number): void {
+    if (!Number.isFinite(duration) || duration <= 0) return;
+    this.timers.set(id, setTimeout(() => this.dismiss(id), duration));
+  }
+  private clearTimer(id: string): void {
+    const t = this.timers.get(id);
+    if (t !== undefined) { clearTimeout(t); this.timers.delete(id); }
+  }
+  subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  };
+  getSnapshot = (): ToastEntry[] => this.snapshot;
+  private emit(): void {
+    this.snapshot = Array.from(this.entries.values());
+    for (const listener of this.listeners) listener();
+  }
+}
+export const toastStore = new ToastStore();
+/** Stable server snapshot — SSR renders with no toasts. */
+export const EMPTY_TOASTS: ToastEntry[] = [];
+type Msg<T> = string | ((value: T) => string);
+const resolve = <T,>(m: Msg<T>, v: T): string => (typeof m === "function" ? m(v) : m);
+const typed = (type: ToastType) =>
+  (message: string, opts?: Omit<ToastOptions, "type">): string => toastStore.add(message, { ...opts, type });
+/**
+ * Fire a toast from anywhere. Use the typed helpers for status feedback:
+ *   toast.success("Saved"); toast.error("Delete failed");
+ * `toast.promise` shows loading → success/error around an async action.
+ */
+export const toast = Object.assign(
+  (message: string, opts?: ToastOptions): string => toastStore.add(message, opts),
+  {
+    success: typed("success"),
+    error: typed("error"),
+    info: typed("info"),
+    warning: typed("warning"),
+    loading: typed("loading"),
+    /** Dismiss one toast by id, or all toasts when called with no id. */
+    dismiss: (id?: string): void => (id ? toastStore.dismiss(id) : toastStore.clear()),
+    promise<T>(
+      promise: Promise<T>,
+      msgs: { loading: string; success: Msg<T>; error: Msg<unknown> },
+      opts?: Omit<ToastOptions, "type" | "id">,
+    ): Promise<T> {
+      const id = toastStore.add(msgs.loading, { ...opts, type: "loading" });
+      promise.then(
+        (value) => toastStore.add(resolve(msgs.success, value), { ...opts, id, type: "success" }),
+        (err) => toastStore.add(resolve(msgs.error, err), { ...opts, id, type: "error" }),
+      );
+      return promise;
+    },
+  },
+);
+export type Toast = typeof toast;

package/src/index.ts CHANGED Viewed

@@ -119,6 +119,8 @@ export { Image } from "./client/components/Image.tsx";
 export type { ImageProps, ImageFormat, ImageFit } from "./client/components/Image.tsx";
 export { ScrollRestoration } from "./client/components/ScrollRestoration.tsx";
 export type { ScrollRestorationProps } from "./client/components/ScrollRestoration.tsx";
+export { Toaster } from "./client/components/Toaster.tsx";
+export type { ToasterProps, ToastPosition } from "./client/components/Toaster.tsx";
 // Client hooks
 export { useLoaderData } from "./client/hooks/useLoaderData.ts";
@@ -140,6 +142,9 @@ export type { SearchParamsResult } from "./client/hooks/useSearchParams.ts";
 export { useSearch, useSetSearch } from "./client/hooks/useSearch.ts";
 export type { SetSearchFn, SetSearchOptions } from "./client/hooks/useSearch.ts";
 export { serializeSearch } from "./client/search-serializer.ts";
+export { useToast, useToasts } from "./client/hooks/useToast.ts";
+export { toast, toastStore } from "./client/toast-store.ts";
+export type { Toast, ToastEntry, ToastOptions, ToastType, ToastAction } from "./client/toast-store.ts";
 export { useBlocker } from "./client/hooks/useBlocker.ts";
 export { useLocale } from "./client/hooks/useLocale.ts";
 export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";

package/src/server/adapter.ts CHANGED Viewed

@@ -1,3 +1,5 @@
+import { isExplicitDev } from "./env.ts";
 // ── BractAdapter ──────────────────────────────────────────────────────────
 /**
@@ -59,7 +61,11 @@ export class BunAdapter implements BractAdapter {
       fetch: handler,
       error(err: Error) {
         console.error("[bractjs] unhandled server error:", err);
-        return new Response(JSON.stringify({ error: err.message }), {
+        // SECURITY(high): never leak internal error details in production. This
+        // is a last-resort backstop (buildFetchHandler already catches request
+        // errors) — mirror the isExplicitDev() gating used on every other path.
+        const message = isExplicitDev() ? err.message : "Internal Server Error";
+        return new Response(JSON.stringify({ error: message }), {
           status: 500,
           headers: { "Content-Type": "application/json; charset=utf-8" },
         });

package/src/server/request-handler.ts CHANGED Viewed

@@ -101,7 +101,12 @@ async function route(
       // and leak loader data. Run the route middleware chain around the work,
       // sharing the same mutable `context` so a gate can set/clear fields.
       const mwCtx: MiddlewareContext = { request: loaderRequest, params: match.params, context };
-      return runRouteMiddleware(collectRouteMiddleware(chain), mwCtx, async () => {
+      // `return await` (not bare `return`): a loader/gate inside the middleware
+      // work can throw a redirect (e.g. requireAdmin). Without awaiting here the
+      // returned promise rejects *after* this try block, so the catch below never
+      // runs isRedirect() and the redirect escapes to the top-level handler as a
+      // 500 instead of being returned as a 302 for the soft-nav client.
+      return await runRouteMiddleware(collectRouteMiddleware(chain), mwCtx, async () => {
         const routeContext = await runRouteContext(
           chain.route as Parameters<typeof runRouteContext>[0],
           loaderRequest,

package/src/server/serve.ts CHANGED Viewed

@@ -13,6 +13,7 @@ import { handleActionRequest } from "./action-handler.ts";
 import { BunAdapter, type BractAdapter } from "./adapter.ts";
 import type { ModuleRegistry } from "./layout.ts";
 import { resolve, join } from "node:path";
+import { error } from "./response.ts";
 import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 import { installUseClientServerStub } from "./use-client-runtime.ts";
@@ -310,7 +311,22 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     // only SSR documents. The per-route (nested) middleware chain still runs
     // inside handleRequest for SSR/_data, sharing this same `context` object.
     const ctx: MiddlewareContext = { request, params: {}, context: {} };
-    return pipeline.run(ctx, () => dispatch(request, ctx.context));
+    // SECURITY(high): adapter-agnostic catch-all. An uncaught throw from a
+    // global middleware or from dispatch itself (e.g. resolveRouteChain at
+    // import time) would otherwise reach the adapter's error handler — which on
+    // Bun leaks err.message and on Cloudflare/custom adapters isn't handled at
+    // all. Log, fire onError (so observability still sees it), and return a
+    // generic 500 with the message gated to dev — matching every other path.
+    try {
+      return await pipeline.run(ctx, () => dispatch(request, ctx.context));
+    } catch (err) {
+      console.error("[bract] unhandled request error:", err);
+      await fireOnError(onError, err, request);
+      return error(
+        isExplicitDev() ? (err instanceof Error ? err.message : String(err)) : "Internal Server Error",
+        500,
+      );
+    }
   };
 }

package/types/index.d.ts CHANGED Viewed

@@ -4,11 +4,12 @@ import type { ReactNode, Context, CSSProperties } from "react";
 export type {
   LoaderArgs, ActionArgs, MetaDescriptor, MetaArgs,
   LoaderFunction, ActionFunction, MetaFunction, RouteModule,
-  RouteFile, Segment, RouterLocation,
+  RouteFile, Segment, RouterLocation, RouteMatch,
   ShouldRevalidateArgs, ShouldRevalidateFunction,
+  HeadersFunction, HeadersArgs,
   LoaderData, ActionData,
 } from "./route.d.ts";
-import type { RouterLocation, LoaderData, ActionData, ActionArgs } from "./route.d.ts";
+import type { RouterLocation, LoaderData, ActionData, ActionArgs, RouteMatch } from "./route.d.ts";
 // ── Config + Server ───────────────────────────────────────────────────────
 export type { BractJSConfig, ServerManifest, BuildConfig } from "./config.d.ts";
@@ -259,6 +260,50 @@ export interface ScrollRestorationProps {
 /** Restores scroll on back/forward, scrolls to top (or `#hash`) on new navigations. Render once in root.tsx. */
 export declare function ScrollRestoration(props?: ScrollRestorationProps): null;
+export type ToastType = "success" | "error" | "info" | "warning" | "loading";
+export interface ToastAction { label: string; onClick: () => void }
+export interface ToastEntry {
+  id: string;
+  type: ToastType;
+  message: string;
+  description?: string;
+  duration: number;
+  action?: ToastAction;
+  createdAt: number;
+}
+export interface ToastOptions {
+  id?: string;
+  type?: ToastType;
+  description?: string;
+  duration?: number;
+  action?: ToastAction;
+}
+type ToastMsg<T> = string | ((value: T) => string);
+export interface Toast {
+  (message: string, opts?: ToastOptions): string;
+  success(message: string, opts?: Omit<ToastOptions, "type">): string;
+  error(message: string, opts?: Omit<ToastOptions, "type">): string;
+  info(message: string, opts?: Omit<ToastOptions, "type">): string;
+  warning(message: string, opts?: Omit<ToastOptions, "type">): string;
+  loading(message: string, opts?: Omit<ToastOptions, "type">): string;
+  dismiss(id?: string): void;
+  promise<T>(
+    promise: Promise<T>,
+    msgs: { loading: string; success: ToastMsg<T>; error: ToastMsg<unknown> },
+    opts?: Omit<ToastOptions, "type" | "id">,
+  ): Promise<T>;
+}
+export type ToastPosition =
+  | "top-left" | "top-center" | "top-right"
+  | "bottom-left" | "bottom-center" | "bottom-right";
+export interface ToasterProps {
+  position?: ToastPosition;
+  gap?: number;
+  renderToast?: (toast: ToastEntry, dismiss: () => void) => ReactNode;
+}
+/** Renders the active toast queue. Mount once in root.tsx, then call `toast.*` anywhere. */
+export declare function Toaster(props?: ToasterProps): ReactNode;
 export interface FormProps { method?: "post" | "put" | "delete"; action?: string; /** Renders a hidden `intent` input (pairs with defineActions()). */ intent?: string; children?: ReactNode; [key: string]: unknown; }
 export declare function Form(props: FormProps): ReactNode;
@@ -294,6 +339,8 @@ export declare function useLoaderData<T = unknown>(): LoaderData<T>;
 export declare function useActionData<T = unknown>(): ActionData<T> | null;
 /** The current location — reactive on the client, request-derived during SSR. */
 export declare function useLocation(): RouterLocation;
+/** The matched route chain (root → layouts → route); each entry has `{ id, pathname, params, data, handle }`. */
+export declare function useMatches(): RouteMatch[];
 export declare function useParams<TTo extends string>(): ParamsFor<TTo>;
 export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
 export type NavigationState = "idle" | "loading" | "submitting";
@@ -393,6 +440,19 @@ export interface ContextFactory<T> {
 // ── beforeLoad / useBlocker ───────────────────────────────────────────────
 export declare function useBlocker(shouldBlock: () => boolean): void;
+// ── Toasts ────────────────────────────────────────────────────────────────
+/** The stable `toast` API — call from anywhere to flash status feedback. */
+export declare const toast: Toast;
+export declare const toastStore: {
+  add(message: string, opts?: ToastOptions): string;
+  dismiss(id: string): void;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): ToastEntry[];
+};
+export declare function useToast(): Toast;
+export declare function useToasts(): ToastEntry[];
 // ── i18n routing (E2) ────────────────────────────────────────────────────
 export declare function useLocale(defaultLocale?: string): string;
 export declare function useLocalizedLink(defaultLocale?: string): (path: string) => string;

package/LICENSE DELETED Viewed

@@ -1,21 +0,0 @@
-MIT License
-Copyright (c) 2026 YOUR_NAME
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.