@mandujs/core 0.18.1 → 0.18.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -44,14 +44,14 @@
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "zod": ">=3.0.0"
+    "react-dom": "^19.0.0"
   },
   "dependencies": {
     "chokidar": "^5.0.0",
     "fast-glob": "^3.3.2",
     "glob": "^13.0.0",
     "minimatch": "^10.1.1",
-    "ollama": "^0.6.3"
+    "ollama": "^0.6.3",
+    "zod": "^3.23.8"
   }
 }

package/src/bundler/build.ts

@@ -3,18 +3,18 @@
  * Bun.build 기반 클라이언트 번들 빌드
  */
 
-import type { RoutesManifest, RouteSpec } from "../spec/schema";
-import { needsHydration, getRouteHydration } from "../spec/schema";
-import type {
-  BundleResult,
-  BundleOutput,
-  BundleManifest,
-  BundleStats,
-  BundlerOptions,
-} from "./types";
-import { HYDRATION } from "../constants";
-import path from "path";
-import fs from "fs/promises";
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+import { needsHydration, getRouteHydration } from "../spec/schema";
+import type {
+  BundleResult,
+  BundleOutput,
+  BundleManifest,
+  BundleStats,
+  BundlerOptions,
+} from "./types";
+import { HYDRATION } from "../constants";
+import path from "path";
+import fs from "fs/promises";
 
 /**
  * 빈 매니페스트 생성
@@ -205,61 +205,88 @@ async function loadAndHydrate(element, src) {
     // Dynamic import - 이 시점에 Island 모듈 로드
     const module = await import(src);
     const island = module.default;
+    const data = getServerData(id);
 
-    // Island 유효성 검사
-    if (!island || !island.__mandu_island) {
-      throw new Error('[Mandu] Invalid island module: ' + id);
-    }
+    // Mandu Island (preferred)
+    if (island && island.__mandu_island === true) {
+      const { definition } = island;
+
+      // Island 컴포넌트 (Error Boundary + Loading 지원)
+      function IslandComponent() {
+        const [isReady, setIsReady] = useState(false);
+
+        useEffect(() => {
+          setIsReady(true);
+        }, []);
+
+        // setup 호출 및 render
+        const setupResult = definition.setup(data);
+        const content = definition.render(setupResult);
+
+        // Loading wrapper 적용
+        const wrappedContent = definition.loading
+          ? React.createElement(IslandLoadingWrapper, {
+              loading: definition.loading,
+              isReady,
+            }, content)
+          : content;
+
+        // Error Boundary 적용
+        return React.createElement(IslandErrorBoundary, {
+          islandId: id,
+          errorBoundary: definition.errorBoundary,
+        }, wrappedContent);
+      }
 
-    const { definition } = island;
-    const data = getServerData(id);
+      // Hydrate (SSR DOM 재사용 + 이벤트 연결)
+      const root = hydrateRoot(element, React.createElement(IslandComponent));
+      hydratedRoots.set(id, root);
 
-    // Island 컴포넌트 (Error Boundary + Loading 지원)
-    function IslandComponent() {
-      const [isReady, setIsReady] = useState(false);
-
-      useEffect(() => {
-        setIsReady(true);
-      }, []);
-
-      // setup 호출 및 render
-      const setupResult = definition.setup(data);
-      const content = definition.render(setupResult);
-
-      // Loading wrapper 적용
-      const wrappedContent = definition.loading
-        ? React.createElement(IslandLoadingWrapper, {
-            loading: definition.loading,
-            isReady,
-          }, content)
-        : content;
-
-      // Error Boundary 적용
-      return React.createElement(IslandErrorBoundary, {
-        islandId: id,
-        errorBoundary: definition.errorBoundary,
-      }, wrappedContent);
-    }
+      // 완료 표시
+      element.setAttribute('data-mandu-hydrated', 'true');
 
-    // Hydrate (SSR DOM 재사용 + 이벤트 연결)
-    const root = hydrateRoot(element, React.createElement(IslandComponent));
-    hydratedRoots.set(id, root);
+      // 성능 마커
+      if (performance.mark) {
+        performance.mark('mandu-hydrated-' + id);
+      }
 
-    // 완료 표시
-    element.setAttribute('data-mandu-hydrated', 'true');
+      // 이벤트 발송
+      element.dispatchEvent(new CustomEvent('mandu:hydrated', {
+        bubbles: true,
+        detail: { id, data }
+      }));
 
-    // 성능 마커
-    if (performance.mark) {
-      performance.mark('mandu-hydrated-' + id);
+      console.log('[Mandu] Hydrated:', id);
     }
+    // Plain React component fallback (e.g. "use client" pages)
+    else if (typeof island === 'function' || React.isValidElement(island)) {
+      console.warn('[Mandu] Plain component hydration:', id);
 
-    // 이벤트 발송
-    element.dispatchEvent(new CustomEvent('mandu:hydrated', {
-      bubbles: true,
-      detail: { id, data }
-    }));
+      const root = typeof island === 'function'
+        ? hydrateRoot(element, React.createElement(island, data))
+        : hydrateRoot(element, island);
+
+      hydratedRoots.set(id, root);
+
+      // 완료 표시
+      element.setAttribute('data-mandu-hydrated', 'true');
+
+      // 성능 마커
+      if (performance.mark) {
+        performance.mark('mandu-hydrated-' + id);
+      }
+
+      // 이벤트 발송
+      element.dispatchEvent(new CustomEvent('mandu:hydrated', {
+        bubbles: true,
+        detail: { id, data }
+      }));
 
-    console.log('[Mandu] Hydrated:', id);
+      console.log('[Mandu] Plain component hydrated:', id);
+    }
+    else {
+      throw new Error('[Mandu] Invalid module: expected Mandu island or React component: ' + id);
+    }
   } catch (error) {
     console.error('[Mandu] Hydration failed for', id, error);
     element.setAttribute('data-mandu-error', 'true');
@@ -282,7 +309,7 @@ function hydrateIslands() {
   for (const el of islands) {
     const id = el.getAttribute('data-mandu-island');
     const src = el.getAttribute('data-mandu-src');
-    const priority = el.getAttribute('data-mandu-priority') || '${HYDRATION.DEFAULT_PRIORITY}';
+    const priority = el.getAttribute('data-mandu-priority') || '${HYDRATION.DEFAULT_PRIORITY}';
 
     if (!id || !src) {
       console.warn('[Mandu] Island missing id or src:', el);
@@ -366,6 +393,8 @@ import React, {
   Suspense,
   StrictMode,
   Profiler,
+  // Misc
+  version,
   // Types
   Component,
   PureComponent,
@@ -377,7 +406,17 @@ import { jsx, jsxs } from 'react/jsx-runtime';
 import { jsxDEV } from 'react/jsx-dev-runtime';
 
 // React internals (ReactDOM이 내부적으로 접근 필요)
-const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED = React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED;
+// React 19+: __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE
+// React <=18: __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED
+const __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE =
+  React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE || {};
+const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED =
+  React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED || {};
+
+// Null safety for Playwright headless browsers (React 19)
+if (__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE.S == null) {
+  __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE.S = function () {};
+}
 
 // 전역 React 설정 (모든 모듈에서 동일 인스턴스 공유)
 if (typeof window !== 'undefined') {
@@ -414,9 +453,11 @@ export {
   Suspense,
   StrictMode,
   Profiler,
+  version,
   Component,
   PureComponent,
   Children,
+  __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
   __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
   // JSX Runtime exports
   jsx,
@@ -812,10 +853,8 @@ async function buildRuntime(
       },
     });
 
-    // 소스 파일 정리
-    await fs.unlink(runtimePath).catch(() => {});
-
     if (!result.success) {
+      // 실패 시 디버깅을 위해 소스 파일을 남겨둠 (_runtime.src.js)
       return {
         success: false,
         outputPath: "",
@@ -823,17 +862,28 @@ async function buildRuntime(
       };
     }
 
+    // 성공 시에만 소스 파일 정리
+    await fs.unlink(runtimePath).catch(() => {});
+
     return {
       success: true,
       outputPath: `/.mandu/client/${outputName}`,
       errors: [],
     };
-  } catch (error) {
-    await fs.unlink(runtimePath).catch(() => {});
+  } catch (error: any) {
+    // 예외 발생 시에도 디버깅을 위해 소스 파일을 남겨둠
+    const extra: string[] = [];
+    if (error?.errors && Array.isArray(error.errors)) {
+      extra.push(...error.errors.map((e: any) => String(e?.message || e)));
+    }
+    if (error?.logs && Array.isArray(error.logs)) {
+      extra.push(...error.logs.map((l: any) => String(l?.message || l)));
+    }
+
     return {
       success: false,
       outputPath: "",
-      errors: [String(error)],
+      errors: [String(error), ...extra].filter(Boolean),
     };
   }
 }
@@ -855,21 +905,21 @@ interface VendorBuildResult {
  * Vendor shim 번들 빌드
  * React, ReactDOM, ReactDOMClient를 각각의 shim으로 빌드
  */
