npm - @mandujs/core - Versions diffs - 0.23.0 → 0.24.0 - Mend

@mandujs/core 0.23.0 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/package.json +1 -1
package/src/bundler/__tests__/reverse-import-graph.test.ts +519 -0
package/src/bundler/dev.ts +288 -0
package/src/bundler/reverse-import-graph.ts +339 -0
package/src/bundler/safe-build.test.ts +54 -0
package/src/bundler/safe-build.ts +33 -7
package/src/client/prefetch-helper.ts +55 -0
package/src/config/mandu.ts +216 -172
package/src/config/validate.ts +376 -357
package/src/runtime/adapter-bun.ts +64 -62
package/src/runtime/server.ts +110 -4
package/src/runtime/ssr.ts +146 -7
package/src/runtime/streaming-ssr.ts +89 -3

package/src/runtime/adapter-bun.ts CHANGED Viewed

@@ -1,62 +1,64 @@
-/**
- * Mandu Bun Adapter (기본 어댑터)
- * Bun.serve() 기반 서버 생성
- */
-import type { ManduAdapter, AdapterOptions, AdapterServer } from "./adapter";
-import { startServer, type ManduServer } from "./server";
-/**
- * Bun 어댑터 (기본)
- *
- * @example
- * ```typescript
- * // mandu.config.ts
- * import { adapterBun } from "@mandujs/core";
- *
- * export default {
- *   adapter: adapterBun(),
- * };
- * ```
- */
-export function adapterBun(): ManduAdapter {
-  return {
-    name: "adapter-bun",
-    createServer(options: AdapterOptions): AdapterServer {
-      let manduServer: ManduServer | null = null;
-      return {
-        async fetch(req: Request): Promise<Response> {
-          if (!manduServer) {
-            return new Response("Server not started", { status: 503 });
-          }
-          // 내부 서버로 프록시
-          const url = new URL(req.url);
-          const targetUrl = `http://localhost:${manduServer.server.port}${url.pathname}${url.search}`;
-          return globalThis.fetch(new Request(targetUrl, req));
-        },
-        async listen(port: number, hostname?: string) {
-          manduServer = startServer(options.manifest, {
-            ...options.serverOptions,
-            port,
-            hostname,
-            rootDir: options.rootDir,
-            bundleManifest: options.bundleManifest,
-          });
-          return {
-            port: manduServer.server.port ?? port,
-            hostname: hostname ?? "localhost",
-          };
-        },
-        async close() {
-          manduServer?.stop();
-          manduServer = null;
-        },
-      };
-    },
-  };
-}
+/**
+ * Mandu Bun Adapter (기본 어댑터)
+ * Bun.serve() 기반 서버 생성
+ */
+import type { ManduAdapter, AdapterOptions, AdapterServer } from "./adapter";
+import { startServer, type ManduServer } from "./server";
+/**
+ * Bun 어댑터 (기본)
+ *
+ * @example
+ * ```typescript
+ * // mandu.config.ts
+ * import { adapterBun } from "@mandujs/core";
+ *
+ * export default {
+ *   adapter: adapterBun(),
+ * };
+ * ```
+ */
+export function adapterBun(): ManduAdapter {
+  return {
+    name: "adapter-bun",
+    createServer(options: AdapterOptions): AdapterServer {
+      let manduServer: ManduServer | null = null;
+      return {
+        async fetch(req: Request): Promise<Response> {
+          if (!manduServer) {
+            return new Response("Server not started", { status: 503 });
+          }
+          // 내부 서버로 프록시
+          const url = new URL(req.url);
+          const targetUrl = `http://localhost:${manduServer.server.port}${url.pathname}${url.search}`;
+          return globalThis.fetch(new Request(targetUrl, req));
+        },
+        async listen(port: number, hostname?: string) {
+          manduServer = startServer(options.manifest, {
+            ...options.serverOptions,
+            port,
+            hostname,
+            rootDir: options.rootDir,
+            bundleManifest: options.bundleManifest,
+          });
+          return {
+            port: manduServer.server.port ?? port,
+            // Report the effective bind address. startServer() defaults to
+            // 0.0.0.0 when no hostname is supplied. See #190.
+            hostname: hostname ?? "0.0.0.0",
+          };
+        },
+        async close() {
+          manduServer?.stop();
+          manduServer = null;
+        },
+      };
+    },
+  };
+}

