@mandujs/core 0.54.12 → 0.54.14

package/src/router/fs-scanner.ts

@@ -28,16 +28,55 @@ import {
   sortRoutesByPriority,
   getPatternShape,
 } from "./fs-patterns";
-import { mark, measure } from "../perf";
-import { METADATA_ROUTES } from "../routes/types";
-import {
-  hasUseClientDirective,
-  resolveRouteLevelClientEntryPath,
-} from "./client-entry";
-
-// ═══════════════════════════════════════════════════════════════════════════
-// Scanner Class
-// ═══════════════════════════════════════════════════════════════════════════
+import { mark, measure } from "../perf";
+import { METADATA_ROUTES } from "../routes/types";
+import type { HydrationConfig } from "../spec/schema";
+import {
+  hasUseClientDirective,
+  resolveRouteLevelClientEntry,
+} from "./client-entry";
+
+const HYDRATION_STRATEGIES = new Set(["none", "island", "full", "progressive"]);
+const HYDRATION_PRIORITIES = new Set(["immediate", "visible", "idle", "interaction"]);
+
+function parsePageHydrationConfig(source: string): HydrationConfig | undefined {
+  const stringMatch = source.match(
+    /export\s+const\s+hydration\s*(?::[^=]+)?=\s*["'](none|island|full|progressive)["']/m,
+  );
+  if (stringMatch?.[1]) {
+    return {
+      strategy: stringMatch[1] as HydrationConfig["strategy"],
+      priority: "visible",
+      preload: false,
+    };
+  }
+
+  const objectMatch = source.match(
+    /export\s+const\s+hydration\s*(?::[^=]+)?=\s*\{([\s\S]*?)\}\s*;?/m,
+  );
+  const body = objectMatch?.[1];
+  if (!body) return undefined;
+
+  const strategyMatch = body.match(/\bstrategy\s*:\s*["']([^"']+)["']/);
+  const strategy = strategyMatch?.[1];
+  if (!strategy || !HYDRATION_STRATEGIES.has(strategy)) return undefined;
+
+  const priorityMatch = body.match(/\bpriority\s*:\s*["']([^"']+)["']/);
+  const priority = priorityMatch?.[1];
+  const preloadMatch = body.match(/\bpreload\s*:\s*(true|false)\b/);
+
+  return {
+    strategy: strategy as HydrationConfig["strategy"],
+    priority: HYDRATION_PRIORITIES.has(priority ?? "")
+      ? (priority as HydrationConfig["priority"])
+      : "visible",
+    preload: preloadMatch?.[1] === "true",
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scanner Class
+// ═══════════════════════════════════════════════════════════════════════════
 
 /**
  * FS Routes 스캐너
@@ -364,17 +403,22 @@ 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;
-
-      if (file.type === "page") {
-        try {
-          pageFileContent = await Bun.file(file.absolutePath).text();
-        } catch {
-          pageFileContent = null;
-        }
-      }
+      // clientModule 결정: island 파일 또는 "use client"가 있는 page 자체
+      let clientModule: string | undefined;
+      let clientExportName: string | undefined;
+      let hydration: HydrationConfig | undefined;
+      let pageFileContent: string | null = null;
+
+      if (file.type === "page") {
+        try {
+          pageFileContent = await Bun.file(file.absolutePath).text();
+        } catch {
+          pageFileContent = null;
+        }
+        if (pageFileContent) {
+          hydration = parsePageHydrationConfig(pageFileContent);
+        }
+      }
 
       if (islands?.[0]) {
         // 우선순위: 명시적 island 파일
@@ -395,12 +439,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,12 +461,14 @@ export class FSScanner {
         segments: file.segments,
         pattern,
         kind: file.type === "page" ? "page" : "api",
-        module: modulePath,
-        componentModule: file.type === "page" ? modulePath : undefined,
-        clientModule,
-        layoutChain,
-        loadingModule,
-        errorModule,
+        module: modulePath,
+        componentModule: file.type === "page" ? modulePath : undefined,
+        clientModule,
+        clientExportName,
+        hydration,
+        layoutChain,
+        loadingModule,
+        errorModule,
         notFoundModule,
         sourceFile: file.absolutePath,
       };

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;

package/src/runtime/__tests__/devtools-adapter.test.ts

@@ -1,68 +1,68 @@
-import { afterEach, describe, expect, it } from "bun:test";
-import type { RoutesManifest } from "../../spec/schema";
-import {
-  createRuntimeDevtoolsAdapter,
-  shouldRecordRuntimeRequest,
-  type RuntimeDevtoolsAdapter,
-} from "../devtools-adapter";
-
-const manifest: RoutesManifest = {
-  version: 1,
-  routes: [],
-};
-
-describe("runtime devtools adapter", () => {
-  let adapter: RuntimeDevtoolsAdapter | null = null;
-
-  afterEach(() => {
-    adapter?.stop();
-    adapter = null;
-  });
-
-  it("stays disabled outside dev mode", async () => {
-    adapter = createRuntimeDevtoolsAdapter({
-      isDev: false,
-      rootDir: process.cwd(),
-      manifest,
-      guardConfig: null,
-    });
-
-    expect(adapter.kitchen).toBeNull();
-    expect(adapter.dashboardPath).toBeNull();
-    const response = await adapter.handleRequest(
-      new Request("http://localhost:3000/__kitchen"),
-      "/__kitchen"
-    );
-    expect(response).toBeNull();
-  });
-
-  it("dispatches Kitchen requests in dev mode", async () => {
-    adapter = createRuntimeDevtoolsAdapter({
-      isDev: true,
-      rootDir: process.cwd(),
-      manifest,
-      guardConfig: null,
-    });
-
-    expect(adapter.kitchen).not.toBeNull();
-    expect(adapter.dashboardPath).toBe("/__kitchen");
-    await expect(
-      adapter.handleRequest(new Request("http://localhost:3000/api/ping"), "/api/ping")
-    ).resolves.toBeNull();
-
-    const response = await adapter.handleRequest(
-      new Request("http://localhost:3000/__kitchen"),
-      "/__kitchen"
-    );
-    expect(response?.status).toBe(200);
-    expect(await response?.text()).toContain("Mandu Kitchen");
-  });
-
-  it("keeps framework-internal request paths out of the Kitchen request log", () => {
-    expect(shouldRecordRuntimeRequest("/api/ping")).toBe(true);
-    expect(shouldRecordRuntimeRequest("/_mandu/heap")).toBe(true);
-    expect(shouldRecordRuntimeRequest("/.mandu/client/runtime.js")).toBe(false);
-    expect(shouldRecordRuntimeRequest("/__kitchen/api/events")).toBe(false);
-    expect(shouldRecordRuntimeRequest("/__mandu/events/recent")).toBe(false);
-  });
-});
+import { afterEach, describe, expect, it } from "bun:test";
+import type { RoutesManifest } from "../../spec/schema";
+import {
+  createRuntimeDevtoolsAdapter,
+  shouldRecordRuntimeRequest,
+  type RuntimeDevtoolsAdapter,
+} from "../devtools-adapter";
+
+const manifest: RoutesManifest = {
+  version: 1,
+  routes: [],
+};
+
+describe("runtime devtools adapter", () => {
+  let adapter: RuntimeDevtoolsAdapter | null = null;
+
+  afterEach(() => {
+    adapter?.stop();
+    adapter = null;
+  });
+
+  it("stays disabled outside dev mode", async () => {
+    adapter = createRuntimeDevtoolsAdapter({
+      isDev: false,
+      rootDir: process.cwd(),
+      manifest,
+      guardConfig: null,
+    });
+
+    expect(adapter.kitchen).toBeNull();
+    expect(adapter.dashboardPath).toBeNull();
+    const response = await adapter.handleRequest(
+      new Request("http://localhost:3000/__kitchen"),
+      "/__kitchen"
+    );
+    expect(response).toBeNull();
+  });
+
+  it("dispatches Kitchen requests in dev mode", async () => {
+    adapter = createRuntimeDevtoolsAdapter({
+      isDev: true,
+      rootDir: process.cwd(),
+      manifest,
+      guardConfig: null,
+    });
+
+    expect(adapter.kitchen).not.toBeNull();
+    expect(adapter.dashboardPath).toBe("/__kitchen");
+    await expect(
+      adapter.handleRequest(new Request("http://localhost:3000/api/ping"), "/api/ping")
+    ).resolves.toBeNull();
+
+    const response = await adapter.handleRequest(
+      new Request("http://localhost:3000/__kitchen"),
+      "/__kitchen"
+    );
+    expect(response?.status).toBe(200);
+    expect(await response?.text()).toContain("Mandu Kitchen");
+  });
+
+  it("keeps framework-internal request paths out of the Kitchen request log", () => {
+    expect(shouldRecordRuntimeRequest("/api/ping")).toBe(true);
+    expect(shouldRecordRuntimeRequest("/_mandu/heap")).toBe(true);
+    expect(shouldRecordRuntimeRequest("/.mandu/client/runtime.js")).toBe(false);
+    expect(shouldRecordRuntimeRequest("/__kitchen/api/events")).toBe(false);
+    expect(shouldRecordRuntimeRequest("/__mandu/events/recent")).toBe(false);
+  });
+});

package/src/runtime/__tests__/observability-lifecycle.test.ts

@@ -1,103 +1,103 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import {
-  INTERNAL_EVENTS_ENDPOINT,
-  createRuntimeObservabilityLifecycle,
-} from "../observability-lifecycle";
-import { eventBus } from "../../observability/event-bus";
-import {
-  resetTracer,
-  type Span,
-  type SpanExporter,
-} from "../../observability/tracing";
-
-class CaptureExporter implements SpanExporter {
-  readonly spans: Span[] = [];
-  export(spans: Span[]): void {
-    this.spans.push(...spans);
-  }
-}
-
-afterEach(() => {
-  resetTracer();
-});
-
-describe("runtime observability lifecycle", () => {
-  test("serves heap snapshots with perf data when exposed", async () => {
-    const lifecycle = createRuntimeObservabilityLifecycle({ isDev: true });
-    const response = lifecycle.handleEndpoint(
-      new Request("http://localhost/_mandu/heap"),
-      "/_mandu/heap"
-    );
-
-    expect(response?.status).toBe(200);
-    const body = await response!.json() as {
-      process: { heapUsed: number };
-      perf: unknown;
-    };
-    expect(body.process.heapUsed).toBeGreaterThan(0);
-    expect(body.perf).toBeDefined();
-  });
-
-  test("keeps metrics hidden in production unless explicitly enabled", () => {
-    const hidden = createRuntimeObservabilityLifecycle({ isDev: false });
-    const shown = createRuntimeObservabilityLifecycle({
-      isDev: false,
-      metricsEndpoint: true,
-    });
-
-    expect(hidden.handleEndpoint(new Request("http://localhost/_mandu/metrics"), "/_mandu/metrics")).toBeNull();
-    expect(shown.handleEndpoint(new Request("http://localhost/_mandu/metrics"), "/_mandu/metrics")?.status).toBe(200);
-  });
-
-  test("serves recent EventBus snapshots from the lifecycle endpoint", async () => {
-    const lifecycle = createRuntimeObservabilityLifecycle({ isDev: true });
-    const source = `observability-lifecycle-${Date.now()}`;
-    eventBus.emit({
-      type: "http",
-      severity: "info",
-      source,
-      message: "GET /observed 200",
-    });
-
-    const response = lifecycle.handleEndpoint(
-      new Request(`http://localhost${INTERNAL_EVENTS_ENDPOINT}/recent?source=${source}`),
-      `${INTERNAL_EVENTS_ENDPOINT}/recent`
-    );
-
-    expect(response?.status).toBe(200);
-    const body = await response!.json() as {
-      events: Array<{ source: string; message: string }>;
-    };
-    expect(body.events.some((event) => event.source === source)).toBe(true);
-  });
-
-  test("wraps requests in a root tracing span", async () => {
-    const exporter = new CaptureExporter();
-    const lifecycle = createRuntimeObservabilityLifecycle({
-      isDev: false,
-      tracing: {
-        enabled: true,
-        customExporter: exporter,
-      },
-    });
-    const incomingTraceId = "4bf92f3577b34da6a3ce929d0e0e4736";
-    const incomingSpanId = "00f067aa0ba902b7";
-    const response = await lifecycle.runRequest(
-      new Request("https://example.test/users", {
-        headers: {
-          traceparent: `00-${incomingTraceId}-${incomingSpanId}-01`,
-        },
-      }),
-      Date.now(),
-      "corr-1",
-      async () => new Response("created", { status: 201 })
-    );
-
-    expect(response.status).toBe(201);
-    expect(exporter.spans).toHaveLength(1);
-    expect(exporter.spans[0].traceId).toBe(incomingTraceId);
-    expect(exporter.spans[0].parentSpanId).toBe(incomingSpanId);
-    expect(exporter.spans[0].attributes["http.status_code"]).toBe(201);
-    expect(exporter.spans[0].status).toBe("ok");
-  });
-});
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  INTERNAL_EVENTS_ENDPOINT,
+  createRuntimeObservabilityLifecycle,
+} from "../observability-lifecycle";
+import { eventBus } from "../../observability/event-bus";
+import {
+  resetTracer,
+  type Span,
+  type SpanExporter,
+} from "../../observability/tracing";
+
+class CaptureExporter implements SpanExporter {
+  readonly spans: Span[] = [];
+  export(spans: Span[]): void {
+    this.spans.push(...spans);
+  }
+}
+
+afterEach(() => {
+  resetTracer();
+});
+
+describe("runtime observability lifecycle", () => {
+  test("serves heap snapshots with perf data when exposed", async () => {
+    const lifecycle = createRuntimeObservabilityLifecycle({ isDev: true });
+    const response = lifecycle.handleEndpoint(
+      new Request("http://localhost/_mandu/heap"),
+      "/_mandu/heap"
+    );
+
+    expect(response?.status).toBe(200);
+    const body = await response!.json() as {
+      process: { heapUsed: number };
+      perf: unknown;
+    };
+    expect(body.process.heapUsed).toBeGreaterThan(0);
+    expect(body.perf).toBeDefined();
+  });
+
+  test("keeps metrics hidden in production unless explicitly enabled", () => {
+    const hidden = createRuntimeObservabilityLifecycle({ isDev: false });
+    const shown = createRuntimeObservabilityLifecycle({
+      isDev: false,
+      metricsEndpoint: true,
+    });
+
+    expect(hidden.handleEndpoint(new Request("http://localhost/_mandu/metrics"), "/_mandu/metrics")).toBeNull();
+    expect(shown.handleEndpoint(new Request("http://localhost/_mandu/metrics"), "/_mandu/metrics")?.status).toBe(200);
+  });
+
+  test("serves recent EventBus snapshots from the lifecycle endpoint", async () => {
+    const lifecycle = createRuntimeObservabilityLifecycle({ isDev: true });
+    const source = `observability-lifecycle-${Date.now()}`;
+    eventBus.emit({
+      type: "http",
+      severity: "info",
+      source,
+      message: "GET /observed 200",
+    });
+
+    const response = lifecycle.handleEndpoint(
+      new Request(`http://localhost${INTERNAL_EVENTS_ENDPOINT}/recent?source=${source}`),
+      `${INTERNAL_EVENTS_ENDPOINT}/recent`
+    );
+
+    expect(response?.status).toBe(200);
+    const body = await response!.json() as {
+      events: Array<{ source: string; message: string }>;
+    };
+    expect(body.events.some((event) => event.source === source)).toBe(true);
+  });
+
+  test("wraps requests in a root tracing span", async () => {
+    const exporter = new CaptureExporter();
+    const lifecycle = createRuntimeObservabilityLifecycle({
+      isDev: false,
+      tracing: {
+        enabled: true,
+        customExporter: exporter,
+      },
+    });
+    const incomingTraceId = "4bf92f3577b34da6a3ce929d0e0e4736";
+    const incomingSpanId = "00f067aa0ba902b7";
+    const response = await lifecycle.runRequest(
+      new Request("https://example.test/users", {
+        headers: {
+          traceparent: `00-${incomingTraceId}-${incomingSpanId}-01`,
+        },
+      }),
+      Date.now(),
+      "corr-1",
+      async () => new Response("created", { status: 201 })
+    );
+
+    expect(response.status).toBe(201);
+    expect(exporter.spans).toHaveLength(1);
+    expect(exporter.spans[0].traceId).toBe(incomingTraceId);
+    expect(exporter.spans[0].parentSpanId).toBe(incomingSpanId);
+    expect(exporter.spans[0].attributes["http.status_code"]).toBe(201);
+    expect(exporter.spans[0].status).toBe("ok");
+  });
+});