@mandujs/core 0.54.12 → 0.54.13

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

@@ -40,10 +40,11 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toEqual({
-      module: "@/client/pages/login/LoginPage.client",
-      localName: "LoginPage",
-    });
+    expect(routeClient).toEqual({
+      module: "@/client/pages/login/LoginPage.client",
+      localName: "LoginPage",
+      exportName: "default",
+    });
   });
 
   it("promotes a fragment wrapper with head-only elements and a bare client component", () => {
@@ -58,10 +59,11 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toEqual({
-      module: "@/client/pages/home/HomeApp.client",
-      localName: "HomeApp",
-    });
+    expect(routeClient).toEqual({
+      module: "@/client/pages/home/HomeApp.client",
+      localName: "HomeApp",
+      exportName: "default",
+    });
   });
 
   it("detects a named-imported client component when the page returns only that component", () => {
@@ -73,11 +75,28 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toEqual({
-      module: "@/client/pages/notifications/NotificationsPage.client",
-      localName: "NotificationsPage",
-    });
-  });
+    expect(routeClient).toEqual({
+      module: "@/client/pages/notifications/NotificationsPage.client",
+      localName: "NotificationsPage",
+      exportName: "NotificationsPage",
+    });
+  });
+
+  it("preserves the source export name for aliased named imports", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import { NotificationsPage as PageIsland } from "@/client/pages/notifications/NotificationsPage.client";
+
+      export default function Page() {
+        return <PageIsland />;
+      }
+    `);
+
+    expect(routeClient).toEqual({
+      module: "@/client/pages/notifications/NotificationsPage.client",
+      localName: "PageIsland",
+      exportName: "NotificationsPage",
+    });
+  });
 
   it("promotes embedded client imports inside a larger server page", () => {
     const routeClient = findRouteLevelClientComponentImport(`
@@ -91,10 +110,11 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toEqual({
-      module: "@/client/pages/home/HomeApp.client",
-      localName: "HomeApp",
-    });
+    expect(routeClient).toEqual({
+      module: "@/client/pages/home/HomeApp.client",
+      localName: "HomeApp",
+      exportName: "default",
+    });
   });
 
   it("promotes client imports when the page wrapper passes props", () => {
@@ -106,10 +126,11 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toEqual({
-      module: "@/client/pages/pledges/PledgePage.client",
-      localName: "PledgePage",
-    });
+    expect(routeClient).toEqual({
+      module: "@/client/pages/pledges/PledgePage.client",
+      localName: "PledgePage",
+      exportName: "default",
+    });
   });
 
   it("detects multiple rendered client imports in a server shell", () => {
@@ -130,14 +151,16 @@ describe("findClientComponentImports", () => {
     `);
 
     expect(routeClients).toEqual([
-      {
-        module: "@/client/widgets/comments-section/CommentsSection.client",
-        localName: "CommentsSection",
-      },
-      {
-        module: "@/client/widgets/pledge-actions/PledgeActions.client",
-        localName: "PledgeActions",
-      },
+      {
+        module: "@/client/widgets/comments-section/CommentsSection.client",
+        localName: "CommentsSection",
+        exportName: "CommentsSection",
+      },
+      {
+        module: "@/client/widgets/pledge-actions/PledgeActions.client",
+        localName: "PledgeActions",
+        exportName: "PledgeActions",
+      },
     ]);
   });
 
@@ -150,10 +173,23 @@ describe("findClientComponentImports", () => {
       }
     `);
 
-    expect(routeClient).toEqual({
-      module: "@/client/widgets/pledge-form/PledgeForm",
-      localName: "PledgeForm",
-    });
+    expect(routeClient).toEqual({
+      module: "@/client/widgets/pledge-form/PledgeForm",
+      localName: "PledgeForm",
+      exportName: "PledgeForm",
+    });
+  });
+
+  it("does not promote shared UI primitives to route-level client entries", () => {
+    const routeClient = findRouteLevelClientComponentImport(`
+      import { Button } from "@/client/shared/ui/button";
+
+      export default function Page() {
+        return <main><Button>Open</Button></main>;
+      }
+    `);
+
+    expect(routeClient).toBeNull();
   });
 
   it("resolves a route-level client entry by reading a use client target without .client in the path", async () => {

package/src/router/client-entry.ts

@@ -8,12 +8,23 @@ export interface ClientComponentImport {
   names: string[];
 }
 
-export interface RouteLevelClientComponentImport {
-  module: string;
-  localName: string;
-}
-
-const CLIENT_ENTRY_SPECIFIER_PATTERN = /\.(?:client|island)(?:\.[tj]sx?)?$/;
+export interface RouteLevelClientComponentImport {
+  module: string;
+  localName: string;
+  exportName: string;
+}
+
+const CLIENT_ENTRY_SPECIFIER_PATTERN = /\.(?:client|island)(?:\.[tj]sx?)?$/;
+const DEFAULT_EXPORT_NAME = "default";
+
+interface ComponentImportSpecifier {
+  importedName: string;
+  localName: string;
+}
+
+interface ComponentImportRecord extends ClientComponentImport {
+  specifiers: ComponentImportSpecifier[];
+}
 
 export function normalizeRouteModulePath(value: string | undefined): string {
   return (value ?? "").replace(/\\/g, "/").replace(/^\.\//, "");
@@ -45,45 +56,64 @@ async function readRouteModule(rootDir: string, modulePath: string): Promise<str
   }
 }
 
-export function findClientComponentImports(source: string): ClientComponentImport[] {
-  return findComponentImports(source).filter((entry) => clientSpecifierLooksBrowserOnly(entry.module));
-}
-
-function findComponentImports(source: string): ClientComponentImport[] {
-  const imports: ClientComponentImport[] = [];
-  const importFromPattern = /import\s+(?!type\b)([\s\S]*?)\s+from\s+["']([^"']+)["']/g;
-  const sideEffectPattern = /import\s+["']([^"']+)["']/g;
+export function findClientComponentImports(source: string): ClientComponentImport[] {
+  return findComponentImportRecords(source)
+    .filter((entry) => clientSpecifierLooksBrowserOnly(entry.module))
+    .map(toPublicClientComponentImport);
+}
+
+function toPublicClientComponentImport(entry: ComponentImportRecord): ClientComponentImport {
+  return {
+    module: entry.module,
+    kind: entry.kind,
+    names: entry.names,
+  };
+}
+
+function findComponentImportRecords(source: string): ComponentImportRecord[] {
+  const imports: ComponentImportRecord[] = [];
+  const importFromPattern = /import\s+(?!type\b)([\s\S]*?)\s+from\s+["']([^"']+)["']/g;
+  const sideEffectPattern = /import\s+["']([^"']+)["']/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 module = match[2] ?? "";
+    const names: string[] = [];
+    const specifiers: ComponentImportSpecifier[] = [];
+    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;
-        const parts = name.split(/\s+as\s+/i).map((part) => part.trim()).filter(Boolean);
-        names.push(parts[1] ?? parts[0]);
-      }
-    }
-
-    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 name = rawName.trim();
+        if (!name) continue;
+        const parts = name.split(/\s+as\s+/i).map((part) => part.trim()).filter(Boolean);
+        const importedName = parts[0] ?? "";
+        const localName = parts[1] ?? importedName;
+        names.push(localName);
+        specifiers.push({ importedName, localName });
+      }
+    }
+
+    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]);
+        specifiers.push({ importedName: "*", localName: namespaceMatch[1] });
+      }
+    }
+
+    const beforeNamed = clause.split("{")[0]?.replace(/,\s*$/, "").trim() ?? "";
+    if (beforeNamed && !beforeNamed.startsWith("*")) {
+      hasDefault = true;
+      const localName = beforeNamed.split(",")[0].trim();
+      names.push(localName);
+      specifiers.push({ importedName: DEFAULT_EXPORT_NAME, localName });
+    }
 
     const kind =
       (hasDefault && (hasNamed || hasNamespace))
