@mandujs/core 0.54.19 → 0.54.21

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,102 +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;
-    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";
+    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 ==========
 
@@ -2114,21 +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;
-    componentModule?: string;
-    clientModule?: string;
-    clientExportName?: string;
-    boundaries?: unknown[];
-  },
+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,
@@ -2138,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
@@ -2189,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) {
@@ -2216,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,
@@ -2227,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,
@@ -2422,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) {
@@ -3450,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.