package/src/runtime/server.ts CHANGED Viewed

@@ -350,6 +350,32 @@ export interface ServerOptions {
    * When set, token-protected endpoints such as `/_mandu/cache` become available.
    */
   managementToken?: string;
+  /**
+   * Issue #192 — enable CSS View Transitions auto-inject (default `true`).
+   * When `true`, every SSR response gets
+   * `<style>@view-transition{navigation:auto}</style>` in its `<head>`,
+   * giving supported browsers a default crossfade on cross-document
+   * navigation. Pass `false` to suppress (typically wired from
+   * `ManduConfig.transitions`).
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — enable the hover prefetch helper (default `true`).
+   * When `true`, every SSR response gets a ~500-byte inline script that
+   * prefetches same-origin links on hover. Pass `false` to suppress
+   * (typically wired from `ManduConfig.prefetch`). Individual links can
+   * also opt out via `data-no-prefetch`.
+   */
+  prefetch?: boolean;
+  /**
+   * Issue #191 — override dev-mode `_devtools.js` injection.
+   * Wired from `ManduConfig.dev.devtools`.
+   *   - `true`      → force inject on every page (SSR-only + Kitchen).
+   *   - `false`     → force skip on every page.
+   *   - `undefined` → default. Inject iff the page's route has at least
+   *                   one island. Pure-SSR pages download zero devtools.
+   */
+  devtools?: boolean;
 }
 export interface ManduServer {
@@ -456,6 +482,24 @@ export interface ServerRegistrySettings {
    * Default: false (Bun/Node runtime with full FS access).
    */
   edge?: boolean;
+  /**
+   * Issue #192 — threaded from `ServerOptions.transitions`.
+   * `undefined` is treated as `true` at the SSR call-site (enabled by
+   * default); `false` suppresses the `<style>@view-transition>` injection.
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — threaded from `ServerOptions.prefetch`.
+   * `undefined` is treated as `true` at the SSR call-site (enabled by
+   * default); `false` suppresses the hover prefetch `<script>` injection.
+   */
+  prefetch?: boolean;
+  /**
+   * Issue #191 — threaded from `ServerOptions.devtools`. `undefined`
+   * means "use default (islands → inject)"; `true` / `false` force the
+   * dev-mode `_devtools.js` `<script>` injection on / off. No-op in prod.
+   */
+  devtools?: boolean;
 }
 export class ServerRegistry {
@@ -1889,6 +1933,9 @@ async function renderPageSSR(
         criticalData: loaderData as Record<string, unknown> | undefined,
         enableClientRouter: true,
         cssPath: settings.cssPath,
+        transitions: settings.transitions,
+        prefetch: settings.prefetch,
+        devtools: settings.devtools,
         onShellReady: () => {
           if (settings.isDev) {
             console.log(`[Mandu Streaming] Shell ready: ${route.id}`);
@@ -1924,6 +1971,9 @@ async function renderPageSSR(
       routePattern: route.pattern,
       cssPath: settings.cssPath,
       islandPreWrapped: !!needsIslandWrap,
+      transitions: settings.transitions,
+      prefetch: settings.prefetch,
+      devtools: settings.devtools,
     });
     return ok(cookies ? cookies.applyToResponse(ssrResponse) : ssrResponse);
   } catch (error) {
@@ -1960,6 +2010,9 @@ async function renderPageSSR(
             title: "Mandu App — Error",
             isDev: settings.isDev,
             cssPath: settings.cssPath,
+            transitions: settings.transitions,
+            prefetch: settings.prefetch,
+            devtools: settings.devtools,
           });
           return ok(cookies ? cookies.applyToResponse(errorHtml) : errorHtml);
         }
@@ -2058,6 +2111,9 @@ async function renderNotFoundPage(
       title: "Not Found",
       isDev: settings.isDev,
       cssPath: settings.cssPath,
+      transitions: settings.transitions,
+      prefetch: settings.prefetch,
+      devtools: settings.devtools,
     });
     // renderSSR returns a 200; override to 404 without losing headers.
@@ -2485,6 +2541,9 @@ async function handleRequestInternal(
           title: "Not Found",
           isDev: settings.isDev,
           cssPath: settings.cssPath,
+          transitions: settings.transitions,
+          prefetch: settings.prefetch,
+          devtools: settings.devtools,
         });
         const headers = new Headers(html.headers);
         const body = await html.text();