@@ -94,33 +124,51 @@ function findComponentImports(source: string): ClientComponentImport[] {
             ? "namespace"
             : "default";
 
-    imports.push({ module, kind, names });
-  }
+    imports.push({ module, kind, names, specifiers });
+  }
 
   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;
+    imports.push({ module, kind: "side-effect", names: [], specifiers: [] });
+  }
+
+  return imports;
 }
 
 export function findRouteLevelClientComponentImport(source: string): RouteLevelClientComponentImport | null {
   return findRouteLevelClientComponentImports(source)[0] ?? null;
 }
 
-export function findRouteLevelClientComponentImports(source: string): RouteLevelClientComponentImport[] {
-  const candidates = findComponentImports(source).flatMap((entry) =>
-    entry.names
-      .filter((localName) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(localName))
-      .map((localName) => ({ module: entry.module, localName }))
-  );
+export function findRouteLevelClientComponentImports(source: string): RouteLevelClientComponentImport[] {
+  const candidates = findComponentImportRecords(source).flatMap((entry) =>
+    isRouteLevelClientEntrySpecifier(entry.module)
+      ? entry.specifiers
+          .filter((specifier) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(specifier.localName))
+          .map((specifier) => ({
+            module: entry.module,
+            localName: specifier.localName,
+            exportName: specifier.importedName,
+          }))
+      : []
+  );
 
   if (candidates.length === 0) return [];
   return defaultExportRendersClientComponents(source, candidates);
 }
 
+function isRouteLevelClientEntrySpecifier(specifier: string): boolean {
+  const normalized = specifier.replace(/\\/g, "/");
+  if (
+    normalized.includes("/client/shared/") ||
+    normalized.startsWith("@/client/shared/") ||
+    normalized.startsWith("src/client/shared/")
+  ) {
+    return false;
+  }
+  return true;
+}
+
 export async function resolveClientImportModulePath(
   rootDir: string,
   importerModule: string,
@@ -138,31 +186,42 @@ export async function resolveClientImportModulePath(
   return null;
 }
 
-export async function resolveRouteLevelClientEntryPath(
-  rootDir: string,
-  routeModule: string,
-  source: string,
-): Promise<string | null> {
-  const routeLevelClientImports = findRouteLevelClientComponentImports(source);
-  for (const routeLevelClientImport of routeLevelClientImports) {
-    const resolved = await resolveClientImportModulePath(rootDir, routeModule, routeLevelClientImport.module);
-    if (!resolved) continue;
-    if (clientSpecifierLooksBrowserOnly(routeLevelClientImport.module)) return resolved;
-
-    const importedSource = await readRouteModule(rootDir, resolved);
-    if (importedSource !== null && hasUseClientDirective(importedSource)) {
-      return resolved;
-    }
-  }
-
-  return null;
-}
+export async function resolveRouteLevelClientEntryPath(
+  rootDir: string,
+  routeModule: string,
+  source: string,
+): Promise<string | null> {
+  return (await resolveRouteLevelClientEntry(rootDir, routeModule, source))?.modulePath ?? null;
+}
+
+export async function resolveRouteLevelClientEntry(
+  rootDir: string,
+  routeModule: string,
+  source: string,
+): Promise<{ modulePath: string; exportName: string } | null> {
+  const routeLevelClientImports = findRouteLevelClientComponentImports(source);
+  for (const routeLevelClientImport of routeLevelClientImports) {
+    const resolved = await resolveClientImportModulePath(rootDir, routeModule, routeLevelClientImport.module);
+    if (!resolved) continue;
+    if (clientSpecifierLooksBrowserOnly(routeLevelClientImport.module)) {
+      return { modulePath: resolved, exportName: routeLevelClientImport.exportName };
+    }
+
+    const importedSource = await readRouteModule(rootDir, resolved);
+    if (importedSource !== null && hasUseClientDirective(importedSource)) {
+      return { modulePath: resolved, exportName: routeLevelClientImport.exportName };
+    }
+  }
+
+  return null;
+}
 
 export async function shouldPreserveExistingClientModule(
   route: RouteSpec,
   clientModule: string,
   rootDir: string,
 ): Promise<boolean> {
+  if (!isRouteLevelClientEntrySpecifier(clientModule)) return false;
   const source = await readRouteModule(rootDir, clientModule);
   if (source === null) return false;
   if (hasUseServerDirective(source)) return false;
@@ -446,12 +505,13 @@ export async function validateClientModuleForBrowserBundle(
     return `[${route.id}] Client module "${route.clientModule}" has a "use server" directive and cannot be bundled for the browser.`;
   }
 
-  if (clientModuleIsRouteComponent(route) && !hasUseClientDirective(source)) {
-    const realClientEntry = await resolveRouteLevelClientEntryPath(rootDir, route.clientModule, source);
-    if (realClientEntry) {
-      route.clientModule = realClientEntry;
-      return null;
-    }
+  if (clientModuleIsRouteComponent(route) && !hasUseClientDirective(source)) {
+    const realClientEntry = await resolveRouteLevelClientEntry(rootDir, route.clientModule, source);
+    if (realClientEntry) {
+      route.clientModule = realClientEntry.modulePath;
+      route.clientExportName = realClientEntry.exportName;
+      return null;
+    }
     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. ` +

package/src/router/fs-routes.ts

@@ -14,11 +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 { shouldPreserveExistingClientModule } from "./client-entry";
+import {
+  runOnRouteRegistered,
+  runOnManifestBuilt,
+} from "../plugins/runner";
+import { shouldPreserveExistingClientModule } from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types
@@ -87,12 +87,13 @@ export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
       ...base,
       kind: "page" as const,
       componentModule: normalizePath(fsRoute.componentModule ?? ""),
-      ...(fsRoute.clientModule
-        ? {
-            clientModule: normalizePath(fsRoute.clientModule),
-            hydration: fsRoute.hydration ?? {
-              strategy: "island" as const,
-              priority: "immediate" as const,
+      ...(fsRoute.clientModule
+        ? {
+            clientModule: normalizePath(fsRoute.clientModule),
+            ...(fsRoute.clientExportName ? { clientExportName: fsRoute.clientExportName } : {}),
+            hydration: fsRoute.hydration ?? {
+              strategy: "island" as const,
+              priority: "immediate" as const,
               preload: false,
             },
           }
@@ -309,17 +310,18 @@ export async function generateManifest(
       for (const route of manifest.routes) {
         const prev = existingMap.get(route.id);
         if (!prev) continue;
-        // 사용자가 설정한 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;
-        }
+        // 사용자가 설정한 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;
+          route.clientExportName = prev.clientExportName;
+        }
         if (prev.hydration && !route.hydration) {
           route.hydration = prev.hydration;
         }

package/src/router/fs-scanner.ts

@@ -30,10 +30,10 @@ import {
 } from "./fs-patterns";
 import { mark, measure } from "../perf";
 import { METADATA_ROUTES } from "../routes/types";
-import {
-  hasUseClientDirective,
-  resolveRouteLevelClientEntryPath,
-} from "./client-entry";
+import {
+  hasUseClientDirective,
+  resolveRouteLevelClientEntry,
+} from "./client-entry";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Scanner Class
@@ -364,9 +364,10 @@ export class FSScanner {
       const dirPath = this.getDirPath(file.relativePath);
       const islands = islandMap.get(dirPath);
 
-      // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
-      let clientModule: string | undefined;
-      let pageFileContent: string | null = null;
+      // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
+      let clientModule: string | undefined;
+      let clientExportName: string | undefined;
+      let pageFileContent: string | null = null;
 
       if (file.type === "page") {
         try {
@@ -395,12 +396,14 @@ export class FSScanner {
       } else if (file.type === "page" && pageFileContent) {
         // page 파일 자체에서 "use client" 확인
         const hasUseClient = hasUseClientDirective(pageFileContent);
-        if (hasUseClient) {
-          clientModule = modulePath;
-        } else {
-          clientModule = await resolveRouteLevelClientEntryPath(rootDir, modulePath, pageFileContent) ?? undefined;
-        }
-      }
+        if (hasUseClient) {
+          clientModule = modulePath;
+        } else {
+          const routeClientEntry = await resolveRouteLevelClientEntry(rootDir, modulePath, pageFileContent);
+          clientModule = routeClientEntry?.modulePath;
+          clientExportName = routeClientEntry?.exportName;
+        }
+      }
 
       // 로딩/에러/404 모듈 찾기 — nearest-ancestor resolution.
       // Phase 18.β: `not-found.tsx` joins `loading.tsx`/`error.tsx` in
@@ -415,10 +418,11 @@ export class FSScanner {
         segments: file.segments,
         pattern,
         kind: file.type === "page" ? "page" : "api",
-        module: modulePath,
-        componentModule: file.type === "page" ? modulePath : undefined,
-        clientModule,
-        layoutChain,
+        module: modulePath,
+        componentModule: file.type === "page" ? modulePath : undefined,
+        clientModule,
+        clientExportName,
+        layoutChain,
         loadingModule,
         errorModule,
         notFoundModule,

package/src/router/fs-types.ts

@@ -117,11 +117,14 @@ export interface FSRouteConfig {
   /** API 핸들러 모듈 경로 */
   module: string;
 
-  /** Island 컴포넌트 모듈 경로 */
-  clientModule?: string;
-
-  /** 적용할 레이아웃 체인 */
-  layoutChain: string[];
+  /** Island 컴포넌트 모듈 경로 */
+  clientModule?: string;
+
+  /** Named export used by the route-level client module, if not default. */
+  clientExportName?: string;
+
+  /** 적용할 레이아웃 체인 */
+  layoutChain: string[];
 
   /** 로딩 UI 모듈 경로 */
   loadingModule?: string;