@mandujs/core 0.54.5 → 0.54.7

package/src/resource/ddl/emit.ts

@@ -15,10 +15,11 @@
  *   4. Value literals in `DEFAULT` clauses flow through `resolveDefault`
  *      which handles quote escaping. `kind: "sql"` is the explicit
  *      escape hatch — caller's responsibility.
- *   5. Unsupported changes (v1 scope — `alter-column-type`) emit a
- *      `-- TODO:` comment block + a no-op `SELECT 1;` so the generated
- *      migration still parses and Agent C's runner can record an
- *      "applied but manual" row.
+ *   5. Unsupported changes (v1 scope — `alter-column-type`, and some
+ *      dialect-specific ALTER gaps) emit a `-- TODO:` comment block plus
+ *      a deliberate failing sentinel statement. The generated migration
+ *      is reviewable/editable, but `mandu db apply` will not record it
+ *      until the operator replaces the TODO with real SQL.
  *
  * Determinism:
  *   - `emitCreateTable` emits columns in `DdlFieldDef` array order — the
@@ -338,15 +339,16 @@ export function emitChange(change: Change, provider: SqlProvider): string {
 // Change emitters (internal — called only via emitChange dispatch).
 // =====================================================================
 
-function emitAddColumn(
-  resourceName: string,
-  field: DdlFieldDef,
-  provider: SqlProvider,
-): string {
-  const table = quoteIdent(resourceName, provider);
-  const columnDef = emitColumnDef(field, provider);
-  const addColumn = `ALTER TABLE ${table} ADD COLUMN ${columnDef};`;
-  if (!field.indexed || field.unique || field.primary) return addColumn;
+function emitAddColumn(
+  resourceName: string,
+  field: DdlFieldDef,
+  provider: SqlProvider,
+): string {
+  validateAddColumn(resourceName, field, provider);
+  const table = quoteIdent(resourceName, provider);
+  const columnDef = emitColumnDef(field, provider);
+  const addColumn = `ALTER TABLE ${table} ADD COLUMN ${columnDef};`;
+  if (!field.indexed || field.unique || field.primary) return addColumn;
   return [
     addColumn,
     emitCreateIndex(
@@ -356,8 +358,85 @@ function emitAddColumn(
       false,
       provider,
     ),
-  ].join("\n");
-}
+  ].join("\n");
+}
+
+function validateAddColumn(
+  resourceName: string,
+  field: DdlFieldDef,
+  provider: SqlProvider,
+): void {
+  if (provider !== "sqlite") return;
+
+  if (field.primary) {
+    throw new Error(
+      `SQLite cannot add PRIMARY KEY column "${field.name}" to existing table "${resourceName}" via ALTER TABLE. ` +
+        `Create a manual table-rebuild migration instead.`,
+    );
+  }
+
+  if (field.unique) {
+    throw new Error(
+      `SQLite cannot add UNIQUE column "${field.name}" to existing table "${resourceName}" via ALTER TABLE. ` +
+        `Add a nullable/non-unique column first, backfill it, then create a unique index manually.`,
+    );
+  }
+
+  const defaultIssue = sqliteAddColumnDefaultIssue(field);
+  if (defaultIssue) {
+    throw new Error(
+      `SQLite cannot add column "${field.name}" to existing table "${resourceName}" with this DEFAULT: ` +
+        `${defaultIssue} Use a scalar literal default or write a manual backfill migration.`,
+    );
+  }
+
+  if (field.nullable) return;
+  if (field.default !== undefined && !isSqliteNullDefault(field.default)) return;
+
+  throw new Error(
+    `SQLite cannot add required column "${field.name}" to existing table "${resourceName}" without a non-NULL constant DEFAULT. ` +
+      `Add a scalar default, set required:false, or write a manual backfill migration.`,
+  );
+}
+
+function sqliteAddColumnDefaultIssue(field: DdlFieldDef): string | null {
+  const def = field.default;
+  if (!def) return null;
+  if (def.kind === "now") {
+    return `default "now" maps to CURRENT_TIMESTAMP, which SQLite rejects in ADD COLUMN.`;
+  }
+  if (def.kind !== "sql") return null;
+
+  const expr = def.expr.trim();
+  if (/^CURRENT_(?:TIME|DATE|TIMESTAMP)\b/i.test(expr)) {
+    return `SQLite rejects CURRENT_TIME/CURRENT_DATE/CURRENT_TIMESTAMP in ADD COLUMN.`;
+  }
+  if (/\b[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(expr)) {
+    return `SQLite rejects non-constant function defaults in ADD COLUMN.`;
+  }
+  if (!isSqliteAddColumnConstantSqlDefault(expr)) {
+    return `SQLite ADD COLUMN only accepts literal constant defaults; raw SQL expression ${JSON.stringify(expr)} is not safe to emit automatically.`;
+  }
+  return null;
+}
+
+function isSqliteNullDefault(def: NonNullable<DdlFieldDef["default"]>): boolean {
+  return def.kind === "null" || (def.kind === "sql" && /^NULL$/i.test(def.expr.trim()));
+}
+
+function isSqliteAddColumnConstantSqlDefault(expr: string): boolean {
+  let value = expr.trim();
+  while (value.startsWith("(") && value.endsWith(")")) {
+    value = value.slice(1, -1).trim();
+  }
+  return (
+    /^NULL$/i.test(value) ||
+    /^(?:TRUE|FALSE)$/i.test(value) ||
+    /^[+-]?(?:\d+|\d+\.\d+|\.\d+)(?:e[+-]?\d+)?$/i.test(value) ||
+    /^'(?:''|[^'])*'$/.test(value) ||
+    /^X'(?:[0-9a-f]{2})*'$/i.test(value)
+  );
+}
 
 /**
  * DROP COLUMN.
@@ -383,8 +462,8 @@ function emitDropColumn(
  *
  * Output: a multi-line SQL comment block naming the resource + field +
  * fromType → toType, followed by the literal TODO message and a no-op
- * `SELECT 1;` so the migration runner (Agent C) parses and advances past
- * this statement.
+ * a deliberate failing sentinel so the migration runner refuses to mark
+ * this TODO as applied until the operator edits the migration manually.
  */
 function emitAlterColumnTypeStub(
   resourceName: string,
@@ -398,11 +477,13 @@ function emitAlterColumnTypeStub(
     `--   from: ${fromType}`,
     `--   to:   ${toType}`,
     `-- TODO: Mandu does not auto-generate ALTER COLUMN TYPE in v1.`,
-    `-- Please write the migration manually, then re-run \`mandu db apply\`.`,
-    `-- ================================================================`,
-    `SELECT 1;`,
-  ].join("\n");
-}
+    `-- Please write the migration manually, then re-run \`mandu db apply\`.`,
+    `-- ================================================================`,
+    manualMigrationRequiredStatement(
+      `Mandu cannot auto-generate ALTER COLUMN TYPE for ${resourceName}.${fieldName}`,
+    ),
+  ].join("\n");
+}
 
 function emitAlterColumnNullable(
   resourceName: string,
@@ -419,30 +500,34 @@ function emitAlterColumnNullable(
       : `ALTER TABLE ${table} ALTER COLUMN ${col} SET NOT NULL;`;
   }
   if (provider === "sqlite") {
-    // SQLite cannot toggle NOT NULL on an existing column without a full
-    // table recreate. Emit a stub so the user handles it manually.
-    return [
-      `-- ================================================================`,
-      `-- Nullability change: ${resourceName}.${fieldName} → ${nullable ? "NULL" : "NOT NULL"}`,
-      `-- TODO: SQLite cannot toggle NOT NULL in place. Recreate the table`,
-      `-- manually (CREATE new, INSERT SELECT, DROP old, RENAME) and re-run.`,
-      `-- ================================================================`,
-      `SELECT 1;`,
-    ].join("\n");
-  }
+    // SQLite cannot toggle NOT NULL on an existing column without a full
+    // table recreate. Emit a failing stub so the user handles it manually.
+    return [
+      `-- ================================================================`,
+      `-- Nullability change: ${resourceName}.${fieldName} → ${nullable ? "NULL" : "NOT NULL"}`,
+      `-- TODO: SQLite cannot toggle NOT NULL in place. Recreate the table`,
+      `-- manually (CREATE new, INSERT SELECT, DROP old, RENAME) and re-run.`,
+      `-- ================================================================`,
+      manualMigrationRequiredStatement(
+        `SQLite nullability change requires manual table rebuild for ${resourceName}.${fieldName}`,
+      ),
+    ].join("\n");
+  }
   // MySQL requires the full column spec; we cannot reconstruct it here.
   // Emit a stub — Agent B's diff emits `alter-column-nullable` only when
   // everything else matches, so this is narrow-scope.
   return [
     `-- ================================================================`,
     `-- Nullability change: ${resourceName}.${fieldName} → ${nullable ? "NULL" : "NOT NULL"}`,
-    `-- TODO: MySQL MODIFY COLUMN requires the full column type; Mandu v1`,
-    `-- cannot emit this automatically. Please edit this migration to use`,
-    `-- \`ALTER TABLE ${resourceName} MODIFY COLUMN ${fieldName} <TYPE> ${nullable ? "NULL" : "NOT NULL"}\``,
-    `-- ================================================================`,
-    `SELECT 1;`,
-  ].join("\n");
-}
+    `-- TODO: MySQL MODIFY COLUMN requires the full column type; Mandu v1`,
+    `-- cannot emit this automatically. Please edit this migration to use`,
+    `-- \`ALTER TABLE ${resourceName} MODIFY COLUMN ${fieldName} <TYPE> ${nullable ? "NULL" : "NOT NULL"}\``,
+    `-- ================================================================`,
+    manualMigrationRequiredStatement(
+      `MySQL nullability change requires manual MODIFY COLUMN for ${resourceName}.${fieldName}`,
+    ),
+  ].join("\n");
+}
 
 function emitAlterColumnDefault(
   resourceName: string,
@@ -458,15 +543,17 @@ function emitAlterColumnDefault(
       : `ALTER TABLE ${table} ALTER COLUMN ${col} DROP DEFAULT;`;
   }
   if (provider === "sqlite") {
-    // Same constraint as nullability — SQLite needs a table recreate.
-    return [
-      `-- ================================================================`,
-      `-- Default change: ${resourceName}.${fieldName}`,
-      `-- TODO: SQLite cannot ALTER DEFAULT in place. Recreate the table.`,
-      `-- ================================================================`,
-      `SELECT 1;`,
-    ].join("\n");
-  }
+    // Same constraint as nullability — SQLite needs a table recreate.
+    return [
+      `-- ================================================================`,
+      `-- Default change: ${resourceName}.${fieldName}`,
+      `-- TODO: SQLite cannot ALTER DEFAULT in place. Recreate the table.`,
+      `-- ================================================================`,
+      manualMigrationRequiredStatement(
+        `SQLite default change requires manual table rebuild for ${resourceName}.${fieldName}`,
+      ),
+    ].join("\n");
+  }
   // MySQL — ALTER COLUMN ... SET DEFAULT / DROP DEFAULT is actually supported.
   return def
     ? `ALTER TABLE ${table} ALTER COLUMN ${col} SET DEFAULT ${resolveDefault(def, provider)};`
