@ubean/islands 0.1.13 → 0.2.0

package/dist/runtime.js

@@ -1,4 +1,4 @@
-import { createApp, defineComponent, h } from "vue";
+import { Suspense, createApp, defineComponent, h, onMounted, ref, watch } from "vue";
 //#region src/runtime.ts
 const _global = globalThis;
 function decodeProps(raw) {
@@ -35,12 +35,13 @@ function collectIslands(root) {
 function hydrateIsland(record, component, options = {}) {
 	if (record.el.hasAttribute("data-hydrated")) return;
 	record.el.setAttribute("data-hydrated", "true");
-	const app = createApp(defineComponent({
+	const ChildComponent = defineComponent({
 		name: `Island-${record.componentName}`,
 		setup() {
 			return () => h(component, record.props);
 		}
-	}));
+	});
+	const app = createApp(ChildComponent);
 	if (options.appContext) {
 		if (options.appContext.config?.globalProperties) Object.assign(app.config.globalProperties, options.appContext.config.globalProperties);
 		const appContextInternal = options.appContext;
@@ -101,19 +102,20 @@ function hydrateIslands(options = {}) {
 			} else doHydrate();
 		} else if (directive === "client:media" && record.mediaQuery) {
 			const mql = _global.window?.matchMedia?.(record.mediaQuery);
-			if (mql) if (mql.matches) doHydrate();
-			else {
-				const fn = (e) => {
-					if (e.matches) {
-						doHydrate();
-						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);
-			}
-			else doHydrate();
+			if (mql) {
+				if (mql.matches) doHydrate();
+				else {
+					const fn = (e) => {
+						if (e.matches) {
+							doHydrate();
+							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);
+				}
+			} else doHydrate();
 		} else doHydrate();
 	}
 }
@@ -124,5 +126,382 @@ function resolveComponent(name, components, getComponent) {
 	console.warn(`[ubean:islands] Island component "${name}" not found in registry.\nPossible causes:\n  1. Component is globally registered or dynamically imported — pass it via hydrateIslands({ components: { ${name}: YourComp } })\n  2. Component name mismatch between template tag and import\n  3. Component is auto-imported by unplugin-vue-components (no static import → not in auto-registry)\nRegistered components: ${registered.length > 0 ? registered.join(", ") : "(none)"}`);
 	return null;
 }
+/**
+* `POST /__server-component` 端点 — 接收 `{ path, props }`,在服务端用注册表中的
+* 组件重新渲染并返回 HTML 片段。由 `createServerComponentMiddleware()` 处理。
+*/
+const SERVER_COMPONENT_ENDPOINT = "/__server-component";
+/**
+* 全局服务端组件注册表:组件绝对路径 → Vue 组件对象。
+*
+* SSR 构建中,`defineServerIsland(Comp, { rerenderOnPropsChange: true }, '/abs/path')`
+* 会调用 `registerServerComponent(path, Comp)` 将真实组件注册到此处。
+* 客户端构建中 `Comp` 是 stub,不会注册。
+*
+* 中间件 `createServerComponentMiddleware()` 通过 `getServerComponent(path)` 取出
+* 组件,用 `renderToString(h(Comp, props))` 重新渲染并返回 HTML。
+*/
+const serverComponentRegistry = /* @__PURE__ */ new Map();
+/**
+* 注册服务端组件到全局注册表 (SSR 构建中由 `defineServerIsland` 自动调用)。
+*/
+function registerServerComponent(path, component) {
+	serverComponentRegistry.set(path, component);
+}
+/**
+* 从全局注册表取出服务端组件 (由 `createServerComponentMiddleware` 调用)。
+* 未注册时返回 `undefined`。
+*/
+function getServerComponent(path) {
+	return serverComponentRegistry.get(path);
+}
+/** 清空注册表 (仅用于测试)。 */
+function _clearServerComponentRegistry() {
+	serverComponentRegistry.clear();
+}
+/**
+* 定义服务端 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 插件自动注入,勿手动传)
+*/
+function defineServerIsland(Component, options, __serverComponentPath) {
+	const fallback = options?.fallback;
+	const rerenderOnPropsChange = options?.rerenderOnPropsChange === true && !!__serverComponentPath;
+	if (rerenderOnPropsChange && typeof window === "undefined" && __serverComponentPath) registerServerComponent(__serverComponentPath, Component);
+	return defineComponent({
+		name: "ServerIsland",
+		inheritAttrs: false,
+		setup(_, { slots, attrs }) {
+			if (rerenderOnPropsChange) {
+				const containerRef = ref(null);
+				const fetchAndReplace = async () => {
+					const el = containerRef.value;
+					if (!el) return;
+					try {
+						const res = await _fetchServerComponent(__serverComponentPath, { ...attrs });
+						if (res.ok) el.innerHTML = await res.text();
+					} catch {}
+				};
+				onMounted(() => {
+					fetchAndReplace();
+					watch(() => ({ ...attrs }), fetchAndReplace, { deep: true });
+				});
+				return () => h("ubean-server-island", { ref: containerRef }, [h(Suspense, null, {
+					default: () => h(Component, attrs, slots),
+					fallback: typeof fallback === "string" ? () => fallback : fallback ? () => h(fallback) : () => h("ubean-defer-fallback")
+				})]);
+			}
+			return () => h(Suspense, null, {
+				default: () => h(Component, attrs, slots),
+				fallback: typeof fallback === "string" ? () => fallback : fallback ? () => h(fallback) : () => h("ubean-defer-fallback")
+			});
+		}
+	});
+}
+/**
+* 内部: POST 到 `/__server-component` 获取重新渲染的 HTML 片段。
+*
+* 抽出为独立函数便于测试时 mock。使用全局 `fetch`。
+*/
+async function _fetchServerComponent(path, props) {
+	const res = await globalThis.fetch(SERVER_COMPONENT_ENDPOINT, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			path,
+			props
+		})
+	});
+	return {
+		ok: res.ok,
+		text: () => res.text()
+	};
+}
+/**
+* 定义客户端 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>
+* ```
+*/
+function defineIsland(Component, strategy, options) {
+	const mediaQuery = options?.mediaQuery;
+	const staticProps = options?.props;
+	const directive = `client:${strategy}`;
+	return defineComponent({
+		name: "ClientIsland",
+		inheritAttrs: false,
+		setup(_, { slots, attrs }) {
+			const mergedProps = {
+				...staticProps,
+				...attrs
+			};
+			return () => h("ubean-island", {
+				"data-island-id": `island-runtime-${strategy}`,
+				"data-component": Component?.name ?? "AnonymousIsland",
+				"data-directive": directive,
+				...mediaQuery ? { "data-media": mediaQuery } : {},
+				"data-props": escapeIslandProps(mergedProps)
+			}, strategy === "only" ? void 0 : h(Component, mergedProps, slots));
+		}
+	});
+}
+/** 序列化 props 为 data-props 属性值(与 vite.ts escapeAttr 等价)。 */
+function escapeIslandProps(props) {
+	return JSON.stringify(props).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+/**
+* `.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。
+*/
+const ServerComponentStub = defineComponent({
+	name: "ServerComponentStub",
+	setup() {
+		return () => h("ubean-server-only", { "data-server-only": "" });
+	}
+});
+/**
+* `.client.vue` 组件在 SSR 构建中的通用占位符 (Task 9.2)。
+*
+* Vite 插件在 SSR 构建中将 `.client.vue` 的 import 重定向到虚拟模块,
+* 该模块导出此组件。组件渲染 `<div data-client-only></div>` 占位符,
+* 与客户端 `defineClientComponent` 初始渲染输出一致,确保水合无 mismatch。
+*
+* SSR 使用通用占位符(而非真实组件)避免了在服务端导入可能含浏览器 API
+* 的 `.client.vue` 组件代码。
+*/
+const ClientComponentPlaceholder = defineComponent({
+	name: "ClientComponentPlaceholder",
+	setup() {
+		return () => h("div", { "data-client-only": "" });
+	}
+});
+/**
+* 定义客户端组件 —— `.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);
+* ```
+*/
+function defineClientComponent(component) {
+	return defineComponent({
+		name: "ClientComponent",
+		inheritAttrs: false,
+		setup(_, { slots, attrs }) {
+			const isClient = ref(false);
+			onMounted(() => {
+				isClient.value = true;
+			});
+			return () => isClient.value ? h(component, attrs, slots) : h("div", { "data-client-only": "" });
+		}
+	});
+}
+/**
+* 定义配对组件 — `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);
+* ```
+*/
+function definePairedComponent(ServerComp, ClientComp) {
+	return defineComponent({
+		name: "PairedComponent",
+		inheritAttrs: false,
+		setup(_, { slots, attrs }) {
+			const isClient = ref(false);
+			onMounted(() => {
+				isClient.value = true;
+			});
+			return () => isClient.value ? h(ClientComp, attrs, slots) : h(ServerComp, attrs, slots);
+		}
+	});
+}
 //#endregion
-export { collectIslands, hydrateIsland, hydrateIslands };
+export { ClientComponentPlaceholder, SERVER_COMPONENT_ENDPOINT, ServerComponentStub, _clearServerComponentRegistry, collectIslands, defineClientComponent, defineIsland, definePairedComponent, defineServerIsland, getServerComponent, hydrateIsland, hydrateIslands, registerServerComponent };

package/dist/server-component.d.ts

@@ -0,0 +1,39 @@
+import { SERVER_COMPONENT_ENDPOINT } from "./runtime.js";
+import { MiddlewareHandler } from "hono";
+import { UbeanEnv } from "@ubean/shared";
+//#region src/server-component.d.ts
+/**
+ * 响应头:标识来自 server-component 中间件的响应。
+ */
+declare const SERVER_COMPONENT_RESPONSE_HEADER = "x-ubean-server-component";
+/**
+ * 创建 server-component 中间件 — 处理 `POST /__server-component` 请求。
+ *
+ * 用法 (通常由 `createUbeanApp()` 自动挂载,用户无需手动调用):
+ *
+ * ```ts
+ * import { createUbeanApp } from 'ubean/runtime/app';
+ * import { createServerComponentMiddleware, SERVER_COMPONENT_ENDPOINT } from '@ubean/islands/server';
+ *
+ * const app = createUbeanApp();
+ * app.on('POST', SERVER_COMPONENT_ENDPOINT, createServerComponentMiddleware());
+ * ```
+ */
+declare function createServerComponentMiddleware(): MiddlewareHandler<UbeanEnv>;
+/**
+ * 检查请求是否指向 server-component 端点。
+ *
+ * 供路由注册器跳过将该路径注册为普通 API 路由。
+ */
+declare function isServerComponentRequest(c: {
+  req: {
+    path: string;
+    method: string;
+  };
+}): boolean;
+/**
+ * 检查响应是否来自 server-component 中间件。
+ */
+declare function isServerComponentResponse(response: Response): boolean;
+//#endregion
+export { SERVER_COMPONENT_ENDPOINT, SERVER_COMPONENT_RESPONSE_HEADER, createServerComponentMiddleware, isServerComponentRequest, isServerComponentResponse };

package/dist/server-component.js

@@ -0,0 +1,70 @@
+import { SERVER_COMPONENT_ENDPOINT, getServerComponent } from "./runtime.js";
+import { h } from "vue";
+import { renderToString } from "vue/server-renderer";
+//#region src/server-component.ts
+/**
+* 响应头:标识来自 server-component 中间件的响应。
+*/
+const SERVER_COMPONENT_RESPONSE_HEADER = "x-ubean-server-component";
+/**
+* 创建 server-component 中间件 — 处理 `POST /__server-component` 请求。
+*
+* 用法 (通常由 `createUbeanApp()` 自动挂载,用户无需手动调用):
+*
+* ```ts
+* import { createUbeanApp } from 'ubean/runtime/app';
+* import { createServerComponentMiddleware, SERVER_COMPONENT_ENDPOINT } from '@ubean/islands/server';
+*
+* const app = createUbeanApp();
+* app.on('POST', SERVER_COMPONENT_ENDPOINT, createServerComponentMiddleware());
+* ```
+*/
+function createServerComponentMiddleware() {
+	return async (c) => {
+		if (!(c.req.header("Content-Type") || "").includes("application/json")) return _htmlError(c, "Content-Type must be application/json", 400);
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return _htmlError(c, "Malformed JSON body", 400);
+		}
+		const path = body?.path;
+		if (!path) return _htmlError(c, "Missing \"path\" field", 400);
+		const Component = getServerComponent(path);
+		if (!Component) return _htmlError(c, `Component not registered for path: ${path}`, 404);
+		const props = body?.props ?? {};
+		try {
+			const html = await renderToString(h(Component, props));
+			return c.body(html, 200, {
+				"Content-Type": "text/html; charset=utf-8",
+				"Cache-Control": "no-store",
+				[SERVER_COMPONENT_RESPONSE_HEADER]: "true"
+			});
+		} catch (err) {
+			return _htmlError(c, `Render failed: ${err instanceof Error ? err.message : String(err)}`, 500);
+		}
+	};
+}
+/**
+* 检查请求是否指向 server-component 端点。
+*
+* 供路由注册器跳过将该路径注册为普通 API 路由。
+*/
+function isServerComponentRequest(c) {
+	return c.req.method === "POST" && c.req.path === "/__server-component";
+}
+/**
+* 检查响应是否来自 server-component 中间件。
+*/
+function isServerComponentResponse(response) {
+	return response.headers.get(SERVER_COMPONENT_RESPONSE_HEADER) === "true";
+}
+function _htmlError(c, message, status) {
+	return c.body(message, status, {
+		"Content-Type": "text/plain; charset=utf-8",
+		"Cache-Control": "no-store",
+		[SERVER_COMPONENT_RESPONSE_HEADER]: "true"
+	});
+}
+//#endregion
+export { SERVER_COMPONENT_ENDPOINT, SERVER_COMPONENT_RESPONSE_HEADER, createServerComponentMiddleware, isServerComponentRequest, isServerComponentResponse };

