@mandujs/core 0.54.18 → 0.54.19

package/package.json

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

package/src/agent/__tests__/context.test.ts

@@ -240,9 +240,9 @@ describe("agent context", () => {
     expect(parsed.project.name).toBe("agent-app");
   });
 
-  it("records changed file reasons and warns on internal API edits", async () => {
-    const version = await runGit(root, ["--version"]);
-    if (!version.ok) return;
+  it("records changed file reasons and warns on internal API edits", async () => {
+    const version = await runGit(root, ["--version"]);
+    if (!version.ok) return;
 
     expect((await runGit(root, ["init"])).ok).toBe(true);
     await runGit(root, ["config", "user.email", "agent@example.com"]);
@@ -264,12 +264,43 @@ describe("agent context", () => {
     expect(reason?.internalApi).toBe(true);
     expect(reason?.recommendedChecks).toContain("bun run check:public-api && bun run check:target-boundaries");
     expect(report.diagnostics.some((diag) => diag.code === "MANDU_VERIFY_INTERNAL_API_EDIT")).toBe(true);
-    expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain(
-      "bun run check:public-api && bun run check:target-boundaries",
-    );
-  });
-
-  it("turns a verify report into repair actions", async () => {
+    expect(report.suggestedCommands.map((cmd) => cmd.command)).toContain(
+      "bun run check:public-api && bun run check:target-boundaries",
+    );
+  });
+
+  it("recommends hydration gates for hydration-sensitive runtime edits", async () => {
+    const version = await runGit(root, ["--version"]);
+    if (!version.ok) return;
+
+    expect((await runGit(root, ["init"])).ok).toBe(true);
+    await runGit(root, ["config", "user.email", "agent@example.com"]);
+    await runGit(root, ["config", "user.name", "Agent"]);
+    expect((await runGit(root, ["add", "."])).ok).toBe(true);
+    expect((await runGit(root, ["commit", "-m", "initial"])).ok).toBe(true);
+
+    await writeFile(root, "packages/core/src/bundler/build.ts", "export const changed = true;\n");
+
+    const report = await buildAgentVerifyReport(root, {
+      includeDiagnose: false,
+      includeGuard: false,
+      includeContract: false,
+    });
+
+    const reason = report.changedFileReasons.find(
+      (entry) => entry.file === "packages/core/src/bundler/build.ts",
+    );
+    expect(reason?.recommendedChecks).toContain("bun run test:hydration-boundary");
+    expect(reason?.recommendedChecks).toContain("bun run test:hydration-e2e");
+    expect(reason?.recommendedChecks).toContain("bun run check:publish");
+
+    const suggestedCommands = report.suggestedCommands.map((cmd) => cmd.command);
+    expect(suggestedCommands).toContain("bun run test:hydration-boundary");
+    expect(suggestedCommands).toContain("bun run test:hydration-e2e");
+    expect(suggestedCommands).toContain("bun run check:publish");
+  });
+
+  it("turns a verify report into repair actions", async () => {
     await writeAgentVerifyReport(root, {
       schemaVersion: 1,
       framework: "mandu",

package/src/agent/verify.ts

@@ -245,12 +245,17 @@ function commandSuggestions(
   if (files.some((file) => file.startsWith("packages/mcp/"))) {
     add("bun test packages/mcp/tests", "MCP package files changed.", true);
   }
-  if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
-    add("bun run check:publish", "Package metadata or lockfile changed.", true);
-  }
-  if (changedFileReasons.some((entry) => entry.internalApi)) {
-    add("bun run check:public-api && bun run check:target-boundaries", "Internal framework boundaries changed.", true);
-  }
+  if (files.some((file) => file.includes("package.json") || file === "bun.lock")) {
+    add("bun run check:publish", "Package metadata or lockfile changed.", true);
+  }
+  if (files.some(isHydrationSensitiveEdit)) {
+    add("bun run test:hydration-boundary", "Hydration-sensitive runtime/router/bundler files changed.", true);
+    add("bun run test:hydration-e2e", "Hydration-sensitive changes need browser-level validation.", true);
+    add("bun run check:publish", "Pre-publish hydration gates should pass before release.", true);
+  }
+  if (changedFileReasons.some((entry) => entry.internalApi)) {
+    add("bun run check:public-api && bun run check:target-boundaries", "Internal framework boundaries changed.", true);
+  }
   if (diagnostics.some((d) => d.severity === "error" || d.severity === "fatal")) {
     add("mandu agent repair --from .mandu/agent-verify.json", "Verification produced repairable diagnostics.", false);
   }
@@ -258,22 +263,40 @@ function commandSuggestions(
   return out;
 }
 
-function isInternalApiEdit(file: string): boolean {
-  return [
-    "packages/core/src/runtime/",
-    "packages/core/src/bundler/",
+function isInternalApiEdit(file: string): boolean {
+  return [
+    "packages/core/src/runtime/",
+    "packages/core/src/bundler/",
     "packages/core/src/server/",
     "packages/core/src/guard/",
     "packages/core/src/spec/",
     "packages/core/src/router/",
     "packages/core/src/internal/",
-  ].some((prefix) => file.startsWith(prefix));
-}
-
-function changedFileReason(file: string): AgentChangedFileReason {
-  const normalized = normalizePath(file) ?? file;
-  const reasons: string[] = [];
-  const recommendedChecks: string[] = [];
+  ].some((prefix) => file.startsWith(prefix));
+}
+
+function isHydrationSensitiveEdit(file: string): boolean {
+  return [
+    "packages/core/src/runtime/page-render-response.ts",
+    "packages/core/src/runtime/server.ts",
+    "packages/core/src/runtime/ssr.ts",
+    "packages/core/src/runtime/streaming-ssr.ts",
+    "packages/core/src/internal/client-boundary.ts",
+    "packages/core/src/bundler/build.ts",
+    "packages/core/src/bundler/client-boundary-transform.ts",
+    "packages/core/src/router/client-entry.ts",
+    "packages/core/src/router/fs-routes.ts",
+    "packages/core/src/router/fs-scanner.ts",
+    "packages/core/src/client/serialize.ts",
+    "packages/core/src/client/props-serialization.ts",
+    "packages/core/src/client/runtime-entry.ts",
+  ].includes(file);
+}
+
+function changedFileReason(file: string): AgentChangedFileReason {
+  const normalized = normalizePath(file) ?? file;
+  const reasons: string[] = [];
+  const recommendedChecks: string[] = [];
 
   if (/\.(ts|tsx|js|jsx)$/.test(normalized)) {
     reasons.push("Source code changed.");
@@ -295,13 +318,21 @@ function changedFileReason(file: string): AgentChangedFileReason {
     reasons.push("User-facing documentation changed.");
     recommendedChecks.push("bun run check:docs-drift");
   }
-  if (normalized === "package.json" || normalized === "bun.lock" || normalized.endsWith("/package.json")) {
-    reasons.push("Package metadata or dependency graph changed.");
-    recommendedChecks.push("bun run check:publish");
-  }
-
-  const internalApi = isInternalApiEdit(normalized);
-  if (internalApi) {
+  if (normalized === "package.json" || normalized === "bun.lock" || normalized.endsWith("/package.json")) {
+    reasons.push("Package metadata or dependency graph changed.");
+    recommendedChecks.push("bun run check:publish");
+  }
+  if (isHydrationSensitiveEdit(normalized)) {
+    reasons.push("Hydration/runtime/client boundary behavior changed.");
+    recommendedChecks.push(
+      "bun run test:hydration-boundary",
+      "bun run test:hydration-e2e",
+      "bun run check:publish",
+    );
+  }
+
+  const internalApi = isInternalApiEdit(normalized);
+  if (internalApi) {
     reasons.push("Framework internal API changed.");
     recommendedChecks.push("bun run check:public-api && bun run check:target-boundaries");
   }

package/src/bundler/build.test.ts

@@ -29,11 +29,11 @@ async function evaluateGeneratedHydrationRuntime(): Promise<{ hydrateIslands: ()
   const runtimeSource = await readFile(await Bun.file(sourcePath).exists() ? sourcePath : bundledPath, "utf-8");
   const instrumented = runtimeSource
     .replace(
-      /import\s+React,\s*\{\s*useState,\s*useEffect,\s*Component\s*\}\s+from\s+['"]react['"];?/,
+      /import\s+React,\s*\{[^}]*\}\s+from\s+['"]react['"];?/,
       "const React = globalThis.__MANDU_TEST_REACT__; const { useState, useEffect, Component } = React;",
     )
     .replace(
-      /import\s+\{\s*hydrateRoot,\s*createRoot\s*\}\s+from\s+['"]react-dom\/client['"];?/,
+      /import\s+\{[^}]*\}\s+from\s+['"]react-dom\/client['"];?/,
       "const { hydrateRoot, createRoot } = globalThis.__MANDU_TEST_REACT_DOM_CLIENT__;",
     )
     .replace(
@@ -308,7 +308,7 @@ describe("buildClientBundles vendor shims", () => {
     expect(runtimeSource).toContain("data-mandu-props");
     expect(runtimeSource).toContain("Missing boundary-local props for transformed client boundary");
     expect(runtimeSource).toContain("warnedBoundaryPropFallbacks");
-    expect(runtimeSource).toContain("deserializeManduProps");
+    expect(runtimeSource).toContain("deserializeProps");
     expect(runtimeSource).toContain("new Date");
     expect(runtimeSource).toContain("new Map");
   });
@@ -437,6 +437,43 @@ describe("buildClientBundles vendor shims", () => {
     );
   });
 
+  test("runtime falls back to route-level server data when boundary-local props are absent", async () => {
+    const modulePath = path.join(rootDir, ".mandu", "client", "runtime-route-data-fallback.js");
+    await writeFile(
+      modulePath,
+      `
+        export default function RouteFallbackBoundary(props) {
+          globalThis.__MANDU_TEST_ROUTE_DATA_FALLBACK_PROPS__ = props;
+          return null;
+        }
+      `,
+      "utf-8",
+    );
+    Object.assign(globalThis, {
+      __MANDU_TEST_ROUTE_DATA_FALLBACK_PROPS__: undefined,
+    });
+    document.body.innerHTML = `
+      <div
+        data-mandu-island="route-fallback--0"
+        data-mandu-boundary-id="route-fallback--0"
+        data-mandu-route-id="route-fallback"
+        data-mandu-src="${pathToFileURL(modulePath).href}?t=${Date.now()}"
+        data-hydrate="load"
+      ></div>
+    `;
+    (window as typeof window & { __MANDU_DATA__?: unknown; __MANDU_ROOTS__?: Map<string, unknown> }).__MANDU_DATA__ = {
+      "route-fallback": { serverData: { label: "route-level" } },
+    };
+    (window as typeof window & { __MANDU_ROOTS__?: Map<string, unknown> }).__MANDU_ROOTS__ = new Map();
+
+    const runtime = await evaluateGeneratedHydrationRuntime();
+    runtime.hydrateIslands();
+
+    await waitForRuntimeAssertion(() =>
+      (globalThis as typeof globalThis & { __MANDU_TEST_ROUTE_DATA_FALLBACK_PROPS__?: { label?: string } }).__MANDU_TEST_ROUTE_DATA_FALLBACK_PROPS__?.label === "route-level"
+    );
+  });
+
   test("does not bundle a server page when stale manifest marks page.tsx as clientModule", async () => {
     const staleRoot = await mkRepoTempDir("stale-client-module-");
     try {