@mandujs/core 0.54.18 → 0.54.20

package/src/runtime/__tests__/searchparams-page-props.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "bun:test";
+import React from "react";
+import type { RoutesManifest } from "../../spec/schema";
+import {
+  createServerRegistry,
+  startServer,
+  type ManduServer,
+} from "../server";
+
+// Issue #314 — server page components must receive `searchParams` (query
+// string) as a prop, matching the value `generateMetadata` already gets.
+// SearchPage renders the query so we can assert it survives SSR.
+function SearchPage({
+  params,
+  searchParams,
+}: {
+  params: Record<string, string>;
+  searchParams: Record<string, string>;
+}): React.ReactElement {
+  return React.createElement(
+    "main",
+    null,
+    React.createElement("p", { "data-testid": "q" }, `q = ${searchParams.q ?? "(undefined)"}`),
+    React.createElement("p", { "data-testid": "id" }, `id = ${params.id ?? "(none)"}`),
+  );
+}
+
+function searchManifest(): RoutesManifest {
+  return {
+    version: 1,
+    routes: [
+      {
+        id: "search",
+        kind: "page",
+        pattern: "/search",
+        module: "app/search/page.tsx",
+        componentModule: "app/search/page.tsx",
+        hydration: { strategy: "none", priority: "visible", preload: false },
+      },
+    ],
+  };
+}
+
+async function fetchSearch(query: string): Promise<{ status: number; html: string }> {
+  const registry = createServerRegistry();
+  registry.registerRouteComponent("search", SearchPage);
+
+  let server: ManduServer | undefined;
+  try {
+    server = startServer(searchManifest(), {
+      port: 0,
+      registry,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+      silent: true,
+    });
+    const response = await fetch(`http://127.0.0.1:${server.server.port}/search${query}`);
+    return { status: response.status, html: await response.text() };
+  } finally {
+    server?.stop();
+  }
+}
+
+describe("server page searchParams prop (#314)", () => {
+  it("passes the query string to the page component", async () => {
+    const { status, html } = await fetchSearch("?q=foo");
+
+    expect(status).toBe(200);
+    expect(html).toContain("q = foo");
+    expect(html).not.toContain("q = (undefined)");
+  });
+
+  it("renders gracefully when the query string is absent", async () => {
+    const { status, html } = await fetchSearch("");
+
+    expect(status).toBe(200);
+    expect(html).toContain("q = (undefined)");
+  });
+});

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";

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, type InlineClientHydrationTarget } 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,12 +479,13 @@ export type ErrorLoader = () => Promise<{ default: ErrorComponent }>;
  * - component: React 컴포넌트
  * - filling: Slot의 ManduFilling 인스턴스 (loader 포함)
  */
-export interface PageRegistration {
-  component: React.ComponentType<{
-    params: Record<string, string>;
-    loaderData?: unknown;
-    __manduHydration?: InlineClientHydrationTarget;
-  }>;
+export interface PageRegistration {
+  component: React.ComponentType<{
+    params: Record<string, string>;
+    searchParams: Record<string, string>;
+    loaderData?: unknown;
+    __manduHydration?: InlineClientHydrationTarget;
+  }>;
   filling?: ManduFilling<unknown>;
   /** #186: page 모듈의 static `metadata` export (선택) */
   metadata?: Metadata;
@@ -506,20 +507,23 @@ 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;
-  __manduHydration?: InlineClientHydrationTarget;
-}
-
-type RouteComponent = (props: {
-  params: Record<string, string>;
-  loaderData?: unknown;
-  __manduHydration?: InlineClientHydrationTarget;
-}) => React.ReactElement;
+export interface AppContext {
+  routeId: string;
+  url: string;
+  params: Record<string, string>;
+  /** 요청 URL의 쿼리스트링 (generateMetadata와 동일한 값) */
+  searchParams: Record<string, string>;
+  /** SSR loader에서 로드한 데이터 */
+  loaderData?: unknown;
+  __manduHydration?: InlineClientHydrationTarget;
+}
+
+type RouteComponent = (props: {
+  params: Record<string, string>;
+  searchParams: Record<string, string>;
+  loaderData?: unknown;
+  __manduHydration?: InlineClientHydrationTarget;
+}) => React.ReactElement;
 type CreateAppFn = (context: AppContext) => React.ReactElement;
 
 // ========== Server Registry (인스턴스별 분리) ==========
@@ -1095,8 +1099,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) {
@@ -1106,90 +1110,103 @@ function createDefaultAppFactory(registry: ServerRegistry) {
       );
     }
 
