@mandujs/core 0.54.13 → 0.54.14

package/package.json

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

package/src/bundler/__tests__/build-runner.ts

@@ -100,11 +100,11 @@ const manifest: RoutesManifest = mode === "server-page-client-module"
           },
         ],
       }
-  : mode === "hydration-no-client-module"
-    ? {
-        version: 1,
-        routes: [
-          {
+  : mode === "hydration-no-client-module"
+    ? {
+        version: 1,
+        routes: [
+          {
             id: "login",
             kind: "page",
             pattern: "/login",
@@ -115,13 +115,32 @@ const manifest: RoutesManifest = mode === "server-page-client-module"
               priority: "immediate",
               preload: false,
             },
-          },
-        ],
-      }
-    : {
-        version: 1,
-        routes: [
-          {
+          },
+        ],
+      }
+  : mode === "i18n-locale-route-id"
+    ? {
+        version: 1,
+        routes: [
+          {
+            id: "ko::demo",
+            kind: "page",
+            pattern: "/ko",
+            module: "app/page.tsx",
+            componentModule: "app/page.tsx",
+            clientModule: "app/demo.client.tsx",
+            hydration: {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            },
+          },
+        ],
+      }
+    : {
+        version: 1,
+        routes: [
+          {
             id: "demo",
             kind: "page",
             pattern: "/",

package/src/bundler/__tests__/fast-refresh.test.ts

@@ -19,9 +19,9 @@
  *   packages/core/src/runtime/fast-refresh-runtime.ts
  */
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, mkdir, rm, writeFile, readFile } from "fs/promises";
-import path from "path";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, writeFile, readFile } from "fs/promises";
+import path from "path";
 
 import {
   appendBoundary,
@@ -40,12 +40,19 @@ import {
   _isRefreshScheduledForTests,
   type ReactRefreshRuntime,
 } from "../../runtime/fast-refresh-runtime";
-import {
-  createManduHot,
-  dispatchReplacement,
-  _resetRegistryForTests,
-} from "../../runtime/hmr-client";
-import { generateFastRefreshPreamble } from "../dev";
+import {
+  createManduHot,
+  dispatchReplacement,
+  _resetRegistryForTests,
+} from "../../runtime/hmr-client";
+import { generateFastRefreshPreamble } from "../dev";
+
+const repoTempRoot = path.resolve(import.meta.dir, "../../../../..", ".tmp-test-artifacts");
+
+async function mkRepoTempDir(prefix: string): Promise<string> {
+  await mkdir(repoTempRoot, { recursive: true });
+  return mkdtemp(path.join(repoTempRoot, prefix));
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // Section A — plugin pure unit tests
@@ -263,10 +270,10 @@ describe("manduHMR — __MANDU_HMR__ global behavior", () => {
 describe.skipIf(process.env.MANDU_SKIP_BUNDLER_TESTS === "1")(
   "Bun.build({ reactFastRefresh: true }) + fastRefreshPlugin()",
   () => {
-    let rootDir: string;
-
-    beforeAll(async () => {
-      rootDir = await mkdtemp(path.join(import.meta.dir, ".tmp-fr-build-"));
+    let rootDir: string;
+
+    beforeAll(async () => {
+      rootDir = await mkRepoTempDir("fr-build-");
       // Three source files — one boundary, one plain, one .island.tsx —
       // give us the minimal matrix for the plugin's include filter.
       await writeFile(
@@ -512,10 +519,10 @@ describe("dispatchReplacement + __MANDU_HMR__ integration", () => {
 describe.skipIf(process.env.MANDU_SKIP_BUNDLER_TESTS === "1")(
   "buildVendorShims emits fast-refresh shims in dev mode",
   () => {
-    let rootDir: string;
-
-    beforeAll(async () => {
-      rootDir = await mkdtemp(path.join(import.meta.dir, ".tmp-fr-vendor-"));
+    let rootDir: string;
+
+    beforeAll(async () => {
+      rootDir = await mkRepoTempDir("fr-vendor-");
       await mkdir(path.join(rootDir, "app"), { recursive: true });
       await writeFile(
         path.join(rootDir, "package.json"),

package/src/bundler/build.test.ts

@@ -1,11 +1,17 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { mkdtemp, mkdir, readFile, rm, writeFile } from "fs/promises";
-import path from "path";
-import { pathToFileURL } from "url";
-
-// 모든 테스트가 하나의 빌드 결과를 공유 — 병렬 Bun.build 충돌 방지
-let rootDir: string;
-let result: { success: boolean; errors: string[] };
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+
+// 모든 테스트가 하나의 빌드 결과를 공유 — 병렬 Bun.build 충돌 방지
+let rootDir: string;
+let result: { success: boolean; errors: string[] };
+const repoTempRoot = path.resolve(import.meta.dir, "../../../..", ".tmp-test-artifacts");
+
+async function mkRepoTempDir(prefix: string): Promise<string> {
+  await mkdir(repoTempRoot, { recursive: true });
+  return mkdtemp(path.join(repoTempRoot, prefix));
+}
 
 async function importBuiltModule(relativePath: string): Promise<Record<string, unknown>> {
   const fileUrl = pathToFileURL(path.join(rootDir, relativePath)).href;
@@ -24,10 +30,13 @@ async function importBuiltModule(relativePath: string): Promise<Record<string, u
  * See `__tests__/build-runner.ts` for the subprocess entrypoint and more
  * background.
  */
-async function runBuildInSubprocess(root: string, mode?: string): Promise<{
-  success: boolean;
-  errors: string[];
-}> {
+async function runBuildInSubprocess(root: string, mode?: string): Promise<{
+  success: boolean;
+  errors: string[];
+  manifest?: {
+    bundles?: Record<string, { js?: string }>;
+  } | null;
+}> {
   const runner = path.join(
     import.meta.dir,
     "__tests__",
@@ -52,25 +61,27 @@ async function runBuildInSubprocess(root: string, mode?: string): Promise<{
     const last = lines[lines.length - 1] ?? "";
     try {
       const parsed = JSON.parse(last);
-      return {
-        success: parsed.success === true,
-        errors: Array.isArray(parsed.errors) ? parsed.errors : [],
-      };
+      return {
+        success: parsed.success === true,
+        errors: Array.isArray(parsed.errors) ? parsed.errors : [],
+        manifest: parsed.manifest ?? null,
+      };
     } catch (e) {
-      return {
-        success: false,
-        errors: [
-          `build-runner output could not be parsed as JSON: ${String(e)}\nLast stdout line: ${last}`,
-        ],
-      };
-    }
-  } catch (err) {
-    return { success: false, errors: [`spawn failed: ${String(err)}`] };
-  }
-}
+      return {
+        success: false,
+        errors: [
+          `build-runner output could not be parsed as JSON: ${String(e)}\nLast stdout line: ${last}`,
+        ],
+        manifest: null,
+      };
+    }
+  } catch (err) {
+    return { success: false, errors: [`spawn failed: ${String(err)}`], manifest: null };
+  }
+}
 
-beforeAll(async () => {
-  rootDir = await mkdtemp(path.join(import.meta.dir, ".tmp-bundler-"));
+beforeAll(async () => {
+  rootDir = await mkRepoTempDir("bundler-");
 
   await mkdir(path.join(rootDir, "app"), { recursive: true });
   await writeFile(
@@ -186,8 +197,8 @@ describe("buildClientBundles vendor shims", () => {
     expect(runtimeSource).toContain("JSON.parse");
   });
 
-  test("does not bundle a server page when stale manifest marks page.tsx as clientModule", async () => {
-    const staleRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-stale-client-module-"));
+  test("does not bundle a server page when stale manifest marks page.tsx as clientModule", async () => {
+    const staleRoot = await mkRepoTempDir("stale-client-module-");
     try {
       await mkdir(path.join(staleRoot, "app"), { recursive: true });
       await mkdir(path.join(staleRoot, "src", "shared", "contracts"), { recursive: true });
@@ -220,7 +231,7 @@ describe("buildClientBundles vendor shims", () => {
   });
 
   test("rewrites route-component clientModule to the real client import before bundling", async () => {
-    const routeClientRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-route-client-import-"));
+    const routeClientRoot = await mkRepoTempDir("route-client-import-");
     try {
       await mkdir(path.join(routeClientRoot, "app", "login"), { recursive: true });
       await mkdir(path.join(routeClientRoot, "src", "client", "pages", "login"), { recursive: true });
@@ -267,7 +278,7 @@ describe("buildClientBundles vendor shims", () => {
   });
 
   test("bundles route-level named client exports without requiring a default export", async () => {
-    const routeClientRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-route-named-client-import-"));
+    const routeClientRoot = await mkRepoTempDir("route-named-client-import-");
     try {
       await mkdir(path.join(routeClientRoot, "app", "login"), { recursive: true });
       await mkdir(path.join(routeClientRoot, "src", "client", "pages", "login"), { recursive: true });
@@ -317,8 +328,34 @@ describe("buildClientBundles vendor shims", () => {
     }
   });
 
+  test("uses Windows-safe asset filenames for locale-prefixed route ids", async () => {
+    const localeRoot = await mkRepoTempDir("i18n-locale-route-id-");
+    try {
+      await mkdir(path.join(localeRoot, "app"), { recursive: true });
+      await writeFile(
+        path.join(localeRoot, "package.json"),
+        JSON.stringify({ name: "mandu-i18n-route-id-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(localeRoot, "app", "demo.client.tsx"),
+        "export default function DemoIsland() { return null; }\n",
+        "utf-8",
+      );
+
+      const localeResult = await runBuildInSubprocess(localeRoot, "i18n-locale-route-id");
+      expect(localeResult.success).toBe(true);
+      const bundle = localeResult.manifest?.bundles?.["ko::demo"];
+      expect(bundle?.js).toBe("/.mandu/client/ko_3a__3a_demo.island.js");
+      expect(bundle?.js).not.toContain(":");
+      expect(await Bun.file(path.join(localeRoot, ".mandu", "client", "ko_3a__3a_demo.island.js")).exists()).toBe(true);
+    } finally {
+      await rm(localeRoot, { recursive: true, force: true });
+    }
+  });
+
   test("fails when hydration is enabled but no clientModule can be resolved", async () => {
-    const missingRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-hydration-no-client-"));
+    const missingRoot = await mkRepoTempDir("hydration-no-client-");
     try {
       await mkdir(path.join(missingRoot, "app", "login"), { recursive: true });
       await mkdir(path.join(missingRoot, "src", "client", "widgets", "login-form"), { recursive: true });

package/src/bundler/build.ts

@@ -1929,25 +1929,34 @@ async function buildVendorShims(
   };
 }
 
-function vendorShimFailureHint(shimName: string): string {
-  if (shimName.includes("react-refresh")) {
-    return "Hint: install the optional dev peer dependency with `bun add -d react-refresh`.";
-  }
-  return "Hint: check the import paths and ensure the vendor package is installed.";
-}
-
-/**
- * 단일 Island 번들 빌드
- */
+function vendorShimFailureHint(shimName: string): string {
+  if (shimName.includes("react-refresh")) {
+    return "Hint: install the optional dev peer dependency with `bun add -d react-refresh`.";
+  }
+  return "Hint: check the import paths and ensure the vendor package is installed.";
+}
+
+function routeIdToAssetStem(routeId: string): string {
+  const safe = routeId.replace(/[<>:"/\\|?*\x00-\x1F]/g, (ch) =>
+    `_${ch.codePointAt(0)!.toString(16)}_`
+  );
+  return safe.replace(/[. ]+$/g, "") || "route";
+}
+
+/**
+ * 단일 Island 번들 빌드
+ */
 async function buildIsland(
   route: RouteSpec,
   rootDir: string,
   outDir: string,
   options: BundlerOptions
-): Promise<BundleOutput> {
-  const clientModulePath = path.join(rootDir, route.clientModule!);
-  const entryPath = path.join(outDir, `_entry_${route.id}.js`);
-  const outputName = `${route.id}.island.js`;
+): Promise<BundleOutput> {
+  const clientModulePath = path.join(rootDir, route.clientModule!);
+  const assetStem = routeIdToAssetStem(route.id);
+  const entryStem = `_entry_${assetStem}`;
+  const entryPath = path.join(outDir, `${entryStem}.js`);
+  const outputName = `${assetStem}.island.js`;
 
   // Phase 7.1 B-1/B-4: wire native Fast Refresh transform + Mandu's
   // boundary injection plugin. Dev-only; prod bundles remain clean.
@@ -1988,11 +1997,11 @@ async function buildIsland(
     let actualOutputPath: string;
     let actualOutputName: string;
 
-    if (options.splitting && result.outputs.length > 0) {
-      // splitting 모드: 결과에서 엔트리 파일 찾기
-      const entryOutput = result.outputs.find(
-        (o) => o.kind === "entry-point" || o.path.includes(route.id)
-      );
+    if (options.splitting && result.outputs.length > 0) {
+      // splitting 모드: 결과에서 엔트리 파일 찾기
+      const entryOutput = result.outputs.find(
+        (o) => o.kind === "entry-point" || o.path.includes(entryStem) || o.path.includes(assetStem)
+      );
       if (entryOutput) {
         actualOutputPath = entryOutput.path;
         actualOutputName = path.basename(entryOutput.path);

package/src/router/client-entry.test.ts

@@ -1,14 +1,21 @@
-import { describe, expect, it } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
-import path from "path";
+import { describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
+import path from "path";
 import {
   findClientComponentImports,
   findRouteLevelClientComponentImport,
   findRouteLevelClientComponentImports,
   resolveRouteLevelClientEntryPath,
-} from "./client-entry";
-
-describe("findClientComponentImports", () => {
+} from "./client-entry";
+
+const repoTempRoot = path.resolve(import.meta.dir, "../../../..", ".tmp-test-artifacts");
+
+async function mkRepoTempDir(prefix: string): Promise<string> {
+  await mkdir(repoTempRoot, { recursive: true });
+  return mkdtemp(path.join(repoTempRoot, prefix));
+}
+
+describe("findClientComponentImports", () => {
   it("detects named .client imports for diagnostics", () => {
     const imports = findClientComponentImports(`
       import { LoginForm, SubmitButton as Button } from "@/client/widgets/login-form/LoginForm.client";
@@ -192,8 +199,8 @@ describe("findClientComponentImports", () => {
     expect(routeClient).toBeNull();
   });
 
-  it("resolves a route-level client entry by reading a use client target without .client in the path", async () => {
-    const rootDir = await mkdtemp(path.join(import.meta.dir, ".tmp-client-entry-"));
+  it("resolves a route-level client entry by reading a use client target without .client in the path", async () => {
+    const rootDir = await mkRepoTempDir("client-entry-");
     try {
       await mkdir(path.join(rootDir, "app", "pledges", "new"), { recursive: true });
       await mkdir(path.join(rootDir, "src", "client", "widgets", "pledge-form"), { recursive: true });

package/src/router/client-entry.ts

@@ -216,21 +216,28 @@ export async function resolveRouteLevelClientEntry(
   return null;
 }
 
-export async function shouldPreserveExistingClientModule(
-  route: RouteSpec,
-  clientModule: string,
-  rootDir: string,
-): Promise<boolean> {
-  if (!isRouteLevelClientEntrySpecifier(clientModule)) return false;
-  const source = await readRouteModule(rootDir, clientModule);
-  if (source === null) return false;
-  if (hasUseServerDirective(source)) return false;
-  if (clientModuleIsRouteComponent(route, clientModule)) {
-    if (hasUseClientDirective(source)) return true;
-    return await routeComponentHasResolvableClientEntry(rootDir, clientModule, source);
-  }
-  return true;
-}
+export async function shouldPreserveExistingClientModule(
+  route: RouteSpec,
+  clientModule: string,
+  rootDir: string,
+): Promise<boolean> {
+  if (!isRouteLevelClientEntrySpecifier(clientModule)) return false;
+  const source = await readRouteModule(rootDir, clientModule);
+  if (source === null) return false;
+  if (hasUseServerDirective(source)) return false;
+  if (clientModuleIsRouteComponent(route, clientModule)) {
+    if (hasUseClientDirective(source)) return true;
+    return await routeComponentHasResolvableClientEntry(rootDir, clientModule, source);
+  }
+
+  if (route.kind !== "page" || !route.componentModule) return false;
+
+  const routeSource = await readRouteModule(rootDir, route.componentModule);
+  if (routeSource === null) return false;
+
+  const currentEntry = await resolveRouteLevelClientEntry(rootDir, route.componentModule, routeSource);
+  return normalizeRouteModulePath(currentEntry?.modulePath) === normalizeRouteModulePath(clientModule);
+}
 
 function resolveImportBasePath(rootDir: string, importerModule: string, specifier: string): string | null {
   const normalized = specifier.replace(/\\/g, "/");

package/src/router/fs-routes.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
+import path from "path";
+import { generateManifest } from "./fs-routes";
+
+const repoTempRoot = path.resolve(import.meta.dir, "../../../..", ".tmp-test-artifacts");
+
+async function mkRepoTempDir(prefix: string): Promise<string> {
+  await mkdir(repoTempRoot, { recursive: true });
+  return mkdtemp(path.join(repoTempRoot, prefix));
+}
+
+describe("generateManifest hydration config", () => {
+  it("does not preserve stale island hydration after the client entry disappears", async () => {
+    const rootDir = await mkRepoTempDir("routes-hydration-stale-");
+    try {
+      await mkdir(path.join(rootDir, "app", "candidates", "[id]"), { recursive: true });
+      await mkdir(path.join(rootDir, "src", "client", "widgets"), { recursive: true });
+      await writeFile(
+        path.join(rootDir, "app", "candidates", "[id]", "page.tsx"),
+        `
+          import { PledgeAccordion } from "@/client/widgets/PledgeAccordion.client";
+          export default function Page() {
+            return <main><PledgeAccordion pledges={[]} /></main>;
+          }
+        `,
+        "utf-8",
+      );
+      await writeFile(
+        path.join(rootDir, "src", "client", "widgets", "PledgeAccordion.client.tsx"),
+        `
+          "use client";
+          export function PledgeAccordion() {
+            return <div />;
+          }
+        `,
+        "utf-8",
+      );
+
+      const first = await generateManifest(rootDir);
+      const firstRoute = first.manifest.routes.find((route) => route.id === "candidates-$id");
+      expect(firstRoute?.clientModule).toContain("PledgeAccordion.client.tsx");
+      expect(firstRoute?.hydration?.strategy).toBe("island");
+
+      await writeFile(
+        path.join(rootDir, "app", "candidates", "[id]", "page.tsx"),
+        `
+          export default function Page() {
+            return <main><details><summary>server only</summary></details></main>;
+          }
+        `,
+        "utf-8",
+      );
+
+      const second = await generateManifest(rootDir);
+      const secondRoute = second.manifest.routes.find((route) => route.id === "candidates-$id");
+      expect(secondRoute?.clientModule).toBeUndefined();
+      expect(secondRoute?.hydration?.strategy).not.toBe("island");
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  it("reads page-level hydration exports from the current page source", async () => {
+    const rootDir = await mkRepoTempDir("routes-hydration-export-");
+    try {
+      await mkdir(path.join(rootDir, "app", "about"), { recursive: true });
+      await writeFile(
+        path.join(rootDir, "app", "about", "page.tsx"),
+        `
+          export const hydration = { strategy: "none", priority: "idle", preload: true };
+          export default function Page() {
+            return <main>About</main>;
+          }
+        `,
+        "utf-8",
+      );
+
+      const result = await generateManifest(rootDir);
+      const route = result.manifest.routes.find((entry) => entry.id === "about");
+      expect(route?.hydration).toEqual({
+        strategy: "none",
+        priority: "idle",
+        preload: true,
+      });
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/router/fs-routes.ts

@@ -94,10 +94,12 @@ export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
             hydration: fsRoute.hydration ?? {
               strategy: "island" as const,
               priority: "immediate" as const,
-              preload: false,
-            },
-          }
-        : {}),
+              preload: false,
+            },
+          }
+        : fsRoute.hydration
+          ? { hydration: fsRoute.hydration }
+          : {}),
       ...(fsRoute.layoutChain && fsRoute.layoutChain.length > 0
         ? { layoutChain: fsRoute.layoutChain.map(normalizePath) }
         : {}),
@@ -322,9 +324,13 @@ export async function generateManifest(
           route.clientModule = prev.clientModule;
           route.clientExportName = prev.clientExportName;
         }
-        if (prev.hydration && !route.hydration) {
-          route.hydration = prev.hydration;
-        }
+        if (prev.hydration && !route.hydration) {
+          const canPreserveHydration =
+            !!route.clientModule || prev.hydration.strategy === "none";
+          if (canPreserveHydration) {
+            route.hydration = prev.hydration;
+          }
+        }
         // Issue #214 — preserve prerender-time fields (`dynamicParams`,
         // `staticParams`) across manifest rescans. `mandu build`'s prerender
         // phase stamps these onto the manifest; a subsequent `mandu dev`

package/src/router/fs-scanner.ts

@@ -28,16 +28,55 @@ import {
   sortRoutesByPriority,
   getPatternShape,
 } from "./fs-patterns";
-import { mark, measure } from "../perf";
-import { METADATA_ROUTES } from "../routes/types";
+import { mark, measure } from "../perf";
+import { METADATA_ROUTES } from "../routes/types";
+import type { HydrationConfig } from "../spec/schema";
 import {
   hasUseClientDirective,
   resolveRouteLevelClientEntry,
 } from "./client-entry";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Scanner Class
-// ═══════════════════════════════════════════════════════════════════════════
+
+const HYDRATION_STRATEGIES = new Set(["none", "island", "full", "progressive"]);
+const HYDRATION_PRIORITIES = new Set(["immediate", "visible", "idle", "interaction"]);
+
+function parsePageHydrationConfig(source: string): HydrationConfig | undefined {
+  const stringMatch = source.match(
+    /export\s+const\s+hydration\s*(?::[^=]+)?=\s*["'](none|island|full|progressive)["']/m,
+  );
+  if (stringMatch?.[1]) {
+    return {
+      strategy: stringMatch[1] as HydrationConfig["strategy"],
+      priority: "visible",
+      preload: false,
+    };
+  }
+
+  const objectMatch = source.match(
+    /export\s+const\s+hydration\s*(?::[^=]+)?=\s*\{([\s\S]*?)\}\s*;?/m,
+  );
+  const body = objectMatch?.[1];
+  if (!body) return undefined;
+
+  const strategyMatch = body.match(/\bstrategy\s*:\s*["']([^"']+)["']/);
+  const strategy = strategyMatch?.[1];
+  if (!strategy || !HYDRATION_STRATEGIES.has(strategy)) return undefined;
+
+  const priorityMatch = body.match(/\bpriority\s*:\s*["']([^"']+)["']/);
+  const priority = priorityMatch?.[1];
+  const preloadMatch = body.match(/\bpreload\s*:\s*(true|false)\b/);
+
+  return {
+    strategy: strategy as HydrationConfig["strategy"],
+    priority: HYDRATION_PRIORITIES.has(priority ?? "")
+      ? (priority as HydrationConfig["priority"])
+      : "visible",
+    preload: preloadMatch?.[1] === "true",
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scanner Class
+// ═══════════════════════════════════════════════════════════════════════════
 
 /**
  * FS Routes 스캐너
@@ -367,15 +406,19 @@ export class FSScanner {
       // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
       let clientModule: string | undefined;
       let clientExportName: string | undefined;
+      let hydration: HydrationConfig | undefined;
       let pageFileContent: string | null = null;
-
-      if (file.type === "page") {
-        try {
-          pageFileContent = await Bun.file(file.absolutePath).text();
-        } catch {
-          pageFileContent = null;
-        }
-      }
+
+      if (file.type === "page") {
+        try {
+          pageFileContent = await Bun.file(file.absolutePath).text();
+        } catch {
+          pageFileContent = null;
+        }
+        if (pageFileContent) {
+          hydration = parsePageHydrationConfig(pageFileContent);
+        }
+      }
 
       if (islands?.[0]) {
         // 우선순위: 명시적 island 파일
@@ -422,9 +465,10 @@ export class FSScanner {
         componentModule: file.type === "page" ? modulePath : undefined,
         clientModule,
         clientExportName,
+        hydration,
         layoutChain,
-        loadingModule,
-        errorModule,
+        loadingModule,
+        errorModule,
         notFoundModule,
         sourceFile: file.absolutePath,
       };

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

@@ -100,4 +100,65 @@ describe("runtime page render response orchestration", () => {
     expect(html).toContain('"home":{"serverData":{"items":["a","b"]}');
     expect(html).not.toContain('"serverData":{"home"');
   });
+
+  it("serializes props for inline client components rendered by async server pages", async () => {
+    function PledgeAccordion({ pledges }: { pledges: Array<{ id: string; title: string }> }) {
+      return React.createElement(
+        "ul",
+        null,
+        pledges.map((pledge) => React.createElement("li", { key: pledge.id }, pledge.title)),
+      );
+    }
+
+    async function CandidatePage() {
+      const pledges = [
+        { id: "p1", title: "Public transit" },
+        { id: "p2", title: "Housing" },
+      ];
+      return React.createElement(
+        "main",
+        null,
+        React.createElement(PledgeAccordion, { pledges }),
+      );
+    }
+
+    const response = await renderPageResponse({
+      app: React.createElement(CandidatePage),
+      useStreaming: false,
+      title: "Candidate",
+      headTags: "",
+      isDev: false,
+      routeId: "candidates-$id",
+      routePattern: "/candidates/:id",
+      hydration: { strategy: "island", priority: "immediate", preload: false },
+      bundleManifest: {
+        ...HYDRATED_MANIFEST,
+        bundles: {
+          "candidates-$id": {
+            js: "/.mandu/client/candidates-$id.island.js",
+            dependencies: ["_runtime", "_react"],
+            priority: "immediate",
+          },
+        },
+      },
+      loaderData: undefined,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+      inlineClientHydration: {
+        routeId: "candidates-$id",
+        src: "/.mandu/client/candidates-$id.island.js",
+        priority: "immediate",
+        component: PledgeAccordion,
+      },
+    });
+
+    const html = await response.text();
+    expect(html).toContain('data-mandu-island="candidates-$id--0"');
+    expect(html).toContain('data-mandu-src="/.mandu/client/candidates-$id.island.js"');
+    expect(html).toContain("&quot;pledges&quot;");
+    expect(html).toContain("Public transit");
+    expect(html).not.toContain('data-mandu-island="candidates-$id"');
+  });
 });

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

@@ -1,8 +1,16 @@
-import type React from "react";
+import React from "react";
 import type { BundleManifest } from "../bundler/types";
 import type { HydrationConfig } from "../spec/schema";
 import type { CookieManager } from "../filling/context";
 import { renderSSR, renderStreamingResponse, resolveAsyncElement } from "./ssr";
+import { serializeProps } from "../client/serialize";
+
+export interface InlineClientHydrationTarget {
+  routeId: string;
+  src: string;
+  priority: NonNullable<HydrationConfig["priority"]>;
+  component: unknown;
+}
 
 export interface PageRenderResponseOptions {
   app: React.ReactElement;
@@ -23,6 +31,7 @@ export interface PageRenderResponseOptions {
   spa?: boolean;
   devtools?: boolean;
   islandPreWrapped?: boolean;
+  inlineClientHydration?: InlineClientHydrationTarget;
   cookies?: CookieManager;
 }
 
@@ -30,18 +39,111 @@ export async function renderPageResponse(
   options: PageRenderResponseOptions
 ): Promise<Response> {
   let app = options.app;
+  let islandPreWrapped = !!options.islandPreWrapped;
 
   if (!options.useStreaming) {
-    app = (await resolveAsyncElement(app)) as React.ReactElement;
+    if (options.inlineClientHydration) {
+      const resolved = await resolveAndWrapInlineClientHydration(
+        app,
+        options.inlineClientHydration,
+      );
+      app = resolved.node as React.ReactElement;
+      islandPreWrapped = islandPreWrapped || resolved.didWrap;
+    } else {
+      app = (await resolveAsyncElement(app)) as React.ReactElement;
+    }
   }
 
+  const effectiveOptions = islandPreWrapped === !!options.islandPreWrapped
+    ? options
+    : { ...options, islandPreWrapped };
+
   const response = options.useStreaming
-    ? await renderStreamingPageResponse(app, options)
-    : renderNonStreamingPageResponse(app, options);
+    ? await renderStreamingPageResponse(app, effectiveOptions)
+    : renderNonStreamingPageResponse(app, effectiveOptions);
 
   return options.cookies ? options.cookies.applyToResponse(response) : response;
 }
 
+async function resolveAndWrapInlineClientHydration(
+  node: React.ReactNode,
+  target: InlineClientHydrationTarget,
+  counter = { value: 0 },
+): Promise<{ node: React.ReactNode; didWrap: boolean }> {
+  if (node == null || typeof node !== "object") {
+    return { node, didWrap: false };
+  }
+
+  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;
+      }),
+    );
+    return { node: children, didWrap };
+  }
+
+  if (!React.isValidElement(node)) {
+    return { node, didWrap: false };
+  }
+
+  const element = node as React.ReactElement<Record<string, unknown>>;
+  const type = element.type;
+
+  if (type === target.component) {
+    const id = `${target.routeId}--${counter.value++}`;
+    return {
+      node: React.createElement(
+        "div",
+        {
+          "data-mandu-island": id,
+          "data-mandu-src": target.src,
+          "data-mandu-priority": target.priority,
+          "data-hydrate": priorityToHydrate(target.priority),
+          "data-props": serializeProps(element.props ?? {}),
+          style: { display: "contents" },
+        },
+        element,
+      ),
+      didWrap: true,
+    };
+  }
+
+  if (typeof type === "function" && !isClassComponent(type)) {
+    const rendered = await (type as (props: Record<string, unknown>) => React.ReactNode | Promise<React.ReactNode>)(
+      element.props ?? {},
+    );
+    return resolveAndWrapInlineClientHydration(rendered, target, counter);
+  }
+
+  const props = element.props;
+  const rawChildren = props?.children as React.ReactNode | undefined;
+  if (rawChildren === undefined) {
+    return { node: element, didWrap: false };
+  }
+
+  const resolvedChildren = await resolveAndWrapInlineClientHydration(rawChildren, target, counter);
+  if (!resolvedChildren.didWrap && resolvedChildren.node === rawChildren) {
+    return { node: element, didWrap: false };
+  }
+
+  const cloned = Array.isArray(resolvedChildren.node)
+    ? React.cloneElement(element, undefined, ...resolvedChildren.node)
+    : React.cloneElement(element, undefined, resolvedChildren.node);
+  return { node: cloned, didWrap: resolvedChildren.didWrap };
+}
+
+function isClassComponent(type: Function): boolean {
+  return !!(type.prototype && type.prototype.isReactComponent);
+}
+
+function priorityToHydrate(priority: InlineClientHydrationTarget["priority"]): string {
+  return priority === "immediate" ? "load" : priority;
+}
+
 async function renderStreamingPageResponse(
   app: React.ReactElement,
   options: PageRenderResponseOptions

package/src/runtime/router.test.ts

@@ -157,10 +157,10 @@ describe("Wildcard Matching", () => {
 
     const result = router.match("/docs");
 
-    expect(result).not.toBeNull();
-    expect(result!.route.id).toBe("docs");
-    expect(result!.params).toEqual({});
-  });
+    expect(result).not.toBeNull();
+    expect(result!.route.id).toBe("docs");
+    expect(result!.params).toEqual({ path: "" });
+  });
 
   test("optional wildcard matches with remaining path", () => {
     const router = createRouter([

package/src/runtime/router.ts

@@ -415,12 +415,10 @@ export class Router {
             route,
           };
 
-          // Optional wildcard: 현재 노드도 매칭 가능하게 route 설정
-          if (isOptional && !node.route) {
-            node.route = route;
-          }
-          return;
-        }
+          // Optional wildcard base paths are matched from wildcardConfig so
+          // the named wildcard param is still materialized as an empty string.
+          return;
+        }
 
         // Regular parameter: :param
         const paramName = seg.slice(1);
@@ -528,12 +526,12 @@ export class Router {
       if (node.wildcardConfig.optional) {
         if (this.debug) {
           console.log(`[Router] Optional wildcard match: ${node.wildcardConfig.route.id} with empty path`);
-        }
-        return {
-          route: node.wildcardConfig.route,
-          params,
-        };
-      }
+        }
+        return {
+          route: node.wildcardConfig.route,
+          params: { ...params, [node.wildcardConfig.name]: "" },
+        };
+      }
       // Non-optional wildcard: /files/:path* does NOT match /files
       if (this.debug) {
         console.log(`[Router] Wildcard policy: ${pathname} does not match non-optional wildcard`);

package/src/runtime/server.ts

@@ -93,7 +93,7 @@ import {
 } from "./static-files";
 export { __clearStaticEtagCacheForTests } from "./static-files";
 import { extractShellHtml, createPPRResponse } from "./ppr";
-import { renderPageResponse } from "./page-render-response";
+import { renderPageResponse, type InlineClientHydrationTarget } from "./page-render-response";
 import { isRedirectResponse } from "./redirect";
 import { isNotFoundResponse } from "./not-found";
 import { newId } from "../id";
@@ -479,8 +479,12 @@ export type ErrorLoader = () => Promise<{ default: ErrorComponent }>;
  * - component: React 컴포넌트
  * - filling: Slot의 ManduFilling 인스턴스 (loader 포함)
  */
-export interface PageRegistration {
-  component: React.ComponentType<{ params: Record<string, string>; loaderData?: unknown }>;
+export interface PageRegistration {
+  component: React.ComponentType<{
+    params: Record<string, string>;
+    loaderData?: unknown;
+    __manduHydration?: InlineClientHydrationTarget;
+  }>;
   filling?: ManduFilling<unknown>;
   /** #186: page 모듈의 static `metadata` export (선택) */
   metadata?: Metadata;
@@ -502,15 +506,20 @@ export type PageHandler = () => Promise<PageRegistration>;
  */
 export type MetadataHandler = () => Promise<unknown>;
 
-export interface AppContext {
-  routeId: string;
-  url: string;
-  params: Record<string, string>;
-  /** SSR loader에서 로드한 데이터 */
-  loaderData?: unknown;
-}
-
-type RouteComponent = (props: { params: Record<string, string>; loaderData?: unknown }) => React.ReactElement;
+export interface AppContext {
+  routeId: string;
+  url: string;
+  params: Record<string, string>;
+  /** SSR loader에서 로드한 데이터 */
+  loaderData?: unknown;
+  __manduHydration?: InlineClientHydrationTarget;
+}
+
+type RouteComponent = (props: {
+  params: Record<string, string>;
+  loaderData?: unknown;
+  __manduHydration?: InlineClientHydrationTarget;
+}) => React.ReactElement;
 type CreateAppFn = (context: AppContext) => React.ReactElement;
 
 // ========== Server Registry (인스턴스별 분리) ==========
@@ -1086,8 +1095,8 @@ async function wrapWithLayouts(
 }
 
 // Default createApp implementation (registry 기반)
-function createDefaultAppFactory(registry: ServerRegistry) {
-  return function defaultCreateApp(context: AppContext): React.ReactElement {
+function createDefaultAppFactory(registry: ServerRegistry) {
+  return function defaultCreateApp(context: AppContext): React.ReactElement {
     const Component = registry.routeComponents.get(context.routeId);
 
     if (!Component) {
@@ -1097,14 +1106,53 @@ function createDefaultAppFactory(registry: ServerRegistry) {
       );
     }
 
-    return React.createElement(Component, {
-      params: context.params,
-      loaderData: context.loaderData,
-    });
-  };
-}
-
-const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
+    return React.createElement(Component, {
+      params: context.params,
+      loaderData: context.loaderData,
+      __manduHydration: context.__manduHydration,
+    });
+  };
+}
+
+async function resolveInlineClientHydrationTarget(
+  route: {
+    id: string;
+    clientModule?: string;
+    clientExportName?: string;
+    hydration?: HydrationConfig;
+  },
+  rootDir: string,
+  src: string,
+): Promise<InlineClientHydrationTarget | undefined> {
+  if (!route.clientModule || !route.clientExportName || !src) {
+    return undefined;
+  }
+
+  try {
+    const module = await import(path.join(rootDir, route.clientModule));
+    const exportName = route.clientExportName;
+    const component = exportName === "default"
+      ? module.default
+      : module[exportName] ?? module.default;
+
+    if (!component) return undefined;
+
+    return {
+      routeId: route.id,
+      src,
+      priority: route.hydration?.priority ?? "visible",
+      component,
+    };
+  } catch (error) {
+    console.warn(
+      `[Mandu] Failed to resolve inline client hydration target for "${route.id}":`,
+      error,
+    );
+    return undefined;
+  }
+}
+
+const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
 
 // ========== Request Handler ==========
 
@@ -2017,8 +2065,19 @@ function extractTitleText(titleHtml: string): string | null {
 /**
  * SSR 렌더링 (Streaming/Non-streaming)
  */
-async function renderPageSSR(
-  route: { id: string; pattern: string; layoutChain?: string[]; streaming?: boolean; hydration?: HydrationConfig; errorModule?: string; loadingModule?: string; notFoundModule?: string },
+async function renderPageSSR(
+  route: {
+    id: string;
+    pattern: string;
+    layoutChain?: string[];
+    streaming?: boolean;
+    hydration?: HydrationConfig;
+    errorModule?: string;
+    loadingModule?: string;
+    notFoundModule?: string;
+    clientModule?: string;
+    clientExportName?: string;
+  },
   params: Record<string, string>,
   loaderData: unknown,
   url: string,
@@ -2028,15 +2087,30 @@ async function renderPageSSR(
 ): Promise<Result<Response>> {
   const settings = registry.settings;
   const defaultAppCreator = createDefaultAppFactory(registry);
-  const appCreator = registry.createAppFn || defaultAppCreator;
-
-  try {
-    let app = appCreator({
-      routeId: route.id,
-      url,
-      params,
-      loaderData,
-    });
+  const appCreator = registry.createAppFn || defaultAppCreator;
+
+  try {
+    const useStreaming = route.streaming !== undefined
+      ? route.streaming
+      : settings.streaming;
+    const needsIslandHydration = !!(
+      route.hydration &&
+      route.hydration.strategy !== "none" &&
+      settings.bundleManifest
+    );
+    const routeBundle = settings.bundleManifest?.bundles[route.id];
+    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
+    const inlineClientHydration = needsIslandHydration && !useStreaming
+      ? await resolveInlineClientHydrationTarget(route, settings.rootDir, bundleSrc)
+      : undefined;
+
+    let app = appCreator({
+      routeId: route.id,
+      url,
+      params,
+      loaderData,
+      __manduHydration: inlineClientHydration,
+    });
 
     // Phase 18.β — per-route Suspense wrapper (Next.js `loading.tsx` parity).
     // If the route declared a `loading.tsx`, wrap the page element in a
@@ -2064,20 +2138,13 @@ async function renderPageSSR(
 
     // Island 래핑: 레이아웃 적용 전에 페이지 콘텐츠만 island div로 감쌈
     // 이렇게 하면 레이아웃은 island 바깥에 위치하여 하이드레이션 시 레이아웃이 유지됨
-    const needsIslandHydration = !!(
-      route.hydration &&
-      route.hydration.strategy !== "none" &&
-      settings.bundleManifest
-    );
-    const routeBundle = settings.bundleManifest?.bundles[route.id];
-    const bundleSrc = routeBundle?.js ? `${routeBundle.js}?t=${Date.now()}` : "";
-    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0;
-
-    if (needsIslandHydration && !needsIslandWrap && settings.isDev) {
-      console.warn(
-        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
-        `Run mandu build/generate and ensure the route has a clientModule.`,
-      );
+    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0 && !inlineClientHydration;
+
+    if (needsIslandHydration && bundleSrc.length === 0 && settings.isDev) {
+      console.warn(
+        `[Mandu] Hydration requested for route "${route.id}" but no client bundle was found. ` +
+        `Run mandu build/generate and ensure the route has a clientModule.`,
+      );
     }
 
     if (needsIslandWrap) {
@@ -2098,12 +2165,7 @@ async function renderPageSSR(
     // #186: layout chain + page metadata 병합
     const builtMeta = await buildSSRMetadata(route, params, url, registry);
 
-    // Streaming SSR 모드 결정
-    const useStreaming = route.streaming !== undefined
-      ? route.streaming
-      : settings.streaming;
-
-    const pageResponse = await renderPageResponse({
+    const pageResponse = await renderPageResponse({
       app,
       useStreaming,
       title: builtMeta.title,
@@ -2114,11 +2176,12 @@ async function renderPageSSR(
       routePattern: route.pattern,
       layoutChain: route.layoutChain,
       hydration: route.hydration,
-      bundleManifest: settings.bundleManifest,
-      loaderData,
-      cssPath: settings.cssPath,
-      islandPreWrapped: needsIslandWrap,
-      transitions: settings.transitions,
+      bundleManifest: settings.bundleManifest,
+      loaderData,
+      cssPath: settings.cssPath,
+      islandPreWrapped: needsIslandWrap,
+      inlineClientHydration,
+      transitions: settings.transitions,
       prefetch: settings.prefetch,
       spa: settings.spa,
       devtools: settings.devtools,