@bractjs/bractjs 0.1.29 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.29",
+  "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",

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

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

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

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

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

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

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

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

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

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

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

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

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