@@ -510,7 +597,7 @@ function emitRenameTable(
   return `ALTER TABLE ${from} RENAME TO ${to};`;
 }
 
-function emitRenameColumn(
+function emitRenameColumn(
   resourceName: string,
   oldName: string,
   newName: string,
@@ -522,7 +609,15 @@ function emitRenameColumn(
   // All three dialects use `ALTER TABLE ... RENAME COLUMN ... TO ...` in
   // their modern versions (PG >=9.2, MySQL >=8.0.3, SQLite >=3.25).
   return `ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to};`;
-}
+}
+
+function manualMigrationRequiredStatement(message: string): string {
+  return `SELECT mandu_manual_migration_required(${sqlStringLiteral(message)});`;
+}
+
+function sqlStringLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
 
 // =====================================================================
 // Validation helpers.

package/src/resource/generator-schema.ts

@@ -363,21 +363,17 @@ ${result.migrationSql}`;
 // ============================================
 
 /**
- * Wrap the sequence of `Change` → SQL emission with a transaction
- * header/footer. SQLite uses `BEGIN` / `COMMIT` (plain) because its
- * migration runner invokes each file via `db.transaction()` anyway —
- * but the explicit BEGIN/COMMIT is harmless inside an already-open tx
- * and makes the file runnable standalone via `sqlite3 foo.db < file.sql`.
- */
-function composeMigrationSql(changes: readonly Change[], provider: SqlProvider): string {
-  const body = emitChanges(changes, provider);
-  if (body.length === 0) return "";
-  return `BEGIN;
-
-${body}
-
-COMMIT;`;
-}
+ * Compose the sequence of `Change` → SQL emission.
+ *
+ * Do not wrap with `BEGIN` / `COMMIT`: the migration runner already applies
+ * each file inside a transaction, and SQLite rejects nested BEGIN with
+ * "cannot start a transaction within a transaction".
+ */
+function composeMigrationSql(changes: readonly Change[], provider: SqlProvider): string {
+  const body = emitChanges(changes, provider);
+  if (body.length === 0) return "";
+  return body;
+}
 
 // ============================================
 // Internals — filesystem I/O

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

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "bun:test";
+import {
+  findClientComponentImports,
+  findRouteLevelClientComponentImport,
+} from "./client-entry";
+
+describe("findClientComponentImports", () => {
+  it("detects named .client imports for diagnostics", () => {
+    const imports = findClientComponentImports(`
+      import { LoginForm, SubmitButton as Button } from "@/client/widgets/login-form/LoginForm.client";
+      import Header from "./Header.client.tsx";
+    `);
+
+    expect(imports).toEqual([
+      {
+        module: "@/client/widgets/login-form/LoginForm.client",
+        kind: "named",
+        names: ["LoginForm", "SubmitButton"],
+      },
+      {
+        module: "./Header.client.tsx",
+        kind: "default",
+        names: ["Header"],
+      },
+    ]);
+  });
+
+  it("detects a default-imported client component when the page returns only that component", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import LoginPage from "@/client/pages/login/LoginPage.client";
+
+      export const metadata = { title: "Login" };
+
+      export default function Page() {
+        return <LoginPage />;
+      }
+    `);
+
+    expect(routeClient).toEqual({
+      module: "@/client/pages/login/LoginPage.client",
+      localName: "LoginPage",
+    });
+  });
+
+  it("does not promote embedded client imports inside a larger server page", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import HomeApp from "@/client/pages/home/HomeApp.client";
+
+      export default function HomePage() {
+        return <>
+          <meta name="description" content="home" />
+          <HomeApp />
+        </>;
+      }
+    `);
+
+    expect(routeClient).toBeNull();
+  });
+
+  it("does not promote client imports when the page wrapper passes props", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import PledgePage from "@/client/pages/pledges/PledgePage.client";
+
+      export default function Page({ params }) {
+        return <PledgePage id={params.id} />;
+      }
+    `);
+
+    expect(routeClient).toBeNull();
+  });
+});

