@mandujs/core 0.26.0 → 0.28.0

package/package.json

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

package/src/bundler/build.ts

@@ -16,6 +16,8 @@ import type {
 import { HYDRATION } from "../constants";
 import { safeBuild } from "./safe-build";
 import { fastRefreshPlugin } from "./fast-refresh-plugin";
+import { defaultBundlerPlugins } from "./plugins";
+import type { BunPlugin } from "bun";
 import { mark, measure } from "../perf";
 import { HMR_PERF } from "../perf/hmr-markers";
 import {
@@ -29,6 +31,24 @@ import {
 import path from "path";
 import fs from "fs/promises";
 
+/**
+ * Resolve Mandu's default bundler plugin set from a `BundlerOptions`
+ * object. Currently returns the `mandu:block-generated-imports` plugin
+ * unless `options.blockGeneratedImport === false`. Centralised here so
+ * every `safeBuild(...)` call-site can compose
+ * `[...manduDefaultPlugins(options), ...buildLocalPlugins]` and stay in
+ * sync as the default set grows.
+ */
+function manduDefaultPlugins(options: BundlerOptions): BunPlugin[] {
+  return defaultBundlerPlugins({
+    config: {
+      guard: {
+        blockGeneratedImport: options.blockGeneratedImport,
+      },
+    },
+  });
+}
+
 /**
  * Scan for *.island.tsx / *.island.ts files across hydrated route directories.
  *
@@ -121,7 +141,7 @@ async function buildPerIslandBundle(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: isDev ? [fastRefreshPlugin()] : [],
+      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: { "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"), ...options.define },
     });
@@ -1063,6 +1083,7 @@ if (typeof window !== 'undefined') {
       minify: false, // dev only
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      plugins: manduDefaultPlugins(options),
       // React를 인라인 번들링 (import map 없이도 독립 동작)
       // DevTools는 Shadow DOM 격리 → 앱 React와 충돌 없음
       define: {
@@ -1117,6 +1138,7 @@ async function buildRouterRuntime(
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
+      plugins: manduDefaultPlugins(options),
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
         ...options.define,
@@ -1193,6 +1215,7 @@ async function buildRuntime(
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
       external: ["react", "react-dom", "react-dom/client"],
+      plugins: manduDefaultPlugins(options),
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
         ...options.define,
@@ -1482,6 +1505,7 @@ async function buildVendorShims(
         sourcemap: options.sourcemap ? "external" : "none",
         target: "browser",
         external: shimExternal,
+        plugins: manduDefaultPlugins(options),
         define: {
           "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
           ...options.define,
@@ -1590,7 +1614,7 @@ async function buildIsland(
       target: "browser",
       splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
       ...(isDev ? { reactFastRefresh: true } : {}),
-      plugins: isDev ? [fastRefreshPlugin()] : [],
+      plugins: [...manduDefaultPlugins(options), ...(isDev ? [fastRefreshPlugin()] : [])],
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),

package/src/bundler/index.ts

@@ -7,3 +7,4 @@ export * from "./types";
 export * from "./build";
 export * from "./dev";
 export * from "./css";
+export * from "./plugins";

package/src/bundler/plugins/__tests__/block-generated-imports.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Regression tests for `mandu:block-generated-imports` (issue #207).
+ *
+ * Split into two sections:
+ *   A — pure unit tests on `ForbiddenGeneratedImportError` + helpers.
+ *   B — integration tests driving a real `Bun.build` with a synthetic
+ *       `__generated__/` import in a tmpdir, asserting the build fails
+ *       with the expected error text.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+
+import {
+  ForbiddenGeneratedImportError,
+  blockGeneratedImports,
+  defaultAllowImporter,
+  DEFAULT_BLOCK_FILTER,
+  defaultBundlerPlugins,
+} from "../index";
+import { GENERATED_IMPORT_DOCS_URL } from "../../../guard/check";
+
+// ────────────────────────────────────────────────────────────────────
+// Section A — unit
+// ────────────────────────────────────────────────────────────────────
+
+describe("ForbiddenGeneratedImportError", () => {
+  test("captures specifier and importer fields", () => {
+    const err = new ForbiddenGeneratedImportError(
+      "./__generated__/routes",
+      "/repo/src/app.ts",
+    );
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(ForbiddenGeneratedImportError);
+    expect(err.specifier).toBe("./__generated__/routes");
+    expect(err.importer).toBe("/repo/src/app.ts");
+    expect(err.docsUrl).toBe(GENERATED_IMPORT_DOCS_URL);
+    expect(err.name).toBe("ForbiddenGeneratedImportError");
+  });
+
+  test("message includes specifier, importer, docs URL, and getGenerated() hint", () => {
+    const err = new ForbiddenGeneratedImportError(
+      "./__generated__/data",
+      "/repo/src/page.tsx",
+    );
+    expect(err.message).toContain("./__generated__/data");
+    expect(err.message).toContain("/repo/src/page.tsx");
+    expect(err.message).toContain(GENERATED_IMPORT_DOCS_URL);
+    expect(err.message).toContain("getGenerated");
+    expect(err.message).toContain('@mandujs/core/runtime');
+  });
+
+  test("message falls back to <unknown> importer when empty", () => {
+    const err = new ForbiddenGeneratedImportError("./__generated__/x", "");
+    expect(err.message).toContain("<unknown>");
+  });
+});
+
+describe("defaultAllowImporter", () => {
+  test("exempts packages/core/src/runtime/** paths", () => {
+    expect(
+      defaultAllowImporter("/repo/packages/core/src/runtime/registry.ts"),
+    ).toBe(true);
+  });
+
+  test("normalises Windows backslashes", () => {
+    expect(
+      defaultAllowImporter(
+        "C:\\repo\\packages\\core\\src\\runtime\\registry.ts",
+      ),
+    ).toBe(true);
+  });
+
+  test("does NOT exempt regular user code", () => {
+    expect(defaultAllowImporter("/repo/src/app.ts")).toBe(false);
+    expect(defaultAllowImporter("")).toBe(false);
+  });
+});
+
+describe("DEFAULT_BLOCK_FILTER", () => {
+  test("matches __generated__ specifiers", () => {
+    expect("./__generated__/foo").toMatch(DEFAULT_BLOCK_FILTER);
+    expect("../../src/__generated__/routes").toMatch(DEFAULT_BLOCK_FILTER);
+  });
+  test("does NOT match look-alikes without double underscores", () => {
+    expect("./generated/foo".match(DEFAULT_BLOCK_FILTER)).toBeNull();
+    expect("./src/generate/foo".match(DEFAULT_BLOCK_FILTER)).toBeNull();
+  });
+});
+
+describe("defaultBundlerPlugins", () => {
+  test("installs block-generated-imports by default", () => {
+    const plugins = defaultBundlerPlugins();
+    expect(plugins).toHaveLength(1);
+    expect(plugins[0]?.name).toBe("mandu:block-generated-imports");
+  });
+
+  test("respects opt-out via guard.blockGeneratedImport === false", () => {
+    const plugins = defaultBundlerPlugins({
+      config: { guard: { blockGeneratedImport: false } },
+    });
+    expect(plugins).toHaveLength(0);
+  });
+
+  test("treats undefined as default-on", () => {
+    const plugins = defaultBundlerPlugins({ config: { guard: {} } });
+    expect(plugins).toHaveLength(1);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────
+// Section B — integration against real Bun.build
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Integration tests invoke real `Bun.build`. On shards where the
+ * Windows `onResolve` panic is flaky, set `MANDU_SKIP_BUNDLER_TESTS=1`
+ * to skip — matches the convention used by `fast-refresh.test.ts`.
+ */
+const SKIP_BUNDLER = process.env.MANDU_SKIP_BUNDLER_TESTS === "1";
+
+describe.skipIf(SKIP_BUNDLER)("blockGeneratedImports — Bun.build integration", () => {
+  let tmpRoot: string;
+
+  beforeAll(async () => {
+    tmpRoot = await mkdtemp(path.join(tmpdir(), "mandu-block-gen-"));
+  });
+
+  afterAll(async () => {
+    await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+  });
+
+  test("Bun.build fails when source imports a __generated__ file", async () => {
+    const dir = path.join(tmpRoot, "scenario-block");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { routes } from "./__generated__/data";\nconsole.log(routes);\n`,
+    );
+
+    // Bun's plugin host surfaces a thrown onResolve error either as an
+    // exception from `Bun.build(...)` OR as an unsuccessful result whose
+    // logs contain the message. Accept either shape so the assertion is
+    // robust across Bun patch releases.
+    // Bun's plugin host surfaces a thrown onResolve error via multiple
+    // channels across patch releases: an exception from `Bun.build()`
+    // (with `AggregateError.errors[]` on recent versions), or an
+    // unsuccessful `result.logs[]`. Collect from every channel and assert
+    // the aggregated text.
+    const collected: string[] = [];
+    try {
+      const result = await Bun.build({
+        entrypoints: [path.join(dir, "entry.ts")],
+        outdir: path.join(dir, "out"),
+        target: "browser",
+        plugins: [blockGeneratedImports()],
+      });
+      expect(result.success).toBe(false);
+      for (const log of result.logs) {
+        collected.push(String(log?.message ?? log));
+      }
+    } catch (err) {
+      if (err instanceof Error) collected.push(err.message);
+      const maybeAgg = err as { errors?: unknown[] };
+      if (Array.isArray(maybeAgg.errors)) {
+        for (const inner of maybeAgg.errors) {
+          if (inner instanceof Error) collected.push(inner.message);
+          else collected.push(String(inner));
+        }
+      }
+    }
+
+    const message = collected.join("\n");
+    expect(message).toContain("__generated__");
+    expect(message).toContain(GENERATED_IMPORT_DOCS_URL);
+    expect(message).toContain("getGenerated");
+  });
+
+  test("Bun.build succeeds when opt-out is set (no plugin installed)", async () => {
+    const dir = path.join(tmpRoot, "scenario-optout");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { routes } from "./__generated__/data";\nconsole.log(routes);\n`,
+    );
+
+    // Simulate the opt-out path: defaultBundlerPlugins with the flag off
+    // returns an empty plugin list, so the build has nothing to reject it.
+    const plugins = defaultBundlerPlugins({
+      config: { guard: { blockGeneratedImport: false } },
+    });
+
+    const result = await Bun.build({
+      entrypoints: [path.join(dir, "entry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins,
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("Bun.build succeeds when source has no __generated__ imports", async () => {
+    const dir = path.join(tmpRoot, "scenario-clean");
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      path.join(dir, "clean.ts"),
+      `export const value = 42;\n`,
+    );
+    await writeFile(
+      path.join(dir, "entry.ts"),
+      `import { value } from "./clean";\nconsole.log(value);\n`,
+    );
+
+    const result = await Bun.build({
+      entrypoints: [path.join(dir, "entry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins: [blockGeneratedImports()],
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  test("allowImporter lets whitelisted files import __generated__", async () => {
+    const dir = path.join(tmpRoot, "scenario-allow");
+    const runtimeDir = path.join(dir, "packages/core/src/runtime");
+    await mkdir(path.join(dir, "__generated__"), { recursive: true });
+    await mkdir(runtimeDir, { recursive: true });
+    await writeFile(
+      path.join(dir, "__generated__/data.ts"),
+      "export const routes = [];\n",
+    );
+    // Use a relative import so the filter can see `__generated__` in the
+    // specifier and invoke our hook — at which point the importer path
+    // matches the default allow-list.
+    await writeFile(
+      path.join(runtimeDir, "registry.ts"),
+      `import { routes } from "../../../../__generated__/data";\nexport { routes };\n`,
+    );
+
+    const result = await Bun.build({
+      entrypoints: [path.join(runtimeDir, "registry.ts")],
+      outdir: path.join(dir, "out"),
+      target: "browser",
+      plugins: [blockGeneratedImports()],
+    });
+
+    // The allow predicate lets the import fall through to Bun's default
+    // resolution, which succeeds because the file exists.
+    expect(result.success).toBe(true);
+  });
+});

package/src/bundler/plugins/block-generated-imports.ts

@@ -0,0 +1,155 @@
+/**
+ * Bun bundler plugin — hard-fail on direct `__generated__/` imports.
+ *
+ * Background
+ * ──────────
+ * The Guard rule `INVALID_GENERATED_IMPORT` (see `guard/check.ts`) already
+ * scans source files for literal `import … from '…generated…'` statements,
+ * but it only runs when the user (or CI) invokes `mandu guard check`.
+ * Autonomous coding agents routinely bypass that step. This plugin closes
+ * the gap at the bundler level: every `mandu dev` / `mandu build` pass
+ * installs it by default, and any import whose specifier contains
+ * `__generated__` fails the build with a structured, actionable error.
+ *
+ * Design
+ * ──────
+ * - `onResolve({ filter: /__generated__/ })` — Bun hands us every import
+ *   whose *specifier* matches the regex, along with the importer's path
+ *   (`args.importer`). We never return a result; we always throw.
+ * - The error is `ForbiddenGeneratedImportError`, a named subclass of
+ *   `Error`. Tests can `instanceof`-check; Bun surfaces `error.message` in
+ *   its `result.logs` output for CLI display.
+ * - The message is built via the shared Guard helper
+ *   (`buildForbiddenGeneratedImportMessage`) so the bundler path and the
+ *   static Guard pass cannot drift out of sync.
+ *
+ * Legitimate escape hatches
+ * ─────────────────────────
+ * 1. `getGenerated()` / `tryGetGenerated()` from `@mandujs/core/runtime`
+ *    read through a global manifest slot (`__MANDU_MANIFEST__`). They do
+ *    NOT trigger an ESM import for the generated artifact, so they never
+ *    hit this plugin. That is the officially supported API.
+ * 2. `import type` statements are allowed by the rule — TS erases them
+ *    before emit, so they never become runtime imports. However, a
+ *    bundler `onResolve` hook cannot distinguish `import type` from a
+ *    value import because Bun strips the `type` keyword before plugin
+ *    dispatch. For this reason the plugin exposes an `allowImporter`
+ *    option (defaulted to recognise `@mandujs/core/runtime` internals)
+ *    but deliberately does NOT try to parse the source for `type`-only
+ *    imports. User type imports go through the type-checker, not the
+ *    bundler, so they remain unaffected in practice.
+ * 3. The per-project opt-out lives in `ManduConfig.guard.blockGeneratedImport
+ *    = false`. The plugin is simply not installed when the flag is off.
+ */
+
+import type { BunPlugin } from "bun";
+import {
+  buildForbiddenGeneratedImportMessage,
+  FORBIDDEN_GENERATED_IMPORT_SUGGESTION,
+  GENERATED_IMPORT_DOCS_URL,
+} from "../../guard/check";
+
+/**
+ * Raised by the plugin's `onResolve` hook. Named so tests can
+ * `instanceof`-check, and so Bun's log output clearly attributes the
+ * failure to the plugin.
+ */
+export class ForbiddenGeneratedImportError extends Error {
+  /** The literal `from "…"` specifier that tripped the guard. */
+  readonly specifier: string;
+  /** Absolute path of the file that issued the import (best-effort). */
+  readonly importer: string;
+  /** Docs URL that explains the official replacement. */
+  readonly docsUrl: string;
+  /** Short, one-line remediation hint. */
+  readonly suggestion: string;
+
+  constructor(specifier: string, importer: string) {
+    const message =
+      `${buildForbiddenGeneratedImportMessage(specifier)}\n` +
+      `  Importer: ${importer || "<unknown>"}\n` +
+      `  Replacement: import { getGenerated } from "@mandujs/core/runtime";\n` +
+      `  Then: const data = getGenerated(<key>);\n` +
+      `  Docs: ${GENERATED_IMPORT_DOCS_URL}`;
+    super(message);
+    this.name = "ForbiddenGeneratedImportError";
+    this.specifier = specifier;
+    this.importer = importer;
+    this.docsUrl = GENERATED_IMPORT_DOCS_URL;
+    this.suggestion = FORBIDDEN_GENERATED_IMPORT_SUGGESTION;
+  }
+}
+
+export interface BlockGeneratedImportsOptions {
+  /**
+   * Predicate that returns `true` when the importer should be exempted
+   * from the rule. Default exempts `@mandujs/core/runtime` (which in
+   * principle never imports `__generated__`, but is listed here so
+   * framework boot code cannot trip over itself during upgrades).
+   */
+  allowImporter?: (importerPath: string) => boolean;
+  /**
+   * Custom filter regex applied to the import specifier. Defaults to
+   * `/__generated__/`. Mandu ships a single default — exposing this for
+   * test harnesses that want to narrow or broaden the filter.
+   */
+  filter?: RegExp;
+}
+
+/**
+ * Default exempt predicate — matches `@mandujs/core/runtime` internals.
+ * The runtime package reads generated artifacts via the global registry,
+ * so in practice it never imports `__generated__/*`. Kept as a belt-and-
+ * suspenders guard against self-inflicted regressions.
+ */
+export function defaultAllowImporter(importerPath: string): boolean {
+  if (!importerPath) return false;
+  // Normalize Windows backslashes so a single check covers both platforms.
+  const norm = importerPath.replace(/\\/g, "/");
+  return (
+    norm.includes("/@mandujs/core/runtime/") ||
+    norm.includes("/packages/core/src/runtime/") ||
+    norm.includes("packages/core/src/runtime/")
+  );
+}
+
+/**
+ * Build a `BunPlugin` that blocks direct `__generated__/` imports.
+ *
+ * Usage — call from `defaultBundlerPlugins(config)` (see `./index.ts`).
+ * Every `safeBuild` / `Bun.build` invocation in Mandu funnels through
+ * that helper, so a single install point enforces the rule everywhere.
+ */
+export function blockGeneratedImports(
+  options: BlockGeneratedImportsOptions = {},
+): BunPlugin {
+  const filter = options.filter ?? /__generated__/;
+  const allowImporter = options.allowImporter ?? defaultAllowImporter;
+
+  return {
+    name: "mandu:block-generated-imports",
+    setup(build) {
+      build.onResolve({ filter }, (args) => {
+        // Normalise the specifier so a Windows-style import (which would
+        // be exotic but technically legal in some toolchains) is still
+        // caught.
+        const specifier = args.path;
+        const importer = args.importer ?? "";
+
+        if (allowImporter(importer)) {
+          // Internal runtime code gets a pass. Return `undefined` so
+          // Bun resolves the path through its normal pipeline.
+          return undefined;
+        }
+
+        // Throw a structured error. Bun surfaces `error.message` in
+        // `BuildResult.logs` (non-success) or re-throws on an exception
+        // path; either way the message reaches the developer.
+        throw new ForbiddenGeneratedImportError(specifier, importer);
+      });
+    },
+  };
+}
+
+/** Exported for unit-test convenience — keep the filter text assertable. */
+export const DEFAULT_BLOCK_FILTER = /__generated__/;

package/src/bundler/plugins/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Bundler-plugin barrel.
+ *
+ * `defaultBundlerPlugins()` is the single choke point for the plugin
+ * set that Mandu installs on every `Bun.build` invocation. Adding a new
+ * default-on plugin means adding it here — every call-site in
+ * `bundler/build.ts` and `cli/src/util/bun.ts` composes the result of
+ * this helper with any build-specific plugins.
+ */
+
+import type { BunPlugin } from "bun";
+import {
+  blockGeneratedImports,
+  type BlockGeneratedImportsOptions,
+} from "./block-generated-imports";
+
+export {
+  blockGeneratedImports,
+  ForbiddenGeneratedImportError,
+  defaultAllowImporter,
+  DEFAULT_BLOCK_FILTER,
+  type BlockGeneratedImportsOptions,
+} from "./block-generated-imports";
+
+/**
+ * Subset of `ManduConfig.guard` consumed by `defaultBundlerPlugins()`.
+ * We deliberately don't import the full `ManduConfig` type to keep the
+ * plugins module cycle-free.
+ */
+export interface DefaultBundlerPluginsConfig {
+  guard?: {
+    blockGeneratedImport?: boolean;
+  };
+}
+
+export interface DefaultBundlerPluginsOptions {
+  /** Mandu config (only `guard.blockGeneratedImport` is consulted). */
+  config?: DefaultBundlerPluginsConfig;
+  /** Override options for the block-generated-imports plugin. */
+  blockGeneratedImports?: BlockGeneratedImportsOptions;
+}
+
+/**
+ * Compose Mandu's default plugin list. Current contents:
+ *
+ *   - `mandu:block-generated-imports` — hard-fail on direct
+ *     `__generated__/` imports. Opt-out via
+ *     `config.guard.blockGeneratedImport = false`.
+ *
+ * Always returns a fresh array; callers are free to concat build-local
+ * plugins (e.g. `fastRefreshPlugin()` in dev) without mutating the
+ * default set.
+ */
+export function defaultBundlerPlugins(
+  options: DefaultBundlerPluginsOptions = {},
+): BunPlugin[] {
+  const plugins: BunPlugin[] = [];
+  const blockEnabled = options.config?.guard?.blockGeneratedImport !== false;
+  if (blockEnabled) {
+    plugins.push(blockGeneratedImports(options.blockGeneratedImports));
+  }
+  return plugins;
+}

package/src/bundler/types.ts

@@ -156,4 +156,12 @@ export interface BundlerOptions {
    * - 안전성: 기존 `.mandu/manifest.json` 이 없으면 자동으로 full build로 fallback.
    */
   skipFrameworkBundles?: boolean;
+  /**
+   * Issue #207 — opt-out for the `mandu:block-generated-imports` bundler
+   * plugin. Default `true` (plugin installed on every build). Set
+   * `false` to skip installation — mirrors
+   * `ManduConfig.guard.blockGeneratedImport`. CLI callers pass the
+   * resolved config flag straight through.
+   */
+  blockGeneratedImport?: boolean;
 }

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

@@ -0,0 +1,82 @@
+/**
+ * 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>`;

package/src/config/mandu.ts

@@ -147,6 +147,22 @@ export interface ManduConfig {
     realtime?: boolean;
     rules?: Record<string, GuardRuleSeverity>;
     contractRequired?: GuardRuleSeverity;
+    /**
+     * Issue #207 — hard-fail on direct `__generated__/` imports at the
+     * bundler level. When `true` (default), every `mandu dev` /
+     * `mandu build` pass installs the
+     * `mandu:block-generated-imports` Bun plugin, which throws
+     * `ForbiddenGeneratedImportError` the moment any source file
+     * resolves an import whose specifier contains `__generated__`.
+     *
+     * Set to `false` only when a migration path literally requires
+     * the legacy barrel re-export pattern. User code should always
+     * prefer `getGenerated()` from `@mandujs/core/runtime`; see
+     * https://mandujs.com/docs/architect/generated-access.
+     *
+     * Default: `true`.
+     */
+    blockGeneratedImport?: boolean;
   };
   build?: {
     outDir?: string;

package/src/config/validate.ts

@@ -80,6 +80,12 @@ const GuardConfigSchema = z
     exclude: z.array(z.string()).default([]),
     realtime: z.boolean().default(true),
     rules: z.record(z.enum(["error", "warn", "warning", "off"])).optional(),
+    /**
+     * Issue #207 — bundler-level hard-fail on direct `__generated__/`
+     * imports. Default `true`. Set `false` to opt out of the
+     * `mandu:block-generated-imports` Bun plugin.
+     */
+    blockGeneratedImport: z.boolean().default(true),
   })
   .strict();
 

package/src/guard/check.ts

@@ -12,6 +12,40 @@ export interface GuardCheckResult {
   violations: GuardViolation[];
 }
 
+/**
+ * Canonical docs URL for the `getGenerated()` runtime-registry pattern.
+ * Shared by the Guard `INVALID_GENERATED_IMPORT` rule and the bundler
+ * plugin `block-generated-imports` so both paths surface the same
+ * remediation target.
+ */
+export const GENERATED_IMPORT_DOCS_URL =
+  "https://mandujs.com/docs/architect/generated-access";
+
+/**
+ * Build the user-facing message for a detected direct `__generated__/`
+ * import. `specifier` is the literal import string that tripped the
+ * guard (not the resolved path).
+ *
+ * This helper is the single source of truth for the message text — both
+ * the static Guard pass (`checkInvalidGeneratedImport`) and the bundler
+ * plugin (`blockGeneratedImports`) call through it so the two paths
+ * cannot drift.
+ */
+export function buildForbiddenGeneratedImportMessage(specifier: string): string {
+  return (
+    `Direct __generated__/ imports are forbidden: ${specifier}. ` +
+    `Use the runtime registry: see ${GENERATED_IMPORT_DOCS_URL}`
+  );
+}
+
+/**
+ * Shared remediation hint. Points at `getGenerated()` from
+ * `@mandujs/core/runtime` and the decision-tree docs.
+ */
+export const FORBIDDEN_GENERATED_IMPORT_SUGGESTION =
+  "Import getGenerated() from @mandujs/core/runtime and read the generated artifact through the manifest. " +
+  `See ${GENERATED_IMPORT_DOCS_URL} for the decision tree.`;
+
 function normalizeSeverity(level: GuardRuleSeverity): "error" | "warning" | "off" {
   if (level === "warn") return "warning";
   return level;
@@ -119,12 +153,8 @@ export async function checkInvalidGeneratedImport(
         violations.push({
           ruleId: GUARD_RULES.INVALID_GENERATED_IMPORT.id,
           file: relativePath,
-          message:
-            `Direct __generated__/ imports are forbidden: ${match[1]}. ` +
-            `Use the runtime registry: see https://mandujs.com/docs/architect/generated-access`,
-          suggestion:
-            "Import getGenerated() from @mandujs/core/runtime and read the generated artifact through the manifest. " +
-            "See https://mandujs.com/docs/architect/generated-access for the decision tree.",
+          message: buildForbiddenGeneratedImportMessage(match[1]),
+          suggestion: FORBIDDEN_GENERATED_IMPORT_SUGGESTION,
         });
       }
     }

package/src/runtime/server.ts

@@ -376,6 +376,17 @@ export interface ServerOptions {
    * also opt out via `data-no-prefetch`.
    */
   prefetch?: boolean;
+  /**
+   * Issue #193 / #208 — enable opt-out SPA navigation (default `true`).
+   * When `true`, every SSR response gets (a) the `window.__MANDU_SPA__`
+   * global elided (the router's default) and (b) the inline SPA-nav
+   * IIFE (~1.6 KB) that intercepts internal `<a>` clicks with pushState
+   * + fetch + View-Transitions DOM-swap, so `hydration: "none"` projects
+   * still feel like a SPA. `false` reverts to legacy full-reload (and
+   * the full router's opt-in `data-mandu-link` requirement). Wired from
+   * `ManduConfig.spa`; per-link opt-out lives on `data-no-spa`.
+   */
+  spa?: boolean;
   /**
    * Issue #191 — override dev-mode `_devtools.js` injection.
    * Wired from `ManduConfig.dev.devtools`.
@@ -527,6 +538,14 @@ export interface ServerRegistrySettings {
    * default); `false` suppresses the hover prefetch `<script>` injection.
    */
   prefetch?: boolean;
+  /**
+   * Issue #193 / #208 — threaded from `ServerOptions.spa`.
+   * `undefined` is treated as `true` at the SSR call-site (default SPA
+   * nav on, helper injected). `false` both disables the full client
+   * router (opt-in via `data-mandu-link` only) AND omits the inline
+   * SPA-nav IIFE from `<head>`.
+   */
+  spa?: boolean;
   /**
    * Issue #191 — threaded from `ServerOptions.devtools`. `undefined`
    * means "use default (islands → inject)"; `true` / `false` force the
@@ -2081,6 +2100,7 @@ async function renderPageSSR(
         cssPath: settings.cssPath,
         transitions: settings.transitions,
         prefetch: settings.prefetch,
+        spa: settings.spa,
         devtools: settings.devtools,
         onShellReady: () => {
           if (settings.isDev) {
@@ -2119,6 +2139,7 @@ async function renderPageSSR(
       islandPreWrapped: !!needsIslandWrap,
       transitions: settings.transitions,
       prefetch: settings.prefetch,
+      spa: settings.spa,
       devtools: settings.devtools,
     });
     return ok(cookies ? cookies.applyToResponse(ssrResponse) : ssrResponse);
@@ -2162,6 +2183,7 @@ async function renderPageSSR(
             cssPath: settings.cssPath,
             transitions: settings.transitions,
             prefetch: settings.prefetch,
+            spa: settings.spa,
             devtools: settings.devtools,
           });
           return ok(cookies ? cookies.applyToResponse(errorHtml) : errorHtml);
@@ -2268,6 +2290,7 @@ async function renderNotFoundPage(
       cssPath: settings.cssPath,
       transitions: settings.transitions,
       prefetch: settings.prefetch,
+      spa: settings.spa,
       devtools: settings.devtools,
     });
 
@@ -2749,6 +2772,7 @@ async function handleRequestInternal(
           cssPath: settings.cssPath,
           transitions: settings.transitions,
           prefetch: settings.prefetch,
+          spa: settings.spa,
           devtools: settings.devtools,
         });
         const headers = new Headers(html.headers);
@@ -2907,6 +2931,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     managementToken,
     transitions,
     prefetch,
+    spa,
     devtools,
     observability: observabilityOption,
   } = options;
@@ -2946,6 +2971,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     managementToken,
     transitions,
     prefetch,
+    spa,
     devtools,
     heapEndpoint: observabilityOption?.heapEndpoint,
     metricsEndpoint: observabilityOption?.metricsEndpoint,

package/src/runtime/ssr.ts

@@ -10,6 +10,7 @@ import { escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./esc
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 import { generateFastRefreshPreamble } from "../bundler/dev";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
+import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
 
 /**
  * Issue #192 — `@view-transition` at-rule block.
@@ -579,6 +580,16 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   //   or cancel with a later inline style. False disables each independently.
   const viewTransitionTag = transitions !== false ? VIEW_TRANSITION_STYLE_TAG : "";
   const prefetchScriptTag = prefetch !== false ? PREFETCH_HELPER_SCRIPT : "";
+  // Issue #208 — Inline SPA-nav IIFE. Pre-#208 Issue #193 wired the SPA
+  // click handler into the client bundle (`router.ts::handleLinkClick`),
+  // which never ships to `hydration: "none"` projects (docs / marketing
+  // sites). The inline helper closes that gap: ~1.6 KB of JS that runs
+  // parse-time on every SSR response and intercepts internal anchor
+  // clicks using the same 10 exclusion cases as the full router.
+  // Coexists safely with the full router via a `__MANDU_ROUTER_STATE__`
+  // early-exit. Emit when `spa !== false`; skip entirely when the user
+  // opts out via `ssr.spa: false` (same flag the big-router reads).
+  const spaNavHelperTag = spa !== false ? SPA_NAV_HELPER_SCRIPT : "";
 
   // useHead/useSeoMeta SSR 수집
   let collectedHeadTags = "";
@@ -709,6 +720,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   ${cssLinkTag}
   ${viewTransitionTag}
   ${prefetchScriptTag}
+  ${spaNavHelperTag}
   ${hoistedLinkTags}
   ${headTags}
   ${collectedHeadTags}

package/src/runtime/streaming-ssr.ts

@@ -25,6 +25,7 @@ import { getRenderToString } from "./react-renderer";
 import { mark, measure } from "../perf";
 import { generateFastRefreshPreamble } from "../bundler/dev";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
+import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
 
 /**
  * Issue #192 — `@view-transition` at-rule, mirror of the constant in
@@ -176,6 +177,14 @@ export interface StreamingSSROptions {
    * Default: `true`.
    */
   prefetch?: boolean;
+  /**
+   * Issue #208 — emit the inline SPA-nav helper `<script>` (~1.6 KB)
+   * into the streaming shell `<head>`. Mirrors `SSROptions.spa`:
+   * `true` (default) injects so zero-JS / `hydration: "none"` projects
+   * still get pushState navigations + View Transitions API; `false`
+   * omits the block entirely, matching the legacy full-reload default.
+   */
+  spa?: boolean;
   /**
    * Issue #191 — control dev-mode injection of the `_devtools.js`
    * bundle. Mirrors `SSROptions.devtools`:
@@ -533,6 +542,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     isDev = false,
     transitions = true,
     prefetch = true,
+    spa = true,
   } = options;
 
   // CSS 링크 태그 생성
@@ -549,6 +559,11 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   // an inline style later in the document order.
   const viewTransitionTag = transitions !== false ? VIEW_TRANSITION_STYLE_TAG : "";
   const prefetchScriptTag = prefetch !== false ? PREFETCH_HELPER_SCRIPT : "";
+  // Issue #208 — Inline SPA-nav IIFE, mirror of `ssr.ts::renderToHTML`.
+  // See that call-site for the full rationale. Streaming SSR follows
+  // the same opt-out contract: `spa !== false` injects, `spa: false`
+  // omits the `<script>` block entirely.
+  const spaNavHelperTag = spa !== false ? SPA_NAV_HELPER_SCRIPT : "";
 
   // Island wrapper (hydration이 필요한 경우)
   const needsHydration = hydration && hydration.strategy !== "none" && routeId && bundleManifest;
@@ -630,6 +645,7 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   ${cssLinkTag}
   ${viewTransitionTag}
   ${prefetchScriptTag}
+  ${spaNavHelperTag}
   ${loadingStyles}
   ${importMapScript}
   ${headTags}