@mandujs/core 0.54.2 → 0.54.4

package/src/bundler/css.ts

@@ -18,14 +18,38 @@ import fs from "fs/promises";
 import { watch as fsWatch, type FSWatcher } from "fs";
 import { withPerf } from "../perf";
 
-/**
- * Tailwind CLI 실행 명령어를 결정한다.
- * Windows에서 Bun.spawn은 PATH 기반 명령어 해석이 불안정하므로 (#152)
- * process.execPath (절대 경로)를 사용해 안정적으로 실행한다.
- */
-function getTailwindCommand(args: string[]): string[] {
-  return [process.execPath, "x", ...args];
-}
+/**
+ * Tailwind CLI 실행 명령어를 결정한다.
+ * Windows에서 Bun.spawn은 PATH 기반 명령어 해석이 불안정하므로 (#152)
+ * `bun run mandu` 환경에서는 process.execPath (bun 절대 경로)를 사용한다.
+ * Standalone Mandu binary에서는 process.execPath가 mandu.exe를 가리키므로
+ * `mandu x @tailwindcss/cli`로 오해석된다. 이 경우 PATH에서 Bun을 찾는다.
+ */
+function isBunExecutable(executablePath: string | undefined): boolean {
+  if (!executablePath) return false;
+  const base = path.basename(executablePath).toLowerCase();
+  return base === "bun" || base === "bun.exe";
+}
+
+type WhichExecutable = (command: string) => string | null | undefined;
+
+function resolveBunExecutable(
+  execPath = process.execPath,
+  which: WhichExecutable = (command) => Bun.which(command),
+): string {
+  if (isBunExecutable(execPath)) return execPath;
+  const fromPath = which("bun");
+  if (fromPath) return fromPath;
+  return process.platform === "win32" ? "bun.exe" : "bun";
+}
+
+function getTailwindCommand(
+  args: string[],
+  execPath = process.execPath,
+  which?: WhichExecutable,
+): string[] {
+  return [resolveBunExecutable(execPath, which), "x", ...args];
+}
 
 // ========== Types ==========
 
@@ -320,7 +344,13 @@ export function getCSSServerPath(): string {
 /**
  * CSS 링크 태그 생성
  */
-export function generateCSSLinkTag(isDev: boolean = false): string {
-  const cacheBust = isDev ? `?t=${Date.now()}` : "";
-  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
-}
+export function generateCSSLinkTag(isDev: boolean = false): string {
+  const cacheBust = isDev ? `?t=${Date.now()}` : "";
+  return `<link rel="stylesheet" href="${SERVER_CSS_PATH}${cacheBust}">`;
+}
+
+export const __private = {
+  getTailwindCommand,
+  isBunExecutable,
+  resolveBunExecutable,
+};

package/src/bundler/manifest-schema.ts

@@ -28,7 +28,8 @@
  *
  * URL safety model (applies to `shared.runtime`, `shared.vendor`,
  * `shared.router`, `shared.fastRefresh.glue`, `shared.fastRefresh.runtime`,
- * `bundles[].js`, `bundles[].css`, `islands[].js`, `importMap.imports[*]`):
+ * `bundles[].js`, `bundles[].css`, `islands[].js`, `partials[].js`,
+ * `importMap.imports[*]`):
  *
  *   ALLOW:  absolute paths rooted at `/.mandu/client/` ending in `.js` or `.css`.
  *           The bundler itself only ever emits this shape.
@@ -161,15 +162,20 @@ const BundleEntrySchema = z.object({
   priority: PrioritySchema,
 });
 
