@ubean/islands 0.6.2 → 0.6.4

package/README.md

@@ -0,0 +1,294 @@
+# @ubean/islands
+
+**English | [中文](./README.zh-CN.md)**
+
+Islands architecture for ubean — partial hydration for Vue components, plus the server-component protocol.
+
+`@ubean/islands` owns everything about **partial hydration** in ubean: the `v-client.*` directive family, the build-time transform that turns directives into `<ubean-island>` elements, the auto-generated registry virtual module, the client hydration runtime, the `.server.vue` / `.client.vue` file conventions, and the `POST /__server-component` endpoint for re-rendering server islands.
+
+```vue
+<script setup lang="ts">
+import Counter from '~/components/Counter.vue';
+</script>
+
+<template>
+  <Counter v-client.load :initial="0" />
+</template>
+```
+
+## Table of Contents
+
+- [Package Positioning](#package-positioning)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [The `v-client` Directive](#the-v-client-directive)
+  - [`v-client.only` vs `<ClientOnly>`](#v-clientonly-vs-clientonly)
+- [Directive API](#directive-api)
+- [Programmatic Wrappers](#programmatic-wrappers)
+- [Server / Client Components](#server--client-components)
+  - [Constraints](#constraints)
+- [Islands Registry](#islands-registry)
+- [Server Component Endpoint](#server-component-endpoint)
+- [Vite Plugin API](#vite-plugin-api)
+- [SSR Helpers](#ssr-helpers)
+- [Type Safety](#type-safety)
+- [Architecture Notes](#architecture-notes)
+
+## Package Positioning
+
+`@ubean/islands` is the **islands runtime and build-time transform**:
+
+| Layer                       | Responsibility                                                                                                                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@ubean/islands` (this pkg) | `v-client.*` directive, island/registry transform, hydration runtime, `.server.vue` / `.client.vue`, `POST /__server-component`                  |
+| `@ubean/vue`                | Page routing and the lean kernel; `<ClientOnly>` and the page/cache/transition layer live there — this package only adds island hydration on top |
+| `@ubean/client`             | Calls `hydrateIslands()` automatically after mount and after each SPA navigation — the framework's bridge to this runtime                        |
+| `@ubean/build`              | Wires `ubeanIslandsPlugin()` into `ubeanPlugin()`; the app factory mounts `createServerComponentMiddleware()`                                    |
+
+**Included:**
+
+- The `v-client.load` / `.idle` / `.visible` / `.media` / `.only` directive family and its strategy resolvers
+- `defineIsland` (client island) / `defineServerIsland` (server island) / `defineClientComponent` / `definePairedComponent`
+- The client hydration runtime: `hydrateIslands`, `collectIslands`, `hydrateIsland`, `hasPendingIslands`, `scheduleIslandHydration`
+- The bootstrap script (`getIslandsBootstrapScript`) and its clear script
+- The server-component protocol: `SERVER_COMPONENT_ENDPOINT`, `registerServerComponent`, `getServerComponent`, `createServerComponentMiddleware`
+- The Vite plugin (`/vite` subpath): directive scan, `<ubean-island>` transform, registry virtual module, `.server.vue` / `.client.vue` resolution and the restricted-parent check
+- SSR helpers for rendering placeholders (`createIslandsContext`, `registerIsland`, `getIslandsScript`, `generateIslandPlaceholder`, `renderIslandPlaceholder`, `hydrationStrategyMeta`)
+
+**NOT included:**
+
+- Page routing, `<ClientOnly>`, page cache, page transitions, `definePage` — `@ubean/vue`
+- App factories, `defineApp`, the automatic post-mount hydration call and the data layer — `@ubean/client`
+- Full SSR rendering (streaming, head merging, deferred payloads) — `@ubean/client/ssr` and `@ubean/pages`
+- Server routing and the Hono app — `@ubean/app`
+
+**Runtime dependency whitelist (main entry): `vue`.** The main entry imports only `./directive` and `./runtime` — no `node:*`, no `vite`. `hono` and `pathe` are used by the server-component middleware and the Vite plugin, which live behind the `/server` and `/vite` subpaths. `vite` is an **optional peer** used only by the build-time subpath.
+
+## Install
+
+```bash
+pnpm add ubean          # or: pnpm add @ubean/islands
+# build-time (the /vite subpath):
+pnpm add -D vite
+```
+
+## Quick Start
+
+**1. Vite config** — the plugin scans `.vue` files, transforms `v-client.*` tags and generates the registry:
+
+```ts
+// vite.config.ts
+import vue from '@vitejs/plugin-vue';
+import { ubeanIslandsPlugin } from '@ubean/islands/vite';
+
+export default {
+  plugins: [vue(), ubeanIslandsPlugin()]
+};
+```
+
+**2. Mark the interactive component** — put the directive on the **component element**, not a plain `<div>`:
+
+```vue
+<script setup lang="ts">
+import Counter from '~/components/Counter.vue';
+import HeavyChart from '~/components/HeavyChart.vue';
+</script>
+
+<template>
+  <Counter v-client.load />
+  <HeavyChart v-client.idle />
+</template>
+```
+
+**3. Nothing else.** Import the component in `<script setup>` and the framework hydrates it after mount — no code in `app.ts` is required.
+
+A complete example lives in [`apps/docs/src/content/en/guide/islands.md`](../../apps/docs/src/content/en/guide/islands.md).
+
+## The `v-client` Directive
+
+The modifier selects the hydration strategy — one directive per strategy, all declared on the component tag:
+
+| Directive          | Strategy    | Hydrates when                                      |
+| ------------------ | ----------- | -------------------------------------------------- |
+| `v-client.load`    | `'load'`    | Immediately on page load                           |
+| `v-client.idle`    | `'idle'`    | Browser is idle (`requestIdleCallback`)            |
+| `v-client.visible` | `'visible'` | Element scrolls into view (`IntersectionObserver`) |
+| `v-client.media`   | `'media'`   | A CSS media query matches (value is the query)     |
+| `v-client.only`    | `'only'`    | Client only — no SSR output for this component     |
+
+```vue
+<template>
+  <Counter v-client.load />
+  <HeavyChart v-client.idle />
+  <Comments v-client.visible />
+  <MobileNav v-client.media="'(max-width: 768px)'" />
+  <ClientOnlyWidget v-client.only />
+</template>
+```
+
+The value of `.media` is a Vue expression, so a string literal must be quoted. Props passed to an island must be JSON-serializable (strings, numbers, booleans, arrays, plain objects).
+
+### `v-client.only` vs `<ClientOnly>`
+
+`<ClientOnly>` (from `@ubean/vue` / `@ubean/client`) covers the non-island case and takes a `fallback` prop / `#fallback` slot:
+
+| Use `v-client.only`                                           | Use `<ClientOnly>`                                                                              |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Component-level islands (registry-driven hydration)           | Template fragments / plain HTML (the islands transform only matches capitalized component tags) |
+| Needs a deferral strategy alongside (load/idle/visible/media) | Same-tree rendering with full app context                                                       |
+| Content is replaced by a separate app on hydration            | Must not sit inside an island placeholder (it is wiped when the island hydrates)                |
+
+## Directive API
+
+```ts
+import {
+  vClient,
+  resolveClientStrategy,
+  strategyToLegacyDirective,
+  legacyDirectiveToStrategy
+} from '@ubean/islands/directive';
+
+vClient; // the Vue directive object (ObjectDirective<HTMLElement, string, ClientStrategy>)
+resolveClientStrategy({ load: true, media: true }); // → 'load' | 'idle' | 'visible' | 'media' | 'only'
+```
+
+- `ClientStrategy = 'load' | 'idle' | 'visible' | 'media' | 'only'`; `ClientDirective = 'client:load' | 'client:idle' | 'client:visible' | 'client:media' | 'client:only'`.
+- `applyStrategy(el, strategy, mediaQuery?)` / `cleanupStrategy(el)` are the imperative primitives the directive uses.
+- The `data-*` protocol attributes are exported for tooling: `CLIENT_DIRECTIVE_ATTR` (`data-client-directive`), `CLIENT_MEDIA_ATTR` (`data-media`), `CLIENT_ONLY_ATTR` (`data-client-only`).
+- The `/directive` subpath is browser-safe and has no build-time dependency — it is what `@ubean/client` imports.
+
+## Programmatic Wrappers
+
+```ts
+import { defineIsland, defineServerIsland } from '@ubean/islands';
+import AsyncChart from '~/components/AsyncChart.vue';
+import Counter from '~/components/Counter.vue';
+
+// Client island; strategy: 'load' | 'idle' | 'visible' | 'media' | 'only'
+const CounterIsland = defineIsland(Counter, 'load');
+
+// 'media' requires a mediaQuery; props can be pre-bound
+const MobileNavIsland = defineIsland(MobileNav, 'media', {
+  mediaQuery: '(max-width: 768px)',
+  props: { theme: 'dark' }
+});
+
+// Server island — wraps the async component in <Suspense> with a fallback
+const Chart = defineServerIsland(AsyncChart, { fallback: '<div class="skeleton">Loading…</div>' });
+```
+
+- `IslandOptions = { mediaQuery?: string, props?: Record<string, unknown> }`.
+- `ServerIslandOptions = { fallback?: Component | string, rerenderOnPropsChange?: boolean }`. When omitted, a `<ubean-defer-fallback>` placeholder is used.
+- With `rerenderOnPropsChange: true`, the client requests the server-rendered HTML once after mount and again whenever props change, replacing the container's content; the SSR side registers the component so the endpoint can find it. The Vite plugin injects the component's absolute path as the third argument — without it the option degrades to `false`.
+- `defineClientComponent(component)` and `definePairedComponent(ServerComp, ClientComp)` are the runtime halves of the `.client.vue` and `.server.vue` + `.client.vue` conventions; both are normally generated by the plugin, not written by hand.
+
+## Server / Client Components
+
+Two file-name conventions for components that belong to exactly one build graph. The plugin handles resolution — no import change and no directive needed.
+
+- **`Foo.client.vue`** — renders only on the client. SSR emits a `<!--client-only-->` comment placeholder and the real component replaces it after mount. For components that need browser APIs.
+- **`Foo.server.vue`** — renders only on the server. The client build swaps the import for a stub, so neither the implementation nor its imports reach the client bundle. For server-only access (env vars, databases).
+- **`Foo.server.vue` + `Foo.client.vue` together** — import the base name (`import Foo from './Foo.vue'`); that file must **not** exist. SSR renders the server half, the client half takes over after mount.
+
+### Constraints
+
+**A `.server.vue` must be a `<template>`-form SFC.** The server wraps the template in `<ubean-server-only v-once>` so hydration can match it; a render-function SFC (or `export { default } from …`) has nothing to wrap and the build fails with that reason.
+
+**A `.server.vue` occupies a wrapper element, so its context matters.** The client keeps a stub in the tree and hydration preserves the server-rendered children by matching that element. The wrapper is an ordinary flow element, so a server component may only be used where a flow element is allowed:
+
+```html
+<!-- breaks: the wrapper is not valid inside <tr>, so the parser hoists it out of the table -->
+<table>
+  <tr>
+    <ServerGreeting />
+  </tr>
+</table>
+
+<!-- fine: the server component renders the container itself -->
+<ServerTable />
+```
+
+**The plugin rejects this at transform time** (dev overlay / `vite build` error), naming the parent and the component. The failure is deliberate: the symptom it prevents is silent in production — content appears _outside_ the container before hydration, and afterwards Vue reports `Hydration node mismatch` / `Hydration children mismatch` and removes the content.
+
+The check covers table ancestors (`table`, `thead`, `tbody`, `tfoot`, `tr`, `colgroup`) and `select` / `optgroup`. It deliberately does **not** cover `ul` / `ol` / `dl`: there the wrapper stays put, so both sides produce the same DOM and hydration is fine.
+
+Workarounds: let the server component render the container (the whole `<table>` / `<ul>`), or place it inside an allowed child (`<td>`, `<li>`). `.client.vue` has no such constraint — a comment node is legal in every context.
+
+## Islands Registry
+
+`virtual:ubean-islands-registry` is generated by the plugin from the `<script setup>` imports of every file that uses a `v-client.*` directive:
+
+```ts
+declare module 'virtual:ubean-islands-registry' {
+  export const islands: Record<string, Component | (() => Promise<Component>)>;
+}
+```
+
+- The key is the **template tag name**; the value is a lazy loader, so island components never land in the entry chunk.
+- The module exports `{}` when nothing was scanned.
+- `ISLANDS_REGISTRY_VIRTUAL_ID` (from `/vite`) is the virtual module id; the `/virtual-registration` subpath is **types-only** (`"import": null`) — it exists so editors can resolve the module's type without pulling in the plugin.
+- A component reached only through a global registration, `defineAsyncComponent` or a dynamic import cannot be auto-registered; pass it manually through `hydrateIslands({ components })` (manual entries win).
+- Only components actually used with a `v-client.*` directive are included in the client bundle.
+
+The pipeline, end to end: **scan** `.vue` files → **transform** island tags into `<ubean-island v-once>` (with serialized props in data attributes) → **resolve** import paths → **generate** the registry virtual module → **bridge** it through `hydrateIslands` in `@ubean/client` → **auto-hydrate** after mount (double `requestAnimationFrame`) and after each SPA navigation.
+
+## Server Component Endpoint
+
+`createServerComponentMiddleware()` handles `POST /__server-component` — the endpoint the client island wrapper posts to when it needs fresh server HTML:
+
+```ts
+import { SERVER_COMPONENT_ENDPOINT, createServerComponentMiddleware } from '@ubean/islands/server';
+
+SERVER_COMPONENT_ENDPOINT; // '/__server-component'
+app.use('*', createServerComponentMiddleware());
+```
+
+- Request body: `{ "path": "/abs/path/Foo.server.vue", "props": { … } }`.
+- Responses: `200` HTML / `400` missing path / `404` unregistered component / `500` render failure; every response carries `Cache-Control: no-store`.
+- `registerServerComponent(path, component)` / `getServerComponent(path)` are the registry accessors the SSR renderer and the middleware share.
+- The registry deliberately lives on **`globalThis`**: in dev the SSR graph inlines this package's runtime while `@ubean/app` resolves `@ubean/islands/server` through Node, so a module-level `Map` would give the two instances different registries — the middleware would 404 for components that were registered (guard: `packages/islands/test/server-component-registry-singleton.test.ts`).
+- `isServerComponentRequest(c)` / `isServerComponentResponse(response)` and `SERVER_COMPONENT_RESPONSE_HEADER` (`x-ubean-server-component`) let a request-logging or proxy layer identify these calls.
+
+## Vite Plugin API
+
+```ts
+import { ubeanIslandsPlugin } from '@ubean/islands/vite';
+
+export default {
+  plugins: [ubeanIslandsPlugin({ enabled: true })]
+};
+```
+
+`UbeanIslandsPluginOptions = { enabled?: boolean }`. The subpath also exposes the transform's building blocks for advanced integrations: `isServerComponentFile`, `isClientComponentFile`, `hasServerComponentTemplate`, `wrapServerComponentTemplate`, `findRestrictedServerComponentUsage`, `injectServerComponentPath`, `transformVueSfcIslands`, `collectIslandComponents`, `generateRegistryModule`, `parseScriptImports`, `resolveIslandImportPath`, `scanIslandDirectiveNames`, plus the virtual ids `ISLANDS_REGISTRY_VIRTUAL_ID`, `SERVER_COMPONENT_STUB_VIRTUAL_ID` and `CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID`.
+
+The plugin is intentionally **not** re-exported from the main entry — it pulls `node:fs` / `node:path`, which must not reach a browser bundle.
+
+## SSR Helpers
+
+```ts
+import { createIslandsContext, registerIsland, getIslandsScript, renderIslandPlaceholder } from '@ubean/islands';
+
+const ctx = createIslandsContext();
+const id = registerIsland(ctx, 'Counter', 'client:load', { initial: 10 });
+const html = renderIslandPlaceholder({ component: 'Counter', directive: 'client:load', props: { initial: 10 } });
+const script = getIslandsScript([...ctx.islands.values()]);
+```
+
+- `getIslandsBootstrapScript()` emits the IIFE that marks islands for hydration according to their strategy; `getIslandsClearScript()` its counterpart.
+- `hydrationStrategyMeta` maps each directive to its strategy metadata.
+- These are for custom SSR pipelines; the framework's own renderer already calls them.
+
+## Type Safety
+
+- `ClientStrategy` / `ClientDirective` / `ClientDirectiveBinding` / `VClientDirective` type the directive; `IslandStrategy` / `IslandOptions` / `ServerIslandOptions` the wrappers.
+- `IslandRecord` / `IslandHydrateOptions` / `HydrateIslandsOptions` / `IslandHydrationScheduler` type the hydration runtime; `IslandsContext` / `IslandDefinition` / `IslandSsrOptions` the SSR helpers.
+- `declare module 'virtual:ubean-islands-registry'` ships with the package, so the virtual module is typed without extra setup.
+
+## Architecture Notes
+
+- **Two layers, one job:** the `v-client.*` directive is the authoring surface; the registry plus the hydration runtime is the mechanism. You never call `hydrateIslands()` by hand in a normal app.
+- **Browser-safe main entry:** `dist/index.js` imports only `./directive` and `./runtime`. The Vite plugin (`/vite`) and the Hono middleware (`/server`) are separate subpaths.
+- **Registry on `globalThis`:** required because dev loads two module instances (see above); a module-scoped `Map` would silently split the registry.
+- **The transform is deliberate about HTML parsing:** only parents where the parser actually reparents or drops the wrapper are rejected; `ul` / `ol` / `dl` are left alone to avoid false positives.
+- **Progressive enhancement of the transform:** the plugin errors at build time rather than letting hydration remove content silently in production.
+- **Ownership:** `@ubean/build` wires the plugin; `@ubean/client` owns the automatic hydration call; `@ubean/islands` owns the mechanism.

package/README.zh-CN.md

@@ -0,0 +1,296 @@
+# @ubean/islands
+
+**[English](./README.md) | 中文**
+
+ubean 的 Islands 架构 —— Vue 组件的局部水合，以及服务端组件协议。
+
+`@ubean/islands` 拥有 ubean 中**局部水合**的全部内容：`v-client.*` 指令族、把指令转换为 `<ubean-island>` 元素的构建期转换、自动生成的注册表虚拟模块、客户端水合运行时、`.server.vue` / `.client.vue` 文件约定，以及用于重渲染服务端岛屿的 `POST /__server-component` 端点。
+
+```vue
+<script setup lang="ts">
+import Counter from '~/components/Counter.vue';
+</script>
+
+<template>
+  <Counter v-client.load :initial="0" />
+</template>
+```
+
+## 目录
+
+- [@ubean/islands](#ubeanislands)
+  - [目录](#目录)
+  - [包定位](#包定位)
+  - [安装](#安装)
+  - [快速开始](#快速开始)
+  - [`v-client` 指令](#v-client-指令)
+    - [`v-client.only` 与 `<ClientOnly>`](#v-clientonly-与-clientonly)
+  - [指令 API](#指令-api)
+  - [编程式包装器](#编程式包装器)
+  - [Server / Client 组件](#server--client-组件)
+    - [约束](#约束)
+  - [Islands 注册表](#islands-注册表)
+  - [服务端组件端点](#服务端组件端点)
+  - [Vite 插件 API](#vite-插件-api)
+  - [SSR 助手](#ssr-助手)
+  - [类型安全](#类型安全)
+  - [架构说明](#架构说明)
+
+## 包定位
+
+`@ubean/islands` 是**岛屿运行时 + 构建期转换**：
+
+| 分层                     | 职责                                                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `@ubean/islands`（本包） | `v-client.*` 指令、岛屿/注册表转换、水合运行时、`.server.vue` / `.client.vue`、`POST /__server-component` |
+| `@ubean/vue`             | 页面路由与精简内核；`<ClientOnly>` 与页面/缓存/过渡层在那里 —— 本包只是在其上叠加岛屿水合                 |
+| `@ubean/client`          | mount 之后与每次 SPA 导航后自动调用 `hydrateIslands()` —— 框架通往本运行时的桥                            |
+| `@ubean/build`           | 把 `ubeanIslandsPlugin()` 接进 `ubeanPlugin()`；应用工厂挂载 `createServerComponentMiddleware()`          |
+
+**包含：**
+
+- `v-client.load` / `.idle` / `.visible` / `.media` / `.only` 指令族及其策略解析器
+- `defineIsland`（客户端岛屿）/ `defineServerIsland`（服务端岛屿）/ `defineClientComponent` / `definePairedComponent`
+- 客户端水合运行时：`hydrateIslands`、`collectIslands`、`hydrateIsland`、`hasPendingIslands`、`scheduleIslandHydration`
+- 引导脚本（`getIslandsBootstrapScript`）及其清理脚本
+- 服务端组件协议：`SERVER_COMPONENT_ENDPOINT`、`registerServerComponent`、`getServerComponent`、`createServerComponentMiddleware`
+- Vite 插件（`/vite` 子路径）：指令扫描、`<ubean-island>` 转换、注册表虚拟模块、`.server.vue` / `.client.vue` 解析与受限父级检查
+- 用于渲染占位符的 SSR 助手（`createIslandsContext`、`registerIsland`、`getIslandsScript`、`generateIslandPlaceholder`、`renderIslandPlaceholder`、`hydrationStrategyMeta`）
+
+**不包含：**
+
+- 页面路由、`<ClientOnly>`、页面缓存、页面过渡、`definePage` —— `@ubean/vue`
+- 应用工厂、`defineApp`、mount 后的自动水合调用、数据层 —— `@ubean/client`
+- 完整 SSR 渲染（流式、head 合并、延迟数据 payload）—— `@ubean/client/ssr` 与 `@ubean/pages`
+- 服务端路由与 Hono 应用 —— `@ubean/app`
+
+**运行时依赖白名单（主入口）：`vue`。** 主入口只导入 `./directive` 与 `./runtime` —— 没有 `node:*`，也没有 `vite`。`hono` 与 `pathe` 由服务端组件中间件与 Vite 插件使用，它们分别位于 `/server` 与 `/vite` 子路径之后。`vite` 是 **optional peer**，仅构建期子路径使用。
+
+## 安装
+
+```bash
+pnpm add ubean          # 或：pnpm add @ubean/islands
+# 构建期（/vite 子路径）：
+pnpm add -D vite
+```
+
+## 快速开始
+
+**1. Vite 配置** —— 插件扫描 `.vue` 文件、转换 `v-client.*` 标签并生成注册表：
+
+```ts
+// vite.config.ts
+import vue from '@vitejs/plugin-vue';
+import { ubeanIslandsPlugin } from '@ubean/islands/vite';
+
+export default {
+  plugins: [vue(), ubeanIslandsPlugin()]
+};
+```
+
+**2. 标记交互组件** —— 指令要落在**组件元素**上，而不是普通 `<div>`：
+
+```vue
+<script setup lang="ts">
+import Counter from '~/components/Counter.vue';
+import HeavyChart from '~/components/HeavyChart.vue';
+</script>
+
+<template>
+  <Counter v-client.load />
+  <HeavyChart v-client.idle />
+</template>
+```
+
+**3. 其余什么都不用做。** 在 `<script setup>` 中导入组件，框架会在 mount 后自动水合 —— `app.ts` 中无需任何代码。
+
+完整示例见 [`apps/docs/src/content/en/guide/islands.md`](../../apps/docs/src/content/en/guide/islands.md)。
+
+## `v-client` 指令
+
+修饰符决定水合策略 —— 每条策略一个指令，都声明在组件标签上：
+
+| 指令               | 策略        | 何时水合                                  |
+| ------------------ | ----------- | ----------------------------------------- |
+| `v-client.load`    | `'load'`    | 页面加载后立即水合                        |
+| `v-client.idle`    | `'idle'`    | 浏览器空闲时（`requestIdleCallback`）     |
+| `v-client.visible` | `'visible'` | 元素进入视口时（`IntersectionObserver`）  |
+| `v-client.media`   | `'media'`   | 某条 CSS media query 命中时（值为该查询） |
+| `v-client.only`    | `'only'`    | 仅客户端 —— 该组件不产出 SSR HTML         |
+
+```vue
+<template>
+  <Counter v-client.load />
+  <HeavyChart v-client.idle />
+  <Comments v-client.visible />
+  <MobileNav v-client.media="'(max-width: 768px)'" />
+  <ClientOnlyWidget v-client.only />
+</template>
+```
+
+`.media` 的值是 Vue 表达式，因此字符串字面量必须加引号。传给岛屿的 props 必须可 JSON 序列化（字符串、数字、布尔、数组、纯对象）。
+
+### `v-client.only` 与 `<ClientOnly>`
+
+`<ClientOnly>`（来自 `@ubean/vue` / `@ubean/client`）覆盖非岛屿场景，接受 `fallback` prop / `#fallback` slot：
+
+| 用 `v-client.only`                              | 用 `<ClientOnly>`                                          |
+| ----------------------------------------------- | ---------------------------------------------------------- |
+| 组件级岛屿（由注册表驱动水合）                  | 模板片段 / 普通 HTML（岛屿转换只匹配首字母大写的组件标签） |
+| 需要同时指定延后策略（load/idle/visible/media） | 同树渲染且拥有完整应用上下文                               |
+| 组件内容由独立应用在 hydration 时替换           | 不能放进岛屿占位符内部（岛屿水合时会被清除）               |
+
+## 指令 API
+
+```ts
+import {
+  vClient,
+  resolveClientStrategy,
+  strategyToLegacyDirective,
+  legacyDirectiveToStrategy
+} from '@ubean/islands/directive';
+
+vClient; // Vue 指令对象（ObjectDirective<HTMLElement, string, ClientStrategy>）
+resolveClientStrategy({ load: true, media: true }); // → 'load' | 'idle' | 'visible' | 'media' | 'only'
+```
+
+- `ClientStrategy = 'load' | 'idle' | 'visible' | 'media' | 'only'`；`ClientDirective = 'client:load' | 'client:idle' | 'client:visible' | 'client:media' | 'client:only'`。
+- `applyStrategy(el, strategy, mediaQuery?)` / `cleanupStrategy(el)` 是指令底层的命令式原语。
+- 供工具链使用的 `data-*` 协议属性已导出：`CLIENT_DIRECTIVE_ATTR`（`data-client-directive`）、`CLIENT_MEDIA_ATTR`（`data-media`）、`CLIENT_ONLY_ATTR`（`data-client-only`）。
+- `/directive` 子路径浏览器安全且无构建期依赖 —— `@ubean/client` 导入的正是它。
+
+## 编程式包装器
+
+```ts
+import { defineIsland, defineServerIsland } from '@ubean/islands';
+import AsyncChart from '~/components/AsyncChart.vue';
+import Counter from '~/components/Counter.vue';
+
+// 客户端岛屿；strategy: 'load' | 'idle' | 'visible' | 'media' | 'only'
+const CounterIsland = defineIsland(Counter, 'load');
+
+// 'media' 必须提供 mediaQuery；props 可预先绑定
+const MobileNavIsland = defineIsland(MobileNav, 'media', {
+  mediaQuery: '(max-width: 768px)',
+  props: { theme: 'dark' }
+});
+
+// 服务端岛屿 —— 把异步组件包进带 fallback 的 <Suspense>
+const Chart = defineServerIsland(AsyncChart, { fallback: '<div class="skeleton">Loading…</div>' });
+```
+
+- `IslandOptions = { mediaQuery?: string, props?: Record<string, unknown> }`。
+- `ServerIslandOptions = { fallback?: Component | string, rerenderOnPropsChange?: boolean }`。省略时使用 `<ubean-defer-fallback>` 占位元素。
+- 开启 `rerenderOnPropsChange: true` 后，客户端在 mount 后请求一次服务端渲染的 HTML，并在 props 变化时重复请求，用返回值替换容器内容；SSR 侧会把组件注册进全局注册表以便端点查找。Vite 插件会注入组件绝对路径作为第三个参数 —— 没有该参数时该选项退化为 `false`。
+- `defineClientComponent(component)` 与 `definePairedComponent(ServerComp, ClientComp)` 分别是 `.client.vue` 与 `.server.vue` + `.client.vue` 约定的运行时半边；两者通常由插件生成，无需手写。
+
+## Server / Client 组件
+
+两个文件名约定，用于只属于单一构建图的组件。插件负责解析 —— 无需改导入，也无需指令。
+
+- **`Foo.client.vue`** —— 只在客户端渲染。SSR 输出 `<!--client-only-->` 注释占位符，真实组件在 mount 后替换它。适用于需要浏览器 API 的组件。
+- **`Foo.server.vue`** —— 只在服务端渲染。客户端构建把该导入换成 stub，因此实现与其依赖都不会进入客户端产物。适用于服务端专属访问（环境变量、数据库）。
+- **`Foo.server.vue` + `Foo.client.vue` 成对存在** —— 导入基础名（`import Foo from './Foo.vue'`）；该文件必须**不存在**。SSR 渲染服务端半边，客户端半边在 mount 后接管。
+
+### 约束
+
+**`.server.vue` 必须是 `<template>` 形式的 SFC。** 服务端会把模板包进 `<ubean-server-only v-once>` 以便水合匹配；render 函数式 SFC（或 `export { default } from …`）没有可包裹的模板，构建会以该原因失败。
+
+**`.server.vue` 会占据一个包裹元素，因此上下文很重要。** 客户端在树中保留一个 stub，水合通过匹配该元素来保留服务端渲染的子节点。该包裹元素是普通的流式元素，所以服务端组件只能用在允许流式元素的位置：
+
+```html
+<!-- 会出错：包裹元素在 <tr> 中不合法，解析器会把它提到 table 之外 -->
+<table>
+  <tr>
+    <ServerGreeting />
+  </tr>
+</table>
+
+<!-- 正确：由服务端组件自己渲染容器 -->
+<ServerTable />
+```
+
+**插件在转换阶段就会拒绝这种写法**（dev overlay / `vite build` 报错），并指出父元素与组件名。这个失败是刻意的：它要防止的症状在生产环境是**静默**的 —— 水合前内容出现在容器**之外**，之后 Vue 报 `Hydration node mismatch` / `Hydration children mismatch` 并把内容移除。
+
+检查覆盖表格祖先（`table`、`thead`、`tbody`、`tfoot`、`tr`、`colgroup`）以及 `select` / `optgroup`。它刻意**不**覆盖 `ul` / `ol` / `dl`：在那里包裹元素不会被移动，两侧 DOM 一致，水合正常。
+
+解法：让服务端组件自己渲染容器（整个 `<table>` / `<ul>`），或把它放进允许的子元素（`<td>`、`<li>`）。`.client.vue` 没有此约束 —— 注释节点在任何上下文都合法。
+
+## Islands 注册表
+
+`virtual:ubean-islands-registry` 由插件从每个使用了 `v-client.*` 指令的文件的 `<script setup>` 导入生成：
+
+```ts
+declare module 'virtual:ubean-islands-registry' {
+  export const islands: Record<string, Component | (() => Promise<Component>)>;
+}
+```
+
+- key 是**模板标签名**；value 是惰性 loader，因此岛屿组件永远不会进入入口 chunk。
+- 未扫描到任何内容时该模块导出 `{}`。
+- `ISLANDS_REGISTRY_VIRTUAL_ID`（来自 `/vite`）是虚拟模块 id；`/virtual-registration` 子路径是**纯类型**（`"import": null`）—— 它的存在只为让编辑器在不引入插件的情况下解析该模块类型。
+- 仅通过全局注册、`defineAsyncComponent` 或动态导入触达的组件无法自动注册；请通过 `hydrateIslands({ components })` 手动传入（手动项优先）。
+- 只有真正与 `v-client.*` 指令一起使用的组件才会进入客户端产物。
+
+端到端流程：**扫描** `.vue` 文件 → 把岛屿标签**转换**为 `<ubean-island v-once>`（props 序列化进 data 属性）→ **解析**导入路径 → **生成**注册表虚拟模块 → 在 `@ubean/client` 中通过 `hydrateIslands` **桥接** → mount 之后（双重 `requestAnimationFrame`）以及每次 SPA 导航后**自动水合**。
+
+## 服务端组件端点
+
+`createServerComponentMiddleware()` 处理 `POST /__server-component` —— 客户端岛屿包装器需要最新服务端 HTML 时请求的端点：
+
+```ts
+import { SERVER_COMPONENT_ENDPOINT, createServerComponentMiddleware } from '@ubean/islands/server';
+
+SERVER_COMPONENT_ENDPOINT; // '/__server-component'
+app.use('*', createServerComponentMiddleware());
+```
+
+- 请求体：`{ "path": "/abs/path/Foo.server.vue", "props": { … } }`。
+- 响应：`200` HTML / `400` 缺少 path / `404` 组件未注册 / `500` 渲染失败；每个响应都带 `Cache-Control: no-store`。
+- `registerServerComponent(path, component)` / `getServerComponent(path)` 是 SSR 渲染器与中间件共用的注册表读写口。
+- 注册表刻意挂在 **`globalThis`** 上：dev 下 SSR 图会把本包 runtime 内联，而 `@ubean/app` 通过 Node 解析 `@ubean/islands/server`，模块级 `Map` 会让两个实例拿到不同的注册表 —— 中间件会对已注册的组件返回 404（守卫见 `packages/islands/test/server-component-registry-singleton.test.ts`）。
+- `isServerComponentRequest(c)` / `isServerComponentResponse(response)` 与 `SERVER_COMPONENT_RESPONSE_HEADER`（`x-ubean-server-component`）让请求日志或代理层能识别这些调用。
+
+## Vite 插件 API
+
+```ts
+import { ubeanIslandsPlugin } from '@ubean/islands/vite';
+
+export default {
+  plugins: [ubeanIslandsPlugin({ enabled: true })]
+};
+```
+
+`UbeanIslandsPluginOptions = { enabled?: boolean }`。该子路径还暴露转换的构建块供高级集成使用：`isServerComponentFile`、`isClientComponentFile`、`hasServerComponentTemplate`、`wrapServerComponentTemplate`、`findRestrictedServerComponentUsage`、`injectServerComponentPath`、`transformVueSfcIslands`、`collectIslandComponents`、`generateRegistryModule`、`parseScriptImports`、`resolveIslandImportPath`、`scanIslandDirectiveNames`，以及虚拟 id `ISLANDS_REGISTRY_VIRTUAL_ID`、`SERVER_COMPONENT_STUB_VIRTUAL_ID`、`CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID`。
+
+插件刻意**不**从主入口 re-export —— 它会拉入 `node:fs` / `node:path`，绝不能进入浏览器产物。
+
+## SSR 助手
+
+```ts
+import { createIslandsContext, registerIsland, getIslandsScript, renderIslandPlaceholder } from '@ubean/islands';
+
+const ctx = createIslandsContext();
+const id = registerIsland(ctx, 'Counter', 'client:load', { initial: 10 });
+const html = renderIslandPlaceholder({ component: 'Counter', directive: 'client:load', props: { initial: 10 } });
+const script = getIslandsScript([...ctx.islands.values()]);
+```
+
+- `getIslandsBootstrapScript()` 产出按策略标记待水合岛屿的 IIFE；`getIslandsClearScript()` 是它的对应物。
+- `hydrationStrategyMeta` 把每条指令映射到其策略元数据。
+- 这些面向自定义 SSR 管线；框架自带渲染器已经调用过它们。
+
+## 类型安全
+
+- `ClientStrategy` / `ClientDirective` / `ClientDirectiveBinding` / `VClientDirective` 描述指令；`IslandStrategy` / `IslandOptions` / `ServerIslandOptions` 描述包装器。
+- `IslandRecord` / `IslandHydrateOptions` / `HydrateIslandsOptions` / `IslandHydrationScheduler` 描述水合运行时；`IslandsContext` / `IslandDefinition` / `IslandSsrOptions` 描述 SSR 助手。
+- `declare module 'virtual:ubean-islands-registry'` 随包发布，虚拟模块无需额外配置即可获得类型。
+
+## 架构说明
+
+- **两层，一件事**：`v-client.*` 指令是编写面；注册表加水合运行时是机制。正常应用里你永远不会手写 `hydrateIslands()`。
+- **主入口浏览器安全**：`dist/index.js` 只导入 `./directive` 与 `./runtime`。Vite 插件（`/vite`）与 Hono 中间件（`/server`）是独立子路径。
+- **注册表挂在 `globalThis`**：因为 dev 会加载两份模块实例（见上文）；模块作用域的 `Map` 会静默把注册表一分为二。
+- **转换对 HTML 解析刻意克制**：只拒绝解析器确实会移动或丢弃包裹元素的父级；`ul` / `ol` / `dl` 被放过以避免误报。
+- **转换是渐进增强的**：插件在构建期报错，而不是让水合在生产环境静默移除内容。
+- **归属**：`@ubean/build` 接线插件；`@ubean/client` 拥有自动水合调用；`@ubean/islands` 拥有机制。

package/dist/runtime.d.ts

@@ -354,4 +354,5 @@ export declare function defineClientComponent(component: Component): Component;
  * ```
  */
 export declare function definePairedComponent(ServerComp: Component, ClientComp: Component): Component;
-//#endregion
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/islands",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Islands architecture for ubean (Vite plugin for client:load/idle/visible/media/only directives, bootstrap script, client hydrate runtime)",
   "files": [
     "dist"
@@ -36,19 +36,19 @@
     }
   },
   "dependencies": {
-    "@ubean/shared": "0.6.2",
+    "@ubean/shared": "0.6.4",
     "hono": "4.13.13",
     "pathe": "^2.0.3",
-    "vue": "^3.5.43"
+    "vue": "^3.5.44"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
     "typescript": "npm:typescript-native-bridge@latest",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vite-plus": "1.1.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0"
   },
   "peerDependencies": {
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0"
   },
   "peerDependenciesMeta": {
     "vite": {