@mandujs/core 0.54.12 → 0.54.14

package/src/bundler/types.ts

@@ -55,28 +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";
-    }
-  >;
-  /** Inline partial bundles (from *.partial.tsx / *.partial.ts files) */
-  partials?: Record<
-    string,
-    {
-      /** JavaScript bundle path */
-      js: 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 런타임 */
@@ -123,19 +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";
-}
-
-/** Inline partial bundle entry (used by scanPartialFiles) */
-export interface PartialFileEntry {
-  name: string;
-  filePath: 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,9 +3,9 @@
  * Hydration을 위한 클라이언트 사이드 컴포넌트 정의
  */
 
-import type { ReactNode } from "react";
-import { serializeProps } from "./serialize";
-import { getServerData as getGlobalServerData } from "./window-state";
+import type { ReactNode } from "react";
+import { serializeProps } from "./serialize";
+import { getServerData as getGlobalServerData } from "./window-state";
 
 /**
  * Island 정의 타입
@@ -336,45 +336,45 @@ export interface PartialConfig {
 /**
  * Partial Island 정의 타입
  */
-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;
-}
+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;
-}
-
-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;
-}
+  __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 생성
@@ -399,56 +399,56 @@ function priorityToHydrate(priority: NonNullable<PartialDefinition<unknown>["pri
  * }
  * ```
  */
-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 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),
-    );
-  };
+  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/config/validate.ts

@@ -43,7 +43,7 @@ function _strictWithWarnings<T extends z.ZodRawShape>(
  */
 const ServerConfigSchema = z
   .object({
-    port: z.number().min(1).max(65535).default(3333),
+    port: z.number().min(1).max(65535).default(3333),
     // Default `"::"` (IPv6 wildcard, dual-stack): accepts both IPv4 and
     // IPv6 clients on one socket. Fixes Windows Node 17+ fetch failing
     // with `ECONNREFUSED ::1:PORT` because `localhost` resolves to `::1`

package/src/contract/schema.ts

@@ -152,6 +152,13 @@ export interface ContractInstance extends ContractSchema {
   _validated?: boolean;
 }
 
+/**
+ * Public API schema boundary. Use this alias in docs and generated examples
+ * when distinguishing a request/response contract from an executable filling.
+ */
+export type ApiContract<T extends ContractDefinition = ContractDefinition> =
+  T & ContractInstance;
+
 /** Validation error detail */
 export interface ContractValidationIssue {
   /** Field path (e.g., "body.email") */

package/src/deploy/inference/context.ts

@@ -78,8 +78,8 @@ export async function buildDeployInferenceContext(
     // still gets the manifest metadata and falls back to defaults.
   }
 
-  const imports = extractImports(source);
-  const dependencyClasses = classifySourceDependencies(source, imports);
+  const imports = extractImports(source);
+  const dependencyClasses = classifySourceDependencies(source, imports);
   // Mandu's manifest patterns use `:param` / `*` (path-pattern style),
   // not bracket-form. Detect both shapes so the heuristic doesn't
   // misclassify dynamic routes as prerenderable. Examples:
@@ -139,82 +139,82 @@ export function extractImports(source: string): string[] {
 }
 
 /** Map import specifiers to coarse dependency classes. */
-export function classifyImports(imports: string[]): ReadonlySet<DependencyClass> {
-  const classes = new Set<DependencyClass>();
-  for (const spec of imports) {
+export function classifyImports(imports: string[]): ReadonlySet<DependencyClass> {
+  const classes = new Set<DependencyClass>();
+  for (const spec of imports) {
     const cls = classifyOne(spec);
     if (cls) classes.add(cls);
   }
   if (classes.size === 0) classes.add("fetch-only");
-  return classes;
-}
-
-/**
- * Classify dependency signals that do not always appear as bare imports.
- *
- * Dogfooding surfaced Mandu API routes importing project-local
- * `src/server/infra/db` helpers and using `db` tagged templates. Those
- * are server-only even when the bare imports look edge-safe.
- */
-export function classifySourceDependencies(
-  source: string,
-  imports: string[] = extractImports(source),
-): ReadonlySet<DependencyClass> {
-  const classes = new Set<DependencyClass>(classifyImports(imports));
-  if (classes.size === 1 && classes.has("fetch-only")) {
-    classes.delete("fetch-only");
-  }
-
-  const allImports = extractAllImportSpecifiers(source);
-  if (allImports.some(isServerInfraImport)) {
-    classes.add("db");
-  }
-
-  if (/\bBun\.SQL\b|\bBun\.sqlite\b/i.test(source)) {
-    classes.add("bun-native");
-  }
-
-  if (
-    /(?:^|[^\w$])db\s*`/.test(source) ||
-    /\bctx\.deps\.db\b/.test(source) ||
-    /\bdb\.(?:query|execute|select|insert|update|delete)\b/.test(source)
-  ) {
-    classes.add("db");
-  }
-
-  if (classes.size === 0) {
-    classes.add("fetch-only");
-  }
-  return classes;
-}
-
-function extractAllImportSpecifiers(source: string): string[] {
-  const out = new Set<string>();
-  const staticImport = /^\s*import\b[^"']*?["']([^"']+)["']/gm;
-  const dynamicImport = /\bimport\(\s*["']([^"']+)["']\s*\)/g;
-  for (const re of [staticImport, dynamicImport]) {
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(source)) !== null) {
-      out.add(m[1]!);
-    }
-  }
-  return [...out].sort();
-}
-
-function isServerInfraImport(specifier: string): boolean {
-  const s = specifier.replace(/\\/g, "/").toLowerCase();
-  return (
-    s === "@/server/infra" ||
-    s.startsWith("@/server/infra/") ||
-    s === "src/server/infra" ||
-    s.startsWith("src/server/infra/") ||
-    s.endsWith("/server/infra") ||
-    s.includes("/server/infra/")
-  );
-}
-
-function classifyOne(spec: string): DependencyClass | null {
-  const s = spec.toLowerCase();
+  return classes;
+}
+
+/**
+ * Classify dependency signals that do not always appear as bare imports.
+ *
+ * Dogfooding surfaced Mandu API routes importing project-local
+ * `src/server/infra/db` helpers and using `db` tagged templates. Those
+ * are server-only even when the bare imports look edge-safe.
+ */
+export function classifySourceDependencies(
+  source: string,
+  imports: string[] = extractImports(source),
+): ReadonlySet<DependencyClass> {
+  const classes = new Set<DependencyClass>(classifyImports(imports));
+  if (classes.size === 1 && classes.has("fetch-only")) {
+    classes.delete("fetch-only");
+  }
+
+  const allImports = extractAllImportSpecifiers(source);
+  if (allImports.some(isServerInfraImport)) {
+    classes.add("db");
+  }
+
+  if (/\bBun\.SQL\b|\bBun\.sqlite\b/i.test(source)) {
+    classes.add("bun-native");
+  }
+
+  if (
+    /(?:^|[^\w$])db\s*`/.test(source) ||
+    /\bctx\.deps\.db\b/.test(source) ||
+    /\bdb\.(?:query|execute|select|insert|update|delete)\b/.test(source)
+  ) {
+    classes.add("db");
+  }
+
+  if (classes.size === 0) {
+    classes.add("fetch-only");
+  }
+  return classes;
+}
+
+function extractAllImportSpecifiers(source: string): string[] {
+  const out = new Set<string>();
+  const staticImport = /^\s*import\b[^"']*?["']([^"']+)["']/gm;
+  const dynamicImport = /\bimport\(\s*["']([^"']+)["']\s*\)/g;
+  for (const re of [staticImport, dynamicImport]) {
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(source)) !== null) {
+      out.add(m[1]!);
+    }
+  }
+  return [...out].sort();
+}
+
+function isServerInfraImport(specifier: string): boolean {
+  const s = specifier.replace(/\\/g, "/").toLowerCase();
+  return (
+    s === "@/server/infra" ||
+    s.startsWith("@/server/infra/") ||
+    s === "src/server/infra" ||
+    s.startsWith("src/server/infra/") ||
+    s.endsWith("/server/infra") ||
+    s.includes("/server/infra/")
+  );
+}
+
+function classifyOne(spec: string): DependencyClass | null {
+  const s = spec.toLowerCase();
   if (
     s === "bun:sqlite" ||
     s === "bun:ffi" ||
@@ -231,14 +231,14 @@ function classifyOne(spec: string): DependencyClass | null {
   if (s === "node:child_process" || s === "child_process" || s === "node:worker_threads" || s === "worker_threads") {
     return "node-child";
   }
-  if (
-    /^(postgres|pg|mysql2?|drizzle-orm(\/.*)?|@prisma\/client|prisma|mongodb|mongoose|@neondatabase\/.+|kysely|sqlite3|better-sqlite3|@planetscale\/.+)$/.test(s)
-  ) {
-    return "db";
-  }
-  if (s === "@mandujs/core/db" || s.startsWith("@mandujs/core/db/")) {
-    return "db";
-  }
+  if (
+    /^(postgres|pg|mysql2?|drizzle-orm(\/.*)?|@prisma\/client|prisma|mongodb|mongoose|@neondatabase\/.+|kysely|sqlite3|better-sqlite3|@planetscale\/.+)$/.test(s)
+  ) {
+    return "db";
+  }
+  if (s === "@mandujs/core/db" || s.startsWith("@mandujs/core/db/")) {
+    return "db";
+  }
   if (/^(@anthropic-ai\/sdk|openai|ai|@ai-sdk\/.+|@google\/generative-ai|cohere-ai)$/.test(s)) {
     return "ai-sdk";
   }

package/src/devtools/client/components/panel/islands-panel.tsx

@@ -183,28 +183,28 @@ export function IslandsPanel({ islands }: IslandsPanelProps): React.ReactElement
     );
   }, [islands]);
 
-  if (islands.length === 0) {
-    return (
-      <div style={styles.container}>
-        <div style={styles.emptyState}>
-          <p>
-            아직 hydration 이벤트가 없습니다.<br />
-            정적 상태는 mandu.runtime.status에서 확인하세요.
-          </p>
-        </div>
-      </div>
-    );
-  }
+  if (islands.length === 0) {
+    return (
+      <div style={styles.container}>
+        <div style={styles.emptyState}>
+          <p>
+            아직 hydration 이벤트가 없습니다.<br />
+            정적 상태는 mandu.runtime.status에서 확인하세요.
+          </p>
+        </div>
+      </div>
+    );
+  }
 
   return (
     <div style={styles.container}>
       {/* Header Stats */}
       <div style={styles.header}>
         <div style={styles.stats}>
-          <div style={styles.stat}>
-            <span>Mounts:</span>
-            <span style={styles.statValue}>{stats.total}</span>
-          </div>
+          <div style={styles.stat}>
+            <span>Mounts:</span>
+            <span style={styles.statValue}>{stats.total}</span>
+          </div>
           <div style={styles.stat}>
             <span>Ready</span>
             <span style={styles.statValue}>{stats.hydrated}</span>

package/src/devtools/client/components/panel/panel-container.tsx

@@ -28,7 +28,7 @@ export interface PanelContainerProps {
 
 export const TABS: TabDefinition[] = [
   { id: 'errors', label: 'Issues', icon: 'ERR', testId: testIds.tabErrors },
-  { id: 'islands', label: 'Client Mounts', icon: 'HYD', testId: testIds.tabIslands },
+  { id: 'islands', label: 'Client Mounts', icon: 'HYD', testId: testIds.tabIslands },
   { id: 'network', label: 'Network', icon: 'NET', testId: testIds.tabNetwork },
   { id: 'guard', label: 'Guard', icon: 'GRD', testId: testIds.tabGuard },
   { id: 'preview', label: 'Changes', icon: 'CHG', testId: testIds.tabPreview },

package/src/error/formatter.ts

@@ -24,11 +24,16 @@ export function formatErrorResponse(error: ManduError, options: FormatOptions =
     code: error.code,
     message: error.message,
     summary: error.summary,
+    cause: error.summary,
     fix: error.fix,
+    filePath: error.fix.file,
+    solution: error.fix.suggestion,
   };
 
   if (error.route) {
     response.route = error.route;
+    response.routeId = error.route.id;
+    response.routePattern = error.route.pattern;
   }
 
   // 개발 모드에서만 디버그 정보 포함
@@ -65,6 +70,7 @@ export function formatErrorForConsole(error: ManduError, options: FormatOptions
   } else {
     lines.push(`  → ${error.summary}`);
   }
+  lines.push(`  Cause: ${error.summary}`);
 
   // 수정 안내
   lines.push("");
@@ -75,11 +81,14 @@ export function formatErrorForConsole(error: ManduError, options: FormatOptions
     lines.push(`  Fix: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
     lines.push(`       ${error.fix.suggestion}`);
   }
+  lines.push(`  File: ${error.fix.file}${error.fix.line ? `:${error.fix.line}` : ""}`);
+  lines.push(`  Solution: ${error.fix.suggestion}`);
 
   // 라우트 컨텍스트
   if (error.route) {
     lines.push("");
-    lines.push(`  Route: ${error.route.id} (${error.route.pattern})`);
+    lines.push(`  Route ID: ${error.route.id}`);
+    lines.push(`  Route: ${error.route.pattern}`);
   }
 
   // 디버그 정보 (개발 모드)

package/src/experimental/index.ts

@@ -0,0 +1,10 @@
+export * as a11y from "../a11y";
+export * as agent from "../agent";
+export * as brain from "../brain";
+export * as deploy from "../deploy";
+export * as design from "../design";
+export * as desktop from "../desktop";
+export * as devtools from "../devtools";
+export * as diagnose from "../diagnose";
+export * as kitchen from "../kitchen";
+export * as scheduler from "../scheduler";

package/src/filling/context.ts

@@ -628,23 +628,23 @@ export class ManduContext {
     return this.withCookies(new Response(null, { status: 204 }));
   }
 
-  /** 400 Bad Request, or custom 4xx/5xx error with ctx.error(status, message). */
-  error(message: string, details?: unknown): Response;
-  error(status: number, message: string, details?: unknown): Response;
-  error(
-    statusOrMessage: number | string,
-    messageOrDetails?: string | unknown,
-    maybeDetails?: unknown
-  ): Response {
-    if (typeof statusOrMessage === "number") {
-      const status = Number.isInteger(statusOrMessage) && statusOrMessage >= 400 && statusOrMessage <= 599
-        ? statusOrMessage
-        : 400;
-      const message = typeof messageOrDetails === "string" ? messageOrDetails : "Error";
-      return this.json({ status: "error", message, details: maybeDetails }, status);
-    }
-    return this.json({ status: "error", message: statusOrMessage, details: messageOrDetails }, 400);
-  }
+  /** 400 Bad Request, or custom 4xx/5xx error with ctx.error(status, message). */
+  error(message: string, details?: unknown): Response;
+  error(status: number, message: string, details?: unknown): Response;
+  error(
+    statusOrMessage: number | string,
+    messageOrDetails?: string | unknown,
+    maybeDetails?: unknown
+  ): Response {
+    if (typeof statusOrMessage === "number") {
+      const status = Number.isInteger(statusOrMessage) && statusOrMessage >= 400 && statusOrMessage <= 599
+        ? statusOrMessage
+        : 400;
+      const message = typeof messageOrDetails === "string" ? messageOrDetails : "Error";
+      return this.json({ status: "error", message, details: maybeDetails }, status);
+    }
+    return this.json({ status: "error", message: statusOrMessage, details: messageOrDetails }, 400);
+  }
 
   /** 401 Unauthorized */
   unauthorized(message: string = "Unauthorized"): Response {