npm - @mandujs/core - Versions diffs - 0.28.0 → 0.29.1 - Mend

@mandujs/core 0.28.0 → 0.29.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 (24) hide show

package/package.json +9 -1
package/src/bundler/generate-static-params.ts +290 -0
package/src/bundler/prerender.ts +242 -69
package/src/client/hydrate.ts +340 -0
package/src/client/index.ts +11 -0
package/src/config/mandu.ts +40 -0
package/src/config/validate.ts +36 -0
package/src/dev-error-overlay/__tests__/overlay-injector.test.ts +241 -0
package/src/dev-error-overlay/index.ts +30 -0
package/src/dev-error-overlay/overlay-client.ts +300 -0
package/src/dev-error-overlay/overlay-injector.ts +243 -0
package/src/dev-error-overlay/overlay-styles.ts +52 -0
package/src/dev-error-overlay/types.ts +66 -0
package/src/middleware/bridge.ts +147 -0
package/src/middleware/compose.ts +134 -0
package/src/middleware/define.ts +132 -0
package/src/middleware/index.ts +76 -50
package/src/router/fs-patterns.test.ts +96 -0
package/src/router/fs-routes.ts +1 -0
package/src/router/fs-scanner.ts +10 -1
package/src/router/fs-types.ts +8 -0
package/src/runtime/server.ts +310 -10
package/src/runtime/ssr.ts +70 -2
package/src/spec/schema.ts +6 -0

package/src/dev-error-overlay/overlay-injector.ts ADDED Viewed

