@mandujs/core 0.54.14 → 0.54.15

package/package.json

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

package/src/bundler/__tests__/hdr.test.ts

@@ -204,9 +204,16 @@ describe("Phase 7.2 Agent B — findRouteIdForSlot", () => {
 // Section B — HMR server broadcast of slot-refetch
 // -----------------------------------------------------------------------------
 
-function pickPort(): number {
-  return 40000 + Math.floor(Math.random() * 10000);
-}
+const HMR_TEST_PORT_STATE = "__MANDU_HMR_TEST_PORT_STATE__";
+
+function pickPort(): number {
+  const stateGlobal = globalThis as typeof globalThis & {
+    __MANDU_HMR_TEST_PORT_STATE__?: { next: number };
+  };
+  stateGlobal.__MANDU_HMR_TEST_PORT_STATE__ ??= { next: 0 };
+  const index = stateGlobal.__MANDU_HMR_TEST_PORT_STATE__.next++;
+  return 41000 + (((process.pid % 3500) * 2 + index * 2) % 7000);
+}
 
 describe("Phase 7.2 Agent B — slot-refetch broadcast", () => {
   let server: HMRServer | null = null;

package/src/bundler/__tests__/hmr-client.test.ts

@@ -172,17 +172,22 @@ describe("createManduHot — Vite-compat import.meta.hot runtime", () => {
  * Utility: spin up an HMR server and return it plus the public port the
  * client should dial. The caller owns teardown via `afterEach`.
  *
- * We pass `port: 0` ... almost. `createHMRServer` computes
- * `port + PORTS.HMR_OFFSET` internally, so if we want an ephemeral
- * listener we'd need to bind ahead of time. For these tests that would
- * complicate setup; we pick a random port in the high range instead
- * and accept the tiny risk of collision (test is < 1 s).
- */
-function pickPort(): number {
-  // 40000–49999 range — avoids common dev ports while staying well
-  // below ephemeral ranges Bun may pick for outbound sockets.
-  return 40000 + Math.floor(Math.random() * 10000);
-}
+ * We pass `port: 0` ... almost. `createHMRServer` computes
+ * `port + PORTS.HMR_OFFSET` internally, so if we want an ephemeral
+ * listener we'd need to bind ahead of time. These tests instead use a
+ * process-local monotonic port allocator to avoid random collisions
+ * during the full parallel core suite.
+ */
+const HMR_TEST_PORT_STATE = "__MANDU_HMR_TEST_PORT_STATE__";
+
+function pickPort(): number {
+  const stateGlobal = globalThis as typeof globalThis & {
+    __MANDU_HMR_TEST_PORT_STATE__?: { next: number };
+  };
+  stateGlobal.__MANDU_HMR_TEST_PORT_STATE__ ??= { next: 0 };
+  const index = stateGlobal.__MANDU_HMR_TEST_PORT_STATE__.next++;
+  return 41000 + (((process.pid % 3500) * 2 + index * 2) % 7000);
+}
 
 /**
  * A wrapper around WebSocket that stashes every incoming message in an

package/src/bundler/build.test.ts

@@ -128,14 +128,26 @@ afterAll(async () => {
 // subprocess via `__tests__/build-runner.ts`. In-process retry does not
 // recover from that one; a fresh module graph does.
 describe("buildClientBundles vendor shims", () => {
-  test("build succeeds", () => {
-    if (!result.success) {
-      console.error("[build.test] errors:", result.errors);
-    }
-    expect(result.success).toBe(true);
-  });
-
-  test("re-exports modern React 19 APIs used by islands", async () => {
+  test("build succeeds", () => {
+    if (!result.success) {
+      console.error("[build.test] errors:", result.errors);
+    }
+    expect(result.success).toBe(true);
+  });
+
+  test("runtime reads canonical data-hydrate strategies", async () => {
+    const runtimePath = path.join(rootDir, ".mandu", "client", "_runtime.js");
+    const runtimeSource = await readFile(runtimePath, "utf-8");
+
+    expect(runtimeSource).toContain("data-hydrate");
+    expect(runtimeSource).toContain("matchMedia");
+    expect(runtimeSource).toContain("200px");
+    expect(runtimeSource).toContain('"click"');
+    expect(runtimeSource).not.toContain("mouseenter");
+    expect(runtimeSource).not.toContain("pointerdown");
+  });
+
+  test("re-exports modern React 19 APIs used by islands", async () => {
     const reactShim = await importBuiltModule(".mandu/client/_react.js");
     const requiredExports = [
       "Activity",
@@ -187,15 +199,18 @@ describe("buildClientBundles vendor shims", () => {
     expect(runtimeSource).toContain("data-mandu-hydrating");
     expect(runtimeSource).toContain("data-mandu-render-mode");
     expect(runtimeSource).toContain("data-mandu-recoverable-error");
-    expect(runtimeSource).toContain("pointerdown");
+    expect(runtimeSource).toContain('"click"');
+    expect(runtimeSource).not.toContain("pointerdown");
   });
 
-  test("runtime parses SSR data script before island setup", async () => {
-    const runtimeSource = await readFile(path.join(rootDir, ".mandu", "client", "_runtime.js"), "utf-8");
-    expect(runtimeSource).toContain("function readManduData");
-    expect(runtimeSource).toContain("document.getElementById(\"__MANDU_DATA__\")");
-    expect(runtimeSource).toContain("JSON.parse");
-  });
+  test("runtime parses SSR data script before island setup", async () => {
+    const runtimeSource = await readFile(path.join(rootDir, ".mandu", "client", "_runtime.js"), "utf-8");
+    expect(runtimeSource).toContain("function readManduData");
+    expect(runtimeSource).toContain("document.getElementById(\"__MANDU_DATA__\")");
+    expect(runtimeSource).toContain("deserializeManduProps");
+    expect(runtimeSource).toContain("new Date");
+    expect(runtimeSource).toContain("new Map");
+  });
 
   test("does not bundle a server page when stale manifest marks page.tsx as clientModule", async () => {
     const staleRoot = await mkRepoTempDir("stale-client-module-");

package/src/bundler/build.ts

@@ -522,25 +522,103 @@ function generateRuntimeSource(): string {
 import React, { useState, useEffect, Component } from 'react';
 import { hydrateRoot, createRoot } from 'react-dom/client';
 
-// Hydrated roots 추적 (unmount용) - 전역 초기화
-window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
-const hydratedRoots = window.__MANDU_ROOTS__;
-
-// 서버 데이터
-function readManduData() {
-  if (window.__MANDU_DATA__) return window.__MANDU_DATA__;
+// Hydrated roots 추적 (unmount용) - 전역 초기화
+window.__MANDU_ROOTS__ = window.__MANDU_ROOTS__ || new Map();
+const hydratedRoots = window.__MANDU_ROOTS__;
+
+const TYPE_MARKERS = {
+  UNDEFINED: "\\u0000_",
+  DATE: "\\u0000D",
+  URL: "\\u0000U",
+  REGEXP: "\\u0000R",
+  MAP: "\\u0000M",
+  SET: "\\u0000S",
+  REF: "\\u0000$",
+  BIGINT: "\\u0000B",
+  SYMBOL: "\\u0000Y",
+  ERROR: "\\u0000E",
+};
+
+function deserializeManduProps(json) {
+  const ctx = { refs: [] };
+  return deserializeManduValue(JSON.parse(json), ctx);
+}
+
+function deserializeManduValue(value, ctx) {
+  if (value === null) return null;
+  if (typeof value === 'string') {
+    if (value === TYPE_MARKERS.UNDEFINED) return undefined;
+    if (value.startsWith("\\u0000\\u0000")) return value.slice(2);
+    if (value.startsWith(TYPE_MARKERS.DATE)) return new Date(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.URL)) return new URL(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.REGEXP)) {
+      const str = value.slice(2);
+      const match = str.match(/^\\/(.*)\\/([gimsuy]*)$/);
+      return match ? new RegExp(match[1], match[2]) : str;
+    }
+    if (value.startsWith(TYPE_MARKERS.BIGINT)) return BigInt(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.SYMBOL)) return Symbol(value.slice(2));
+    if (value.startsWith(TYPE_MARKERS.REF)) return ctx.refs[parseInt(value.slice(2), 10)];
+    return value;
+  }
+  if (typeof value === 'boolean' || typeof value === 'number') return value;
+  if (Array.isArray(value)) {
+    const marker = value[0];
+    if (marker === TYPE_MARKERS.ERROR) {
+      const error = new Error(value[2]);
+      error.name = value[1];
+      if (value[3]) error.stack = value[3];
+      ctx.refs.push(error);
+      return error;
+    }
+    if (marker === TYPE_MARKERS.MAP) {
+      const map = new Map();
+      ctx.refs.push(map);
+      for (let i = 1; i < value.length; i++) {
+        const entry = value[i];
+        map.set(deserializeManduValue(entry[0], ctx), deserializeManduValue(entry[1], ctx));
+      }
+      return map;
+    }
+    if (marker === TYPE_MARKERS.SET) {
+      const set = new Set();
+      ctx.refs.push(set);
+      for (let i = 1; i < value.length; i++) {
+        set.add(deserializeManduValue(value[i], ctx));
+      }
+      return set;
+    }
+    const arr = [];
+    ctx.refs.push(arr);
+    for (const item of value) arr.push(deserializeManduValue(item, ctx));
+    return arr;
+  }
+  if (typeof value === 'object') {
+    const obj = {};
+    ctx.refs.push(obj);
+    for (const [key, nested] of Object.entries(value)) {
+      obj[key] = deserializeManduValue(nested, ctx);
+    }
+    return obj;
+  }
+  return value;
+}
+
+// 서버 데이터
+function readManduData() {
+  if (window.__MANDU_DATA__) return window.__MANDU_DATA__;
 
   const raw = window.__MANDU_DATA_RAW__ || document.getElementById('__MANDU_DATA__')?.textContent;
   if (!raw) {
     window.__MANDU_DATA__ = {};
     return window.__MANDU_DATA__;
-  }
-
-  try {
-    window.__MANDU_DATA__ = JSON.parse(raw);
-  } catch (error) {
-    console.warn('[Mandu] Failed to parse server data:', error);
-    window.__MANDU_DATA__ = {};
+  }
+
+  try {
+    window.__MANDU_DATA__ = deserializeManduProps(raw);
+  } catch (error) {
+    console.warn('[Mandu] Failed to parse server data:', error);
+    window.__MANDU_DATA__ = {};
   }
 
   return window.__MANDU_DATA__;
@@ -681,26 +759,62 @@ function createHydrationOptions(element, id, mode) {
   };
 }
 
-/**
- * Hydration 스케줄러
- */
-function scheduleHydration(element, src, priority) {
-  switch (priority) {
-    case 'immediate':
-      loadAndHydrate(element, src);
-      break;
+/**
+ * Hydration 스케줄러
+ */
+function priorityToHydrateStrategy(priority) {
+  return priority === 'immediate' ? 'load' : priority;
+}
+
+function scheduleHydration(element, src, strategy) {
+  if (!strategy) strategy = 'load';
+  if (strategy === 'immediate') strategy = 'load';
+
+  if (strategy.startsWith('media(') && strategy.endsWith(')')) {
+    const query = strategy.slice('media('.length, -1).trim();
+    if (!query || !window.matchMedia) {
+      loadAndHydrate(element, src);
+      return;
+    }
+    const mql = window.matchMedia(query);
+    if (mql.matches) {
+      loadAndHydrate(element, src);
+      return;
+    }
+    const onChange = (event) => {
+      if (!event.matches) return;
+      if (mql.removeEventListener) {
+        mql.removeEventListener('change', onChange);
+      } else if (mql.removeListener) {
+        mql.removeListener(onChange);
+      }
+      loadAndHydrate(element, src);
+    };
+    if (mql.addEventListener) {
+      mql.addEventListener('change', onChange);
+    } else if (mql.addListener) {
+      mql.addListener(onChange);
+    }
+    return;
+  }
+
+  switch (strategy) {
+    case 'load':
+    case 'immediate':
+      loadAndHydrate(element, src);
+      break;
 
     case 'visible':
       if ('IntersectionObserver' in window) {
         const observer = new IntersectionObserver((entries) => {
-          if (entries[0].isIntersecting) {
-            observer.disconnect();
-            loadAndHydrate(element, src);
-          }
-        }, { rootMargin: '50px' });
-        const target = resolveHydrationTarget(element);
-        observer.observe(target);
-      } else {
+          if (entries[0].isIntersecting) {
+            observer.disconnect();
+            loadAndHydrate(element, src);
+          }
+        }, { rootMargin: '200px' });
+        const target = resolveHydrationTarget(element);
+        observer.observe(target);
+      } else {
         loadAndHydrate(element, src);
       }
       break;
@@ -712,26 +826,26 @@ function scheduleHydration(element, src, priority) {
         setTimeout(() => loadAndHydrate(element, src), 200);
       }
       break;
-
-    case 'interaction': {
-      const target = resolveHydrationTarget(element);
-      const hydrate = () => {
-        target.removeEventListener('mouseenter', hydrate);
-        target.removeEventListener('focusin', hydrate);
-        target.removeEventListener('touchstart', hydrate);
-        target.removeEventListener('pointerdown', hydrate);
-        target.removeEventListener('keydown', hydrate);
-        loadAndHydrate(element, src);
-      };
-      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;
-    }
-  }
-}
+
+    case 'interaction': {
+      const target = resolveHydrationTarget(element);
+      const hydrate = () => {
+        target.removeEventListener('touchstart', hydrate);
+        target.removeEventListener('click', hydrate);
+        target.removeEventListener('keydown', hydrate);
+        loadAndHydrate(element, src);
+      };
+      target.addEventListener('touchstart', hydrate, { once: true, passive: true });
+      target.addEventListener('click', hydrate, { once: true });
+      target.addEventListener('keydown', hydrate, { once: true });
+      break;
+    }
+
+    default:
+      console.warn('[Mandu] Unknown hydrate strategy "' + strategy + '", falling back to load.');
+      loadAndHydrate(element, src);
+  }
+}
 
 /**
  * Island 로드 및 hydrate (핵심 함수)
@@ -767,12 +881,12 @@ async function loadAndHydrate(element, src) {
       const propsEl = element.hasAttribute('data-props')
         ? element
         : 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);
-        }
+      if (propsEl) {
+        try {
+          data = deserializeManduProps(propsEl.getAttribute('data-props') || '{}');
+        } catch (e) {
+          console.warn('[Mandu] Failed to parse data-props fallback:', e);
+        }
       }
     }
 
@@ -916,12 +1030,13 @@ function hydrateIslands() {
   const seenIds = new Set();
 
   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}';
-
-    if (!id || !src) {
-      console.warn('[Mandu] Island missing id or src:', el);
+    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 hydrateStrategy = el.getAttribute('data-hydrate') || priorityToHydrateStrategy(priority);
+
+    if (!id || !src) {
+      console.warn('[Mandu] Island missing id or src:', el);
       continue;
     }
 
@@ -929,12 +1044,12 @@ function hydrateIslands() {
     if (seenIds.has(id)) {
       console.warn('[Mandu] Duplicate island id detected:', id, '- skipping');
       continue;
-    }
-    seenIds.add(id);
-
-    scheduleHydration(el, src, priority);
-  }
-}
+    }
+    seenIds.add(id);
+
+    scheduleHydration(el, src, hydrateStrategy);
+  }
+}
 
 /**
  * Island unmount
@@ -1168,39 +1283,44 @@ function patternCacheSet(key, value) {
   patternCache.set(key, value);
 }
 
-function compilePattern(pattern) {
-  var cached = patternCacheGet(pattern);
-  if (cached) return cached;
-
-  const paramNames = [];
-  let paramIndex = 0;
-  const paramMatches = [];
-
-  const withPlaceholders = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
-    paramMatches.push(name);
-    return '%%PARAM%%';
-  });
-
-  const escaped = withPlaceholders.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&');
-  const regexStr = escaped.replace(/%%PARAM%%/g, () => {
-    paramNames.push(paramMatches[paramIndex++]);
-    return '([^/]+)';
-  });
-
-  const compiled = { regex: new RegExp('^' + regexStr + '$'), paramNames };
-  patternCacheSet(pattern, compiled);
-  return compiled;
-}
+function compilePattern(pattern) {
+  var cached = patternCacheGet(pattern);
+  if (cached) return cached;
+
+  const paramNames = [];
+  const normalized = pattern === '/' ? '/' : pattern.replace(/\\/+$/, '') || '/';
+  const segments = normalized.split('/').filter(Boolean);
+  const regexStr = segments.length === 0
+    ? '/'
+    : segments.map((segment) => {
+        if (segment === '*') return '/.+';
+        const wildcardMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\\*(\\?)?$/);
+        if (wildcardMatch) {
+          paramNames.push(wildcardMatch[1]);
+          return wildcardMatch[2] === '?' ? '(?:/(.*))?' : '/(.+)';
+        }
+        const paramMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)$/);
+        if (paramMatch) {
+          paramNames.push(paramMatch[1]);
+          return '/([^/]+)';
+        }
+        return '/' + segment.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&');
+      }).join('');
+
+  const compiled = { regex: new RegExp('^' + regexStr + '$'), paramNames };
+  patternCacheSet(pattern, compiled);
+  return compiled;
+}
 
 function extractParams(pattern, pathname) {
   const compiled = compilePattern(pattern);
   const match = pathname.match(compiled.regex);
   if (!match) return {};
-
-  const params = {};
-  compiled.paramNames.forEach((name, i) => { params[name] = match[i + 1]; });
-  return params;
-}
+
+  const params = {};
+  compiled.paramNames.forEach((name, i) => { params[name] = match[i + 1] || ''; });
+  return params;
+}
 
 function notifyListeners() {
   const state = getGlobalState();

package/src/client/router.ts

@@ -165,39 +165,42 @@ const patternCache = new LRUCache<string, CompiledPattern>(LIMITS.ROUTER_PATTERN
 // because `registerCacheSize` replaces any prior reporter under the same key.
 registerCacheSize("patternCache", () => patternCache.size);
 
-/**
- * 패턴을 정규식으로 컴파일
- */
-function compilePattern(pattern: string): CompiledPattern {
-  const cached = patternCache.get(pattern);
-  if (cached) return cached;
-
-  const paramNames: string[] = [];
-  const PARAM_PLACEHOLDER = "\x00PARAM\x00";
-  const paramMatches: string[] = [];
-
-  const withPlaceholders = pattern.replace(
-    /:([a-zA-Z_][a-zA-Z0-9_]*)/g,
-    (_, paramName) => {
-      paramMatches.push(paramName);
-      return PARAM_PLACEHOLDER;
-    }
-  );
-
-  const escaped = withPlaceholders.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
-
-  let paramIndex = 0;
-  const regexStr = escaped.replace(
-    new RegExp(PARAM_PLACEHOLDER.replace(/\x00/g, "\\x00"), "g"),
-    () => {
-      paramNames.push(paramMatches[paramIndex++]);
-      return "([^/]+)";
-    }
-  );
-
-  const compiled = {
-    regex: new RegExp(`^${regexStr}$`),
-    paramNames,
+/**
+ * 패턴을 정규식으로 컴파일
+ */
+function compilePattern(pattern: string): CompiledPattern {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+
+  const paramNames: string[] = [];
+  const normalized = pattern === "/" ? "/" : pattern.replace(/\/+$/, "") || "/";
+  const segments = normalized.split("/").filter(Boolean);
+
+  const regexStr = segments.length === 0
+    ? "/"
+    : segments.map((segment) => {
+        if (segment === "*") {
+          return "/.+";
+        }
+
+        const wildcardMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\*(\?)?$/);
+        if (wildcardMatch) {
+          paramNames.push(wildcardMatch[1]);
+          return wildcardMatch[2] === "?" ? "(?:/(.*))?" : "/(.+)";
+        }
+
+        const paramMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)$/);
+        if (paramMatch) {
+          paramNames.push(paramMatch[1]);
+          return "/([^/]+)";
+        }
+
+        return `/${escapePatternSegment(segment)}`;
+      }).join("");
+
+  const compiled = {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames,
   };
 
   patternCache.set(pattern, compiled);
@@ -216,13 +219,17 @@ function extractParamsFromPath(
 
   if (!match) return {};
 
-  const params: Record<string, string> = {};
-  compiled.paramNames.forEach((name, index) => {
-    params[name] = match[index + 1];
-  });
-
-  return params;
-}
+  const params: Record<string, string> = {};
+  compiled.paramNames.forEach((name, index) => {
+    params[name] = match[index + 1] ?? "";
+  });
+
+  return params;
+}
+
+function escapePatternSegment(segment: string): string {
+  return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 // ========== Navigation ==========
 

package/src/runtime/__tests__/page-render-response.test.ts

@@ -78,6 +78,30 @@ describe("runtime page render response orchestration", () => {
     expect(html).toContain("Stream Page");
   });
 
+  it("emits canonical data-hydrate attributes on streaming island wrappers", async () => {
+    const response = await renderPageResponse({
+      app: React.createElement("main", null, "stream-hydrated-page"),
+      useStreaming: true,
+      title: "Stream Hydrated Page",
+      headTags: "",
+      isDev: false,
+      routeId: "home",
+      routePattern: "/",
+      loaderData: { ok: true },
+      hydration: { strategy: "island", priority: "interaction", preload: false },
+      bundleManifest: HYDRATED_MANIFEST,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html).toContain('data-mandu-island="home"');
+    expect(html).toContain('data-mandu-priority="interaction"');
+    expect(html).toContain('data-hydrate="interaction"');
+  });
+
   it("serializes non-streaming loaderData as the route server data exactly once", async () => {
     const response = await renderPageResponse({
       app: React.createElement("main", null, "hydrated-page"),
@@ -161,4 +185,113 @@ describe("runtime page render response orchestration", () => {
     expect(html).toContain("Public transit");
     expect(html).not.toContain('data-mandu-island="candidates-$id"');
   });
+
+  it("does not invoke sync function components while looking for inline client targets", async () => {
+    function ClientWidget({ label }: { label: string }) {
+      return React.createElement("button", null, label);
+    }
+
+    function HookPage() {
+      const id = React.useId();
+      return React.createElement("main", { id }, React.createElement(ClientWidget, { label: "Click" }));
+    }
+
+    const response = await renderPageResponse({
+      app: React.createElement(HookPage),
+      useStreaming: false,
+      title: "Hook Page",
+      headTags: "",
+      isDev: false,
+      routeId: "hook-page",
+      routePattern: "/hook",
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: {
+        ...HYDRATED_MANIFEST,
+        bundles: {
+          "hook-page": {
+            js: "/.mandu/client/hook-page.island.js",
+            dependencies: ["_runtime", "_react"],
+            priority: "visible",
+          },
+        },
+      },
+      loaderData: undefined,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+      inlineClientHydration: {
+        routeId: "hook-page",
+        src: "/.mandu/client/hook-page.island.js",
+        priority: "visible",
+        component: ClientWidget,
+      },
+    });
+
+    const html = await response.text();
+    expect(html).toContain("Hook Page");
+    expect(html).toContain("Click");
+    expect(html).toContain('data-mandu-island="hook-page"');
+    expect(html).not.toContain('data-mandu-island="hook-page--0"');
+  });
+
+  it("assigns inline client island IDs in document order", async () => {
+    function ClientWidget({ label }: { label: string }) {
+      return React.createElement("button", null, label);
+    }
+
+    async function SlowSection() {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      return React.createElement(ClientWidget, { label: "first" });
+    }
+
+    async function FastSection() {
+      return React.createElement(ClientWidget, { label: "second" });
+    }
+
+    async function OrderedPage() {
+      return [
+        React.createElement(SlowSection, { key: "slow" }),
+        React.createElement(FastSection, { key: "fast" }),
+      ];
+    }
+
+    const response = await renderPageResponse({
+      app: React.createElement(OrderedPage),
+      useStreaming: false,
+      title: "Ordered",
+      headTags: "",
+      isDev: false,
+      routeId: "ordered",
+      routePattern: "/ordered",
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: {
+        ...HYDRATED_MANIFEST,
+        bundles: {
+          ordered: {
+            js: "/.mandu/client/ordered.island.js",
+            dependencies: ["_runtime", "_react"],
+            priority: "visible",
+          },
+        },
+      },
+      loaderData: undefined,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+      inlineClientHydration: {
+        routeId: "ordered",
+        src: "/.mandu/client/ordered.island.js",
+        priority: "visible",
+        component: ClientWidget,
+      },
+    });
+
+    const html = await response.text();
+    expect(html.indexOf('data-mandu-island="ordered--0"')).toBeLessThan(
+      html.indexOf('data-mandu-island="ordered--1"'),
+    );
+    expect(html.indexOf("first")).toBeLessThan(html.indexOf("second"));
+  });
 });

package/src/runtime/page-render-response.ts

@@ -76,13 +76,12 @@ async function resolveAndWrapInlineClientHydration(
 
   if (Array.isArray(node)) {
     let didWrap = false;
-    const children = await Promise.all(
-      node.map(async (child) => {
-        const result = await resolveAndWrapInlineClientHydration(child, target, counter);
-        didWrap = didWrap || result.didWrap;
-        return result.node;
-      }),
-    );
+    const children: React.ReactNode[] = [];
+    for (const child of node) {
+      const result = await resolveAndWrapInlineClientHydration(child, target, counter);
+      didWrap = didWrap || result.didWrap;
+      children.push(result.node);
+    }
     return { node: children, didWrap };
   }
 
@@ -112,7 +111,7 @@ async function resolveAndWrapInlineClientHydration(
     };
   }
 
-  if (typeof type === "function" && !isClassComponent(type)) {
+  if (typeof type === "function" && isAsyncFunctionComponent(type)) {
     const rendered = await (type as (props: Record<string, unknown>) => React.ReactNode | Promise<React.ReactNode>)(
       element.props ?? {},
     );
@@ -136,8 +135,9 @@ async function resolveAndWrapInlineClientHydration(
   return { node: cloned, didWrap: resolvedChildren.didWrap };
 }
 
-function isClassComponent(type: Function): boolean {
-  return !!(type.prototype && type.prototype.isReactComponent);
+function isAsyncFunctionComponent(type: Function): boolean {
+  return !type.prototype?.isReactComponent &&
+    (type as { constructor?: { name?: string } }).constructor?.name === "AsyncFunction";
 }
 
 function priorityToHydrate(priority: InlineClientHydrationTarget["priority"]): string {

package/src/runtime/streaming-ssr.ts

@@ -390,7 +390,7 @@ function generateErrorScript(error: Error, routeId: string): string {
  * Island를 Suspense로 감싸는 래퍼
  * Streaming SSR에서 Island별 점진적 렌더링 지원
  */
-export function SuspenseIsland({
+export function SuspenseIsland({
   children,
   fallback,
   routeId,
@@ -401,14 +401,16 @@ export function SuspenseIsland({
   fallback?: ReactNode;
   routeId: string;
   priority?: HydrationPriority;
-  bundleSrc?: string;
-}): ReactElement {
-  const defaultFallback = React.createElement("div", {
-    "data-mandu-island": routeId,
-    "data-mandu-priority": priority,
-    "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
-    "data-mandu-loading": "true",
-    style: { display: "contents", minHeight: "50px" },
+  bundleSrc?: string;
+}): ReactElement {
+  const hydrate = priorityToHydrateStrategy(priority);
+  const defaultFallback = React.createElement("div", {
+    "data-mandu-island": routeId,
+    "data-mandu-priority": priority,
+    "data-hydrate": hydrate,
+    "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
+    "data-mandu-loading": "true",
+    style: { display: "contents", minHeight: "50px" },
   }, React.createElement("div", {
     className: "mandu-loading-skeleton",
     style: {
@@ -424,14 +426,19 @@ export function SuspenseIsland({
   return React.createElement(
     Suspense,
     { fallback: fallback || defaultFallback },
-    React.createElement("div", {
-      "data-mandu-island": routeId,
-      "data-mandu-priority": priority,
-      "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
-      style: { display: "contents" },
-    }, children)
-  );
-}
+    React.createElement("div", {
+      "data-mandu-island": routeId,
+      "data-mandu-priority": priority,
+      "data-hydrate": hydrate,
+      "data-mandu-src": bundleSrc ? `${bundleSrc}${bundleSrc.includes('?') ? '&' : '?'}t=${Date.now()}` : bundleSrc,
+      style: { display: "contents" },
+    }, children)
+  );
+}
+
+function priorityToHydrateStrategy(priority: HydrationPriority): string {
+  return priority === "immediate" ? "load" : priority;
+}
 
 /**
  * Deferred 데이터를 위한 Suspense 컴포넌트
@@ -619,8 +626,9 @@ function generateHTMLShell(options: StreamingSSROptions): string {
     const bundle = bundleManifest.bundles[routeId];
     const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
     const priority = hydration.priority || "visible";
+    const hydrate = priorityToHydrateStrategy(priority);
     if (hasRouteBundle) {
-      islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
+      islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" data-hydrate="${escapeHtmlAttr(hydrate)}" style="display:contents">`;
     }
   }