mandu-hydration

name	mandu-hydration
description	Island Hydration pattern for Mandu. Use when creating interactive components, client-side state, or partial hydration. Triggers on tasks involving "use client", client.tsx, useState, useEffect, Island, or hydration.
license	MIT
metadata	{"author":"mandu","version":"1.0.0"}

Mandu Island Hydration

Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다. 대부분의 페이지는 정적 HTML로 유지하고, 필요한 부분만 JavaScript를 로드합니다.

Agent Workflow Contract

This skill is a Domain addendum. It must not replace mandu-agent-workflow. Use it only after mandu.agent.plan selects the hydration, island, partial, or route domain.

Canonical workflow step: plan -> apply -> verify -> repair.

Preferred MCP tools:

Step	Tools
plan	mandu.agent.plan, mandu.island.list
apply	mandu.agent.apply, mandu.hydration.set, mandu.hydration.addClientSlot
verify	mandu.agent.verify, mandu.build, mandu.build.status
repair	mandu.agent.repair

Allowed file edits:

• app/**/*.partial.tsx, app/**/*.island.tsx, route-local client components
• Page hydration metadata only when the plan names the route
• Shared client utilities only after inspecting existing client boundaries

Verification command:

mandu agent verify --changed --json --write

Common failures:

• Rendering page-level islands inline instead of using partial().Render
• Forgetting route hydration metadata when a server page renders partials
• Moving server-only imports into client bundles

Repair path:

mandu agent repair --from .mandu/agent-verify.json --json

When to Apply

Reference these guidelines when:

• Creating interactive client components
• Adding client-side state to pages
• Implementing partial hydration
• Setting up client-server data flow
• Working with Island communication

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Client Directive	CRITICAL	hydration-directive-
2	Island Structure	HIGH	hydration-island-
3	Hydration Priority	MEDIUM	hydration-priority-
4	Data Flow	MEDIUM	hydration-data-

Quick Reference

1. Client Directive (CRITICAL)

• hydration-directive-use-client - Add "use client" directive for client components
• hydration-directive-file-naming - Use .client.tsx for client component files

2. Island Structure (HIGH)

• hydration-island-setup - Use Mandu.island() with setup function
• hydration-island-render - Separate state logic from render

3. Hydration Priority (MEDIUM)

• hydration-priority-immediate - Load on page load (critical interactions)
• hydration-priority-visible - Load when visible (default)
• hydration-priority-idle - Load when browser idle
• hydration-priority-interaction - Load on user interaction

4. Data Flow (MEDIUM)

• 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

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

import {
  useServerData,
  useHydrated,
  useIslandEvent,
} from "@mandujs/core/client";

// Access SSR data
const data = useServerData<UserData>("user", defaultValue);

// Check hydration status
const isHydrated = useHydrated();

How to Use

Read individual rule files for detailed explanations:

rules/hydration-directive-use-client.md
rules/hydration-island-setup.md