@@ -0,0 +1,243 @@
+/**
+ * Phase 18.α — Dev Error Overlay injector.
+ *
+ * Provides two surfaces:
+ *
+ *   1. `buildOverlayHeadTag(config)` — returns the `<style>` + `<script>`
+ *      block to splice into the SSR `<head>`. Returns `""` in production
+ *      mode, when the user opts out via `ManduConfig.dev.errorOverlay:
+ *      false`, or when the environment signals a non-dev build. This is
+ *      the canonical entry point called from `runtime/ssr.ts`.
+ *
+ *   2. `buildOverlayErrorEmbed(payload)` — serialises a
+ *      `DevErrorPayload` into two tags (a `<script type="application/json">`
+ *      the IIFE reads on DOMContentLoaded, plus a fire-and-forget event
+ *      dispatch for late-mounted pages). Used by the 500-response path
+ *      in `runtime/server.ts` so SSR crashes still render the overlay
+ *      even when the React tree never produced output.
+ *
+ * Security posture:
+ *   - Prod NEVER renders the overlay — triple-gated by env, explicit
+ *     opt-in, and the injector's early-return.
+ *   - The payload is escaped with the existing `escapeJsonForInlineScript`
+ *     so `</script>` sequences cannot break out.
+ *   - Stack traces contain absolute paths. Acceptable in dev; the
+ *     injector refuses to emit when NODE_ENV=production regardless of
+ *     any other flag.
+ */
+import { escapeJsonForInlineScript } from "../runtime/escape";
+import { OVERLAY_CLIENT_SCRIPT } from "./overlay-client";
+import { OVERLAY_STYLES } from "./overlay-styles";
+import type { DevErrorPayload, DevErrorStackFrame } from "./types";
+import {
+  OVERLAY_CUSTOM_EVENT,
+  OVERLAY_PAYLOAD_ELEMENT_ID,
+} from "./types";
+/**
+ * Config consumed by the injector. Mirrors `ManduConfig.dev.errorOverlay`
+ * plus an `isDev` escape hatch for callers that already know the runtime
+ * mode (e.g. the SSR pipeline computes this from `settings.isDev`).
+ */
+export interface DevOverlayInjectorConfig {
+  /** Explicit dev-mode signal. When `false`, the injector ALWAYS returns "". */
+  isDev: boolean;
+  /**
+   * User-level opt-out from `ManduConfig.dev.errorOverlay`. `undefined`
+   * means "default" (enabled in dev). `false` disables; `true` is a
+   * no-op (dev is always enabled).
+   */
+  enabled?: boolean;
+}
+/**
+ * The absolute guard: production NEVER renders. Triple-checks:
+ *   - `config.isDev === true` (caller authoritative)
+ *   - `NODE_ENV !== "production"` (env authoritative; `isDev` can't lie)
+ *   - user did not set `dev.errorOverlay: false`
+ *
+ * All three must pass. If any check fails we return `false` and the
+ * injector emits an empty string.
+ */
+export function shouldInjectOverlay(config: DevOverlayInjectorConfig): boolean {
+  if (config.enabled === false) return false;
+  if (!config.isDev) return false;
+  try {
+    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "production") {
+      return false;
+    }
+  } catch {
+    // edge runtimes that sandbox `process` — fall through; isDev already
+    // passed and the caller asserted dev mode.
+  }
+  return true;
+}
+/**
+ * Build the `<style>` + `<script>` block to inject into the SSR `<head>`.
+ * Returns `""` in production or when the user opts out.
+ *
+ * The returned string is expected to be spliced AS-IS into the
+ * `renderToHTML` head template — `escapeJsonForInlineScript` is NOT
+ * applied at this layer because the content is already safe (a verbatim
+ * IIFE string and a verbatim CSS string, both authored in this repo).
+ */
+export function buildOverlayHeadTag(config: DevOverlayInjectorConfig): string {
+  if (!shouldInjectOverlay(config)) return "";
+  // `id` attributes let tests + HMR locate the tags. The IIFE guards
+  // against double-mount via `OVERLAY_MOUNTED_FLAG`, so even if two
+  // copies somehow slip in the user-visible behaviour is still correct.
+  return (
+    `<style id="__mandu-dev-overlay-style">${OVERLAY_STYLES}</style>` +
+    `<script id="__mandu-dev-overlay-client">${OVERLAY_CLIENT_SCRIPT}</script>`
+  );
+}
+/**
+ * Thin wrapper called from `runtime/ssr.ts`. The function name matches
+ * the spec ("maybeInjectDevOverlay"). Returning a string keeps ssr.ts'
+ * template-literal interpolation ergonomic.
+ */
+export function maybeInjectDevOverlay(config: DevOverlayInjectorConfig): string {
+  return buildOverlayHeadTag(config);
+}
+/**
+ * Parse a raw `error.stack` string into frames on the server, mirroring
+ * the client-side parser. Server-side preparation means the overlay
+ * renders the structured list immediately — no regex cost on the main
+ * thread at page load.
+ *
+ * Deliberately simple: handles Chrome / V8 (`    at fn (file:line:col)`)
+ * and Firefox (`fn@file:line:col`). Anything else becomes an
+ * `<anonymous>` frame carrying the raw line text, so information is
+ * never lost.
+ */
+export function parseStackFrames(stack: string | undefined | null): DevErrorStackFrame[] {
+  if (!stack) return [];
+  const lines = stack.split("\n");
+  const out: DevErrorStackFrame[] = [];
+  for (const raw of lines) {
+    const t = raw.trim();
+    if (!t) continue;
+    // Skip the first line if it's just "Error: message" (the header).
+    if (/^[A-Z][a-zA-Z]*(?:Error)?:/.test(t) && out.length === 0) continue;
+    let m = t.match(/^at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/);
+    if (m) {
+      out.push({
+        fn: m[1],
+        file: m[2],
+        line: Number.parseInt(m[3], 10),
+        column: Number.parseInt(m[4], 10),
+        raw,
+      });
+      continue;
+    }
+    m = t.match(/^at\s+(.+):(\d+):(\d+)$/);
+    if (m) {
+      out.push({
+        fn: "<anonymous>",
+        file: m[1],
+        line: Number.parseInt(m[2], 10),
+        column: Number.parseInt(m[3], 10),
+        raw,
+      });
+      continue;
+    }
+    m = t.match(/^(.*?)@(.+):(\d+):(\d+)$/);
+    if (m) {
+      out.push({
+        fn: m[1] || "<anonymous>",
+        file: m[2],
+        line: Number.parseInt(m[3], 10),
+        column: Number.parseInt(m[4], 10),
+        raw,
+      });
+      continue;
+    }
+    out.push({ fn: "<anonymous>", file: t, line: null, column: null, raw });
+  }
+  return out;
+}
+/**
+ * Build a `DevErrorPayload` from a caught `Error`-like value. Safe
+ * against non-Error throws (strings, plain objects, undefined).
+ */
+export function buildPayloadFromError(
+  err: unknown,
+  extra: { kind?: DevErrorPayload["kind"]; routeId?: string; url?: string } = {},
+): DevErrorPayload {
+  let name = "Error";
+  let message = "";
+  let stack = "";
+  if (err && typeof err === "object") {
+    const rec = err as { name?: unknown; message?: unknown; stack?: unknown };
+    name = typeof rec.name === "string" ? rec.name : "Error";
+    message = typeof rec.message === "string" ? rec.message : "";
+    stack = typeof rec.stack === "string" ? rec.stack : "";
+  } else if (typeof err === "string") {
+    message = err;
+  } else if (err !== null && err !== undefined) {
+    try { message = String(err); } catch { message = "<unserializable>"; }
+  }
+  return {
+    name,
+    message,
+    frames: parseStackFrames(stack),
+    stack,
+    kind: extra.kind ?? "ssr",
+    timestamp: Date.now(),
+    routeId: extra.routeId,
+    url: extra.url,
+  };
+}
+/**
+ * Build the body-end embed tags for an SSR 500 response. The first tag
+ * carries the payload as JSON (the IIFE picks it up on
+ * DOMContentLoaded); the second tag is a defensive re-dispatch for
+ * pages that already fired DOMContentLoaded by the time the overlay
+ * mounts (possible when HMR re-runs the client bundle).
+ *
+ * Both tags are safe to splice verbatim — `escapeJsonForInlineScript`
+ * neutralises any `</script>` in the payload.
+ */
+export function buildOverlayErrorEmbed(payload: DevErrorPayload): string {
+  const json = escapeJsonForInlineScript(JSON.stringify(payload));
+  const dispatch = `(function(){try{var d=${json};window.dispatchEvent(new CustomEvent(${JSON.stringify(
+    OVERLAY_CUSTOM_EVENT,
+  )},{detail:d}));}catch(_){}})();`;
+  return (
+    `<script id="${OVERLAY_PAYLOAD_ELEMENT_ID}" type="application/json">${json}</script>` +
+    `<script>${dispatch}</script>`
+  );
+}
+/**
+ * Produce a minimal HTML document for the SSR 500 surface in dev. The
+ * overlay client IIFE is inlined so the overlay renders even when the
+ * React tree never emitted a root — which is exactly when `createSSRErrorResponse`
+ * fires. Returns a complete `<!doctype html>` string; the server wraps
+ * it in a 500 `Response`.
+ */
+export function buildOverlayErrorHtml(payload: DevErrorPayload): string {
+  return (
+    `<!doctype html><html lang="en"><head><meta charset="UTF-8">` +
+    `<title>Mandu — ${escapeTitle(payload.name)}</title>` +
+    buildOverlayHeadTag({ isDev: true }) +
+    `</head><body><div id="root"></div>` +
+    buildOverlayErrorEmbed(payload) +
+    `</body></html>`
+  );
+}
+function escapeTitle(s: string): string {
+  return s.replace(/[<>&"']/g, (c) =>
+    c === "<" ? "&lt;"
+      : c === ">" ? "&gt;"
+      : c === "&" ? "&amp;"
+      : c === "\"" ? "&quot;"
+      : "&#39;",
+  );
+}

package/src/dev-error-overlay/overlay-styles.ts ADDED Viewed

@@ -0,0 +1,52 @@
+/**
+ * Phase 18.α — Dev Error Overlay styles.
+ *
+ * Scoped CSS string emitted inside a single `<style>` tag by the
+ * injector. Deliberately:
+ *
+ *   - Prefix every selector with `.mandu-dev-overlay` so we never leak
+ *     into the host page's stylesheet (no `*` or `body` selectors).
+ *   - Inline all values — no Tailwind, no CSS vars from userland.
+ *   - Use `system-ui, -apple-system, ...` + a monospace stack so the
+ *     overlay works even on pages that have not yet loaded webfonts
+ *     (broken SSR responses often haven't).
+ *   - Hit contrast ratio ≥ 7:1 (WCAG AAA) for the text-on-backdrop
+ *     combination: `#f4f4f5` on `rgba(10,10,10,0.94)` ≈ 14.2:1.
+ *
+ * The whole string weighs ~2.2 KB uncompressed. gzip ≈ 0.9 KB.
+ */
+export const OVERLAY_STYLES = `
+.mandu-dev-overlay{position:fixed;inset:0;z-index:2147483647;background:rgba(10,10,10,0.94);color:#f4f4f5;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace;font-size:13px;line-height:1.5;overflow:auto;padding:32px;box-sizing:border-box;-webkit-font-smoothing:antialiased}
+.mandu-dev-overlay *,.mandu-dev-overlay *::before,.mandu-dev-overlay *::after{box-sizing:border-box}
+.mandu-dev-overlay__panel{max-width:960px;margin:0 auto;background:#18181b;border:1px solid #3f3f46;border-radius:8px;box-shadow:0 20px 60px rgba(0,0,0,0.6);overflow:hidden}
+.mandu-dev-overlay__header{display:flex;align-items:center;justify-content:space-between;padding:16px 24px;background:#27272a;border-bottom:1px solid #3f3f46}
+.mandu-dev-overlay__title{display:flex;flex-direction:column;gap:4px}
+.mandu-dev-overlay__kind{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:#fca5a5;font-weight:600}
+.mandu-dev-overlay__name{font-size:18px;color:#fafafa;font-weight:600;font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+.mandu-dev-overlay__actions{display:flex;gap:8px}
+.mandu-dev-overlay__btn{appearance:none;background:#3f3f46;border:1px solid #52525b;color:#fafafa;padding:6px 12px;border-radius:6px;font-family:inherit;font-size:12px;cursor:pointer;transition:background 120ms ease;font-weight:500}
+.mandu-dev-overlay__btn:hover{background:#52525b}
+.mandu-dev-overlay__btn:focus-visible{outline:2px solid #60a5fa;outline-offset:2px}
+.mandu-dev-overlay__btn--primary{background:#2563eb;border-color:#1d4ed8}
+.mandu-dev-overlay__btn--primary:hover{background:#1d4ed8}
+.mandu-dev-overlay__body{padding:24px}
+.mandu-dev-overlay__message{font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;font-size:15px;color:#fafafa;margin:0 0 20px;white-space:pre-wrap;word-break:break-word;padding:12px 16px;background:#0a0a0a;border-left:3px solid #ef4444;border-radius:4px}
+.mandu-dev-overlay__meta{display:flex;flex-wrap:wrap;gap:16px;margin-bottom:20px;padding:12px 16px;background:#0a0a0a;border-radius:6px;font-size:12px}
+.mandu-dev-overlay__meta-item{display:flex;flex-direction:column;gap:2px}
+.mandu-dev-overlay__meta-label{color:#a1a1aa;font-size:10px;text-transform:uppercase;letter-spacing:0.06em}
+.mandu-dev-overlay__meta-value{color:#e4e4e7}
+.mandu-dev-overlay__section-title{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:#a1a1aa;margin:0 0 8px;font-weight:600}
+.mandu-dev-overlay__frames{list-style:none;margin:0;padding:0;background:#0a0a0a;border-radius:6px;overflow:hidden}
+.mandu-dev-overlay__frame{padding:10px 16px;border-bottom:1px solid #27272a;display:flex;flex-direction:column;gap:2px}
+.mandu-dev-overlay__frame:last-child{border-bottom:none}
+.mandu-dev-overlay__frame-fn{color:#fbbf24;font-weight:500}
+.mandu-dev-overlay__frame-loc{color:#a1a1aa;font-size:12px}
+.mandu-dev-overlay__frame-link{color:#93c5fd;text-decoration:none;cursor:pointer}
+.mandu-dev-overlay__frame-link:hover{text-decoration:underline;color:#bfdbfe}
+.mandu-dev-overlay__frame-link:focus-visible{outline:2px solid #60a5fa;outline-offset:1px;border-radius:2px}
+.mandu-dev-overlay__stack{margin-top:16px;padding:12px 16px;background:#0a0a0a;border-radius:6px;max-height:240px;overflow:auto;white-space:pre-wrap;word-break:break-all;color:#d4d4d8;font-size:12px}
+.mandu-dev-overlay__footer{padding:12px 24px;background:#0a0a0a;border-top:1px solid #27272a;font-size:11px;color:#71717a;text-align:center}
+.mandu-dev-overlay__footer code{background:#27272a;padding:1px 6px;border-radius:3px;color:#a1a1aa}
+.mandu-dev-overlay[hidden]{display:none}
+@media (prefers-reduced-motion:reduce){.mandu-dev-overlay__btn{transition:none}}
+`.trim();

package/src/dev-error-overlay/types.ts ADDED Viewed

@@ -0,0 +1,66 @@
+/**
+ * Phase 18.α — Dev Error Overlay: shared type definitions.
+ *
+ * These types are shipped to both the server-side injector AND the
+ * client-side IIFE. Keep them plain-object friendly (no class instances,
+ * no bigints) because the payload is round-tripped through
+ * `JSON.stringify` when embedded into the 500-response HTML and read back
+ * via `JSON.parse(document.getElementById('__MANDU_ERROR__').textContent)`
+ * by `overlay-client.ts`.
+ */
+/**
+ * A single formatted stack frame. Parsed from `Error.stack` by the
+ * client IIFE; the server also pre-parses when emitting a 500 payload
+ * so the overlay can render immediately without running the regex on
+ * the main thread twice.
+ */
+export interface DevErrorStackFrame {
+  /** Function name (e.g. `MyComponent`), or `<anonymous>` when the frame is anonymous. */
+  fn: string;
+  /** Absolute or project-relative file path. Used to build the clickable `vscode://file/` link. */
+  file: string;
+  /** 1-based line number, or `null` when the stack frame did not carry one. */
+  line: number | null;
+  /** 1-based column number, or `null`. */
+  column: number | null;
+  /** The raw frame text as it appeared in `Error.stack` — preserved for copy-paste fidelity. */
+  raw: string;
+}
+/**
+ * The structured error payload that both the server (for SSR 500s) and
+ * the client (for `window.onerror` / `unhandledrejection`) marshall into
+ * the overlay. `kind` distinguishes the entry point so the UI can render
+ * a slightly different header ("SSR render failed" vs "Uncaught
+ * TypeError") without losing the rest of the data.
+ */
+export interface DevErrorPayload {
+  /** Error class name, e.g. `TypeError`. Falls back to `"Error"` when absent. */
+  name: string;
+  /** The message. May be empty. */
+  message: string;
+  /** Parsed frames — first frame is the top of the call stack. */
+  frames: DevErrorStackFrame[];
+  /** Raw `error.stack` string for "Copy for AI" and fallback rendering. */
+  stack: string;
+  /** Where the error surfaced. Used for UI copy. */
+  kind: "ssr" | "window" | "unhandled-rejection" | "manual";
+  /** Unix ms timestamp (client or server clock — both are best-effort in dev). */
+  timestamp: number;
+  /** Route id, when known (SSR errors carry it; client errors usually don't). */
+  routeId?: string;
+  /** URL pathname at error time — helpful when copying for AI triage. */
+  url?: string;
+  /** User-agent, for client-side errors only. The server never fills this. */
+  userAgent?: string;
+}
+/** HTML attribute name the injector uses for the `<script type="application/json">` payload tag. */
+export const OVERLAY_PAYLOAD_ELEMENT_ID = "__MANDU_ERROR__";
+/** `window` event name fired by user code / server embed to surface an error to the overlay. */
+export const OVERLAY_CUSTOM_EVENT = "__MANDU_ERROR__";
+/** Sentinel flag on `window` used by the client IIFE to avoid double-mount on HMR. */
+export const OVERLAY_MOUNTED_FLAG = "__MANDU_OVERLAY_MOUNTED__";

package/src/middleware/bridge.ts ADDED Viewed

@@ -0,0 +1,147 @@
+/**
+ * Bridge wrappers — Phase 18.ε
+ *
+ * Adapters that expose Mandu's existing ctx-based middleware
+ * (`csrf` / `session` / `secure` / `rateLimit`) through the canonical
+ * request-level {@link Middleware} interface. Both call styles remain
+ * supported forever — these bridges exist purely so the new
+ * `compose(...)` API can slot in a familiar primitive without wiring
+ * boilerplate.
+ *
+ * The bridge pattern:
+ *
+ *   1. Build a throwaway `ManduContext` from the incoming Request so the
+ *      ctx-based handler has the API surface it expects (`ctx.headers`,
+ *      `ctx.cookies`, `ctx.forbidden()`, etc.).
+ *   2. Invoke the ctx-based handler.
+ *   3. If it returns a Response, treat that as a short-circuit.
+ *   4. Otherwise call `next()` to continue the chain, then apply any
+ *      pending cookies the ctx-based handler wrote (e.g. CSRF cookie
+ *      issuance, session commits) onto the downstream Response.
+ *
+ * Note: request-level composition happens BEFORE route matching, so the
+ * `ctx.params` is always `{}` at this stage. Middleware that depends on
+ * route params (unusual) should stick with `filling().use(...)`.
+ */
+import { defineMiddleware, type Middleware } from "./define";
+import { ManduContext, type CookieManager } from "../filling/context";
+import { csrf, type CsrfMiddlewareOptions } from "./csrf";
+import {
+  session,
+  saveSession,
+  destroySession,
+  type SessionMiddlewareOptions,
+} from "./session";
+import {
+  secure as secureCtx,
+  type SecureMiddlewareOptions,
+} from "./secure";
+import {
+  rateLimit as rateLimitCtx,
+  type RateLimitMiddlewareOptions,
+} from "./rate-limit";
+// Re-export helpers so `saveSession` / `destroySession` are still reachable
+// from call-sites that import from the bridge surface. Backward compat.
+export { saveSession, destroySession };
+/**
+ * Copy pending Set-Cookie headers recorded on a `CookieManager` onto a
+ * downstream Response. Mirrors the end-of-request commit path used by
+ * `ManduContext.json()`/`ok()` so the ctx-based middleware's cookie
+ * writes (e.g. CSRF token issuance) survive the bridge.
+ */
+function applyCookies(cookies: CookieManager, response: Response): Response {
+  return cookies.hasPendingCookies() ? cookies.applyToResponse(response) : response;
+}
+/**
+ * Build a bridge middleware from a ctx-based `(ctx) => Response | void`
+ * handler. Short-circuits when the ctx handler returns a Response;
+ * otherwise continues the chain and folds the ctx's pending cookies
+ * back onto the final Response.
+ */
+function bridgeCtxMiddleware(
+  name: string,
+  build: () => (ctx: ManduContext) => Promise<Response | void> | Response | void
+): Middleware {
+  const ctxHandler = build();
+  return defineMiddleware({
+    name,
+    async handler(req, next) {
+      const ctx = new ManduContext(req);
+      const early = await ctxHandler(ctx);
+      if (early instanceof Response) {
+        return applyCookies(ctx.cookies, early);
+      }
+      const response = await next();
+      return applyCookies(ctx.cookies, response);
+    },
+  });
+}
+/**
+ * Request-level CSRF middleware — issues a double-submit cookie on safe
+ * methods and rejects with 403 when an unsafe request lacks a matching
+ * token. See {@link csrf} for the full semantics.
+ */
+export function csrfMiddleware(options: CsrfMiddlewareOptions): Middleware {
+  return bridgeCtxMiddleware("csrf", () => csrf(options));
+}
+/**
+ * Request-level session middleware — attaches a `Session` under the
+ * configured key. Commit remains caller-driven via {@link saveSession}
+ * / {@link destroySession}. See {@link session} for full semantics.
+ *
+ * Note: because composition runs pre-dispatch, the attached session is
+ * ONLY observable inside route handlers that read it via the same key
+ * (e.g. `ctx.get("session")`). The bridge's `ManduContext` is discarded
+ * after cookie-commit, so this bridge is strictly a convenience for
+ * session *hydration* + cookie roll-over; writes performed inside the
+ * route handler must still call `saveSession(routeCtx)` explicitly.
+ */
+export function sessionMiddleware(options: SessionMiddlewareOptions): Middleware {
+  return bridgeCtxMiddleware("session", () => session(options));
+}
+/**
+ * Request-level secure-headers middleware. Unlike the ctx-based
+ * `secure()` which uses `afterHandle` on a filling plugin, this bridge
+ * applies security headers via the `compose()` chain — it wraps the
+ * downstream Response and mutates its headers. See {@link secureCtx}
+ * for configuration.
+ *
+ * Implementation: calls the underlying `secure()` plugin's `afterHandle`
+ * hook directly against the downstream Response, skipping its
+ * `beforeHandle` (which only sets the CSP nonce for ctx-aware SSR — a
+ * request-level chain cannot thread a nonce into the route component,
+ * so nonce plumbing is intentionally out of scope for this bridge and
+ * users who need it should keep `.use(secure(...))` inline).
+ */
+export function secureMiddleware(options: SecureMiddlewareOptions = {}): Middleware {
+  const plugin = secureCtx(options);
+  return defineMiddleware({
+    name: "secure",
+    async handler(req, next) {
+      const response = await next();
+      const ctx = new ManduContext(req);
+      const afterHandle = plugin.afterHandle;
+      if (typeof afterHandle !== "function") return response;
+      const mutated = await afterHandle(ctx, response);
+      return mutated ?? response;
+    },
+  });
+}
+/**
+ * Request-level rate-limit middleware. Shares the underlying
+ * `rateLimit()` store semantics (sliding window, pluggable store). When
+ * the limiter rejects, returns the configured 429 Response directly
+ * (short-circuits the chain).
+ */
+export function rateLimitMiddleware(
+  options: RateLimitMiddlewareOptions
+): Middleware {
+  return bridgeCtxMiddleware("rate-limit", () => rateLimitCtx(options));
+}

package/src/middleware/compose.ts ADDED Viewed

@@ -0,0 +1,134 @@
+/**
+ * Middleware composition — Phase 18.ε
+ *
+ * Builds a request pipeline from an array of `Middleware` layers and a
+ * final handler. The resulting function has Next.js / SvelteKit semantics:
+ *
+ *   - **Declaration order = outer-to-inner.** `compose(a, b, c)` runs
+ *     `a.handler(req, nextA)` first; `nextA()` runs `b.handler`, whose
+ *     `nextB()` runs `c.handler`, whose `nextC()` invokes `finalHandler`.
+ *
+ *   - **Short-circuit.** Any middleware may return a Response without
+ *     calling `next()`. Downstream middleware and the final handler are
+ *     skipped; the outer chain receives the short-circuit Response.
+ *
+ *   - **Rewrite.** `next(modifiedReq)` propagates `modifiedReq` to the
+ *     remainder of the chain. The current middleware still sees the
+ *     original `req` argument (no mutation).
+ *
+ *   - **Match filter.** Middleware with a `match(req) === false` are
+ *     skipped at their position in the chain — `next()` transparently
+ *     advances to the next layer.
+ *
+ *   - **Error propagation.** Throws inside middleware are re-thrown to
+ *     the caller. Mandu's outer `handleRequest` wraps this in the
+ *     framework's error boundary (error → 500 via `errorToResponse`),
+ *     so middleware authors never need their own top-level try/catch
+ *     unless they want to convert specific errors to specific responses.
+ *
+ *   - **Double-next guard.** Calling `next()` twice inside a single
+ *     middleware is a programming error (it would re-execute downstream
+ *     layers with duplicate side effects). The second call throws a
+ *     `MiddlewareError` with the offending middleware's name so the bug
+ *     surfaces immediately in dev.
+ *
+ * @see {@link Middleware} for the interface.
+ * @see `docs/architect/middleware-composition.md` for patterns.
+ */
+import type { Middleware } from "./define";
+/**
+ * The finalized request handler that sits at the bottom of the middleware
+ * chain. Typically this is `handleRequest(req, router, registry)` adapted
+ * to the `(req) => Promise<Response>` shape.
+ */
+export type FinalHandler = (req: Request) => Promise<Response>;
+/**
+ * The function produced by {@link compose}. Applies the middleware chain
+ * on top of `finalHandler` for the given request.
+ */
+export type ComposedHandler = (
+  req: Request,
+  finalHandler: FinalHandler
+) => Promise<Response>;
+/**
+ * Thrown when a middleware calls `next()` more than once. Identifies the
+ * middleware by name so the diagnostic is actionable.
+ */
+export class MiddlewareError extends Error {
+  override readonly name = "MiddlewareError";
+  constructor(
+    public readonly middlewareName: string,
+    message: string
+  ) {
+    super(`[${middlewareName}] ${message}`);
+  }
+}
+/**
+ * Compose a middleware chain. Zero middleware produces a passthrough:
+ * `compose()(req, final) === final(req)`.
+ */
+export function compose(...middlewares: Middleware[]): ComposedHandler {
+  // Defensive copy — callers mutating the source array after compose() must
+  // not affect the frozen pipeline. Also narrows index type for the inner
+  // recursion and makes an empty-array fast path trivial.
+  const chain = middlewares.slice();
+  if (chain.length === 0) {
+    return (req, finalHandler) => finalHandler(req);
+  }
+  return async function composed(
+    req: Request,
+    finalHandler: FinalHandler
+  ): Promise<Response> {
+    // Recursive dispatcher. `index` is the next middleware to try; `current`
+    // is the Request object that layer will receive. Each invocation either:
+    //   (a) index === chain.length → delegate to finalHandler(current)
+    //   (b) chain[index].match(current) === false → skip, recurse to next
+    //   (c) run chain[index].handler(current, next) where next() = dispatch(i+1, …)
+    async function dispatch(index: number, current: Request): Promise<Response> {
+      if (index >= chain.length) {
+        return finalHandler(current);
+      }
+      const mw = chain[index]!;
+      // Evaluate match filter. Throws in `match` are framework-bug territory —
+      // we surface them to the outer error boundary rather than papering over.
+      if (mw.match) {
+        let matched: boolean;
+        try {
+          matched = mw.match(current);
+        } catch (err) {
+          throw new MiddlewareError(
+            mw.name,
+            `\`match(req)\` threw: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+        if (!matched) {
+          return dispatch(index + 1, current);
+        }
+      }
+      // Single-use `next` guard — second invocation throws.
+      let nextCalled = false;
+      const next = (override?: Request): Promise<Response> => {
+        if (nextCalled) {
+          throw new MiddlewareError(
+            mw.name,
+            "next() was called more than once. Each middleware must call next() at most once."
+          );
+        }
+        nextCalled = true;
+        return dispatch(index + 1, override ?? current);
+      };
+      return mw.handler(current, next);
+    }
+    return dispatch(0, req);
+  };
+}