package/dist/virtual-registry.d.ts

@@ -2,7 +2,7 @@
  * `virtual:ubean-islands-registry` 的 TypeScript 类型声明。
  *
  * 此虚拟模块由 `ubeanIslandsPlugin` 在构建/开发期生成,导出扫描到的 island 组件注册表。
- * 详见 `docs/islands-auto-registry.md`（方案 C）。
+ * 自动注册机制详见站点指南 [Islands](/guide/islands)（Automatic Hydration 一节）。
  *
  * 用户项目通常无需手动引用此声明 —— 只要 `tsconfig.json` 的 `include` 涵盖了
  * `node_modules/@ubean/islands/dist/**`,TypeScript 会自动发现此 ambient 声明。

package/dist/vite.d.ts

@@ -1,6 +1,33 @@
 import { Plugin } from "vite";
 //#region src/vite.d.ts
-type ClientDirective = 'client:load' | 'client:idle' | 'client:visible' | 'client:media' | 'client:only';
+/**
+ * 判断 id 是否为 `.server.vue` 文件 (Task 9.1)。
+ *
+ * 仅检查路径部分(忽略 `?query`),避免 `?vue&type=template` 子查询误匹配。
+ */
+declare function isServerComponentFile(id: string): boolean;
+/**
+ * 判断 id 是否为 `.client.vue` 文件 (Task 9.2)。
+ *
+ * 仅检查路径部分(忽略 `?query`)。注意:从虚拟包装模块内部对真实文件的
+ * import 不会被此函数拦截(由 `resolveId` 中的 importer 检查排除)。
+ */
+declare function isClientComponentFile(id: string): boolean;
+/** `.server.vue` 在 client 构建中的通用虚拟 stub 模块 ID */
+declare const SERVER_COMPONENT_STUB_VIRTUAL_ID = "virtual:ubean-server-component-stub";
+/** `.client.vue` 在 SSR 构建中的通用占位符虚拟模块 ID */
+declare const CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID = "virtual:ubean-client-component-placeholder";
+/**
+ * 将 `.server.vue` SFC 的 `<template>` 内容包裹在 `<ubean-server-only v-once>` 中。
+ *
+ * SSR 渲染输出 `<ubean-server-only v-once>真实内容</ubean-server-only>`,
+ * 客户端 stub 渲染 `<ubean-server-only></ubean-server-only>` (无子节点)。
+ * `v-once` 标记内容为静态,Vue 水合时保留 SSR HTML 不清除。
+ *
+ * 仅在 SSR 上下文运行(client 构建中 `.server.vue` 被 `resolveId` 重定向到 stub,
+ * 真实文件不会被加载/转换)。
+ */
+declare function wrapServerComponentTemplate(code: string): string | null;
 /**
  * 一个 island 组件的注册条目。
  *
@@ -31,13 +58,43 @@ type IslandComponentMap = Map<string, IslandComponentEntry>;
  */
 declare function parseScriptImports(scriptContent: string): Map<string, string>;
 /**
- * 扫描模板内容，返回所有带 `client:xxx` 指令的组件标签名集合。
+ * Task 9.4: 扫描代码中的 `defineServerIsland(Identifier, { ... rerenderOnPropsChange: true ... })`
+ * 调用,解析 `Identifier` 的 import 路径,将其作为第 3 个参数注入:
+ *
+ * ```ts
+ * defineServerIsland(Comp, { rerenderOnPropsChange: true }, "/abs/path.server.vue")
+ * ```
+ *
+ * ## 工作机制
+ *
+ * 1. 提取 `<script>` 块内容(`.vue` 文件)或整个代码(`.ts` 文件)
+ * 2. 查找所有 `defineServerIsland(...)` 调用,跳过注释/字符串/函数声明
+ * 3. 对每个调用:
+ *    - 参数 < 2 → 跳过(至少需要 Component + options)
+ *    - 参数 ≥ 3 → 跳过(已有路径,幂等)
+ *    - options 对象不含 `rerenderOnPropsChange: true` → 跳过(非 props 重渲染场景)
+ *    - 通过 `parseScriptImports` 解析 identifier 的 import 路径,相对路径解析为绝对路径
+ *    - 在 `)` 前注入 `, "/abs/path"`
+ *
+ * ## 幂等性
+ *
+ * 已注入的调用(参数 ≥ 3)不会被再次处理。
+ *
+ * @param code 完整源码(`.vue` SFC 或 `.ts` 文件)
+ * @param sourceFile 源文件绝对路径(用于解析相对 import)
+ * @returns 修改后的源码,或 `null` 表示无修改
+ */
+declare function injectServerComponentPath(code: string, sourceFile: string): string | null;
+/**
+ * 扫描模板内容，返回所有带 `v-client.*` 指令的组件标签名集合。
  *
  * 复用 `findTagAt` 的标签解析逻辑，确保与 `transformTemplate` 的识别规则一致
  * （仅匹配首字母大写的组件标签）。
  *
  * 与 `transformTemplate` 对称：非 island 标签会递归扫描其 innerHTML，
  * island 标签不递归（其子内容属于该 island 的 SSR 输出，不作为独立 island）。
+ *
+ * Phase 4: 仅识别 `v-client.*`(旧的 `client:*` 语法已移除)。
  */
 declare function scanIslandDirectiveNames(template: string): Set<string>;
 /**
@@ -50,7 +107,7 @@ declare function resolveIslandImportPath(importPath: string, sourceFile: string)
  * 步骤：
  * 1. 提取 `<script setup>` / `<script>` 内容
  * 2. 解析 import 语句，建立 { 局部名 → import 路径 } 映射
- * 3. 扫描模板中的 `<Comp client:xxx />` 指令，得到组件名集合
+ * 3. 扫描模板中的 `<Comp v-client.* />` 指令，得到组件名集合
  * 4. 交集：既在 import 映射中、又在 island 指令集合中的组件
  * 5. 将相对 import 路径解析为绝对路径
  *
@@ -86,4 +143,4 @@ interface UbeanIslandsPluginOptions {
 declare const ISLANDS_REGISTRY_VIRTUAL_ID = "virtual:ubean-islands-registry";
 declare function ubeanIslandsPlugin(_options?: UbeanIslandsPluginOptions): Plugin;
 //#endregion
-export { ClientDirective, ISLANDS_REGISTRY_VIRTUAL_ID, IslandComponentEntry, IslandComponentMap, UbeanIslandsPluginOptions, collectIslandComponents, generateRegistryModule, parseScriptImports, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin };
+export { CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID, ISLANDS_REGISTRY_VIRTUAL_ID, IslandComponentEntry, IslandComponentMap, SERVER_COMPONENT_STUB_VIRTUAL_ID, UbeanIslandsPluginOptions, collectIslandComponents, generateRegistryModule, injectServerComponentPath, isClientComponentFile, isServerComponentFile, parseScriptImports, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin, wrapServerComponentTemplate };