@mandujs/core 0.25.3 → 0.27.0

package/src/routes/types.ts

@@ -0,0 +1,341 @@
+/**
+ * Metadata Route Types
+ *
+ * File-convention types for Next.js-style metadata routes. Each type
+ * matches the Next.js shape so developers familiar with that ecosystem
+ * can drop their existing contract in verbatim.
+ *
+ * Exposed via `@mandujs/core/routes`. For the legacy free-form SEO
+ * metadata types (Metadata, Icons, OpenGraph, ...) see `@mandujs/core`
+ * / `packages/core/src/seo/types.ts` — this module is scoped strictly
+ * to the file-convention routes (sitemap.ts, robots.ts, llms.txt.ts,
+ * manifest.ts) and their runtime handlers.
+ *
+ * @module routes/types
+ */
+import { z } from "zod";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Sitemap (sitemap.ts → /sitemap.xml)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Change frequency hint from the Sitemaps XML schema.
+ * @see https://www.sitemaps.org/protocol.html#changefreqdef
+ */
+export type ChangeFrequency =
+  | "always"
+  | "hourly"
+  | "daily"
+  | "weekly"
+  | "monthly"
+  | "yearly"
+  | "never";
+
+/** Alternate language URLs for a sitemap entry (hreflang). */
+export interface SitemapAlternates {
+  languages?: Record<string, string>;
+}
+
+/**
+ * Single sitemap entry. Next.js shape — `url` is required, everything
+ * else is optional. `lastModified` accepts a `Date` or ISO string so
+ * users can return e.g. `fs.statSync(...).mtime` directly.
+ */
+export interface SitemapEntry {
+  /** Absolute URL of the page. */
+  url: string;
+  /** Last modification time of the page. */
+  lastModified?: string | Date;
+  /** Crawl frequency hint for search engines. */
+  changeFrequency?: ChangeFrequency;
+  /** Priority hint [0.0, 1.0]. */
+  priority?: number;
+  /** Alternate URLs for i18n / hreflang. */
+  alternates?: SitemapAlternates;
+  /** Optional image URLs associated with the page. */
+  images?: string[];
+}
+
+/** Full sitemap: an array of SitemapEntry. */
+export type Sitemap = SitemapEntry[];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Robots (robots.ts → /robots.txt)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Single rule group in robots.txt. Each group applies to one or more
+ * user agents; `allow` / `disallow` accept a single string or array.
+ */
+export interface RobotsRule {
+  /** User agent string ("*", "Googlebot", ...). */
+  userAgent: string | string[];
+  /** Paths explicitly permitted. */
+  allow?: string | string[];
+  /** Paths explicitly denied. */
+  disallow?: string | string[];
+  /** Crawl delay in seconds. */
+  crawlDelay?: number;
+}
+
+/**
+ * Complete robots.txt definition. Matches Next.js `MetadataRoute.Robots`.
+ */
+export interface Robots {
+  /** One or more rule groups. */
+  rules: RobotsRule | RobotsRule[];
+  /** Sitemap URL(s) to announce. */
+  sitemap?: string | string[];
+  /** Host directive (Yandex). */
+  host?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Web App Manifest (manifest.ts → /manifest.webmanifest)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type DisplayMode = "fullscreen" | "standalone" | "minimal-ui" | "browser";
+export type Orientation =
+  | "any"
+  | "natural"
+  | "landscape"
+  | "landscape-primary"
+  | "landscape-secondary"
+  | "portrait"
+  | "portrait-primary"
+  | "portrait-secondary";
+
+/**
+ * Icon descriptor in a web app manifest. `src` + `sizes` + `type` is
+ * the minimal W3C contract; `purpose` is optional but recommended for
+ * maskable icons.
+ */
+export interface WebAppManifestIcon {
+  src: string;
+  sizes?: string;
+  type?: string;
+  purpose?: "any" | "maskable" | "monochrome" | string;
+}
+
+/** Shortcut entry (jumplist) in a web app manifest. */
+export interface WebAppManifestShortcut {
+  name: string;
+  short_name?: string;
+  description?: string;
+  url: string;
+  icons?: WebAppManifestIcon[];
+}
+
+/**
+ * Web app manifest (application/manifest+json). We type the common
+ * subset defined by the W3C spec; unknown keys pass through via the
+ * index signature so callers can add experimental fields.
+ */
+export interface WebAppManifest {
+  /** Full name of the application (required per W3C). */
+  name: string;
+  /** Short name for home-screen / launcher. */
+  short_name: string;
+  /** Description. */
+  description?: string;
+  /** Starting URL. */
+  start_url?: string;
+  /** Application scope (URL prefix). */
+  scope?: string;
+  /** Display mode. */
+  display?: DisplayMode;
+  /** Orientation preference. */
+  orientation?: Orientation;
+  /** Primary theme color (toolbar). */
+  theme_color?: string;
+  /** Background color (splash). */
+  background_color?: string;
+  /** Icons — at least one is required by the spec. */
+  icons: WebAppManifestIcon[];
+  /** Language tag (e.g. "en-US"). */
+  lang?: string;
+  /** Text direction. */
+  dir?: "ltr" | "rtl" | "auto";
+  /** Categories (taxonomy). */
+  categories?: string[];
+  /** Shortcuts shown in the app launcher. */
+  shortcuts?: WebAppManifestShortcut[];
+  /** Additional W3C fields pass through unchanged. */
+  [key: string]: unknown;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Default export function signatures
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Default-export contract for `app/sitemap.ts`. Return `Sitemap` or a
+ * Promise — Mandu awaits the result during the request.
+ */
+export type SitemapFn = () => Sitemap | Promise<Sitemap>;
+
+/**
+ * Default-export contract for `app/robots.ts`.
+ */
+export type RobotsFn = () => Robots | Promise<Robots>;
+
+/**
+ * Default-export contract for `app/llms.txt.ts`. Return the complete
+ * text body; Mandu serves it verbatim with `text/plain` content type.
+ */
+export type LlmsTxtFn = () => string | Promise<string>;
+
+/**
+ * Default-export contract for `app/manifest.ts`.
+ */
+export type ManifestFn = () => WebAppManifest | Promise<WebAppManifest>;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Metadata route kinds (for manifest / fs-scanner)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Discriminator used in `RouteSpec.kind === "metadata"` entries and in
+ * `ScannedFile.metadataKind` when fs-scanner detects one of the four
+ * metadata files.
+ */
+export type MetadataRouteKind = "sitemap" | "robots" | "llms-txt" | "manifest";
+
+/**
+ * Static table mapping each metadata route kind to the file name the
+ * scanner recognizes, the URL pattern that serves the content, and the
+ * Content-Type header. Kept deliberately flat so both fs-scanner and
+ * the runtime dispatcher can read from the same source of truth.
+ */
+export const METADATA_ROUTES: Record<
+  MetadataRouteKind,
+  { fileBase: string; pattern: string; contentType: string }
+> = {
+  sitemap: {
+    fileBase: "sitemap",
+    pattern: "/sitemap.xml",
+    contentType: "application/xml; charset=utf-8",
+  },
+  robots: {
+    fileBase: "robots",
+    pattern: "/robots.txt",
+    contentType: "text/plain; charset=utf-8",
+  },
+  "llms-txt": {
+    // `llms.txt.ts` — filename contains a dot before the extension to
+    // mirror the served path (/llms.txt). Detected specifically in
+    // `detectMetadataFile()` since it doesn't match the common
+    // `<name>.<ext>` shape.
+    fileBase: "llms.txt",
+    pattern: "/llms.txt",
+    contentType: "text/plain; charset=utf-8",
+  },
+  manifest: {
+    fileBase: "manifest",
+    pattern: "/manifest.webmanifest",
+    contentType: "application/manifest+json; charset=utf-8",
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Zod schemas — runtime validation of user-returned values
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validates a single sitemap entry. `url` must be a URL-like string;
+ * we accept both protocol-absolute URLs and site-root-relative paths
+ * (`/docs/...`) so users building a sitemap for an internal base can
+ * return relative URLs. `lastModified` accepts Date or date-like string.
+ */
+export const SitemapEntrySchema = z.object({
+  url: z
+    .string()
+    .min(1, "SitemapEntry.url must not be empty")
+    .refine(
+      (v) => /^(https?:\/\/|\/)/.test(v),
+      "SitemapEntry.url must be absolute (http(s)://...) or site-root-relative (/...)"
+    ),
+  lastModified: z
+    .union([z.date(), z.string().min(1)])
+    .optional(),
+  changeFrequency: z
+    .enum(["always", "hourly", "daily", "weekly", "monthly", "yearly", "never"])
+    .optional(),
+  priority: z.number().min(0).max(1).optional(),
+  alternates: z
+    .object({ languages: z.record(z.string()).optional() })
+    .optional(),
+  images: z.array(z.string().min(1)).optional(),
+});
+
+export const SitemapSchema = z.array(SitemapEntrySchema);
+
+export const RobotsRuleSchema = z.object({
+  userAgent: z.union([z.string().min(1), z.array(z.string().min(1))]),
+  allow: z.union([z.string(), z.array(z.string())]).optional(),
+  disallow: z.union([z.string(), z.array(z.string())]).optional(),
+  crawlDelay: z.number().nonnegative().optional(),
+});
+
+export const RobotsSchema = z.object({
+  rules: z.union([RobotsRuleSchema, z.array(RobotsRuleSchema)]),
+  sitemap: z.union([z.string().min(1), z.array(z.string().min(1))]).optional(),
+  host: z.string().optional(),
+});
+
+export const WebAppManifestIconSchema = z.object({
+  src: z.string().min(1, "WebAppManifest icon.src must not be empty"),
+  sizes: z.string().optional(),
+  type: z.string().optional(),
+  purpose: z.string().optional(),
+});
+
+/**
+ * Minimum W3C-compliant manifest — `name`, `short_name`, and at least
+ * one icon. Unknown keys pass through via `.passthrough()` so users
+ * can add experimental manifest fields without fighting the validator.
+ */
+export const WebAppManifestSchema = z
+  .object({
+    name: z.string().min(1, "WebAppManifest.name is required"),
+    short_name: z.string().min(1, "WebAppManifest.short_name is required"),
+    description: z.string().optional(),
+    start_url: z.string().optional(),
+    scope: z.string().optional(),
+    display: z
+      .enum(["fullscreen", "standalone", "minimal-ui", "browser"])
+      .optional(),
+    orientation: z
+      .enum([
+        "any",
+        "natural",
+        "landscape",
+        "landscape-primary",
+        "landscape-secondary",
+        "portrait",
+        "portrait-primary",
+        "portrait-secondary",
+      ])
+      .optional(),
+    theme_color: z.string().optional(),
+    background_color: z.string().optional(),
+    icons: z
+      .array(WebAppManifestIconSchema)
+      .min(1, "WebAppManifest.icons must contain at least one icon"),
+    lang: z.string().optional(),
+    dir: z.enum(["ltr", "rtl", "auto"]).optional(),
+    categories: z.array(z.string()).optional(),
+    shortcuts: z
+      .array(
+        z.object({
+          name: z.string().min(1),
+          short_name: z.string().optional(),
+          description: z.string().optional(),
+          url: z.string().min(1),
+          icons: z.array(WebAppManifestIconSchema).optional(),
+        })
+      )
+      .optional(),
+  })
+  .passthrough();

package/src/runtime/server.ts

@@ -69,6 +69,7 @@ import { extractShellHtml, createPPRResponse } from "./ppr";
 import { isRedirectResponse } from "./redirect";
 import { isNotFoundResponse } from "./not-found";
 import { newId } from "../id";
+import { handleMetadataRoute as dispatchMetadataRoute } from "../routes/metadata-routes";
 
 export interface RateLimitOptions {
   windowMs?: number;
@@ -375,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`.
@@ -461,6 +473,15 @@ export interface PageRegistration {
  */
 export type PageHandler = () => Promise<PageRegistration>;
 
+/**
+ * Issue #206 — Metadata route handler. A thunk that returns the
+ * imported user module (or its `default` export) so the dispatcher
+ * in `handleMetadataRoute` can invoke the user-supplied function with
+ * the correct Content-Type + cache headers. The indirection keeps dev
+ * HMR cheap: the handler only imports on the request that needs it.
+ */
+export type MetadataHandler = () => Promise<unknown>;
+
 export interface AppContext {
   routeId: string;
   url: string;
@@ -517,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
@@ -541,6 +570,15 @@ export class ServerRegistry {
   readonly pageHandlers: Map<string, PageHandler> = new Map();
   readonly pageFillings: Map<string, ManduFilling<unknown>> = new Map();
   readonly routeComponents: Map<string, RouteComponent> = new Map();
+  /**
+   * Issue #206 — metadata-route handlers keyed by `route.id`
+   * (`metadata-sitemap` / `metadata-robots` / `metadata-llms-txt` /
+   * `metadata-manifest`). Each handler is a thunk that imports the
+   * user module lazily so dev HMR can swap it without restarting the
+   * server. The dispatcher in `handleMetadataRoute()` extracts the
+   * default export and invokes it.
+   */
+  readonly metadataHandlers: Map<string, MetadataHandler> = new Map();
   /** Layout 컴포넌트 캐시 (모듈 경로 → 컴포넌트) */
   readonly layoutComponents: Map<string, LayoutComponent> = new Map();
   /** Layout 로더 (모듈 경로 → 로더 함수) */
@@ -596,6 +634,17 @@ export class ServerRegistry {
     this.apiHandlers.set(routeId, handler);
   }
 
+  /**
+   * Issue #206 — register a metadata-route loader. The handler must
+   * be a thunk returning either the raw user function or the
+   * module namespace (`{ default: fn }`). The dispatcher accepts both
+   * shapes so callers don't have to care whether they imported with
+   * `import("./sitemap")` or a bundled variant.
+   */
+  registerMetadataHandler(routeId: string, handler: MetadataHandler): void {
+    this.metadataHandlers.set(routeId, handler);
+  }
+
   registerPageLoader(routeId: string, loader: PageLoader): void {
     this.pageLoaders.set(routeId, loader);
   }
@@ -760,6 +809,7 @@ export class ServerRegistry {
     this.pageGenerateMetadata.clear();
     this.layoutMetadata.clear();
     this.layoutGenerateMetadata.clear();
+    this.metadataHandlers.clear();
     this.createAppFn = null;
     this.rateLimiter = null;
     this.notFoundHandler = null;
@@ -792,6 +842,17 @@ export function registerApiHandler(routeId: string, handler: ApiHandler): void {
   defaultRegistry.registerApiHandler(routeId, handler);
 }
 
+/**
+ * Issue #206 — register a metadata route handler on the default
+ * registry. See {@link ServerRegistry.registerMetadataHandler} for
+ * the handler contract. Exposed at module scope so the CLI handlers
+ * wiring (`packages/cli/src/util/handlers.ts`) can reach it without
+ * threading a registry reference.
+ */
+export function registerMetadataHandler(routeId: string, handler: MetadataHandler): void {
+  defaultRegistry.registerMetadataHandler(routeId, handler);
+}
+
 export function registerPageLoader(routeId: string, loader: PageLoader): void {
   defaultRegistry.registerPageLoader(routeId, loader);
 }
@@ -1369,6 +1430,47 @@ async function handleApiRoute(
   }
 }
 
+// ---------- Metadata Route Handler (Issue #206) ----------
+
+/**
+ * Dispatch a metadata route (sitemap / robots / llms.txt / manifest).
+ *
+ * The registry stores a thunk that lazily imports the user module
+ * on the first request. We delegate the actual validation + render
+ * + Response assembly to `dispatchMetadataRoute()` from
+ * `@mandujs/core/routes` so the pipeline stays testable in isolation.
+ *
+ * A missing registration falls through to the framework's
+ * "handler not found" 500 response — typically only reachable if the
+ * scanner detected the file but `registerManifestHandlers` skipped it
+ * (which would be a framework bug).
+ */
+async function handleMetadataRouteRequest(
+  route: RouteSpec,
+  registry: ServerRegistry
+): Promise<Result<Response>> {
+  if (route.kind !== "metadata") {
+    return err(createHandlerNotFoundResponse(route.id, route.pattern));
+  }
+  const handler = registry.metadataHandlers.get(route.id);
+  if (!handler) {
+    return err(createHandlerNotFoundResponse(route.id, route.pattern));
+  }
+
+  try {
+    const userExport = await handler();
+    const response = await dispatchMetadataRoute({
+      kind: route.metadataKind,
+      userExport,
+      sourceFile: route.module,
+    });
+    return ok(response);
+  } catch (errValue) {
+    const error = errValue instanceof Error ? errValue : new Error(String(errValue));
+    return err(createSSRErrorResponse(route.id, route.pattern, error));
+  }
+}
+
 // ---------- Page Data Loader ----------
 
 /**
@@ -1998,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) {
@@ -2036,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);
@@ -2079,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);
@@ -2185,6 +2290,7 @@ async function renderNotFoundPage(
       cssPath: settings.cssPath,
       transitions: settings.transitions,
       prefetch: settings.prefetch,
+      spa: settings.spa,
       devtools: settings.devtools,
     });
 
@@ -2666,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);
@@ -2701,6 +2808,10 @@ async function handleRequestInternal(
     return handlePageRoute(req, url, route, params, registry);
   }
 
+  if (route.kind === "metadata") {
+    return handleMetadataRouteRequest(route, registry);
+  }
+
   // 4. 알 수 없는 라우트 종류 — exhaustiveness check
   const _exhaustive: never = route;
   return err({
@@ -2820,6 +2931,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     managementToken,
     transitions,
     prefetch,
+    spa,
     devtools,
     observability: observabilityOption,
   } = options;
@@ -2859,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}