@mandujs/mcp 0.37.1 → 0.37.3

package/README.md

@@ -136,10 +136,9 @@ bunx @mandujs/mcp --root /path/to/project
 
 ### Semantic Slots (RFC-001) 🆕
 
-| Tool | Description |
-|------|-------------|
-| `mandu_validate_slot` | Validate slot against constraints |
-| `mandu_validate_slots` | Batch validate multiple slots |
+| Tool | Description |
+|------|-------------|
+| `mandu_get_slot_constraints` | Get recommended slot constraint presets |
 
 ### Architecture Negotiation (RFC-001) 🆕
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.37.1",
+  "version": "0.37.3",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,9 +34,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "^0.54.1",
-    "@mandujs/ate": "^0.26.0",
-    "@mandujs/skills": "^0.20.0",
+    "@mandujs/core": "^0.54.3",
+    "@mandujs/ate": "^0.26.1",
+    "@mandujs/skills": "^0.20.1",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "engines": {

package/src/prompts.ts

@@ -48,10 +48,10 @@ Follow these steps using Mandu MCP tools:
 1. Read current route manifest: Resource mandu://routes
 2. Read project config: Resource mandu://config
 3. Negotiate the feature spec: Tool mandu.negotiate
-4. Generate scaffold: Tool mandu.negotiate.scaffold
-5. If client interactivity needed, create island: Tool mandu_create_island
-   Use the declarative pattern: island('visible', Component)
-6. If data requirements exist, create slot: Tool mandu_create_slot
+4. Generate scaffold: Tool mandu.negotiate.scaffold
+5. If client interactivity needed, create island: Tool mandu_create_island
+   Use @mandujs/core/client with wrapComponent(Component) or island({ setup, render })
+6. If data requirements exist, create slot: Tool mandu_create_slot
    Slots are server-side data loaders that run before render
 7. If API is exposed, define contract: Tool mandu_create_contract
    Contracts are Zod schemas for validation and OpenAPI generation

package/src/resources/skills/guides.ts

@@ -377,21 +377,21 @@ Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티
 | \`idle\` | 브라우저 유휴 시 | 비중요 기능 |
 | \`interaction\` | 사용자 상호작용 시 | 클릭해야 활성화 |
 
-## Island 만들기
-
-### 1. 클라이언트 컴포넌트 작성
-
-\`\`\`tsx
-// app/counter/client.tsx
-
-"use client";
-
-import { useState } from "react";
-
-export default function Counter({ initial = 0 }: { initial?: number }) {
-  const [count, setCount] = useState(initial);
-
-  return (
+## Inline client region 만들기
+
+### 1. 클라이언트 컴포넌트 작성
+
+\`\`\`tsx
+// app/counter/client.tsx
+
+"use client";
+
+import { useState } from "react";
+
+export function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = useState(initial);
+
+  return (
     <div>
       <p>Count: {count}</p>
       <button onClick={() => setCount(c => c - 1)}>-</button>
@@ -399,34 +399,43 @@ export default function Counter({ initial = 0 }: { initial?: number }) {
     </div>
   );
 }
-\`\`\`
-
-### 2. 페이지에서 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import Counter from "./client";
-
-export default function CounterPage() {
-  return (
+\`\`\`
+
+### 2. 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div>
       <h1>Counter Demo</h1>
       <p>이 텍스트는 정적 HTML입니다.</p>
-
-      {/* 이 부분만 hydration됩니다 */}
-      <Counter initial={10} />
-    </div>
-  );
-}
-\`\`\`
-
-## Mandu.island() API
-
-고급 Island 패턴을 위한 API:
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+
+      {/* 이 부분만 hydration됩니다 */}
+      <CounterPartial.Render initial={10} />
+    </div>
+  );
+}
+\`\`\`
+
+## Mandu.island() API
+
+고급 page-level Island 패턴을 위한 API입니다. \`Mandu.island()\`는 단일
+정의 객체만 받습니다. \`island("visible", Component)\` 형태는 지원하지
+않으며, 서버 페이지 안에 inline으로 렌더링할 영역은 \`partial()\`을
+사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState, useCallback } from "react";

package/src/resources/skills/mandu-deployment/rules/db-provider-supabase.md

@@ -138,8 +138,8 @@ export function createServerSupabase() {
 Mandu 의 client island 에서 Realtime 구독:
 
 ```tsx
-// app/messages/MessagesIsland.client.tsx
-import { island } from "@mandujs/core/client";
+// app/messages/MessagesIsland.client.tsx
+import { wrapComponent } from "@mandujs/core/client";
 import { useEffect, useState } from "react";
 import { supabase } from "@/lib/supabase";
 
@@ -174,7 +174,7 @@ function Messages() {
   );
 }
 
