@mandujs/core 0.54.16 → 0.54.18

package/src/router/fs-scanner.ts

@@ -7,7 +7,7 @@
  */
 
 import { stat } from "fs/promises";
-import { join, relative, basename, extname } from "path";
+import { dirname, join, relative, basename, extname } from "path";
 import type {
   ScannedFile,
   FSScannerConfig,
@@ -33,8 +33,17 @@ import { METADATA_ROUTES } from "../routes/types";
 import type { HydrationConfig } from "../spec/schema";
 import {
   hasUseClientDirective,
+  resolveClientImportModulePath,
   resolveRouteLevelClientEntry,
 } from "./client-entry";
+import {
+  assertNoClientBoundaryDiagnostics,
+  collectStaticImportSpecifiers,
+  isClientBoundaryModuleSpecifier,
+  transformClientBoundaries,
+  validateClientBoundaryExport,
+  validateClientBoundaryServerOnlyImports,
+} from "../bundler/client-boundary-transform";
 
 const HYDRATION_STRATEGIES = new Set(["none", "island", "full", "progressive"]);
 const HYDRATION_PRIORITIES = new Set(["immediate", "visible", "idle", "interaction"]);
@@ -406,8 +415,10 @@ export class FSScanner {
       // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
       let clientModule: string | undefined;
       let clientExportName: string | undefined;
+      let boundaries: NonNullable<FSRouteConfig["boundaries"]> = [];
       let hydration: HydrationConfig | undefined;
       let pageFileContent: string | null = null;
+      let pageHasUseClient = false;
 
       if (file.type === "page") {
         try {
@@ -417,6 +428,23 @@ export class FSScanner {
         }
         if (pageFileContent) {
           hydration = parsePageHydrationConfig(pageFileContent);
+          pageHasUseClient = hasUseClientDirective(pageFileContent);
+          if (!pageHasUseClient) {
+            boundaries = await this.resolveClientBoundaries(
+              rootDir,
+              modulePath,
+              routeId,
+              pageFileContent,
+              hydration?.priority ?? "visible",
+            );
+          }
+          if (boundaries.length > 0 && !hydration) {
+            hydration = {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            };
+          }
         }
       }
 
@@ -436,12 +464,11 @@ export class FSScanner {
             conflictsWith: islands[0].absolutePath,
           });
         }
-      } else if (file.type === "page" && pageFileContent) {
-        // page 파일 자체에서 "use client" 확인
-        const hasUseClient = hasUseClientDirective(pageFileContent);
-        if (hasUseClient) {
+      } else if (file.type === "page" && pageFileContent) {
+        // page 파일 자체에서 "use client" 확인
+        if (pageHasUseClient) {
           clientModule = modulePath;
-        } else {
+        } else if (boundaries.length === 0) {
           const routeClientEntry = await resolveRouteLevelClientEntry(rootDir, modulePath, pageFileContent);
           clientModule = routeClientEntry?.modulePath;
           clientExportName = routeClientEntry?.exportName;
@@ -465,6 +492,7 @@ export class FSScanner {
         componentModule: file.type === "page" ? modulePath : undefined,
         clientModule,
         clientExportName,
+        boundaries: boundaries && boundaries.length > 0 ? boundaries : undefined,
         hydration,
         layoutChain,
         loadingModule,
@@ -486,7 +514,7 @@ export class FSScanner {
     return { routes, routeErrors };
   }
 
-  private hasHydrationShellMismatchRisk(pageContent: string, _islandRelativePath: string): boolean {
+  private hasHydrationShellMismatchRisk(pageContent: string, _islandRelativePath: string): boolean {
     // import문에서 island 모듈의 변수명을 직접 파싱
     const importMatch = pageContent.match(
       /import\s+([A-Za-z_$][A-Za-z0-9_$]*)\s+from\s+["'][^"']*\.island(?:\.(?:tsx?|jsx?))?["']/
@@ -503,10 +531,116 @@ export class FSScanner {
     return new RegExp(
       `typeof\\s+${islandVarName}\\s*!==\\s*["']undefined["']\\s*&&\\s*null`
     ).test(pageContent);
-  }
-
-  /**
-   * 레이아웃 체인 해결
+  }
+
+  private async resolveClientBoundaries(
+    rootDir: string,
+    routeModule: string,
+    routeId: string,
+    source: string,
+    hydrate: NonNullable<HydrationConfig["priority"]>,
+  ): Promise<NonNullable<FSRouteConfig["boundaries"]>> {
+    const modules = await this.collectRouteBoundaryModules(rootDir, routeModule, source);
+    const boundaries: NonNullable<FSRouteConfig["boundaries"]> = [];
+
+    for (const moduleInfo of modules) {
+      const result = transformClientBoundaries(moduleInfo.source, {
+        routeId,
+        fileName: moduleInfo.modulePath,
+        hydrate,
+        ordinalOffset: boundaries.length,
+      });
+      if (result.boundaries.length === 0) continue;
+
+      const diagnostics = [...result.diagnostics];
+      const resolved = await Promise.all(result.boundaries.map(async (boundary) => {
+        const modulePath = await resolveClientImportModulePath(rootDir, boundary.source.file, boundary.module);
+        const resolvedBoundary = {
+          ...boundary,
+          module: modulePath ?? boundary.module,
+        };
+        if (modulePath) {
+          const clientSource = await Bun.file(join(rootDir, modulePath)).text();
+          diagnostics.push(...validateClientBoundaryServerOnlyImports(clientSource, resolvedBoundary, modulePath));
+          const validation = validateClientBoundaryExport(clientSource, resolvedBoundary, modulePath);
+          if (validation.diagnostic) diagnostics.push(validation.diagnostic);
+        }
+        return resolvedBoundary;
+      }));
+      assertNoClientBoundaryDiagnostics(diagnostics);
+      boundaries.push(...resolved);
+    }
+
+    return boundaries;
+  }
+
+  private async collectRouteBoundaryModules(
+    rootDir: string,
+    routeModule: string,
+    routeSource: string,
+  ): Promise<Array<{ modulePath: string; source: string }>> {
+    const visited = new Set<string>();
+    const modules: Array<{ modulePath: string; source: string }> = [];
+
+    const visit = async (modulePath: string, source: string): Promise<void> => {
+      const normalizedModulePath = modulePath.replace(/\\/g, "/").replace(/^\.\//, "");
+      if (visited.has(normalizedModulePath)) return;
+      visited.add(normalizedModulePath);
+      modules.push({ modulePath: normalizedModulePath, source });
+
+      for (const specifier of collectStaticImportSpecifiers(source, normalizedModulePath)) {
+        if (isClientBoundaryModuleSpecifier(specifier)) continue;
+        const resolved = await this.resolveRouteOwnedImportModulePath(rootDir, normalizedModulePath, specifier);
+        if (!resolved || visited.has(resolved)) continue;
+
+        let childSource: string;
+        try {
+          childSource = await Bun.file(join(rootDir, resolved)).text();
+        } catch {
+          continue;
+        }
+        if (hasUseClientDirective(childSource)) continue;
+
+        await visit(resolved, childSource);
+      }
+    };
+
+    await visit(routeModule, routeSource);
+    return modules;
+  }
+
+  private async resolveRouteOwnedImportModulePath(
+    rootDir: string,
+    importerModule: string,
+    specifier: string,
+  ): Promise<string | null> {
+    const normalized = specifier.replace(/\\/g, "/");
+    let basePath: string | null = null;
+
+    if (normalized.startsWith("@/") || normalized.startsWith("~/")) {
+      basePath = join(rootDir, "src", normalized.slice(2));
+    } else if (normalized.startsWith("./") || normalized.startsWith("../")) {
+      basePath = join(rootDir, dirname(importerModule), normalized);
+    }
+
+    if (!basePath) return null;
+
+    for (const candidate of expandRouteImportCandidates(basePath)) {
+      try {
+        const entry = await stat(candidate);
+        if (entry.isFile()) {
+          return relative(rootDir, candidate).replace(/\\/g, "/");
+        }
+      } catch {
+        // Try the next candidate.
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * 레이아웃 체인 해결
    */
   private resolveLayoutChain(
     segments: ScannedFile["segments"],
@@ -755,7 +889,7 @@ export function synthesizeLocaleRoutes(
   return out;
 }
 
-function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteConfig {
+function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteConfig {
   const prefixedPattern = route.pattern === "/"
     ? `/${locale}`
     : `/${locale}${route.pattern.startsWith("/") ? route.pattern : `/${route.pattern}`}`;
@@ -771,12 +905,26 @@ function prefixRouteWithLocale(route: FSRouteConfig, locale: string): FSRouteCon
       { raw: locale, type: "static" },
       ...route.segments,
     ],
-  };
-}
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Factory Function
-// ═══════════════════════════════════════════════════════════════════════════
+  };
+}
+
+function expandRouteImportCandidates(basePath: string): string[] {
+  if (/\.[cm]?[jt]sx?$/.test(basePath)) return [basePath];
+  return [
+    `${basePath}.tsx`,
+    `${basePath}.ts`,
+    `${basePath}.jsx`,
+    `${basePath}.js`,
+    join(basePath, "index.tsx"),
+    join(basePath, "index.ts"),
+    join(basePath, "index.jsx"),
+    join(basePath, "index.js"),
+  ];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Factory Function
+// ═══════════════════════════════════════════════════════════════════════════
 
 /**
  * 스캐너 생성 팩토리 함수

package/src/router/fs-types.ts

@@ -6,7 +6,7 @@
  * @module router/fs-types
  */
 
-import type { RouteKind, HydrationConfig, SpecHttpMethod } from "../spec/schema";
+import type { RouteKind, HydrationConfig, RouteClientBoundary, SpecHttpMethod } from "../spec/schema";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Segment Types
@@ -123,6 +123,9 @@ export interface FSRouteConfig {
   /** Named export used by the route-level client module, if not default. */
   clientExportName?: string;
 
+  /** Compiler-discovered client boundaries rendered by this route. */
+  boundaries?: RouteClientBoundary[];
+
   /** 적용할 레이아웃 체인 */
   layoutChain: string[];
 

package/src/runtime/__tests__/inline-client-hydration.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import React from "react";
+import type { BundleManifest } from "../../bundler/types";
+import type { RoutesManifest } from "../../spec/schema";
+import {
+  createServerRegistry,
+  startServer,
+  type ManduServer,
+} from "../server";
+
+const TEST_ROOT = path.resolve(process.cwd(), ".tmp-test-artifacts", "inline-client-hydration");
+
+function hydratedManifest(routeId: string): BundleManifest {
+  return {
+    version: 1,
+    buildTime: "2026-05-23T00:00:00.000Z",
+    env: "production",
+    bundles: {
+      [routeId]: {
+        js: `/.mandu/client/${routeId}.island.js`,
+        dependencies: ["_runtime", "_react"],
+        priority: "visible",
+      },
+    },
+    shared: {
+      runtime: "/.mandu/client/_runtime.js",
+      vendor: "/.mandu/client/_react.js",
+      router: "/.mandu/client/_router.js",
+    },
+  };
+}
+
+async function resetTestRoot(): Promise<void> {
+  await rm(TEST_ROOT, { recursive: true, force: true });
+  await mkdir(TEST_ROOT, { recursive: true });
+}
+
+afterEach(async () => {
+  await rm(TEST_ROOT, { recursive: true, force: true });
+});
+
+describe("startServer inline client hydration", () => {
+  it("captures component props through sync server pages and inferred named client exports", async () => {
+    await resetTestRoot();
+
+    const routeId = "pledges-$id";
+    const clientModule = "src/client/widgets/comments-section/CommentsSection.client.tsx";
+    const clientPath = path.join(TEST_ROOT, clientModule);
+    await mkdir(path.dirname(clientPath), { recursive: true });
+    await writeFile(
+      clientPath,
+      `
+import React from "react";
+
+export function CommentsSection({ pledgeId, initialComments }) {
+  return React.createElement(
+    "section",
+    { "data-pledge-id": pledgeId },
+    initialComments.map((comment) =>
+      React.createElement("p", { key: comment.id }, comment.body)
+    )
+  );
+}
+`,
+      "utf-8",
+    );
+
+    const imported = await import(`${pathToFileURL(clientPath).href}?t=${Date.now()}`);
+    const CommentsSection = imported.CommentsSection as React.ComponentType<{
+      pledgeId: string;
+      initialComments: Array<{ id: string; body: string }>;
+    }>;
+
+    function PledgePage(): React.ReactElement {
+      return React.createElement(
+        "main",
+        null,
+        React.createElement(CommentsSection, {
+          pledgeId: "pledge-1",
+          initialComments: [{ id: "c1", body: "serialized comment" }],
+        }),
+      );
+    }
+
+    const registry = createServerRegistry();
+    registry.registerRouteComponent(routeId, PledgePage);
+
+    const manifest: RoutesManifest = {
+      version: 1,
+      routes: [
+        {
+          id: routeId,
+          kind: "page",
+          pattern: "/pledges/:id",
+          module: "app/pledges/[id]/page.tsx",
+          componentModule: "app/pledges/[id]/page.tsx",
+          clientModule,
+          hydration: { strategy: "island", priority: "visible", preload: false },
+        },
+      ],
+    };
+
+    let server: ManduServer | undefined;
+    try {
+      server = startServer(manifest, {
+        port: 0,
+        registry,
+        rootDir: TEST_ROOT,
+        bundleManifest: hydratedManifest(routeId),
+        transitions: false,
+        prefetch: false,
+        spa: false,
+        devtools: false,
+        silent: true,
+      });
+
+      const response = await fetch(`http://127.0.0.1:${server.server.port}/pledges/pledge-1`);
+      const html = await response.text();
+
+      expect(response.status).toBe(200);
+      expect(html).toContain('data-mandu-island="pledges-$id--0"');
+      expect(html).toContain('type="application/json" data-mandu-props="pledges-$id--0"');
+      expect(html).toContain('"pledgeId":"pledge-1"');
+      expect(html).toContain('"initialComments"');
+      expect(html).toContain("serialized comment");
+      expect(html).not.toContain('data-mandu-island="pledges-$id"');
+    } finally {
+      server?.stop();
+    }
+  });
+});

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

@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import React from "react";
 import { renderPageResponse } from "../page-render-response";
 import type { BundleManifest } from "../../bundler/types";
+import { __ManduClientBoundary } from "../../internal/client-boundary";
 
 const HYDRATED_MANIFEST: BundleManifest = {
   version: 1,
@@ -102,6 +103,164 @@ describe("runtime page render response orchestration", () => {
     expect(html).toContain('data-hydrate="interaction"');
   });
 
+  it("does not duplicate pre-wrapped streaming islands and preloads split island chunks", async () => {
+    const response = await renderPageResponse({
+      app: React.createElement(
+        "div",
+        {
+          "data-mandu-island": "home",
+          "data-mandu-src": "/.mandu/client/home.island.js?t=prewrapped",
+          "data-mandu-priority": "visible",
+          "data-hydrate": "visible",
+          style: { display: "contents" },
+        },
+        React.createElement("main", null, "prewrapped-stream-page"),
+      ),
+      useStreaming: true,
+      title: "Prewrapped Stream",
+      headTags: "",
+      isDev: false,
+      routeId: "home",
+      routePattern: "/",
+      loaderData: undefined,
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: {
+        ...HYDRATED_MANIFEST,
+        islands: {
+          "home-widget": {
+            route: "home",
+            js: "/.mandu/client/home-widget.island.js",
+            priority: "visible",
+          },
+        },
+      },
+      islandPreWrapped: true,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html.match(/data-mandu-island="home"/g)?.length).toBe(1);
+    expect(html).toContain("prewrapped-stream-page");
+    expect(html).toContain('<link rel="modulepreload" href="/.mandu/client/home-widget.island.js?v=');
+    expect(html).not.toContain('<link rel="modulepreload" href="/.mandu/client/home.island.js?v=');
+  });
+
+  it("serializes compiler-owned client boundaries on the streaming path", async () => {
+    const routeId = "stream-boundary";
+    const manifest: BundleManifest = {
+      ...HYDRATED_MANIFEST,
+      bundles: {},
+      boundaries: {
+        "stream-boundary--0": {
+          route: routeId,
+          js: "/.mandu/client/stream-boundary--0.boundary.js",
+          module: "src/client/Counter.client.tsx",
+          exportName: "Counter",
+          priority: "visible",
+          hydrate: "visible",
+        },
+      },
+    };
+
+    const response = await renderPageResponse({
+      app: React.createElement(
+        "main",
+        null,
+        React.createElement(__ManduClientBoundary, {
+          routeId,
+          boundaryId: "stream-boundary--0",
+          module: "src/client/Counter.client.tsx",
+          exportName: "Counter",
+          hydrate: "visible",
+          props: { count: 7 },
+        }),
+      ),
+      useStreaming: true,
+      title: "Stream Boundary",
+      headTags: "",
+      isDev: false,
+      routeId,
+      routePattern: "/stream-boundary",
+      loaderData: undefined,
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: manifest,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html).toContain('data-mandu-island="stream-boundary--0"');
+    expect(html).toContain('data-mandu-boundary-id="stream-boundary--0"');
+    expect(html).toContain('data-mandu-client-export="Counter"');
+    expect(html).toContain('data-mandu-src="/.mandu/client/stream-boundary--0.boundary.js?t=');
+    expect(html).toContain('type="application/json" data-mandu-props="stream-boundary--0"');
+    expect(html).toContain('"count":7');
+    expect(html).toContain('<link rel="modulepreload" href="/.mandu/client/stream-boundary--0.boundary.js?v=');
+    expect(html).not.toContain('data-mandu-island="stream-boundary" data-mandu-src=');
+  });
+
+  it("keeps boundary context across async streaming server components", async () => {
+    const routeId = "async-stream-boundary";
+    const manifest: BundleManifest = {
+      ...HYDRATED_MANIFEST,
+      bundles: {},
+      boundaries: {
+        "async-stream-boundary--0": {
+          route: routeId,
+          js: "/.mandu/client/async-stream-boundary--0.boundary.js",
+          module: "src/client/AsyncCounter.client.tsx",
+          exportName: "AsyncCounter",
+          priority: "visible",
+          hydrate: "visible",
+        },
+      },
+    };
+
+    async function AsyncPage() {
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      return React.createElement(
+        "main",
+        null,
+        React.createElement(__ManduClientBoundary, {
+          routeId,
+          boundaryId: "async-stream-boundary--0",
+          module: "src/client/AsyncCounter.client.tsx",
+          exportName: "AsyncCounter",
+          hydrate: "visible",
+          props: { count: 11 },
+        }),
+      );
+    }
+
+    const response = await renderPageResponse({
+      app: React.createElement(AsyncPage),
+      useStreaming: true,
+      title: "Async Stream Boundary",
+      headTags: "",
+      isDev: false,
+      routeId,
+      routePattern: "/async-stream-boundary",
+      loaderData: undefined,
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: manifest,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html).toContain('data-mandu-island="async-stream-boundary--0"');
+    expect(html).toContain('data-mandu-src="/.mandu/client/async-stream-boundary--0.boundary.js?t=');
+    expect(html).toContain('data-mandu-props="async-stream-boundary--0"');
+    expect(html).toContain('"count":11');
+  });
+
   it("serializes non-streaming loaderData as the route server data exactly once", async () => {
     const response = await renderPageResponse({
       app: React.createElement("main", null, "hydrated-page"),
@@ -188,6 +347,59 @@ describe("runtime page render response orchestration", () => {
     expect(html).not.toContain('data-mandu-island="candidates-$id"');
   });
 
+  it("serializes inline client props through a sync server wrapper fallback", async () => {
+    function ClientWidget({ label }: { label: string }) {
+      return React.createElement("button", null, label);
+    }
+
+    function ServerWrapper({ label }: { label: string }) {
+      return React.createElement("section", null, React.createElement(ClientWidget, { label }));
+    }
+
+    function WrappedPage() {
+      return React.createElement("main", null, React.createElement(ServerWrapper, { label: "wrapped" }));
+    }
+
+    const response = await renderPageResponse({
+      app: React.createElement(WrappedPage),
+      useStreaming: false,
+      title: "Wrapped",
+      headTags: "",
+      isDev: false,
+      routeId: "wrapped-fallback",
+      routePattern: "/wrapped",
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: {
+        ...HYDRATED_MANIFEST,
+        bundles: {
+          "wrapped-fallback": {
+            js: "/.mandu/client/wrapped-fallback.island.js",
+            dependencies: ["_runtime", "_react"],
+            priority: "visible",
+          },
+        },
+      },
+      loaderData: undefined,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+      inlineClientHydration: {
+        routeId: "wrapped-fallback",
+        src: "/.mandu/client/wrapped-fallback.island.js",
+        priority: "visible",
+        component: ClientWidget,
+      },
+    });
+
+    const html = await response.text();
+    expect(html).toContain('data-mandu-island="wrapped-fallback--0"');
+    expect(html).toContain('data-mandu-src="/.mandu/client/wrapped-fallback.island.js"');
+    expect(html).toContain('data-mandu-props="wrapped-fallback--0"');
+    expect(html).toContain('"label":"wrapped"');
+    expect(html).not.toContain('data-mandu-island="wrapped-fallback"');
+  });
+
   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);