@@ -2586,10 +2645,43 @@ function startBunServerWithFallback(options: {
 // ========== Server Startup ==========
+/**
+ * Format a base URL for startup logging based on the bound hostname.
+ *
+ * When binding to wildcard addresses (`0.0.0.0`, `::`, or empty string),
+ * the server listens on all interfaces — browsers must use `localhost`
+ * or a specific loopback address to connect. We surface both IPv4 and IPv6
+ * loopback URLs so the user can pick whichever their OS prefers.
+ *
+ * Returns `{ primary, additional }` where `primary` is the canonical URL
+ * for UX (open-in-browser, runtime control) and `additional` are supplementary
+ * URLs shown in the startup log.
+ */
+export function formatServerAddresses(
+  hostname: string | undefined,
+  port: number
+): { primary: string; additional: string[] } {
+  const isWildcardV4 = hostname === "0.0.0.0" || hostname === undefined || hostname === "";
+  const isWildcardV6 = hostname === "::" || hostname === "[::]";
+  if (isWildcardV4 || isWildcardV6) {
+    return {
+      primary: `http://localhost:${port}`,
+      additional: [`http://127.0.0.1:${port}`, `http://[::1]:${port}`],
+    };
+  }
+  // Bracket IPv6 literals for URL syntax.
+  const host = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+  return { primary: `http://${host}:${port}`, additional: [] };
+}
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
   const {
     port = 3000,
-    hostname = "localhost",
+    // Default to 0.0.0.0 (dual-stack wildcard on IPv4) so `localhost` resolves
+    // to 127.0.0.1 via OS-level IPv4-preferred lookups (e.g., Windows). Users
+    // can still pin `hostname: "::1"` or `hostname: "127.0.0.1"` explicitly.
+    // See issue #190.
+    hostname = "0.0.0.0",
     rootDir = process.cwd(),
     isDev = false,
     hmrPort,
@@ -2603,6 +2695,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     guardConfig = null,
     cache: cacheOption,
     managementToken,
+    transitions,
+    prefetch,
+    devtools,
   } = options;
   // cssPath 처리:
@@ -2638,6 +2733,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     rateLimit: rateLimitOptions,
     cssPath,
     managementToken,
+    transitions,
+    prefetch,
+    devtools,
   };
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
@@ -2737,8 +2835,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     registry.settings = { ...registry.settings, hmrPort: actualPort };
   }
+  const addresses = formatServerAddresses(hostname, actualPort);
   if (isDev) {
-    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${actualPort}`);
+    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}`);
     }