-    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 || !src) {
-    return undefined;
-  }
-
-  try {
-    const module = await import(path.join(rootDir, route.clientModule));
-    const component = resolveInlineClientHydrationComponent(module, route);
-
-    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;
-  }
-}
-
-function resolveInlineClientHydrationComponent(
-  module: Record<string, unknown>,
-  route: { id: string; clientModule?: string; clientExportName?: string },
-): unknown {
-  if (module.default) return module.default;
-
-  const candidates = [
-    route.clientExportName && route.clientExportName !== "default" ? route.clientExportName : undefined,
-    inferInlineClientExportNameFromPath(route.clientModule),
-    inferInlineClientExportNameFromRouteId(route.id),
-  ].filter((candidate, index, values): candidate is string =>
-    !!candidate && values.indexOf(candidate) === index
-  );
-
-  for (const candidate of candidates) {
-    if (module[candidate]) return module[candidate];
-  }
-
-  const runtimeExports = Object.keys(module).filter((name) => name !== "__esModule");
-  return runtimeExports.length === 1 ? module[runtimeExports[0]] : undefined;
-}
-
-function inferInlineClientExportNameFromPath(clientModulePath: string | undefined): string | undefined {
-  if (!clientModulePath) return undefined;
-  const basename = path.basename(clientModulePath).replace(/\.[cm]?[jt]sx?$/, "");
-  const withoutClientSuffix = basename.replace(/\.(client|island)$/, "");
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(withoutClientSuffix)
-    ? withoutClientSuffix
-    : undefined;
-}
-
-function inferInlineClientExportNameFromRouteId(routeId: string): string | undefined {
-  const pascal = routeId
-    .split(/[^A-Za-z0-9]+/)
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join("");
-  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(pascal) ? pascal : undefined;
-}
-
-const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
+    return React.createElement(Component, {
+      params: context.params,
+      searchParams: context.searchParams,
+      loaderData: context.loaderData,
+      __manduHydration: context.__manduHydration,
+    });
+  };
+}
+
+async function resolveInlineClientHydrationTarget(
+  route: {
+    id: string;
+    componentModule?: string;
+    clientModule?: string;
+    clientExportName?: string;
+    hydration?: HydrationConfig;
+    boundaries?: unknown[];
+  },
+  rootDir: string,
+  src: string,
+): Promise<InlineClientHydrationTarget | undefined> {
+  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));
+    const component = resolveInlineClientHydrationComponent(module, route);
+
+    if (!component) return undefined;
+
+    return {
+      routeId: route.id,
+      src,
+      priority: route.hydration?.priority ?? "visible",
+      component,
+      legacyRuntimeScan,
+      sourceFile: route.componentModule ?? route.clientModule,
+    };
+  } catch (error) {
+    console.warn(
+      `[Mandu] Failed to resolve inline client hydration target for "${route.id}":`,
+      error,
+    );
+    return undefined;
+  }
+}
+
+function resolveInlineClientHydrationComponent(
+  module: Record<string, unknown>,
+  route: { id: string; clientModule?: string; clientExportName?: string },
+): unknown {
+  if (module.default) return module.default;
+
+  const candidates = [
+    route.clientExportName && route.clientExportName !== "default" ? route.clientExportName : undefined,
+    inferInlineClientExportNameFromPath(route.clientModule),
+    inferInlineClientExportNameFromRouteId(route.id),
+  ].filter((candidate, index, values): candidate is string =>
+    !!candidate && values.indexOf(candidate) === index
+  );
+
+  for (const candidate of candidates) {
+    if (module[candidate]) return module[candidate];
+  }
+
+  const runtimeExports = Object.keys(module).filter((name) => name !== "__esModule");
+  return runtimeExports.length === 1 ? module[runtimeExports[0]] : undefined;
+}
+
+function inferInlineClientExportNameFromPath(clientModulePath: string | undefined): string | undefined {
+  if (!clientModulePath) return undefined;
+  const basename = path.basename(clientModulePath).replace(/\.[cm]?[jt]sx?$/, "");
+  const withoutClientSuffix = basename.replace(/\.(client|island)$/, "");
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(withoutClientSuffix)
+    ? withoutClientSuffix
+    : undefined;
+}
+
+function inferInlineClientExportNameFromRouteId(routeId: string): string | undefined {
+  const pascal = routeId
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(pascal) ? pascal : undefined;
+}
+
+const INTERNAL_CACHE_ENDPOINT = "/_mandu/cache";
 
 // ========== Request Handler ==========
 
