@mandujs/core 0.54.17 → 0.54.19

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"),
@@ -175,6 +334,8 @@ describe("runtime page render response orchestration", () => {
         src: "/.mandu/client/candidates-$id.island.js",
         priority: "immediate",
         component: PledgeAccordion,
+        legacyRuntimeScan: true,
+        sourceFile: "app/candidates/[id]/page.tsx",
       },
     });
 
@@ -188,6 +349,61 @@ 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,
+        legacyRuntimeScan: true,
+        sourceFile: "app/wrapped/page.tsx",
+      },
+    });
+
+    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);
@@ -287,6 +503,8 @@ describe("runtime page render response orchestration", () => {
         src: "/.mandu/client/ordered.island.js",
         priority: "visible",
         component: ClientWidget,
+        legacyRuntimeScan: true,
+        sourceFile: "app/ordered/page.tsx",
       },
     });
 

package/src/runtime/handlers.ts

@@ -23,7 +23,7 @@ import {
   type PageRegistration,
 } from "./server";
 import { registerManifest } from "./registry";
-import { needsHydration, type RoutesManifest } from "../spec/schema";
+import { needsHydration, type RouteClientBoundary, type RoutesManifest } from "../spec/schema";
 
 type RouteModule = Record<string, unknown>;
 
@@ -84,7 +84,7 @@ function createMethodDispatcher(module: RouteModule, routeId: string) {
   };
 }
 
