@mandujs/core 0.18.2 → 0.18.3

package/package.json

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

package/src/bundler/build.ts

@@ -205,11 +205,11 @@ async function loadAndHydrate(element, src) {
     // Dynamic import - 이 시점에 Island 모듈 로드
     const module = await import(src);
     const island = module.default;
+    const data = getServerData(id);
 
     // Mandu Island (preferred)
     if (island && island.__mandu_island === true) {
       const { definition } = island;
-      const data = getServerData(id);
 
       // Island 컴포넌트 (Error Boundary + Loading 지원)
       function IslandComponent() {
@@ -258,11 +258,14 @@ async function loadAndHydrate(element, src) {
 
       console.log('[Mandu] Hydrated:', id);
     }
-    // Plain React component fallback
+    // Plain React component fallback (e.g. "use client" pages)
     else if (typeof island === 'function' || React.isValidElement(island)) {
       console.warn('[Mandu] Plain component hydration:', id);
-      const data = getServerData(id);
-      const root = hydrateRoot(element, React.createElement(island, data));
+
+      const root = typeof island === 'function'
+        ? hydrateRoot(element, React.createElement(island, data))
+        : hydrateRoot(element, island);
+
       hydratedRoots.set(id, root);
 
       // 완료 표시
@@ -390,6 +393,8 @@ import React, {
   Suspense,
   StrictMode,
   Profiler,
+  // Misc
+  version,
   // Types
   Component,
   PureComponent,
@@ -401,15 +406,16 @@ 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 (Playwright headless 환경 호환성)
+// 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
+// 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() {};
+  __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE.S = function () {};
 }
 
 // 전역 React 설정 (모든 모듈에서 동일 인스턴스 공유)
@@ -447,20 +453,18 @@ export {
   Suspense,
   StrictMode,
   Profiler,
+  version,
   Component,
   PureComponent,
   Children,
-  __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
   __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,
   jsxs,
   jsxDEV,
 };
 
-// Version export (React 19 compatibility)
-export const version = React.version;
-
 // Default export
 export default React;
 `;
@@ -849,10 +853,8 @@ async function buildRuntime(
       },
     });
 
-    // 소스 파일 정리
-    await fs.unlink(runtimePath).catch(() => {});
-
     if (!result.success) {
+      // 실패 시 디버깅을 위해 소스 파일을 남겨둠 (_runtime.src.js)
       return {
         success: false,
         outputPath: "",
@@ -860,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),
     };
   }
 }

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>`);