@mandujs/core 0.54.31 → 0.55.0-beta.1

package/src/runtime/server.ts

@@ -436,9 +436,11 @@ export interface ManduServer {
   router: Router;
   /** 이 서버 인스턴스의 레지스트리 */
   registry: ServerRegistry;
-  /** Replace the live dispatch table after FS routes change in dev mode. */
-  updateManifest: (nextManifest: RoutesManifest) => void;
-  stop: () => void;
+  /** Replace the live dispatch table after FS routes change in dev mode. */
+  updateManifest: (nextManifest: RoutesManifest) => void;
+  /** Replace the client artifact manifest after a dev-server restart. */
+  updateBundleManifest: (nextManifest: BundleManifest | undefined) => void;
+  stop: () => void;
 }
 
 export type ApiHandler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
@@ -3605,14 +3607,15 @@ function isPortInUseError(error: unknown): boolean {
   return code === "EADDRINUSE" || message.includes("EADDRINUSE") || message.includes("address already in use");
 }
 
-function startBunServerWithFallback(options: {
+function startBunServerWithFallback(options: {
   port: number;
   hostname?: string;
   fetch: (req: Request, server: Server<undefined>) => Promise<Response | undefined>;
   websocket?: Record<string, unknown>;
 }): { server: Server<undefined>; port: number; attempts: number } {
-  const { port: startPort, hostname, fetch, websocket } = options;
-  let lastError: unknown = null;
+  const { port: startPort, hostname, fetch, websocket } = options;
+  let lastError: unknown = null;
+  const attemptedPorts: number[] = [];
 
   // `Parameters<typeof Bun.serve>[0]` captures the full `Serve.Options`
   // XOR union. We only ever use the hostname/port branch, so cast through
@@ -3630,10 +3633,11 @@ function startBunServerWithFallback(options: {
 
   for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
     const candidate = startPort + attempt;
-    if (candidate < 1 || candidate > 65535) {
-      continue;
-    }
-    try {
+    if (candidate < 1 || candidate > 65535) {
+      continue;
+    }
+    attemptedPorts.push(candidate);
+    try {
       const server = Bun.serve({ port: candidate, ...serveOptions } as unknown as BunServeOptions);
       return { server, port: server.port ?? candidate, attempts: attempt };
     } catch (error) {
@@ -3642,10 +3646,22 @@ function startBunServerWithFallback(options: {
       }
       lastError = error;
     }
-  }
-
-  throw lastError ?? new Error(`No available port found starting at ${startPort}`);
-}
+  }
+
+  const attemptedRange = attemptedPorts.length === 0
+    ? String(startPort)
+    : attemptedPorts.length === 1
+      ? String(attemptedPorts[0])
+      : `${attemptedPorts[0]}-${attemptedPorts.at(-1)}`;
+  const bindHost = hostname?.trim() || "::";
+  const fatal = new Error(
+    `[Mandu Port Bind Failed] Could not bind ${bindHost} on port(s) ${attemptedRange}. ` +
+      "All candidates are already in use. Stop the conflicting process or choose another port with --port <number>.",
+  );
+  fatal.name = "ManduPortBindError";
+  (fatal as Error & { cause?: unknown }).cause = lastError;
+  throw fatal;
+}
 
 // ========== Server Startup ==========
 
@@ -3782,13 +3798,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   if (i18nOption !== undefined && !isI18nDefinition(i18nOption)) {
     throw new Error(
       "[mandu] ServerOptions.i18n must be the return value of defineI18n(). " +
-        "Import { defineI18n } from '@mandujs/core/i18n'."
+        "Import { defineI18n } from '@mandujs/core/compat/i18n/index'."
     );
   }
   if (messagesOption !== undefined && !isMessageRegistry(messagesOption)) {
     throw new Error(
       "[mandu] ServerOptions.messages must be the return value of defineMessages(). " +
-        "Import { defineMessages } from '@mandujs/core/i18n'."
+        "Import { defineMessages } from '@mandujs/core/compat/i18n/index'."
     );
   }
 
@@ -4124,10 +4140,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     server,
     router,
     registry,
-    updateManifest: (nextManifest: RoutesManifest) => {
-      router.setRoutes(nextManifest.routes);
-      registry.devtoolsAdapter?.updateManifest(nextManifest);
-    },
+    updateManifest: (nextManifest: RoutesManifest) => {
+      router.setRoutes(nextManifest.routes);
+      registry.devtoolsAdapter?.updateManifest(nextManifest);
+    },
+    updateBundleManifest: (nextManifest: BundleManifest | undefined) => {
+      registry.settings.bundleManifest = nextManifest;
+    },
     stop: () => {
       registry.devtoolsAdapter?.stop();
       registry.devtoolsAdapter = null;

package/src/runtime/shims.ts

@@ -1,48 +1,48 @@
-/**
- * Runtime Shims for React Compatibility
- *
- * React 19+ 호환성을 위한 런타임 shim 스크립트들을 제공합니다.
- *
- * @module runtime/shims
- */
-
-/**
- * React 19 Client Internals Shim Script
- *
- * React 19에서 react-dom/client가 실행되기 전에 ReactSharedInternals.S가
- * 존재하는지 확인하고 필요시 초기화하는 inline 스크립트입니다.
- *
- * **사용 목적**:
- * - Playwright headless 환경에서 hydration 실패 방지
- * - React 19의 __CLIENT_INTERNALS.S가 null일 수 있는 문제 해결
- * - SSR HTML에 삽입하여 번들 로드 전에 실행
- *
- * **안전성**:
- * - try-catch로 감싸져 있어 오류 발생 시에도 안전
- * - 기존 값이 있으면 덮어쓰지 않음
- * - React가 없거나 internals가 없어도 실패하지 않음
- *
- * @example
- * ```typescript
- * // SSR HTML에 삽입
- * const html = `
- *   ${hydrationScripts}
- *   ${REACT_INTERNALS_SHIM_SCRIPT}
- *   ${routerScript}
- * `;
- * ```
- */
-export const REACT_INTERNALS_SHIM_SCRIPT = `<script>
-// React 19 internals shim: ensure ReactSharedInternals.S exists before react-dom/client runs.
-// Some builds expect React.__CLIENT_INTERNALS... .S to be a function, but it may be null.
-// This shim is safe: it only fills the slot if missing.
-(function(){
-  try {
-    var React = window.React;
-    var i = React && React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
-    if (i && i.S == null) {
-      i.S = function(){};
-    }
-  } catch(e) {}
-})();
-</script>`;
+/**
+ * Runtime Shims for React Compatibility
+ *
+ * React 19+ 호환성을 위한 런타임 shim 스크립트들을 제공합니다.
+ *
+ * @module runtime/shims
+ */
+
+/**
+ * React 19 Client Internals Shim Script
+ *
+ * React 19에서 react-dom/client가 실행되기 전에 ReactSharedInternals.S가
+ * 존재하는지 확인하고 필요시 초기화하는 inline 스크립트입니다.
+ *
+ * **사용 목적**:
+ * - Playwright headless 환경에서 hydration 실패 방지
+ * - React 19의 __CLIENT_INTERNALS.S가 null일 수 있는 문제 해결
+ * - SSR HTML에 삽입하여 번들 로드 전에 실행
+ *
+ * **안전성**:
+ * - try-catch로 감싸져 있어 오류 발생 시에도 안전
+ * - 기존 값이 있으면 덮어쓰지 않음
+ * - React가 없거나 internals가 없어도 실패하지 않음
+ *
+ * @example
+ * ```typescript
+ * // SSR HTML에 삽입
+ * const html = `
+ *   ${hydrationScripts}
+ *   ${REACT_INTERNALS_SHIM_SCRIPT}
+ *   ${routerScript}
+ * `;
+ * ```
+ */
+export const REACT_INTERNALS_SHIM_SCRIPT = `<script>
+// React 19 internals shim: ensure ReactSharedInternals.S exists before react-dom/client runs.
+// Some builds expect React.__CLIENT_INTERNALS... .S to be a function, but it may be null.
+// This shim is safe: it only fills the slot if missing.
+(function(){
+  try {
+    var React = window.React;
+    var i = React && React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+    if (i && i.S == null) {
+      i.S = function(){};
+    }
+  } catch(e) {}
+})();
+</script>`;

package/src/runtime/ssr.ts

@@ -3,7 +3,11 @@ import { serializeProps } from "../client/serialize";
 import { createRequire } from "module";
 import React, { type ReactElement, type ReactNode } from "react";
 import type { BundleManifest } from "../bundler/types";
-import { isSafeManduUrl } from "../bundler/manifest-schema";
+import { isSafePublishedManduUrl } from "../bundler/manifest-schema";
+import {
+  scopeBundleManifestToGeneration,
+  scopeClientAssetUrl,
+} from "../bundler/generation";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { PORTS, TIMEOUTS } from "../constants";
 import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
@@ -319,7 +323,9 @@ export function wrapWithIsland(
   bundleSrc?: string,
   hydrate?: string
 ): string {
-  const cacheBustedSrc = bundleSrc ? `${bundleSrc}?t=${Date.now()}` : undefined;
+  const cacheBustedSrc = bundleSrc
+    ? `${bundleSrc}${bundleSrc.includes("?") ? "&" : "?"}t=${Date.now()}`
+    : undefined;
   const srcAttr = cacheBustedSrc ? ` data-mandu-src="${escapeHtmlAttr(cacheBustedSrc)}"` : "";
   const hydrateValue = hydrate ?? priorityToHydrateStrategy(priority);
   const hydrateAttr = ` data-hydrate="${escapeHtmlAttr(hydrateValue)}"`;
@@ -392,12 +398,12 @@ function generateFastRefreshPreambleTag(
   const fr = manifest?.shared?.fastRefresh;
   if (!fr) return "";
   if (!fr.glue || !fr.runtime) return "";
-  // Phase 7.2.R3 M-01 — manifest wire-up. `isSafeManduUrl` rejects
+  // Phase 7.2.R3 M-01 — manifest wire-up. The response-time validator
   // tampered entries (protocol, traversal, non-/.mandu paths, >2KB).
   // Fail closed: if either URL is suspect, skip the preamble entirely
   // — dev refresh breaks loudly instead of injecting an attacker-
   // controlled <script src> via a tampered manifest.
-  if (!isSafeManduUrl(fr.glue) || !isSafeManduUrl(fr.runtime)) return "";
+  if (!isSafePublishedManduUrl(fr.glue) || !isSafePublishedManduUrl(fr.runtime)) return "";
   const raw = generateFastRefreshPreamble(fr.glue, fr.runtime);
   if (!nonce) return raw;
   // Inject nonce attribute onto the first <script> tag ONLY. Matches
@@ -628,9 +634,13 @@ export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
   return React.cloneElement(element, undefined, resolvedChildren);
 }
 
-export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const hasExplicitTitle = options.title !== undefined;
-  const {
+export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
+  const hasExplicitTitle = options.title !== undefined;
+  const scopedBundleManifest = scopeBundleManifestToGeneration(options.bundleManifest);
+  const responseOptions = scopedBundleManifest === options.bundleManifest
+    ? options
+    : { ...options, bundleManifest: scopedBundleManifest };
+  const {
     title = "Mandu App",
     lang = "ko",
     serverData,
@@ -651,7 +661,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     devtools,
     devErrorOverlay,
     layoutChain,
-  } = options;
+  } = responseOptions;
 
   // Issue #233 — derive a stable short key for the layout chain so the
   // SPA nav helper can detect cross-layout transitions. Deterministic
@@ -1083,9 +1093,19 @@ window.__MANDU_HMR_PORT__ = ${hmrPort};
               }
             }
             if (!updated) location.reload();
-          } else if (msg.type === 'error') {
-            console.error('[Mandu HMR] Build error:', msg.data && msg.data.message);
-          }
+          } else if (msg.type === 'error') {
+            var errorData = msg.data || {};
+            console.error('[Mandu HMR] Build error:', errorData.message);
+            window.dispatchEvent(new CustomEvent('__MANDU_ERROR__', { detail: {
+              name: errorData.name || 'BuildError',
+              message: errorData.message || 'Build failed',
+              stack: errorData.stack || '',
+              kind: 'manual',
+              timestamp: errorData.timestamp || Date.now(),
+              routeId: errorData.routeId,
+              url: window.location.pathname + window.location.search
+            }}));
+          }
         } catch(err) {}
       };
       ws.onclose = function() { scheduleReconnect(); };
@@ -1148,12 +1168,18 @@ function shouldInjectDevtools(
  * @internal Exported via `_testOnly_generateDevtoolsScript` below so tests
  * can verify the URL shape without needing a full render.
  */
-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>`;
-}
+function generateDevtoolsScript(manifest?: BundleManifest): string {
+  const src = scopeClientAssetUrl(
+    "/.mandu/client/_devtools.js",
+    manifest?.generationId,
+  );
+  const key = manifest?.buildTime ? "v" : "t";
+  const value = manifest?.buildTime
+    ? encodeURIComponent(manifest.buildTime)
+    : Date.now();
+  const cacheBust = `${src.includes("?") ? "&" : "?"}${key}=${value}`;
+  return `<script type="module" src="${src}${cacheBust}"></script>`;
+}
 
 /** @internal test helper — exposed only so unit tests can inspect the decision. */
 export const _testOnly_shouldInjectDevtools = shouldInjectDevtools;