@mandujs/core 0.28.0 → 0.29.0

package/src/client/hydrate.ts

@@ -0,0 +1,340 @@
+/**
+ * Mandu Per-Island Hydration Scheduler
+ *
+ * Phase 18.δ — Formal hydration strategy spec for Islands.
+ *
+ * Strategies (Astro-compatible naming):
+ *   - `load`                — hydrate immediately (current default; equiv. to Astro `client:load`)
+ *   - `idle`                — `requestIdleCallback` (Astro `client:idle`)
+ *   - `visible`             — `IntersectionObserver` rootMargin 200px (Astro `client:visible`)
+ *   - `interaction`         — hydrate on first click/touchstart/keydown (Astro `client:only` equivalent for events)
+ *   - `media(<query>)`      — hydrate only when `matchMedia(query).matches` (Astro `client:media`)
+ *
+ * This module is the **single source of truth** for hydration scheduling on
+ * the client. It is intentionally side-effect-free on import so that:
+ *   1. Bundlers can tree-shake unused strategies.
+ *   2. Unit tests can import it under happy-dom/JSDOM without triggering
+ *      global mutation (no `document.querySelectorAll` on module eval).
+ *
+ * The bundler-generated runtime (`bundler/build.ts::generateRuntimeSource`)
+ * delegates strategy selection to `scheduleHydration()` here — SSR emits the
+ * `data-hydrate` attribute, the runtime reads it and dispatches.
+ *
+ * Design contract:
+ *   - Every strategy invokes its `hydrate` callback at most ONCE.
+ *   - Every strategy returns a `dispose()` cleanup that detaches observers
+ *     and event listeners (no memory leaks on route change / unmount).
+ *   - Unknown / malformed strategies fall back to `load` with a console
+ *     warning so broken islands never silently stay un-interactive.
+ */
+
+export type HydrationStrategyName =
+  | "load"
+  | "idle"
+  | "visible"
+  | "interaction"
+  | "media";
+
+export interface ParsedStrategy {
+  name: HydrationStrategyName;
+  /** media query string when `name === "media"`, else `undefined`. */
+  media?: string;
+}
+
+/** `rootMargin` used by the `visible` IntersectionObserver. */
+export const VISIBLE_ROOT_MARGIN = "200px";
+
+/** Events that trigger `interaction` hydration. */
+export const INTERACTION_EVENTS = ["click", "touchstart", "keydown"] as const;
+
+/**
+ * Parse a `data-hydrate` attribute value into a normalized strategy.
+ *
+ * Accepts:
+ *   - `"load"` | `"idle"` | `"visible"` | `"interaction"`
+ *   - `"media(min-width: 768px)"` — media query in parentheses
+ *
+ * Returns `{ name: "load" }` with a `console.warn` for unknown/malformed
+ * inputs (fail-open default — never leave an island dead).
+ */
+export function parseHydrateStrategy(
+  attr: string | null | undefined,
+): ParsedStrategy {
+  if (!attr) return { name: "load" };
+
+  const trimmed = attr.trim();
+
+  if (
+    trimmed === "load" ||
+    trimmed === "idle" ||
+    trimmed === "visible" ||
+    trimmed === "interaction"
+  ) {
+    return { name: trimmed };
+  }
+
+  // media(<query>) — extract inner query
+  const mediaMatch = /^media\(\s*(.+?)\s*\)$/.exec(trimmed);
+  if (mediaMatch && mediaMatch[1]) {
+    return { name: "media", media: mediaMatch[1] };
+  }
+
+  // Fallback: legacy `immediate` alias → `load`
+  if (trimmed === "immediate") return { name: "load" };
+
+  if (typeof console !== "undefined" && typeof console.warn === "function") {
+    console.warn(
+      `[Mandu] Unknown hydrate strategy "${attr}", falling back to "load".`,
+    );
+  }
+  return { name: "load" };
+}
+
+/**
+ * A function returned by each strategy scheduler. Invoke to detach any
+ * observers / listeners BEFORE the actual hydration kicks in. Safe to call
+ * multiple times (idempotent).
+ */
+export type Disposer = () => void;
+
+function noopDispose(): Disposer {
+  return () => {};
+}
+
+/**
+ * `load` — hydrate synchronously on next microtask.
+ *
+ * We use a microtask (Promise.resolve().then) rather than calling `hydrate`
+ * directly so that callers can install listeners on `mandu:hydrated` events
+ * after `scheduleHydration` returns. Matches Astro `client:load` semantics.
+ */
+function scheduleLoad(hydrate: () => void): Disposer {
+  let cancelled = false;
+  Promise.resolve().then(() => {
+    if (!cancelled) hydrate();
+  });
+  return () => {
+    cancelled = true;
+  };
+}
+
+/**
+ * `idle` — hydrate when the browser is idle.
+ * Falls back to `setTimeout(200)` when `requestIdleCallback` is unavailable
+ * (Safari < 16.4, some WebViews).
+ */
+function scheduleIdle(hydrate: () => void): Disposer {
+  const w = typeof window !== "undefined" ? window : undefined;
+  if (!w) return noopDispose();
+
+  if (typeof w.requestIdleCallback === "function") {
+    const handle = w.requestIdleCallback(() => hydrate());
+    return () => {
+      if (typeof w.cancelIdleCallback === "function") {
+        w.cancelIdleCallback(handle);
+      }
+    };
+  }
+
+  const timer = setTimeout(hydrate, 200);
+  return () => clearTimeout(timer);
+}
+
+/**
+ * `visible` — hydrate when the element enters the viewport (+200px margin).
+ * Falls back to immediate hydration when `IntersectionObserver` is missing.
+ */
+function scheduleVisible(
+  element: Element,
+  hydrate: () => void,
+): Disposer {
+  if (typeof IntersectionObserver === "undefined") {
+    hydrate();
+    return noopDispose();
+  }
+
+  let disposed = false;
+  const observer = new IntersectionObserver(
+    (entries) => {
+      if (disposed) return;
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          disposed = true;
+          observer.disconnect();
+          hydrate();
+          return;
+        }
+      }
+    },
+    { rootMargin: VISIBLE_ROOT_MARGIN },
+  );
+
+  // `display:contents` wrappers have zero layout size → observe the first
+  // element child when available so IntersectionObserver sees real geometry.
+  const target = resolveObservationTarget(element);
+  observer.observe(target);
+
+  return () => {
+    disposed = true;
+    observer.disconnect();
+  };
+}
+
+/**
+ * `interaction` — hydrate on the first click / touchstart / keydown within
+ * the island. Matches the task spec (click/touch/keydown only; no
+ * mouseenter or pointerdown to keep scroll & hover passive).
+ */
+function scheduleInteraction(
+  element: Element,
+  hydrate: () => void,
+): Disposer {
+  let fired = false;
+  const target = resolveObservationTarget(element);
+
+  const onEvent = () => {
+    if (fired) return;
+    fired = true;
+    dispose();
+    hydrate();
+  };
+
+  const dispose: Disposer = () => {
+    for (const evt of INTERACTION_EVENTS) {
+      target.removeEventListener(evt, onEvent, true);
+    }
+  };
+
+  for (const evt of INTERACTION_EVENTS) {
+    // Capture phase so the island hydrates BEFORE the user's click bubbles
+    // to their still-dehydrated event handler.
+    target.addEventListener(evt, onEvent, { capture: true, once: false });
+  }
+
+  return dispose;
+}
+
+/**
+ * `media(<query>)` — hydrate only when `matchMedia(query).matches` becomes
+ * true. If already matching on mount, hydrate immediately; otherwise wait
+ * for the first `change` event.
+ */
+function scheduleMedia(query: string, hydrate: () => void): Disposer {
+  if (
+    typeof window === "undefined" ||
+    typeof window.matchMedia !== "function"
+  ) {
+    // No matchMedia support → fall back to `load` so the island is at least
+    // interactive. Conservative: users can't debug silent no-ops.
+    hydrate();
+    return noopDispose();
+  }
+
+  const mql = window.matchMedia(query);
+  if (mql.matches) {
+    hydrate();
+    return noopDispose();
+  }
+
+  let disposed = false;
+  const onChange = (e: MediaQueryListEvent) => {
+    if (disposed) return;
+    if (e.matches) {
+      disposed = true;
+      detach();
+      hydrate();
+    }
+  };
+
+  const detach: Disposer = () => {
+    if (typeof mql.removeEventListener === "function") {
+      mql.removeEventListener("change", onChange);
+    } else if (typeof (mql as unknown as { removeListener?: (l: unknown) => void }).removeListener === "function") {
+      // Safari < 14 legacy API
+      (mql as unknown as { removeListener: (l: (e: MediaQueryListEvent) => void) => void }).removeListener(onChange);
+    }
+  };
+
+  if (typeof mql.addEventListener === "function") {
+    mql.addEventListener("change", onChange);
+  } else if (typeof (mql as unknown as { addListener?: (l: unknown) => void }).addListener === "function") {
+    (mql as unknown as { addListener: (l: (e: MediaQueryListEvent) => void) => void }).addListener(onChange);
+  }
+
+  return () => {
+    disposed = true;
+    detach();
+  };
+}
+
+/**
+ * Resolve the DOM node to actually observe / listen on. Island wrappers use
+ * `style="display:contents"` which has zero layout box — IntersectionObserver
+ * refuses to fire for such elements. Promote to the first element child when
+ * available, else fall back to the wrapper itself.
+ */
+function resolveObservationTarget(element: Element): Element {
+  if (typeof window === "undefined" || typeof getComputedStyle !== "function") {
+    return element;
+  }
+  try {
+    const cs = getComputedStyle(element);
+    if (cs.display === "contents" && element.firstElementChild) {
+      return element.firstElementChild;
+    }
+  } catch {
+    /* happy-dom may reject partial stylesheet queries — treat as layout element */
+  }
+  return element;
+}
+
+/**
+ * Public entry — schedule hydration of `element` according to `strategy`,
+ * invoking `hydrate` at most once. Returns a disposer for cleanup.
+ *
+ * Unknown strategies degrade to `load` with a console warning.
+ *
+ * @param element  — the island root (typically `[data-mandu-island]`)
+ * @param strategy — either a `ParsedStrategy` from `parseHydrateStrategy`
+ *                   OR a raw attribute string (e.g. `"media(min-width: 768px)"`)
+ * @param hydrate  — callback invoked once when the strategy trigger fires
+ */
+export function scheduleHydration(
+  element: Element,
+  strategy: ParsedStrategy | string | null | undefined,
+  hydrate: () => void,
+): Disposer {
+  const parsed =
+    typeof strategy === "string" || strategy == null
+      ? parseHydrateStrategy(strategy as string | null | undefined)
+      : strategy;
+
+  switch (parsed.name) {
+    case "load":
+      return scheduleLoad(hydrate);
+    case "idle":
+      return scheduleIdle(hydrate);
+    case "visible":
+      return scheduleVisible(element, hydrate);
+    case "interaction":
+      return scheduleInteraction(element, hydrate);
+    case "media":
+      return parsed.media
+        ? scheduleMedia(parsed.media, hydrate)
+        : scheduleLoad(hydrate);
+    default:
+      // Exhaustiveness: if a new strategy is added to the union without a
+      // handler, TypeScript flags the `never` check below at compile time.
+      ((_x: never) => _x)(parsed.name);
+      return scheduleLoad(hydrate);
+  }
+}
+
+/**
+ * Internal test helpers — expose resolveObservationTarget so that unit
+ * tests can verify the `display:contents` promotion rule without relying
+ * on public API side-effects.
+ *
+ * @internal
+ */
+export const _testOnly_resolveObservationTarget = resolveObservationTarget;

