@ubean/islands 0.1.12 → 0.2.0

package/dist/directive.d.ts

@@ -0,0 +1,149 @@
+import { DirectiveBinding, ObjectDirective } from "vue";
+//#region src/directive.d.ts
+/**
+ * The five hydration strategies supported by the Islands directive.
+ *
+ * - `load`:    Hydrate immediately on page load (default).
+ * - `idle`:    Hydrate when the browser is idle (`requestIdleCallback`).
+ * - `visible`: Hydrate when the element scrolls into viewport (`IntersectionObserver`).
+ * - `media`:   Hydrate when a CSS media query matches (`matchMedia`).
+ * - `only`:    Skip SSR entirely — render placeholder during SSR, hydrate on client.
+ */
+type ClientStrategy = 'load' | 'idle' | 'visible' | 'media' | 'only';
+/**
+ * Modifiers for the `v-client` directive.
+ *
+ * Exactly one modifier should be active. If multiple are present, the first
+ * matching strategy in priority order (load → idle → visible → media → only)
+ * is used.
+ */
+interface ClientDirectiveModifiers {
+  /** Hydrate immediately on page load. */
+  load?: boolean;
+  /** Hydrate when the browser is idle. */
+  idle?: boolean;
+  /** Hydrate when the element enters the viewport. */
+  visible?: boolean;
+  /** Hydrate when the media query (passed as directive value) matches. */
+  media?: boolean;
+  /** Skip SSR, render only on the client. */
+  only?: boolean;
+}
+/**
+ * The value passed to `v-client.media` — a CSS media query string.
+ *
+ * For other strategies, the value is `undefined` (not passed).
+ *
+ * @example
+ * ```vue
+ * <Comp v-client.media="'(max-width: 768px)'" />
+ * <Comp v-client.media="isMobile ? '(max-width: 768px)' : '(min-width: 769px)'" />
+ * ```
+ */
+type ClientDirectiveValue = string | undefined;
+/**
+ * The full directive binding for `v-client`.
+ *
+ * Provides type-safe access to modifiers and value in directive hooks.
+ * Modifiers are cast to `ClientDirectiveModifiers` at runtime since Vue's
+ * `DirectiveBinding` types them as `Record<string, boolean>`.
+ */
+type ClientDirectiveBinding = DirectiveBinding<ClientDirectiveValue>;
+/**
+ * The `v-client` directive type.
+ *
+ * Use this for type-safe registration on a Vue app:
+ * ```typescript
+ * app.directive('client', vClient);
+ * ```
+ */
+type VClientDirective = ObjectDirective<HTMLElement, ClientDirectiveValue, ClientStrategy>;
+/**
+ * Resolve the hydration strategy from directive modifiers.
+ *
+ * Priority: load → idle → visible → media → only.
+ * If no modifier is present, defaults to `'load'`.
+ */
+declare function resolveClientStrategy(modifiers: ClientDirectiveModifiers): ClientStrategy;
+/**
+ * Map a `ClientStrategy` to the legacy `ClientDirective` string.
+ *
+ * Used internally by the Vite plugin to maintain backward compatibility
+ * with the `<ubean-island data-directive="client:load">` format.
+ */
+declare function strategyToLegacyDirective(strategy: ClientStrategy): string;
+/**
+ * Parse a directive string (legacy `client:xxx` or new `v-client.xxx`) into
+ * a `ClientStrategy`.
+ *
+ * @internal Used by the Vite plugin to unify old and new syntax.
+ */
+declare function legacyDirectiveToStrategy(directive: string): ClientStrategy | null;
+/** Data attribute used to mark elements for the Islands hydration system. */
+declare const CLIENT_DIRECTIVE_ATTR = "data-client-directive";
+/** Data attribute for the media query (used with `v-client.media`). */
+declare const CLIENT_MEDIA_ATTR = "data-media";
+/** Data attribute marking a client-only element (skip SSR). */
+declare const CLIENT_ONLY_ATTR = "data-client-only";
+/**
+ * The `v-client` Vue custom directive.
+ *
+ * Registers on the Vue app via `app.directive('client', vClient)`.
+ *
+ * In SSR/Islands mode: the Vite plugin transforms `v-client.*` before the
+ * directive runs, so this code only executes in CSR-only scenarios.
+ *
+ * In CSR-only mode: the directive marks the element with data attributes
+ * so `hydrateIslands()` can discover it, and directly applies the hydration
+ * strategy (idle/visible/media) for immediate effect.
+ */
+declare const vClient: VClientDirective;
+/**
+ * Apply a hydration deferral strategy directly to a DOM element.
+ *
+ * Used by the runtime directive (CSR mode) and exported for advanced use
+ * cases (e.g. custom wrapper components).
+ *
+ * - `load`: No deferral (element is already mounted).
+ * - `idle`: Defers visibility until `requestIdleCallback`.
+ * - `visible`: Defers visibility until `IntersectionObserver` fires.
+ * - `media`: Defers visibility until `matchMedia` matches.
+ * - `only`: No deferral (element is already on client).
+ */
+declare function applyStrategy(el: HTMLElement, strategy: ClientStrategy, mediaQuery?: string): void;
+/**
+ * Clean up all strategy resources for an element.
+ *
+ * Exported for wrapper components that manage elements manually.
+ */
+declare function cleanupStrategy(el: HTMLElement): void;
+/**
+ * Augment Vue's type system to recognize `v-client` in templates.
+ *
+ * This provides IDE autocompletion and type checking for:
+ * - `v-client.load` / `v-client.idle` / `v-client.visible` /
+ *   `v-client.media` / `v-client.only`
+ * - The directive value (string for media query)
+ *
+ * @internal This is automatically applied when the module is imported.
+ */
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    /**
+     * `v-client` directive — Islands hydration strategy.
+     *
+     * Modifiers: `.load`, `.idle`, `.visible`, `.media`, `.only`
+     * Value: `string` (media query, only for `.media`)
+     */
+    vClient: VClientDirective;
+  }
+  interface ComponentCustomOptions {
+    /**
+     * Register the `v-client` directive on this component's app.
+     * (Framework-level — users don't need to set this manually.)
+     */
+    clientDirective?: boolean;
+  }
+}
+//#endregion
+export { CLIENT_DIRECTIVE_ATTR, CLIENT_MEDIA_ATTR, CLIENT_ONLY_ATTR, ClientDirectiveBinding, ClientDirectiveModifiers, ClientDirectiveValue, ClientStrategy, VClientDirective, applyStrategy, cleanupStrategy, legacyDirectiveToStrategy, resolveClientStrategy, strategyToLegacyDirective, vClient };

