@mandujs/core 0.18.22 → 0.19.2

package/src/bundler/build.ts

@@ -47,6 +47,78 @@ function getHydratedRoutes(manifest: RoutesManifest): RouteSpec[] {
   );
 }
 
+const REACT_SHIM_EXPORTS = [
+  "Activity",
+  "Children",
+  "Component",
+  "Fragment",
+  "Profiler",
+  "PureComponent",
+  "StrictMode",
+  "Suspense",
+  "__COMPILER_RUNTIME",
+  "act",
+  "cache",
+  "cacheSignal",
+  "captureOwnerStack",
+  "cloneElement",
+  "createContext",
+  "createElement",
+  "createRef",
+  "forwardRef",
+  "isValidElement",
+  "lazy",
+  "memo",
+  "startTransition",
+  "unstable_useCacheRefresh",
+  "use",
+  "useActionState",
+  "useCallback",
+  "useContext",
+  "useDebugValue",
+  "useDeferredValue",
+  "useEffect",
+  "useEffectEvent",
+  "useId",
+  "useImperativeHandle",
+  "useInsertionEffect",
+  "useLayoutEffect",
+  "useMemo",
+  "useOptimistic",
+  "useReducer",
+  "useRef",
+  "useState",
+  "useSyncExternalStore",
+  "useTransition",
+  "version",
+] as const;
+
+const REACT_DOM_SHIM_EXPORTS = [
+  "createPortal",
+  "flushSync",
+  "preconnect",
+  "prefetchDNS",
+  "preinit",
+  "preinitModule",
+  "preload",
+  "preloadModule",
+  "requestFormReset",
+  "unstable_batchedUpdates",
+  "useFormState",
+  "useFormStatus",
+  "version",
+] as const;
+
+const REACT_DOM_CLIENT_SHIM_EXPORTS = [
+  "createRoot",
+  "hydrateRoot",
+  "version",
+] as const;
+
+function formatShimBindings(names: readonly string[], indent = "  "): string {
+  return names.map((name) => `${indent}${name},`).join("\n");
+}
+
 /**
  * Runtime 번들 소스 생성 (v0.8.0 재설계)
  *
@@ -66,7 +138,7 @@ function generateRuntimeSource(): string {
 
 // React 정적 import (Island와 같은 인스턴스 공유)
 import React, { useState, useEffect, Component } from 'react';
-import { hydrateRoot } from 'react-dom/client';
+import { hydrateRoot, createRoot } from 'react-dom/client';
 
 // Hydrated roots 추적 (unmount용) - 전역 초기화
 window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
@@ -147,6 +219,67 @@ function IslandLoadingWrapper({ children, loading, isReady }) {
   return children;
 }
 
+function resolveHydrationTarget(element) {
+  if (!(element instanceof HTMLElement)) {
+    return element;
+  }
+
+  if (getComputedStyle(element).display !== 'contents') {
+    return element;
+  }
+
+  const queue = Array.from(element.children);
+  while (queue.length > 0) {
+    const candidate = queue.shift();
+    if (candidate instanceof HTMLElement) {
+      return candidate;
+    }
+    if (candidate) {
+      queue.push(...candidate.children);
+    }
+  }
+
+  return element.parentElement || element;
+}
+
+function hasHydratableMarkup(element) {
+  for (const node of element.childNodes) {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      return true;
+    }
+
+    if (node.nodeType === Node.TEXT_NODE && node.textContent && node.textContent.trim() !== '') {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function shouldHydrateCompiledIsland(element) {
+  return (
+    element.getAttribute('data-mandu-loading') !== 'true' &&
+    hasHydratableMarkup(element)
+  );
+}
+
+function createHydrationOptions(element, id, mode) {
+  return {
+    onRecoverableError(error) {
+      element.setAttribute('data-mandu-recoverable-error', 'true');
+      console.warn('[Mandu] Recoverable hydration error:', id, mode, error);
+      element.dispatchEvent(new CustomEvent('mandu:recoverable-hydration-error', {
+        bubbles: true,
+        detail: {
+          id,
+          mode,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      }));
+    },
+  };
+}
+
 /**
  * Hydration 스케줄러
  */
@@ -164,7 +297,8 @@ function scheduleHydration(element, src, priority) {
             loadAndHydrate(element, src);
           }
         }, { rootMargin: '50px' });
