@mandujs/core 0.54.16 → 0.54.18

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";

package/src/router/client-entry.test.ts

@@ -3,9 +3,10 @@ import { mkdir, mkdtemp, rm, writeFile } from "fs/promises";
 import path from "path";
 import {
   findClientComponentImports,
-  findRouteLevelClientComponentImport,
-  findRouteLevelClientComponentImports,
-  resolveRouteLevelClientEntryPath,
+  findRouteLevelClientComponentImport,
+  findRouteLevelClientComponentImports,
+  resolveRouteLevelClientEntryPath,
+  validateClientModuleForBrowserBundle,
 } from "./client-entry";
 
 const repoTempRoot = path.resolve(import.meta.dir, "../../../..", ".tmp-test-artifacts");
@@ -230,6 +231,42 @@ describe("findClientComponentImports", () => {
       expect(resolved).toBe("src/client/widgets/pledge-form/PledgeForm.tsx");
     } finally {
       await rm(rootDir, { recursive: true, force: true });
-    }
-  });
-});
+    }
+  });
+
+  it("validates explicit route-level client modules against server-only imports", async () => {
+    const rootDir = await mkRepoTempDir("client-entry-server-only-");
+    try {
+      await mkdir(path.join(rootDir, "app"), { recursive: true });
+      await writeFile(
+        path.join(rootDir, "app", "dashboard.island.tsx"),
+        `"use client";
+         import { Database } from "bun:sqlite";
+         export default function Dashboard() {
+           return String(Database);
+         }`,
+      );
+
+      const error = await validateClientModuleForBrowserBundle(
+        {
+          id: "dashboard",
+          kind: "page",
+          pattern: "/dashboard",
+          module: "app/dashboard.tsx",
+          componentModule: "app/dashboard.tsx",
+          clientModule: "app/dashboard.island.tsx",
+          clientExportName: "default",
+          hydration: { strategy: "island", priority: "visible", preload: false },
+        },
+        rootDir,
+      );
+
+      expect(error).toContain("MANDU_BOUNDARY_SERVER_ONLY_IMPORT");
+      expect(error).toContain("bun:sqlite");
+      expect(error).toContain("route=dashboard");
+      expect(error).toContain("Suggestion:");
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/router/client-entry.ts

@@ -1,6 +1,10 @@
-import { readFile } from "fs/promises";
-import path from "path";
-import type { RouteSpec } from "../spec/schema";
+import { readFile } from "fs/promises";
+import path from "path";
+import type { RouteSpec } from "../spec/schema";
+import {
+  formatClientBoundaryDiagnostics,
+  validateClientBoundaryServerOnlyImports,
+} from "../bundler/client-boundary-transform";
 
 export interface ClientComponentImport {
   module: string;
@@ -499,10 +503,10 @@ function isIdentifierChar(value: string): boolean {
   return /[A-Za-z0-9_$]/.test(value);
 }
 
-export async function validateClientModuleForBrowserBundle(
-  route: RouteSpec,
-  rootDir: string,
-): Promise<string | null> {
+export async function validateClientModuleForBrowserBundle(
+  route: RouteSpec,
+  rootDir: string,
+): Promise<string | null> {
   if (!route.clientModule) return null;
 
   const source = await readRouteModule(rootDir, route.clientModule);
@@ -517,17 +521,34 @@ export async function validateClientModuleForBrowserBundle(
     if (realClientEntry) {
       route.clientModule = realClientEntry.modulePath;
       route.clientExportName = realClientEntry.exportName;
-      return null;
+      const realSource = await readRouteModule(rootDir, route.clientModule);
+      return realSource === null ? null : formatClientModuleBrowserDiagnostics(route, realSource);
     }
     return (
       `[${route.id}] Route component "${route.clientModule}" is configured as clientModule, ` +
       `but it is a server page (missing "use client"). Mandu will not bundle server pages into client islands. ` +
       `Remove the stale clientModule from .mandu/routes.manifest.json or use a *.partial.tsx / spec/slots/${route.id}.client.tsx client entry.`
     );
-  }
-
-  return null;
-}
+  }
+
+  return formatClientModuleBrowserDiagnostics(route, source);
+}
+
+function formatClientModuleBrowserDiagnostics(route: RouteSpec, source: string): string | null {
+  if (!route.clientModule) return null;
+  const diagnostics = validateClientBoundaryServerOnlyImports(
+    source,
+    {
+      id: `${route.id}--client-module`,
+      routeId: route.id,
+      module: route.clientModule,
+      exportName: route.clientExportName ?? "default",
+    },
+    route.clientModule,
+  );
+  if (diagnostics.length === 0) return null;
+  return formatClientBoundaryDiagnostics(diagnostics);
+}
 
 async function routeComponentHasResolvableClientEntry(
   rootDir: string,