@@ -2102,19 +2119,21 @@ 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;
-    clientModule?: string;
-    clientExportName?: string;
-  },
+async function renderPageSSR(
+  route: {
+    id: string;
+    pattern: string;
+    layoutChain?: string[];
+    streaming?: boolean;
+    hydration?: HydrationConfig;
+    errorModule?: string;
+    loadingModule?: string;
+    notFoundModule?: string;
+    componentModule?: string;
+    clientModule?: string;
+    clientExportName?: string;
+    boundaries?: unknown[];
+  },
   params: Record<string, string>,
   loaderData: unknown,
   url: string,
@@ -2124,30 +2143,31 @@ async function renderPageSSR(
 ): Promise<Result<Response>> {
   const settings = registry.settings;
   const defaultAppCreator = createDefaultAppFactory(registry);
-  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,
-    });
+  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,
+      searchParams: extractSearchParams(url),
+      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
@@ -2175,13 +2195,13 @@ async function renderPageSSR(
 
     // Island 래핑: 레이아웃 적용 전에 페이지 콘텐츠만 island div로 감쌈
     // 이렇게 하면 레이아웃은 island 바깥에 위치하여 하이드레이션 시 레이아웃이 유지됨
-    const needsIslandWrap = needsIslandHydration && bundleSrc.length > 0 && !inlineClientHydration;
+    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 (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) {
@@ -2202,7 +2222,7 @@ async function renderPageSSR(
     // #186: layout chain + page metadata 병합
     const builtMeta = await buildSSRMetadata(route, params, url, registry);
 
-    const pageResponse = await renderPageResponse({
+    const pageResponse = await renderPageResponse({
       app,
       useStreaming,
       title: builtMeta.title,
@@ -2213,12 +2233,12 @@ async function renderPageSSR(
       routePattern: route.pattern,
       layoutChain: route.layoutChain,
       hydration: route.hydration,
-      bundleManifest: settings.bundleManifest,
-      loaderData,
-      cssPath: settings.cssPath,
-      islandPreWrapped: needsIslandWrap,
-      inlineClientHydration,
-      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,
@@ -2408,6 +2428,7 @@ async function renderNotFoundPage(
     // streaming, no island bundling — a 404 page is plain).
     let app: React.ReactElement = React.createElement(NotFoundComponent, {
       params,
+      searchParams: extractSearchParams(req.url),
       loaderData,
     });
     if (route.layoutChain && route.layoutChain.length > 0) {
@@ -3436,6 +3457,7 @@ async function handleRequestInternal(
         }
         const rawApp = React.createElement(registration.component, {
           params: {},
+          searchParams: extractSearchParams(req.url),
           loaderData,
         });
         // Issue #198 — pre-resolve in case the not-found component is async.