-const IslandEntrySchema = z.object({
-  js: safeManduUrl("islands[].js"),
-  route: z.string().min(1),
-  priority: PrioritySchema,
-});
-
-const FastRefreshSchema = z.object({
-  runtime: safeManduUrl("shared.fastRefresh.runtime"),
-  glue: safeManduUrl("shared.fastRefresh.glue"),
+const IslandEntrySchema = z.object({
+  js: safeManduUrl("islands[].js"),
+  route: z.string().min(1),
+  priority: PrioritySchema,
+});
+
+const PartialEntrySchema = z.object({
+  js: safeManduUrl("partials[].js"),
+  priority: PrioritySchema,
+});
+
+const FastRefreshSchema = z.object({
+  runtime: safeManduUrl("shared.fastRefresh.runtime"),
+  glue: safeManduUrl("shared.fastRefresh.glue"),
 });
 
 const SharedSchema = z.object({
@@ -219,10 +225,11 @@ export const BundleManifestSchema = z
   .object({
     version: z.number().int().min(1),
     buildTime: z.string().min(1),
-    env: z.enum(["development", "production"]),
-    bundles: z.record(z.string(), BundleEntrySchema),
-    islands: z.record(z.string(), IslandEntrySchema).optional(),
-    shared: SharedSchema,
+    env: z.enum(["development", "production"]),
+    bundles: z.record(z.string(), BundleEntrySchema),
+    islands: z.record(z.string(), IslandEntrySchema).optional(),
+    partials: z.record(z.string(), PartialEntrySchema).optional(),
+    shared: SharedSchema,
     importMap: ImportMapSchema.optional(),
   })
   .strict();

package/src/bundler/types.ts

@@ -55,18 +55,28 @@ export interface BundleManifest {
       priority: "immediate" | "visible" | "idle" | "interaction";
     }
   >;
-  /** Per-island bundles (code splitting: each island file gets its own JS bundle) */
-  islands?: Record<
-    string,
-    {
-      /** JavaScript bundle path */
+  /** Per-island bundles (code splitting: each island file gets its own JS bundle) */
+  islands?: Record<
+    string,
+    {
+      /** JavaScript bundle path */
       js: string;
       /** Route that owns this island */
       route: string;
       /** Hydration priority */
-      priority: "immediate" | "visible" | "idle" | "interaction";
-    }
-  >;
+      priority: "immediate" | "visible" | "idle" | "interaction";
+    }
+  >;
+  /** Inline partial bundles (from *.partial.tsx / *.partial.ts files) */
+  partials?: Record<
+    string,
+    {
+      /** JavaScript bundle path */
+      js: string;
+      /** Hydration priority */
+      priority: "immediate" | "visible" | "idle" | "interaction";
+    }
+  >;
   /** 공유 청크 */
   shared: {
     /** Hydration 런타임 */
@@ -113,12 +123,19 @@ export interface BundleStats {
 }
 
 /** Per-island code splitting entry (used by scanIslandFiles) */
-export interface IslandFileEntry {
-  name: string;
-  filePath: string;
-  routeId: string;
-  priority: "immediate" | "visible" | "idle" | "interaction";
-}
+export interface IslandFileEntry {
+  name: string;
+  filePath: string;
+  routeId: string;
+  priority: "immediate" | "visible" | "idle" | "interaction";
+}
+
+/** Inline partial bundle entry (used by scanPartialFiles) */
+export interface PartialFileEntry {
+  name: string;
+  filePath: string;
+  priority: "immediate" | "visible" | "idle" | "interaction";
+}
 
 /**
  * 번들러 옵션

package/src/client/island.ts

@@ -3,8 +3,9 @@
  * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
  */
 
-import type { ReactNode } from "react";
-import { getServerData as getGlobalServerData } from "./window-state";
+import type { ReactNode } from "react";
+import { serializeProps } from "./serialize";
+import { getServerData as getGlobalServerData } from "./window-state";
 
 /**
  * Island 정의 타입
@@ -335,26 +336,45 @@ export interface PartialConfig {
 /**
  * Partial Island 정의 타입
  */
-export interface PartialDefinition<TProps> {
-  /** Partial 컴포넌트 */
-  component: React.ComponentType<TProps>;
-  /** 초기 props (SSR에서 전달) */
-  initialProps?: TProps;
-  /** 하이드레이션 우선순위 */
-  priority?: "immediate" | "visible" | "idle" | "interaction";
-}
+export interface PartialDefinition<TProps> {
+  /** Partial 고유 ID. 기본값은 component displayName/name 입니다. */
+  id?: string;
+  /** Partial 컴포넌트 */
+  component: React.ComponentType<TProps>;
+  /** 초기 props (SSR에서 전달) */
+  initialProps?: TProps;
+  /** 하이드레이션 우선순위 */
+  priority?: "immediate" | "visible" | "idle" | "interaction";
+  /** 명시적 번들 URL. 기본값은 `/.mandu/client/{id}.partial.js` 입니다. */
+  src?: string;
+  /** 에러 시 표시할 UI */
+  errorBoundary?: (error: Error, reset: () => void) => ReactNode;
+  /** 로딩 중 표시할 UI */
+  loading?: () => ReactNode;
+}
 
 /**
  * 컴파일된 Partial
  */
-export interface CompiledPartial<TProps> {
+export interface CompiledPartial<TProps> {
   /** Partial 정의 */
   definition: PartialDefinition<TProps>;
   /** Mandu Partial 마커 */
   __mandu_partial: true;
   /** Partial ID */
-  __mandu_partial_id?: string;
-}
+  __mandu_partial_id?: string;
+}
+
+function normalizePartialId(id: string): string {
+  return id
+    .trim()
+    .replace(/[^A-Za-z0-9_-]/g, "-")
+    .replace(/^-+|-+$/g, "") || "partial";
+}
+
+function priorityToHydrate(priority: NonNullable<PartialDefinition<unknown>["priority"]>): string {
+  return priority === "immediate" ? "load" : priority;
+}
 
 /**
  * Partial Island 생성
@@ -379,26 +399,56 @@ export interface CompiledPartial<TProps> {
  * }
  * ```
  */
-export function partial<TProps extends Record<string, unknown>>(
-  definition: PartialDefinition<TProps>
-): CompiledPartial<TProps> & {
-  Render: React.ComponentType<TProps>;
-} {
+export function partial<TProps extends Record<string, unknown>>(
+  definition: PartialDefinition<TProps>
+): CompiledPartial<TProps> & {
+  Render: React.ComponentType<TProps>;
+} {
   if (!definition.component) {
     throw new Error("[Mandu Partial] component is required");
   }
 
-  const compiled: CompiledPartial<TProps> = {
-    definition,
-    __mandu_partial: true,
-  };
-
-  // Render 컴포넌트 생성
-  const React = require("react");
-
-  const RenderComponent: React.FC<TProps> = (props) => {
-    return React.createElement(definition.component, props);
-  };
+  const partialId = normalizePartialId(
+    definition.id ||
+    definition.component.displayName ||
+    definition.component.name ||
+    "partial",
+  );
+  const normalizedDefinition: PartialDefinition<TProps> = {
+    ...definition,
+    id: partialId,
+  };
+
+  const compiled: CompiledPartial<TProps> = {
+    definition: normalizedDefinition,
+    __mandu_partial: true,
+    __mandu_partial_id: partialId,
+  };
+
+  // Render 컴포넌트 생성
+  const React = require("react");
+
+  const RenderComponent: React.FC<TProps> = (props) => {
+    const renderProps = Object.keys(props).length > 0
+      ? props
+      : (normalizedDefinition.initialProps ?? props);
+    const priority = normalizedDefinition.priority ?? "visible";
+    const bundleSrc = normalizedDefinition.src ?? `/.mandu/client/${partialId}.partial.js`;
+
+    return React.createElement(
+      "div",
+      {
+        "data-mandu-island": partialId,
+        "data-mandu-partial": partialId,
+        "data-mandu-src": bundleSrc,
+        "data-mandu-priority": priority,
+        "data-hydrate": priorityToHydrate(priority),
+        "data-props": serializeProps(renderProps),
+        style: { display: "contents" },
+      },
+      React.createElement(normalizedDefinition.component, renderProps),
+    );
+  };
 
   return Object.assign(compiled, { Render: RenderComponent });
 }

package/src/guard/config-guard.ts

@@ -187,13 +187,19 @@ export function formatConfigGuardResult(result: ConfigGuardResult): string {
   } else if (!result.lockfileExists) {
     lines.push("💡 Lockfile 없음");
     lines.push("   'mandu lock'으로 생성 권장");
-  } else {
-    lines.push("❌ 설정 무결성 검증 실패");
-
-    for (const error of result.errors) {
-      lines.push(`   🔴 ${error.message}`);
-    }
-  }
+  } else {
+    lines.push("❌ 설정 무결성 검증 실패");
+
+    for (const error of result.errors) {
+      lines.push(`   🔴 ${error.message}`);
+    }
+
+    lines.push("");
+    lines.push("   다음 단계:");
+    lines.push("   ↳ 변경 확인: mandu lock --diff");
+    lines.push("   ↳ 의도한 변경이면: mandu lock");
+    lines.push("   ↳ 패키지 업데이트 직후라면 새 Mandu 기본값으로 lockfile을 갱신하세요.");
+  }
 
   if (result.warnings.length > 0 && result.lockfileExists) {
     lines.push("");

package/src/guard/fs-routes-policy.ts

@@ -0,0 +1,51 @@
+import type { FSRoutesGuardConfig } from "./types";
+
+export const DEFAULT_FS_ROUTES_GUARD_POLICY: FSRoutesGuardConfig = {
+  noPageToPage: true,
+  pageCanImport: [
+    "client/pages",
+    "client/widgets",
+    "client/features",
+    "client/entities",
+    "client/shared",
+    "shared/contracts",
+    "shared/types",
+    "shared/utils/client",
+  ],
+  layoutCanImport: [
+    "client/app",
+    "client/widgets",
+    "client/shared",
+    "shared/contracts",
+    "shared/types",
+    "shared/utils/client",
+  ],
+  routeCanImport: [
+    "server/api",
+    "server/application",
+    "server/domain",
+    "server/infra",
+    "server/core",
+    "shared/contracts",
+    "shared/schema",
+    "shared/types",
+    "shared/utils/client",
+    "shared/utils/server",
+    "shared/env",
+  ],
+};
+
+function clonePolicy(policy: FSRoutesGuardConfig): FSRoutesGuardConfig {
+  return {
+    noPageToPage: policy.noPageToPage,
+    pageCanImport: policy.pageCanImport ? [...policy.pageCanImport] : undefined,
+    layoutCanImport: policy.layoutCanImport ? [...policy.layoutCanImport] : undefined,
+    routeCanImport: policy.routeCanImport ? [...policy.routeCanImport] : undefined,
+  };
+}
+
+export function getDefaultFsRoutesGuardPolicy(
+  enabled: boolean
+): FSRoutesGuardConfig | undefined {
+  return enabled ? clonePolicy(DEFAULT_FS_ROUTES_GUARD_POLICY) : undefined;
+}

package/src/guard/index.ts

@@ -120,12 +120,17 @@ export {
 // Architecture Guard - Watcher
 // ═══════════════════════════════════════════════════════════════════════════
 
-export {
-  createGuardWatcher,
-  checkFile,
-  checkDirectory,
-  clearAnalysisCache,
-} from "./watcher";
+export {
+  createGuardWatcher,
+  checkFile,
+  checkDirectory,
+  clearAnalysisCache,
+} from "./watcher";
+
+export {
+  DEFAULT_FS_ROUTES_GUARD_POLICY,
+  getDefaultFsRoutesGuardPolicy,
+} from "./fs-routes-policy";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Architecture Guard - Presets

package/src/index.ts

@@ -21,8 +21,9 @@ export const __MANDU_CORE_VERSION__: string = (() => {
   }
 })();
 
-export * from "./spec";
-export * from "./runtime";
+export * from "./spec";
+export * from "./agent";
+export * from "./runtime";
 export * from "./generator";
 export * from "./guard";
 export * from "./report";

package/src/router/client-entry.ts

@@ -0,0 +1,71 @@
+import { readFile } from "fs/promises";
+import path from "path";
+import type { RouteSpec } from "../spec/schema";
+
+export function normalizeRouteModulePath(value: string | undefined): string {
+  return (value ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+export function hasUseClientDirective(source: string): boolean {
+  return /^(?:\uFEFF)?\s*(?:(?:\/\/[^\r\n]*(?:\r?\n|$))|(?:\/\*[\s\S]*?\*\/\s*))*["']use client["']\s*;?/.test(source);
+}
+
+export function hasUseServerDirective(source: string): boolean {
+  return /^(?:\uFEFF)?\s*(?:(?:\/\/[^\r\n]*(?:\r?\n|$))|(?:\/\*[\s\S]*?\*\/\s*))*["']use server["']\s*;?/.test(source);
+}
+
+export function clientModuleIsRouteComponent(route: RouteSpec, clientModule = route.clientModule): boolean {
+  if (route.kind !== "page" || !clientModule) return false;
+
+  const client = normalizeRouteModulePath(clientModule);
+  return (
+    client === normalizeRouteModulePath(route.componentModule) ||
+    client === normalizeRouteModulePath(route.module)
+  );
+}
+
+async function readRouteModule(rootDir: string, modulePath: string): Promise<string | null> {
+  try {
+    return await readFile(path.resolve(rootDir, modulePath), "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export async function shouldPreserveExistingClientModule(
+  route: RouteSpec,
+  clientModule: string,
+  rootDir: string,
+): Promise<boolean> {
+  const source = await readRouteModule(rootDir, clientModule);
+  if (source === null) return false;
+  if (hasUseServerDirective(source)) return false;
+  if (clientModuleIsRouteComponent(route, clientModule)) {
+    return hasUseClientDirective(source);
+  }
+  return true;
+}
+
+export async function validateClientModuleForBrowserBundle(
+  route: RouteSpec,
+  rootDir: string,
+): Promise<string | null> {
+  if (!route.clientModule) return null;
+
+  const source = await readRouteModule(rootDir, route.clientModule);
+  if (source === null) return null;
+
+  if (hasUseServerDirective(source)) {
+    return `[${route.id}] Client module "${route.clientModule}" has a "use server" directive and cannot be bundled for the browser.`;
+  }
+
+  if (clientModuleIsRouteComponent(route) && !hasUseClientDirective(source)) {
+    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;
+}

package/src/router/fs-routes.ts

@@ -14,10 +14,11 @@ import { DEFAULT_SCANNER_CONFIG } from "./fs-types";
 import { scanRoutes } from "./fs-scanner";
 import { loadManduConfig } from "../config";
 import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
-import {
-  runOnRouteRegistered,
-  runOnManifestBuilt,
-} from "../plugins/runner";
+import {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+} from "../plugins/runner";
+import { shouldPreserveExistingClientModule } from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -308,10 +309,17 @@ export async function generateManifest(
       for (const route of manifest.routes) {
         const prev = existingMap.get(route.id);
         if (!prev) continue;
-        // 사용자가 설정한 clientModule/hydration 보존
-        if (prev.clientModule && !route.clientModule) {
-          route.clientModule = prev.clientModule;
-        }
+        // 사용자가 설정한 clientModule/hydration 보존.
+        // If app/page.tsx used to be a client page and later becomes a server
+        // page, preserving the old clientModule would leak the server graph into
+        // the browser bundle.
+        if (
+          prev.clientModule &&
+          !route.clientModule &&
+          await shouldPreserveExistingClientModule(route, prev.clientModule, rootDir)
+        ) {
+          route.clientModule = prev.clientModule;
+        }
         if (prev.hydration && !route.hydration) {
           route.hydration = prev.hydration;
         }

package/src/router/fs-scanner.ts

@@ -28,8 +28,9 @@ import {
   sortRoutesByPriority,
   getPatternShape,
 } from "./fs-patterns";
-import { mark, measure } from "../perf";
-import { METADATA_ROUTES } from "../routes/types";
+import { mark, measure } from "../perf";
+import { METADATA_ROUTES } from "../routes/types";
+import { hasUseClientDirective } from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Scanner Class
@@ -390,7 +391,7 @@ export class FSScanner {
         }
       } else if (file.type === "page" && pageFileContent) {
         // page 파일 자체에서 "use client" 확인
-        const hasUseClient = /^\s*["']use client["']/m.test(pageFileContent);
+        const hasUseClient = hasUseClientDirective(pageFileContent);
         if (hasUseClient) {
           clientModule = modulePath;
         }

package/src/runtime/__tests__/page-render-response.test.ts

@@ -1,6 +1,32 @@
 import { describe, expect, it } from "bun:test";
 import React from "react";
 import { renderPageResponse } from "../page-render-response";
+import type { BundleManifest } from "../../bundler/types";
+
+const HYDRATED_MANIFEST: BundleManifest = {
+  version: 1,
+  buildTime: "2026-05-19T00:00:00.000Z",
+  env: "production",
+  bundles: {
+    home: {
+      js: "/.mandu/client/home.island.js",
+      dependencies: ["_runtime", "_react"],
+      priority: "visible",
+    },
+  },
+  shared: {
+    runtime: "/.mandu/client/_runtime.js",
+    vendor: "/.mandu/client/_react.js",
+    router: "/.mandu/client/_router.js",
+  },
+  importMap: {
+    imports: {
+      react: "/.mandu/client/_react.js",
+      "react-dom": "/.mandu/client/_react-dom.js",
+      "react-dom/client": "/.mandu/client/_react-dom-client.js",
+    },
+  },
+};
 
 describe("runtime page render response orchestration", () => {
   it("pre-resolves async components on the non-streaming path", async () => {
@@ -51,4 +77,27 @@ describe("runtime page render response orchestration", () => {
     expect(html).toContain("stream-page");
     expect(html).toContain("Stream Page");
   });
+
+  it("serializes non-streaming loaderData as the route server data exactly once", async () => {
+    const response = await renderPageResponse({
+      app: React.createElement("main", null, "hydrated-page"),
+      useStreaming: false,
+      title: "Hydrated Page",
+      headTags: "",
+      isDev: false,
+      routeId: "home",
+      routePattern: "/",
+      loaderData: { items: ["a", "b"] },
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: HYDRATED_MANIFEST,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html).toContain('"home":{"serverData":{"items":["a","b"]}');
+    expect(html).not.toContain('"serverData":{"home"');
+  });
 });

package/src/runtime/page-render-response.ts

@@ -84,10 +84,6 @@ function renderNonStreamingPageResponse(
   app: React.ReactElement,
   options: PageRenderResponseOptions
 ): Response {
-  const serverData = options.loaderData
-    ? { [options.routeId]: { serverData: options.loaderData } }
-    : undefined;
-
   return renderSSR(app, {
     title: options.title,
     headTags: options.headTags,
@@ -96,7 +92,7 @@ function renderNonStreamingPageResponse(
     routeId: options.routeId,
     hydration: options.hydration,
     bundleManifest: options.bundleManifest,
-    serverData,
+    serverData: options.loaderData,
     enableClientRouter: true,
     routePattern: options.routePattern,
     cssPath: options.cssPath,