-        observer.observe(element);
+        const target = resolveHydrationTarget(element);
+        observer.observe(target);
       } else {
         loadAndHydrate(element, src);
       }
@@ -179,15 +313,20 @@ function scheduleHydration(element, src, priority) {
       break;
 
     case 'interaction': {
+      const target = resolveHydrationTarget(element);
       const hydrate = () => {
-        element.removeEventListener('mouseenter', hydrate);
-        element.removeEventListener('focusin', hydrate);
-        element.removeEventListener('touchstart', hydrate);
+        target.removeEventListener('mouseenter', hydrate);
+        target.removeEventListener('focusin', hydrate);
+        target.removeEventListener('touchstart', hydrate);
+        target.removeEventListener('pointerdown', hydrate);
+        target.removeEventListener('keydown', hydrate);
         loadAndHydrate(element, src);
       };
-      element.addEventListener('mouseenter', hydrate, { once: true, passive: true });
-      element.addEventListener('focusin', hydrate, { once: true });
-      element.addEventListener('touchstart', hydrate, { once: true, passive: true });
+      target.addEventListener('mouseenter', hydrate, { once: true, passive: true });
+      target.addEventListener('focusin', hydrate, { once: true });
+      target.addEventListener('touchstart', hydrate, { once: true, passive: true });
+      target.addEventListener('pointerdown', hydrate, { once: true, passive: true });
+      target.addEventListener('keydown', hydrate, { once: true });
       break;
     }
   }