@@ -2750,10 +2853,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
       console.log(`🌊 Streaming SSR enabled`);
     }
     if (registry.kitchen) {
-      console.log(`🍳 Kitchen dashboard at http://${hostname}:${actualPort}/__kitchen`);
+      console.log(`🍳 Kitchen dashboard at ${addresses.primary}/__kitchen`);
     }
   } else {
-    console.log(`🥟 Mandu server running at http://${hostname}:${actualPort}`);
+    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`);
     }

package/src/runtime/ssr.ts CHANGED Viewed

@@ -9,6 +9,21 @@ import { PORTS, TIMEOUTS } from "../constants";
 import { escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 import { generateFastRefreshPreamble } from "../bundler/dev";
+import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
+/**
+ * Issue #192 — `@view-transition` at-rule block.
+ * Inert in browsers without CSS View Transitions (Firefox, Safari < 18.0):
+ * the at-rule is simply ignored, so there is no regression. Supporting
+ * browsers (Chrome/Edge ≥ 111, Safari 18.2+) play the default crossfade
+ * between cross-document navigations.
+ *
+ * `navigation: auto` is the only value we need — selective transitions
+ * are a per-route concern reserved for a future `transitions` config
+ * sub-block.
+ */
+const VIEW_TRANSITION_STYLE_TAG =
+  "<style>@view-transition{navigation:auto}</style>";
 // Re-export streaming SSR utilities
 export {
@@ -69,6 +84,45 @@ export interface SSROptions {
    * manifest entry — prod builds never emit the preamble at all.
    */
   cspNonce?: string | boolean;
+  /**
+   * Issue #192 — emit `<style>@view-transition{navigation:auto}</style>`
+   * into `<head>`. Supported browsers (Chrome/Edge ≥ 111, Safari 18.2+)
+   * show a default crossfade between cross-document navigations; others
+   * ignore the at-rule (no regression).
+   *
+   * Default: `true`. Pass `false` to suppress the injection — typically
+   * wired from `ManduConfig.transitions`.
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — emit the ~500-byte hover prefetch helper (`<script>`)
+   * into `<head>`. Listens for `mouseover` on same-origin `<a href="/...">`
+   * anchors and issues `<link rel="prefetch" as="document">` once per
+   * unique target. Individual links can opt out via `data-no-prefetch`.
+   *
+   * Default: `true`. Pass `false` to suppress — typically wired from
+   * `ManduConfig.prefetch`.
+   */
+  prefetch?: boolean;
+  /**
+   * Issue #191 — control dev-mode injection of the `_devtools.js` bundle
+   * (~1.15 MB React dev runtime + Mandu Kitchen panel).
+   *
+   * Three states:
+   *   - `true`  → force inject regardless of islands (explicit opt-in —
+   *              use this for SSR-only projects that still want the
+   *              Kitchen panel for local debugging).
+   *   - `false` → force skip regardless of islands (explicit opt-out —
+   *              disables Kitchen even for island projects).
+   *   - unset   → default. Inject iff the page renders at least one
+   *              hydratable island. Pure-SSR pages (no islands) download
+   *              zero devtools bytes.
+   *
+   * Wired from `ManduConfig.dev.devtools`. Only takes effect in dev mode
+   * (production builds omit the `_devtools.js` output entirely, so this
+   * flag is a no-op in prod regardless of value).
+   */
+  devtools?: boolean;
 }
 let projectRenderToString: ((element: ReactElement) => string) | null | undefined;
@@ -394,6 +448,9 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     routePattern,
     cssPath,
     islandPreWrapped,
+    transitions = true,
+    prefetch = true,
+    devtools,
   } = options;
   // CSS 링크 태그 생성
@@ -403,6 +460,20 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
+  // Issue #192 — Smooth navigation primitives.
+  // `transitions`: CSS `@view-transition { navigation: auto }` — inert in
+  //   non-supporting browsers (Firefox, older Safari), crossfade in
+  //   Chrome/Edge ≥ 111 and Safari 18.2+. Zero layout impact, ~70 bytes.
+  // `prefetch`: ~500-byte IIFE that listens for `mouseover` on internal
+  //   `<a href="/...">` anchors and issues `<link rel="prefetch">`. Honors
+  //   per-link `data-no-prefetch` opt-out.
+  // Position: immediately after `cssLinkTag` so that (a) the at-rule
+  //   parses alongside the user stylesheet, and (b) both blocks precede
+  //   user-owned `headTags` / `collectedHeadTags`, letting users override
+  //   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 : "";
   // useHead/useSeoMeta SSR 수집
   let collectedHeadTags = "";
   let headReset: (() => void) | undefined;
@@ -492,10 +563,14 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? generateFastRefreshPreambleTag(isDev, bundleManifest, resolvedCspNonce)
     : "";
-  // DevTools 번들 로드 (개발 모드)
+  // Issue #191 — DevTools 번들 (~1.15 MB) 주입 결정.
+  //   - 기본: island 이 하나라도 있을 때만 주입. Pure-SSR 페이지는 0 bytes 다운로드.
+  //   - `devtools === true`  → 강제 주입 (SSR-only 프로젝트에서 Kitchen panel 원할 때)
+  //   - `devtools === false` → 강제 스킵 (island 프로젝트에서도 Kitchen 비활성화)
+  // Cache-bust 은 `manifest.buildTime` 우선, 없으면 `Date.now()`.
   let devtoolsScript = "";
-  if (isDev) {
-    devtoolsScript = generateDevtoolsScript();
+  if (isDev && shouldInjectDevtools(devtools, bundleManifest)) {
+    devtoolsScript = generateDevtoolsScript(bundleManifest);
   }
   // #179: body 내 <link> 태그를 <head>로 호이스팅
@@ -516,6 +591,8 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${escapeHtmlText(title)}</title>
   ${cssLinkTag}
+  ${viewTransitionTag}
+  ${prefetchScriptTag}
   ${hoistedLinkTags}
   ${headTags}
   ${collectedHeadTags}
@@ -729,13 +806,75 @@ window.__MANDU_HMR_PORT__ = ${hmrPort};
 }
 /**
- * DevTools 번들 로드 스크립트 생성 (개발 모드 전용)
- * _devtools.js 번들이 자체적으로 initManduKitchen()을 호출
+ * Issue #191 — Determine whether the dev-only `_devtools.js` bundle
+ * (~1.15 MB React dev runtime + Kitchen panel) should be injected
+ * into the HTML response.
+ *
+ * Decision table (`devtools` option × manifest shape):
+ *
+ *   | `devtools`  | hasIslands | inject? | rationale                   |
+ *   |-------------|------------|---------|-----------------------------|
+ *   | `true`      | any        | YES     | explicit opt-in             |
+ *   | `false`     | any        | NO      | explicit opt-out            |
+ *   | `undefined` | true       | YES     | default, hydration runtime  |
+ *   | `undefined` | false      | NO      | pure-SSR — save 1.15 MB     |
+ *   | `undefined` | no manifest| NO      | nothing to hydrate anyway   |
+ *
+ * `hasIslands` is derived from the existing manifest shape rather than
+ * a new field, so no bundler-side change is required:
+ *   - `manifest.islands` is populated only when per-island code
+ *     splitting produced at least one bundle (build.ts:1654).
+ *   - `manifest.bundles` entries exist only for routes where
+ *     `needsHydration()` is true (build.ts:70 filter).
+ * Either non-empty ⇒ some route on this server hydrates ⇒ devtools useful.
+ *
+ * @internal Exported via `_testOnly_shouldInjectDevtools` below so
+ * `tests/runtime/devtools-inject.test.ts` can table-test the matrix
+ * without mounting React.
+ */
+function shouldInjectDevtools(
+  devtools: boolean | undefined,
+  manifest: BundleManifest | undefined,
+): boolean {
+  // Explicit overrides take absolute precedence.
+  if (devtools === true) return true;
+  if (devtools === false) return false;
+  // Default behavior: inject only when there is at least one island.
+  if (!manifest) return false;
+  const hasIslandsMap =
+    manifest.islands && Object.keys(manifest.islands).length > 0;
+  const hasBundles =
+    manifest.bundles && Object.keys(manifest.bundles).length > 0;
+  return Boolean(hasIslandsMap || hasBundles);
+}
+/**
+ * Issue #191 — DevTools 번들 로드 스크립트 생성 (개발 모드 전용).
+ *
+ * `_devtools.js` 번들이 자체적으로 `initManduKitchen()` 을 호출한다.
+ *
+ * Cache-bust: `?v=${manifest.buildTime}` 을 우선 사용하고, manifest 가 없으면
+ * `?t=${Date.now()}` 로 fallback. `buildTime` 은 빌드별로 고정이라 브라우저
+ * 캐시 효율이 좋지만, 동일 빌드 안에서 HMR 이 발생하더라도 devtools 번들은
+ * dev 서버의 static 응답이 `Cache-Control: no-cache, no-store, must-revalidate`
+ * (server.ts:1104) 를 보내므로 stale 위험이 없다.
+ *
+ * @internal Exported via `_testOnly_generateDevtoolsScript` below so tests
+ * can verify the URL shape without needing a full render.
  */
-function generateDevtoolsScript(): string {
-  return `<script type="module" src="/.mandu/client/_devtools.js"></script>`;
+function generateDevtoolsScript(manifest?: BundleManifest): string {
+  const cacheBust = manifest?.buildTime
+    ? `?v=${encodeURIComponent(manifest.buildTime)}`
+    : `?t=${Date.now()}`;
+  return `<script type="module" src="/.mandu/client/_devtools.js${cacheBust}"></script>`;
 }
+/** @internal test helper — exposed only so unit tests can inspect the decision. */
+export const _testOnly_shouldInjectDevtools = shouldInjectDevtools;
+/** @internal test helper — exposed only so unit tests can inspect the script tag. */
+export const _testOnly_generateDevtoolsScript = generateDevtoolsScript;
 export function createHTMLResponse(
   html: string,
   status: number = 200,

package/src/runtime/streaming-ssr.ts CHANGED Viewed

@@ -24,6 +24,16 @@ import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 import { getRenderToString } from "./react-renderer";
 import { mark, measure } from "../perf";
 import { generateFastRefreshPreamble } from "../bundler/dev";
+import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
+/**
+ * Issue #192 — `@view-transition` at-rule, mirror of the constant in
+ * `./ssr.ts`. Duplicated here to keep the streaming path self-contained
+ * without a cross-module runtime import cycle (ssr.ts already re-exports
+ * streaming-ssr.ts). Both constants MUST stay byte-identical.
+ */
+const VIEW_TRANSITION_STYLE_TAG =
+  "<style>@view-transition{navigation:auto}</style>";
 // ========== Types ==========
@@ -154,8 +164,67 @@ export interface StreamingSSROptions {
    * Dev + hydration + populated `shared.fastRefresh` only.
    */
   cspNonce?: string | boolean;
+  /**
+   * Issue #192 — emit `<style>@view-transition{navigation:auto}</style>`
+   * into the streaming shell `<head>`. Mirrors `SSROptions.transitions`.
+   * Default: `true`.
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — emit the ~500-byte hover prefetch helper `<script>`
+   * into the streaming shell `<head>`. Mirrors `SSROptions.prefetch`.
+   * Default: `true`.
+   */
+  prefetch?: boolean;
+  /**
+   * Issue #191 — control dev-mode injection of the `_devtools.js`
+   * bundle. Mirrors `SSROptions.devtools`:
+   *   - `true`      → force inject (explicit opt-in)
+   *   - `false`     → force skip (explicit opt-out)
+   *   - `undefined` → default; inject iff the manifest has islands.
+   */
+  devtools?: boolean;
 }
+/**
+ * Issue #191 — Streaming-SSR mirror of `ssr.ts:shouldInjectDevtools`.
+ * Kept in sync manually (tiny pure function, not worth a cross-module
+ * runtime import — the ssr.ts → streaming-ssr.ts re-export direction
+ * means a circular import here would force a refactor of the whole
+ * module graph). The unit test suite table-tests both implementations
+ * against the same matrix so drift is caught at CI time.
+ */
+function shouldInjectDevtoolsStreaming(
+  devtools: boolean | undefined,
+  manifest: BundleManifest | undefined,
+): boolean {
+  if (devtools === true) return true;
+  if (devtools === false) return false;
+  if (!manifest) return false;
+  const hasIslandsMap =
+    manifest.islands && Object.keys(manifest.islands).length > 0;
+  const hasBundles =
+    manifest.bundles && Object.keys(manifest.bundles).length > 0;
+  return Boolean(hasIslandsMap || hasBundles);
+}
+/**
+ * Issue #191 — Streaming-SSR mirror of `ssr.ts:generateDevtoolsScript`.
+ * Emits `<script type="module" src="/.mandu/client/_devtools.js?v=BUILD">`
+ * with a `buildTime`-keyed cache-bust (or `Date.now()` fallback).
+ */
+function generateStreamingDevtoolsScript(manifest: BundleManifest | undefined): string {
+  const cacheBust = manifest?.buildTime
+    ? `?v=${encodeURIComponent(manifest.buildTime)}`
+    : `?t=${Date.now()}`;
+  return `<script type="module" src="/.mandu/client/_devtools.js${cacheBust}"></script>`;
+}
+/** @internal — surface for the shared test suite in tests/runtime/devtools-inject.test.ts. */
+export const _testOnly_shouldInjectDevtoolsStreaming = shouldInjectDevtoolsStreaming;
+/** @internal — surface for the shared test suite in tests/runtime/devtools-inject.test.ts. */
+export const _testOnly_generateStreamingDevtoolsScript = generateStreamingDevtoolsScript;
 export interface StreamingLoaderResult<T = unknown> {
   /** 즉시 로드할 Critical 데이터 */
   critical?: T;
@@ -462,6 +531,8 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     hydration,
     cssPath,
     isDev = false,
+    transitions = true,
+    prefetch = true,
   } = options;
   // CSS 링크 태그 생성
@@ -471,6 +542,14 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     ? `<link rel="stylesheet" href="${escapeHtmlAttr(`${cssPath}${isDev ? `?t=${Date.now()}` : ""}`)}">`
     : "";
+  // Issue #192 — Smooth navigation primitives. Mirror of the block in
+  // `ssr.ts::renderToHTML`; see that call-site for the full rationale.
+  // Positioned right after the user stylesheet so the at-rule parses
+  // alongside it, and before user `headTags` so users can override with
+  // an inline style later in the document order.
+  const viewTransitionTag = transitions !== false ? VIEW_TRANSITION_STYLE_TAG : "";
+  const prefetchScriptTag = prefetch !== false ? PREFETCH_HELPER_SCRIPT : "";
   // Island wrapper (hydration이 필요한 경우)
   const needsHydration = hydration && hydration.strategy !== "none" && routeId && bundleManifest;
@@ -549,6 +628,8 @@ function generateHTMLShell(options: StreamingSSROptions): string {
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${escapeHtmlText(title)}</title>
   ${cssLinkTag}
+  ${viewTransitionTag}
+  ${prefetchScriptTag}
   ${loadingStyles}
   ${importMapScript}
   ${headTags}
@@ -572,6 +653,7 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     hmrPort,
     enableClientRouter = false,
     hydration,
+    devtools,
   } = options;
   const scripts: string[] = [];
@@ -658,9 +740,13 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     scripts.push(generateHMRScript(hmrPort));
   }
-  // 11. DevTools 번들 로드 (개발 모드)
-  if (isDev) {
-    scripts.push(`<script type="module" src="/.mandu/client/_devtools.js"></script>`);
+  // 11. Issue #191 — DevTools 번들 (~1.15 MB) 주입 결정.
+  //   - 기본: manifest 에 island/bundle 이 있을 때만 주입 (pure-SSR 페이지는 스킵).
+  //   - `devtools === true`  → 강제 주입 (SSR-only 프로젝트에서 Kitchen 원할 때).
+  //   - `devtools === false` → 강제 스킵.
+  //   - Cache-bust (`?v=buildTime`) 로 HMR 후 stale 방지.
+  if (isDev && shouldInjectDevtoolsStreaming(devtools, bundleManifest)) {
+    scripts.push(generateStreamingDevtoolsScript(bundleManifest));
   }
   // Island wrapper 닫기 (hydration이 필요한 경우)