@mandujs/core 0.54.17 → 0.54.19

package/src/diagnose/checks.ts

@@ -767,7 +767,7 @@ async function listMandujsSiblings(rootDir: string): Promise<string[]> {
  * version to the hoisted core. A mismatch is reported as `error`
  * (boot-breaking on the user's machine) with a copy-pastable fix.
  */
-export async function checkNestedInternalCore(rootDir: string): Promise<DiagnoseCheckResult> {
+export async function checkNestedInternalCore(rootDir: string): Promise<DiagnoseCheckResult> {
   const hoistedPath = path.join(rootDir, "node_modules", "@mandujs", "core", "package.json");
   const hoistedVersion = await readPackageVersion(hoistedPath);
 
@@ -828,5 +828,186 @@ export async function checkNestedInternalCore(rootDir: string): Promise<Diagnose
       mismatchCount: mismatches.length,
       mismatches,
     },
-  };
-}
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// 8. client_boundary_manifests (F42/F45)
+// ────────────────────────────────────────────────────────────────────────
+
+interface DiagnoseRouteBoundary {
+  id?: unknown;
+  routeId?: unknown;
+  module?: unknown;
+  exportName?: unknown;
+  source?: unknown;
+}
+
+interface DiagnoseRouteRecord {
+  id?: unknown;
+  boundaries?: unknown;
+}
+
+async function readJsonObject(filePath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function toRouteRecords(value: unknown): DiagnoseRouteRecord[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is DiagnoseRouteRecord =>
+    !!entry && typeof entry === "object" && !Array.isArray(entry)
+  );
+}
+
+function toRouteBoundaries(route: DiagnoseRouteRecord): DiagnoseRouteBoundary[] {
+  if (!Array.isArray(route.boundaries)) return [];
+  return route.boundaries.filter((entry): entry is DiagnoseRouteBoundary =>
+    !!entry && typeof entry === "object" && !Array.isArray(entry)
+  );
+}
+
+function bundleAssetExists(rootDir: string, jsPath: unknown): Promise<boolean> {
+  if (typeof jsPath !== "string" || jsPath.length === 0) return Promise.resolve(false);
+  const relativePath = jsPath.startsWith("/")
+    ? jsPath.slice(1)
+    : jsPath;
+  return fs.access(path.join(rootDir, relativePath)).then(
+    () => true,
+    () => false,
+  );
+}
+
+/**
+ * F42/F45 check: validate compiler-owned client boundary records.
+ *
+ * This does not rebuild the app. It inspects generated route and bundle
+ * manifests and reports:
+ *   - duplicate boundary ids in `.mandu/routes.manifest.json`
+ *   - malformed boundary records missing id/module/exportName
+ *   - missing boundary bundle entries in `.mandu/manifest.json`
+ *   - boundary bundle entries whose JS asset is absent on disk
+ */
+export async function checkClientBoundaryManifests(rootDir: string): Promise<DiagnoseCheckResult> {
+  const routesManifestPath = path.join(rootDir, ".mandu", "routes.manifest.json");
+  const routesManifest = await readJsonObject(routesManifestPath);
+
+  if (!routesManifest) {
+    return {
+      ok: true,
+      rule: "client_boundary_manifests",
+      message: "Routes manifest is missing or unreadable — boundary manifest check skipped.",
+      details: { skipped: true, routesManifestPath: path.relative(rootDir, routesManifestPath) },
+    };
+  }
+
+  const boundaries: Array<{ routeId: string; id: string; module: string; exportName: string }> = [];
+  const malformed: Array<{ routeId: string; reason: string }> = [];
+  const seen = new Map<string, string>();
+  const duplicates: Array<{ id: string; firstRouteId: string; duplicateRouteId: string }> = [];
+
+  for (const route of toRouteRecords(routesManifest.routes)) {
+    const routeId = typeof route.id === "string" ? route.id : "(unknown-route)";
+    for (const boundary of toRouteBoundaries(route)) {
+      const id = typeof boundary.id === "string" ? boundary.id : "";
+      const module = typeof boundary.module === "string" ? boundary.module : "";
+      const exportName = typeof boundary.exportName === "string" ? boundary.exportName : "";
+      if (!id || !module || !exportName) {
+        malformed.push({ routeId, reason: "Boundary record must include id, module, and exportName." });
+        continue;
+      }
+
+      const firstRouteId = seen.get(id);
+      if (firstRouteId) {
+        duplicates.push({ id, firstRouteId, duplicateRouteId: routeId });
+      } else {
+        seen.set(id, routeId);
+      }
+      boundaries.push({ routeId, id, module, exportName });
+    }
+  }
+
+  if (malformed.length > 0 || duplicates.length > 0) {
+    return {
+      ok: false,
+      rule: "client_boundary_manifests",
+      severity: "error",
+      message: `Client boundary route manifest has ${malformed.length} malformed record(s) and ${duplicates.length} duplicate id(s).`,
+      suggestion: "Regenerate routes with `mandu generate` or rerun the build; boundary ids must be unique and include id/module/exportName.",
+      details: {
+        boundaryCount: boundaries.length,
+        malformed: malformed.slice(0, 10),
+        duplicates: duplicates.slice(0, 10),
+      },
+    };
+  }
+
+  if (boundaries.length === 0) {
+    return {
+      ok: true,
+      rule: "client_boundary_manifests",
+      message: "No compiler-owned client boundaries recorded in the routes manifest.",
+      details: { boundaryCount: 0 },
+    };
+  }
+
+  const bundleManifestPath = path.join(rootDir, ".mandu", "manifest.json");
+  const bundleManifest = await readJsonObject(bundleManifestPath);
+  if (!bundleManifest) {
+    return {
+      ok: false,
+      rule: "client_boundary_manifests",
+      severity: "error",
+      message: `Routes manifest declares ${boundaries.length} client boundary record(s), but bundle manifest is missing.`,
+      suggestion: "Run `mandu build` before deploy so boundary bundles are emitted and can be checked.",
+      details: { boundaryCount: boundaries.length, bundleManifestPath: path.relative(rootDir, bundleManifestPath) },
+    };
+  }
+
+  const bundleBoundaries = bundleManifest.boundaries && typeof bundleManifest.boundaries === "object" && !Array.isArray(bundleManifest.boundaries)
+    ? bundleManifest.boundaries as Record<string, unknown>
+    : {};
+  const missingEntries: string[] = [];
+  const missingAssets: string[] = [];
+
+  for (const boundary of boundaries) {
+    const entry = bundleBoundaries[boundary.id];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      missingEntries.push(boundary.id);
+      continue;
+    }
+    const jsPath = (entry as { js?: unknown }).js;
+    if (!(await bundleAssetExists(rootDir, jsPath))) {
+      missingAssets.push(boundary.id);
+    }
+  }
+
+  if (missingEntries.length > 0 || missingAssets.length > 0) {
+    return {
+      ok: false,
+      rule: "client_boundary_manifests",
+      severity: "error",
+      message: `Client boundary bundle manifest is incomplete: ${missingEntries.length} missing entr${missingEntries.length === 1 ? "y" : "ies"}, ${missingAssets.length} missing asset(s).`,
+      suggestion: "Run `mandu clean && mandu build`; if the issue persists, inspect `mandu.route.boundaries` with `includeBundle: true`.",
+      details: {
+        boundaryCount: boundaries.length,
+        missingEntries: missingEntries.slice(0, 10),
+        missingAssets: missingAssets.slice(0, 10),
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    rule: "client_boundary_manifests",
+    message: `Client boundary manifests are consistent for ${boundaries.length} boundary record(s).`,
+    details: { boundaryCount: boundaries.length },
+  };
+}

package/src/diagnose/run.ts

@@ -11,10 +11,11 @@ import {
   checkPrerenderPollution,
   checkCloneElementWarnings,
   checkDevArtifactsInProd,
-  checkPackageExportGaps,
-  checkNestedInternalCore,
-  checkA11yHints,
-} from "./checks";
+  checkPackageExportGaps,
+  checkNestedInternalCore,
+  checkA11yHints,
+  checkClientBoundaryManifests,
+} from "./checks";
 
 /**
  * Registered extended checks (Issue #215 + Phase 18.χ).
@@ -30,10 +31,11 @@ export const EXTENDED_CHECKS = [
   { name: "prerender_pollution", run: checkPrerenderPollution },
   { name: "cloneelement_warnings", run: checkCloneElementWarnings },
   { name: "dev_artifacts_in_prod", run: checkDevArtifactsInProd },
-  { name: "package_export_gaps", run: checkPackageExportGaps },
-  { name: "nested_internal_core", run: checkNestedInternalCore },
-  { name: "a11y_hints", run: checkA11yHints },
-] as const;
+  { name: "package_export_gaps", run: checkPackageExportGaps },
+  { name: "nested_internal_core", run: checkNestedInternalCore },
+  { name: "client_boundary_manifests", run: checkClientBoundaryManifests },
+  { name: "a11y_hints", run: checkA11yHints },
+] as const;
 
 /**
  * Run every extended check in parallel and return the aggregate report.

package/src/generator/templates.test.ts

@@ -20,7 +20,7 @@ describe("generatePageComponent", () => {
     expect(() => generatePageComponent(route)).toThrow("no clientModule");
   });
 
-  test("imports the real page module for static routes instead of emitting a placeholder", () => {
+  test("imports the real page module for static routes instead of emitting a placeholder", () => {
     const route: RouteSpec = {
       id: "about",
       kind: "page",
@@ -35,10 +35,53 @@ describe("generatePageComponent", () => {
     expect(generated).toContain('import pageModule from "../../../../app/about/page.tsx"');
     expect(generated).toContain("React.createElement(pageModule");
     expect(generated).not.toContain("About Page");
-    expect(generated).not.toContain('React.createElement("p", null, "Route ID: about")');
-  });
-
-  test("renders route-level default-imported client components through the page module", () => {
+    expect(generated).not.toContain('React.createElement("p", null, "Route ID: about")');
+  });
+
+  test("imports the real page module for compiler-owned boundary routes without a clientModule", () => {
+    const route: RouteSpec = {
+      id: "login",
+      kind: "page",
+      pattern: "/login",
+      module: "app/login/page.tsx",
+      componentModule: "app/login/page.tsx",
+      hydration: {
+        strategy: "island",
+        priority: "visible",
+        preload: false,
+      },
+      boundaries: [
+        {
+          id: "login--0",
+          routeId: "login",
+          module: "src/client/pages/login/LoginPage.client.tsx",
+          importSpecifier: "@/client/pages/login/LoginPage.client",
+          exportName: "default",
+          localName: "LoginPage",
+          hydrate: "visible",
+          ordinal: 0,
+          propsSource: "inline",
+          propsKeys: [],
+          hasSpreadProps: false,
+          source: {
+            file: "app/login/page.tsx",
+            line: 6,
+            column: 10,
+          },
+        },
+      ],
+    };
+
+    const generated = generatePageComponent(route);
+
+    expect(generated).toContain("Page Module: app/login/page.tsx");
+    expect(generated).toContain('import pageModule from "../../../../app/login/page.tsx"');
+    expect(generated).toContain("React.createElement(pageModule");
+    expect(generated).not.toContain("Client Module:");
+    expect(generated).not.toContain("Login Page");
+  });
+
+  test("renders route-level default-imported client components through the page module", () => {
     const route: RouteSpec = {
       id: "login",
       kind: "page",

package/src/generator/templates.ts

@@ -244,7 +244,9 @@ export function generatePageComponent(route: RouteSpec): string {
     return generatePageComponentWithIsland(route);
   }
 
-  if (needsHydration(route)) {
+  const hasCompilerOwnedBoundaries = (route.boundaries?.length ?? 0) > 0;
+
+  if (needsHydration(route) && !hasCompilerOwnedBoundaries) {
     throw new Error(
       `[${route.id}] Route has hydration strategy "${route.hydration?.strategy}" but no clientModule. ` +
       "Refusing to generate a placeholder page because it would disagree with runtime hydration state.",
@@ -260,6 +262,13 @@ export function generatePageComponent(route: RouteSpec): string {
     return generatePageComponentFromModule(route);
   }
 
+  if (needsHydration(route)) {
+    throw new Error(
+      `[${route.id}] Route has hydration strategy "${route.hydration?.strategy}" and compiler-owned boundaries, ` +
+      "but no componentModule. Refusing to generate a placeholder page because it would disagree with runtime hydration state.",
+    );
+  }
+
   const pageName = toPascalCase(route.id);
 
   // Legacy fallback for malformed historical manifests that lack componentModule.

package/src/internal/client-boundary.ts

@@ -0,0 +1,266 @@
+import React from "react";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import type { BundleManifest } from "../bundler/types";
+import { serializeProps } from "../client/serialize";
+import { escapeJsonForInlineScript } from "../runtime/escape";
+
+export interface ManduClientBoundaryProps {
+  routeId: string;
+  boundaryId: string;
+  module: string;
+  exportName: string;
+  props?: Record<string, unknown>;
+  hydrate?: string;
+  src?: string;
+}
+
+interface BoundaryRenderContext {
+  routeId?: string;
+  bundleManifest?: BundleManifest;
+  instanceCounts: Map<string, number>;
+}
+
+export interface ManduClientBoundaryRenderScope {
+  <T>(render: () => T): T;
+  wrapElement(element: React.ReactElement): React.ReactElement;
+}
+
+const boundaryContextStack: BoundaryRenderContext[] = [];
+const boundaryAsyncStorage = new AsyncLocalStorage<BoundaryRenderContext>();
+const BoundaryReactContext = React.createContext<BoundaryRenderContext | undefined>(undefined);
+
+export function createManduClientBoundaryRenderScope(
+  routeId: string | undefined,
+  bundleManifest: BundleManifest | undefined,
+): ManduClientBoundaryRenderScope {
+  const context: BoundaryRenderContext = { routeId, bundleManifest, instanceCounts: new Map() };
+  const scope = (<T>(render: () => T): T => runWithBoundaryContext(context, render)) as ManduClientBoundaryRenderScope;
+  scope.wrapElement = (element: React.ReactElement): React.ReactElement =>
+    React.createElement(BoundaryReactContext.Provider, { value: context }, element);
+  return scope;
+}
+
+export function renderWithManduClientBoundaryManifest<T>(
+  routeId: string | undefined,
+  bundleManifest: BundleManifest | undefined,
+  render: () => T,
+): T {
+  return createManduClientBoundaryRenderScope(routeId, bundleManifest)(render);
+}
+
+function runWithBoundaryContext<T>(
+  context: BoundaryRenderContext,
+  render: () => T,
+): T {
+  boundaryContextStack.push(context);
+  try {
+    return boundaryAsyncStorage.run(context, render);
+  } catch (error) {
+    throw error;
+  } finally {
+    boundaryContextStack.pop();
+  }
+}
+
+export function __ManduClientBoundary({
+  routeId,
+  boundaryId,
+  module,
+  exportName,
+  props = {},
+  hydrate = "visible",
+  src,
+}: ManduClientBoundaryProps): React.ReactElement {
+  const fallbackContext = getCurrentBoundaryContext();
+  return React.createElement(
+    BoundaryReactContext.Consumer,
+    {
+      children: (reactContext: BoundaryRenderContext | undefined) =>
+        renderClientBoundaryElement({
+          routeId,
+          boundaryId,
+          module,
+          exportName,
+          props,
+          hydrate,
+          src,
+        }, reactContext ?? fallbackContext),
+    },
+  );
+}
+
+function renderClientBoundaryElement(
+  {
+    routeId,
+    boundaryId,
+    module,
+    exportName,
+    props = {},
+    hydrate = "visible",
+    src,
+  }: ManduClientBoundaryProps,
+  context: BoundaryRenderContext | undefined,
+): React.ReactElement {
+  assertSerializableBoundaryProps({ routeId, boundaryId, module, exportName, props });
+  const serializedProps = serializeProps(props);
+  const priority = hydrate === "load" ? "immediate" : hydrate;
+  const resolvedSrc = src ?? resolveBoundarySrc(context, routeId, boundaryId);
+  const instanceId = nextBoundaryInstanceId(context, boundaryId);
+
+  return React.createElement(
+    React.Fragment,
+    null,
+    React.createElement("div", {
+      "data-mandu-island": instanceId,
+      "data-mandu-boundary-id": boundaryId,
+      "data-mandu-route-id": routeId,
+      "data-mandu-src": resolvedSrc,
+      "data-mandu-priority": priority,
+      "data-hydrate": hydrate,
+      "data-mandu-client-module": module,
+      "data-mandu-client-export": exportName,
+      style: { display: "contents" },
+    }),
+    React.createElement("script", {
+      type: "application/json",
+      "data-mandu-props": instanceId,
+      dangerouslySetInnerHTML: {
+        __html: escapeJsonForInlineScript(serializedProps),
+      },
+    }),
+  );
+}
+
+function assertSerializableBoundaryProps({
+  routeId,
+  boundaryId,
+  module,
+  exportName,
+  props,
+}: Required<Pick<ManduClientBoundaryProps, "routeId" | "boundaryId" | "module" | "exportName" | "props">>): void {
+  const reason = findNonSerializableBoundaryValue(props, "$", new WeakSet<object>());
+  if (!reason) return;
+
+  throw new Error(
+    `[MANDU_BOUNDARY_UNSERIALIZABLE_PROP] Client boundary props are not serializable for route "${routeId}", boundary "${boundaryId}" (${module}#${exportName}): ${reason}. ` +
+    "Pass plain serializable data, or construct functions, React elements, symbols, promises, and class instances inside the client component.",
+  );
+}
+
+function findNonSerializableBoundaryValue(
+  value: unknown,
+  path: string,
+  seen: WeakSet<object>,
+): string | null {
+  if (value === null || value === undefined) return null;
+
+  const valueType = typeof value;
+  if (valueType === "string" || valueType === "number" || valueType === "boolean" || valueType === "bigint") {
+    return null;
+  }
+
+  if (valueType === "function") {
+    return `${path} is a function`;
+  }
+
+  if (valueType === "symbol") {
+    return `${path} is a symbol`;
+  }
+
+  if (valueType !== "object") {
+    return `${path} has unsupported type "${valueType}"`;
+  }
+
+  if (React.isValidElement(value)) {
+    return `${path} is a React element`;
+  }
+
+  if (value instanceof Date || value instanceof URL || value instanceof RegExp || value instanceof Error) {
+    return null;
+  }
+
+  if (seen.has(value)) {
+    return null;
+  }
+  seen.add(value);
+
+  if (value instanceof Promise) {
+    return `${path} is a Promise`;
+  }
+
+  if (value instanceof Map) {
+    let index = 0;
+    for (const [key, entryValue] of value.entries()) {
+      const keyReason = findNonSerializableBoundaryValue(key, `${path}.<map-key:${index}>`, seen);
+      if (keyReason) return keyReason;
+      const valueReason = findNonSerializableBoundaryValue(entryValue, `${path}.<map-value:${index}>`, seen);
+      if (valueReason) return valueReason;
+      index++;
+    }
+    return null;
+  }
+
+  if (value instanceof Set) {
+    let index = 0;
+    for (const entryValue of value.values()) {
+      const reason = findNonSerializableBoundaryValue(entryValue, `${path}.<set:${index}>`, seen);
+      if (reason) return reason;
+      index++;
+    }
+    return null;
+  }
+
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      const reason = findNonSerializableBoundaryValue(value[index], `${path}[${index}]`, seen);
+      if (reason) return reason;
+    }
+    return null;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    const name = prototype?.constructor?.name ?? "unknown";
+    return `${path} is a ${name} instance`;
+  }
+
+  for (const [key, entryValue] of Object.entries(value as Record<string, unknown>)) {
+    const reason = findNonSerializableBoundaryValue(entryValue, `${path}.${key}`, seen);
+    if (reason) return reason;
+  }
+
+  return null;
+}
+
+function nextBoundaryInstanceId(context: BoundaryRenderContext | undefined, boundaryId: string): string {
+  if (!context) return boundaryId;
+
+  const count = context.instanceCounts.get(boundaryId) ?? 0;
+  context.instanceCounts.set(boundaryId, count + 1);
+  return count === 0 ? boundaryId : `${boundaryId}--${count}`;
+}
+
+function resolveBoundarySrc(
+  context: BoundaryRenderContext | undefined,
+  routeId: string,
+  boundaryId: string,
+): string | undefined {
+  const manifest = context?.bundleManifest;
+  if (!manifest) return undefined;
+
+  const boundary = manifest.boundaries?.[boundaryId];
+  if (boundary?.js) return cacheBust(boundary.js);
+
+  const effectiveRouteId = routeId || context?.routeId;
+  const routeBundle = effectiveRouteId ? manifest.bundles[effectiveRouteId] : undefined;
+  return routeBundle?.js ? cacheBust(routeBundle.js) : undefined;
+}
+
+function cacheBust(src: string): string {
+  return `${src}${src.includes("?") ? "&" : "?"}t=${Date.now()}`;
+}
+
+function getCurrentBoundaryContext(): BoundaryRenderContext | undefined {
+  return boundaryAsyncStorage.getStore() ?? boundaryContextStack[boundaryContextStack.length - 1];
+}

package/src/internal/index.ts

@@ -11,7 +11,8 @@ export * as watcher from "../watcher";
 export * as runtimeCache from "../runtime/cache";
 export * as runtimeRouter from "../runtime/router";
 export * as runtimeServer from "../runtime/server";
-export * as runtimeFastRefreshTypes from "../runtime/fast-refresh-types";
+export * as runtimeFastRefreshTypes from "../runtime/fast-refresh-types";
+export * as clientBoundary from "./client-boundary";
 
 export * as resourceDdlDiff from "../resource/ddl/diff";
 export * as resourceDdlEmit from "../resource/ddl/emit";