@mandujs/core 0.54.17 → 0.54.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.17",
+  "version": "0.54.19",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -65,6 +65,7 @@
     "./i18n": "./src/i18n/index.ts",
     "./id": "./src/id/index.ts",
     "./internal": "./src/internal/index.ts",
+    "./internal/client-boundary": "./src/internal/client-boundary.ts",
     "./observability": "./src/observability/index.ts",
     "./openapi/generator": "./src/openapi/generator.ts",
     "./perf": "./src/perf/index.ts",
@@ -203,6 +204,7 @@
     "fast-glob": "^3.3.2",
     "glob": "^13.0.0",
     "minimatch": "^10.1.1",
+    "typescript": ">=6.0.0",
     "zod": "^3.23.8"
   }
 }

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

@@ -64,14 +64,35 @@ describe("agent context", () => {
     await writeFile(root, ".mandu/routes.manifest.json", JSON.stringify({
       version: 1,
       routes: [
-        {
-          id: "home",
-          pattern: "/",
-          kind: "page",
-          module: "app/page.tsx",
-          componentModule: "app/page.tsx",
-          layoutChain: [],
-        },
+        {
+          id: "home",
+          pattern: "/",
+          kind: "page",
+          module: "app/page.tsx",
+          componentModule: "app/page.tsx",
+          layoutChain: [],
+          hydration: { strategy: "island", priority: "visible", preload: false },
+          boundaries: [
+            {
+              id: "home--0",
+              routeId: "home",
+              module: "src/client/HomeWidget.client.tsx",
+              importSpecifier: "@/client/HomeWidget.client",
+              exportName: "HomeWidget",
+              localName: "HomeWidget",
+              hydrate: "visible",
+              ordinal: 0,
+              propsSource: "inline",
+              propsKeys: ["user"],
+              hasSpreadProps: false,
+              source: {
+                file: "app/page.tsx",
+                line: 5,
+                column: 12,
+              },
+            },
+          ],
+        },
         {
           id: "api-ping",
           pattern: "/api/ping",
@@ -102,10 +123,26 @@ describe("agent context", () => {
     expect(context.framework).toBe("mandu");
     expect(context.project.name).toBe("agent-app");
     expect(context.project.packageManager).toBe("bun@1.3.14");
-    expect(context.routeSource).toBe("manifest");
-    expect(context.routes).toHaveLength(2);
-    expect(context.pages.map((r) => r.id)).toEqual(["home"]);
-    expect(context.apis.map((r) => r.id)).toEqual(["api-ping"]);
+    expect(context.routeSource).toBe("manifest");
+    expect(context.routes).toHaveLength(2);
+    expect(context.pages.map((r) => r.id)).toEqual(["home"]);
+    expect(context.pages[0]?.boundaryCount).toBe(1);
+    expect(context.pages[0]?.boundaries?.[0]).toMatchObject({
+      id: "home--0",
+      module: "src/client/HomeWidget.client.tsx",
+      importSpecifier: "@/client/HomeWidget.client",
+      exportName: "HomeWidget",
+      localName: "HomeWidget",
+      ordinal: 0,
+      hydrate: "visible",
+      propsKeys: ["user"],
+      source: {
+        file: "app/page.tsx",
+        line: 5,
+        column: 12,
+      },
+    });
+    expect(context.apis.map((r) => r.id)).toEqual(["api-ping"]);
     expect(context.apis[0]?.hasContractModule).toBe(true);
     expect(context.partials.map((p) => p.path)).toEqual(["app/dashboard/counter.partial.tsx"]);
     expect(context.islands.map((p) => p.path)).toEqual(["app/dashboard/chart.island.tsx"]);
@@ -125,10 +162,11 @@ describe("agent context", () => {
 
     expect(result.path).toBe(agentManifestPath(root));
     const manifest = await readAgentManifest(root);
-    expect(manifest?.schemaVersion).toBe(1);
-    expect(manifest?.project.name).toBe("agent-app");
-    expect(manifest?.agentWorkflow.canonical).toEqual(["context", "plan", "apply", "verify", "repair"]);
-  });
+    expect(manifest?.schemaVersion).toBe(1);
+    expect(manifest?.project.name).toBe("agent-app");
+    expect(manifest?.routes[0]?.boundaries?.[0]?.id).toBe("home--0");
+    expect(manifest?.agentWorkflow.canonical).toEqual(["context", "plan", "apply", "verify", "repair"]);
+  });
 
   it("builds a deterministic agent plan from intent", () => {
     const plan = buildAgentPlan({
@@ -202,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"]);
@@ -226,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/context.ts

@@ -119,6 +119,7 @@ function summarizeRoute(route: RouteSpec | {
   methods?: string[];
   hydration?: { strategy?: string; priority?: string };
   clientModule?: string;
+  boundaries?: RouteSpec["boundaries"];
   contractModule?: string;
   layoutChain?: string[];
   metadataKind?: string;
@@ -127,6 +128,21 @@ function summarizeRoute(route: RouteSpec | {
     "metadataKind" in route && typeof route.metadataKind === "string"
       ? route.metadataKind
       : undefined;
+  const boundaries = Array.isArray(route.boundaries)
+    ? route.boundaries.map((boundary) => ({
+        id: boundary.id,
+        module: boundary.module,
+        ...(boundary.importSpecifier ? { importSpecifier: boundary.importSpecifier } : {}),
+        exportName: boundary.exportName,
+        localName: boundary.localName,
+        ordinal: boundary.ordinal,
+        hydrate: boundary.hydrate,
+        propsSource: boundary.propsSource,
+        propsKeys: boundary.propsKeys ?? [],
+        hasSpreadProps: !!boundary.hasSpreadProps,
+        source: boundary.source,
+      }))
+    : [];
   return {
     id: route.id,
     pattern: route.pattern,
@@ -144,6 +160,7 @@ function summarizeRoute(route: RouteSpec | {
     hasClientModule: typeof route.clientModule === "string" && route.clientModule.length > 0,
     hasContractModule:
       typeof route.contractModule === "string" && route.contractModule.length > 0,
+    ...(boundaries.length > 0 ? { boundaryCount: boundaries.length, boundaries } : {}),
     layoutDepth: Array.isArray(route.layoutChain) ? route.layoutChain.length : 0,
     ...(metadataKind ? { metadataKind } : {}),
   };

package/src/agent/types.ts

@@ -32,23 +32,43 @@ export interface AgentProjectSummary {
   configFile: string | null;
 }
 
-export interface AgentRouteSummary {
-  id: string;
-  pattern: string;
-  kind: "page" | "api" | "metadata" | string;
+export interface AgentRouteSummary {
+  id: string;
+  pattern: string;
+  kind: "page" | "api" | "metadata" | string;
   module: string;
   methods?: string[];
   hydration?: {
     strategy?: string;
     priority?: string;
-  };
-  hasClientModule: boolean;
-  hasContractModule: boolean;
-  layoutDepth: number;
-  metadataKind?: string;
-}
-
-export interface AgentArtifactSummary {
+  };
+  hasClientModule: boolean;
+  hasContractModule: boolean;
+  boundaryCount?: number;
+  boundaries?: AgentRouteBoundarySummary[];
+  layoutDepth: number;
+  metadataKind?: string;
+}
+
+export interface AgentRouteBoundarySummary {
+  id: string;
+  module: string;
+  importSpecifier?: string;
+  exportName: string;
+  localName: string;
+  ordinal: number;
+  hydrate: string;
+  propsSource: string;
+  propsKeys: string[];
+  hasSpreadProps: boolean;
+  source: {
+    file: string;
+    line: number;
+    column: number;
+  };
+}
+
+export interface AgentArtifactSummary {
   path: string;
   kind: "partial" | "island" | "slot" | "contract";
 }

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/__snapshots__/build.test.ts.snap

@@ -0,0 +1,5 @@
+{
+  "snapshots": {
+    "client boundary manifest metadata": "{\n  \"bundleBoundaries\": {\n    \"boundary-demo--0\": {\n      \"exportName\": \"BoundaryWidget\",\n      \"hydrate\": \"visible\",\n      \"js\": \"/.mandu/client/boundary-demo--0.boundary.js\",\n      \"module\": \"src/client/BoundaryWidget.client.tsx\",\n      \"priority\": \"visible\",\n      \"route\": \"boundary-demo\"\n    }\n  },\n  \"routes\": [\n    {\n      \"boundaries\": [\n        {\n          \"exportName\": \"BoundaryWidget\",\n          \"hasSpreadProps\": false,\n          \"hydrate\": \"visible\",\n          \"id\": \"boundary-demo--0\",\n          \"importSpecifier\": \"@/client/BoundaryWidget.client\",\n          \"localName\": \"BoundaryWidget\",\n          \"module\": \"src/client/BoundaryWidget.client.tsx\",\n          \"ordinal\": 0,\n          \"propsKeys\": [\n            \"label\"\n          ],\n          \"propsSource\": \"inline\",\n          \"routeId\": \"boundary-demo\",\n          \"source\": {\n            \"column\": 12,\n            \"file\": \"app/boundary/page.tsx\",\n            \"line\": 5\n          }\n        }\n      ],\n      \"componentModule\": \"app/boundary/page.tsx\",\n      \"id\": \"boundary-demo\",\n      \"module\": \"app/boundary/page.tsx\"\n    }\n  ]\n}\n"
+  }
+}

package/src/bundler/__tests__/build-runner.ts

@@ -51,8 +51,11 @@
  * clean tmpdir with no prior `.mandu/vendor-cache/`.
  */
 
-import { buildClientBundles } from "../build";
-import type { RoutesManifest } from "../../spec/schema";
+import { buildClientBundles } from "../build";
+import type { RoutesManifest } from "../../spec/schema";
+import { mkdir } from "fs/promises";
+import path from "path";
+import { generateManifest } from "../../router/fs-routes";
 
 const rootDir = process.argv[2];
 if (!rootDir) {
@@ -61,7 +64,9 @@ if (!rootDir) {
 }
 const mode = process.argv[3] ?? "default";
 
-const manifest: RoutesManifest = mode === "server-page-client-module"
+const manifest: RoutesManifest = mode === "client-boundary-generated-transitive"
+  ? (await generateManifest(rootDir)).manifest
+  : mode === "server-page-client-module"
   ? {
       version: 1,
       routes: [
@@ -118,6 +123,83 @@ const manifest: RoutesManifest = mode === "server-page-client-module"
           },
         ],
       }
+  : mode === "client-boundary"
+    || mode === "client-boundary-target"
+    || mode === "client-boundary-skip-framework"
+    || mode === "client-boundary-duplicate-id"
+    ? {
+        version: 1,
+        routes: [
+          {
+            id: "boundary-demo",
+            kind: "page",
+            pattern: "/boundary",
+            module: "app/boundary/page.tsx",
+            componentModule: "app/boundary/page.tsx",
+            hydration: {
+              strategy: "island",
+              priority: "visible",
+              preload: false,
+            },
+            boundaries: [
+              {
+                id: "boundary-demo--0",
+                routeId: "boundary-demo",
+                module: "src/client/BoundaryWidget.client.tsx",
+                importSpecifier: "@/client/BoundaryWidget.client",
+                exportName: "BoundaryWidget",
+                localName: "BoundaryWidget",
+                hydrate: "visible",
+                ordinal: 0,
+                propsSource: "inline",
+                propsKeys: ["label"],
+                hasSpreadProps: false,
+                source: {
+                  file: "app/boundary/page.tsx",
+                  line: 5,
+                  column: 12,
+                },
+              },
+            ],
+          },
+          ...(mode === "client-boundary-duplicate-id"
+            ? [
+                {
+                  id: "boundary-copy",
+                  kind: "page" as const,
+                  pattern: "/boundary-copy",
+                  module: "app/boundary/page.tsx",
+                  componentModule: "app/boundary/page.tsx",
+                  hydration: {
+                    strategy: "island" as const,
+                    priority: "visible" as const,
+                    preload: false,
+                  },
+                  boundaries: [
+                    {
+                      id: "boundary-demo--0",
+                      routeId: "boundary-copy",
+                      module: "src/client/BoundaryWidget.client.tsx",
+                      importSpecifier: "@/client/BoundaryWidget.client",
+                      exportName: "BoundaryWidget",
+                      localName: "BoundaryWidget",
+                      hydrate: "visible" as const,
+                      ordinal: 0,
+                      propsSource: "inline" as const,
+                      propsKeys: ["label"],
+                      hasSpreadProps: false,
+                      source: {
+                        file: "app/boundary/page.tsx",
+                        line: 8,
+                        column: 12,
+                      },
+                    },
+                  ],
+                },
+              ]
+            : []),
+        ],
+      }
   : mode === "i18n-locale-route-id"
     ? {
         version: 1,
@@ -156,27 +238,58 @@ const manifest: RoutesManifest = mode === "server-page-client-module"
         ],
       };
 
-try {
-  const result = await buildClientBundles(manifest, rootDir, {
-    minify: false,
-    sourcemap: false,
-    splitting: false,
-  });
+try {
+  if (mode === "client-boundary-target" || mode === "client-boundary-skip-framework") {
+    await mkdir(path.join(rootDir, ".mandu"), { recursive: true });
+    await Bun.write(
+      path.join(rootDir, ".mandu", "manifest.json"),
+      JSON.stringify(
+        {
+          version: 1,
+          buildTime: "2026-05-23T00:00:00.000Z",
+          env: "development",
+          bundles: {},
+          shared: {
+            runtime: "/.mandu/client/_runtime.js",
+            vendor: "/.mandu/client/_react.js",
+            router: "/.mandu/client/_router.js",
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  }
+
+  const result = await buildClientBundles(manifest, rootDir, {
+    minify: false,
+    sourcemap: false,
+    splitting: false,
+    ...(mode === "client-boundary-target" ? { targetRouteIds: ["boundary-demo"] } : {}),
+    ...(mode === "client-boundary-skip-framework" ? { skipFrameworkBundles: true } : {}),
+  });
   process.stdout.write(
     JSON.stringify({
-      success: result.success,
-      errors: result.errors,
-      manifest: {
-        shared: {
+      success: result.success,
+      errors: result.errors,
+      manifest: {
+        routes: manifest.routes.map((route) => ({
+          id: route.id,
+          module: route.module,
+          componentModule: route.componentModule,
+          boundaries: route.kind === "page" ? route.boundaries ?? [] : [],
+        })),
+        shared: {
           runtime: result.manifest.shared?.runtime ?? null,
           vendor: result.manifest.shared?.vendor ?? null,
           router: result.manifest.shared?.router ?? null,
           fastRefresh: result.manifest.shared?.fastRefresh ?? null,
         },
-        bundles: result.manifest.bundles ?? {},
-      },
-    }) + "\n",
-  );
+        bundles: result.manifest.bundles ?? {},
+        boundaries: result.manifest.boundaries ?? {},
+      },
+    }) + "\n",
+  );
   process.exit(result.success ? 0 : 1);
 } catch (err) {
   process.stdout.write(