@mandujs/core 0.54.11 → 0.54.13

package/src/bundler/__tests__/cold-start.test.ts

@@ -28,13 +28,13 @@ import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import path from "path";
-import type { RouteSpec, RoutesManifest } from "../../spec/schema";
-import {
-  _testOnly_scanIslandFiles,
-  _testOnly_scanPartialFiles,
-  _testOnly_getHydratedRoutes,
-  _testOnly_getHydrationRoutesMissingClientModule,
-} from "../build";
+import type { RouteSpec, RoutesManifest } from "../../spec/schema";
+import {
+  _testOnly_scanIslandFiles,
+  _testOnly_scanPartialFiles,
+  _testOnly_getHydratedRoutes,
+  _testOnly_getHydrationRoutesMissingClientModule,
+} from "../build";
 import { HMR_PERF } from "../../perf/hmr-markers";
 import {
   _resetCacheForTesting as _resetPerfCache,
@@ -374,7 +374,7 @@ describe("Phase 7.1 R1 Agent C — getHydratedRoutes filter", () => {
   });
 });
 
-describe("Phase 7.1 R1 Agent C — per-island scan skips non-hydrated routes", () => {
+describe("Phase 7.1 R1 Agent C — per-island scan skips non-hydrated routes", () => {
   let project: ReturnType<typeof createProject>;
 
   beforeEach(() => {
@@ -502,55 +502,55 @@ describe("Phase 7.1 R1 Agent C — per-island scan skips non-hydrated routes", (
     ];
     const result = await _testOnly_scanIslandFiles(routes, project.rootDir);
     expect(result).toEqual([]);
-  });
-});
-
-describe("hydration route validation", () => {
-  it("finds pages that request hydration without a client module", () => {
-    const manifest = {
-      version: 1,
-      routes: [
-        {
-          id: "login",
-          pattern: "/login",
-          kind: "page",
-          module: "app/login/page.tsx",
-          componentModule: "app/login/page.tsx",
-          hydration: { strategy: "full", priority: "immediate", preload: false },
-        },
-        pureSsrRoute("about", "/about", "app/about"),
-        pageRoute("dashboard", "/dashboard", "app/dashboard"),
-      ],
-    } as RoutesManifest;
-
-    const missing = _testOnly_getHydrationRoutesMissingClientModule(manifest);
-    expect(missing.map((route) => route.id)).toEqual(["login"]);
-  });
-});
-
-describe("partial bundle scan", () => {
-  let project: ReturnType<typeof createProject>;
-
-  beforeEach(() => {
-    project = createProject();
-  });
-
-  afterEach(() => {
-    try {
-      rmSync(project.rootDir, { recursive: true, force: true });
-    } catch {
-      /* Windows lock tolerance */
-    }
-  });
-
-  it("discovers *.partial.tsx files outside .mandu and node_modules", async () => {
-    project.writeIslandFile("app", "Home.partial.tsx");
-    project.writeIslandFile(".mandu/client", "Stale.partial.tsx");
-    project.writeIslandFile("node_modules/pkg", "Ignored.partial.tsx");
-
-    const result = await _testOnly_scanPartialFiles(project.rootDir);
-
-    expect(result.map((entry) => entry.name)).toEqual(["Home"]);
-    expect(result[0].priority).toBe("visible");
-  });
-});
+  });
+});
+
+describe("hydration route validation", () => {
+  it("finds pages that request hydration without a client module", () => {
+    const manifest = {
+      version: 1,
+      routes: [
+        {
+          id: "login",
+          pattern: "/login",
+          kind: "page",
+          module: "app/login/page.tsx",
+          componentModule: "app/login/page.tsx",
+          hydration: { strategy: "full", priority: "immediate", preload: false },
+        },
+        pureSsrRoute("about", "/about", "app/about"),
+        pageRoute("dashboard", "/dashboard", "app/dashboard"),
+      ],
+    } as RoutesManifest;
+
+    const missing = _testOnly_getHydrationRoutesMissingClientModule(manifest);
+    expect(missing.map((route) => route.id)).toEqual(["login"]);
+  });
+});
+
+describe("partial bundle scan", () => {
+  let project: ReturnType<typeof createProject>;
+
+  beforeEach(() => {
+    project = createProject();
+  });
+
+  afterEach(() => {
+    try {
+      rmSync(project.rootDir, { recursive: true, force: true });
+    } catch {
+      /* Windows lock tolerance */
+    }
+  });
+
+  it("discovers *.partial.tsx files outside .mandu and node_modules", async () => {
+    project.writeIslandFile("app", "Home.partial.tsx");
+    project.writeIslandFile(".mandu/client", "Stale.partial.tsx");
+    project.writeIslandFile("node_modules/pkg", "Ignored.partial.tsx");
+
+    const result = await _testOnly_scanPartialFiles(project.rootDir);
+
+    expect(result.map((entry) => entry.name)).toEqual(["Home"]);
+    expect(result[0].priority).toBe("visible");
+  });
+});