@@ -200,20 +339,47 @@ function scheduleHydration(element, src, priority) {
  */
 async function loadAndHydrate(element, src) {
   const id = element.getAttribute('data-mandu-island');
+  if (!id) {
+    return;
+  }
+
+  if (
+    hydratedRoots.has(id) ||
+    element.hasAttribute('data-mandu-hydrated') ||
+    element.getAttribute('data-mandu-hydrating') === 'true'
+  ) {
+    return;
+  }
+
+  element.setAttribute('data-mandu-hydrating', 'true');
 
   try {
     // Dynamic import - 이 시점에 Island 모듈 로드
     const module = await import(src);
     const island = module.default;
-    const data = getServerData(id);
+    let data = getServerData(id);
+
+    // Fallback: read data-props from child element if __MANDU_DATA__ is empty
+    if (!data || Object.keys(data).length === 0) {
+      const propsEl = element.querySelector('[data-props]');
+      if (propsEl) {
+        try {
+          data = JSON.parse(propsEl.getAttribute('data-props'));
+        } catch (e) {
+          console.warn('[Mandu] Failed to parse data-props fallback:', e);
+        }
+      }
+    }
 
     // Mandu Island (preferred)
     if (island && island.__mandu_island === true) {
       const { definition } = island;
+      const shouldHydrate = shouldHydrateCompiledIsland(element);
+      const renderMode = shouldHydrate ? 'hydrate' : 'mount';
 
       // Island 컴포넌트 (Error Boundary + Loading 지원)
-      function IslandComponent() {
-        const [isReady, setIsReady] = useState(false);
+      function IslandComponent({ initialReady }) {
+        const [isReady, setIsReady] = useState(initialReady);
 
         useEffect(() => {
           setIsReady(true);
@@ -238,11 +404,22 @@ async function loadAndHydrate(element, src) {
         }, wrappedContent);
       }
 
-      // Hydrate (SSR DOM 재사용 + 이벤트 연결)
-      const root = hydrateRoot(element, React.createElement(IslandComponent));
+      const root = shouldHydrate
+        ? hydrateRoot(
+            element,
+            React.createElement(IslandComponent, { initialReady: true }),
+            createHydrationOptions(element, id, renderMode)
+          )
+        : createRoot(element);
+
+      if (!shouldHydrate) {
+        root.render(React.createElement(IslandComponent, { initialReady: false }));
+      }
+
       hydratedRoots.set(id, root);
 
       // 완료 표시
+      element.setAttribute('data-mandu-render-mode', renderMode);
       element.setAttribute('data-mandu-hydrated', 'true');
 
       // 성능 마커
@@ -253,22 +430,47 @@ async function loadAndHydrate(element, src) {
       // 이벤트 발송
       element.dispatchEvent(new CustomEvent('mandu:hydrated', {
         bubbles: true,
-        detail: { id, data }
+        detail: { id, data, mode: renderMode }
       }));
 
-      console.log('[Mandu] Hydrated:', id);
+      // Kitchen DevTools에 island 등록
+      if (window.__MANDU_DEVTOOLS_HOOK__) {
+        const hydrateTime = performance.now ? performance.now() : Date.now();
+        window.__MANDU_DEVTOOLS_HOOK__.emit({
+          type: 'island:register',
+          timestamp: Date.now(),
+          data: {
+            id,
+            name: id,
+            strategy: element.getAttribute('data-mandu-priority') || 'visible',
+            status: 'hydrated',
+            renderMode,
+            hydrateStartTime: hydrateTime - 10,
+            hydrateEndTime: hydrateTime,
+            propsSize: JSON.stringify(data).length,
+          },
+        });
+      }
+
+      console.log('[Mandu] Hydrated:', id, '(' + renderMode + ')');
     }
     // 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 renderMode = 'hydrate';
 
       const root = typeof island === 'function'
-        ? hydrateRoot(element, React.createElement(island, data))
-        : hydrateRoot(element, island);
+        ? hydrateRoot(
+            element,
+            React.createElement(island, data),
+            createHydrationOptions(element, id, renderMode)
+          )
+        : hydrateRoot(element, island, createHydrationOptions(element, id, renderMode));
 
       hydratedRoots.set(id, root);
 
       // 완료 표시
+      element.setAttribute('data-mandu-render-mode', renderMode);
       element.setAttribute('data-mandu-hydrated', 'true');
 
       // 성능 마커
@@ -279,10 +481,10 @@ async function loadAndHydrate(element, src) {
       // 이벤트 발송
       element.dispatchEvent(new CustomEvent('mandu:hydrated', {
         bubbles: true,
-        detail: { id, data }
+        detail: { id, data, mode: renderMode }
       }));
 
-      console.log('[Mandu] Plain component hydrated:', id);
+      console.log('[Mandu] Plain component hydrated:', id, '(' + renderMode + ')');
     }
     else {
       throw new Error('[Mandu] Invalid module: expected Mandu island or React component: ' + id);
@@ -296,6 +498,8 @@ async function loadAndHydrate(element, src) {
       bubbles: true,
       detail: { id, error: error.message }
     }));
+  } finally {
+    element.removeAttribute('data-mandu-hydrating');
   }
 }
 
@@ -363,42 +567,7 @@ function generateReactShimSource(): string {
  * import map을 통해 bare specifier 해결
  */
 import React, {
-  // Core
-  createElement,
-  cloneElement,
-  createContext,
-  createRef,
-  forwardRef,
-  isValidElement,
-  memo,
-  lazy,
-  // Hooks
-  useState,
-  useEffect,
-  useContext,
-  useReducer,
-  useCallback,
-  useMemo,
-  useRef,
-  useLayoutEffect,
-  useImperativeHandle,
-  useDebugValue,
-  useDeferredValue,
-  useTransition,
-  useId,
-  useSyncExternalStore,
-  useInsertionEffect,
-  // Components
-  Fragment,
-  Suspense,
-  StrictMode,
-  Profiler,
-  // Misc
-  version,
-  // Types
-  Component,
-  PureComponent,
-  Children,
+${formatShimBindings(REACT_SHIM_EXPORTS)}
 } from 'react';
 
 // JSX Runtime functions (JSX 변환에 필요)
@@ -426,37 +595,7 @@ if (typeof window !== 'undefined') {
 
 // Named exports
 export {
-  createElement,
-  cloneElement,
-  createContext,
-  createRef,
-  forwardRef,
-  isValidElement,
-  memo,
-  lazy,
-  useState,
-  useEffect,
-  useContext,
-  useReducer,
-  useCallback,
-  useMemo,
-  useRef,
-  useLayoutEffect,
-  useImperativeHandle,
-  useDebugValue,
-  useDeferredValue,
-  useTransition,
-  useId,
-  useSyncExternalStore,
-  useInsertionEffect,
-  Fragment,
-  Suspense,
-  StrictMode,
-  Profiler,
-  version,
-  Component,
-  PureComponent,
-  Children,
+${formatShimBindings(REACT_SHIM_EXPORTS)}
   __CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE,
   __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED,
   // JSX Runtime exports
@@ -480,16 +619,12 @@ function generateReactDOMShimSource(): string {
  * Mandu React DOM Shim (Generated)
  */
 import ReactDOM, {
-  createPortal,
-  flushSync,
-  version,
+${formatShimBindings(REACT_DOM_SHIM_EXPORTS)}
 } from 'react-dom';
 
 // Named exports
 export {
-  createPortal,
-  flushSync,
-  version,
+${formatShimBindings(REACT_DOM_SHIM_EXPORTS)}
 };
 
 // Default export
@@ -506,13 +641,19 @@ function generateReactDOMClientShimSource(): string {
 /**
  * Mandu React DOM Client Shim (Generated)
  */
-import { createRoot, hydrateRoot } from 'react-dom/client';
+import { 
+${formatShimBindings(REACT_DOM_CLIENT_SHIM_EXPORTS)}
+} from 'react-dom/client';
 
 // Named exports (명시적으로 re-export)
-export { createRoot, hydrateRoot };
+export { 
+${formatShimBindings(REACT_DOM_CLIENT_SHIM_EXPORTS)}
+};
 
 // Default export
-export default { createRoot, hydrateRoot };
+export default { 
+${formatShimBindings(REACT_DOM_CLIENT_SHIM_EXPORTS)}
+};
 `;
 }
 
@@ -1087,7 +1228,7 @@ async function buildIsland(
       minify: options.minify ?? process.env.NODE_ENV === "production",
       sourcemap: options.sourcemap ? "external" : "none",
       target: "browser",
-      splitting: options.splitting ?? false,
+      splitting: options.splitting ?? (process.env.NODE_ENV === "production"),
       external: ["react", "react-dom", "react-dom/client", ...(options.external || [])],
       define: {
         "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "development"),
@@ -1305,24 +1446,28 @@ export async function buildClientBundles(
       return buildClientBundles(manifest, rootDir, { ...options, targetRouteIds: undefined });
     }
 
-    for (const output of outputs) {
-      if (existingManifest.bundles[output.routeId]) {
-        existingManifest.bundles[output.routeId].js = output.outputPath;
-      } else {
-        const route = targetRoutes.find((r) => r.id === output.routeId);
-        const hydration = route ? getRouteHydration(route) : null;
-        existingManifest.bundles[output.routeId] = {
-          js: output.outputPath,
-          dependencies: ["_runtime", "_react"],
-          priority: hydration?.priority || HYDRATION.DEFAULT_PRIORITY,
-        };
+    // Only update manifest with successfully built outputs (#10: preserve previous good manifest on failure)
+    if (outputs.length > 0) {
+      for (const output of outputs) {
+        if (existingManifest.bundles[output.routeId]) {
+          existingManifest.bundles[output.routeId].js = output.outputPath;
+        } else {
+          const route = targetRoutes.find((r) => r.id === output.routeId);
+          const hydration = route ? getRouteHydration(route) : null;
+          existingManifest.bundles[output.routeId] = {
+            js: output.outputPath,
+            dependencies: ["_runtime", "_react"],
+            priority: hydration?.priority || HYDRATION.DEFAULT_PRIORITY,
+          };
+        }
       }
-    }
 
-    await fs.writeFile(
-      path.join(rootDir, ".mandu/manifest.json"),
-      JSON.stringify(existingManifest, null, 2)
-    );
+      await fs.writeFile(
+        path.join(rootDir, ".mandu/manifest.json"),
+        JSON.stringify(existingManifest, null, 2)
+      );
+    }
+    // When all builds failed, do NOT overwrite manifest — keep previous good state
 
     const stats = calculateStats(outputs, startTime);
     return { success: errors.length === 0, outputs, errors, manifest: existingManifest, stats };
@@ -1356,13 +1501,46 @@ export async function buildClientBundles(
     console.warn("[Mandu] DevTools bundle build failed:", devtoolsResult.errors.join(", "));
   }
 
+  // 4.5. Pre-build validation: detect wrong import paths in island files
+  for (const route of hydratedRoutes) {
+    if (route.clientModule) {
+      const clientModulePath = path.join(rootDir, route.clientModule);
+      try {
+        const source = await fs.readFile(clientModulePath, "utf-8");
+        // Match imports from "@mandujs/core" but NOT "@mandujs/core/client" or other subpaths
+        const wrongImportPattern = /(?:import|from)\s+['"]@mandujs\/core['"]|require\s*\(\s*['"]@mandujs\/core['"]\s*\)/;
+        if (wrongImportPattern.test(source)) {
+          const errMsg =
+            `[${route.id}] Island file "${route.clientModule}" imports from "@mandujs/core" which is a server-side module.\n` +
+            `  Fix: Change the import to "@mandujs/core/client".\n` +
+            `  Client islands cannot use server-side modules.`;
+          console.error(`\n\x1b[31mERROR: ${errMsg}\x1b[0m\n`);
+          errors.push(errMsg);
+        }
+      } catch {
+        // File read failure will be caught later during build
+      }
+    }
+  }
+
   // 5. 각 Island 번들 빌드
   for (const route of hydratedRoutes) {
     try {
       const result = await buildIsland(route, rootDir, outDir, options);
       outputs.push(result);
     } catch (error) {
-      errors.push(`[${route.id}] ${String(error)}`);
+      const errorStr = String(error);
+      // Detect common mistake: importing @mandujs/core (server module) in client island
+      if (errorStr.includes("AggregateError") || errorStr.includes("Could not resolve")) {
+        const clientModule = route.clientModule || "";
+        errors.push(
+          `[${route.id}] ${errorStr}\n` +
+          `  💡 Hint: If your island imports from "@mandujs/core", change it to "@mandujs/core/client".\n` +
+          `     Client islands cannot use server-side modules. File: ${clientModule}`
+        );
+      } else {
+        errors.push(`[${route.id}] ${errorStr}`);
+      }
     }
   }
 

package/src/bundler/css.ts

@@ -8,11 +8,24 @@
  * - 출력: .mandu/client/globals.css
  */
 
-import { spawn, type Subprocess } from "bun";
+import { spawn, which, type Subprocess } from "bun";
 import path from "path";
 import fs from "fs/promises";
 import { watch as fsWatch, type FSWatcher } from "fs";
 
+/**
+ * Tailwind CLI 실행 명령어를 결정한다.
+ * bunx가 PATH에 없는 환경(일부 Windows/CI)에서도 동작하도록
+ * `bun x`로 fallback한다.
+ */
+function getTailwindCommand(args: string[]): string[] {
+  if (which("bunx")) {
+    return ["bunx", ...args];
+  }
+  // bunx shim이 없어도 `bun x`는 동작함
+  return ["bun", "x", ...args];
+}
+
 // ========== Types ==========
 
 export interface CSSBuildOptions {
@@ -124,7 +137,7 @@ export async function buildCSS(options: CSSBuildOptions): Promise<CSSBuildResult
   }
 
   try {
-    const proc = spawn(["bunx", ...args], {
+    const proc = spawn(getTailwindCommand(args), {
       cwd: rootDir,
       stdout: "pipe",
       stderr: "pipe",
@@ -206,7 +219,7 @@ export async function startCSSWatch(options: CSSBuildOptions): Promise<CSSWatche
   // Bun subprocess로 Tailwind CLI 실행
   let proc;
   try {
-    proc = spawn(["bunx", ...args], {
+    proc = spawn(getTailwindCommand(args), {
       cwd: rootDir,
       stdout: "pipe",
       stderr: "pipe",
@@ -275,7 +288,9 @@ export async function startCSSWatch(options: CSSBuildOptions): Promise<CSSWatche
       const { done, value } = await reader.read();
       if (done) break;
 
-      const text = decoder.decode(value).trim();
+      const rawText = decoder.decode(value).trim();
+      // ANSI 이스케이프 코드 제거 후 비교 (Tailwind CLI가 컬러 출력)
+      const text = rawText.replace(/\u001b\[[0-9;]*m/g, "").trim();
       if (text) {
         // 환경 경고 무시
         if (text.includes(".bash_profile") || text.includes("$'\\377")) {
@@ -287,7 +302,7 @@ export async function startCSSWatch(options: CSSBuildOptions): Promise<CSSWatche
           text.includes("Resolving dependencies") ||
           text.includes("Resolved, downloaded") ||
           text.includes("Saved lockfile") ||
-          text.includes("≈ tailwindcss") ||
+          text.includes("tailwindcss") ||
           text.match(/^v?\d+\.\d+\.\d+/) // 버전 출력
         ) {
           if (text) console.log(`   ℹ️  CSS: ${text}`);