package/src/client/index.ts

@@ -63,6 +63,17 @@ export {
   type HydrationPriority,
 } from "./runtime";
 
+// Phase 18.δ — Per-Island hydration scheduler (Astro-grade)
+export {
+  scheduleHydration,
+  parseHydrateStrategy,
+  VISIBLE_ROOT_MARGIN,
+  INTERACTION_EVENTS,
+  type HydrationStrategyName,
+  type ParsedStrategy,
+  type Disposer,
+} from "./hydrate";
+
 // SSE / ReadableStream API (microtask-starvation-safe)
 export {
   useSSE,

package/src/config/mandu.ts

@@ -2,6 +2,7 @@ import path from "path";
 import { readJsonFile } from "../utils/bun";
 import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
+import type { Middleware } from "../middleware/define";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
@@ -232,6 +233,29 @@ export interface ManduConfig {
      * to re-read this comment to recover.
      */
     prebuildTimeoutMs?: number;
+    /**
+     * Phase 18.α — Dev-only full-screen error overlay (Next.js / Astro
+     * style). When `true` (default) Mandu injects a ~10 KB inline
+     * `<style>` + `<script>` block into every dev SSR response that
+     * renders a modal on:
+     *
+     *   - `window.onerror` — uncaught script errors
+     *   - `unhandledrejection` — unhandled Promise rejections
+     *   - custom `__MANDU_ERROR__` CustomEvent — used by the server's
+     *     500 path to surface SSR render failures directly in the
+     *     browser instead of only in the terminal
+     *
+     * The overlay ships a "Copy for AI" button that formats a markdown
+     * snapshot of the error + stack for paste-into-Claude triage.
+     *
+     * Production builds NEVER emit the overlay regardless of this flag:
+     * `shouldInjectOverlay()` triple-gates against `isDev`,
+     * `NODE_ENV=production`, and explicit opt-out.
+     *
+     * Set `false` to disable in dev (e.g. when capturing screenshots
+     * for docs). Default: `true`.
+     */
+    errorOverlay?: boolean;
   };
   fsRoutes?: {
     routesDir?: string;
@@ -265,6 +289,22 @@ export interface ManduConfig {
   };
   plugins?: ManduPlugin[];
   hooks?: Partial<ManduHooks>;
+  /**
+   * Phase 18.ε — canonical request-level middleware chain.
+   *
+   * Array of {@link Middleware} executed in declaration order (outermost
+   * first) BEFORE route dispatch. Each middleware may short-circuit by
+   * returning a Response without calling `next()`, or mutate the
+   * downstream Response after `next()` returns. This is the Next.js
+   * `middleware.ts` / SvelteKit `handle` sequence analogue.
+   *
+   * Compose with {@link defineMiddleware} + bridge wrappers
+   * (`csrfMiddleware`, `sessionMiddleware`, `secureMiddleware`,
+   * `rateLimitMiddleware`) from `@mandujs/core/middleware`.
+   *
+   * @see `docs/architect/middleware-composition.md`
+   */
+  middleware?: Middleware[];
 }
 
 export const CONFIG_FILES = [

package/src/config/validate.ts

@@ -5,6 +5,7 @@ import { CONFIG_FILES, coerceConfig } from "./mandu";
 import { readJsonFile } from "../utils/bun";
 import type { ManduAdapter } from "../runtime/adapter";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
+import type { Middleware } from "../middleware/define";
 
 /**
  * DNA-003: Strict mode schema helper
@@ -98,6 +99,12 @@ const BuildConfigSchema = z
     minify: z.boolean().default(true),
     sourcemap: z.boolean().default(false),
     splitting: z.boolean().default(false),
+    /**
+     * Phase 18 — prerender static HTML for pages during `mandu build`.
+     * Default: `true` (every static page + every dynamic page whose
+     * module exports `generateStaticParams` is prerendered).
+     */
+    prerender: z.boolean().default(true),
   })
   .strict();
 