package/dist/directive.js

@@ -0,0 +1,158 @@
+//#region src/directive.ts
+/**
+* Resolve the hydration strategy from directive modifiers.
+*
+* Priority: load → idle → visible → media → only.
+* If no modifier is present, defaults to `'load'`.
+*/
+function resolveClientStrategy(modifiers) {
+	if (modifiers.load) return "load";
+	if (modifiers.idle) return "idle";
+	if (modifiers.visible) return "visible";
+	if (modifiers.media) return "media";
+	if (modifiers.only) return "only";
+	return "load";
+}
+/**
+* Map a `ClientStrategy` to the legacy `ClientDirective` string.
+*
+* Used internally by the Vite plugin to maintain backward compatibility
+* with the `<ubean-island data-directive="client:load">` format.
+*/
+function strategyToLegacyDirective(strategy) {
+	return `client:${strategy}`;
+}
+/**
+* Parse a directive string (legacy `client:xxx` or new `v-client.xxx`) into
+* a `ClientStrategy`.
+*
+* @internal Used by the Vite plugin to unify old and new syntax.
+*/
+function legacyDirectiveToStrategy(directive) {
+	const match = directive.match(/^(?:client:|v-client\.)(load|idle|visible|media|only)$/);
+	return match ? match[1] : null;
+}
+/** Data attribute used to mark elements for the Islands hydration system. */
+const CLIENT_DIRECTIVE_ATTR = "data-client-directive";
+/** Data attribute for the media query (used with `v-client.media`). */
+const CLIENT_MEDIA_ATTR = "data-media";
+/** Data attribute marking a client-only element (skip SSR). */
+const CLIENT_ONLY_ATTR = "data-client-only";
+/** WeakMap for storing cleanup functions per element. */
+const cleanupMap = /* @__PURE__ */ new WeakMap();
+/**
+* The `v-client` Vue custom directive.
+*
+* Registers on the Vue app via `app.directive('client', vClient)`.
+*
+* In SSR/Islands mode: the Vite plugin transforms `v-client.*` before the
+* directive runs, so this code only executes in CSR-only scenarios.
+*
+* In CSR-only mode: the directive marks the element with data attributes
+* so `hydrateIslands()` can discover it, and directly applies the hydration
+* strategy (idle/visible/media) for immediate effect.
+*/
+const vClient = {
+	mounted(el, binding) {
+		const modifiers = binding.modifiers;
+		const strategy = resolveClientStrategy(modifiers);
+		const mediaQuery = typeof binding.value === "string" ? binding.value : void 0;
+		el.setAttribute(CLIENT_DIRECTIVE_ATTR, strategy);
+		if (strategy === "media" && mediaQuery) el.setAttribute(CLIENT_MEDIA_ATTR, mediaQuery);
+		if (strategy === "only") el.setAttribute(CLIENT_ONLY_ATTR, "true");
+		applyStrategy(el, strategy, mediaQuery);
+	},
+	unmounted(el) {
+		const cleanups = cleanupMap.get(el);
+		if (cleanups) {
+			for (const cleanup of cleanups) cleanup();
+			cleanupMap.delete(el);
+		}
+		el.removeAttribute(CLIENT_DIRECTIVE_ATTR);
+		el.removeAttribute(CLIENT_MEDIA_ATTR);
+		el.removeAttribute(CLIENT_ONLY_ATTR);
+	}
+};
+/**
+* Apply a hydration deferral strategy directly to a DOM element.
+*
+* Used by the runtime directive (CSR mode) and exported for advanced use
+* cases (e.g. custom wrapper components).
+*
+* - `load`: No deferral (element is already mounted).
+* - `idle`: Defers visibility until `requestIdleCallback`.
+* - `visible`: Defers visibility until `IntersectionObserver` fires.
+* - `media`: Defers visibility until `matchMedia` matches.
+* - `only`: No deferral (element is already on client).
+*/
+function applyStrategy(el, strategy, mediaQuery) {
+	if (strategy === "load" || strategy === "only") return;
+	const cleanups = [];
+	if (strategy === "idle") {
+		const ric = globalThis.requestIdleCallback;
+		if (typeof ric === "function") {
+			const id = ric(() => {
+				el.removeAttribute("data-client-pending");
+			}, { timeout: 2e3 });
+			cleanups.push(() => {
+				const cancel = globalThis.cancelIdleCallback;
+				if (typeof cancel === "function") cancel(id);
+			});
+		} else {
+			const id = setTimeout(() => {
+				el.removeAttribute("data-client-pending");
+			}, 200);
+			cleanups.push(() => clearTimeout(id));
+		}
+		el.setAttribute("data-client-pending", "idle");
+	} else if (strategy === "visible") {
+		const IOCtor = globalThis.IntersectionObserver;
+		if (typeof IOCtor === "function") {
+			const io = new IOCtor((entries) => {
+				for (const entry of entries) if (entry.isIntersecting) {
+					io.disconnect();
+					el.removeAttribute("data-client-pending");
+				}
+			}, { rootMargin: "200px" });
+			io.observe(el);
+			cleanups.push(() => io.disconnect());
+		}
+		el.setAttribute("data-client-pending", "visible");
+	} else if (strategy === "media" && mediaQuery) {
+		const mql = globalThis.window?.matchMedia?.(mediaQuery);
+		if (mql) {
+			if (mql.matches) {} else {
+				const fn = (e) => {
+					if (e.matches) {
+						el.removeAttribute("data-client-pending");
+						if (mql.removeEventListener) mql.removeEventListener("change", fn);
+						else if (mql.removeListener) mql.removeListener(fn);
+					}
+				};
+				if (mql.addEventListener) mql.addEventListener("change", fn);
+				else if (mql.addListener) mql.addListener(fn);
+				cleanups.push(() => {
+					if (mql.removeEventListener) mql.removeEventListener("change", fn);
+					else if (mql.removeListener) mql.removeListener(fn);
+				});
+				el.setAttribute("data-client-pending", "media");
+			}
+		}
+	}
+	if (cleanups.length > 0) cleanupMap.set(el, cleanups);
+}
+/**
+* Clean up all strategy resources for an element.
+*
+* Exported for wrapper components that manage elements manually.
+*/
+function cleanupStrategy(el) {
+	const cleanups = cleanupMap.get(el);
+	if (cleanups) {
+		for (const cleanup of cleanups) cleanup();
+		cleanupMap.delete(el);
+	}
+	el.removeAttribute("data-client-pending");
+}
+//#endregion
+export { CLIENT_DIRECTIVE_ATTR, CLIENT_MEDIA_ATTR, CLIENT_ONLY_ATTR, applyStrategy, cleanupStrategy, legacyDirectiveToStrategy, resolveClientStrategy, strategyToLegacyDirective, vClient };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ISLANDS_REGISTRY_VIRTUAL_ID, IslandComponentEntry, IslandComponentMap, UbeanIslandsPluginOptions, collectIslandComponents, generateRegistryModule, parseScriptImports, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin } from "./vite.js";
+import { CLIENT_DIRECTIVE_ATTR, CLIENT_MEDIA_ATTR, CLIENT_ONLY_ATTR, ClientDirectiveBinding, ClientDirectiveModifiers, ClientDirectiveValue, ClientStrategy, VClientDirective, applyStrategy, cleanupStrategy, legacyDirectiveToStrategy, resolveClientStrategy, strategyToLegacyDirective, vClient } from "./directive.js";
+import { ClientComponentPlaceholder, IslandOptions, IslandStrategy, SERVER_COMPONENT_ENDPOINT, ServerComponentStub, ServerIslandOptions, defineClientComponent, defineIsland, definePairedComponent, defineServerIsland, getServerComponent, registerServerComponent } from "./runtime.js";
 //#region src/types.d.ts
 type ClientDirective = 'client:load' | 'client:idle' | 'client:visible' | 'client:media' | 'client:only';
 interface IslandDefinition {
@@ -37,4 +38,4 @@ declare const hydrationStrategyMeta: Record<ClientDirective, {
 declare function getIslandsBootstrapScript(): string;
 declare function getIslandsClearScript(): string;
 //#endregion
-export { type ClientDirective, type ClientHydrationStrategy, ISLANDS_REGISTRY_VIRTUAL_ID, type IslandComponentEntry, type IslandComponentMap, type IslandDefinition, type IslandSsrOptions, type IslandsContext, type UbeanIslandsPluginOptions, collectIslandComponents, createIslandsContext, generateIslandPlaceholder, generateRegistryModule, getIslandsBootstrapScript, getIslandsClearScript, getIslandsScript, hydrationStrategyMeta, parseScriptImports, registerIsland, renderIslandPlaceholder, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin };
+export { CLIENT_DIRECTIVE_ATTR, CLIENT_MEDIA_ATTR, CLIENT_ONLY_ATTR, ClientComponentPlaceholder, type ClientDirective, type ClientDirectiveBinding, type ClientDirectiveModifiers, type ClientDirectiveValue, type ClientHydrationStrategy, type ClientStrategy, type IslandDefinition, type IslandOptions, type IslandSsrOptions, type IslandStrategy, type IslandsContext, SERVER_COMPONENT_ENDPOINT, ServerComponentStub, type ServerIslandOptions, type VClientDirective, applyStrategy, cleanupStrategy, createIslandsContext, defineClientComponent, defineIsland, definePairedComponent, defineServerIsland, generateIslandPlaceholder, getIslandsBootstrapScript, getIslandsClearScript, getIslandsScript, getServerComponent, hydrationStrategyMeta, legacyDirectiveToStrategy, registerIsland, registerServerComponent, renderIslandPlaceholder, resolveClientStrategy, strategyToLegacyDirective, vClient };

package/dist/index.js

@@ -1,4 +1,5 @@
-import { ISLANDS_REGISTRY_VIRTUAL_ID, collectIslandComponents, generateRegistryModule, parseScriptImports, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin } from "./vite.js";
+import { CLIENT_DIRECTIVE_ATTR, CLIENT_MEDIA_ATTR, CLIENT_ONLY_ATTR, applyStrategy, cleanupStrategy, legacyDirectiveToStrategy, resolveClientStrategy, strategyToLegacyDirective, vClient } from "./directive.js";
+import { ClientComponentPlaceholder, SERVER_COMPONENT_ENDPOINT, ServerComponentStub, defineClientComponent, defineIsland, definePairedComponent, defineServerIsland, getServerComponent, registerServerComponent } from "./runtime.js";
 //#region src/types.ts
 function createIslandsContext() {
 	return {
@@ -65,4 +66,4 @@ function getIslandsClearScript() {
 	return `(function(){function clearIslands(){var islands=document.querySelectorAll('ubean-island[data-island-id]');islands.forEach(function(el){if(el.getAttribute('data-directive')!=='client:only'){return}el.innerHTML='';el.setAttribute('data-cleared','true')})}if(document.readyState==='loading'){document.addEventListener('DOMContentLoaded',clearIslands)}else{clearIslands()}})();`;
 }
 //#endregion
-export { ISLANDS_REGISTRY_VIRTUAL_ID, collectIslandComponents, createIslandsContext, generateIslandPlaceholder, generateRegistryModule, getIslandsBootstrapScript, getIslandsClearScript, getIslandsScript, hydrationStrategyMeta, parseScriptImports, registerIsland, renderIslandPlaceholder, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin };
+export { CLIENT_DIRECTIVE_ATTR, CLIENT_MEDIA_ATTR, CLIENT_ONLY_ATTR, ClientComponentPlaceholder, SERVER_COMPONENT_ENDPOINT, ServerComponentStub, applyStrategy, cleanupStrategy, createIslandsContext, defineClientComponent, defineIsland, definePairedComponent, defineServerIsland, generateIslandPlaceholder, getIslandsBootstrapScript, getIslandsClearScript, getIslandsScript, getServerComponent, hydrationStrategyMeta, legacyDirectiveToStrategy, registerIsland, registerServerComponent, renderIslandPlaceholder, resolveClientStrategy, strategyToLegacyDirective, vClient };

package/dist/runtime.d.ts

@@ -4,6 +4,7 @@ interface DomElement {
   getAttribute(name: string): string | null;
   setAttribute(name: string, value: string): void;
   hasAttribute(name: string): boolean;
+  innerHTML: string;
 }
 interface NodeListOf<T> {
   forEach(callback: (value: T, key: number, parent: NodeListOf<T>) => void): void;
@@ -31,5 +32,307 @@ interface HydrateIslandsOptions extends IslandHydrateOptions {
   components?: Record<string, Component | (() => Promise<Component>)>;
 }
 declare function hydrateIslands(options?: HydrateIslandsOptions): void;
+/**
+ * `POST /__server-component` 端点 — 接收 `{ path, props }`,在服务端用注册表中的
+ * 组件重新渲染并返回 HTML 片段。由 `createServerComponentMiddleware()` 处理。
+ */
+declare const SERVER_COMPONENT_ENDPOINT = "/__server-component";
+/**
+ * 注册服务端组件到全局注册表 (SSR 构建中由 `defineServerIsland` 自动调用)。
+ */
+declare function registerServerComponent(path: string, component: Component): void;
+/**
+ * 从全局注册表取出服务端组件 (由 `createServerComponentMiddleware` 调用)。
+ * 未注册时返回 `undefined`。
+ */
+declare function getServerComponent(path: string): Component | undefined;
+/** 清空注册表 (仅用于测试)。 */
+declare function _clearServerComponentRegistry(): void;
+/**
+ * `defineServerIsland` 的选项。
+ */
+interface ServerIslandOptions {
+  /**
+   * Suspense fallback 内容。
+   *
+   * - 字符串:作为静态文本渲染(适合简单 loading 提示)
+   * - Vue 组件:作为 fallback slot 渲染(可包含动态内容)
+   * - 未提供:渲染空 `<ubean-defer-fallback>` 占位元素(与 PPR 静态壳默认行为一致)
+   *
+   * 在 PPR 模式下,预渲染(SSG)阶段仅渲染 fallback(生成静态壳);
+   * 流式 SSR 阶段 fallback 先输出,异步组件解析后通过 Suspense 边界流式输出。
+   */
+  fallback?: Component | string;
+  /**
+   * Task 9.4: 是否在 props 变化时重新请求服务端组件 HTML 并替换 DOM。
+   *
+   * - `false` (默认): 仅 SSR 渲染一次,客户端水合后不再请求服务端。
+   * - `true`: 客户端 `onMounted` 后立即请求一次,并 `watch` props 变化重新请求,
+   *   用返回的 HTML 替换容器 `innerHTML`。SSR 端会将组件注册到全局注册表供中间件查找。
+   *
+   * 需配合 Vite 插件自动注入的第 3 参数 (组件绝对路径) 使用。当 `true` 但未提供
+   * 路径时 (例如手动调用未走 Vite 插件),退化为 `false` 行为。
+   */
+  rerenderOnPropsChange?: boolean;
+}
+/**
+ * 定义服务端 island — 将异步组件包裹在 `<Suspense>` 边界中,实现 Partial
+ * Prerendering / Server Islands 模式。
+ *
+ * 替代旧版 `server:defer` 编译时指令。对齐 Next.js 16 PPR / Astro 5
+ * `server:defer` 语义。
+ *
+ * ## 工作机制
+ *
+ * - **预渲染(SSG)阶段**:仅渲染 fallback(生成静态壳)
+ * - **流式 SSR 阶段**:fallback 先输出,异步组件解析后通过 Suspense 边界流式输出
+ * - **客户端**:Suspense 边界保持,异步组件解析后自动替换 fallback
+ *
+ * 传入的 `Component` 必须是异步的(`async setup()` 或 `defineAsyncComponent`)
+ * 才能触发 Suspense 流式行为;同步组件会立即解析,Suspense 退化为透明包装。
+ *
+ * ## Task 9.4: Props 重渲染
+ *
+ * 当 `options.rerenderOnPropsChange: true` 且 Vite 插件注入了组件路径 (第 3 参数):
+ *
+ * - **SSR**: `defineServerIsland` 将组件注册到全局注册表 (`registerServerComponent`),
+ *   供 `POST /__server-component` 中间件查找。SSR 渲染输出与不带此选项时一致。
+ * - **客户端**: 包装组件外层渲染 `<ubean-server-island>` 容器 (带 ref),内部仍是
+ *   `<Suspense><Component /></Suspense>` (client 构建中 `Component` 是 stub)。
+ *   `onMounted` 后立即 `POST {path, props}` 到 `/__server-component`,用返回的 HTML
+ *   替换容器 `innerHTML`;`watch(attrs)` 在 props 变化时重复此流程。
+ *
+ * ## Props/Slots 透传
+ *
+ * 包装组件设置 `inheritAttrs: false`,将所有 attrs(含 props)和 slots
+ * 透传给内部 `Component`,使用方式与直接渲染 `Component` 一致:
+ *
+ * ```vue
+ * <DashboardIsland :userId="123" #header="slotProps">...</DashboardIsland>
+ * ```
+ *
+ * 等价于:
+ *
+ * ```vue
+ * <Suspense>
+ *   <template #fallback><!-- fallback 内容 --></template>
+ *   <Dashboard :userId="123" #header="slotProps">...</Dashboard>
+ * </Suspense>
+ * ```
+ *
+ * ## 用法示例
+ *
+ * ```ts
+ * import { defineServerIsland, h } from 'ubean';
+ * import Dashboard from './Dashboard.vue';
+ *
+ * // 1. 字符串 fallback
+ * const DashboardIsland = defineServerIsland(Dashboard, {
+ *   fallback: 'Loading dashboard...'
+ * });
+ *
+ * // 2. 组件 fallback
+ * const DashboardIsland = defineServerIsland(Dashboard, {
+ *   fallback: () => h('div', { class: 'spinner' }, 'Loading...')
+ * });
+ *
+ * // 3. 默认占位(fallback 未提供时渲染 <ubean-defer-fallback/>)
+ * const DashboardIsland = defineServerIsland(Dashboard);
+ *
+ * // 4. Task 9.4: props 变化时重渲染 (Vite 插件会自动注入第 3 参数)
+ * const DashboardIsland = defineServerIsland(Dashboard, {
+ *   rerenderOnPropsChange: true
+ * });
+ * ```
+ *
+ * 在 SFC 中使用包装后的组件:
+ *
+ * ```vue
+ * <script setup>
+ * import { defineServerIsland } from 'ubean';
+ * import Dashboard from './Dashboard.vue';
+ * const DashboardIsland = defineServerIsland(Dashboard, {
+ *   fallback: 'Loading...'
+ * });
+ * </script>
+ *
+ * <template>
+ *   <DashboardIsland :userId="123" />
+ * </template>
+ * ```
+ *
+ * @param Component 服务端组件 (通常是 `.server.vue` 导入)
+ * @param options 选项
+ * @param __serverComponentPath 组件绝对路径 (由 Vite 插件自动注入,勿手动传)
+ */
+declare function defineServerIsland(Component: Component, options?: ServerIslandOptions, __serverComponentPath?: string): Component;
+/**
+ * 客户端 island 水合策略(与 `v-client.*` 的 modifier 一一对应)。
+ */
+type IslandStrategy = 'load' | 'idle' | 'visible' | 'media' | 'only';
+/**
+ * `defineIsland` 的选项。
+ */
+interface IslandOptions {
+  /**
+   * 媒体查询字符串(仅 `strategy: 'media'` 时使用)。
+   *
+   * 与 `v-client.media="'(max-width: 768px)'"` 中的字符串值等价。
+   */
+  mediaQuery?: string;
+  /**
+   * 静态 props,在 SSR 阶段序列化到 `<ubean-island data-props="...">`。
+   *
+   * 未提供时,所有 attrs 都会作为 props 透传给内部组件。
+   * (与 `v-client.*` 在模板上接收 attrs 的行为一致。)
+   */
+  props?: Record<string, unknown>;
+}
+/**
+ * 定义客户端 island — 将组件包装为延迟水合的 island。
+ *
+ * 这是 `v-client.*` Vue 指令的运行时替代方案,适用于编程式场景
+ * (如动态构造 island、在 `.ts` 文件中定义 island、或需要参数化的场景)。
+ *
+ * **注意**:模板中的 `v-client.*` 指令语法仍然有效,由 Vite 插件
+ * (`ubean:islands`)在编译时转换为 `<ubean-island>` 占位元素;
+ * `defineIsland` 仅为运行时编程式使用提供,不会替代 Vite 插件的转换逻辑。
+ *
+ * ## 工作机制
+ *
+ * - **SSR 阶段**:渲染 `<ubean-island>` 占位元素,包含 `data-island-id`、
+ *   `data-component`、`data-directive`、`data-props`、`data-media` 属性
+ *   (与 `v-client.*` 转换后的输出格式完全一致)。
+ * - **客户端**:由 `hydrateIslands()` 根据 `data-directive` 选择水合策略
+ *   (load/idle/visible/media/only),在合适时机挂载组件。
+ *
+ * ## 用法示例
+ *
+ * ```ts
+ * import { defineIsland } from 'ubean';
+ * import Counter from './Counter.vue';
+ *
+ * // 1. 立即水合(等价于 v-client.load)
+ * const CounterIsland = defineIsland(Counter, 'load');
+ *
+ * // 2. 空闲时水合(等价于 v-client.idle)
+ * const HeavyChartIsland = defineIsland(HeavyChart, 'idle');
+ *
+ * // 3. 进入视口时水合(等价于 v-client.visible)
+ * const LazyMapIsland = defineIsland(LazyMap, 'visible');
+ *
+ * // 4. 媒体查询匹配时水合(等价于 v-client.media)
+ * const MobileNavIsland = defineIsland(MobileNav, 'media', {
+ *   mediaQuery: '(max-width: 768px)'
+ * });
+ *
+ * // 5. 仅客户端渲染(等价于 v-client.only)
+ * const ClientOnlyWidgetIsland = defineIsland(ClientOnlyWidget, 'only');
+ * ```
+ *
+ * 在 SFC 中使用包装后的组件:
+ *
+ * ```vue
+ * <script setup>
+ * import { defineIsland } from 'ubean';
+ * import Counter from './Counter.vue';
+ * const CounterIsland = defineIsland(Counter, 'load');
+ * </script>
+ *
+ * <template>
+ *   <CounterIsland :count="5" />
+ * </template>
+ * ```
+ */
+declare function defineIsland(Component: Component, strategy: IslandStrategy, options?: IslandOptions): Component;
+/**
+ * `.server.vue` 组件在客户端 bundle 中的占位 stub (Task 9.1)。
+ *
+ * Vite 插件在 client 构建中将 `.server.vue` 的 import 重定向到虚拟 stub 模块,
+ * 该模块导出此组件。组件渲染一个空的 `<ubean-server-only>` 元素 —— SSR 已在
+ * 该元素内部渲染了完整 HTML,客户端 Vue 水合时匹配该元素但不触碰其子节点
+ * (SSR 模板通过 `v-once` 标记为静态内容),从而保留服务端渲染的 HTML 不被清除。
+ *
+ * 这保证了 `.server.vue` 组件的 JS 不会发送到客户端 —— 客户端只导入此 stub。
+ */
+declare const ServerComponentStub: import("vue").DefineComponent<{}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * `.client.vue` 组件在 SSR 构建中的通用占位符 (Task 9.2)。
+ *
+ * Vite 插件在 SSR 构建中将 `.client.vue` 的 import 重定向到虚拟模块,
+ * 该模块导出此组件。组件渲染 `<div data-client-only></div>` 占位符,
+ * 与客户端 `defineClientComponent` 初始渲染输出一致,确保水合无 mismatch。
+ *
+ * SSR 使用通用占位符(而非真实组件)避免了在服务端导入可能含浏览器 API
+ * 的 `.client.vue` 组件代码。
+ */
+declare const ClientComponentPlaceholder: import("vue").DefineComponent<{}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 定义客户端组件 —— `.client.vue` 在客户端构建中的包装器 (Task 9.2)。
+ *
+ * Vite 插件在 client 构建中为每个 `.client.vue` 生成虚拟包装模块:
+ * ```ts
+ * import RealComp from '/abs/path/Foo.client.vue';
+ * import { defineClientComponent } from '@ubean/islands/runtime';
+ * export default defineClientComponent(RealComp);
+ * ```
+ *
+ * ## 工作机制
+ *
+ * - **SSR**: 由 `ClientComponentPlaceholder` 替代,渲染 `<div data-client-only></div>`
+ * - **客户端初始渲染**: `isClient` 为 false,渲染相同的 `<div data-client-only></div>`,
+ *   与 SSR 输出匹配,水合无 mismatch
+ * - **客户端 `onMounted` 后**: `isClient` 变为 true,渲染真实组件,Vue 自动 patch 替换占位符
+ *
+ * 这种模式确保 `.client.vue` 组件只在客户端渲染,SSR 仅输出占位符,
+ * 且不依赖 islands 注册表 / `hydrateIslands()` 机制。
+ *
+ * ## 用法
+ *
+ * 通常由 Vite 插件自动生成包装模块,用户无需手动调用。如需编程式使用:
+ *
+ * ```ts
+ * import { defineClientComponent } from '@ubean/islands/runtime';
+ * import Widget from './Widget.client.vue';
+ * const WidgetClient = defineClientComponent(Widget);
+ * ```
+ */
+declare function defineClientComponent(component: Component): Component;
+/**
+ * 定义配对组件 — `Foo.vue` 同时存在 `.server.vue` + `.client.vue` 兄弟文件时,
+ * Vite 插件生成的虚拟包装模块调用此函数 (Task 9.3)。
+ *
+ * ## 工作机制
+ *
+ * - **SSR**: 配对 wrapper 模块直接 re-export `.server.vue`,根本不会调用本函数
+ *   (见 `vite.ts` `load` 钩子 SSR 分支)。SSR 渲染真实服务端组件内容。
+ * - **客户端初始渲染**: `isClient` 为 false,渲染 `ServerComp` —— 但在客户端构建中
+ *   `.server.vue` 已被重定向到 `ServerComponentStub`(渲染空的
+ *   `<ubean-server-only>` 元素),与 SSR 输出的 `<ubean-server-only v-once>真实内容
+ *   </ubean-server-only>` 标签匹配,Vue 水合时元素标签一致 (内部子节点因 `v-once`
+ *   标记为静态而被保留,虽有 mismatch 但 Vue 通常能容忍)。
+ * - **客户端 `onMounted` 后**: `isClient` 变为 true,渲染 `ClientComp` (真实客户端
+ *   组件),Vue 自动 patch 替换 stub 内容。
+ *
+ * ## 局限性
+ *
+ * SSR 渲染的 HTML 在客户端水合时不会被完美保留 —— Vue 会尝试 patch stub 的空
+ * `<ubean-server-only>` 与 SSR 输出的有内容版本,可能导致 SSR 内容被清除后再渲染
+ * 客户端组件。这是已知的折中 (与 React Server Components 的 hydration 流程类似)。
+ *
+ * 通常由 Vite 插件自动生成包装模块,用户无需手动调用。如需编程式使用:
+ *
+ * ```ts
+ * import { definePairedComponent } from '@ubean/islands/runtime';
+ * import ServerComp from './Foo.server.vue';
+ * import ClientComp from './Foo.client.vue';
+ * const Foo = definePairedComponent(ServerComp, ClientComp);
+ * ```
+ */
+declare function definePairedComponent(ServerComp: Component, ClientComp: Component): Component;
 //#endregion
-export { HydrateIslandsOptions, IslandHydrateOptions, IslandRecord, collectIslands, hydrateIsland, hydrateIslands };
+export { ClientComponentPlaceholder, HydrateIslandsOptions, IslandHydrateOptions, IslandOptions, IslandRecord, IslandStrategy, SERVER_COMPONENT_ENDPOINT, ServerComponentStub, ServerIslandOptions, _clearServerComponentRegistry, collectIslands, defineClientComponent, defineIsland, definePairedComponent, defineServerIsland, getServerComponent, hydrateIsland, hydrateIslands, registerServerComponent };