package/src/bundler/__tests__/css.test.ts

@@ -1,20 +1,20 @@
-import { describe, expect, test } from "bun:test";
-import { __private } from "../css";
-
-describe("CSS Tailwind command resolution", () => {
-  test("uses process.execPath when it is Bun", () => {
-    expect(
-      __private.getTailwindCommand(["@tailwindcss/cli"], "C:\\tools\\bun.exe"),
-    ).toEqual(["C:\\tools\\bun.exe", "x", "@tailwindcss/cli"]);
-  });
-
-  test("does not treat standalone mandu.exe as Bun", () => {
-    expect(
-      __private.getTailwindCommand(
-        ["@tailwindcss/cli"],
-        "C:\\Users\\User\\AppData\\Local\\Mandu\\bin\\mandu.exe",
-        () => "C:\\Users\\User\\.bun\\bin\\bun.exe",
-      ),
-    ).toEqual(["C:\\Users\\User\\.bun\\bin\\bun.exe", "x", "@tailwindcss/cli"]);
-  });
-});
+import { describe, expect, test } from "bun:test";
+import { __private } from "../css";
+
+describe("CSS Tailwind command resolution", () => {
+  test("uses process.execPath when it is Bun", () => {
+    expect(
+      __private.getTailwindCommand(["@tailwindcss/cli"], "C:\\tools\\bun.exe"),
+    ).toEqual(["C:\\tools\\bun.exe", "x", "@tailwindcss/cli"]);
+  });
+
+  test("does not treat standalone mandu.exe as Bun", () => {
+    expect(
+      __private.getTailwindCommand(
+        ["@tailwindcss/cli"],
+        "C:\\Users\\User\\AppData\\Local\\Mandu\\bin\\mandu.exe",
+        () => "C:\\Users\\User\\.bun\\bin\\bun.exe",
+      ),
+    ).toEqual(["C:\\Users\\User\\.bun\\bin\\bun.exe", "x", "@tailwindcss/cli"]);
+  });
+});

package/src/bundler/analyzer.ts

@@ -341,26 +341,26 @@ export async function analyzeBundle(
       deps: entry.dependencies ?? [],
     });
   }
