@ubean/islands 0.1.13 → 0.2.0

package/dist/vite.js

@@ -1,17 +1,89 @@
+import { legacyDirectiveToStrategy, strategyToLegacyDirective } from "./directive.js";
+import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 //#region src/vite.ts
-const CLIENT_DIRECTIVES = [
-	"client:load",
-	"client:idle",
-	"client:visible",
-	"client:media",
-	"client:only"
+/**
+* `v-client.*` 指令属性名(Phase 4: 唯一支持的客户端 island 语法)。
+*
+* 旧的 `client:*` attribute 语法已移除 — 请迁移至 `v-client.*`,
+* 或使用运行时 `defineIsland()` 包装组件。
+*/
+const V_CLIENT_DIRECTIVES = [
+	"v-client.load",
+	"v-client.idle",
+	"v-client.visible",
+	"v-client.media",
+	"v-client.only"
 ];
-const DIRECTIVE_RE = /\bclient:(load|idle|visible|media|only)\b/;
+/**
+* Matches `v-client.*` (用于客户端 island 检测)。
+*
+* Phase 4 起 `client:*` legacy 语法不再支持,正则只匹配 `v-client.*`。
+*/
+const ANY_CLIENT_DIRECTIVE_RE = /\bv-client\.(?:load|idle|visible|media|only)\b/;
+/** Matches `v-client.*` (用于快速跳过非 island SFC) */
+const ANY_DIRECTIVE_RE = /\bv-client\.(?:load|idle|visible|media|only)\b/;
 function isVueSfc(id) {
 	return /\.vue(?:\?.*)?$/.test(id) && !id.includes("&type=");
 }
 /**
+* 判断 id 是否为 `.server.vue` 文件 (Task 9.1)。
+*
+* 仅检查路径部分(忽略 `?query`),避免 `?vue&type=template` 子查询误匹配。
+*/
+function isServerComponentFile(id) {
+	return id.split("?")[0].endsWith(".server.vue");
+}
+/**
+* 判断 id 是否为 `.client.vue` 文件 (Task 9.2)。
+*
+* 仅检查路径部分(忽略 `?query`)。注意:从虚拟包装模块内部对真实文件的
+* import 不会被此函数拦截(由 `resolveId` 中的 importer 检查排除)。
+*/
+function isClientComponentFile(id) {
+	return id.split("?")[0].endsWith(".client.vue");
+}
+/** `.server.vue` 在 client 构建中的通用虚拟 stub 模块 ID */
+const SERVER_COMPONENT_STUB_VIRTUAL_ID = "virtual:ubean-server-component-stub";
+const SERVER_COMPONENT_STUB_RESOLVED_ID = `\0${SERVER_COMPONENT_STUB_VIRTUAL_ID}`;
+/** `.client.vue` 在 SSR 构建中的通用占位符虚拟模块 ID */
+const CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID = "virtual:ubean-client-component-placeholder";
+const CLIENT_COMPONENT_PLACEHOLDER_RESOLVED_ID = `\0${CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID}`;
+/** `.client.vue` 在 client 构建中文件级包装虚拟模块 ID 前缀 */
+const CLIENT_COMPONENT_WRAPPER_PREFIX = "\0virtual:ubean-client-component:";
+/**
+* Task 9.3: 配对组件 (`Foo.vue` 同时存在 `.server.vue` + `.client.vue`) 在
+* SSR / client 构建中生成的虚拟包装模块 ID 前缀。
+*
+* 后缀格式: `${serverPath}|${clientPath}` (两个绝对路径用 `|` 分隔)。
+*
+* - SSR `load`: 仅 `import ServerComp from serverPath; export default ServerComp;`
+*   (导入真实 `.server.vue`,经现有规则解析为真实文件 + 模板包裹)
+* - client `load`: 同时导入 `.server.vue` (→ stub) 与 `.client.vue` (→ 真实文件,
+*   通过 importer 检查跳过 `defineClientComponent` 包装),调用 `definePairedComponent`
+*   实现初始渲染 ServerComp(stub) → onMounted 后切换为 ClientComp。
+*/
+const PAIRED_COMPONENT_WRAPPER_PREFIX = "\0virtual:ubean-paired-component:";
+/** `|` 在文件路径中几乎不会出现,用作 `serverPath` 与 `clientPath` 的分隔符。 */
+const PAIRED_PATH_SEPARATOR = "|";
+/**
+* 将 `.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,
+* 真实文件不会被加载/转换)。
+*/
+function wrapServerComponentTemplate(code) {
+	const tpl = extractTemplateBlock(code);
+	if (!tpl) return null;
+	if (tpl.content.trim().startsWith("<ubean-server-only")) return null;
+	const newContent = `<ubean-server-only v-once>${tpl.content}</ubean-server-only>`;
+	return `${code.slice(0, tpl.start)}<template${tpl.attrs}>${newContent}</template>${code.slice(tpl.end)}`;
+}
+/**
 * 判断 id 是否为 SFC 主模块（非 `?vue&type=...` 子查询）。
 *
 * 收集 island 组件时需要同时访问 `<script setup>` 与 `<template>` 块，
@@ -56,14 +128,358 @@ function parseScriptImports(scriptContent) {
 	}
 	return map;
 }
+const DEFINE_SERVER_ISLAND_RE = /\bdefineServerIsland\s*\(/g;
+/**
+* 预扫描代码,返回所有"非代码"区间 `[start, end)`:注释(块/行)和字符串字面量。
+*
+* 用于跳过注释/字符串内的 `defineServerIsland(` 匹配(如 JSDoc 示例或说明性字符串)。
+* 复用 `@ubean/actions` Vite 插件的成熟模式 (见 lessons #P-lessons)。
+*/
+function findNonCodeRanges(code) {
+	const ranges = [];
+	const len = code.length;
+	let i = 0;
+	while (i < len) {
+		if (code[i] === "/" && code[i + 1] === "*") {
+			const start = i;
+			i += 2;
+			while (i < len && !(code[i] === "*" && code[i + 1] === "/")) i++;
+			i += 2;
+			ranges.push([start, Math.min(i, len)]);
+			continue;
+		}
+		if (code[i] === "/" && code[i + 1] === "/") {
+			const start = i;
+			i += 2;
+			while (i < len && code[i] !== "\n") i++;
+			ranges.push([start, i]);
+			continue;
+		}
+		if (code[i] === "\"" || code[i] === "'" || code[i] === "`") {
+			const start = i;
+			const quote = code[i];
+			i++;
+			while (i < len) {
+				if (code[i] === "\\") {
+					i += 2;
+					continue;
+				}
+				if (quote === "`" && code[i] === "$" && code[i + 1] === "{") {
+					i += 2;
+					let depth = 1;
+					while (i < len && depth > 0) {
+						if (code[i] === "{") depth++;
+						else if (code[i] === "}") depth--;
+						i++;
+					}
+					continue;
+				}
+				if (code[i] === quote) {
+					i++;
+					break;
+				}
+				i++;
+			}
+			ranges.push([start, i]);
+			continue;
+		}
+		i++;
+	}
+	return ranges;
+}
+function isInsideRanges(pos, ranges) {
+	for (const [start, end] of ranges) if (pos >= start && pos < end) return true;
+	return false;
+}
+/**
+* 从 `startIdx` 开始查找匹配的闭合括号(支持字符串/模板字面量/注释跳过)。
+* `startIdx` 应指向 `(` 后的第一个字符。返回 `)` 的索引,或 `null`。
+*/
+function findBalanced(code, openChar, closeChar, startIdx) {
+	let depth = 1;
+	let i = startIdx;
+	let inString = null;
+	let escaped = false;
+	let inTemplateExpr = 0;
+	while (i < code.length && depth > 0) {
+		const ch = code[i];
+		if (escaped) {
+			escaped = false;
+			i++;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			i++;
+			continue;
+		}
+		if (inString) {
+			if (inString === "`" && ch === "$" && code[i + 1] === "{") {
+				inTemplateExpr++;
+				i += 2;
+				continue;
+			}
+			if (inString === "`" && ch === "}" && inTemplateExpr > 0) {
+				inTemplateExpr--;
+				i++;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			i++;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			i++;
+			continue;
+		}
+		if (ch === "/" && code[i + 1] === "/") {
+			while (i < code.length && code[i] !== "\n") i++;
+			continue;
+		}
+		if (ch === "/" && code[i + 1] === "*") {
+			i += 2;
+			while (i < code.length && !(code[i] === "*" && code[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		if (ch === openChar) depth++;
+		else if (ch === closeChar) {
+			depth--;
+			if (depth === 0) return i;
+		}
+		i++;
+	}
+	return null;
+}
+/**
+* 在 `[argStart, end)` 区间内查找顶层逗号(深度 0)位置数组。
+*/
+function findTopLevelCommas(code, argStart, end) {
+	const commas = [];
+	let depth = 0;
+	let i = argStart;
+	let inString = null;
+	let escaped = false;
+	let inTemplateExpr = 0;
+	while (i < end) {
+		const ch = code[i];
+		if (escaped) {
+			escaped = false;
+			i++;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			i++;
+			continue;
+		}
+		if (inString) {
+			if (inString === "`" && ch === "$" && code[i + 1] === "{") {
+				inTemplateExpr++;
+				i += 2;
+				continue;
+			}
+			if (inString === "`" && ch === "}" && inTemplateExpr > 0) {
+				inTemplateExpr--;
+				i++;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			i++;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			i++;
+			continue;
+		}
+		if (ch === "/" && code[i + 1] === "/") {
+			while (i < end && code[i] !== "\n") i++;
+			continue;
+		}
+		if (ch === "/" && code[i + 1] === "*") {
+			i += 2;
+			while (i < end && !(code[i] === "*" && code[i + 1] === "/")) i++;
+			i += 2;
+			continue;
+		}
+		if (ch === "(" || ch === "[" || ch === "{") depth++;
+		else if (ch === ")" || ch === "]" || ch === "}") depth--;
+		else if (ch === "," && depth === 0) commas.push(i);
+		i++;
+	}
+	return commas;
+}
+/**
+* 提取源码中所有 `defineServerIsland(...)` 调用信息。
+*
+* 跳过注释/字符串内的匹配(如 JSDoc 示例)和函数声明(`function defineServerIsland(`)。
+*/
+function findDefineServerIslandCalls(code) {
+	const results = [];
+	const nonCodeRanges = findNonCodeRanges(code);
+	let m;
+	DEFINE_SERVER_ISLAND_RE.lastIndex = 0;
+	while ((m = DEFINE_SERVER_ISLAND_RE.exec(code)) !== null) {
+		const start = m.index;
+		if (isInsideRanges(start, nonCodeRanges)) continue;
+		const before = code.slice(0, start);
+		if (/\bfunction\s+$/.test(before)) continue;
+		const argStart = start + m[0].length;
+		const end = findBalanced(code, "(", ")", argStart);
+		if (end === null) continue;
+		const commas = findTopLevelCommas(code, argStart, end);
+		const argRanges = [];
+		let prev = argStart;
+		for (const comma of commas) {
+			argRanges.push([prev, comma]);
+			prev = comma + 1;
+		}
+		argRanges.push([prev, end]);
+		const args = argRanges.map(([s, e]) => code.slice(s, e).trim());
+		results.push({
+			start,
+			argStart,
+			end,
+			args
+		});
+	}
+	return results;
+}
+/**
+* 提取 SFC 中 `<script setup>` 或 `<script>` 块的内容及其位置区间。
+*
+* 返回 `{ content, contentStart, contentEnd }` 或 `null`。`contentStart`/`contentEnd`
+* 是内容在原 code 中的起止位置(不含开闭标签)。
+*/
+function extractScriptBlockWithPositions(code) {
+	const setupMatch = code.match(/<script\s+[^>]*setup[^>]*>/);
+	if (setupMatch && setupMatch.index !== void 0) {
+		const openTagEnd = setupMatch.index + setupMatch[0].length;
+		const closeIdx = code.indexOf("<\/script>", openTagEnd);
+		if (closeIdx !== -1) return {
+			content: code.slice(openTagEnd, closeIdx),
+			contentStart: openTagEnd,
+			contentEnd: closeIdx
+		};
+	}
+	const plainMatch = code.match(/<script(?!\s[^>]*setup)[^>]*>/);
+	if (plainMatch && plainMatch.index !== void 0) {
+		const openTagEnd = plainMatch.index + plainMatch[0].length;
+		const closeIdx = code.indexOf("<\/script>", openTagEnd);
+		if (closeIdx !== -1) return {
+			content: code.slice(openTagEnd, closeIdx),
+			contentStart: openTagEnd,
+			contentEnd: closeIdx
+		};
+	}
+	return null;
+}
+/**
+* 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` 表示无修改
+*/
+function injectServerComponentPath(code, sourceFile) {
+	if (sourceFile.endsWith(".vue")) {
+		const scriptBlock = extractScriptBlockWithPositions(code);
+		if (!scriptBlock) return null;
+		const newContent = _doInject(scriptBlock.content, sourceFile);
+		if (newContent === null) return null;
+		return code.slice(0, scriptBlock.contentStart) + newContent + code.slice(scriptBlock.contentEnd);
+	}
+	return _doInject(code, sourceFile);
+}
+function _doInject(scriptContent, sourceFile) {
+	const calls = findDefineServerIslandCalls(scriptContent);
+	if (calls.length === 0) return null;
+	const importMap = parseScriptImports(scriptContent);
+	let result = scriptContent;
+	let changed = false;
+	for (let i = calls.length - 1; i >= 0; i--) {
+		const call = calls[i];
+		if (call.args.length < 2) continue;
+		if (call.args.length >= 3) continue;
+		const optionsText = call.args[1];
+		if (!optionsText.startsWith("{")) continue;
+		if (!/\brerenderOnPropsChange\s*:\s*true\b/.test(optionsText)) continue;
+		const identifier = call.args[0].trim();
+		const importPath = importMap.get(identifier);
+		if (!importPath) continue;
+		const absolutePath = resolveIslandImportPath(importPath, sourceFile);
+		const insertPos = call.end;
+		const insertText = `, ${JSON.stringify(absolutePath)}`;
+		result = result.slice(0, insertPos) + insertText + result.slice(insertPos);
+		changed = true;
+	}
+	return changed ? result : null;
+}
+/**
+* Find the `v-client.*` directive on a tag.
+*
+* Returns the legacy directive name (e.g. `'client:load'`) for internal
+* consistency with `<ubean-island data-directive="...">` format consumed by
+* `hydrateIslands()`, or `null` if no client directive is present.
+*
+* Also returns the media query value for `v-client.media`.
+*
+* Phase 4: 旧的 `client:*` attribute 语法已移除,仅识别 `v-client.*`。
+*/
+function findClientDirectiveOnTag(attrs) {
+	for (const vcd of V_CLIENT_DIRECTIVES) if (attrs.has(vcd)) {
+		const strategy = legacyDirectiveToStrategy(vcd) || "load";
+		return {
+			directive: strategyToLegacyDirective(strategy),
+			mediaQuery: strategy === "media" ? extractMediaQuery(attrs.get(vcd)) : void 0
+		};
+	}
+	return null;
+}
+/**
+* Extract a media query string from a directive value.
+*
+* For `v-client.media="'(max-width: 768px)'"` the value is a Vue expression
+* (string literal), so we strip surrounding quotes.
+*/
+function extractMediaQuery(raw) {
+	if (raw === void 0 || raw === true) return void 0;
+	let value = String(raw).trim();
+	if (value.startsWith("'") && value.endsWith("'") || value.startsWith("\"") && value.endsWith("\"")) value = value.slice(1, -1);
+	return value || void 0;
+}
 /**
-* 扫描模板内容，返回所有带 `client:xxx` 指令的组件标签名集合。
+* 扫描模板内容，返回所有带 `v-client.*` 指令的组件标签名集合。
 *
 * 复用 `findTagAt` 的标签解析逻辑，确保与 `transformTemplate` 的识别规则一致
 * （仅匹配首字母大写的组件标签）。
 *
 * 与 `transformTemplate` 对称：非 island 标签会递归扫描其 innerHTML，
 * island 标签不递归（其子内容属于该 island 的 SSR 输出，不作为独立 island）。
+*
+* Phase 4: 仅识别 `v-client.*`(旧的 `client:*` 语法已移除)。
 */
 function scanIslandDirectiveNames(template) {
 	const names = /* @__PURE__ */ new Set();
@@ -83,7 +499,7 @@ function scanIslandDirectiveNames(template) {
 				pos = lt + 1;
 				continue;
 			}
-			if (CLIENT_DIRECTIVES.some((d) => tag.attrs.has(d))) names.add(tag.tagName);
+			if (findClientDirectiveOnTag(tag.attrs) !== null) names.add(tag.tagName);
 			if (!tag.selfClosing) scan(tag.innerHTML);
 			pos = tag.end;
 		}
@@ -102,7 +518,7 @@ function resolveIslandImportPath(importPath, sourceFile) {
 * 步骤：
 * 1. 提取 `<script setup>` / `<script>` 内容
 * 2. 解析 import 语句，建立 { 局部名 → import 路径 } 映射
-* 3. 扫描模板中的 `<Comp client:xxx />` 指令，得到组件名集合
+* 3. 扫描模板中的 `<Comp v-client.* />` 指令，得到组件名集合
 * 4. 交集：既在 import 映射中、又在 island 指令集合中的组件
 * 5. 将相对 import 路径解析为绝对路径
 *
@@ -113,14 +529,14 @@ function collectIslandComponents(code, sourceFile) {
 	const scriptContent = extractScriptBlock(code);
 	const templateContent = extractTemplateBlock(code)?.content ?? "";
 	if (!templateContent) return [];
-	if (!DIRECTIVE_RE.test(templateContent)) return [];
+	if (!ANY_CLIENT_DIRECTIVE_RE.test(templateContent)) return [];
 	const importMap = parseScriptImports(scriptContent);
 	const islandNames = scanIslandDirectiveNames(templateContent);
 	const entries = [];
 	for (const name of islandNames) {
 		const importPath = importMap.get(name);
 		if (!importPath) {
-			console.warn(`[ubean:islands] Component "${name}" used with client:xxx directive in ${sourceFile} has no corresponding static import in <script setup>. It will not be auto-registered. Add it manually via hydrateIslands({ components: { ${name}: YourComp } }) or pass a getComponent() resolver.`);
+			console.warn(`[ubean:islands] Component "${name}" used with v-client.* directive in ${sourceFile} has no corresponding static import in <script setup>. It will not be auto-registered. Add it manually via hydrateIslands({ components: { ${name}: YourComp } }) or pass a getComponent() resolver.`);
 			continue;
 		}
 		const absolutePath = resolveIslandImportPath(importPath, sourceFile);
@@ -187,11 +603,42 @@ function generateRegistryModule(components) {
 		"};"
 	].join("\n");
 }
+/**
+* 提取 SFC 中顶层的 `<template>` 块。
+*
+* 处理嵌套 `<template>` 标签:Vue SFC 的 `<template>` 块内部可能包含
+* `<template #slot>` 等嵌套 template 标签(如作用域插槽、`v-if`/`v-for`
+* 包装)。简单 `indexOf('</template>')` 会错误匹配到嵌套关闭标签,因此用
+* 深度计数找到匹配的顶层关闭标签。
+*
+* 仅匹配小写 `<template`(SFC 块标签),不会误匹配 `<Template>` 组件。
+*/
 function extractTemplateBlock(code) {
 	const openMatch = code.match(/<template([^>]*)>/);
 	if (!openMatch) return null;
 	const openTagEnd = openMatch.index + openMatch[0].length;
-	const closeIdx = code.indexOf("</template>", openTagEnd);
+	const openRe = /<template[\s>]/g;
+	const closeRe = /<\/template>/g;
+	openRe.lastIndex = openTagEnd;
+	closeRe.lastIndex = openTagEnd;
+	let depth = 1;
+	let closeIdx = -1;
+	while (depth > 0) {
+		const nextOpen = openRe.exec(code);
+		const nextClose = closeRe.exec(code);
+		if (!nextClose) return null;
+		if (nextOpen && nextOpen.index < nextClose.index) {
+			depth++;
+			closeRe.lastIndex = nextOpen.index + nextOpen[0].length;
+		} else {
+			depth--;
+			if (depth === 0) {
+				closeIdx = nextClose.index;
+				break;
+			}
+			openRe.lastIndex = nextClose.index + nextClose[0].length;
+		}
+	}
 	if (closeIdx === -1) return null;
 	return {
 		start: openMatch.index,
@@ -285,7 +732,7 @@ function parseAttrs(str) {
 function collectStaticProps(attrs) {
 	const props = {};
 	for (const [key, val] of attrs) {
-		if (key.startsWith("client:")) continue;
+		if (key.startsWith("v-client.")) continue;
 		if (key.startsWith("v-") || key.startsWith("@") || key.startsWith(":")) continue;
 		if (key === "key" || key === "ref") continue;
 		if (val === true) props[key] = true;
@@ -324,8 +771,8 @@ function transformTemplate(template, islandCounter, filePath) {
 			pos = lt + 1;
 			continue;
 		}
-		const directive = CLIENT_DIRECTIVES.find((d) => tag.attrs.has(d));
-		if (!directive) {
+		const clientDirectiveInfo = findClientDirectiveOnTag(tag.attrs);
+		if (!clientDirectiveInfo) {
 			const inner = tag.selfClosing ? "" : transformTemplate(tag.innerHTML, islandCounter, filePath);
 			out += tag.fullOpenTag;
 			out += inner;
@@ -333,11 +780,11 @@ function transformTemplate(template, islandCounter, filePath) {
 			pos = tag.end;
 			continue;
 		}
+		const { directive, mediaQuery } = clientDirectiveInfo;
 		islandCounter.count++;
 		const islandId = `island-${filePath.replace(/[^a-zA-Z0-9]/g, "-")}-${islandCounter.count}`;
-		const mediaRaw = tag.attrs.get("client:media");
 		let mediaStr = "";
-		if (directive === "client:media" && mediaRaw && mediaRaw !== true) mediaStr = ` data-media="${escapeAttr(String(mediaRaw).replace(/^["']|["']$/g, ""))}"`;
+		if (directive === "client:media" && mediaQuery) mediaStr = ` data-media="${escapeAttr(mediaQuery)}"`;
 		const props = collectStaticProps(tag.attrs);
 		const propsJson = escapeAttr(JSON.stringify(props));
 		out += `<ubean-island v-once data-island-id="${islandId}" data-component="${tag.tagName}" data-directive="${directive}" data-props="${propsJson}"${mediaStr}>`;
@@ -353,7 +800,7 @@ function transformVueSfcIslands(code, filePath) {
 		code,
 		islandCount: 0
 	};
-	if (!DIRECTIVE_RE.test(tpl.content)) return {
+	if (!ANY_DIRECTIVE_RE.test(tpl.content)) return {
 		code,
 		islandCount: 0
 	};
@@ -421,20 +868,74 @@ function ubeanIslandsPlugin(_options = {}) {
 		configureServer(server) {
 			devServer = server;
 		},
-		resolveId(id) {
+		async resolveId(id, importer, options) {
 			if (id === "virtual:ubean-islands-registry") return ISLANDS_REGISTRY_RESOLVED_ID;
+			if (!enabled) return void 0;
+			if (!options?.ssr && isServerComponentFile(id)) return SERVER_COMPONENT_STUB_RESOLVED_ID;
+			if (isClientComponentFile(id) && !importer?.startsWith(CLIENT_COMPONENT_WRAPPER_PREFIX) && !importer?.startsWith(PAIRED_COMPONENT_WRAPPER_PREFIX)) {
+				if (options?.ssr) return CLIENT_COMPONENT_PLACEHOLDER_RESOLVED_ID;
+				const resolved = await this.resolve(id, importer, { skipSelf: true });
+				if (!resolved) return void 0;
+				return `${CLIENT_COMPONENT_WRAPPER_PREFIX}${resolved.id}`;
+			}
+			if (importer && !importer.startsWith("\0") && id.endsWith(".vue") && !isServerComponentFile(id) && !isClientComponentFile(id) && id.startsWith(".")) {
+				const importerDir = dirname(resolve(importer));
+				const baseName = resolve(importerDir, id).slice(0, -4);
+				const serverSibling = `${baseName}.server.vue`;
+				const clientSibling = `${baseName}.client.vue`;
+				const hasServer = existsSync(serverSibling);
+				const hasClient = existsSync(clientSibling);
+				if (hasServer && hasClient) return `${PAIRED_COMPONENT_WRAPPER_PREFIX}${serverSibling}${PAIRED_PATH_SEPARATOR}${clientSibling}`;
+				if (hasServer) return serverSibling;
+				if (hasClient) return clientSibling;
+			}
 		},
-		load(id) {
-			if (id !== ISLANDS_REGISTRY_RESOLVED_ID) return void 0;
-			return generateRegistryModule(islandComponents);
+		load(id, options) {
+			if (id === ISLANDS_REGISTRY_RESOLVED_ID) return generateRegistryModule(islandComponents);
+			if (id === SERVER_COMPONENT_STUB_RESOLVED_ID) return `import { ServerComponentStub } from '@ubean/islands/runtime';\nexport default ServerComponentStub;`;
+			if (id === CLIENT_COMPONENT_PLACEHOLDER_RESOLVED_ID) return `import { ClientComponentPlaceholder } from '@ubean/islands/runtime';\nexport default ClientComponentPlaceholder;`;
+			if (id.startsWith(CLIENT_COMPONENT_WRAPPER_PREFIX)) {
+				const realPath = id.slice(32);
+				return `import RealComp from ${JSON.stringify(realPath)};\nimport { defineClientComponent } from '@ubean/islands/runtime';\nexport default defineClientComponent(RealComp);`;
+			}
+			if (id.startsWith(PAIRED_COMPONENT_WRAPPER_PREFIX)) {
+				const payload = id.slice(32);
+				const sepIdx = payload.indexOf(PAIRED_PATH_SEPARATOR);
+				if (sepIdx === -1) return void 0;
+				const serverPath = payload.slice(0, sepIdx);
+				const clientPath = payload.slice(sepIdx + 1);
+				if (options?.ssr) return `import ServerComp from ${JSON.stringify(serverPath)};\nexport default ServerComp;`;
+				return `import ServerComp from ${JSON.stringify(serverPath)};\nimport ClientComp from ${JSON.stringify(clientPath)};\nimport { definePairedComponent } from '@ubean/islands/runtime';\nexport default definePairedComponent(ServerComp, ClientComp);`;
+			}
 		},
 		transform(code, id) {
 			if (!enabled) return null;
-			if (!isVueSfc(id)) return null;
-			if (!DIRECTIVE_RE.test(code)) return null;
+			const normalizedId = id.split("?")[0];
+			const isVue = isVueSfc(id);
+			const isTs = normalizedId.endsWith(".ts") && !id.includes("?");
+			const originalCode = code;
+			if (isVue || isTs) {
+				const injected = injectServerComponentPath(code, normalizedId);
+				if (injected !== null) code = injected;
+			}
+			if (!isVue) return isTs && code !== originalCode ? { code } : null;
+			let serverWrapped = false;
+			if (isServerComponentFile(id)) {
+				const wrapped = wrapServerComponentTemplate(code);
+				if (wrapped !== null) {
+					code = wrapped;
+					serverWrapped = true;
+				}
+			}
+			if (!ANY_DIRECTIVE_RE.test(code) && !serverWrapped) return code !== originalCode ? { code } : null;
 			const absolutePath = id.split("?")[0];
-			const result = transformVueSfcIslands(code, absolutePath.replace(viteConfig.root, "").replace(/^[/\\]/, ""));
-			if (isMainVueSfc(id)) {
+			const filePath = absolutePath.replace(viteConfig.root, "").replace(/^[/\\]/, "");
+			let result = {
+				code,
+				islandCount: 0
+			};
+			if (ANY_DIRECTIVE_RE.test(code)) result = transformVueSfcIslands(code, filePath);
+			if (isMainVueSfc(id) && ANY_DIRECTIVE_RE.test(code)) {
 				const registryChanged = updateRegistry(collectIslandComponents(code, absolutePath), absolutePath);
 				const isHmrUpdate = transformedFiles.has(absolutePath);
 				transformedFiles.add(absolutePath);
@@ -451,4 +952,4 @@ function ubeanIslandsPlugin(_options = {}) {
 	};
 }
 //#endregion
-export { ISLANDS_REGISTRY_VIRTUAL_ID, collectIslandComponents, generateRegistryModule, parseScriptImports, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin };
+export { CLIENT_COMPONENT_PLACEHOLDER_VIRTUAL_ID, ISLANDS_REGISTRY_VIRTUAL_ID, SERVER_COMPONENT_STUB_VIRTUAL_ID, collectIslandComponents, generateRegistryModule, injectServerComponentPath, isClientComponentFile, isServerComponentFile, parseScriptImports, resolveIslandImportPath, scanIslandDirectiveNames, transformVueSfcIslands, ubeanIslandsPlugin, wrapServerComponentTemplate };