@mandujs/core 0.54.13 → 0.54.15

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

@@ -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"),
@@ -100,4 +124,174 @@ 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"');
+  });
+
+  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

@@ -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: 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 };
+  }
+
+  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" && isAsyncFunctionComponent(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 isAsyncFunctionComponent(type: Function): boolean {
+  return !type.prototype?.isReactComponent &&
+    (type as { constructor?: { name?: string } }).constructor?.name === "AsyncFunction";
+}
+
+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`);