-  for (const [islandName, entry] of Object.entries(manifest.islands ?? {})) {
-    // Avoid double-counting: if a per-island chunk shares its route id with
-    // a route-level bundle, we prefer the island entry (finer granularity).
-    const existing = islandSources.findIndex((s) => s.name === islandName);
+  for (const [islandName, entry] of Object.entries(manifest.islands ?? {})) {
+    // Avoid double-counting: if a per-island chunk shares its route id with
+    // a route-level bundle, we prefer the island entry (finer granularity).
+    const existing = islandSources.findIndex((s) => s.name === islandName);
     if (existing !== -1) islandSources.splice(existing, 1);
     islandSources.push({
       name: islandName,
       url: entry.js,
       priority: entry.priority,
-      deps: [],
-    });
-  }
-  for (const [partialName, entry] of Object.entries(manifest.partials ?? {})) {
-    islandSources.push({
-      name: `partial:${partialName}`,
-      url: entry.js,
-      priority: entry.priority,
-      deps: [],
-    });
-  }
+      deps: [],
+    });
+  }
+  for (const [partialName, entry] of Object.entries(manifest.partials ?? {})) {
+    islandSources.push({
+      name: `partial:${partialName}`,
+      url: entry.js,
+      priority: entry.priority,
+      deps: [],
+    });
+  }
 
   const islands: AnalyzeIsland[] = [];
   for (const src of islandSources) {

package/src/bundler/build.test.ts

@@ -219,7 +219,7 @@ describe("buildClientBundles vendor shims", () => {
     }
   });
 