-async function buildVendorShims(
-  outDir: string,
-  options: BundlerOptions
-): Promise<VendorBuildResult> {
-  const errors: string[] = [];
-  type VendorShimKey = "react" | "reactDom" | "reactDomClient" | "jsxRuntime" | "jsxDevRuntime";
-  const results: Record<VendorShimKey, string> = {
-    react: "",
-    reactDom: "",
-    reactDomClient: "",
-    jsxRuntime: "",
-    jsxDevRuntime: "",
-  };
-
-  const shims: Array<{ name: string; source: string; key: VendorShimKey }> = [
+async function buildVendorShims(
+  outDir: string,
+  options: BundlerOptions
+): Promise<VendorBuildResult> {
+  const errors: string[] = [];
+  type VendorShimKey = "react" | "reactDom" | "reactDomClient" | "jsxRuntime" | "jsxDevRuntime";
+  const results: Record<VendorShimKey, string> = {
+    react: "",
+    reactDom: "",
+    reactDomClient: "",
+    jsxRuntime: "",
+    jsxDevRuntime: "",
+  };
+
+  const shims: Array<{ name: string; source: string; key: VendorShimKey }> = [
     { name: "_react", source: generateReactShimSource(), key: "react" },
     { name: "_react-dom", source: generateReactDOMShimSource(), key: "reactDom" },
     { name: "_react-dom-client", source: generateReactDOMClientShimSource(), key: "reactDomClient" },
@@ -877,68 +927,68 @@ async function buildVendorShims(
     { name: "_jsx-dev-runtime", source: generateJsxDevRuntimeShimSource(), key: "jsxDevRuntime" },
   ];
 
-  const buildShim = async (
-    shim: { name: string; source: string; key: VendorShimKey }
-  ): Promise<{ key: VendorShimKey; outputPath?: string; error?: string }> => {
-    const srcPath = path.join(outDir, `${shim.name}.src.js`);
-    const outputName = `${shim.name}.js`;
-
-    try {
-      await Bun.write(srcPath, shim.source);
-
-      // _react.js는 external 없이 React 전체를 번들링
-      // _react-dom*, jsx-runtime은 react를 external로 처리하여 동일한 React 인스턴스 공유
-      let shimExternal: string[] = [];
-      if (shim.name === "_react-dom" || shim.name === "_react-dom-client") {
-        shimExternal = ["react"];
-      } else if (shim.name === "_jsx-runtime" || shim.name === "_jsx-dev-runtime") {
-        shimExternal = ["react"];
-      }
-
-      const result = await Bun.build({
-        entrypoints: [srcPath],
-        outdir: outDir,
-        naming: outputName,
-        minify: options.minify ?? process.env.NODE_ENV === "production",
-        sourcemap: options.sourcemap ? "external" : "none",
-        target: "browser",
-        external: shimExternal,
-        define: {
-          "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
-          ...options.define,
-        },
-      });
-
-      await fs.unlink(srcPath).catch(() => {});
-
-      if (!result.success) {
-        return {
-          key: shim.key,
-          error: `[${shim.name}] ${result.logs.map((l) => l.message).join(", ")}`,
-        };
-      }
-
-      return {
-        key: shim.key,
-        outputPath: `/.mandu/client/${outputName}`,
-      };
-    } catch (error) {
-      await fs.unlink(srcPath).catch(() => {});
-      return {
-        key: shim.key,
-        error: `[${shim.name}] ${String(error)}`,
-      };
-    }
-  };
-
-  const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
-  for (const result of buildResults) {
-    if (result.error) {
-      errors.push(result.error);
-    } else if (result.outputPath) {
-      results[result.key] = result.outputPath;
-    }
-  }
+  const buildShim = async (
+    shim: { name: string; source: string; key: VendorShimKey }
+  ): Promise<{ key: VendorShimKey; outputPath?: string; error?: string }> => {
+    const srcPath = path.join(outDir, `${shim.name}.src.js`);
+    const outputName = `${shim.name}.js`;
+
+    try {
+      await Bun.write(srcPath, shim.source);
+
+      // _react.js는 external 없이 React 전체를 번들링
+      // _react-dom*, jsx-runtime은 react를 external로 처리하여 동일한 React 인스턴스 공유
+      let shimExternal: string[] = [];
+      if (shim.name === "_react-dom" || shim.name === "_react-dom-client") {
+        shimExternal = ["react"];
+      } else if (shim.name === "_jsx-runtime" || shim.name === "_jsx-dev-runtime") {
+        shimExternal = ["react"];
+      }
+
+      const result = await Bun.build({
+        entrypoints: [srcPath],
+        outdir: outDir,
+        naming: outputName,
+        minify: options.minify ?? process.env.NODE_ENV === "production",
+        sourcemap: options.sourcemap ? "external" : "none",
+        target: "browser",
+        external: shimExternal,
+        define: {
+          "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
+          ...options.define,
+        },
+      });
+
+      await fs.unlink(srcPath).catch(() => {});
+
+      if (!result.success) {
+        return {
+          key: shim.key,
+          error: `[${shim.name}] ${result.logs.map((l) => l.message).join(", ")}`,
+        };
+      }
+
+      return {
+        key: shim.key,
+        outputPath: `/.mandu/client/${outputName}`,
+      };
+    } catch (error) {
+      await fs.unlink(srcPath).catch(() => {});
+      return {
+        key: shim.key,
+        error: `[${shim.name}] ${String(error)}`,
+      };
+    }
+  };
+
+  const buildResults = await Promise.all(shims.map((shim) => buildShim(shim)));
+  for (const result of buildResults) {
+    if (result.error) {
+      errors.push(result.error);
+    } else if (result.outputPath) {
+      results[result.key] = result.outputPath;
+    }
+  }
 
   return {
     success: errors.length === 0,
@@ -1052,7 +1102,7 @@ function createBundleManifest(
     bundles[output.routeId] = {
       js: output.outputPath,
       dependencies: ["_runtime", "_react"],
-      priority: hydration?.priority || HYDRATION.DEFAULT_PRIORITY,
+      priority: hydration?.priority || HYDRATION.DEFAULT_PRIORITY,
     };
   }
 

package/src/runtime/shims.ts

@@ -0,0 +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>`;

package/src/runtime/ssr.ts

@@ -6,6 +6,7 @@ import type { BundleManifest } from "../bundler/types";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { PORTS, TIMEOUTS } from "../constants";
 import { escapeHtmlAttr, escapeJsonForInlineScript } from "./escape";
+import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 
 // Re-export streaming SSR utilities
 export {
@@ -251,6 +252,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   ${dataScript}
   ${routeScript}
   ${hydrationScripts}
+  ${needsHydration ? REACT_INTERNALS_SHIM_SCRIPT : ""}
   ${routerScript}
   ${hmrScript}
   ${bodyEndTags}

package/src/runtime/streaming-ssr.ts

@@ -19,6 +19,7 @@ import type { Metadata, MetadataItem } from "../seo/types";
 import { injectSEOIntoOptions, resolveSEO, type SEOOptions } from "../seo/integration/ssr";
 import { PORTS, TIMEOUTS } from "../constants";
 import { escapeHtmlAttr, escapeJsonForInlineScript, escapeJsString } from "./escape";
+import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 
 // ========== Types ==========
 
@@ -507,6 +508,11 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
     scripts.push(`<script type="module" src="${escapeHtmlAttr(bundleManifest.shared.runtime)}"></script>`);
   }
 
+  // 7.5 React internals shim (must run before react-dom/client runs)
+  if (hydration && hydration.strategy !== "none") {
+    scripts.push(REACT_INTERNALS_SHIM_SCRIPT);
+  }
+
   // 8. Router 스크립트
   if (enableClientRouter && bundleManifest?.shared?.router) {
     scripts.push(`<script type="module" src="${escapeHtmlAttr(bundleManifest.shared.router)}"></script>`);