@mandujs/core 0.54.19 → 0.54.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.19",
+  "version": "0.54.20",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/build.test.ts

@@ -17,7 +17,7 @@ async function mkRepoTempDir(prefix: string): Promise<string> {
   await mkdir(repoTempRoot, { recursive: true });
   return mkdtemp(path.join(repoTempRoot, prefix));
 }
-
+
 async function importBuiltModule(relativePath: string): Promise<Record<string, unknown>> {
   const fileUrl = pathToFileURL(path.join(rootDir, relativePath)).href;
   return import(`${fileUrl}?t=${Date.now()}`);
@@ -42,7 +42,11 @@ async function evaluateGeneratedHydrationRuntime(): Promise<{ hydrateIslands: ()
     );
 
   const reactStub = {
-    Component: class {},
+    Component: class {
+      render() {
+        return null;
+      }
+    },
     createElement(type: unknown, props: Record<string, unknown> | null, ...children: unknown[]) {
       if (
         typeof type === "function" &&
@@ -90,19 +94,19 @@ async function waitForRuntimeAssertion(assertion: () => boolean): Promise<void>
   }
   expect(assertion()).toBe(true);
 }
-
-/**
- * Run `buildClientBundles` in an isolated `bun` subprocess.
- *
- * Bun 1.3.x exhibits a deterministic `AggregateError: Bundle failed` when
- * `buildClientBundles` is called from a test file AND the same `bun test`
- * process has previously imported `react` / `react-dom` through any sibling
- * test file (happens transitively through almost every `src/testing/*` or
- * `src/runtime/*` consumer). Retrying in-process does not recover — the
- * resolver state is sticky. A fresh subprocess has a clean module graph.
- * See `__tests__/build-runner.ts` for the subprocess entrypoint and more
- * background.
- */
+
+/**
+ * Run `buildClientBundles` in an isolated `bun` subprocess.
+ *
+ * Bun 1.3.x exhibits a deterministic `AggregateError: Bundle failed` when
+ * `buildClientBundles` is called from a test file AND the same `bun test`
+ * process has previously imported `react` / `react-dom` through any sibling
+ * test file (happens transitively through almost every `src/testing/*` or
+ * `src/runtime/*` consumer). Retrying in-process does not recover — the
+ * resolver state is sticky. A fresh subprocess has a clean module graph.
+ * See `__tests__/build-runner.ts` for the subprocess entrypoint and more
+ * background.
+ */
 async function runBuildInSubprocess(root: string, mode?: string): Promise<{
   success: boolean;
   errors: string[];
@@ -134,36 +138,36 @@ async function runBuildInSubprocess(root: string, mode?: string): Promise<{
     boundaries?: Record<string, { js?: string; route?: string; module?: string; exportName?: string; hydrate?: string }>;
   } | null;
 }> {
-  const runner = path.join(
-    import.meta.dir,
-    "__tests__",
-    "build-runner.ts",
-  );
-  try {
-    const args = [process.execPath, "run", runner, root];
-    if (mode) args.push(mode);
-    const proc = Bun.spawn(args, {
-      cwd: path.resolve(import.meta.dir, "..", ".."),
-      stdin: "ignore",
-      stdout: "pipe",
-      stderr: "inherit",
-    });
-    const out = await new Response(proc.stdout).text();
-    await proc.exited;
-
-    // Find the final JSON line — the runner may log Mandu dev banners
-    // (e.g. "[Mandu] DevTools …") before emitting the payload. The
-    // contract is: last non-empty line is the JSON blob.
-    const lines = out.split(/\r?\n/).filter((l) => l.trim().length > 0);
-    const last = lines[lines.length - 1] ?? "";
-    try {
-      const parsed = JSON.parse(last);
+  const runner = path.join(
+    import.meta.dir,
+    "__tests__",
+    "build-runner.ts",
+  );
+  try {
+    const args = [process.execPath, "run", runner, root];
+    if (mode) args.push(mode);
+    const proc = Bun.spawn(args, {
+      cwd: path.resolve(import.meta.dir, "..", ".."),
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "inherit",
+    });
+    const out = await new Response(proc.stdout).text();
+    await proc.exited;
+
+    // Find the final JSON line — the runner may log Mandu dev banners
+    // (e.g. "[Mandu] DevTools …") before emitting the payload. The
+    // contract is: last non-empty line is the JSON blob.
+    const lines = out.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    const last = lines[lines.length - 1] ?? "";
+    try {
+      const parsed = JSON.parse(last);
       return {
         success: parsed.success === true,
         errors: Array.isArray(parsed.errors) ? parsed.errors : [],
         manifest: parsed.manifest ?? null,
       };
-    } catch (e) {
+    } catch (e) {
       return {
         success: false,
         errors: [
@@ -176,54 +180,54 @@ async function runBuildInSubprocess(root: string, mode?: string): Promise<{
     return { success: false, errors: [`spawn failed: ${String(err)}`], manifest: null };
   }
 }
-
+
 beforeAll(async () => {
   rootDir = await mkRepoTempDir("bundler-");
-
-  await mkdir(path.join(rootDir, "app"), { recursive: true });
-  await writeFile(
-    path.join(rootDir, "package.json"),
-    JSON.stringify({ name: "mandu-build-test", type: "module" }, null, 2),
-    "utf-8",
-  );
-  await writeFile(
-    path.join(rootDir, "app", "demo.client.tsx"),
-    "export default function DemoIsland() { return null; }\n",
-    "utf-8",
-  );
-
-  result = await runBuildInSubprocess(rootDir);
-});
-
-afterAll(async () => {
-  if (rootDir) {
-    await rm(rootDir, { recursive: true, force: true });
-  }
-});
-
-// Historical note — `MANDU_SKIP_BUNDLER_TESTS` gate REMOVED.
-//
-// A previous revision gated this describe block behind
-// `describe.skipIf(MANDU_SKIP_BUNDLER_TESTS === "1")` because running
-// `bun test src/bundler/` without the gate hung indefinitely on Windows
-// (see Phase 0.6 and `docs/qa/wave-R2-integration-report.md`). Root cause
-// was NOT actually in THIS file — it was a deadlock in `safe-build.test.ts`'s
-// "slot handoff" regression test, which drove Bun's microtask queue with a
-// `while (!stop) { await Promise.resolve() }` sampler. That starved libuv
-// I/O callbacks, so the 7 parallel `safeBuild()` calls never completed, the
-// whole test process hung, and downstream test files (including this one
-// when run in the same invocation) looked flaky when they were simply
-// never reached. The handoff sampler now yields via `setImmediate`, which
-// unblocks Bun.build completion and makes `bun test src/bundler/` finish
-// deterministically in ~35s on Windows. Confirmed green 3/3 runs without
-// the gate on 2026-04-20. If you are tempted to re-introduce the skip here,
-// first check whether a sibling test is starving the event loop.
-//
-// A second, independent flake — Bun.build `AggregateError: Bundle failed`
-// when another test file in the same invocation has imported `react` —
-// is now sidestepped by running `buildClientBundles` in a spawned `bun`
-// subprocess via `__tests__/build-runner.ts`. In-process retry does not
-// recover from that one; a fresh module graph does.
+
+  await mkdir(path.join(rootDir, "app"), { recursive: true });
+  await writeFile(
+    path.join(rootDir, "package.json"),
+    JSON.stringify({ name: "mandu-build-test", type: "module" }, null, 2),
+    "utf-8",
+  );
+  await writeFile(
+    path.join(rootDir, "app", "demo.client.tsx"),
+    "export default function DemoIsland() { return null; }\n",
+    "utf-8",
+  );
+
+  result = await runBuildInSubprocess(rootDir);
+});
+
+afterAll(async () => {
+  if (rootDir) {
+    await rm(rootDir, { recursive: true, force: true });
+  }
+});
+
+// Historical note — `MANDU_SKIP_BUNDLER_TESTS` gate REMOVED.
+//
+// A previous revision gated this describe block behind
+// `describe.skipIf(MANDU_SKIP_BUNDLER_TESTS === "1")` because running
+// `bun test src/bundler/` without the gate hung indefinitely on Windows
+// (see Phase 0.6 and `docs/qa/wave-R2-integration-report.md`). Root cause
+// was NOT actually in THIS file — it was a deadlock in `safe-build.test.ts`'s
+// "slot handoff" regression test, which drove Bun's microtask queue with a
+// `while (!stop) { await Promise.resolve() }` sampler. That starved libuv
+// I/O callbacks, so the 7 parallel `safeBuild()` calls never completed, the
+// whole test process hung, and downstream test files (including this one
+// when run in the same invocation) looked flaky when they were simply
+// never reached. The handoff sampler now yields via `setImmediate`, which
+// unblocks Bun.build completion and makes `bun test src/bundler/` finish
+// deterministically in ~35s on Windows. Confirmed green 3/3 runs without
+// the gate on 2026-04-20. If you are tempted to re-introduce the skip here,
+// first check whether a sibling test is starving the event loop.
+//
+// A second, independent flake — Bun.build `AggregateError: Bundle failed`
+// when another test file in the same invocation has imported `react` —
+// is now sidestepped by running `buildClientBundles` in a spawned `bun`
+// subprocess via `__tests__/build-runner.ts`. In-process retry does not
+// recover from that one; a fresh module graph does.
 describe("buildClientBundles vendor shims", () => {
   test("build succeeds", () => {
     if (!result.success) {
@@ -245,61 +249,61 @@ describe("buildClientBundles vendor shims", () => {
   });
 
   test("re-exports modern React 19 APIs used by islands", async () => {
-    const reactShim = await importBuiltModule(".mandu/client/_react.js");
-    const requiredExports = [
-      "Activity",
-      "__COMPILER_RUNTIME",
-      "cache",
-      "cacheSignal",
-      "startTransition",
-      "use",
-      "useActionState",
-      "useEffectEvent",
-      "useOptimistic",
-      "unstable_useCacheRefresh",
-    ];
-
-    for (const exportName of requiredExports) {
-      expect(exportName in reactShim).toBe(true);
-    }
-  });
-
-  test("re-exports modern react-dom and react-dom/client APIs", async () => {
-    const reactDomShim = await importBuiltModule(".mandu/client/_react-dom.js");
-    for (const exportName of [
-      "preconnect",
-      "prefetchDNS",
-      "preinit",
-      "preinitModule",
-      "preload",
-      "preloadModule",
-      "requestFormReset",
-      "unstable_batchedUpdates",
-      "useFormState",
-      "useFormStatus",
-    ]) {
-      expect(exportName in reactDomShim).toBe(true);
-    }
-
-    const reactDomClientShim = await importBuiltModule(".mandu/client/_react-dom-client.js");
-    for (const exportName of ["createRoot", "hydrateRoot", "version"]) {
-      expect(exportName in reactDomClientShim).toBe(true);
-    }
-  });
-
-  test("embeds hydration guards for deferred trigger strategies", async () => {
-    const runtimeSource = await readFile(path.join(rootDir, ".mandu", "client", "_runtime.js"), "utf-8");
-    expect(runtimeSource).toContain("function resolveHydrationTarget");
-    expect(runtimeSource).toContain("function hasHydratableMarkup");
-    expect(runtimeSource).toContain("function shouldHydrateCompiledIsland");
-    expect(runtimeSource).toContain("onRecoverableError");
-    expect(runtimeSource).toContain("data-mandu-hydrating");
-    expect(runtimeSource).toContain("data-mandu-render-mode");
-    expect(runtimeSource).toContain("data-mandu-recoverable-error");
+    const reactShim = await importBuiltModule(".mandu/client/_react.js");
+    const requiredExports = [
+      "Activity",
+      "__COMPILER_RUNTIME",
+      "cache",
+      "cacheSignal",
+      "startTransition",
+      "use",
+      "useActionState",
+      "useEffectEvent",
+      "useOptimistic",
+      "unstable_useCacheRefresh",
+    ];
+
+    for (const exportName of requiredExports) {
+      expect(exportName in reactShim).toBe(true);
+    }
+  });
+
+  test("re-exports modern react-dom and react-dom/client APIs", async () => {
+    const reactDomShim = await importBuiltModule(".mandu/client/_react-dom.js");
+    for (const exportName of [
+      "preconnect",
+      "prefetchDNS",
+      "preinit",
+      "preinitModule",
+      "preload",
+      "preloadModule",
+      "requestFormReset",
+      "unstable_batchedUpdates",
+      "useFormState",
+      "useFormStatus",
+    ]) {
+      expect(exportName in reactDomShim).toBe(true);
+    }
+
+    const reactDomClientShim = await importBuiltModule(".mandu/client/_react-dom-client.js");
+    for (const exportName of ["createRoot", "hydrateRoot", "version"]) {
+      expect(exportName in reactDomClientShim).toBe(true);
+    }
+  });
+
+  test("embeds hydration guards for deferred trigger strategies", async () => {
+    const runtimeSource = await readFile(path.join(rootDir, ".mandu", "client", "_runtime.js"), "utf-8");
+    expect(runtimeSource).toContain("function resolveHydrationTarget");
+    expect(runtimeSource).toContain("function hasHydratableMarkup");
+    expect(runtimeSource).toContain("function shouldHydrateCompiledIsland");
+    expect(runtimeSource).toContain("onRecoverableError");
+    expect(runtimeSource).toContain("data-mandu-hydrating");
+    expect(runtimeSource).toContain("data-mandu-render-mode");
+    expect(runtimeSource).toContain("data-mandu-recoverable-error");
     expect(runtimeSource).toContain('"click"');
     expect(runtimeSource).not.toContain("pointerdown");
-  });
-
+  });
+
   test("runtime parses SSR data script before island setup", async () => {
     const runtimeSource = await readFile(path.join(rootDir, ".mandu", "client", "_runtime.js"), "utf-8");
     expect(runtimeSource).toContain("function readManduData");
@@ -476,81 +480,81 @@ describe("buildClientBundles vendor shims", () => {
 
   test("does not bundle a server page when stale manifest marks page.tsx as clientModule", async () => {
     const staleRoot = await mkRepoTempDir("stale-client-module-");
-    try {
-      await mkdir(path.join(staleRoot, "app"), { recursive: true });
-      await mkdir(path.join(staleRoot, "src", "shared", "contracts"), { recursive: true });
-      await writeFile(
-        path.join(staleRoot, "package.json"),
-        JSON.stringify({ name: "mandu-stale-client-module-test", type: "module" }, null, 2),
-        "utf-8",
-      );
-      await writeFile(
-        path.join(staleRoot, "src", "shared", "contracts", "api.ts"),
-        'export const INTERNAL_BASE = process.env.MANDU_INTERNAL_URL ?? "http://localhost:3333";\n',
-        "utf-8",
-      );
-      await writeFile(
-        path.join(staleRoot, "app", "page.tsx"),
-        'import { INTERNAL_BASE } from "../src/shared/contracts/api";\n' +
-          "export default async function HomePage() {\n" +
-          "  return <main>{INTERNAL_BASE}</main>;\n" +
-          "}\n",
-        "utf-8",
-      );
-
-      const staleResult = await runBuildInSubprocess(staleRoot, "server-page-client-module");
-      expect(staleResult.success).toBe(false);
-      expect(staleResult.errors.join("\n")).toContain("missing \"use client\"");
-      expect(await Bun.file(path.join(staleRoot, ".mandu", "client", "index.island.js")).exists()).toBe(false);
-    } finally {
-      await rm(staleRoot, { recursive: true, force: true });
-    }
-  });
-
+    try {
+      await mkdir(path.join(staleRoot, "app"), { recursive: true });
+      await mkdir(path.join(staleRoot, "src", "shared", "contracts"), { recursive: true });
+      await writeFile(
+        path.join(staleRoot, "package.json"),
+        JSON.stringify({ name: "mandu-stale-client-module-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(staleRoot, "src", "shared", "contracts", "api.ts"),
+        'export const INTERNAL_BASE = process.env.MANDU_INTERNAL_URL ?? "http://localhost:3333";\n',
+        "utf-8",
+      );
+      await writeFile(
+        path.join(staleRoot, "app", "page.tsx"),
+        'import { INTERNAL_BASE } from "../src/shared/contracts/api";\n' +
+          "export default async function HomePage() {\n" +
+          "  return <main>{INTERNAL_BASE}</main>;\n" +
+          "}\n",
+        "utf-8",
+      );
+
+      const staleResult = await runBuildInSubprocess(staleRoot, "server-page-client-module");
+      expect(staleResult.success).toBe(false);
+      expect(staleResult.errors.join("\n")).toContain("missing \"use client\"");
+      expect(await Bun.file(path.join(staleRoot, ".mandu", "client", "index.island.js")).exists()).toBe(false);
+    } finally {
+      await rm(staleRoot, { recursive: true, force: true });
+    }
+  });
+
   test("rewrites route-component clientModule to the real client import before bundling", async () => {
     const routeClientRoot = await mkRepoTempDir("route-client-import-");
-    try {
-      await mkdir(path.join(routeClientRoot, "app", "login"), { recursive: true });
-      await mkdir(path.join(routeClientRoot, "src", "client", "pages", "login"), { recursive: true });
-      await writeFile(
-        path.join(routeClientRoot, "package.json"),
-        JSON.stringify({ name: "mandu-route-client-import-test", type: "module" }, null, 2),
-        "utf-8",
-      );
-      await writeFile(
-        path.join(routeClientRoot, "app", "login", "page.tsx"),
-        'import LoginPage from "@/client/pages/login/LoginPage.client";\n' +
-          "export default function Page() {\n" +
-          "  return <LoginPage />;\n" +
-          "}\n",
-        "utf-8",
-      );
-      await writeFile(
-        path.join(routeClientRoot, "src", "client", "pages", "login", "LoginPage.client.tsx"),
-        '"use client";\n' +
-          'import { useState } from "react";\n' +
-          "export default function LoginPage() {\n" +
-          '  const [email, setEmail] = useState("");\n' +
-          '  return <form><input value={email} onChange={(event) => setEmail(event.currentTarget.value)} /></form>;\n' +
-          "}\n",
-        "utf-8",
-      );
-
-      const routeClientResult = await runBuildInSubprocess(routeClientRoot, "server-page-route-client-import");
-      expect(routeClientResult.success).toBe(true);
-      const bundlePath = path.join(routeClientRoot, ".mandu", "client", "login.island.js");
-      expect(await Bun.file(bundlePath).exists()).toBe(true);
-
-      const bundleSource = await readFile(bundlePath, "utf-8");
-      expect(bundleSource).not.toContain("var LoginPage = LoginPage;");
-      const parseResult = await Bun.build({
-        entrypoints: [bundlePath],
-        target: "browser",
-        external: ["react", "react-dom", "react-dom/client", "react/jsx-dev-runtime"],
-      });
-      expect(parseResult.success).toBe(true);
-    } finally {
-      await rm(routeClientRoot, { recursive: true, force: true });
+    try {
+      await mkdir(path.join(routeClientRoot, "app", "login"), { recursive: true });
+      await mkdir(path.join(routeClientRoot, "src", "client", "pages", "login"), { recursive: true });
+      await writeFile(
+        path.join(routeClientRoot, "package.json"),
+        JSON.stringify({ name: "mandu-route-client-import-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(routeClientRoot, "app", "login", "page.tsx"),
+        'import LoginPage from "@/client/pages/login/LoginPage.client";\n' +
+          "export default function Page() {\n" +
+          "  return <LoginPage />;\n" +
+          "}\n",
+        "utf-8",
+      );
+      await writeFile(
+        path.join(routeClientRoot, "src", "client", "pages", "login", "LoginPage.client.tsx"),
+        '"use client";\n' +
+          'import { useState } from "react";\n' +
+          "export default function LoginPage() {\n" +
+          '  const [email, setEmail] = useState("");\n' +
+          '  return <form><input value={email} onChange={(event) => setEmail(event.currentTarget.value)} /></form>;\n' +
+          "}\n",
+        "utf-8",
+      );
+
+      const routeClientResult = await runBuildInSubprocess(routeClientRoot, "server-page-route-client-import");
+      expect(routeClientResult.success).toBe(true);
+      const bundlePath = path.join(routeClientRoot, ".mandu", "client", "login.island.js");
+      expect(await Bun.file(bundlePath).exists()).toBe(true);
+
+      const bundleSource = await readFile(bundlePath, "utf-8");
+      expect(bundleSource).not.toContain("var LoginPage = LoginPage;");
+      const parseResult = await Bun.build({
+        entrypoints: [bundlePath],
+        target: "browser",
+        external: ["react", "react-dom", "react-dom/client", "react/jsx-dev-runtime"],
+      });
+      expect(parseResult.success).toBe(true);
+    } finally {
+      await rm(routeClientRoot, { recursive: true, force: true });
     }
   });
 
@@ -633,37 +637,37 @@ describe("buildClientBundles vendor shims", () => {
 
   test("fails when hydration is enabled but no clientModule can be resolved", async () => {
     const missingRoot = await mkRepoTempDir("hydration-no-client-");
-    try {
-      await mkdir(path.join(missingRoot, "app", "login"), { recursive: true });
-      await mkdir(path.join(missingRoot, "src", "client", "widgets", "login-form"), { recursive: true });
-      await writeFile(
-        path.join(missingRoot, "package.json"),
-        JSON.stringify({ name: "mandu-hydration-no-client-test", type: "module" }, null, 2),
-        "utf-8",
-      );
-      await writeFile(
-        path.join(missingRoot, "app", "login", "page.tsx"),
-        'import { LoginForm } from "../../src/client/widgets/login-form/LoginForm.client";\n' +
-          "export default function LoginPage() {\n" +
-          "  return <main><LoginForm /></main>;\n" +
-          "}\n",
-        "utf-8",
-      );
-      await writeFile(
-        path.join(missingRoot, "src", "client", "widgets", "login-form", "LoginForm.client.tsx"),
-        "export function LoginForm() { return <form />; }\n",
-        "utf-8",
-      );
-
-      const noClientResult = await runBuildInSubprocess(missingRoot, "hydration-no-client-module");
-      const errors = noClientResult.errors.join("\n");
-      expect(noClientResult.success).toBe(false);
-      expect(errors).toContain("no clientModule could be resolved");
-      expect(errors).toContain("LoginForm.client");
-      expect(errors).toContain("run mandu generate");
-    } finally {
-      await rm(missingRoot, { recursive: true, force: true });
-    }
+    try {
+      await mkdir(path.join(missingRoot, "app", "login"), { recursive: true });
+      await mkdir(path.join(missingRoot, "src", "client", "widgets", "login-form"), { recursive: true });
+      await writeFile(
+        path.join(missingRoot, "package.json"),
+        JSON.stringify({ name: "mandu-hydration-no-client-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(missingRoot, "app", "login", "page.tsx"),
+        'import { LoginForm } from "../../src/client/widgets/login-form/LoginForm.client";\n' +
+          "export default function LoginPage() {\n" +
+          "  return <main><LoginForm /></main>;\n" +
+          "}\n",
+        "utf-8",
+      );
+      await writeFile(
+        path.join(missingRoot, "src", "client", "widgets", "login-form", "LoginForm.client.tsx"),
+        "export function LoginForm() { return <form />; }\n",
+        "utf-8",
+      );
+
+      const noClientResult = await runBuildInSubprocess(missingRoot, "hydration-no-client-module");
+      const errors = noClientResult.errors.join("\n");
+      expect(noClientResult.success).toBe(false);
+      expect(errors).toContain("no clientModule could be resolved");
+      expect(errors).toContain("LoginForm.client");
+      expect(errors).toContain("run mandu generate");
+    } finally {
+      await rm(missingRoot, { recursive: true, force: true });
+    }
   });
 });
 

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/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.