@mandujs/mcp 0.9.19 → 0.9.21

package/src/resources/skills/mandu-hydration/rules/hydration-data-event.md

@@ -0,0 +1,109 @@
+---
+title: Use useIslandEvent for Island Communication
+impact: MEDIUM
+impactDescription: Enables Island-to-Island data flow
+tags: hydration, event, communication
+---
+
+## Use useIslandEvent for Island Communication
+
+Islands are isolated by default. Use `useIslandEvent` to communicate between them.
+
+**Incorrect (shared global state):**
+
+```tsx
+// ❌ Don't use global variables for Island communication
+let globalCount = 0;
+
+// Island A
+export function CounterIsland() {
+  const [count, setCount] = useState(globalCount);
+  // This won't sync with other Islands
+}
+```
+
+**Correct (useIslandEvent):**
+
+```tsx
+// Island A: Counter (emits updates)
+"use client";
+
+import { useState } from "react";
+import { useIslandEvent } from "@mandujs/core/client";
+
+export function CounterIsland() {
+  const [count, setCount] = useState(0);
+  const { emit } = useIslandEvent<{ count: number }>("counter-update");
+
+  const increment = () => {
+    const newCount = count + 1;
+    setCount(newCount);
+    emit({ count: newCount });  // Notify other Islands
+  };
+
+  return <button onClick={increment}>Count: {count}</button>;
+}
+```
+
+```tsx
+// Island B: Display (receives updates)
+"use client";
+
+import { useState } from "react";
+import { useIslandEvent } from "@mandujs/core/client";
+
+export function DisplayIsland() {
+  const [lastCount, setLastCount] = useState(0);
+
+  useIslandEvent<{ count: number }>("counter-update", (data) => {
+    setLastCount(data.count);  // React to counter updates
+  });
+
+  return <p>Last count received: {lastCount}</p>;
+}
+```
+
+## API Reference
+
+```typescript
+// Emit events
+const { emit } = useIslandEvent<T>(eventName);
+emit(data);
+
+// Listen to events
+useIslandEvent<T>(eventName, (data) => {
+  // Handle received data
+});
+
+// Both emit and listen
+const { emit } = useIslandEvent<T>(eventName, (data) => {
+  // Handle received data
+});
+emit(otherData);
+```
+
+## Common Patterns
+
+### Cart Updates
+
+```tsx
+// Product Island
+emit({ action: "add", productId: 123 });
+
+// Cart Island
+useIslandEvent("cart-update", ({ action, productId }) => {
+  if (action === "add") addToCart(productId);
+});
+```
+
+### Form Validation
+
+```tsx
+// Form Field Island
+emit({ field: "email", valid: true, value: "user@example.com" });
+
+// Submit Button Island
+useIslandEvent("field-change", ({ field, valid }) => {
+  updateFieldStatus(field, valid);
+});
+```

package/src/resources/skills/mandu-hydration/rules/hydration-directive-use-client.md