-export interface RegisterHandlersOptions {
+export interface RegisterHandlersOptions {
   /**
    * Module import function (dev: importFresh, start: standard import).
    * The optional `opts.changedFile` is forwarded into Phase 7.0 B5's
@@ -92,7 +92,17 @@ export interface RegisterHandlersOptions {
    * module's import graph, `importFn` returns the cached bundle in ~0.1 ms
    * instead of re-running Bun.build.
    */
-  importFn: (modulePath: string, opts?: { changedFile?: string }) => Promise<unknown>;
+  importFn: (
+    modulePath: string,
+    opts?: {
+      changedFile?: string;
+      clientBoundaryTransform?: {
+        routeId: string;
+        hydrate?: string;
+        boundaries?: RouteClientBoundary[];
+      };
+    },
+  ) => Promise<unknown>;
   /** Set for tracking already registered layout paths */
   registeredLayouts: Set<string>;
   /** Clear layout cache on reload */
@@ -115,9 +125,23 @@ export async function registerManifestHandlers(
   rootDir: string,
   options: RegisterHandlersOptions
 ): Promise<void> {
-  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
-  const importOpts: { changedFile?: string } | undefined =
-    changedFile !== undefined ? { changedFile } : undefined;
+  const { importFn, registeredLayouts, isReload = false, changedFile } = options;
+  const baseImportOpts: { changedFile?: string } | undefined =
+    changedFile !== undefined ? { changedFile } : undefined;
+  const importOptsForRoute = (route?: RoutesManifest["routes"][number]) => {
+    const boundaryTransform = route?.kind === "page" && route.boundaries?.length
+        ? {
+            routeId: route.id,
+            hydrate: route.hydration?.priority ?? "visible",
+            boundaries: route.boundaries,
+          }
+      : undefined;
+    if (!baseImportOpts && !boundaryTransform) return undefined;
+    return {
+      ...baseImportOpts,
+      ...(boundaryTransform ? { clientBoundaryTransform: boundaryTransform } : {}),
+    };
+  };
 
   if (isReload) {
     registeredLayouts.clear();
@@ -134,19 +158,19 @@ export async function registerManifestHandlers(
     // runtime dispatcher invokes the default export on each request
     // so HMR reloads pick up edits automatically (same pattern as
     // API routes below).
-    if (route.kind === "metadata") {
-      const modulePath = path.resolve(rootDir, route.module);
-      registerMetadataHandler(route.id, async () => {
-        return importFn(modulePath, importOpts);
-      });
-      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
-      continue;
+    if (route.kind === "metadata") {
+      const modulePath = path.resolve(rootDir, route.module);
+      registerMetadataHandler(route.id, async () => {
+        return importFn(modulePath, importOptsForRoute(route));
+      });
+      console.log(`  🗺️  Metadata: ${route.pattern} -> ${route.id}`);
+      continue;
     }
 
-    if (route.kind === "api") {
-      const modulePath = path.resolve(rootDir, route.module);
-      try {
-        const module = (await importFn(modulePath, importOpts)) as RouteModule;
+    if (route.kind === "api") {
+      const modulePath = path.resolve(rootDir, route.module);
+      try {
+        const module = (await importFn(modulePath, importOptsForRoute(route))) as RouteModule;
         let handler: unknown = module.default ?? module.handler ?? module;
 
         // 1) ManduFilling instance
@@ -193,7 +217,7 @@ export async function registerManifestHandlers(
               // Layout modules must export a default component. Runtime
               // validation in `renderToHTML` / page-loader asserts this —
               // so casting the unknown `importFn` result is safe here.
-              return importFn(absLayoutPath, importOpts);
+              return importFn(absLayoutPath, baseImportOpts);
             }) as Parameters<typeof registerLayoutLoader>[1]);
             registeredLayouts.add(layoutPath);
             console.log(`  🎨 Layout: ${layoutPath}`);
@@ -204,7 +228,7 @@ export async function registerManifestHandlers(
       // Use PageHandler if slotModule exists (filling.loader support)
       if (route.slotModule) {
         registerPageHandler(route.id, async () => {
-          const mod = (await importFn(componentPath, importOpts)) as Record<string, unknown>;
+          const mod = (await importFn(componentPath, importOptsForRoute(route))) as Record<string, unknown>;
           // Normalize the page module shape. Users write pages in two styles:
           //   (a) `export default function Page() {…}` + `export const filling = …`
           //   (b) `export default { component: …, filling: … }`
@@ -242,7 +266,7 @@ export async function registerManifestHandlers(
           `  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
         );
       } else {
-        registerPageLoader(route.id, (() => importFn(componentPath, importOpts)) as Parameters<typeof registerPageLoader>[1]);
+        registerPageLoader(route.id, (() => importFn(componentPath, importOptsForRoute(route))) as Parameters<typeof registerPageLoader>[1]);
         console.log(
           `  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`
         );
@@ -252,7 +276,7 @@ export async function registerManifestHandlers(
 
   // Phase 6.3: register `app/not-found.tsx` if it exists. Global, one per
   // app — the server falls through to the built-in 404 if unregistered.
-  await registerAppNotFound(rootDir, importFn, importOpts);
+  await registerAppNotFound(rootDir, importFn, baseImportOpts);
 }
 
 /**
@@ -260,11 +284,11 @@ export async function registerManifestHandlers(
  * project root and register it as the app-level 404 handler. Silent
  * no-op if no file exists — the server's built-in 404 covers that case.
  */
-async function registerAppNotFound(
-  rootDir: string,
-  importFn: (modulePath: string, opts?: { changedFile?: string }) => Promise<unknown>,
-  importOpts?: { changedFile?: string },
-): Promise<void> {
+async function registerAppNotFound(
+  rootDir: string,
+  importFn: RegisterHandlersOptions["importFn"],
+  importOpts?: { changedFile?: string },
+): Promise<void> {
   const candidates = [
     "app/not-found.tsx",
     "app/not-found.ts",

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

@@ -11,6 +11,13 @@ export interface InlineClientHydrationTarget {
   src: string;
   priority: NonNullable<HydrationConfig["priority"]>;
   component: unknown;
+  /**
+   * Compatibility path for pre-F42 route-level client modules where the
+   * client component is hidden behind a server wrapper. Disabled by default
+   * because it invokes user function components outside React's renderer.
+   */
+  legacyRuntimeScan?: boolean;
+  sourceFile?: string;
 }
 
 export interface PageRenderResponseOptions {
@@ -125,7 +132,8 @@ async function resolveAndWrapInlineClientHydration(
     };
   }
 
-  if (typeof type === "function" && !isClassComponent(type)) {
+  if (target.legacyRuntimeScan && typeof type === "function" && !isClassComponent(type)) {
+    warnLegacyRuntimePartialScan(target);
     const rendered = await renderFunctionComponentForInlineHydration(
       type,
       element.props ?? {},
@@ -152,6 +160,20 @@ async function resolveAndWrapInlineClientHydration(
   return { node: cloned, didWrap: resolvedChildren.didWrap };
 }
 
+const warnedLegacyRuntimePartialScanRoutes = new Set<string>();
+
+function warnLegacyRuntimePartialScan(target: InlineClientHydrationTarget): void {
+  if (warnedLegacyRuntimePartialScanRoutes.has(target.routeId)) return;
+  warnedLegacyRuntimePartialScanRoutes.add(target.routeId);
+
+  const file = target.sourceFile ? ` file="${target.sourceFile}"` : "";
+  console.warn(
+    `[MANDU_LEGACY_RUNTIME_PARTIAL_SCAN] route="${target.routeId}"${file}: ` +
+    "runtime client component discovery is running under the compatibility flag. " +
+    "Migrate this route to compiler-owned client boundaries so SSR does not invoke user components during discovery.",
+  );
+}
+
 function isAsyncFunctionComponent(type: Function): boolean {
   return !type.prototype?.isReactComponent &&
     (type as { constructor?: { name?: string } }).constructor?.name === "AsyncFunction";
@@ -214,6 +236,7 @@ async function renderStreamingPageResponse(
     criticalData: options.loaderData as Record<string, unknown> | undefined,
     enableClientRouter: true,
     cssPath: options.cssPath,
+    islandPreWrapped: !!options.islandPreWrapped,
     transitions: options.transitions,
     prefetch: options.prefetch,
     spa: options.spa,

package/src/runtime/server.ts

@@ -1117,9 +1117,11 @@ function createDefaultAppFactory(registry: ServerRegistry) {
 async function resolveInlineClientHydrationTarget(
   route: {
     id: string;
+    componentModule?: string;
     clientModule?: string;
     clientExportName?: string;
     hydration?: HydrationConfig;
+    boundaries?: unknown[];
   },
   rootDir: string,
   src: string,
@@ -1127,6 +1129,14 @@ async function resolveInlineClientHydrationTarget(
   if (!route.clientModule || !src) {
     return undefined;
   }
+  if (route.boundaries && route.boundaries.length > 0) {
+    return undefined;
+  }
+
+  const legacyRuntimeScan = process.env.MANDU_LEGACY_RUNTIME_PARTIAL_SCAN === "1";
+  if (!legacyRuntimeScan) {
+    return undefined;
+  }
 
   try {
     const module = await import(path.join(rootDir, route.clientModule));
@@ -1139,6 +1149,8 @@ async function resolveInlineClientHydrationTarget(
       src,
       priority: route.hydration?.priority ?? "visible",
       component,
+      legacyRuntimeScan,
+      sourceFile: route.componentModule ?? route.clientModule,
     };
   } catch (error) {
     console.warn(
@@ -2112,8 +2124,10 @@ async function renderPageSSR(
     errorModule?: string;
     loadingModule?: string;
     notFoundModule?: string;
+    componentModule?: string;
     clientModule?: string;
     clientExportName?: string;
+    boundaries?: unknown[];
   },
   params: Record<string, string>,
   loaderData: unknown,

package/src/runtime/ssr.ts

@@ -8,10 +8,11 @@ import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { PORTS, TIMEOUTS } from "../constants";
 import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
-import { generateFastRefreshPreamble } from "../bundler/dev";
+import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
 import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
-import { maybeInjectDevOverlay } from "../dev-error-overlay";
+import { maybeInjectDevOverlay } from "../dev-error-overlay";
+import { renderWithManduClientBoundaryManifest } from "../internal/client-boundary";
 
 /**
  * Issue #192 — `@view-transition` at-rule block.
@@ -275,8 +276,16 @@ function generateHydrationScripts(
       scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
     }
   }
-
-  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
+
+  if (manifest.boundaries) {
+    for (const boundary of Object.values(manifest.boundaries)) {
+      if (boundary.route !== routeId) continue;
+      const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
     scripts.push(`<script type="module" src="${escapeHtmlAttr(manifest.shared.runtime)}"></script>`);
   }
@@ -703,7 +712,9 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   } catch { /* client 모듈 로드 실패 시 무시 */ }
 
   const renderToString = getRenderToString();
-  let content = renderToString(element);
+  let content = renderWithManduClientBoundaryManifest(routeId, bundleManifest, () =>
+    renderToString(element),
+  );
 
   // 렌더링 중 수집된 head 태그
   collectedHeadTags = headGet?.() ?? "";