@mandujs/core 0.33.0 → 0.33.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/prerender.ts

@@ -32,6 +32,66 @@ import { runDefinePrerenderHook } from "../plugins/runner";
 
 // ========== Types ==========
 
+/**
+ * Issue #213 — link-crawler configuration.
+ *
+ * When the prerender engine crawls rendered HTML for internal links
+ * (`crawl: true`) it accidentally picks up `href` attributes embedded
+ * inside documentation code examples (`<pre>`, `<code>`, fenced
+ * blocks, inline code spans). These are illustrative, not real routes,
+ * and trying to prerender them produces spurious `/path/index.html`
+ * files or build failures.
+ *
+ * The crawl options let callers:
+ *   1. Trust the default behavior (strip code regions + a small
+ *      hard-coded denylist of obvious placeholders).
+ *   2. Extend the denylist with project-specific placeholder globs.
+ *   3. Replace the denylist entirely for maximum control.
+ */
+export interface PrerenderCrawlOptions {
+  /**
+   * Extra pathnames or prefixes to exclude when crawling links. Each
+   * entry is matched against the normalized crawl target:
+   *   - Exact string (e.g. `"/example"`): matches that pathname only.
+   *   - Glob suffix (e.g. `"/your-*"`): uses a simple `*` → `.*` regex
+   *     translation to match any pathname with that prefix / pattern.
+   *
+   * Merged with the default denylist (see
+   * {@link DEFAULT_CRAWL_DENYLIST}). Use {@link PrerenderCrawlOptions.exclude}
+   * to ADD entries; set {@link PrerenderCrawlOptions.replaceDefaultExclude}
+   * to `true` to REPLACE the defaults.
+   */
+  exclude?: string[];
+  /**
+   * When `true`, `exclude` replaces the built-in denylist entirely
+   * instead of extending it. Default `false` (safe — defaults win).
+   */
+  replaceDefaultExclude?: boolean;
+  /**
+   * Issue #219 — file extensions treated as non-HTML assets. When a
+   * discovered `<a href>` / `href` value has a pathname ending in one
+   * of these extensions, the crawler skips it instead of enqueuing it
+   * for prerender. Without this filter, markup like `<picture><source
+   * srcset="/hero.avif"><img src="/hero.webp"></picture>` would cause
+   * the engine to render the asset as HTML and overwrite it on disk.
+   *
+   * Matching is case-insensitive and ignores query strings / hash
+   * fragments. See {@link DEFAULT_ASSET_EXTENSIONS} for the built-in
+   * list.
+   *
+   * Merged with {@link DEFAULT_ASSET_EXTENSIONS} unless
+   * {@link PrerenderCrawlOptions.replaceDefaultAssetExtensions} is
+   * `true`. Entries may be given with or without a leading dot
+   * (`"webp"` and `".webp"` are equivalent).
+   */
+  assetExtensions?: string[];
+  /**
+   * When `true`, `assetExtensions` replaces the built-in asset
+   * extension set entirely. Default `false` (safe — defaults win).
+   */
+  replaceDefaultAssetExtensions?: boolean;
+}
+
 export interface PrerenderOptions {
   /** Project root — all relative paths resolve from here. */
   rootDir: string;
@@ -46,6 +106,12 @@ export interface PrerenderOptions {
   routes?: string[];
   /** Follow internal `<a href>` links in rendered HTML (default: false). */
   crawl?: boolean;
+  /**
+   * Issue #213 — link-crawler configuration. Only consulted when
+   * `crawl: true`. Omitting the block uses the defaults (strip code
+   * regions, apply {@link DEFAULT_CRAWL_DENYLIST}).
+   */
+  crawlOptions?: PrerenderCrawlOptions;
   /**
    * When true, also write `<outDir>/_manifest.json` listing every
    * prerendered pathname. The runtime uses this index to short-circuit
@@ -67,6 +133,18 @@ export interface PrerenderOptions {
    */
   plugins?: readonly ManduPlugin[];
   configHooks?: Partial<ManduHooks>;
+
+  /**
+   * Issue #216 — opt-out from hard-failing on route errors.
+   * When `true`, errors from individual routes (module load / throw /
+   * non-array return from `generateStaticParams`) are collected in
+   * `PrerenderResult.errors` as warnings and the orchestrator returns
+   * normally. When `false` (default) the prerender still collects
+   * every route's error but throws a `PrerenderError` aggregate at
+   * the end so CI can exit non-zero. Set by the CLI's
+   * `--prerender-skip-errors` flag.
+   */
+  skipErrors?: boolean;
 }
 
 export interface PrerenderResult {
@@ -107,6 +185,108 @@ export const LEGACY_PRERENDER_DIR = ".mandu/static";
 export const DEFAULT_PRERENDER_CACHE_CONTROL =
   "public, max-age=31536000, immutable";
 
+/**
+ * Issue #213 — default denylist for the link crawler.
+ *
+ * These entries match paths that appear in doc examples (and never
+ * correspond to real routes): the classic placeholders (`/path`,
+ * `/example`), the `/your-*` and `/my-*` scaffolds people write when
+ * illustrating URL shapes, and the `/...` catch-all literal.
+ *
+ * Exact strings match a full pathname; entries containing `*` are
+ * treated as simple globs (`*` → `.*`, anchored).
+ */
+export const DEFAULT_CRAWL_DENYLIST: readonly string[] = [
+  "/path",
+  "/...",
+  "/example",
+  "/your-*",
+  "/my-*",
+  "/foo",
+  "/bar",
+  "/baz",
+  "/some-path",
+];
+
+/**
+ * Issue #219 — default non-HTML asset extensions the link crawler
+ * refuses to enqueue as prerender targets.
+ *
+ * Motivation: markup like `<picture><source srcset="/hero.avif"><img
+ * src="/hero.webp"></picture>` and `<a href="/whitepaper.pdf">` used
+ * to leak the asset URL into the render queue. The engine would then
+ * invoke the SSR handler, receive a non-HTML response (or an HTML
+ * error page), and write it to `.mandu/prerendered/hero.webp/index.html`
+ * — corrupting the static-asset dispatch for that URL on subsequent
+ * requests.
+ *
+ * Each entry is lowercased with a leading dot. Comparison is
+ * case-insensitive; the crawler strips query strings and hash
+ * fragments before extension testing.
+ *
+ * Extend or replace via `ManduConfig.build.crawl.assetExtensions` /
+ * `replaceDefaultAssetExtensions`.
+ */
+export const DEFAULT_ASSET_EXTENSIONS: readonly string[] = [
+  ".webp",
+  ".avif",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".svg",
+  ".ico",
+  ".pdf",
+  ".zip",
+  ".mp4",
+  ".webm",
+  ".mp3",
+  ".wav",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".css",
+  ".js",
+  ".map",
+  ".json",
+  ".xml",
+  ".txt",
+];
+
+/**
+ * Issue #216 — aggregate error thrown when one or more routes fail
+ * during prerender (and `skipErrors !== true`). Each entry carries the
+ * offending route pattern plus the underlying `cause`, so CI logs show
+ * both the symptom (the summary line) and the root cause chain.
+ */
+export class PrerenderError extends Error {
+  readonly errors: PrerenderRouteError[];
+
+  constructor(errors: PrerenderRouteError[]) {
+    const summary = errors
+      .map((e) => `  - [${e.pattern}] ${e.message}`)
+      .join("\n");
+    super(
+      `Prerender failed for ${errors.length} route(s):\n${summary}`,
+    );
+    this.name = "PrerenderError";
+    this.errors = errors;
+  }
+}
+
+export interface PrerenderRouteError {
+  /** The route pattern that failed (e.g. `/docs/:slug`). */
+  pattern: string;
+  /** Absolute module path that was loaded (or attempted). */
+  module: string;
+  /** Human-readable description of the failure. */
+  message: string;
+  /** The underlying error object, preserved for `cause` chaining. */
+  cause: unknown;
+}
+
 // ========== Implementation ==========
 
 /**
@@ -131,8 +311,10 @@ export async function prerenderRoutes(
     rootDir,
     outDir = LEGACY_PRERENDER_DIR,
     crawl = false,
+    crawlOptions,
     writeIndex = false,
     importModule,
+    skipErrors = false,
   } = options;
 
   // Phase 18.τ — resolve plugin hook bundle once so the hot render loop
@@ -150,9 +332,23 @@ export async function prerenderRoutes(
 
   const pages: PrerenderPageResult[] = [];
   const errors: string[] = [];
+  /**
+   * Issue #216 — structured per-route errors used to build the
+   * aggregate thrown at the end of the run. `errors` (the flat string
+   * array on `PrerenderResult`) is preserved for backward-compat.
+   */
+  const routeErrors: PrerenderRouteError[] = [];
   const renderedPaths = new Set<string>();
   const pageIndex: Record<string, string> = {};
 
+  // Issue #213 — compile the crawl denylist (defaults ∪ user extras, or
+  // user's replacement list) into an array of regexes once. Doing this
+  // outside the per-page crawl loop avoids recompiling N times.
+  const crawlDenylist = compileCrawlDenylist(crawlOptions);
+  // Issue #219 — resolve the non-HTML asset extension set once. Same
+  // rationale: the crawl loop runs N times, set lookup is O(1).
+  const crawlAssetExtensions = resolveAssetExtensions(crawlOptions);
+
   // 1. Explicit user-supplied routes.
   const pathsToRender = new Set<string>(options.routes ?? []);
 
@@ -170,12 +366,34 @@ export async function prerenderRoutes(
   for (const route of manifest.routes) {
     if (route.kind !== "page" || !isDynamicPattern(route.pattern)) continue;
 
+    // ─── Issue #216 ─────────────────────────────────────────────────────────
+    // Distinguish the three failure modes that were previously collapsed
+    // into a single `try/catch` silent skip:
+    //
+    //   1. Module export missing (`generateStaticParams` is undefined)
+    //      → legitimate "page doesn't opt into static params"; silent skip.
+    //   2. Module fails to load (compile error, missing import, etc.)
+    //      → real bug, surface with route + cause chain.
+    //   3. User's `generateStaticParams` throws or returns non-array
+    //      → real bug, surface with route + cause chain.
+    //
+    // The orchestrator still continues with the remaining routes so one
+    // broken page doesn't block the whole build; we just collect each
+    // failure in `routeErrors` and re-raise as a `PrerenderError` once
+    // the run finishes (unless `skipErrors === true`).
+    // ─── End Issue #216 ─────────────────────────────────────────────────────
     let mod: PageModuleWithStaticParams;
     try {
       mod = await loadPageModule(rootDir, route, resolveModule);
-    } catch {
-      // Module failed to load entirely. Silent skip — the page may
-      // simply not opt into static params; SSR can still serve it.
+    } catch (loadErr) {
+      const message = `Failed to load page module for prerender of "${route.pattern}" (${route.module}): ${describeError(loadErr)}`;
+      errors.push(`[${route.pattern}] ${message}`);
+      routeErrors.push({
+        pattern: route.pattern,
+        module: route.module,
+        message,
+        cause: loadErr,
+      });
       continue;
     }
 
@@ -190,7 +408,9 @@ export async function prerenderRoutes(
     // ─── End Issue #214 ─────────────────────────────────────────────────────
 
     if (typeof mod.generateStaticParams !== "function") {
-      // Not opted-in for this route — perfectly fine.
+      // Issue #216 — legitimate "no export" case. This is the only
+      // silent skip that survives the hardening: the whole point of
+      // the feature is that exporting the function is optional.
       continue;
     }
 
@@ -201,7 +421,19 @@ export async function prerenderRoutes(
         paramSets,
       } = await collectStaticPaths(route.pattern, mod);
       for (const p of paths) pathsToRender.add(p);
-      for (const e of paramErrors) errors.push(`[${route.pattern}] ${e}`);
+      for (const e of paramErrors) {
+        errors.push(`[${route.pattern}] ${e}`);
+        // Validation errors from individual param sets are already
+        // fine-grained (`generateStaticParams()[i] for "pattern": ...`);
+        // promote them to route-level errors so the aggregate surfaces
+        // them too.
+        routeErrors.push({
+          pattern: route.pattern,
+          module: route.module,
+          message: e,
+          cause: new Error(e),
+        });
+      }
 
       // ─── Issue #214 ───────────────────────────────────────────────────────
       // Persist the resolved param sets on the spec. The runtime #214 guard
@@ -214,11 +446,17 @@ export async function prerenderRoutes(
       }
       // ─── End Issue #214 ───────────────────────────────────────────────────
     } catch (error) {
-      // User code threw. Surface the error but keep going — other
-      // routes should not be blocked by one buggy generator.
-      errors.push(
-        `[${route.pattern}] generateStaticParams threw: ${describeError(error)}`
-      );
+      // Issue #216 — user's `generateStaticParams` threw. Capture with
+      // context (pattern + module + cause) so `PrerenderError` can
+      // rebuild a proper chain.
+      const message = `generateStaticParams threw: ${describeError(error)}`;
+      errors.push(`[${route.pattern}] ${message}`);
+      routeErrors.push({
+        pattern: route.pattern,
+        module: route.module,
+        message,
+        cause: error,
+      });
     }
   }
 
@@ -283,7 +521,11 @@ export async function prerenderRoutes(
 
       // 5. Optional crawl — harvest internal links for next pass.
       if (crawl) {
-        const links = extractInternalLinks(html);
+        // Issue #213 — strip code regions + apply denylist before adding
+        // discovered paths to the render queue.
+        // Issue #219 — also filter out asset URLs (`/hero.webp`, etc.)
+        // so the engine doesn't try to render them as HTML.
+        const links = extractInternalLinks(html, crawlDenylist, crawlAssetExtensions);
         for (const link of links) {
           if (!renderedPaths.has(link) && !pathsToRender.has(link)) {
             pathsToRender.add(link);
@@ -309,6 +551,13 @@ export async function prerenderRoutes(
     );
   }
 
+  // 7. Issue #216 — if any route errored, surface as aggregate so CI
+  //    can exit non-zero. `skipErrors: true` converts errors to
+  //    warnings (collected in `errors` + the returned result).
+  if (routeErrors.length > 0 && !skipErrors) {
+    throw new PrerenderError(routeErrors);
+  }
+
   return {
     generated: pages.length,
     pages,
@@ -419,19 +668,182 @@ function getOutputPath(outDir: string, pathname: string): string {
   return path.join(outDir, decoded, "index.html");
 }
 
-/** Extract absolute internal `<a href>` paths (same-origin only). */
-function extractInternalLinks(html: string): string[] {
+/**
+ * Issue #213 — strip regions of HTML/MDX that only contain illustrative
+ * markup (doc code examples) before scanning for crawl targets.
+ *
+ * The order below is deliberate:
+ *   1. HTML comments (`<!-- ... -->`) — may wrap real `<a>` / `<code>`
+ *      tags users don't want crawled.
+ *   2. Fenced markdown code blocks (``` ... ```), including ~~~-fenced.
+ *   3. Block HTML code containers (`<pre>...</pre>`, `<code>...</code>`,
+ *      including attributes like `<pre class="language-tsx">`).
+ *   4. Inline-code backticks (`` `...` ``).
+ *
+ * Each strip uses a non-greedy, multiline-aware regex. The replacements
+ * are whitespace-only so line-based tools don't get confused, but the
+ * string lengths stay similar (we don't need precise positions — we only
+ * re-scan for `href` attributes after the strip).
+ *
+ * Exported for test coverage.
+ */
+export function stripCodeRegions(html: string): string {
+  let out = html;
+  // 1. HTML comments — nested and multiline.
+  out = out.replace(/<!--[\s\S]*?-->/g, "");
+  // 2. Fenced markdown code blocks — both ``` and ~~~ fences.
+  //    Allow optional info string on the opening fence.
+  out = out.replace(/```[^\n]*\n[\s\S]*?```/g, "");
+  out = out.replace(/~~~[^\n]*\n[\s\S]*?~~~/g, "");
+  // 3. <pre>...</pre> (case-insensitive, attributes allowed).
+  out = out.replace(/<pre\b[^>]*>[\s\S]*?<\/pre>/gi, "");
+  // 4. <code>...</code> (case-insensitive, attributes allowed).
+  out = out.replace(/<code\b[^>]*>[\s\S]*?<\/code>/gi, "");
+  // 5. Inline markdown code spans — single backtick pairs. Avoid
+  //    matching stray backticks by limiting to same-line and
+  //    disallowing embedded backticks.
+  out = out.replace(/`[^`\r\n]+`/g, "");
+  return out;
+}
+
+/**
+ * Issue #213 — compile the crawl denylist from options + defaults into
+ * an array of regexes once. Accepts exact strings and simple globs where
+ * `*` translates to `.*` (anchored).
+ */
+export function compileCrawlDenylist(
+  options: PrerenderCrawlOptions | undefined,
+): RegExp[] {
+  const defaults = options?.replaceDefaultExclude
+    ? []
+    : DEFAULT_CRAWL_DENYLIST;
+  const extras = options?.exclude ?? [];
+  const combined = Array.from(new Set([...defaults, ...extras]));
+  return combined.map((entry) => denylistEntryToRegex(entry));
+}
+
+function denylistEntryToRegex(entry: string): RegExp {
+  // Escape everything except `*`, then translate `*` → `.*`.
+  const escaped = entry.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Issue #219 — resolve the effective asset extension set from options.
+ *
+ * Normalizes every entry to `.lowercase` with a leading dot (so users
+ * can write `"webp"` or `".WEBP"`), merges with
+ * {@link DEFAULT_ASSET_EXTENSIONS} unless `replaceDefaultAssetExtensions`
+ * is `true`, and returns a `Set<string>` for O(1) lookup in the crawl
+ * loop.
+ *
+ * Exported for test coverage.
+ */
+export function resolveAssetExtensions(
+  options: PrerenderCrawlOptions | undefined,
+): Set<string> {
+  const defaults = options?.replaceDefaultAssetExtensions
+    ? []
+    : DEFAULT_ASSET_EXTENSIONS;
+  const extras = options?.assetExtensions ?? [];
+  const out = new Set<string>();
+  for (const ext of [...defaults, ...extras]) {
+    out.add(normalizeAssetExtension(ext));
+  }
+  return out;
+}
+
+function normalizeAssetExtension(ext: string): string {
+  const lower = ext.toLowerCase();
+  return lower.startsWith(".") ? lower : `.${lower}`;
+}
+
+/**
+ * Issue #219 — does the given pathname end with a known asset
+ * extension? Extracts the basename's extension (case-insensitive) and
+ * tests it against the resolved set.
+ *
+ * `pathname` is the normalized crawl path (query + hash already
+ * stripped by {@link normalizeCrawlPath}) — we still defend in depth
+ * by splitting on `?` / `#` in case a caller passes a raw href.
+ *
+ * Exported for test coverage.
+ */
+export function isAssetPathname(
+  pathname: string,
+  assetExtensions: Set<string>,
+): boolean {
+  if (assetExtensions.size === 0) return false;
+  const clean = pathname.split("?")[0].split("#")[0];
+  const lastSlash = clean.lastIndexOf("/");
+  const basename = lastSlash === -1 ? clean : clean.slice(lastSlash + 1);
+  const dot = basename.lastIndexOf(".");
+  if (dot === -1 || dot === 0) return false;
+  const ext = basename.slice(dot).toLowerCase();
+  return assetExtensions.has(ext);
+}
+
+/**
+ * Normalize a discovered pathname for de-duplication + matching.
+ * Lowercases (HTML href matching is case-insensitive) and strips a
+ * trailing slash except for the root.
+ */
+function normalizeCrawlPath(href: string): string {
+  const clean = href.split("?")[0].split("#")[0];
+  let norm = clean.toLowerCase();
+  if (norm.length > 1 && norm.endsWith("/")) {
+    norm = norm.slice(0, -1);
+  }
+  return norm;
+}
+
+/**
+ * Extract absolute internal `<a href>` paths (same-origin only).
+ *
+ * Issue #213 — strips HTML/MDX code regions before scanning so `href`
+ * attributes inside doc examples (e.g. `<pre><code>&lt;Link
+ * href="/example"&gt;</code></pre>` or fenced markdown) don't leak
+ * into the crawl queue. Also applies the configurable denylist so
+ * placeholder paths like `/path` or `/your-route` are filtered out.
+ *
+ * Issue #219 — filters out URLs whose pathname ends with a known
+ * non-HTML asset extension (`.webp`, `.avif`, `.pdf`, `.css`, …). This
+ * prevents the prerender engine from rendering `<img src>` / `<source
+ * srcset>` / `<a href="/whitepaper.pdf">` values as HTML and
+ * overwriting the real asset on disk. Pass a custom `Set` (e.g. built
+ * by {@link resolveAssetExtensions}) to extend or replace the default
+ * list; callers that want to disable the filter entirely may pass an
+ * empty `Set`.
+ *
+ * Ordering rationale: `stripCodeRegions` runs first so doc examples
+ * never reach the regex. The asset-extension filter runs AFTER the
+ * strip (so `<pre>` code doesn't contribute asset URLs) but BEFORE
+ * the denylist (Set.has is cheaper than an `Array.some` regex scan,
+ * and asset URLs are strictly orthogonal to placeholder denylist
+ * entries — see #213 vs #219).
+ *
+ * Exported for test coverage.
+ */
+export function extractInternalLinks(
+  html: string,
+  denylist: RegExp[] = [],
+  assetExtensions: Set<string> = resolveAssetExtensions(undefined),
+): string[] {
+  const stripped = stripCodeRegions(html);
   const links: string[] = [];
   const hrefRegex = /href=["']([^"']+)["']/g;
   let match: RegExpExecArray | null;
-  while ((match = hrefRegex.exec(html)) !== null) {
+  while ((match = hrefRegex.exec(stripped)) !== null) {
     const href = match[1];
-    if (href.startsWith("/") && !href.startsWith("//")) {
-      const cleanPath = href.split("?")[0].split("#")[0];
-      if (!cleanPath.match(/\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$/)) {
-        links.push(cleanPath);
-      }
-    }
+    if (!href.startsWith("/") || href.startsWith("//")) continue;
+    const normalized = normalizeCrawlPath(href);
+    if (!normalized) continue;
+    // Issue #219 — asset URLs (`.webp`, `.pdf`, `.css`, …) never get
+    // prerendered. This supersedes the old hard-coded regex.
+    if (isAssetPathname(normalized, assetExtensions)) continue;
+    if (denylist.some((re) => re.test(normalized))) continue;
+    links.push(normalized);
   }
   return [...new Set(links)];
 }

package/src/client/spa-nav-helper.ts

@@ -1,82 +1,92 @@
-/**
- * Issue #208 — Minimal inline SPA-navigation helper.
- *
- * Self-contained IIFE injected into the SSR `<head>` that upgrades plain
- * full-page navigations into client-side `history.pushState` +
- * `fetch` + DOM-swap transitions, without loading any JS bundle.
- *
- * Motivating use case: docs / blog / marketing sites that build with
- * `hydration: "none"` (no islands). Under Issue #193 the opt-out SPA
- * router lives in `@mandujs/core/client` (`router.ts`), which only ships
- * inside a hydration bundle. Zero-JS pages therefore lost the "feels
- * like a SPA" behavior that `spa: true` (the framework default) promises.
- *
- * This helper fills the gap: ~1.6 KB of inline JavaScript that the
- * browser parses and runs immediately, no module graph, no network
- * round-trip. Paired with the `@view-transition { navigation: auto }`
- * style block (#192) the result is a visually-animated pushState
- * navigation on every internal link click.
- *
- * Design constraints (locked — changing any of these needs an explicit
- * rationale in the PR):
- *
- *   1. **Exclusion parity with the full router** (`router.ts`
- *      `handleLinkClick`): every browser-owned escape hatch — modifier
- *      keys, non-left click, `target` other than `_self`, `download`,
- *      `mailto:` / `tel:` / `javascript:` / …, cross-origin, hash-only,
- *      no `href`, `data-no-spa`, and `event.defaultPrevented` — is
- *      checked here too. Regression matrix lives at
- *      `tests/client/spa-nav-helper-exclusions.test.ts`.
- *
- *   2. **Co-existence with the full router**: both handlers listen
- *      on `document` `click`. The helper bails out early when
- *      `window.__MANDU_ROUTER_STATE__` is present — that global is
- *      installed by `initializeRouter()` before it calls
- *      `addEventListener`, so on hydrated pages the full router wins.
- *      On pure-SSR pages the state global is missing and the helper
- *      is authoritative.
- *
- *   3. **View Transitions API** — we call
- *      `document.startViewTransition(cb)` when available, mirroring the
- *      `@view-transition` at-rule we already inject. Browsers without
- *      the API (Firefox, Safari < 18.2) execute the callback
- *      synchronously so the feature is a pure progressive enhancement.
- *
- *   4. **DOM swap strategy**: replace `document.body.innerHTML` using
- *      the parsed incoming document's `<body>`. This preserves the
- *      `<head>` across navigations (avoids re-running inline scripts
- *      like this helper) while still picking up `<title>` and
- *      `<meta>` changes via a selective head-element merge. We also
- *      reset `document.title`.
- *
- *   5. **Inline, not external**: same rationale as #192's prefetch
- *      helper — inline removes the extra round-trip on every SSR
- *      response, keeps the CSP posture simple (only two inline scripts:
- *      prefetch + spa-nav), and sidesteps the "zero-JS but loads one
- *      JS file anyway" awkwardness.
- *
- *   6. **Opt-out via `ssr.spa: false`**: the injection site
- *      (`ssr.ts::renderToHTML`, `streaming-ssr.ts::generateHTMLShell`)
- *      omits the `<script>` block entirely when the user's config sets
- *      `spa: false`. No runtime check needed inside the IIFE.
- *
- * The exported `SPA_NAV_HELPER_SCRIPT` wraps the IIFE in a
- * `<script>` tag, ready to paste into `<head>` alongside the prefetch
- * helper and `@view-transition` style block.
- *
- * Size target: ≤3 KB raw (currently ≈2.7 KB after the defensive
- * hardNav / DOMParser-availability guards). If this grows past 3 KB we
- * should revisit the inline-vs-external trade-off.
- */
-
-/**
- * Inner IIFE — exposed for unit tests that want to parse the source.
- *
- * Byte-minified on purpose (no comments, short names). The high-level
- * flow is documented in this file's JSDoc; anyone editing this string
- * MUST update the exclusion-matrix test to match.
- */
-export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;function hardNav(u){try{L.href=u;}catch(_){}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h||h.charAt(0)==="#")return null;var u;try{u=new URL(h,L.origin);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;return u;}function swap(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(nh&&ch){var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}var nb=doc.body;if(nb)document.body.innerHTML=nb.innerHTML;try{window.scrollTo(0,0);}catch(_){}}catch(_){}}function nav(url,push){fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok||!r.headers.get("content-type")||r.headers.get("content-type").indexOf("text/html")<0){hardNav(url);return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url);return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(_){hardNav(url);return;}if(push){try{H.pushState({mandu:1},"",url);}catch(_){hardNav(url);return;}}var run=function(){swap(doc);try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(_){run();}}else{run();}}).catch(function(){hardNav(url);});}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
-
-/** Ready-to-inject `<script>` tag for SSR `<head>` injection. */
-export const SPA_NAV_HELPER_SCRIPT = `<script>${SPA_NAV_HELPER_BODY}</script>`;
+/**
+ * Issue #208 — Minimal inline SPA-navigation helper.
+ * Issue #220 — body-swap observability + fallback + script re-execution.
+ *
+ * Self-contained IIFE injected into the SSR `<head>` that upgrades plain
+ * full-page navigations into client-side `history.pushState` +
+ * `fetch` + DOM-swap transitions, without loading any JS bundle.
+ *
+ * Motivating use case: docs / blog / marketing sites that build with
+ * `hydration: "none"` (no islands). Under Issue #193 the opt-out SPA
+ * router lives in `@mandujs/core/client` (`router.ts`), which only ships
+ * inside a hydration bundle. Zero-JS pages therefore lost the "feels
+ * like a SPA" behavior that `spa: true` (the framework default) promises.
+ *
+ * This helper fills the gap: ~2.8 KB of inline JavaScript that the
+ * browser parses and runs immediately, no module graph, no network
+ * round-trip. Paired with the `@view-transition { navigation: auto }`
+ * style block (#192) the result is a visually-animated pushState
+ * navigation on every internal link click.
+ *
+ * Design constraints (locked — changing any of these needs an explicit
+ * rationale in the PR):
+ *
+ *   1. **Exclusion parity with the full router** (`router.ts`
+ *      `handleLinkClick`): every browser-owned escape hatch — modifier
+ *      keys, non-left click, `target` other than `_self`, `download`,
+ *      `mailto:` / `tel:` / `javascript:` / …, cross-origin, hash-only,
+ *      no `href`, `data-no-spa`, and `event.defaultPrevented` — is
+ *      checked here too. Regression matrix lives at
+ *      `tests/client/spa-nav-helper-exclusions.test.ts`.
+ *
+ *   2. **Co-existence with the full router**: both handlers listen
+ *      on `document` `click`. The helper bails out early when
+ *      `window.__MANDU_ROUTER_STATE__` is present — that global is
+ *      installed by `initializeRouter()` before it calls
+ *      `addEventListener`, so on hydrated pages the full router wins.
+ *      On pure-SSR pages the state global is missing and the helper
+ *      is authoritative.
+ *
+ *   3. **View Transitions API** — we call
+ *      `document.startViewTransition(cb)` when available, mirroring the
+ *      `@view-transition` at-rule we already inject. Browsers without
+ *      the API (Firefox, Safari < 18.2) execute the callback
+ *      synchronously so the feature is a pure progressive enhancement.
+ *
+ *   4. **DOM swap strategy** (issue #220 rework):
+ *      - Prefer `<main>` → `<#root>` → whole `<body>` (in that order).
+ *        We log which container matched via `console.debug`.
+ *      - Scripts inside the swapped region are extracted and
+ *        re-executed via `document.createElement("script")` so
+ *        island bootstraps / inline user scripts still fire.
+ *      - Head `<title>` + selective meta tags are merged from the
+ *        incoming document.
+ *
+ *   5. **Observability + fallback** (issue #220): every failure path
+ *      (fetch !ok, DOMParser unavailable, parser error, no container
+ *      matched, exception inside swap, exception inside
+ *      startViewTransition) logs a `console.warn("[mandu-spa-nav] …")`
+ *      and performs a hard navigation (`location.href = url`) so the
+ *      user always sees fresh content. No silent stuck-URL state.
+ *
+ *   6. **Hydration marker** (issue #220): after a successful swap we
+ *      dispatch `__MANDU_SPA_NAV__` on `window` with
+ *      `detail: { url, durationMs, container }` so islands and
+ *      integrations can re-hydrate if needed.
+ *
+ *   7. **Inline, not external**: same rationale as #192's prefetch
+ *      helper — inline removes the extra round-trip on every SSR
+ *      response, keeps the CSP posture simple, and sidesteps the
+ *      "zero-JS but loads one JS file anyway" awkwardness.
+ *
+ *   8. **Opt-out via `ssr.spa: false`**: the injection site
+ *      (`ssr.ts::renderToHTML`, `streaming-ssr.ts::generateHTMLShell`)
+ *      omits the `<script>` block entirely when the user's config sets
+ *      `spa: false`. No runtime check needed inside the IIFE.
+ *
+ * Size target: ≤3 KB gzipped (currently ≈2.8 KB raw, ≈1.4 KB gz). If
+ * this grows past 3 KB gz we should revisit the inline-vs-external
+ * trade-off.
+ */
+
+/**
+ * Inner IIFE — exposed for unit tests that want to parse the source.
+ *
+ * Byte-minified on purpose (no comments, short names). The high-level
+ * flow is documented in this file's JSDoc; anyone editing this string
+ * MUST update the exclusion-matrix test and the body-swap test to match.
+ */
+export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h||h.charAt(0)==="#")return null;var u;try{u=new URL(h,L.origin);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);try{window.scrollTo(0,0);}catch(_){}var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
+
+/** Ready-to-inject `<script>` tag for SSR `<head>` injection. */
+export const SPA_NAV_HELPER_SCRIPT = `<script>${SPA_NAV_HELPER_BODY}</script>`;

package/src/config/mandu.ts

@@ -197,6 +197,60 @@ export interface ManduConfig {
      * writes JSON only (useful for CI, skips the HTML render cost).
      */
     analyze?: boolean;
+    /**
+     * Issue #213 — tune the prerender link-crawler.
+     *
+     * The crawler (enabled by `mandu build` when `build.prerender !== false`)
+     * scans rendered HTML for `<a href="/...">` and enqueues those paths
+     * for prerendering. Doc sites that ship code examples (`<pre><code>
+     * &lt;Link href="/path" /&gt;</code></pre>`) previously leaked those
+     * illustrative URLs into the render queue, producing spurious
+     * `.mandu/static/path/index.html` files.
+     *
+     * The engine strips `<pre>`, `<code>`, fenced markdown, and inline
+     * code spans before scanning. It also applies a small default
+     * denylist of placeholder paths (`/path`, `/example`, `/your-*`,
+     * etc.). Use this block to extend or replace the denylist for your
+     * project.
+     */
+    crawl?: {
+      /**
+       * Extra pathnames or simple globs (`*`) to exclude when crawling.
+       * Merged with the built-in default denylist unless
+       * {@link replaceDefaultExclude} is `true`.
+       */
+      exclude?: string[];
+      /**
+       * When `true`, `exclude` replaces the built-in denylist entirely.
+       * Default `false`.
+       */
+      replaceDefaultExclude?: boolean;
+      /**
+       * Issue #219 — file extensions treated as non-HTML assets. When
+       * a discovered href's pathname ends with one of these, the
+       * crawler skips it instead of enqueuing it for prerender.
+       *
+       * Example: `<picture><source srcset="/hero.avif"><img
+       * src="/hero.webp"></picture>` used to make the engine render
+       * the asset URL as HTML and overwrite the real `.webp` on disk.
+       * The default set covers common image / font / document /
+       * media / text-asset extensions.
+       *
+       * Entries may be written with or without a leading dot
+       * (`"webp"` and `".webp"` are equivalent). Matching is
+       * case-insensitive; query strings and hash fragments are
+       * stripped before comparison.
+       *
+       * Merged with the built-in default set unless
+       * {@link replaceDefaultAssetExtensions} is `true`.
+       */
+      assetExtensions?: string[];
+      /**
+       * When `true`, `assetExtensions` replaces the built-in set
+       * entirely. Default `false`.
+       */
+      replaceDefaultAssetExtensions?: boolean;
+    };
   };
   dev?: {
     hmr?: boolean;

package/src/config/validate.ts

@@ -119,6 +119,33 @@ const GuardConfigSchema = z
   })
   .strict();
 
+/**
+ * Issue #213 — prerender link-crawler sub-block (strict).
+ *
+ * `exclude` entries are matched against the normalized crawl target:
+ *   - Exact string (`"/example"`): matches that pathname only.
+ *   - Simple glob (`"/your-*"`): `*` → `.*`, anchored start + end.
+ *
+ * When `replaceDefaultExclude === true`, `exclude` replaces the built-in
+ * default denylist entirely. Otherwise (default), user entries are
+ * merged on top of the defaults.
+ *
+ * Issue #219 — `assetExtensions` filters out non-HTML asset URLs
+ * (`.webp`, `.pdf`, `.css`, …) from the crawl queue so the engine
+ * doesn't overwrite real assets with rendered HTML. Entries may be
+ * written with or without a leading dot; matching is case-insensitive.
+ * Merges with the built-in defaults unless
+ * `replaceDefaultAssetExtensions === true`.
+ */
+const BuildCrawlConfigSchema = z
+  .object({
+    exclude: z.array(z.string().min(1)).default([]),
+    replaceDefaultExclude: z.boolean().default(false),
+    assetExtensions: z.array(z.string().min(1)).default([]),
+    replaceDefaultAssetExtensions: z.boolean().default(false),
+  })
+  .strict();
+
 /**
  * Build 설정 스키마 (strict)
  */
@@ -141,6 +168,12 @@ const BuildConfigSchema = z
      * for this project" switch.
      */
     analyze: z.boolean().default(false),
+    /**
+     * Issue #213 — prerender link-crawler denylist. See
+     * {@link BuildCrawlConfigSchema}. Omit the block to trust the
+     * default (strip code regions + built-in placeholder denylist).
+     */
+    crawl: BuildCrawlConfigSchema.optional(),
   })
   .strict();
 

package/src/runtime/server.ts

@@ -597,6 +597,25 @@ export interface ServerOptions {
    * use `ctx.locale.code` and ignore `ctx.t`.
    */
   messages?: MessageRegistry;
+  /**
+   * Issue #217 — suppress the "🥟 Mandu server listening"/"🥟 Mandu Dev
+   * Server listening" banner printed at boot. The HTTP listener still
+   * binds and `ManduServer.server.port` still reports the chosen port;
+   * only the stdout banner (plus its auxiliary lines — HMR hint, CORS
+   * hint, static-file hint, streaming hint, Kitchen hint, "also
+   * reachable at" hint) is gated.
+   *
+   * Intended for internal callers such as the build-time prerender
+   * orchestrator that spin up a transient listener on an ephemeral
+   * port (`port: 0`) and tear it down seconds later — the banner's
+   * URL is always wrong by the time a human (or an LLM reading build
+   * logs) tries to curl it, so printing it causes confusion.
+   *
+   * User-facing commands (`mandu dev`, `mandu start`) leave this
+   * `undefined` / `false` to preserve the normal banner. Default:
+   * `false`.
+   */
+  silent?: boolean;
 }
 
 export interface ManduServer {
@@ -1325,6 +1344,155 @@ function createStaticErrorResponse(status: 400 | 403 | 404 | 500): Response {
   return new Response(body, { status });
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Static asset cache policy — Issue #218
+//
+// The `immutable` Cache-Control directive is a *contract* with browsers:
+// "the bytes at this URL will never change." Violating it (by overwriting a
+// stable-name file between builds) means users keep stale CSS/JS until they
+// hard-refresh. Mandu historically emitted `/.mandu/client/globals.css`
+// and `/.mandu/client/runtime*.js` with fixed URLs but stamped the response
+// with `immutable`, which is the exact failure mode.
+//
+// Policy:
+//   - Hashed URL  (e.g. `.../chunk.a1b2c3d4.js`) → `immutable` is safe,
+//     1-year max-age.
+//   - Stable URL  (no hash in filename) → `max-age=0, must-revalidate`.
+//     The client revalidates on every request; a matching `If-None-Match`
+//     short-circuits to 304 with no body, so the cost is one HEAD-sized
+//     round-trip, not a full re-download.
+//
+// Strong ETag (content-hash) is emitted for every `/.mandu/client/*`
+// response so conditional GETs are cheap. We use `Bun.hash` (wyhash, ~5GB/s)
+// for the digest and cache results keyed by `path + size + mtime` to avoid
+// re-hashing on every hit.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Heuristic: does the filename look like it carries a content hash?
+ *
+ * Matches:
+ *   - `name.<hash>.ext`      where hash is >=8 hex chars (e.g. `chunk.a1b2c3d4.js`)
+ *   - `name-<hash>.ext`      (e.g. `vendor-8f3a2b9c.js`)
+ *   - `name.<hash>.chunk.ext` common bundler shape
+ *
+ * A hash segment is 8+ lowercase hex chars. Longer digests (16, 20, 32) also
+ * match. We deliberately avoid matching ALL-hex short names like `abc.js`
+ * (requires min length 8).
+ */
+function hasContentHashInFilename(filename: string): boolean {
+  // `.` or `-` separator, 8+ hex chars, then `.` before extension
+  // Examples that match: chunk.a1b2c3d4.js, vendor-8f3a2b9c.js, app.1234567890abcdef.css
+  // Examples that DON'T match: globals.css, runtime.js, chunk.js
+  return /[.\-][a-f0-9]{8,}\.[a-z0-9]+$/i.test(filename);
+}
+
+/**
+ * Compute Cache-Control for a static asset.
+ *
+ * - Dev: no caching (always refetch).
+ * - Prod, hashed filename: `public, max-age=31536000, immutable` (1 year).
+ * - Prod, stable filename: `public, max-age=0, must-revalidate` (force
+ *   revalidation; 304 via `If-None-Match` keeps it cheap).
+ */
+function computeStaticCacheControl(filename: string, isDev: boolean): string {
+  if (isDev) return "no-cache, no-store, must-revalidate";
+  if (hasContentHashInFilename(filename)) {
+    return "public, max-age=31536000, immutable";
+  }
+  return "public, max-age=0, must-revalidate";
+}
+
+/**
+ * In-process ETag cache keyed by absolute filePath. Entry is invalidated
+ * when `size` or `mtime` changes. Avoids re-hashing hot files on every
+ * request. The hot path is a single lookup + two scalar compares.
+ */
+interface EtagCacheEntry {
+  size: number;
+  mtime: number;
+  etag: string;
+}
+const etagCache = new Map<string, EtagCacheEntry>();
+const ETAG_CACHE_MAX = 2048;
+
+/** Cheap LRU eviction: drop oldest insert when over cap. */
+function evictEtagCacheIfNeeded(): void {
+  if (etagCache.size <= ETAG_CACHE_MAX) return;
+  const oldestKey = etagCache.keys().next().value;
+  if (oldestKey !== undefined) etagCache.delete(oldestKey);
+}
+
+/**
+ * Compute a strong ETag from file bytes (Bun.hash / wyhash). Cached by
+ * `path + size + mtime` so we only re-hash when the file changes.
+ *
+ * Strong (not weak `W/`) because we actually hashed the payload — this
+ * preserves byte-range / delta semantics per RFC 7232.
+ */
+async function computeStrongEtag(
+  filePath: string,
+  file: import("bun").BunFile,
+): Promise<string> {
+  const size = file.size;
+  const mtime = file.lastModified;
+
+  const cached = etagCache.get(filePath);
+  if (cached && cached.size === size && cached.mtime === mtime) {
+    return cached.etag;
+  }
+
+  // Bun.hash returns a number/bigint; stringify in base36 for compact ETag.
+  // Fall back to size+mtime-derived ETag if hashing ever throws (edge-runtime
+  // polyfills etc. — `Bun.hash` is a Bun-native primitive).
+  let digest: string;
+  try {
+    const bytes = await file.arrayBuffer();
+    const h = Bun.hash(bytes);
+    digest = typeof h === "bigint" ? h.toString(36) : Number(h).toString(36);
+  } catch {
+    digest = `${size.toString(36)}-${mtime.toString(36)}`;
+  }
+
+  const etag = `"${digest}"`;
+  etagCache.set(filePath, { size, mtime, etag });
+  evictEtagCacheIfNeeded();
+  return etag;
+}
+
+/** Exposed for tests — allows clearing the ETag cache between cases. */
+export function __clearStaticEtagCacheForTests(): void {
+  etagCache.clear();
+}
+
+/**
+ * RFC 7232 §3.2 — `If-None-Match` comparison.
+ *
+ * Accepts:
+ *   - `*` wildcard (matches any current representation)
+ *   - a single ETag (`"abc"` or `W/"abc"`)
+ *   - a comma-separated list
+ *
+ * Uses weak-comparison semantics (strip leading `W/`) because that is the
+ * RFC-prescribed form for `If-None-Match`; a strong server-side ETag still
+ * matches a weak client token if the opaque-string portion is equal.
+ */
+function matchesEtag(ifNoneMatch: string, currentEtag: string): boolean {
+  const trimmed = ifNoneMatch.trim();
+  if (trimmed === "*") return true;
+
+  const normalize = (tag: string): string => {
+    const t = tag.trim();
+    return t.startsWith("W/") ? t.slice(2) : t;
+  };
+
+  const currentNormalized = normalize(currentEtag);
+  for (const part of trimmed.split(",")) {
+    if (normalize(part) === currentNormalized) return true;
+  }
+  return false;
+}
+
 /**
  * 경로가 허용된 디렉토리 내에 있는지 검증
  * Path traversal 공격 방지
@@ -1441,26 +1609,39 @@ async function serveStaticFile(pathname: string, settings: ServerRegistrySetting
     }
 
     const mimeType = getMimeType(filePath);
+    const filename = path.basename(filePath);
 
-    // Cache-Control 헤더 설정
+    // Cache-Control — Issue #218: `immutable` is only safe when the URL
+    // contains a content hash. Stable-name bundles (globals.css, runtime.js)
+    // must use `max-age=0, must-revalidate` or clients will serve stale
+    // bytes until a hard refresh.
+    //
+    // Bundle files go through the hash-aware policy; non-bundle assets
+    // (public/*, favicon, etc.) keep the conservative 1-day cache they had
+    // before — they're user-controlled and unlikely to change per deploy.
     let cacheControl: string;
     if (settings.isDev) {
-      // 개발 모드: 캐시 없음
       cacheControl = "no-cache, no-store, must-revalidate";
     } else if (isBundleFile) {
-      // 프로덕션 번들: 1년 캐시 (파일명에 해시 포함 가정)
-      cacheControl = "public, max-age=31536000, immutable";
+      cacheControl = computeStaticCacheControl(filename, /* isDev */ false);
     } else {
-      // 프로덕션 일반 정적 파일: 1일 캐시
       cacheControl = "public, max-age=86400";
     }
 
-    // ETag: weak validator (파일 크기 + 최종 수정 시간)
-    const etag = `W/"${file.size.toString(36)}-${file.lastModified.toString(36)}"`;
-
-    // 304 Not Modified — 불필요한 전송 방지
+    // Strong ETag from content hash for bundle files — enables cheap 304
+    // round-trips when the client revalidates (`If-None-Match`).
+    // Non-bundle static files keep a weak size+mtime validator (same as
+    // pre-#218 behaviour) — we don't pay the hash cost for user-owned
+    // `public/*` content the framework doesn't control.
+    const etag = isBundleFile
+      ? await computeStrongEtag(filePath, file)
+      : `W/"${file.size.toString(36)}-${file.lastModified.toString(36)}"`;
+
+    // 304 Not Modified — unnecessary transfer avoidance. We compare the
+    // full `If-None-Match` string; RFC 7232 also allows a comma-separated
+    // list and `*`, so handle those two forms explicitly.
     const ifNoneMatch = request?.headers.get("If-None-Match");
-    if (ifNoneMatch === etag) {
+    if (ifNoneMatch && matchesEtag(ifNoneMatch, etag)) {
       return {
         handled: true,
         response: new Response(null, {
@@ -3979,6 +4160,11 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     messages: messagesOption,
     plugins: pluginsOption,
     configHooks: configHooksOption,
+    // #217 — internal flag: suppress the "listening" banner. Threaded
+    // through by `mandu build`'s transient prerender server so that
+    // ephemeral `port: 0` listeners don't confuse humans/LLMs with a
+    // URL that's already torn down by the time they curl it.
+    silent = false,
   } = options;
 
   // Phase 18.μ — validate i18n + messages shape. Both are branded via
@@ -4262,31 +4448,43 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
 
   const addresses = formatServerAddresses(hostname, actualPort);
 
-  if (isDev) {
-    console.log(`🥟 Mandu Dev Server listening at ${addresses.primary}`);
-    if (addresses.additional.length > 0) {
-      console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
-    }
-    if (registry.settings.hmrPort) {
-      console.log(`🔥 HMR enabled on port ${registry.settings.hmrPort + PORTS.HMR_OFFSET}`);
-    }
-    console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
-    if (corsOptions) {
-      console.log(`🌐 CORS enabled`);
-    }
-    if (streaming) {
-      console.log(`🌊 Streaming SSR enabled`);
-    }
-    if (registry.kitchen) {
-      console.log(`🍳 Kitchen dashboard at ${addresses.primary}/__kitchen`);
-    }
-  } else {
-    console.log(`🥟 Mandu server listening at ${addresses.primary}`);
-    if (addresses.additional.length > 0) {
-      console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
-    }
-    if (streaming) {
-      console.log(`🌊 Streaming SSR enabled`);
+  // ─── #217 — gate the boot banner on `!silent` ─────────────────────────
+  // `silent: true` is passed by internal callers that spawn a transient
+  // listener on an ephemeral port (e.g. the build-time prerender
+  // orchestrator). The HTTP listener still binds; only the stdout banner
+  // — "🥟 Mandu server listening" / "🥟 Mandu Dev Server listening" plus
+  // its auxiliary lines (additional addresses, HMR, static-file hint,
+  // CORS, streaming, Kitchen) — is suppressed. User-facing commands
+  // (`mandu dev`, `mandu start`) leave `silent` undefined/false and
+  // therefore see the banner unchanged.
+  // ─── End #217 ─────────────────────────────────────────────────────────
+  if (!silent) {
+    if (isDev) {
+      console.log(`🥟 Mandu Dev Server listening at ${addresses.primary}`);
+      if (addresses.additional.length > 0) {
+        console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
+      }
+      if (registry.settings.hmrPort) {
+        console.log(`🔥 HMR enabled on port ${registry.settings.hmrPort + PORTS.HMR_OFFSET}`);
+      }
+      console.log(`📂 Static files: /${publicDir}/, /.mandu/client/`);
+      if (corsOptions) {
+        console.log(`🌐 CORS enabled`);
+      }
+      if (streaming) {
+        console.log(`🌊 Streaming SSR enabled`);
+      }
+      if (registry.kitchen) {
+        console.log(`🍳 Kitchen dashboard at ${addresses.primary}/__kitchen`);
+      }
+    } else {
+      console.log(`🥟 Mandu server listening at ${addresses.primary}`);
+      if (addresses.additional.length > 0) {
+        console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
+      }
+      if (streaming) {
+        console.log(`🌊 Streaming SSR enabled`);
+      }
     }
   }