@@ -0,0 +1,55 @@
+---
+title: Add "use client" Directive for Client Components
+impact: CRITICAL
+impactDescription: Required for client-side interactivity
+tags: hydration, client, directive
+---
+
+## Add "use client" Directive for Client Components
+
+Client components must have `"use client"` directive at the top of the file.
+
+**Incorrect (missing directive):**
+
+```tsx
+// app/counter/client.tsx
+
+import { useState } from "react";
+
+export default function Counter() {
+  const [count, setCount] = useState(0);  // ❌ Will error
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+**Correct (with directive):**
+
+```tsx
+// app/counter/client.tsx
+
+"use client";
+
+import { useState } from "react";
+
+export default function Counter() {
+  const [count, setCount] = useState(0);  // ✅ Works
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+## When to Use "use client"
+
+Use the directive when your component:
+- Uses React hooks (useState, useEffect, useRef, etc.)
+- Has event handlers (onClick, onChange, etc.)
+- Uses browser-only APIs (window, document, localStorage)
+- Needs client-side interactivity
+
+## File Naming Convention
+
+```
+app/
+├── counter/
+│   ├── page.tsx      # Server component (no directive needed)
+│   └── client.tsx    # Client component ("use client" required)
+```

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

@@ -0,0 +1,113 @@
+---
+title: Use Mandu.island() with Setup Function
+impact: HIGH
+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 client";
+
+export default function TodoList({ initialTodos }) {
+  // State, handlers, and JSX all mixed together
+  const [todos, setTodos] = useState(initialTodos);
+  const [input, setInput] = useState("");
+
+  const add = () => {
+    setTodos([...todos, { id: Date.now(), text: input }]);
+    setInput("");
+  };
+
+  return (
+    <div>
+      <input value={input} onChange={e => setInput(e.target.value)} />
+      <button onClick={add}>Add</button>
+      {todos.map(t => <li key={t.id}>{t.text}</li>)}
+    </div>
+  );
+}
+```
+
+**Correct (Mandu.island pattern):**
+
+```tsx
+// spec/slots/todos.client.ts
+
+import { Mandu } from "@mandujs/core/client";
+import { useState, useCallback } from "react";
+
+interface TodosData {
+  todos: { id: number; text: string; done: boolean }[];
+}
+
+export default Mandu.island<TodosData>({
+  // Setup: Initialize client state from server data
+  setup: (serverData) => {
+    const [todos, setTodos] = useState(serverData.todos);
+    const [input, setInput] = useState("");
+
+    const addTodo = useCallback(() => {
+      if (!input.trim()) return;
+      setTodos(prev => [...prev, { id: Date.now(), text: input, done: false }]);
+      setInput("");
+    }, [input]);
+
+    const toggleTodo = useCallback((id: number) => {
+      setTodos(prev => prev.map(t =>
+        t.id === id ? { ...t, done: !t.done } : t
+      ));
+    }, []);
+
+    return { todos, input, setInput, addTodo, toggleTodo };
+  },
+
+  // Render: Pure rendering logic
+  render: ({ todos, input, setInput, addTodo, toggleTodo }) => (
+    <div>
+      <input
+        value={input}
+        onChange={e => setInput(e.target.value)}
+        placeholder="New todo..."
+      />
+      <button onClick={addTodo}>Add</button>
+      <ul>
+        {todos.map(todo => (
+          <li
+            key={todo.id}
+            onClick={() => toggleTodo(todo.id)}
+            style={{ textDecoration: todo.done ? "line-through" : "none" }}
+          >
+            {todo.done ? "✅" : "⬜"} {todo.text}
+          </li>
+        ))}
+      </ul>
+    </div>
+  ),
+
+  // Optional: Error boundary
+  errorBoundary: (error, reset) => (
+    <div>
+      <p>Error: {error.message}</p>
+      <button onClick={reset}>Retry</button>
+    </div>
+  ),
+
+  // Optional: Loading state
+  loading: () => <p>Loading todos...</p>,
+});
+```
+
+## Mandu.island() Options
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `setup` | Yes | Initialize state from server data |
+| `render` | Yes | Pure render function |
+| `errorBoundary` | No | Error UI component |
+| `loading` | No | Loading UI component |

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

@@ -0,0 +1,68 @@
+---
+title: Use Visible Priority for Below-Fold Content
+impact: MEDIUM
+impactDescription: Optimizes initial page load
+tags: hydration, priority, performance
+---
+
+## Use Visible Priority for Below-Fold Content
+
+Set hydration priority based on when the component needs to be interactive.
+
+## Hydration Priorities
+
+| Priority | Load Time | Use Case |
+|----------|-----------|----------|
+| `immediate` | Page load | Critical interactions (header nav, auth forms) |
+| `visible` | Viewport entry (default) | Below-fold content |
+| `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>
+```
+
+## Performance Impact
+
+```
+immediate: +JavaScript bundle at page load
+visible:   +JavaScript when component enters viewport
+idle:      +JavaScript during browser idle time
+interaction: +JavaScript on first user interaction
+```
+
+**Rule of thumb**: Use `visible` (default) unless you have a specific reason to choose another priority.

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

@@ -0,0 +1,85 @@
+---
+name: mandu-performance
+description: |
+  Performance optimization patterns for Mandu applications. Use when optimizing
+  slot handlers, Island components, bundle size, or Bun runtime. Triggers on
+  tasks involving async/await, Promise.all, lazy loading, caching, or performance.
+license: MIT
+metadata:
+  author: mandu
+  version: "1.0.0"
+---
+
+# Mandu Performance
+
+Mandu 애플리케이션의 성능 최적화 가이드. 워터폴 제거, 번들 최적화, 캐싱 패턴, Bun 런타임 활용법을 다룹니다. Vercel의 React Best Practices를 Mandu 컨텍스트로 변환하여 적용합니다.
+
+## When to Apply
+
+Reference these guidelines when:
+- Optimizing slot handler response times
+- Reducing Island component bundle size
+- Implementing caching strategies
+- Working with async/await patterns
+- Leveraging Bun runtime features
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Async Optimization | CRITICAL | `perf-async-` |
+| 2 | Bundle Optimization | CRITICAL | `perf-bundle-` |
+| 3 | Caching Strategies | HIGH | `perf-cache-` |
+| 4 | Bun Runtime | HIGH | `perf-bun-` |
+| 5 | Rendering | MEDIUM | `perf-render-` |
+
+## Quick Reference
+
+### 1. Async Optimization (CRITICAL)
+
+- `perf-async-parallel` - Use Promise.all() for independent operations
+- `perf-async-defer-await` - Move await into branches where actually used
+- `perf-async-early-start` - Start promises early, await late
+
+### 2. Bundle Optimization (CRITICAL)
+
+- `perf-bundle-imports` - Import directly, avoid barrel files
+- `perf-bundle-island-lazy` - Lazy load Islands with dynamic import
+- `perf-bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Caching Strategies (HIGH)
+
+- `perf-cache-slot` - Cache slot responses with appropriate TTL
+- `perf-cache-react` - Use React.cache() for request deduplication
+- `perf-cache-lru` - Use LRU cache for cross-request caching
+
+### 4. Bun Runtime (HIGH)
+
+- `perf-bun-serve` - Optimize Bun.serve() configuration
+- `perf-bun-file` - Use Bun.file() for efficient file operations
+- `perf-bun-sqlite` - Leverage bun:sqlite for fast database access
+
+### 5. Rendering (MEDIUM)
+
+- `perf-render-island-priority` - Set appropriate hydration priority
+- `perf-render-transitions` - Use startTransition for non-urgent updates
+
+## Performance Impact Summary
+
+| Optimization | Typical Improvement |
+|--------------|---------------------|
+| Promise.all() | 2-10× faster |
+| Direct imports | 15-70% faster dev boot |
+| Island lazy loading | 40-60% smaller initial bundle |
+| React.cache() | Eliminates duplicate queries |
+| Bun.file() | 10× faster than Node fs |
+
+## How to Use
+
+Read individual rule files for detailed explanations:
+
+```
+rules/perf-async-parallel.md
+rules/perf-bundle-imports.md
+rules/perf-bun-serve.md
+```

package/src/resources/skills/mandu-performance/metadata.json

@@ -0,0 +1,14 @@
+{
+  "version": "1.0.0",
+  "organization": "Mandu Framework",
+  "date": "February 2026",
+  "abstract": "Mandu 애플리케이션 성능 최적화 가이드. 워터폴 제거 (Promise.all), 번들 최적화 (직접 import, lazy loading), 캐싱 전략 (React.cache, LRU), Bun 런타임 활용 (Bun.serve, Bun.file)을 다룹니다. Vercel React Best Practices 기반으로 Mandu 컨텍스트에 맞게 변환되었습니다.",
+  "references": [
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast",
+    "https://bun.sh/docs/api/http",
+    "https://bun.sh/docs/api/file-io",
+    "https://react.dev/reference/react/cache"
+  ],
+  "tags": ["performance", "async", "bundle", "cache", "bun", "mandu"]
+}

package/src/resources/skills/mandu-performance/rules/_sections.md

@@ -0,0 +1,31 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Async Optimization (perf-async)
+
+**Impact:** CRITICAL
+**Description:** 워터폴은 성능의 #1 킬러입니다. 순차적 await는 매번 전체 네트워크 지연을 추가합니다. 워터폴 제거가 가장 큰 성능 향상을 가져옵니다.
+
+## 2. Bundle Optimization (perf-bundle)
+
+**Impact:** CRITICAL
+**Description:** 초기 번들 크기 감소는 Time to Interactive와 Largest Contentful Paint를 개선합니다. Island lazy loading과 직접 import가 핵심입니다.
+
+## 3. Caching Strategies (perf-cache)
+
+**Impact:** HIGH
+**Description:** 적절한 캐싱은 불필요한 연산과 네트워크 요청을 제거합니다. React.cache()는 요청 내 중복 제거, LRU는 요청 간 캐싱에 사용합니다.
+
+## 4. Bun Runtime (perf-bun)
+
+**Impact:** HIGH
+**Description:** Bun의 네이티브 API (Bun.serve, Bun.file, bun:sqlite)는 Node.js 대비 현저히 빠릅니다. Mandu는 Bun 기반이므로 이를 최대한 활용해야 합니다.
+
+## 5. Rendering Performance (perf-render)
+
+**Impact:** MEDIUM
+**Description:** Island hydration 우선순위 설정과 startTransition 활용으로 사용자 체감 성능을 개선합니다.

package/src/resources/skills/mandu-performance/rules/_template.md

@@ -0,0 +1,64 @@
+# Rule Template
+
+Use this template when creating new rules for mandu-performance.
+
+---
+
+```markdown
+---
+title: Rule Title Here
+impact: CRITICAL | HIGH | MEDIUM | LOW
+impactDescription: 개선 수치 (예: "2-10× improvement", "40% faster")
+tags: performance, tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: {LEVEL} ({impactDescription})**
+
+규칙의 목적과 성능 영향을 설명합니다.
+
+**Incorrect (문제점 - 성능 영향 명시):**
+
+\`\`\`typescript
+// ❌ 순차 실행: 3번의 네트워크 왕복
+const user = await fetchUser();
+const posts = await fetchPosts();
+const comments = await fetchComments();
+// 총 시간: 100ms + 100ms + 100ms = 300ms
+\`\`\`
+
+**Correct (해결책 - 성능 개선 명시):**
+
+\`\`\`typescript
+// ✅ 병렬 실행: 1번의 네트워크 왕복
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments(),
+]);
+// 총 시간: max(100ms, 100ms, 100ms) = 100ms
+\`\`\`
+
+## Mandu Context
+
+Mandu에서 이 규칙을 적용하는 구체적인 방법을 설명합니다.
+
+Reference: [관련 문서 링크](https://example.com)
+```
+
+---
+
+## Naming Convention
+
+- 파일명: `perf-{category}-{rule-name}.md`
+- 예시: `perf-async-parallel.md`, `perf-bundle-imports.md`
+
+## Impact Measurement
+
+| Level | Typical Improvement |
+|-------|---------------------|
+| CRITICAL | 2-10× or 50%+ |
+| HIGH | 20-50% |
+| MEDIUM | 10-20% |
+| LOW | < 10% |

package/src/resources/skills/mandu-performance/rules/perf-async-defer-await.md

@@ -0,0 +1,103 @@
+---
+title: Defer await to Where Actually Used
+impact: CRITICAL
+impactDescription: Eliminates unnecessary blocking
+tags: performance, async, await, slot
+---
+
+## Defer await to Where Actually Used
+
+**Impact: CRITICAL (Eliminates unnecessary blocking)**
+
+await는 실제로 값이 필요한 시점까지 지연하세요. 함수 시작에서 모든 것을 await하면 불필요한 블로킹이 발생합니다.
+
+**Incorrect (너무 일찍 await):**
+
+```typescript
+// spec/slots/user.slot.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const userId = ctx.params.id;
+
+    // ❌ 캐시 확인 전에 DB 쿼리 시작하고 대기
+    const user = await fetchUserFromDB(userId);
+
+    // 캐시에 있으면 DB 쿼리는 불필요했음
+    const cached = cache.get(`user:${userId}`);
+    if (cached) {
+      return ctx.ok(cached);
+    }
+
+    return ctx.ok(user);
+  });
+```
+
+**Correct (필요한 시점에 await):**
+
+```typescript
+// spec/slots/user.slot.ts
+import { Mandu } from "@mandujs/core";
+
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const userId = ctx.params.id;
+
+    // 캐시 먼저 확인
+    const cached = cache.get(`user:${userId}`);
+    if (cached) {
+      return ctx.ok(cached);  // DB 쿼리 안 함
+    }
+
+    // ✅ 캐시 미스일 때만 DB 쿼리
+    const user = await fetchUserFromDB(userId);
+    cache.set(`user:${userId}`, user);
+
+    return ctx.ok(user);
+  });
+```
+
+## Promise 시작은 일찍, await는 늦게
+
+```typescript
+export default Mandu.filling()
+  .get(async (ctx) => {
+    // ✅ Promise 시작 (블로킹 없음)
+    const userPromise = fetchUser(ctx.params.id);
+    const configPromise = fetchConfig();
+
+    // 동기 작업 수행
+    const requestId = generateRequestId();
+    const timestamp = Date.now();
+    logRequest(requestId, timestamp);
+
+    // ✅ 필요한 시점에 await
+    const [user, config] = await Promise.all([userPromise, configPromise]);
+
+    return ctx.ok({ user, config, requestId });
+  });
+```
+
+## 조건부 분기에서의 활용
+
+```typescript
+export default Mandu.filling()
+  .get(async (ctx) => {
+    const { type } = ctx.query;
+
+    if (type === "summary") {
+      // 요약만 필요하면 상세 데이터 불필요
+      const summary = await fetchSummary(ctx.params.id);
+      return ctx.ok({ summary });
+    }
+
+    // 상세 데이터가 필요한 경우에만 fetch
+    const [summary, details] = await Promise.all([
+      fetchSummary(ctx.params.id),
+      fetchDetails(ctx.params.id),
+    ]);
+
+    return ctx.ok({ summary, details });
+  });
+```