@@ -264,6 +271,28 @@ const ManduHooksSchema = z.custom<Partial<ManduHooks>>(
   { message: "hooks must be an object" }
 );
 
+/**
+ * Phase 18.ε — canonical request-level middleware. Each entry must be an
+ * object with a non-empty `name` string and a `handler` function.
+ * `match` is optional but must be a function when present. Zod cannot
+ * introspect closures, so this is a structural check; `defineMiddleware`
+ * enforces the same shape at definition time for the clearest DX error.
+ */
+const MiddlewareSchema = z.custom<Middleware>(
+  (v) => {
+    if (typeof v !== "object" || v === null) return false;
+    const obj = v as { name?: unknown; handler?: unknown; match?: unknown };
+    if (typeof obj.name !== "string" || obj.name.length === 0) return false;
+    if (typeof obj.handler !== "function") return false;
+    if (obj.match !== undefined && typeof obj.match !== "function") return false;
+    return true;
+  },
+  {
+    message:
+      "Each middleware must be an object with a non-empty `name` string, a `handler` function, and (optionally) a `match` function. Use `defineMiddleware({...})` to construct.",
+  }
+);
+
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
@@ -295,6 +324,13 @@ export const ManduConfigSchema = z
     observability: ObservabilityConfigSchema.default({}),
     plugins: z.array(ManduPluginSchema).optional(),
     hooks: ManduHooksSchema.optional(),
+    /**
+     * Phase 18.ε — request-level middleware chain. Array validated
+     * structurally (see {@link MiddlewareSchema}); no default, so
+     * omitting the field leaves the chain empty (zero-overhead
+     * passthrough at runtime).
+     */
+    middleware: z.array(MiddlewareSchema).optional(),
   })
   .strict();