package/src/router/client-entry.ts

@@ -2,6 +2,17 @@ import { readFile } from "fs/promises";
 import path from "path";
 import type { RouteSpec } from "../spec/schema";
 
+export interface ClientComponentImport {
+  module: string;
+  kind: "default" | "named" | "namespace" | "side-effect" | "mixed";
+  names: string[];
+}
+
+export interface RouteLevelClientComponentImport {
+  module: string;
+  localName: string;
+}
+
 export function normalizeRouteModulePath(value: string | undefined): string {
   return (value ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
 }
@@ -32,6 +43,95 @@ async function readRouteModule(rootDir: string, modulePath: string): Promise<str
   }
 }
 
+export function findClientComponentImports(source: string): ClientComponentImport[] {
+  const imports: ClientComponentImport[] = [];
+  const importFromPattern = /import\s+([\s\S]*?)\s+from\s+["']([^"']*\.client(?:\.[tj]sx?)?)["']/g;
+  const sideEffectPattern = /import\s+["']([^"']*\.client(?:\.[tj]sx?)?)["']/g;
+
+  for (const match of source.matchAll(importFromPattern)) {
+    const clause = (match[1] ?? "").trim();
+    const module = match[2] ?? "";
+    const names: string[] = [];
+    let hasDefault = false;
+    let hasNamed = false;
+    let hasNamespace = false;
+
+    const namedMatch = clause.match(/\{([^}]*)\}/);
+    if (namedMatch) {
+      hasNamed = true;
+      for (const rawName of namedMatch[1].split(",")) {
+        const name = rawName.trim();
+        if (!name) continue;
+        names.push(name.split(/\s+as\s+/i)[0].trim());
+      }
+    }
+
+    if (/\*\s+as\s+/.test(clause)) {
+      hasNamespace = true;
+      const namespaceMatch = clause.match(/\*\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*)/);
+      if (namespaceMatch?.[1]) names.push(namespaceMatch[1]);
+    }
+
+    const beforeNamed = clause.split("{")[0]?.replace(/,\s*$/, "").trim() ?? "";
+    if (beforeNamed && !beforeNamed.startsWith("*")) {
+      hasDefault = true;
+      names.push(beforeNamed.split(",")[0].trim());
+    }
+
+    const kind =
+      (hasDefault && (hasNamed || hasNamespace))
+        ? "mixed"
+        : hasNamed
+          ? "named"
+          : hasNamespace
+            ? "namespace"
+            : "default";
+
+    imports.push({ module, kind, names });
+  }
+
+  for (const match of source.matchAll(sideEffectPattern)) {
+    const module = match[1] ?? "";
+    if (imports.some((entry) => entry.module === module)) continue;
+    imports.push({ module, kind: "side-effect", names: [] });
+  }
+
+  return imports;
+}
+
+export function findRouteLevelClientComponentImport(source: string): RouteLevelClientComponentImport | null {
+  const defaultImports = findClientComponentImports(source).filter((entry) => {
+    const localName = entry.names[0] ?? "";
+    return entry.kind === "default" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(localName);
+  });
+
+  if (defaultImports.length !== 1) return null;
+
+  const entry = defaultImports[0];
+  const localName = entry.names[0];
+  if (!entry.module || !localName) return null;
+  if (!defaultExportReturnsOnlyClientComponent(source, localName)) return null;
+
+  return { module: entry.module, localName };
+}
+
+export async function resolveClientImportModulePath(
+  rootDir: string,
+  importerModule: string,
+  specifier: string,
+): Promise<string | null> {
+  const base = resolveImportBasePath(rootDir, importerModule, specifier);
+  if (!base) return null;
+
+  for (const candidate of expandClientModuleCandidates(base)) {
+    if (await Bun.file(candidate).exists()) {
+      return path.relative(rootDir, candidate).replace(/\\/g, "/");
+    }
+  }
+
+  return null;
+}
+
 export async function shouldPreserveExistingClientModule(
   route: RouteSpec,
   clientModule: string,
@@ -46,6 +146,147 @@ export async function shouldPreserveExistingClientModule(
   return true;
 }
 
+function resolveImportBasePath(rootDir: string, importerModule: string, specifier: string): string | null {
+  const normalized = specifier.replace(/\\/g, "/");
+  if (normalized.startsWith("@/") || normalized.startsWith("~/")) {
+    return path.resolve(rootDir, "src", normalized.slice(2));
+  }
+  if (normalized.startsWith("./") || normalized.startsWith("../")) {
+    return path.resolve(rootDir, path.dirname(importerModule), normalized);
+  }
+  return null;
+}
+
+function expandClientModuleCandidates(basePath: string): string[] {
+  if (/\.[cm]?[jt]sx?$/.test(basePath)) return [basePath];
+  return [
+    `${basePath}.tsx`,
+    `${basePath}.ts`,
+    `${basePath}.jsx`,
+    `${basePath}.js`,
+  ];
+}
+
+function defaultExportReturnsOnlyClientComponent(source: string, localName: string): boolean {
+  const functionBody = extractDefaultExportFunctionBody(source);
+  if (functionBody !== null) {
+    const returned = extractOnlyReturnExpression(functionBody);
+    return returned !== null && isSelfClosingJsxElement(returned, localName);
+  }
+
+  const arrowExpression = extractDefaultExportArrowExpression(source);
+  return arrowExpression !== null && isSelfClosingJsxElement(arrowExpression, localName);
+}
+
+function extractDefaultExportFunctionBody(source: string): string | null {
+  const match = /export\s+default\s+(?:async\s+)?function(?:\s+[A-Za-z_$][A-Za-z0-9_$]*)?\s*\([^)]*\)\s*(?::\s*[^{=]+)?\{/m.exec(source);
+  if (!match) return null;
+
+  const openBrace = match.index + match[0].lastIndexOf("{");
+  const closeBrace = findMatchingBrace(source, openBrace);
+  if (closeBrace === -1) return null;
+  return source.slice(openBrace + 1, closeBrace);
+}
+
+function extractDefaultExportArrowExpression(source: string): string | null {
+  const match = /export\s+default\s+(?:async\s+)?(?:\([^)]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>\s*/m.exec(source);
+  if (!match) return null;
+
+  const start = match.index + match[0].length;
+  const rest = source.slice(start).trim();
+  if (rest.startsWith("{")) return null;
+
+  const semicolon = rest.indexOf(";");
+  return semicolon === -1 ? rest : rest.slice(0, semicolon);
+}
+
+function extractOnlyReturnExpression(body: string): string | null {
+  const match = /^\s*return\s+([\s\S]*?)\s*;?\s*$/.exec(body);
+  return match?.[1]?.trim() ?? null;
+}
+
+function isSelfClosingJsxElement(expression: string, localName: string): boolean {
+  const expr = stripWrappingParentheses(expression.trim());
+  const escaped = escapeRegExp(localName);
+  return new RegExp(`^<${escaped}\\s*/>$`).test(expr);
+}
+
+function stripWrappingParentheses(value: string): string {
+  let current = value.trim();
+  while (current.startsWith("(") && current.endsWith(")")) {
+    const close = findMatchingParen(current, 0);
+    if (close !== current.length - 1) break;
+    current = current.slice(1, -1).trim();
+  }
+  return current;
+}
+
+function findMatchingBrace(source: string, openIndex: number): number {
+  return findMatchingDelimiter(source, openIndex, "{", "}");
+}
+
+function findMatchingParen(source: string, openIndex: number): number {
+  return findMatchingDelimiter(source, openIndex, "(", ")");
+}
+
+function findMatchingDelimiter(source: string, openIndex: number, open: string, close: string): number {
+  let depth = 0;
+  let quote: '"' | "'" | "`" | null = null;
+  let lineComment = false;
+  let blockComment = false;
+
+  for (let i = openIndex; i < source.length; i++) {
+    const char = source[i];
+    const next = source[i + 1];
+    const prev = source[i - 1];
+
+    if (lineComment) {
+      if (char === "\n" || char === "\r") lineComment = false;
+      continue;
+    }
+
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        i++;
+      }
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote && prev !== "\\") quote = null;
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      i++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      i++;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+
+    if (char === open) depth++;
+    if (char === close) {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+
+  return -1;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 export async function validateClientModuleForBrowserBundle(
   route: RouteSpec,
   rootDir: string,
@@ -69,3 +310,48 @@ export async function validateClientModuleForBrowserBundle(
 
   return null;
 }
+
+export async function describeMissingHydrationClientModule(
+  route: RouteSpec,
+  rootDir: string,
+  options: { allowPartialOnly?: boolean } = {},
+): Promise<string | null> {
+  const hydration = route.hydration?.strategy ?? "island";
+  const base =
+    `[${route.id}] Route has hydration strategy "${hydration}" but no clientModule could be resolved. ` +
+    `Mandu cannot emit a working data-mandu-src for this route.`;
+
+  const componentModule = route.kind === "page" ? route.componentModule : undefined;
+  if (!componentModule) {
+    return options.allowPartialOnly && hydration === "island" ? null : base;
+  }
+
+  const source = await readRouteModule(rootDir, componentModule);
+  if (source === null) {
+    return options.allowPartialOnly && hydration === "island" ? null : base;
+  }
+
+  const clientImports = findClientComponentImports(source);
+  if (clientImports.length === 0) {
+    if (options.allowPartialOnly && hydration === "island") return null;
+    return (
+      `${base}\n` +
+      `  Fix: add a route-level client module (for example app/*.island.tsx or spec/slots/${route.id}.client.tsx) ` +
+      `or set hydration.strategy to "none".`
+    );
+  }
+
+  const importList = clientImports
+    .map((entry) => {
+      const suffix = entry.names.length > 0 ? ` (${entry.kind}: ${entry.names.join(", ")})` : ` (${entry.kind})`;
+      return `    - ${entry.module}${suffix}`;
+    })
+    .join("\n");
+
+  return (
+    `${base}\n` +
+    `  The page imports client-looking modules, but inline .client.tsx imports are not route bundles:\n` +
+    `${importList}\n` +
+    `  Fix: use partial({ component }).Render for embedded client regions, or expose a route-level client module.`
+  );
+}