-export default island("visible", <Messages />);
+export default wrapComponent(Messages);
 ```
 
 ### 3.3 Storage

package/src/resources/skills/mandu-hydration/SKILL.md

@@ -57,17 +57,25 @@ Reference these guidelines when:
 - `hydration-data-server` - Access server data with useServerData
 - `hydration-data-event` - Communicate between Islands with useIslandEvent
 
-## Hydration Strategies
-
-| Strategy | Description | Use Case |
-|----------|-------------|----------|
-| `none` | No JavaScript | Pure static pages |
-| `island` | Partial hydration (default) | Static + interactive mix |
-| `full` | Full hydration | SPA-style pages |
-
-## Client Hooks
-
-```typescript
+## Hydration Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `none` | No JavaScript | Pure static pages |
+| `island` | Partial hydration (default) | Static + interactive mix |
+| `full` | Full hydration | SPA-style pages |
+
+## Runtime API Constraints
+
+- `island()` / `Mandu.island()` takes one definition object: `island({ setup, render })`.
+- Do not call `island("visible", Component)`; use `wrapComponent(Component)` for a simple page-level island wrapper.
+- Islands are page-level client bundles. Do not render them as inline JSX like `<MyIsland />`.
+- For an embedded interactive region inside a server page, use `partial()`: put it in `*.partial.tsx`, export `partial({ id, component })`, and render the returned `.Render` component from the server page.
+- A server page that renders partials must opt into hydration, for example `export const hydration = { strategy: "island", priority: "visible", preload: false }`.
+
+## Client Hooks
+
+```typescript
 import {
   useServerData,
   useHydrated,

package/src/resources/skills/mandu-hydration/rules/hydration-island-setup.md

@@ -5,13 +5,60 @@ impactDescription: Proper Island structure
 tags: hydration, island, setup
 ---
 
-## Use Mandu.island() with Setup Function
-
-For complex Islands, use `Mandu.island()` API to separate state logic from rendering.
-
-**Incorrect (mixed concerns):**
-
-```tsx
+## Use Mandu.island() with Setup Function
+
+For complex Islands, use `Mandu.island()` API to separate state logic from rendering.
+`Mandu.island()` takes a single definition object. The shorthand
+`island("visible", Component)` is not a supported Mandu runtime API.
+
+Islands are page-level client bundles. They are discovered and rendered by
+the framework wrapper, not embedded directly as inline JSX. Use `partial()`
+when a server page needs an inline interactive region.
+
+```tsx
+// Simple page-level island wrapper
+"use client";
+
+import { wrapComponent } from "@mandujs/core/client";
+
+function Counter() {
+  return <button>Count</button>;
+}
+
+export default wrapComponent(Counter);
+```
+
+```tsx
+// Inline client region inside a server-rendered page
+// app/Counter.partial.tsx
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./counter.client";
+
+export default partial({
+  id: "Counter",
+  component: Counter,
+  priority: "visible",
+});
+```
+
+```tsx
+// app/page.tsx
+import CounterPartial from "./Counter.partial";
+
+export const hydration = {
+  strategy: "island",
+  priority: "visible",
+  preload: false,
+};
+
+export default function Page() {
+  return <CounterPartial.Render initial={0} />;
+}
+```
+
+**Incorrect (mixed concerns):**
+
+```tsx
 "use client";
 
 export default function TodoList({ initialTodos }) {

package/src/resources/skills/mandu-hydration/rules/hydration-priority-visible.md

@@ -18,43 +18,66 @@ Set hydration priority based on when the component needs to be interactive.
 | `idle` | Browser idle | Non-critical features (analytics widgets) |
 | `interaction` | User action | Click-to-activate components |
 
-## Examples
-
-### Immediate: Always-visible interactions
-
-```tsx
-// Header with navigation - needs to work immediately
-<Island priority="immediate">
-  <HeaderNav />
-</Island>
-```
-
-### Visible: Below-fold content (default)
-
-```tsx
-// Comments section - load when scrolled into view
-<Island priority="visible">
-  <CommentsSection postId={postId} />
-</Island>
-```
-
-### Idle: Background features
-
-```tsx
-// Chat widget - can wait until browser is idle
-<Island priority="idle">
-  <ChatWidget />
-</Island>
-```
-
-### Interaction: On-demand activation
-
-```tsx
-// Video player - only hydrate when user clicks play
-<Island priority="interaction">
-  <VideoPlayer videoId={videoId} />
-</Island>
-```
+## Examples
+
+Inline client regions live in `*.partial.tsx` files and use
+`partial({ id, component, priority })`, then render the returned `.Render`
+component from the server page. The page must export a non-`none` hydration
+config.
+
+### Immediate: Always-visible interactions
+
+```tsx
+// Header with navigation - needs to work immediately
+import { partial } from "@mandujs/core/client";
+
+const HeaderNavPartial = partial({
+  id: "HeaderNav",
+  component: HeaderNav,
+  priority: "immediate",
+});
+
+<HeaderNavPartial.Render />
+```
+
+### Visible: Below-fold content (default)
+
+```tsx
+// Comments section - load when scrolled into view
+const CommentsPartial = partial({
+  id: "Comments",
+  component: CommentsSection,
+  priority: "visible",
+});
+
+<CommentsPartial.Render postId={postId} />
+```
+
+### Idle: Background features
+
+```tsx
+// Chat widget - can wait until browser is idle
+const ChatPartial = partial({
+  id: "Chat",
+  component: ChatWidget,
+  priority: "idle",
+});
+
+<ChatPartial.Render />
+```
+
+### Interaction: On-demand activation
+
+```tsx
+// Video player - only hydrate when user clicks play
+const VideoPartial = partial({
+  id: "Video",
+  component: VideoPlayer,
+  priority: "interaction",
+});
+
+<VideoPartial.Render videoId={videoId} />
+```
 
 ## Performance Impact
 

package/src/resources/skills/recipes.ts

@@ -469,24 +469,30 @@ export default function Counter({ initial = 0, step = 1 }: CounterProps) {
 }
 \`\`\`
 
-## Step 2: 페이지에서 사용
-
-\`\`\`tsx
-// app/counter/page.tsx
-
-import Counter from "./client";
-
-export default function CounterPage() {
-  return (
+## Step 2: 서버 페이지에서 partial로 사용
+
+\`\`\`tsx
+// app/counter/page.tsx
+
+import { partial } from "@mandujs/core/client";
+import Counter from "./client";
+
+const CounterPartial = partial({
+  component: Counter,
+  priority: "visible",
+});
+
+export default function CounterPage() {
+  return (
     <div style={{ padding: "20px" }}>
       <h1>Counter Demo</h1>
       <p>아래 카운터는 클라이언트에서 hydration됩니다.</p>
-
-      {/* Island 컴포넌트 */}
-      <Counter initial={10} step={5} />
-
-      <p style={{ marginTop: "20px", color: "#666" }}>
-        이 텍스트는 정적 HTML입니다.
+
+      {/* Inline client region */}
+      <CounterPartial.Render initial={10} step={5} />
+
+      <p style={{ marginTop: "20px", color: "#666" }}>
+        이 텍스트는 정적 HTML입니다.
       </p>
     </div>
   );
@@ -618,10 +624,13 @@ export default function UserList() {
 
 ## Mandu.island() API (고급)
 
-서버 데이터와 클라이언트 상태를 분리하려면:
-
-\`\`\`typescript
-// spec/slots/todos.client.ts
+서버 데이터와 클라이언트 상태를 분리하는 page-level Island가 필요하면
+\`Mandu.island({ setup, render })\`를 사용합니다. \`island("visible",
+Component)\`는 지원하지 않습니다. 서버 페이지 안에 inline으로 렌더링할
+영역은 \`partial()\`을 사용하세요.
+
+\`\`\`typescript
+// spec/slots/todos.client.ts
 
 import { Mandu } from "@mandujs/core/client";
 import { useState } from "react";

package/src/tools/ate.ts

@@ -105,7 +105,11 @@ export const ateToolDefinitions: Tool[] = [
           type: "string",
           description: "Dev server URL (default: http://localhost:3333). Must match the running mandu dev server.",
         },
-        ci: { type: "boolean", description: "CI mode: stricter timeouts, no interactive prompts" },
+        ci: { type: "boolean", description: "CI mode: stricter timeouts, no interactive prompts" },
+        timeoutMs: {
+          type: "number",
+          description: "Hard timeout for the whole Playwright process in milliseconds (default: 600000).",
+        },
         headless: { type: "boolean", description: "Run browsers headlessly (default: true)" },
         browsers: {
           type: "array",
@@ -260,7 +264,11 @@ export const ateToolDefinitions: Tool[] = [
           enum: ["L0", "L1", "L2", "L3"],
           description: "Assertion depth: L0=smoke, L1=HTTP status, L2=contract schema, L3=full behavioral",
         },
-        ci: { type: "boolean", description: "CI mode: stricter timeouts" },
+        ci: { type: "boolean", description: "CI mode: stricter timeouts" },
+        timeoutMs: {
+          type: "number",
+          description: "Hard timeout for the whole Playwright process in milliseconds (default: 600000).",
+        },
         useImpactAnalysis: {
           type: "boolean",
           description: "Run impact analysis first and only test changed routes (faster in CI)",
@@ -378,7 +386,7 @@ export function ateTools(projectRoot: string, server?: Server) {
       return await ateRun(input);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      const isTimeout = /timed out/i.test(message);
+      const isTimeout = /timeout|timed out|타임아웃/i.test(message);
       const snap = tracker.snapshot();
       const partial: PartialRunResults = {
         runId: snap.runId ?? `unknown-${Date.now()}`,
@@ -439,19 +447,21 @@ export function ateTools(projectRoot: string, server?: Server) {
         browsers,
         onlyFiles,
         onlyRoutes,
-        grep,
-        progressToken,
-      } = args as {
+        grep,
+        timeoutMs,
+        progressToken,
+      } = args as {
         repoRoot: string;
         baseURL?: string;
         ci?: boolean;
         headless?: boolean;
         browsers?: ("chromium" | "firefox" | "webkit")[];
         onlyFiles?: string[];
-        onlyRoutes?: string[];
-        grep?: string;
-        progressToken?: string | number;
-      };
+        onlyRoutes?: string[];
+        grep?: string;
+        timeoutMs?: number;
+        progressToken?: string | number;
+      };
       return await runWithObservability(
         {
           repoRoot,
@@ -459,10 +469,11 @@ export function ateTools(projectRoot: string, server?: Server) {
           ci,
           headless,
           browsers,
-          onlyFiles,
-          onlyRoutes,
-          grep,
-        },
+          onlyFiles,
+          onlyRoutes,
+          grep,
+          timeoutMs,
+        },
         { progressToken },
       );
     },
@@ -518,9 +529,10 @@ export function ateTools(projectRoot: string, server?: Server) {
     },
     "mandu.ate.auto_pipeline": async (args: Record<string, unknown>) => {
       const {
-        repoRoot, baseURL, oracleLevel, ci, useImpactAnalysis,
-        base, head, autoHeal, tsconfigPath, routeGlobs, buildSalt,
-      } = args as {
+        repoRoot, baseURL, oracleLevel, ci, useImpactAnalysis,
+        base, head, autoHeal, tsconfigPath, routeGlobs, buildSalt,
+        timeoutMs,
+      } = args as {
         repoRoot: string;
         baseURL?: string;
         oracleLevel?: OracleLevel;
@@ -530,13 +542,14 @@ export function ateTools(projectRoot: string, server?: Server) {
         head?: string;
         autoHeal?: boolean;
         tsconfigPath?: string;
-        routeGlobs?: string[];
-        buildSalt?: string;
-      };
-      return await runFullPipeline({
-        repoRoot, baseURL, oracleLevel, ci, useImpactAnalysis,
-        base, head, autoHeal, tsconfigPath, routeGlobs, buildSalt,
-      });
+        routeGlobs?: string[];
+        buildSalt?: string;
+        timeoutMs?: number;
+      };
+      return await runFullPipeline({
+        repoRoot, baseURL, oracleLevel, ci, useImpactAnalysis,
+        base, head, autoHeal, tsconfigPath, routeGlobs, buildSalt, timeoutMs,
+      });
     },
     "mandu.ate.feedback": async (args: Record<string, unknown>) => {
       const { repoRoot, runId, autoApply } = args as {

package/src/tools/composite.ts

@@ -60,10 +60,10 @@ export const compositeToolDefinitions: Tool[] = [
     },
   },
   {
-    name: "mandu.island.add",
-    description:
-      "Create an island component with correct @mandujs/core/client imports and hydration strategy. " +
-      "Generates a .island.tsx file in app/{route}/ with the island() wrapper.",
+    name: "mandu.island.add",
+    description:
+      "Create an island component with correct @mandujs/core/client imports and hydration strategy. " +
+      "Generates a .island.tsx file in app/{route}/ with the wrapComponent() island definition.",
     annotations: {
       destructiveHint: true,
       readOnlyHint: false,
@@ -474,10 +474,10 @@ function generateMiddlewareSource(preset: string, options: Record<string, string
   return templates[preset] ?? templates.default;
 }
 
-function generateIslandSource(name: string, strategy: string): string {
-  return `"use client";
-import { island } from "@mandujs/core/client";
-import { useState } from "react";
+function generateIslandSource(name: string, strategy: string): string {
+  return `"use client";
+import { wrapComponent } from "@mandujs/core/client";
+import { useState } from "react";
 
 interface ${name}Props {
   [key: string]: unknown;
@@ -493,6 +493,8 @@ function ${name}Inner(props: ${name}Props) {
   );
 }
 
-export default island("${strategy}", ${name}Inner);
-`;
-}
+// Route hydration priority should be set on the page/manifest route.
+// Suggested priority for this island: "${strategy}".
+export default wrapComponent(${name}Inner);
+`;
+}