-  test("rewrites route-component clientModule to the real client import before bundling", async () => {
+  test("rewrites route-component clientModule to the real client import before bundling", async () => {
     const routeClientRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-route-client-import-"));
     try {
       await mkdir(path.join(routeClientRoot, "app", "login"), { recursive: true });
@@ -239,19 +239,85 @@ describe("buildClientBundles vendor shims", () => {
       );
       await writeFile(
         path.join(routeClientRoot, "src", "client", "pages", "login", "LoginPage.client.tsx"),
-        '"use client";\nexport default function LoginPage() { return <form />; }\n',
+        '"use client";\n' +
+          'import { useState } from "react";\n' +
+          "export default function LoginPage() {\n" +
+          '  const [email, setEmail] = useState("");\n' +
+          '  return <form><input value={email} onChange={(event) => setEmail(event.currentTarget.value)} /></form>;\n' +
+          "}\n",
         "utf-8",
       );
 
       const routeClientResult = await runBuildInSubprocess(routeClientRoot, "server-page-route-client-import");
       expect(routeClientResult.success).toBe(true);
-      expect(await Bun.file(path.join(routeClientRoot, ".mandu", "client", "login.island.js")).exists()).toBe(true);
+      const bundlePath = path.join(routeClientRoot, ".mandu", "client", "login.island.js");
+      expect(await Bun.file(bundlePath).exists()).toBe(true);
+
+      const bundleSource = await readFile(bundlePath, "utf-8");
+      expect(bundleSource).not.toContain("var LoginPage = LoginPage;");
+      const parseResult = await Bun.build({
+        entrypoints: [bundlePath],
+        target: "browser",
+        external: ["react", "react-dom", "react-dom/client", "react/jsx-dev-runtime"],
+      });
+      expect(parseResult.success).toBe(true);
     } finally {
       await rm(routeClientRoot, { recursive: true, force: true });
-    }
-  });
-
-  test("fails when hydration is enabled but no clientModule can be resolved", async () => {
+    }
+  });
+
+  test("bundles route-level named client exports without requiring a default export", async () => {
+    const routeClientRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-route-named-client-import-"));
+    try {
+      await mkdir(path.join(routeClientRoot, "app", "login"), { recursive: true });
+      await mkdir(path.join(routeClientRoot, "src", "client", "pages", "login"), { recursive: true });
+      await writeFile(
+        path.join(routeClientRoot, "package.json"),
+        JSON.stringify({ name: "mandu-route-named-client-import-test", type: "module" }, null, 2),
+        "utf-8",
+      );
+      await writeFile(
+        path.join(routeClientRoot, "app", "login", "page.tsx"),
+        'import { LoginPage } from "@/client/pages/login/LoginPage.client";\n' +
+          "export default function Page() {\n" +
+          "  return <LoginPage />;\n" +
+          "}\n",
+        "utf-8",
+      );
+      await writeFile(
+        path.join(routeClientRoot, "src", "client", "pages", "login", "LoginPage.client.tsx"),
+        '"use client";\n' +
+          'import { useState } from "react";\n' +
+          "export function LoginPage() {\n" +
+          '  const [email, setEmail] = useState("");\n' +
+          '  return <form><input value={email} onChange={(event) => setEmail(event.currentTarget.value)} /></form>;\n' +
+          "}\n",
+        "utf-8",
+      );
+
+      const routeClientResult = await runBuildInSubprocess(routeClientRoot, "server-page-route-named-client-import");
+      if (!routeClientResult.success) {
+        console.error("[named route client] errors:", routeClientResult.errors);
+      }
+      expect(routeClientResult.success).toBe(true);
+      const bundlePath = path.join(routeClientRoot, ".mandu", "client", "login.island.js");
+      expect(await Bun.file(bundlePath).exists()).toBe(true);
+
+      const bundleSource = await readFile(bundlePath, "utf-8");
+      expect(bundleSource).toContain("LoginPage");
+      expect(bundleSource).not.toContain("Client islands cannot use server-side modules");
+      const parseResult = await Bun.build({
+        entrypoints: [bundlePath],
+        target: "browser",
+        external: ["react", "react-dom", "react-dom/client", "react/jsx-dev-runtime"],
+      });
+      expect(parseResult.success).toBe(true);
+    } finally {
+      await rm(routeClientRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("fails when hydration is enabled but no clientModule can be resolved", async () => {
     const missingRoot = await mkdtemp(path.join(import.meta.dir, ".tmp-hydration-no-client-"));
     try {
       await mkdir(path.join(missingRoot, "app", "login"), { recursive: true });

package/src/bundler/build.ts

@@ -104,6 +104,9 @@ function nodeEnvDefine(options: BundlerOptions): string {
   return JSON.stringify(resolveBundlerMode(options));
 }
 
+const FAST_REFRESH_SELF_ALIAS_PATTERN =
+  /^var\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*\1;\s*\r?\n(?=\$RefreshReg\$\(\1,\s*["'][^"']*:default["']\);)/gm;
+
 function resolveClientOutDir(rootDir: string, outDir?: string): string {
   const defaultOutDir = path.join(rootDir, ".mandu/client");
   if (!outDir) return defaultOutDir;
@@ -321,6 +324,7 @@ async function buildPerIslandBundle(
       const grouped = result.logs.map((l) => `  - ${l.message}`).join("\n");
       throw new Error(`Island build failed for '${entry.name}' (source: ${entry.filePath}):\n${grouped}\n  Hint: Check the import paths and TypeScript types in this island file.`);
     }
+    await sanitizeGeneratedClientBundle(path.join(outDir, outputName), isDev);
     return { name: entry.name, js: `/.mandu/client/${outputName}`, route: entry.routeId, priority: entry.priority };
   } catch (error) {
     await fs.unlink(entryPath).catch(() => {});
@@ -368,9 +372,9 @@ async function buildPartialBundle(
     }
 
     const outputPath = path.join(outDir, outputName);
+    const sanitizedContent = await sanitizeGeneratedClientBundle(outputPath, isDev);
     const outputFile = Bun.file(outputPath);
-    const content = await outputFile.text();
-    const gzipped = Bun.gzipSync(Buffer.from(content));
+    const gzipped = Bun.gzipSync(Buffer.from(sanitizedContent));
 
     return {
       name: entry.name,
@@ -1439,18 +1443,61 @@ async function buildRouterRuntime(
  * - Runtime이 dynamic import로 로드
  * - 등록/초기화 코드 없음
  */
-function generateIslandEntry(routeId: string, clientModulePath: string): string {
-  // Windows 경로의 백슬래시를 슬래시로 변환 (JS escape 문제 방지)
-  const normalizedPath = clientModulePath.replace(/\\/g, "/");
-  return `
-/**
- * Mandu Island: ${routeId} (Generated)
- * Pure export - no side effects
- */
-import island from "${normalizedPath}";
-export default island;
-`;
-}
+function generateIslandEntry(routeId: string, clientModulePath: string, exportName?: string): string {
+  // Windows 경로의 백슬래시를 슬래시로 변환 (JS escape 문제 방지)
+  const normalizedPath = clientModulePath.replace(/\\/g, "/");
+  const normalizedExportName = exportName && exportName !== "default" ? exportName : undefined;
+  const candidates = [
+    normalizedExportName,
+    inferClientExportNameFromPath(clientModulePath),
+    inferClientExportNameFromRouteId(routeId),
+  ].filter((candidate, index, values): candidate is string =>
+    !!candidate && values.indexOf(candidate) === index
+  );
+  const importSpecifier = JSON.stringify(normalizedPath);
+  const routeLabel = JSON.stringify(routeId);
+  const commentRouteId = routeId.replace(/\*\//g, "* /");
+  return `
+/**
+ * Mandu Island: ${commentRouteId} (Generated)
+ * Pure export - no side effects
+ */
+import * as islandModule from ${importSpecifier};
+
+const candidateExportNames = ${JSON.stringify(candidates)};
+
+function resolveIslandExport(mod) {
+  if (mod.default) return mod.default;
+  for (const name of candidateExportNames) {
+    if (mod[name]) return mod[name];
+  }
+  const runtimeExports = Object.keys(mod).filter((name) => name !== "__esModule");
+  if (runtimeExports.length === 1) return mod[runtimeExports[0]];
+  throw new Error(
+    "[Mandu Island] " + ${routeLabel} + " must export a default component" +
+      (candidateExportNames.length > 0 ? " or one of: " + candidateExportNames.join(", ") : "")
+  );
+}
+
+const island = resolveIslandExport(islandModule);
+export default island;
+`;
+}
+
+function inferClientExportNameFromPath(clientModulePath: string): string | null {
+  const basename = path.basename(clientModulePath).replace(/\.[cm]?[jt]sx?$/, "");
+  const withoutClientSuffix = basename.replace(/\.(client|island)$/, "");
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(withoutClientSuffix) ? withoutClientSuffix : null;
+}
+
+function inferClientExportNameFromRouteId(routeId: string): string | null {
+  const pascal = routeId
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(pascal) ? pascal : null;
+}
 
 function generatePartialEntry(partialId: string, partialModulePath: string): string {
   const normalizedPath = partialModulePath.replace(/\\/g, "/");
@@ -1907,7 +1954,7 @@ async function buildIsland(
   const isDev = isDevelopmentBuild(options);
   try {
     // 엔트리 래퍼 생성
-    await Bun.write(entryPath, generateIslandEntry(route.id, clientModulePath));
+    await Bun.write(entryPath, generateIslandEntry(route.id, clientModulePath, route.clientExportName));
 
     // 빌드
     // splitting 옵션: true면 공통 코드를 별도 청크로 추출
@@ -1960,7 +2007,7 @@ async function buildIsland(
     }
 
     const outputFile = Bun.file(actualOutputPath);
-    const content = await outputFile.text();
+    const content = await sanitizeGeneratedClientBundle(actualOutputPath, isDev);
     const gzipped = Bun.gzipSync(Buffer.from(content));
 
     return {
@@ -1976,6 +2023,48 @@ async function buildIsland(
   }
 }
 
+async function sanitizeGeneratedClientBundle(outputPath: string, isDev: boolean): Promise<string> {
+  const source = await Bun.file(outputPath).text();
+  if (!isDev) return source;
+
+  const sanitized = removeFastRefreshSelfAliases(source);
+  if (sanitized === source) return source;
+
+  await Bun.write(outputPath, sanitized);
+  await validateGeneratedClientBundle(outputPath);
+  return sanitized;
+}
+
+function removeFastRefreshSelfAliases(source: string): string {
+  return source.replace(FAST_REFRESH_SELF_ALIAS_PATTERN, (line, localName: string, offset: number) => {
+    const priorSource = source.slice(0, offset);
+    const declarationPattern = new RegExp(`(?:const|let|class|function)\\s+${escapeRegExp(localName)}\\b`);
+    return declarationPattern.test(priorSource) ? "" : line;
+  });
+}
+
+async function validateGeneratedClientBundle(outputPath: string): Promise<void> {
+  const tempOutDir = await fs.mkdtemp(path.join(path.dirname(outputPath), ".validate-"));
+  try {
+    const result = await safeBuild({
+      entrypoints: [outputPath],
+      outdir: tempOutDir,
+      target: "browser",
+      external: ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime"],
+    });
+    if (result.success) return;
+
+    const grouped = result.logs.map((log) => `  - ${log.message}`).join("\n");
+    throw new Error(`Generated client bundle failed syntax validation (source: ${outputPath}):\n${grouped}`);
+  } finally {
+    await fs.rm(tempOutDir, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 /**
  * 번들 매니페스트 생성
  */
@@ -2513,25 +2602,24 @@ export async function buildClientBundles(
       try {
         return { ok: true as const, result: await buildIsland(route, rootDir, outDir, options) };
       } catch (error) {
-        return { ok: false as const, route, error: String(error) };
+        return { ok: false as const, route, error: formatBundlerException(error) };
       }
     }),
   );
   for (const r of fullIslandResults) {
-    if (r.ok) {
-      outputs.push(r.result);
-    } else {
-      const errorStr = r.error;
-      if (errorStr.includes("AggregateError") || errorStr.includes("Could not resolve")) {
-        const clientModule = r.route.clientModule || "";
-        errors.push(
-          `[${r.route.id}] ${errorStr}\n` +
-          `  💡 Hint: If your island imports from "@mandujs/core", change it to "@mandujs/core/client".\n` +
-          `     Client islands cannot use server-side modules. File: ${clientModule}`,
-        );
-      } else {
-        errors.push(`[${r.route.id}] ${errorStr}`);
-      }
+    if (r.ok) {
+      outputs.push(r.result);
+    } else {
+      const errorStr = r.error;
+      if (errorStr.includes("AggregateError") || errorStr.includes("Could not resolve")) {
+        const clientModule = r.route.clientModule || "";
+        errors.push(
+          `[${r.route.id}] ${errorStr}\n` +
+          `  Hint: Check import paths and browser-compatible exports for this island. File: ${clientModule}`,
+        );
+      } else {
+        errors.push(`[${r.route.id}] ${errorStr}`);
+      }
     }
   }
 
@@ -2632,6 +2720,12 @@ export function printBundleStats(result: BundleResult): void {
   const partialCount = Object.keys(result.manifest.partials ?? {}).length;
   if (result.outputs.length === 0 && partialCount === 0) {
     console.log("No islands or partials to bundle (hydration: none or no client entry)");
+    if (result.errors.length > 0) {
+      console.log("\n⚠️ Errors:");
+      for (const error of result.errors) {
+        console.log(`  ${error}`);
+      }
+    }
     return;
   }
 
@@ -2661,3 +2755,17 @@ export function printBundleStats(result: BundleResult): void {
 
   console.log("");
 }
+
+function formatBundlerException(error: unknown): string {
+  if (error instanceof AggregateError) {
+    const parts = [String(error)];
+    for (const nested of error.errors) {
+      parts.push(`  - ${formatBundlerException(nested).replace(/\n/g, "\n    ")}`);
+    }
+    return parts.join("\n");
+  }
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  return String(error);
+}

package/src/bundler/css.ts

@@ -18,38 +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)
- * `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];
-}
+/**
+ * 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 ==========
 
@@ -344,13 +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 const __private = {
-  getTailwindCommand,
-  isBunExecutable,
-  resolveBunExecutable,
-};
+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,
+};